fix(v-onboard): detect-ops reports 'no signals found', never a 'no ops' verdict

Per review: a fixed signal list is an accelerator for the common case, not a
verdict on the uncommon one. A project deploying via a bespoke ship.sh matched
nothing and the pipeline would silently assert 'no ops layer' — a stated absence
reads more confidently than a gap.

- detect_ops: rename present -> signals_found; falsity documented as 'no signals
  found', not 'no ops'. Empty result carries empty lists, no verdict.
- CLI: print 'no-signals' (an open question), not 'no-ops' (a false absence).
- onboarding.md §1/§3/§6/operations.md: empty scan is never a silent skip; the
  GATE surfaces an open question ('point me at your deployer, e.g. ship.sh').
  Autonomous run records 'no signals found (not confirmed absent)'.
- specs updated; selftest asserts empty lists on bare (no false verdict).

Author: khymerao

docs/superpowers/specs/2026-06-30-v-onboard-design.md

@@ -49,7 +49,7 @@ it in would change that command's character. They stay composable: `/v:init`'s c
 | File | Location | When | Verification |
 |---|---|---|---|
 | `architecture.md`, `business-logic.md`, `tech-context.md` | `docs/superpowers/architecture/` | always | citation hybrid (§7) |
-| `operations.md` | `docs/superpowers/architecture/` | ops files present, confirmed at gate | citation hybrid (§7) |
+| `operations.md` | `docs/superpowers/architecture/` | ops signals found (or maintainer-pointed), confirmed at gate | citation hybrid (§7) |
 | `CONVENTIONS.md` | repo root | code present | derived from real config evidence |
 | `DESIGN.md` (Google format) | repo root | UI repo only | `@google/design.md lint` (§8 caveat) |
 | `AGENTS.md` (primary, confirmable) + thin `CLAUDE.md` (`@AGENTS.md`) | repo root | always | detect-and-bridge (§6) |

docs/superpowers/specs/2026-07-17-v-onboard-operations-dimension-design.md

@@ -64,10 +64,11 @@ bare bool:
 
 ```
 detect_ops(repo) -> {
-  "present":    bool,          # true iff any category non-empty
-  "ci_cd":      [paths...],
-  "containers": [paths...],
-  "deploy":     [paths...],
+  "signals_found": bool,       # true iff >=1 KNOWN signal matched. FALSE = "no signals found",
+                               # NOT "no ops layer" — a bespoke ship.sh matches nothing yet exists.
+  "ci_cd":         [paths...],
+  "containers":    [paths...],
+  "deploy":        [paths...],
 }
 ```
 
@@ -88,11 +89,13 @@ always tracked, so this does not diverge from the git-tracked PACK/scope-gate in
 CLI wiring (mirrors `detect-ui`):
 
 - `add_parser("detect-ops")` with `--repo` (default `.`) and `--json`.
-- `main()`: `detect-ops` prints `ops` / `no-ops` by default; with `--json`, prints the
-  grouped inventory dict. Exit 0.
-- **Selftest** in the existing selftest block: `detect_ops(...)["present"] is True` on a
-  fixture containing a `.github/workflows/ci.yml` (or `Dockerfile`); `... is False` on a
-  bare tree — matching the shape of the existing `detect_ui` true/false selftests.
+- `main()`: `detect-ops` prints `ops` / `no-signals` by default (deliberately **not** `no-ops` —
+  the empty case is an open question, not an absence verdict); with `--json`, prints the grouped
+  inventory dict. Exit 0.
+- **Selftest** in the existing selftest block: `detect_ops(...)["signals_found"] is True` on a
+  fixture containing a `.github/workflows/ci.yml` (or `Dockerfile`); `... is False` **with empty
+  category lists** on a bare tree (asserting the empty result carries no false verdict) — matching
+  the shape of the existing `detect_ui` true/false selftests.
 
 ### 4.2 `onboarding.md` authority-doc edits
 
@@ -107,17 +110,25 @@ CLI wiring (mirrors `detect-ui`):
   **load-bearing** (`security` / `fail-closed`) and blocks on unsupported per the existing
   two-tier gate.
 - **New "operations.md" section** (parallel to the CONVENTIONS.md / DESIGN.md section) —
