@pareto4/pp-core 1.12.1 → 1.17.1

package/pp-core/workflows/execute-phase/steps/verify-post-gate.md

@@ -0,0 +1,163 @@
+# `verify:post` capability gate dispatch — enforce, do not decorate (TGATE-02, D-05)
+
+Extracted from `execute-phase.md` so the host loop body keeps shrinking, per ADR-857 Phase 6.
+`steps/` files are outside `tests/workflow-size-baseline.json` by design; the host is not, and the
+phase-6 ratchet on the host is a ratchet-DOWN that is never re-baselined. This is the second
+application of that pattern in this workflow — `steps/execute-pre-dispatch.md` is the first — and it
+is the mechanism rather than a workaround: every inline candidate for this body measured over the
+host's remaining headroom, while the labelled Read the host gained costs under a hundred bytes.
+
+This step is dispatched from two callers: `execute-phase.md`'s end-of-phase verification step, and
+`verify-work.md`'s issues-are-zero branch. Each Reads it immediately after it has
+`VERIFY_POST_HOOKS_JSON` in scope. It exists because **rendering is not enforcing**: every
+`verify:post` call site in this repository resolved STEP-kind hooks only, so a gate declared at this
+point would have rendered and been silently ignored — the decorative-dispatch defect already found
+once at the execute-side point. This file is what makes the declaration enforce.
+
+Read the `activeHooks` array from the printed `VERIFY_POST_HOOKS_JSON=` line, in-context (do NOT pipe it through a
+shell parser).
+
+**Admission first (D-28, D-05).** Both callers Read this file unconditionally right after rendering
+`verify:post`, so this is where the strict point refuses a config the gate could not read. It
+precedes the inert branch below because a broken config renders no gate and would take that branch.
+Without `.platform-bindings.json` it is inert and prints nothing.
+
+```bash
+_PP_SHIM_NAME="pp-tools.cjs"; _pp_root() { ( for _v in $(env | sed -n 's/^\(GIT_[A-Za-z0-9_]*\)=.*/\1/p'); do unset "$_v"; done; _c=$(git rev-parse --git-common-dir 2>/dev/null); if [ "${_c##*/}" = .git ] && cd "$_c/.." 2>/dev/null; then pwd -P; else git rev-parse --show-toplevel 2>/dev/null || pwd; fi ); }; pp_run() { case "$PP_TOOLS" in *.cjs) node "$PP_TOOLS" "$@";; *) "$PP_TOOLS" "$@";; esac; }; _PP_RUNTIME_ROOT="${RUNTIME_DIR:-$(_pp_root)}"; PP_TOOLS="${_PP_RUNTIME_ROOT}/pp-core/bin/${_PP_SHIM_NAME}"; if [ -f "$PP_TOOLS" ]; then :; elif [ -f "${_PP_RUNTIME_ROOT}/.claude/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${_PP_RUNTIME_ROOT}/.claude/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${_PP_RUNTIME_ROOT}/.codex/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${_PP_RUNTIME_ROOT}/.codex/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "$HOME/.claude/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="$HOME/.claude/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${HERMES_HOME:-$HOME/.hermes}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${HERMES_HOME:-$HOME/.hermes}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${CURSOR_CONFIG_DIR:-$HOME/.cursor}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CURSOR_CONFIG_DIR:-$HOME/.cursor}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${CODEX_HOME:-$HOME/.codex}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CODEX_HOME:-$HOME/.codex}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${GEMINI_CONFIG_DIR:-$HOME/.gemini}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${GEMINI_CONFIG_DIR:-$HOME/.gemini}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${COPILOT_CONFIG_DIR:-$HOME/.copilot}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${COPILOT_CONFIG_DIR:-$HOME/.copilot}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${AUGMENT_CONFIG_DIR:-$HOME/.augment}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${AUGMENT_CONFIG_DIR:-$HOME/.augment}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${TRAE_CONFIG_DIR:-$HOME/.trae}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${TRAE_CONFIG_DIR:-$HOME/.trae}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${QWEN_CONFIG_DIR:-$HOME/.qwen}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${QWEN_CONFIG_DIR:-$HOME/.qwen}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${CLINE_CONFIG_DIR:-$HOME/.cline}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CLINE_CONFIG_DIR:-$HOME/.cline}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${GROK_AGENTS_HOME:-$HOME/.agents}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${GROK_AGENTS_HOME:-$HOME/.agents}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/pp-core/bin/${_PP_SHIM_NAME}"; elif command -v pp-tools >/dev/null 2>&1; then PP_TOOLS="$(command -v pp-tools)"; else echo "ERROR: pp-tools.cjs not found at $PP_TOOLS and pp-tools is not on PATH. Run: npx -y @pareto4/pp-core@latest --claude --local" >&2; exit 1; fi; if [ -n "${CLAUDE_ENV_FILE:-}" ] && [ -n "${PP_TOOLS:-}" ]; then printf "export PATH='%s':\"\$PATH\"\n" "${PP_TOOLS%/*}" >> "$CLAUDE_ENV_FILE" 2>/dev/null || true; fi
+VAULT_ADMIT_PRESENT=$(pp_run query platform-bindings --pick present 2>/dev/null || echo true)
+VAULT_ADMIT=inert
+if [ "$VAULT_ADMIT_PRESENT" = true ]; then VAULT_ADMIT=$(pp_run vault admission 2>/dev/null || echo unrecognised); fi
+case "$VAULT_ADMIT" in on) echo "VAULT_ADMIT=on" ;; off|inert) : ;; *) pp_run vault admission --explain; echo "PARETO_GATE_BLOCKED:vault.admission"; exit 1 ;; esac
+```
+
+**If `activeHooks` is empty or absent, or contains no entry where `kind == "gate"` and a
+`check.query` is present:** skip the rest of this file silently. Print nothing. This branch comes
+first deliberately — it is what keeps a project with no active `verify:post` capability
+structurally inert, and a gate paragraph reached before it would fire on a project that never
+enabled the capability at all.
+
+The predicate tests BOTH conditions, which is the predicate `ship.md`'s generic loop tests. Until
+04-12 it tested only the first, and that looser form was **harmless rather than correct**: an entry
+carrying no `check.query` would have reached the enforcer, whose own loop filters it out — so the
+right behaviour came from another file's guard rather than from this one's, and no predicate gate
+is declared at this point today that would have exposed the difference. A guard that is correct by
+another file's behaviour is one edit away from being wrong.
+
+**Otherwise, dispatch the gate.** Set:
+
+- `GATE_POINT=verify:post` — the loop point label, message text only.
+- `GATE_HOOKS_JSON=$VERIFY_POST_HOOKS_JSON` — the payload the host already rendered above; this
+  file never renders hooks itself.
+- `GATE_POSITIONAL_ARG="${PHASE_DIR}"` — the phase directory, which the host already has in scope
+  on the line after the render.
+- `GATE_UNPAIRED=strict` — **but only on a FULL-PHASE run: when the host's `WAVE_FILTER` is unset
+  AND this invocation carried no `--gaps-only`.** On a full-phase run this is one of the two points
+  at which every plan must already have an executed counterpart, so a
+  plan artifact with no summary counterpart is a real defect here rather than the normal
+  mid-lifecycle state it is at `plan:post` and `execute:wave:post`. When **either** of those
+  partial-execution modes is active, do not set `GATE_UNPAIRED` at all.
+
+  Four facts a future editor needs before touching this condition (04-12, CR-04; 04-18, WR-01).
+  The condition is on **partial execution**, not on one flag — read all four before adding a fifth
+  mode, because two of these were written when the condition named `WAVE_FILTER` alone and the
+  omission of the other mode shipped a halt onto a supported command. **One:** a
+  `--wave N` run legitimately leaves every later-wave plan holding a PLAN.md and no SUMMARY.md —
+  that is what the mode is *for*, and the host sets `WAVE_FILTER` from `--wave N` during argument
+  parsing, filters the plan list on it, and runs a wave-safety check on it, all before this point.
+  **Two:** this step runs **before** the host's `handle_partial_wave_execution` step, which is the
+  step that exists precisely to handle an incomplete phase — so an unconditional strict verdict
+  here is a false halt on a supported execution mode reached *ahead of* the code that would have
+  explained it, and the gate is declared `blocking: true` / `onError: halt`, so the user cannot
+  advance to the next wave at all. **Three:** the `ship:pre` caller is deliberately **not**
+  conditioned the same way and must not be "harmonised" with this one. Its preflight requires
+  `verification.status == passed` before its gate loop is reachable, so a ship run is by
+  construction a full-phase run: it has no partial mode and therefore no false halt to fix. The
+  asymmetry between the two strict points is the whole finding.
+
+  **Four:** `--gaps-only` is a partial-execution mode in exactly the sense `--wave N` is, and the
+  original condition did not cover it — the prose here even asserted `--wave N` was "the third
+  mid-lifecycle case", which made a complete-sounding enumeration out of an incomplete one. The
+  host filters the plan list on `--gaps-only` on the same line it filters on `WAVE_FILTER`, so a
+  gaps-only run legitimately leaves every **non**-gap plan holding a PLAN.md and no SUMMARY.md.
+  With the condition keyed to `WAVE_FILTER` alone, such a run reached this gate with `WAVE_FILTER`
+  unset, set `GATE_UNPAIRED=strict`, and drew `coverage_pair_missing` / `block: true` on those
+  untouched plans — a hard halt, on a `blocking: true` / `onError: halt` hook, that the user cannot
+  advance past. And `handle_partial_wave_execution` does not rescue it twice over: it guards on
+  `WAVE_FILTER` only, and it runs *after* this point regardless. Worst of all, the host documents
+  `/pp:execute-phase {X} --gaps-only` (with the workstream flag) as the gap-closure cycle's **own**
+  command — so the halt landed on the documented remedy for a failed verification, i.e. on the next
+  pass of the very loop this gate serves. The workstream placeholder is deliberately NOT written out
+  here: this file emits no command, and the token carries a substitution obligation that only a file
+  which does emit one should take on.
+
+  **Why this is keyed to the flag and not to a plan count.** `--wave N` is bound to a named host
+  variable; `--gaps-only` is not — the host's argument parsing says it "keeps its current meaning"
+  and every later reference is to the flag by name. So the flag is the only form available at this
+  point, and using it matches how the host itself tests this mode. Keying instead on "no incomplete
+  plans remain" would be a better invariant and would cover the *next* mode without an edit, but
+  that count does not exist yet here: the post-execution plan index is computed inside
+  `handle_partial_wave_execution`, one step **later**. Moving the count earlier is a host edit, and
+  the host is under a ratchet-down byte budget this file exists to protect. If a future change puts
+  an incomplete-plan count in scope at this point, prefer it to both flags and delete this fact.
+
+  The tolerant path is reached by leaving `GATE_UNPAIRED` **unset**, never by setting it to the
+  literal `tolerant`. The enforcer emits this parameter as a two-expansion flag pair specifically so
+  an unset variable contributes no word at all and the command line stays byte-identical to the one
+  that shipped before the parameter existed. An editor who writes the tolerant literal instead gets
+  a command line that works for a different reason — its equivalence to the unset case is the
+  router's tolerance of an explicit value, not the enforcer's contract — and the next parameter
+  added to that line inherits the confusion.
+
+Set **no** `GATE_WS`: a phase **directory** already carries the workstream partition — the
+enforcer's own parameter table says so — so the flag is neither needed nor set. Set **no**
+`GATE_STAGE`: this point validates BOTH stages, exactly as the `execute:post` caller deliberately
+omits it, and that omission is the documented invariant rather than an oversight to tidy up later.
+
+**A caller exposing neither partial-execution mode is a full-phase run by construction, and therefore
+strict.** The condition above is written for the host, which binds `WAVE_FILTER` during argument
+parsing and parses `--gaps-only`. `/pp-verify-work` binds neither, so both of its tests are vacuously
+satisfied and the strict value applies on every one of its runs. That is the right verdict rather
+than an accident of the wording: a UAT pass is a whole-phase judgement, and it is the point at which
+that workflow marks the phase complete in ROADMAP.md and STATE.md, so a plan artifact with no
+executed counterpart is exactly the defect the strict value exists to catch — not the normal
+mid-lifecycle state it is at `plan:post` and `execute:wave:post`. The obligation that places on the
+next caller: if one ever grows a partial-execution mode, it owes this condition the same two tests
+the host already answers, written here rather than assumed at the call site.
+
+**Before the enforcer runs, close the phase's range.** Run
+`pp_run vault manifest record "${PHASE_DIR}" --raw`, print its one-line result, and continue
+regardless. It writes `phases[<phase>].commits` = `git rev-list --reverse --no-merges
+<startCommit>..HEAD` beside the anchor item 4 of `execute-pre-dispatch.md` recorded, so the
+`vault.audit` gate dispatched next and `/pp-undo` read one list. A phase with no anchor (built
+before the anchor existed) answers `start-not-recorded`, which is exactly the case the audit's
+trace-digest fallback covers. `/pp-verify-work` reaches this file with `${PHASE_DIR}` bound too.
+
+**Then commit the recorded manifest.** Only when that result's `ok` is `true`, run
+`pp_run query commit "docs(phase-<phase>): record phase manifest" --files "<manifestPath>"`, with
+`<phase>` and `<manifestPath>` taken from the same result (`manifestPath` is root-relative). Print the
+outcome and continue on every path. Without this, a project that commits `.planning/` keeps the
+manifest untracked and `/pp-ship`'s clean-tree preflight asks about it every time. The commit verb
+itself skips on `commit_docs: false` and on a gitignored `.planning/`, so no guard is added here. A
+`nothing_to_commit` or failed commit is printed, never retried with raw `git`, and never halts.
+
+Then Read and follow `pp-core/workflows/execute-phase/steps/check-query-gate.md` — the single
+generic `check.query` gate enforcer (GATE-02, D-VH-7). **It owns the halt decision**, the two-step
+contract and the `message` passthrough. Do not restate its loop here, and do not interpret its
+verdict here: a third enforcement loop is precisely what that enforcer was created to prevent, and
+two were already collapsed into it.
+
+**After the enforcer returns, certify the phase's end anchors — on a full-phase run only.** The
+enforcer halts on a blocking verdict, so this paragraph is reached only when it let the run go on;
+nothing here assumes the phase is clean from that. On a full-phase run (the same two tests that set
+`GATE_UNPAIRED=strict` above: `WAVE_FILTER` unset and no `--gaps-only`), run
+`pp_run vault anchor certify "${PHASE_DIR}" --raw`, print its one-line result, and continue
+regardless. On a `--wave N` or `--gaps-only` run, skip it: the verb's own strict check would block on
+the plans not yet run, so it could only refuse `not-clean`. The verb re-runs
+`check vault.trace "${PHASE_DIR}" --unpaired strict` itself and records each SUMMARY's end anchor in
+the directory's `.vault-certificates.json` only when that check answers clean with no override, so
+this step can never certify what the gate did not pass (D-107, D-108). A skipped or failed step
+certifies nothing, which only widens the next phase's SEAL-01 reach and never hides a commit (D-110).
+The verb prints nothing unless `vault admission` answers `on` (no `.platform-bindings.json`, or the
+vault off), so print nothing yourself then either. Every result (a certificate, `kept`, or a
+refusal such as `not-clean` or `overridden`) is printed, never retried, and never halts. No bash fence: this file carries one
+launcher preamble, in the admission fence, and this step runs as the manifest-record step above runs.