feat(v-onboard): add Operations/Deployment coverage dimension to /v:onboard

[khymerao]

What

Adds an explicit Operations / Deployment coverage dimension to the /v:onboard pipeline. When a repo has CI/CD, container, or deploy files, onboarding now produces a cited docs/superpowers/architecture/operations.md instead of silently dropping that layer from the generated knowledge base.

Additive & gated — operations.md is only generated when ops files are present and the maintainer confirms it at the existing HUMAN GATE; an unattended/auto-approve run includes it with no new code path.

Why

pack already includes docker/**, .github/workflows/*, Terraform, and deploy scripts, so the raw material reached EXTRACT — but DETECT never inventoried it, EXTRACT had no claim type for it, and the arch doc set was fixed at architecture.md / business-logic.md / tech-context.md. Net effect: Docker topology, CI/CD, production domain, and runbooks were silently skipped — becoming confident partial truth downstream. This closes that blind spot.

How it works

• New deterministic detect-ops subcommand (mirrors detect-ui) inventories three categories — CI/CD (.github/workflows/*, .gitlab-ci.yml, .circleci/config.yml, Jenkinsfile, …), containers/infra (Dockerfile*, docker-compose*/compose.*, *.tf/*.tfvars, k8s heuristics), and deploy/PaaS (Procfile, fly.toml, vercel.json, deploy*.sh, …). Returns {signals_found, ci_cd[], containers[], deploy[]}; CLI prints ops/no-signals or --json. Empty scan = open question at the gate, never a no-ops verdict.
• EXTRACT gains a 5th claim type (operations) targeting operations.md; load-bearing rules still bite (deploy-secret path, prod/branch gate, fail-closed CI check). type is free-form to verify-citations, so no schema change.
• The HUMAN GATE (§6) presents operations.md as its own explicit per-artifact confirm; declining drops it. k8s detection is an honest filename/dir heuristic, flagged as such.

Contents

• scripts/compound-v-onboard.py — detect_ops() + _ops_category() + detect-ops CLI + selftest (walks the filesystem excluding VENDOR_DIRS, so the non-git --selftest trees detect too)
• skills/compound-v/onboarding.md — DETECT bullet, EXTRACT type, operations.md doc section, §6 gate confirm, §7 write surface, refresh note
• docs/superpowers/specs/2026-06-30-v-onboard-design.md — artifacts-table row + conditional-fourth prose
• Design spec + implementation plan under docs/superpowers/{specs,plans}/2026-07-17-*

Conventions / gates (verified locally)

• ✅ Rebased onto main; python3 scripts/compound-v-onboard.py --selftest — 77/77 checks pass
• ✅ detect-ops --json verified on this repo (detects its own .github/workflows/*); no-signals on a bare tree
• ✅ No verify-citations / claims-schema change; no new runtime deps, hooks, or scripts
• ⚠️ scripts/lint-frontmatter.py not run — no pyyaml in the local env; N/A regardless (diff touches no frontmatter)

[copeus]

Review: the gap is real, and one change would make the fix honest

Verified the premise against the code before judging it, and it holds:

• pack() already picks up **/Dockerfile, workflows and Terraform — the raw material does reach the pipeline
• DETECT has exactly one function today, detect_ui. Nothing inventories ops
• grepping all four generated architecture docs for deploy|docker|ci/cd returns nothing

So the material arrives and evaporates between stages. Your framing — "becoming confident partial truth downstream" — is the accurate one, and it's the part that matters: an agent reading our KB gets a document that looks like a complete description of the system and contains no production domain and no deployment path.

The implementation follows the existing precedent (detect_ops mirrors detect_ui), the claim type is free-form so no schema change is needed, it's gated behind the existing human confirm, and the k8s heuristic is labelled as a heuristic rather than presented as fact. That last one is exactly the house rule, and it's good to see it applied unprompted.

The one change I'd ask for

detect_ops matches a fixed list — GitLab, CircleCI, Travis, Azure, Bitbucket, Dockerfile*, *.tf, Procfile, fly.toml, vercel.json. A project that deploys via a bespoke ship.sh matches nothing, and the pipeline concludes "no ops".

That is the same bug this PR fixes, moved down one floor. Today the KB is silently missing the ops layer; after this it would silently assert there isn't one — and a stated absence reads more confidently than a gap.

Ask: don't let the detector conclude "no ops" — let it report "no signals found", and surface that at the gate as a question rather than a verdict: "no explicit ops files detected — if this project does deploy, point me at it." Then the hardcoded list works as an accelerator for the common case instead of a verdict on the uncommon one, and the human stays the backstop exactly where the heuristic is blind.

This is the same rule we applied elsewhere this week: an incomplete scan must never read as a clean one. complete: false beats a confident empty result.

(Fair disclosure: the same critique applies to the detect_ui we already shipped — three filenames and four extensions. You copied our pattern, you didn't invent a shaky one. If you'd rather, moving the signal lists into config so they can be extended without a code change would let us fix both at once, and I'd take that as a follow-up rather than a blocker here.)

Minor

The body says 69/69 selftest checks; main is now at 72, so the branch is a little behind. Needs a rebase and a re-run before merge.

Verdict

Take it. Five files, no overlap with the in-flight v2.18 branch or with #5–#8, real gap, house pattern. This is the cleanest merge in the queue. Please add the "no signals found" framing and rebase, and I'll merge.

[khymerao]

Addressed both, thanks for the sharp read.

"no signals found", not "no ops" — detect_ops now returns signals_found (was present), and its falsity is documented + surfaced as no signals found, never an absence verdict:

• CLI prints no-signals (an open question), not no-ops.
• GATE (§6) now handles both branches. signals_found: false is no longer a silent skip — it poses: "No explicit ops files detected — if this project deploys, point me at it (e.g. a hand-rolled ship.sh)." The human, not the heuristic, decides absence. Autonomous run records "no signals found (not confirmed absent)" so the open question survives to the next interactive pass.
• Selftest asserts the bare-tree result carries empty lists (no false verdict), not just false.

The hardcoded list now works as the common-case accelerator you described, with the human as backstop where it's blind.

Rebase — rebased onto main; selftest is 77/77 now (body updated).

Follow-up (config-driven signal lists for both detect_ops and detect_ui) — agree it's the real fix for the shared blind spot; taking it as a separate follow-up per your note, not folding it in here.