## What
Two small CI-script hygiene fixes from the v2.41.1→main audit (Wave 0,
PR-1 of the 3.0-alignment plan):
1. **`inventory-jsm-skills.sh`** — replace hardcoded `/Users/bo` macOS
paths with `$HOME`, so the inventory resolves skills on Linux/CI instead
of silently returning an empty result. (bead `agentops-yxid`)
2. **`add-validate-job.sh`** — quote `${HELPER_SCRIPT}` in the generated
workflow + pre-push bash so scaffolded jobs are shellcheck-clean. Uses
escaped quotes inside the double-quoted templates (the bare-quote first
attempt broke the template string — caught by shellcheck SC2027/SC1078).
(bead `agentops-obef`)
## Test plan
- `shellcheck --severity=error` clean on both files (CI parity)
- full `shellcheck` clean on both files
- `bash -n` syntax OK
- `add-validate-job.sh ... --dry-run` shows correctly quoted generated
output:
`chmod +x "scripts/..."`, `[[ -f "scripts/..." ]]`, `bash "scripts/..."`
- `scripts/pre-push-gate.sh --fast` passed
Closes-scenario: agentops-yxid#ci-portable-paths
Closes-scenario: agentops-obef#ci-genbash-quoting
Bounded-context: BC5-Runtime
Evidence: pre-push-gate --fast passed; shellcheck clean; dry-run quoted
output verified
🤖 Generated with [Claude Code](https://claude.com/claude-code)
## What
Adds `scripts/add-validate-job.sh` — atomically scaffolds a new
`validate-*` CI job across all 5 touch-points in one command.
## Why
Adding a new validate-* job currently requires hand-edits to **5+ files
in lockstep**:
| Surface | What needs editing |
|---|---|
| `.github/workflows/validate.yml` | new job block |
| `.github/workflows/validate.yml` | summary.needs list entry |
| `.github/workflows/validate.yml` | summary echo line |
| `scripts/pre-push-gate.sh` | new always-runs section |
| `tests/scripts/pre-push-gate.bats` | make_stub for helper script |
| `AGENTS.md` | CI Jobs table row |
Missing any one triggers cascading CI failures across multiple gates. I
hit this exact failure **twice this session** while shipping the
soc-zxia (registries-drift remediation) epic — missing AGENTS rows broke
`validate-ci-policy-parity`; missing bats stubs broke `bats-tests` +
`agentops-contract-canaries`.
This PR is the **meta-fix**: the same registries-drift pattern that
soc-zxia closed for the DDD docs layer, applied to the CI integration
layer.
## Usage
```bash
scripts/add-validate-job.sh validate-my-thing \
--script scripts/check-my-thing.sh \
--reason "What this validates (AGENTS table column)" \
--failure "Common failure mode (AGENTS table column)" \
[--python] # if the helper needs pip install pyyaml
[--dry-run] # show patches without applying
```
## Properties
- **Idempotent**: re-running with same args is a no-op (conflict
detection on job-name uniqueness)
- **Input validation**: job-name format (`validate-<kebab>`),
helper-script existence, all required surface files present, missing
required flags
- **Dry-run mode**: preview all 6 patches before applying
- **Single command**: no chance to miss a touch-point
## Anchors
The scaffolder inserts before known anchors in each surface:
| Surface | Insertion anchor |
|---|---|
| workflow job block | before `validate-flywheel-proof:` |
| summary.needs | before `validate-flywheel-proof,` |
| summary echo | before flywheel-proof echo line |
| pre-push gate | before `# --- 22d. Flywheel-proof` |
| bats stubs | after make_stub for `proof-run.sh` |
| AGENTS table | before validate-flywheel-proof row |
## Verification (dry-run)
Tested against a hypothetical `validate-example` job — scaffolder
produces correct, well-formed patches for all 6 touch-points. Wet-run
validates on the next real validate-* job addition.
## Acceptance
- [x] `scripts/add-validate-job.sh` exists, executable, has `--help`
- [x] Validates inputs (job name format, script existence, conflict
detection)
- [x] Dry-run shows correct patches for all 6 touch-points
- [x] Linked from `docs/documentation-index.md`
- [x] Lands via PR (dogfoods the discipline)
## Related
- Filed-from: soc-zxia (Domain-tightening epic that exposed this need)
- Closes: soc-3oij
- Companion follow-ups (future beads):
- soc-m6tp — generate AGENTS.md CI table from validate.yml (reduces from
6 surfaces to 5)
- soc-xban — auto-discover bats helper stubs (reduces from 5 to 4)
- soc-hwgm — fix TestRunInit* global state flake under -shuffle
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude <noreply@anthropic.com>
Bo