@pareto4/pp-core 1.17.1 → 1.18.0

package/pp-core/workflows/vault-review.md

@@ -1,16 +1,13 @@
 <purpose>
-Retroactive client-vault practice review of a completed phase. Standalone command that works on
-any completed phase — traced or untraced. Produces `{padded}-VAULT-REVIEW.md` with one verdict per
-practice and counts by verdict. This workflow reports; it gates nothing.
+Retroactive review of a completed phase against the client vault's standards documents. Works on
+any phase whose plans carry a `<vault_standards>` block. Produces `{padded}-VAULT-REVIEW.md` with one
+verdict per standards document that governed the phase, and counts by verdict. This workflow
+reports; it gates nothing.
 </purpose>
 
-<required_reading>
-@~/.claude/pp-core/references/verifier-practice-verdicts.md
-</required_reading>
-
 <available_agent_types>
 Valid pp-core subagent types (use exact names — do not fall back to 'general-purpose'):
-- pp-vault-reviewer — Judges the practice remainder the CLI derivation could not settle
+- pp-vault-reviewer — Judges whether the phase's changes conform to each governing standards document
 </available_agent_types>
 
 <process>
@@ -24,57 +21,30 @@ if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 AGENT_SKILLS_VAULT_REVIEWER=$(pp_run query agent-skills pp-vault-reviewer)
 ```
 
-Parse: `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`, `commit_docs`.
-
-### 0a. The vault-off short-circuit — the first act of this workflow
+Parse: `phase_dir`, `phase_number`, `phase_name`, `padded_phase`, `commit_docs`.
 
-Run the derive call now, before any input state is detected, and branch on what the arm prints:
+### 0a. Derive first, and stop when there is nothing to review
 
 ```bash
 REVIEW_PAYLOAD=$(pp_run check vault-review "${PHASE_DIR}" --raw)
 REVIEW_STATUS=$(printf '%s' "${REVIEW_PAYLOAD}" | node -e "let s='';process.stdin.on('data',d=>{s+=d}).on('end',()=>{try{console.log(JSON.parse(s).status||'')}catch{console.log('unparseable')}})")
 ```
 
-**If `REVIEW_STATUS` is `inert`:** print the payload's `statement` field verbatim and STOP here.
-Nothing below this line runs: no agent is spawned, no template is read, and no `VAULT-REVIEW.md` is
-written. A project with the vault practices capability off is left byte-identical by this command
-(the CLAUDE.md inertness rule).
-
-**If `REVIEW_STATUS` is `not_applicable` or `bad-config`:** print the payload's `statement` field
-verbatim and STOP: nothing below runs, no agent is spawned. `not_applicable` is standards mode
-(`vault.mode = standards`): the practices review is parked, and the consulted documents are recorded
-in each plan's `<vault_standards>` block and its SUMMARY's `Standards Consulted` section.
-`bad-config` is a `vault.mode` the engine cannot read.
-
-Why the branch is on the arm's output rather than on the config: **this workflow never reads
-`vault.enabled` or `practices_enabled` itself.** Policy has one home — the CLI arm resolves both keys
-through the shared reader and answers before it touches the vault, the trace or a git subprocess. The
-arm's inert sentence is proven byte-identical between the two spellings of "off" (the key absent, and
-the key present and explicitly `false`) by plan 06-04's integration suite, which compares the two
-outputs byte for byte. Branching here on the arm's output is what makes that proof this workflow's
-proof too; a second config read would be a second policy home that could disagree with the first.
-
-**Capability-OFF is not the same input as an absent vault.** They are never collapsed:
-
-| Input | What happens |
+| `REVIEW_STATUS` | What happens |
 |---|---|
-| The capability is off (`status: inert`) | Stop here, inert. The feature does not apply to this project. |
-| Standards mode or an unrecognised mode (`status: not_applicable` / `bad-config`) | Stop here and print the statement. A parked surface must not render as a clean review. |
-| The capability is on but the vault is missing, unreadable or holds no practices | Continue. The review runs and renders **loudly as gaps-only** through the template's not-derived sections. |
+| `inert` | The vault is off for this project. Print the payload's `statement` and stop. Nothing is written. |
+| `no-argument`, `usage`, `unresolved` | Print the `statement` and stop: the CLI could not use the phase argument. Re-run with the phase directory. |
+| `no-records` | Print the `statement` and stop: no plan in this phase was governed by a standards document. |
+| `ok` | Continue. |
 
-The second row is a phase that was reviewed and whose review found gaps; the first is a project the
-feature does not apply to. A review that reported the second as the first would be reporting a gap as
-an absence of gaps.
-
-**If `REVIEW_STATUS` is `usage`, `no-argument` or `unresolved`:** print the payload's `statement`
-verbatim and stop — the arm reviewed nothing and said which argument it could not use. Re-run with
-the phase directory.
+This workflow never reads `vault.enabled` itself; the CLI is the one place that decides whether the
+vault applies.
 
 Then display the banner:
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- pp-core ► VAULT PRACTICE REVIEW — PHASE {N}: {name}
+ pp-core ► VAULT STANDARDS REVIEW — PHASE {N}: {name}
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
@@ -82,20 +52,17 @@ Then display the banner:
 
 ```bash
 SUMMARY_FILES=$(ls "${PHASE_DIR}"/*-SUMMARY.md 2>/dev/null)
-PLAN_FILES=$(ls "${PHASE_DIR}"/*-PLAN.md 2>/dev/null)
 VAULT_REVIEW_FILE=$(ls "${PHASE_DIR}"/*-VAULT-REVIEW.md 2>/dev/null | head -1)
 ```
 
-- **State A** (`VAULT_REVIEW_FILE` non-empty): a review already exists — re-review, and append a
-  dated audit-trail block to the artifact rather than discarding the previous one.
-- **State B** (`SUMMARY_FILES` non-empty): the phase is completed — run the review.
-- **State C** (`SUMMARY_FILES` empty): exit cleanly — "Phase {N} not executed. Run
-  `/pp:execute-phase {N}` first." This is the honest refusal, and it is the only one. D-06-14 makes
-  **any completed phase** eligible, traced or not; State C refuses only a phase that was never built,
-  because there is no work to review.
-
+- **State A** (`VAULT_REVIEW_FILE` non-empty): a review already exists. Re-review, and append a dated
+  block to the artifact's Audit Trail rather than discarding the previous one.
+- **State B** (`SUMMARY_FILES` non-empty): the phase is completed. Run the review.
+- **State C** (`SUMMARY_FILES` empty): exit cleanly with "Phase {N} not executed. Run
+  `/pp:execute-phase {N}` first."
 
 **Text mode (`workflow.text_mode: true` in config or `--text` flag):** Set `TEXT_MODE=true` if `--text` is present in `$ARGUMENTS` OR `text_mode` from init JSON is `true`. When TEXT_MODE is active, replace every `AskUserQuestion` call with a plain-text numbered list and ask the user to type their choice number. This is required for non-Claude runtimes (OpenAI Codex, Gemini CLI, etc.) where `AskUserQuestion` is not available.
+
 **In State A**, use AskUserQuestion:
 - header: "Existing Vault Review"
 - question: "VAULT-REVIEW.md already exists for Phase {N}."
@@ -105,60 +72,20 @@ VAULT_REVIEW_FILE=$(ls "${PHASE_DIR}"/*-VAULT-REVIEW.md 2>/dev/null | head -1)
 
 If "View": display the file, exit. If "Re-review": continue.
 
-## 2. Provenance — `trace_present_and_loaded`
-
-Read one flag from the payload, and carry it to the spawn:
+## 2. What the payload gives the reviewer
 
-`trace_present_and_loaded` is the payload's **`trace.loaded`**. The CLI sets it true only when a
-`vault:` trace block exists in this phase's artifacts **and** every parsed block records
-`predicate.vault.state: loaded`. A degraded block sets it **false**, and so does an absent one. Two
-fields beside it say which case this is and why: `trace.state` is `loaded`, `degraded`, or `null`
-when no block was found at all, and `trace.reason` names the artifact that failed and what it
-recorded. Do not recompute the flag here — it is derived once, in the CLI, from data this workflow
-never reads.
+The payload is the CLI's derivation and is passed to the agent verbatim; this workflow does not
+reinterpret it.
 
-A degraded block is a valid record of a **failure**: it says no trusted vault load existed when the
-work was planned. It therefore proves nothing about which practices governed that work, which is why
-it is not allowed to stand in for a loaded one. When the flag is false because a trace was found and
-failed, carry `trace.reason` into §5's RECONSTRUCT constraint so the reviewer records why the trace
-could not stand.
+- `documents[]`: every standards document that governed a plan in this phase, with `cachePath` (the
+  cached copy to read; `null` when it is not cached) and `governed[]` (each plan it governed, the
+  planner's `reason`, and the executor's `consulted` status).
+- `plans[]`: each plan's record files, its commit `range`, and the source `files` changed in that
+  range (`filesTruncated` when the list was capped).
+- `gaps[]`: facts the CLI could not establish. Every gap goes into the artifact's `## Not Derived`
+  section; a gap is never silently dropped and never turned into a verdict.
 
-## 3. The three-way short-circuit
-
-`pp-core/workflows/secure-phase.md` states the rule this step copies, in its own words:
-
-> "Empty-by-no-planning must not rubber-stamp a clean SECURITY.md."
-
-Restated for this tier: **an empty or absent trace must never produce a clean review. Reconstruct
-first, then judge.**
-
-| Provenance | What runs |
-|---|---|
-| `trace_present_and_loaded: true`, remainder empty | The derived rows are the whole review. Render them; the agent judges nothing because nothing was left unsettled. |
-| `trace_present_and_loaded: true`, remainder non-empty | Spawn in **verify mode** — judge the supplied remainder only. |
-| `trace_present_and_loaded: false` | Spawn in **RECONSTRUCT mode** — the applicable practice set was rebuilt by the CLI from this phase's real diff crossed with the vault's own practice list, and that reconstructed set is what gets judged. |
-
-**Reconstruct is the primary path, not a degraded one.** A project with no `vault` config key has no
-phase that has or can have a trace, so every review of its own history takes this arm. The payload
-says so in its `statements[]`, and the artifact repeats it.
-
-## 4. The derived payload
-
-`REVIEW_PAYLOAD`, captured in step 0a, is the review's whole factual input and is consumed before the
-spawn. It carries, already computed: `range`, `rangeSource`, `filesConsidered`, the input set, both
-derived-`N-A` populations with their own labels and reasons, the partitioned remainder, the derived
-`derivedCounts` / `derivedRateLine` (what those two describe, and what they are never written as,
-is stated once in the contract block carried into the spawn prompt below),
-`practiceEntries` (each practice's prose already fenced and defanged by the
-shipped renderer), `statements[]`, `notes[]` and `refusesCleanRender`.
-
-**The clean-render refusal is the CLI's, and this workflow honors it rather than reimplementing it.**
-When `refusesCleanRender` is true (the range considered zero files), or when the payload records that
-the vault was absent or unreadable, the review still renders — as a **loud gaps-only artifact**
-through the template's not-derived sections — and never as a clean review. The rule lives in code, in
-the shipped predicate; nothing here restates it as a second copy that could drift.
-
-## 5. Spawn pp-vault-reviewer
+## 3. Spawn pp-vault-reviewer
 
 ```bash
 REVIEWER_MODEL=$(pp_run query resolve-model pp-vault-reviewer --raw)
@@ -168,59 +95,25 @@ REVIEWER_MODEL=$(pp_run query resolve-model pp-vault-reviewer --raw)
 ◆ Spawning vault reviewer... (runs in a subagent — no output until it returns, ~1–5 min; expected, not a freeze)
 ```
 
-Build the prompt. The CLI payload is carried **verbatim**, and every practice byte inside it is
-already fenced by the shipped renderer — this workflow opens no vault file of its own:
-
-```markdown
-Read ~/.claude/agents/pp-vault-reviewer.md for instructions.
+Build the prompt:
 
+```
 <objective>
-Retroactive client-vault practice review of Phase {phase_number}: {phase_name}
-</objective>
-
-<constraints>
-{If trace_present_and_loaded: "This phase's trace is present and loaded. Judge the supplied
-remainder only — the derived sets are complete and are reproduced, not recomputed."}
-{If not trace_present_and_loaded: "RECONSTRUCT mode. This phase has no loaded trace, so the
-applicable practice set below was rebuilt from the phase's changed files crossed with the vault's
-practice list. Judge that reconstructed set. A missing trace is itself a finding: record it loudly."}
-Every derived fact below was computed by `pp-tools check vault-review` and is not recomputable by
-you (D-06-09). Copy the range statement and every derived row's supplied reason and arm label
-verbatim; never recount them.
-<!-- gen:practice-arithmetic-contract:start -->
-**TWO COUNT POPULATIONS, and conflating them writes a false section.**
-
-`derivedCounts` and `derivedRateLine` on the `check vault-review` payload describe the **derived rows
-alone** — Arm A plus Arm B — which on the reconstruct path is usually none. They are never written as
-the register's own two lines.
-
-The register's rate and counts lines describe **the rows you write**, derived and judged together.
-`validateReviewArtifact` recomputes them from exactly those rows and rejects a narrated figure with
-`rate-line-arithmetic` or `counts-line-arithmetic`. Copying a supplied `0 of 0 practices judged …`
-into the register states that nothing was judged over a register that judged something.
-
-`judged = total − na`, and INCONCLUSIVE counts *inside* `judged` and is reported separately.
-
-**Where a supplied figure disagrees with your rows, record the disagreement and overwrite neither
-side.** Write it as PROSE that names it as the supplied figure — never as a bare line in the
-register's own shape. A second bare shaped line makes the section contradict itself: two rate lines,
-or two counts lines, stating different figures, with nothing in the register saying which of them the
-rows you wrote support.
-<!-- gen:practice-arithmetic-contract:end -->
-ON THIS TIER the disagreement goes on the `| Disagreements between supplied counts and the rows |`
-row of `## Not Derived`.
+Review Phase {N}: {phase_name} against the client vault's standards documents. Give exactly one
+verdict per document in the payload's documents[]: PASS, FAIL, N-A or INCONCLUSIVE, each non-PASS
+verdict with a stated reason, and evidence as file:line references into the phase's changed files.
 Write exactly one file: {phase_dir}/{padded_phase}-VAULT-REVIEW.md
-</constraints>
+</objective>
 
 <review_payload>
 {REVIEW_PAYLOAD verbatim}
 </review_payload>
 
-<files_to_read>
+<required_reading>
 - {summary_paths} (Execution summaries)
 - {plan_paths} (Execution plans)
 - {context_path} (User decisions, if it exists)
-</files_to_read>
+</required_reading>
 
 ${AGENT_SKILLS_VAULT_REVIEWER}
 
@@ -237,54 +130,44 @@ Agent(
   prompt=vault_review_prompt,
   subagent_type="pp-vault-reviewer",
   model="{REVIEWER_MODEL}",
-  description="Vault practice review Phase {N}"
+  description="Vault standards review Phase {N}"
 )
 ```
 
 > **ORCHESTRATOR RULE — CODEX RUNTIME**: After calling Agent() above, stop working on this task immediately. Do not read more files, edit code, or run tests related to this task while the subagent is active. Wait for the subagent to return its result. This prevents duplicate work, conflicting edits, and wasted context. Only resume when the subagent result is available.
 
-## 6. Handle Return
-
-The agent returns `## REVIEWED`, `## DEGRADED` or `## ESCALATE`. It reads
-`~/.claude/pp-core/templates/VAULT-REVIEW.md`, fills it, and writes
-`${PHASE_DIR}/${PADDED_PHASE}-VAULT-REVIEW.md` (D-06-16).
+## 4. Handle Return
 
-On `REVIEWED` or `DEGRADED`, run the deterministic shape check over what was written:
+The agent returns `## REVIEWED` or `## ESCALATE`. On `REVIEWED`, check what it wrote:
 
 ```bash
-node -e "const m=require((process.env.PP_LIB || './pp-core/bin/lib') + '/vault-review.cjs');const t=require('fs').readFileSync(process.argv[1],'utf8');const r=m.validateReviewArtifact(t);console.log(JSON.stringify(r.problems,null,2));console.log('rate:',r.expectedRateLine);console.log('counts:',r.expectedCountsLine)" "${PHASE_DIR}/${PADDED_PHASE}-VAULT-REVIEW.md"
+pp_run check vault-review "${PHASE_DIR}" --validate "${PHASE_DIR}/${PADDED_PHASE}-VAULT-REVIEW.md" --raw
 ```
 
-`PP_LIB` defaults to the repo-root layout above. From an installed runtime, set it first —
-`export PP_LIB=~/.claude/pp-core/bin/lib` — because the bare relative path resolves only when the
-cwd is the repo root, and it silently fails everywhere else.
-
-Surface any reported problems to the operator as **repair items**, listed under the artifact's own
-repair heading, and finish with exit 0 either way. A shape complaint is a defect in the artifact to be
-repaired in the artifact — never by editing the validator, and never by deleting the row that produced
-the complaint.
+`valid: true` means every governing document has exactly one verdict row, each verdict is one of the
+four, every non-PASS verdict states its reason, and the counts line agrees with the table. Otherwise
+list each entry of `problems[]` to the operator as a repair item. A problem is repaired in the
+artifact, never by deleting the row that produced it. Exit 0 either way.
 
-`ESCALATE` means no artifact could be written at all (the phase directory does not exist, or the
-payload could not be obtained). Report what the agent said and stop; still exit 0.
+`ESCALATE` means no artifact could be written. Report what the agent said and stop; still exit 0.
 
 Display the summary:
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- pp-core ► VAULT PRACTICE REVIEW COMPLETE
+ pp-core ► VAULT STANDARDS REVIEW COMPLETE
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-**Phase {N}: {Name}** — arm: {traced | reconstruct}
+**Phase {N}: {Name}**
 
-{the artifact's register rate line — the one `validateReviewArtifact` recomputed and accepted}
-{the artifact's register counts line — the one `validateReviewArtifact` recomputed and accepted}
+{the artifact's counts line}
 
-Gaps reported: {none. / the payload's loud statements}
+Gaps reported: {none. / the payload's gaps}
 
 Full review: {path to VAULT-REVIEW.md}
 
 This review reports and does not gate. No verdict above changes a phase status,
-a score, a gap or any deterministic surface — see "Limits of This Review" in the artifact.
+a gap or any gate.
 
 ───────────────────────────────────────────────────────────────
 
@@ -298,28 +181,23 @@ a score, a gap or any deterministic surface — see "Limits of This Review" in t
 ───────────────────────────────────────────────────────────────
 ```
 
-The routing above is offered on **every** path — a review that found `FAIL` rows routes exactly the
-same as one that found none. No step in this workflow reads a verdict, a count or a rate into a halt,
-an exit code, a block or a suppressed route, and nothing here writes to `ROADMAP.md`, `STATE.md`,
-`VERIFICATION.md` or any `SUMMARY.md`. The one file this command produces is the artifact.
+The routing is offered on every path; a review with FAIL rows routes exactly like one without. No
+step reads a verdict into a halt, an exit code or a block, and nothing here writes `ROADMAP.md`,
+`STATE.md`, `VERIFICATION.md` or a `SUMMARY.md`. The one file this command produces is the artifact.
 
-## 7. Commit (if configured)
+## 5. Commit (if configured)
 
 ```bash
-pp_run query commit "docs(${PADDED_PHASE}): vault practice review" --files "${PHASE_DIR}/${PADDED_PHASE}-VAULT-REVIEW.md"
+pp_run query commit "docs(${PADDED_PHASE}): vault standards review" --files "${PHASE_DIR}/${PADDED_PHASE}-VAULT-REVIEW.md"
 ```
 
 </process>
 
 <success_criteria>
-- [ ] Step 0a ran first and branched on the arm's own output
-- [ ] Vault-disabled project: inert sentence printed, nothing else run, nothing written
-- [ ] Input state detected (A/B/C) — State C exits cleanly
-- [ ] `trace_present_and_loaded` read from the payload's `trace.loaded`; degraded and absent both false
-- [ ] Reconstruct arm taken whenever the flag is false, and named as such in the artifact
-- [ ] Agent spawned with the CLI payload verbatim and the origin-dependent constraint
-- [ ] `{padded}-VAULT-REVIEW.md` written in the phase directory; shape check run over it
-- [ ] The payload's derived figures are never written as the register's lines; any difference is on the `| Disagreements between supplied counts and the rows |` row
-- [ ] The register's own rate and counts lines agree with `validateReviewArtifact` over the rows written
+- [ ] Step 0a ran first and stopped on every status other than `ok`
+- [ ] Input state detected (A/B/C); State C exits cleanly
+- [ ] Agent spawned with the CLI payload verbatim
+- [ ] `{padded}-VAULT-REVIEW.md` written in the phase directory and validated with `check vault-review --validate`
+- [ ] Every payload gap appears under Not Derived
 - [ ] Routing offered unconditionally; no verdict reached any halt, block or status
 </success_criteria>