docs(skills): tighten Phase 3 Completion Gate to per-row Cobra resolution (#1173)

d0c4caca57ae295e6b6acee39634e20a0356c87e · 2026-05-12 02:16:17 -0700 · Trevin Chow

* docs(skills): tighten Phase 3 Completion Gate to per-row Cobra resolution

Replace the count-based check with a per-row `<binary> <command> --help`
walk over the absorb manifest's transcendence rows, plus a dogfood
`novel_features_check` JSON backstop. Counting alone passes when a
build replaces an approved command path with a self-contained wrapper
(the dataforseo `--auto-mode` retro), so the gate now asserts the
specific approved leaf resolves to a Cobra command and not a parent
fall-through.

Closes #1151

* docs(skills): clarify Phase 3 Completion Gate Usage-line + skipped semantics

- Assertion (b) now describes Cobra's actual Usage spec line shape
  (`<binary> <leaf> [flags]` vs the `[command]` parent fall-through),
  not "ends with the leaf token" — Cobra's Usage line never ends with
  the bare leaf.
- The dogfood backstop no longer accepts `skipped: true` as a pass.
  Skipped means missing `--research-dir` or empty `novel_features` in
  `research.json` — both are the exact silent-bypass path the gate
  exists to prevent.

Addresses Greptile P2 findings on PR #1173.

Files touched

M skills/printing-press/SKILL.md

Diff

commit d0c4caca57ae295e6b6acee39634e20a0356c87e
Author: Trevin Chow <trevin@trevinchow.com>
Date:   Tue May 12 02:16:17 2026 -0700

    docs(skills): tighten Phase 3 Completion Gate to per-row Cobra resolution (#1173)
    
    * docs(skills): tighten Phase 3 Completion Gate to per-row Cobra resolution
    
    Replace the count-based check with a per-row `<binary> <command> --help`
    walk over the absorb manifest's transcendence rows, plus a dogfood
    `novel_features_check` JSON backstop. Counting alone passes when a
    build replaces an approved command path with a self-contained wrapper
    (the dataforseo `--auto-mode` retro), so the gate now asserts the
    specific approved leaf resolves to a Cobra command and not a parent
    fall-through.
    
    Closes #1151
    
    * docs(skills): clarify Phase 3 Completion Gate Usage-line + skipped semantics
    
    - Assertion (b) now describes Cobra's actual Usage spec line shape
      (`<binary> <leaf> [flags]` vs the `[command]` parent fall-through),
      not "ends with the leaf token" — Cobra's Usage line never ends with
      the bare leaf.
    - The dogfood backstop no longer accepts `skipped: true` as a pass.
      Skipped means missing `--research-dir` or empty `novel_features` in
      `research.json` — both are the exact silent-bypass path the gate
      exists to prevent.
    
    Addresses Greptile P2 findings on PR #1173.
---
 skills/printing-press/SKILL.md | 19 +++++++++++++++----
 1 file changed, 15 insertions(+), 4 deletions(-)

diff --git a/skills/printing-press/SKILL.md b/skills/printing-press/SKILL.md
index a690434a..f494783a 100644
--- a/skills/printing-press/SKILL.md
+++ b/skills/printing-press/SKILL.md
@@ -2274,13 +2274,24 @@ Include:
 
 **MANDATORY. Do NOT proceed to Phase 4 until this gate passes.**
 
-Before moving to shipcheck, verify the build log against the absorb manifest:
+Before moving to shipcheck, verify the build log against the absorb manifest. Counting alone is not enough: a build that replaces an approved `keywords-data google-ads search-volume --auto-mode` with a self-contained wrapper `keywords volume` keeps the count right while shipping a different command than what Phase 1.5 approved. The gate must verify the **specific approved command path** for each transcendence row.
 
-1. Count the transcendence features in the Phase 1.5 manifest's transcendence table
-2. Count the transcendence commands actually built (present in `internal/cli/` and registered in `root.go`)
-3. If built < manifest count, **STOP**. List the missing features and build them before proceeding
+1. **Per-row Cobra resolution check.** Read every transcendence row from `$RESEARCH_DIR/<stamp>-feat-<api>-pp-cli-absorb-manifest.md`. For each row's `Command` value, strip flag tokens and quoted args to get the leaf command path (drop everything from the first `-` token onward; `bottleneck` stays `bottleneck`, `velocity --weeks 4` becomes `velocity`, `compare "LeBron" "Curry"` becomes `compare`, `keywords-data google-ads search-volume --auto-mode` becomes `keywords-data google-ads search-volume`). Then run:
+   ```bash
+   ./<api>-pp-cli <leaf path> --help
+   ```
+   Assert (a) exit code 0 AND (b) the help output's `Usage:` spec line is `<binary> <leaf path> [flags]` — i.e., the line **immediately before** ` [flags]` is the full leaf path you requested. Cobra falls through to the parent's help when a subcommand is unknown — same exit 0, but the Usage spec line is `<binary> <parent> [command]` instead of `<binary> <parent> <leaf> [flags]`. The grep-able signal is `<leaf> [flags]` for a real command vs `[command]` for a parent fall-through; the leaf appearing only under `Available Commands:` is also a fall-through.
+2. **HALT on any miss.** If any approved row fails (a) or (b), STOP. Either build the approved command path now, or return to Phase 1.5 with a revised manifest for explicit re-approval per the existing "no mid-build downgrade" rule. Do not invent a wrapper command and silently update the manifest. Do not classify the feature as "documentation-only" because integration touches many files.
+3. **Deterministic backstop.** After the per-row walk, run the same machine-checked equivalent so a manifest-vs-`research.json` drift cannot mask a miss:
+   ```bash
+   printing-press dogfood --dir "$CLI_WORK_DIR" --research-dir "$API_RUN_DIR" --json \
+     | jq -e '.novel_features_check | .found == .planned and (.missing // []) == [] and (.skipped // false) == false'
+   ```
+   The `novel_features_check` block reports planned/found/missing against `research.json`'s `novel_features`; an exit-0 here plus a clean per-row walk means both sources agree the build matches Phase 1.5 approval. **`skipped: true` is a HALT, not a pass at this gate.** Dogfood marks the check skipped only when `--research-dir` is missing or `research.json` has no `novel_features` key — both conditions mean the gate has no source of truth to verify against, which is exactly the silent-bypass path the gate was designed to prevent. If you reach this gate with no `novel_features` in `research.json` but the absorb manifest lists transcendence rows, re-derive `research.json` from the manifest (per Step 1.5e) before re-running. If `dogfood` reports missing features that the manifest still lists, either `research.json` was edited mid-build (re-derive it from the manifest) or the build is genuinely incomplete (return to step 1).
 4. **Test presence for pure-logic novel packages.** Every Go package you created under `internal/` for novel-feature logic (parsers, matchers, scalers, scrapers — anything that isn't command wiring) must have a `_test.go` with at least one table-driven happy-path test per exported function. `printing-press dogfood` surfaces violations as structural issues: pure-logic packages with zero tests fail shipcheck; packages with fewer than 3 test functions are flagged as warnings for Phase 4.85's agentic review. Trivial placeholder tests pass the file-presence check but are the wrong shape — write real assertions or the review catches you.
 
+The check is structural — no judgment about whether each command does "enough." Behavioral correctness remains dogfood's and scorecard's job in Phase 4.
+
 The generator handles Priority 0 (data layer) and most of Priority 1 (absorbed API endpoints). Priority 2 (transcendence) is always hand-built — the generator does not produce these. If you skip Priority 2, the CLI ships without the features that differentiate it from every other tool.
 
 **Starter templates for novel commands.** Cobra wiring is mechanical and consistent across novel features; the actual feature work lives in the RunE body. Copy the wrapper below and one of the RunE skeletons that follows, fill in the placeholders from the absorb manifest's transcendence row (`Name`, `Command`, `Description`, `Example`, `WhyItMatters`), and replace the body comments with your implementation. Dogfood, verify, and scorecard still apply to the result — the templates raise the floor without changing what shipcheck checks.

← ee13fb16 fix(cli): make dogfood acceptance marker manifest read best- · back to Cli Printing Press · fix(cli): preserve x-mcp config when merging combo specs (#1 660829ed →