-  `operations.md` is generated **only when `detect-ops` is `ops`**; on a repo with no ops
-  files it is **skipped** (verify this negative path on a non-ops dogfood, mirroring the
-  DESIGN.md negative-path note). Read-then-cite from real workflow / Docker / deploy files.
-  Covers: container topology, CI/CD stages, deploy target + production domain, runbook
-  pointers. Never extracts a credential into the doc — `scan-output` (§7) still refuses.
-- **§6 HUMAN GATE** — `operations.md` is presented as its **own explicit per-artifact
-  confirm**, framed with the detected inventory: *"DevOps/deployment tooling detected:
-  `<ci_cd / containers / deploy inventory>` — include `operations.md`?"* Decline → the doc
-  is dropped and nothing is written for it. Under a fully autonomous / unattended run the
-  gate auto-approves it, same as every other artifact — this is the "take them into account
-  without asking in an autonomous cycle" behavior, and it needs no new code path.
+  `operations.md` is generated when `detect-ops` found signals (`signals_found: true`) **or** when
+  the maintainer answers the GATE's open question by naming a bespoke deployer the signal list
+  missed. It is skipped **only** when `signals_found: false` **and** the human confirmed there is
+  genuinely nothing — never silently on an empty scan (verify BOTH the found path and the
+  open-question path on dogfoods). Read-then-cite from real workflow / Docker / deploy files (or the
+  file the maintainer pointed at). Covers: container topology, CI/CD stages, deploy target +
+  production domain, runbook pointers. Never extracts a credential — `scan-output` (§7) still refuses.
+- **§6 HUMAN GATE** — the detector is an accelerator, never a verdict, so the gate surfaces ops in
+  **both** branches:
+  - `signals_found: true` → `operations.md` as its **own explicit per-artifact confirm**, framed
+    with the detected inventory: *"DevOps/deployment tooling detected: `<ci_cd / containers / deploy
+    inventory>` — include `operations.md`?"* Decline → dropped.
+  - `signals_found: false` → **not** a silent skip but an **open question**: *"No explicit ops files
+    detected — if this project deploys, point me at it (e.g. a hand-rolled `ship.sh`)."* Human names
+    it → documented; human confirms nothing → skipped. The human, not the heuristic, decides.
+
+  Under a fully autonomous / unattended run the gate auto-approves the `signals_found: true` doc
+  (ops taken into account without asking — no new code path); with `signals_found: false` and no
+  human, it records "no signals found (not confirmed absent)" rather than asserting no ops layer.
 - **§7 WRITE surface** — add `docs/superpowers/architecture/operations.md` to the approved
   v1 write set. It is a normal cited architecture doc: provenance header, output secret
   gate, commit-before-index all apply unchanged.
@@ -127,7 +138,7 @@ CLI wiring (mirrors `detect-ui`):
 ### 4.3 Spec `2026-06-30-v-onboard-design.md`
 
 - Add an artifacts-table row:
-  `operations.md | docs/superpowers/architecture/ | ops files present, confirmed | citation hybrid (§7)`.
+  `operations.md | docs/superpowers/architecture/ | ops signals found or maintainer-pointed, confirmed | citation hybrid (§7)`.
 - Note `operations.md` as the **conditional fourth** architecture doc (the durable set is
   three-always + `operations.md`-when-ops), consistent with the Cline Memory Bank framing.
 
@@ -143,9 +154,12 @@ No `verify-citations` / claims-schema change. No pre-flight change.
 
 ## 6. Verification
 
-- `detect_ops` selftest passes (present-true on fixture, present-false on bare) inside the
-  existing `python3 scripts/compound-v-onboard.py selftest` run; whole selftest stays green.
+- `detect_ops` selftest passes (`signals_found`-true on fixture; `signals_found`-false **with empty
+  lists** on bare) inside the existing `python3 scripts/compound-v-onboard.py selftest` run; whole
+  selftest stays green.
 - `detect-ops --json` returns the grouped inventory on a real ops repo (e.g. the Laravel+Vue
-  dogfood with `docker/**` + `.github/workflows/ci.yml`); `no-ops` on a bare tree.
-- Manual pipeline read-through: an ops repo surfaces the gate confirm and, on approval,
-  writes a cited `operations.md`; a non-ops repo skips it (negative path).
+  dogfood with `docker/**` + `.github/workflows/ci.yml`); `no-signals` on a bare tree.
+- Manual pipeline read-through, **both** gate branches: an ops repo surfaces the confirm and, on
+  approval, writes a cited `operations.md`; a signal-less repo surfaces the **open question** (not a
+  silent skip) — the doc is written if the maintainer points at a bespoke deployer, skipped only if
+  they confirm none.

scripts/compound-v-onboard.py

@@ -272,7 +272,13 @@ def _ops_category(rel: str):
 
 def detect_ops(repo: str) -> dict:
     """Inventory CI/CD + container/infra + deploy files. Walks the filesystem (excluding VENDOR_DIRS)
-    so it works on non-git trees too. `present` is True iff any category matched."""
+    so it works on non-git trees too.
+
+    `signals_found` is True iff at least one KNOWN signal matched. Its falsity means "no signals
+    found" — NOT a verdict that the project has no ops layer. The signal list is a fixed accelerator
+    for the common case; a bespoke deployer (e.g. `ship.sh`) matches nothing, so an empty result is
+    an OPEN QUESTION the gate must surface ("no explicit ops files — if this project deploys, point
+    me at it"), never a confident "no ops". An incomplete scan must never read as a clean one."""
     found = {"ci_cd": [], "containers": [], "deploy": []}
     for dirpath, dirnames, filenames in os.walk(repo):
         dirnames[:] = [d for d in dirnames if d not in VENDOR_DIRS]
@@ -283,7 +289,7 @@ def detect_ops(repo: str) -> dict:
                 found[cat].append(rel)
     for k in ("ci_cd", "containers", "deploy"):
         found[k].sort()
-    found["present"] = any(found[k] for k in ("ci_cd", "containers", "deploy"))
+    found["signals_found"] = any(found[k] for k in ("ci_cd", "containers", "deploy"))
     return found
 
 
@@ -970,13 +976,18 @@ def check(name, cond):
         with open(os.path.join(d5b, "Dockerfile"), "w") as fh: fh.write("FROM alpine\n")
         with open(os.path.join(d5b, "fly.toml"), "w") as fh: fh.write("app='x'\n")
         r_ops = detect_ops(d5b)
-        check("detect_ops present true on ci+docker", r_ops["present"] is True)
+        check("detect_ops signals_found true on ci+docker", r_ops["signals_found"] is True)
         check("detect_ops finds ci_cd workflow", ".github/workflows/ci.yml" in r_ops["ci_cd"])
         check("detect_ops finds container Dockerfile", "Dockerfile" in r_ops["containers"])
         check("detect_ops finds deploy fly.toml", "fly.toml" in r_ops["deploy"])
     finally:
         shutil.rmtree(d5b, ignore_errors=True)
-    check("detect_ops present false on bare", detect_ops(tempfile.mkdtemp())["present"] is False)
+    # Bare tree ⇒ signals_found False. This is "no signals found" (an open question for the gate),
+    # never a "no ops layer" verdict — a bespoke deployer would match nothing yet still exist.
+    d5c = detect_ops(tempfile.mkdtemp())
+    check("detect_ops signals_found false on bare", d5c["signals_found"] is False)
+    check("detect_ops empty lists on bare (no false verdict, just no signals)",
+          d5c["ci_cd"] == [] and d5c["containers"] == [] and d5c["deploy"] == [])
 
     # OUTPUT-side secret gate: blocks a secret in a GENERATED doc, passes clean prose.
     d6 = tempfile.mkdtemp()
@@ -1290,7 +1301,8 @@ def main(argv) -> int:
         if args.json:
             print(json.dumps(result, indent=2))
         else:
-            print("ops" if result["present"] else "no-ops")
+            # "no-signals" (an open question for the gate), NOT "no-ops" (a false absence verdict).
+            print("ops" if result["signals_found"] else "no-signals")
         return 0
     if args.cmd == "scan-output":
         result = scan_output_files(os.path.abspath(args.repo), args.files)

skills/compound-v/onboarding.md

@@ -55,17 +55,21 @@ Inventory the ground truth, write nothing:
 - **Existing instruction files** (treat per the cardinal rule above), stack, git remote origin.
 - **UI presence** via `python3 scripts/compound-v-onboard.py detect-ui --repo .` → `ui` / `no-ui`.
   This is the only thing that decides whether the DESIGN.md branch runs (step 9 / §DESIGN below).
-- **Operations / Deployment presence** via `python3 scripts/compound-v-onboard.py detect-ops
-  --repo . --json` → `{present, ci_cd[], containers[], deploy[]}`. Inventories CI/CD
+- **Operations / Deployment signals** via `python3 scripts/compound-v-onboard.py detect-ops
+  --repo . --json` → `{signals_found, ci_cd[], containers[], deploy[]}`. Inventories CI/CD
   (`.github/workflows/*`, `.gitlab-ci.yml`, `.circleci/config.yml`, `Jenkinsfile`,
   `azure-pipelines.yml`, `.travis.yml`, `bitbucket-pipelines.yml`), container/infra
   (`Dockerfile*`, `docker-compose*`/`compose.*`, `*.tf`/`*.tfvars`, and k8s heuristics —
   `k8s/`, `kustomization.yaml`, Helm `Chart.yaml`), and deploy/PaaS (`Procfile`, `fly.toml`,
   `vercel.json`, `netlify.toml`, `render.yaml`, `serverless.yml`, `app.yaml`, `deploy*.sh`).
   Silent inventory like `detect-ui` — the *include-it?* ask lives at the GATE (§6), not here.
-  `present: true` is what gates the operations.md branch (§operations.md below). k8s detection
-  is a filename/dir heuristic (it cannot see manifest content) — stated as such here and in the
-  operations.md doc section.
+  The fixed signal list is a **common-case accelerator, not a verdict**:
+  `signals_found: true` proposes the operations.md branch with the found files; `signals_found:
+  false` means **"no signals found," NOT "this project has no ops layer"** — a bespoke deployer
+  (e.g. a hand-rolled `ship.sh`) matches nothing yet still exists. So the empty case is **never a
+  silent skip**; it becomes an **open question at the GATE** (§6). An incomplete scan must never
+  read as a clean one. k8s detection is a filename/dir heuristic (it cannot see manifest content) —
+  stated as such here and in the operations.md doc section.
 - **Style configs**: eslint / prettier / ruff / editorconfig / tsconfig / lockfiles — the
   deterministic evidence `CONVENTIONS.md` is later derived from.
 - **Cross-tool signal** for the bridge decision: presence of `.cursor*`, `.windsurf*`, `GEMINI.md`,
@@ -101,7 +105,9 @@ A claim is **load-bearing** when it concerns **security, fail-closed behavior, o
 the claims where being confidently wrong is dangerous.
 
 `operations` claims (CI/CD, container topology, deploy target, runbook pointers) target
-`operations.md` and are emitted **only when DETECT's `detect-ops` reported `present: true`**. The
+`operations.md` and are emitted when DETECT found ops signals (`signals_found: true`) **or** when
+the maintainer answered the GATE's open question by pointing at a bespoke deployer the signal list
+missed (§6). The
 load-bearing rule still bites: a deploy-secret path, a production/branch deploy gate, or a
 fail-closed CI check is **load-bearing** (`security` / `fail-closed`) and blocks on unsupported
 per the two-tier gate (§4) like any other load-bearing claim. `type` is free-form to
@@ -154,13 +160,25 @@ Also flag drift from `python3 scripts/compound-v-onboard.py staleness --repo .`
 Present, for approval, a **per-artifact AND per-section diff**, alongside confidence/staleness and
 the diagnosis. **Nothing is written before explicit approval** — no auto-apply, ever.
 
-When `detect-ops` reported `present: true`, present `operations.md` as its **own explicit
-per-artifact confirm**, framed with the detected inventory: *"DevOps/deployment tooling detected —
-`<ci_cd / containers / deploy counts + paths>` — include `operations.md`?"* Declining drops the doc
-and writes nothing for it; this is the *"ask the user whether to take DevOps into account"* decision.
+**Operations coverage — surface it in BOTH branches; the detector is an accelerator, never a verdict:**
+
+- **`signals_found: true`** — present `operations.md` as its **own explicit per-artifact confirm**,
+  framed with the detected inventory: *"DevOps/deployment tooling detected —
+  `<ci_cd / containers / deploy counts + paths>` — include `operations.md`?"* Declining drops the doc
+  and writes nothing for it; this is the *"ask the user whether to take DevOps into account"* decision.
+- **`signals_found: false`** — do **not** conclude "no ops layer" and skip silently. The fixed signal
+  list is blind to bespoke deployers, so surface the gap as an **open question**, not a verdict:
+  *"No explicit ops files detected. If this project does deploy, point me at it (e.g. a hand-rolled
+  `ship.sh`, a Makefile target, an internal runbook) and I'll document it in `operations.md`."* If the
+  maintainer names something, EXTRACT reads-then-cites it into `operations.md`; if they confirm there
+  is genuinely nothing, it is skipped — but the **human**, not the heuristic, made that call.
+
 A fully autonomous / unattended run (auto-approve / `--permission-mode dontAsk` — today the headless
-marathon, or any future autonomous onboarding cycle) approves it like every other artifact, so ops
-is taken into account **without asking** — no separate code path is needed.
+marathon, or any future autonomous onboarding cycle) auto-approves the `signals_found: true` doc like
+every other artifact (ops taken into account **without asking** — no separate code path). With
+`signals_found: false` and no human to answer, it records **"ops coverage: no signals found (not
+confirmed absent)"** rather than asserting there is no ops layer — the open question survives to the
+next interactive pass instead of being silently resolved as "none".
 
 Critically, the diff **expands every `@import` target** (to the 4-hop limit). `@import` is **not a
 token optimization** — an imported file loads in **full** at launch; only path-scoped rules and
@@ -273,15 +291,18 @@ explore → ask → propose → write.
   green). Therefore the gate states **"token pairs pass WCAG AA structurally"** — **never
   "accessible."** Document the linter's blindness in the gate output, and flag multi-theme / arbitrary
   Tailwind class colors as "partial capture" rather than implying full coverage.
-- **`operations.md`** (`docs/superpowers/architecture/`, ops repos) is generated **only when
-  `detect-ops` reported `present: true`.** On a repo with no CI/CD, container, or deploy files it
-  is **skipped** (verify this negative path on a non-ops dogfood, mirroring the DESIGN.md negative
-  path). Read-then-cite from the real workflow / Docker / compose / Terraform / deploy files
-  DETECT inventoried — never from the model's prior. Cover: container topology (services, ports,
-  volumes), CI/CD stages (build → test → deploy triggers and branch/environment gates), the deploy
-  target + production domain, and runbook pointers. **No credential is ever extracted into the
-  doc** — the blocking `scan-output` gate (§7) refuses a generated file that contains one, and a
-  deploy-secret reference is documented by *path*, not value.
+- **`operations.md`** (`docs/superpowers/architecture/`, ops repos) is generated when `detect-ops`
+  found signals (`signals_found: true`) **or** when the maintainer answered the GATE's open question
+  (§6) by naming a bespoke deployer the signal list missed. It is skipped **only** when
+  `signals_found: false` **and** the human confirmed there is genuinely nothing — never silently on an
+  empty scan alone (that "no signals found ≠ no ops layer" distinction is the whole point; verify both
+  the found path and the open-question path on dogfoods). Read-then-cite from the real workflow /
+  Docker / compose / Terraform / deploy files DETECT inventoried (or the file the maintainer pointed
+  at) — never from the model's prior. Cover: container topology (services, ports, volumes), CI/CD
+  stages (build → test → deploy triggers and branch/environment gates), the deploy target +
+  production domain, and runbook pointers. **No credential is ever extracted into the doc** — the
+  blocking `scan-output` gate (§7) refuses a generated file that contains one, and a deploy-secret
+  reference is documented by *path*, not value.
 
 ---