@pareto4/pp-core 1.12.0 → 1.13.0

package/pp-core/references/planner-vault-practices.md

@@ -53,7 +53,7 @@ Applies at the `write_phase_prompt` step.
 
 **Vault practices block (only when the vault-practices capability is active):** This whole subsection applies ONLY when the injected `plan:pre -> into: planner` fragment for vault-practices is present in your context — i.e. `vault.enabled` AND `vault.practices_enabled` are both true for this project. When that fragment is absent, do nothing described here: write no `<vault_practices>` block at all, and this PLAN.md stays byte-identical to a plan produced without the capability.
 
-When the fragment IS present: for EACH plan, after that plan's `files_modified` list is finalized and BEFORE calling Write on that plan's PLAN.md, run `pp-tools vault practices match <files_modified...> --block` as an ordinary Bash action against that plan's own files — this call happens in-turn, mid-planning, not before planning starts (the CLI genuinely cannot run any earlier, since `files_modified` does not exist yet at `plan:pre` time).
+When the fragment IS present: for EACH plan, after that plan's `files_modified` list is finalized and BEFORE calling Write on that plan's PLAN.md, run `pp_run vault practices match <files_modified...> --block` as an ordinary Bash action against that plan's own files — this call happens in-turn, mid-planning, not before planning starts (the CLI genuinely cannot run any earlier, since `files_modified` does not exist yet at `plan:pre` time).
 
 **Embed that command's output VERBATIM as the plan's `<vault_practices>` block — byte for byte, from `<vault_practices>` to `</vault_practices>`.** Do not rename a field, re-order an entry, add or move a fence marker, re-wrap, summarise, or omit anything. The CLI already emits the finished block in the exact shape `docs/practices-format.md` defines: the opening notice, the scoped and global groups, the documented field names, and the whole-entry external-content fencing. It ALWAYS includes every practice the matcher returns with `scope: global`, labeled global — that is now guaranteed by the command rather than left to a plan-time judgement call (D-03), and it is never yours to drop one. It also emits the correct degraded one-line state on its own when there is nothing to show, so the block is never silently absent.
 
@@ -65,3 +65,48 @@ Write the block using exactly one of these three degraded one-line states — ve
 - Matcher ran, zero matched AND zero global practices returned: `Practices checked — none apply to this plan's files.` (D-13)
 - Matcher ran, no practices directory found in any fetched vault tier: `Practices checked — none found in the vault.` (D-14)
 - The matcher CLI call itself failed: planning continues regardless — this is advisory, not a blocker, mirroring the vault fetch step's own skip-on-error discipline — and the block carries `Practices could not be checked: <reason>.` (D-15)
+
+### Frontmatter trace ledger — after the plan graph, then fill
+
+**When:** last. Write the plans, run `pp_run query phase-plan-index "$PHASE"`, write back each plan's
+computed `wave` / `serial_group`, and apply any `merge_candidates` merge FIRST (`planner-plan-graph.md`).
+A merge changes a plan's `files_modified` and its identifier, and the ledger's subject list and practice
+set are derived from exactly those, so a ledger written before the plan graph settled describes a
+different plan. Only then, for each final plan, re-run the `--block` match if its `files_modified`
+changed, and add the ledger.
+
+**What to run:** `pp_run vault trace scaffold --stage plan --plan <plan-id> <files_modified...>`. Put the
+returned block in that plan's **frontmatter**, under its top-level `vault:` key, exactly as emitted —
+after `title:`, `wave`, `serial_group` and `chain_reason`, the same verbatim discipline the body block
+gets. A later `pp_run frontmatter set` on the plan keeps the ledger's lines as they are.
+
+**The `<plan-id>` is not free-form.** The plan identifier must be the plan's phase-and-number identifier, exactly the prefix of its artifact filename (for example 04-02), not a bare plan number, a task label or a slug. The command refuses any other shape outright rather than emitting a block you would have to redo.
+
+**What you fill, and only this:** per practice entry, the `status`, a one-line `reason`, and `tasks` —
+the task ids in this plan the practice is expected to govern. **The pin and the practice list are not
+yours to write.** Never type a `ref`, a `resolvedSha` or a digest, and never re-derive, re-order or trim
+the practice list: those are the fields the command exists to produce.
+
+**The three status words** are the existing vocabulary and are never re-coined:
+- `applied` — the practice governs the work and will be followed.
+- `not-applicable` — the practice was considered and ruled out for this plan.
+- `deviated` — the practice loses to something that outranks it, and the `reason` says to what.
+
+**A ruled-out practice gets a line, not silence.** A practice you considered and set aside is recorded
+`not-applicable` **with its reason**. That auditable ruled-out set is the point of the ledger: an
+omitted entry and a never-considered one look the same to every later reader.
+
+**The ledger and the body block have different jobs.** The `vault:` ledger is the **audit record**: our
+keys, our values, one bounded client-authored token (the practice `id`), and **no client prose** — YAML
+has no fence, so practice text copied into frontmatter has left the fence. The `<vault_practices>` body
+block is the **reference content** the executor re-anchors against per task; it **keeps its fences**.
+
+**Degraded or absent vault:** the ledger is still obtained and embedded, carrying the degraded state and
+its reason — a degraded run must leave an artifact that says so, not one indistinguishable from a
+project that was never vault-enabled. The three degraded one-line states above still govern the body
+block. The `override` field is always `null`; it is never yours to write.
+
+**Re-run rule:** if a plan-checker revision or `plan_bounce` later changes that plan's `files_modified`,
+re-run the scaffold and replace the block, exactly as the body block is re-run.
+
+**Shape:** `docs/vault-trace-format.md` is the contract for the block's fields — read the shape there.

package/pp-core/references/planning-config.md

@@ -277,7 +277,7 @@ Set via `workflow.*` namespace in config.json (e.g., `"workflow": { "research":
 
 ### Phase Fields
 
-Set via `phase.*` namespace in config.json. The tier is a preset over the eight `workflow.*` gate booleans (`research`, `pattern_mapper`, `plan_check`, `verifier`, `nyquist_validation`, `code_review`, `post_planning_gaps`, `security_enforcement`); an explicit `false` for one of them still wins.
+Set via `phase.*` namespace in config.json. The tier is a preset over the nine `workflow.*` gate booleans (`research`, `pattern_mapper`, `plan_check`, `verifier`, `nyquist_validation`, `code_review`, `post_planning_gaps`, `security_enforcement`, `vault_review`); an explicit `false` for one of them still wins.
 
 | Key | Type | Default | Allowed Values | Description |
 |-----|------|---------|----------------|-------------|

package/pp-core/templates/practices/README.md

@@ -21,14 +21,23 @@ folder and has two parts:
    frontmatter. This is what a person (or an AI agent quoting the practice
    back to a person) reads.
 
-A malformed practice file is never treated as a fatal error. If a file is
-missing a required field, or a field has an unrecognized value, it is simply
+When practices are gathered for planning, a malformed file is not fatal. If a
+file is missing a required field, or a field has an unrecognized value, it is
 skipped with a plain-English warning explaining what was wrong — the rest of
-your practices still load normally.
+your practices still load normally. And if a file is *understandable but not
+entirely recognized* — say it uses a key your pp-core version is too old to
+know about — it is not skipped at all: it still applies, and a warning names
+what was not understood.
 
-## The five frontmatter keys
+**The vault audit is stricter, and it blocks.** Do not read the paragraph above
+as the whole story before merging into a shared vault — see *What happens if a
+file is malformed* at the end of this page. `/pp-vault-promote` is stricter too:
+it refuses a file the planner would only warn about.
 
-Every practice file's frontmatter needs exactly these five keys:
+## The seven frontmatter keys
+
+Every practice file's frontmatter needs the first five keys below. The last
+two, `check` and `enforced-by`, are optional.
 
 | Key | Meaning |
 |-----|---------|
@@ -37,6 +46,8 @@ Every practice file's frontmatter needs exactly these five keys:
 | `severity` | How strongly this practice should be enforced: `critical`, `warning`, or `info`. This is the same three-level scale used elsewhere in code review. |
 | `applies-to` | A list of file-path patterns (globs) this practice applies to, e.g. `src/**/*.ts`. **Required when `scope: scoped`. Must be left out entirely when `scope: global`.** |
 | `schemaVersion` | Always `1` for now. This lets a future pp-core version recognize practice files written for an older or newer format. |
+| `check` | *Optional.* A small block declaring how this practice can be checked **mechanically** against a change set: which files to look at, and what text must or must not appear in them. Its file patterns use exactly the same glob syntax as `applies-to` — the "Supported glob syntax" table below is the one and only description of that syntax. See "The `check:` block". |
+| `enforced-by` | *Optional.* The name of a stock analyzer rule (or a list of them, at most `ENFORCED_BY_COUNT_CAP`) that already enforces this practice in your own build, e.g. `enforced-by: VSTHRD002`. pp-core records this claim and runs nothing; a practice whose only evidence is `enforced-by:` has not been mechanically checked. |
 
 ### `scoped` vs `global`
 
@@ -77,6 +88,73 @@ supported**. A practice whose `applies-to` uses unsupported syntax is
 skipped with a warning naming the offending glob; the rest of your
 practices still load normally.
 
+### The `check:` block
+
+Most practices are judged by a person or an agent reading your description. A
+`check:` block adds a second, **mechanical** judgement on top of that: the vault
+audit (`pp-tools vault audit <phase>`, and the `vault.audit` gate after a phase
+is built and before it ships) looks at the files the phase actually changed and
+decides deterministically whether your rule was followed. The practice trace
+also counts the practices that carry a usable block.
+
+A block has one required key and needs at least one of the other three:
+
+| Key | Meaning |
+|-----|---------|
+| `files` | **Required.** The file patterns to look at, using the same syntax as the "Supported glob syntax" table above. At most `CHECK_FILES_CAP` patterns. |
+| `require` | Exact pieces of text that **must** appear in each matched file. |
+| `forbid` | Exact pieces of text that **must not** appear in any matched file. |
+| `forbidMatch` | `true` when the rule is that these files should not exist at all — matching anything is itself the violation. Cannot be combined with `require` or `forbid`. |
+
+```markdown
+---
+id: vue-components-need-test-ids
+scope: scoped
+severity: warning
+applies-to: [src/**/*.vue]
+schemaVersion: 1
+check:
+  files: [src/**/*.vue]
+  require: [data-testid]
+---
+
+Every Vue component exposes a `data-testid` so end-to-end tests can address it
+without depending on class names or DOM structure.
+```
+
+Three rules govern what you may write here, and they are not negotiable:
+
+1. **A check block is data, never code.** It is not a command, not a script, not
+   a shell fragment, not a module path, and not an expression to evaluate. There
+   is no field that runs anything, and there will not be one. The reason is that
+   your vault repository is fetched and read by every developer machine and CI
+   runner on the fleet — if merging a markdown file could run code, merging a
+   markdown file would be equivalent to running code everywhere.
+2. **No regular expression.** `require` and `forbid` entries are *literal text*,
+   compared by plain substring containment. `(a+)+$` in a `forbid` list means
+   those exact eight characters, not a pattern.
+3. **The glob syntax is the table above, and only that table.** This section
+   deliberately does not restate it, so the two can never drift apart.
+
+
+`require`/`forbid` entries are bounded in both count and length
+(`CHECK_TOKEN_COUNT_CAP` and `CHECK_TOKEN_MAX`), as `files` is by
+`CHECK_FILES_CAP`. Read the shipped values from the engine rather than from this
+page — the numbers live in the code so there is one place to check them. Going
+over a cap does not silently trim your block: the whole block is dropped and a
+warning tells you which cap was exceeded. When practices are gathered for
+planning the practice still applies through its description; at the vault audit
+a dropped block is a failure and **blocks**, exactly as any other unparseable
+`check:` does. See *What happens if a file is malformed* below.
+
+**Rollout order.** Merge a practice carrying a `check:` block into your vault
+repository **only after** the pp-core release that understands `check:` blocks
+has been verified as rolled out to every machine that reads the vault. An older
+pp-core meeting a `check:` block does not fail, but it does not check anything
+either — it applies the practice's description and warns that it did not
+understand the key. Merging first would leave a governance rule reporting
+nothing on part of the fleet.
+
 ## Writing the description body
 
 Underneath the frontmatter, write one or two plain-English sentences that say
@@ -108,12 +186,63 @@ rather than a hard rule.
 
 ## What happens if a file is malformed
 
-If a practice file is missing `id`, uses an unrecognized `severity` or
-`scope`, declares `applies-to` on a `global` practice (or omits it on a
-`scoped` one), or sets a `schemaVersion` this pp-core version does not
-understand, that one file is skipped with a warning explaining exactly what
-was wrong. Every other well-formed practice file still loads and is applied
-normally — one bad file never breaks the run.
+**Read this before you merge anything into a shared vault.** A malformed file
+behaves differently in the two places pp-core reads your vault, and the
+difference is the difference between a warning and a stopped build.
+
+**When practices are gathered for planning**, a malformed file is tolerated.
+That is the behaviour described below.
+
+**When the vault audit runs**, it is not. The audit is a *blocking* gate at both
+`verify:post` and `ship:pre`: a file it cannot load is a failure, an unparseable
+`check:` block is a failure, and any failure stops the run. It is deliberately
+fail-closed — a governance rule that quietly does nothing is worse than no rule
+at all — so it refuses rather than skipping past something it could not read.
+
+**The practical consequence: one malformed file merged into a shared vault stops
+the build on every machine that fetches it, not just yours.** Use
+`/pp-vault-promote`, which refuses every case below before it reaches the vault,
+rather than committing a practice by hand.
+
+### Skipped
+
+A practice file is skipped when it is missing `id`, has an `id` that does not
+match its filename, uses an unrecognized `severity` or `scope`, declares
+`applies-to` on a `global` practice (or omits it on a `scoped` one), uses
+unsupported glob syntax, or sets a malformed `schemaVersion`.
+
+*Gathering for planning:* that one file is skipped with a warning explaining
+exactly what was wrong, and every other well-formed practice file still loads
+and is applied normally.
+
+*The audit:* the skipped file is reported as a failure and **blocks**.
+
+### Degraded
+
+A practice file is degraded when it is structurally fine but uses something this
+pp-core version does not recognize — a frontmatter key it has never heard of
+(including a typo like `applies_to`), a `schemaVersion` newer than it supports,
+or an `enforced-by:` value it cannot use. It is **not** skipped: it loads, its
+description still applies exactly as written, and a warning names what was not
+understood. pp-core never drops a practice merely because part of it was
+written for a newer engine.
+
+*The audit:* a degraded file whose problem is only an unknown key, a newer
+`schemaVersion` or an unusable `enforced-by:` value does not block. **A broken
+`check:` block is not in this category** — see below.
+
+### A `check:` block that will not parse
+
+This is the case authors most often expect to be lenient, and it is the least
+lenient of the three. A `check:` block that breaks any of the rules above —
+including going over `CHECK_FILES_CAP`, `CHECK_TOKEN_COUNT_CAP` or
+`CHECK_TOKEN_MAX` — is dropped whole.
+
+*Gathering for planning:* the practice still applies through its description, a
+warning names the defect, and the practice is not counted as carrying a check.
+
+*The audit:* an unparseable `check:` block is a failure and **blocks**. A
+dropped block must never read as a check that passed.
 
 ## Getting started
 

package/pp-core/templates/project-charter.md

@@ -0,0 +1,226 @@
+# Project Charter Template
+
+Template for `.planning/discovery/PROJECT-CHARTER.md`, the document every stakeholder signs at the end
+of a Discovery Sprint.
+
+**Purpose:** one short, fixed-shape document that states what will be built, why, for whom, how it will
+be delivered and on what conditions, so that sign-off is a decision on the same questions in the same
+order for every engagement. It summarises the thirteen session files; it does not replace them.
+
+**When:** after Session 13 (wrap-up and Go / No-Go), before `/pp-discovery-to-build`.
+
+**Shape is fixed.** Every charter has the same 14 numbered sections in the same order, with the same
+headings and the same table columns. A section with nothing to report stays in place and says so; it is
+never dropped, merged or renumbered. That is what lets a reader compare two charters side by side.
+
+---
+
+## File Template
+
+```markdown
+---
+document: project-charter
+project: [Project name]
+client: [Client name]
+version: [1.0]
+status: [Draft | For sign-off | Signed | Signed with conditions | Rejected]
+date: [YYYY-MM-DD]
+discovery_sessions_completed: [N]/13
+go_no_go: [Go | Go with conditions | No-Go]
+---
+
+# [Project name] — Project Charter
+
+> [One sentence: what this project delivers, for whom, and why now.]
+
+| Document control | |
+|---|---|
+| Client | [Client name] |
+| Version / status | [1.0] · [Draft] |
+| Date | [YYYY-MM-DD] |
+| Prepared by | [Name, role] |
+| Based on | Discovery Sprint sessions 1–13, completed [YYYY-MM-DD] |
+
+---
+
+## 1. Purpose and background
+
+[Two to four sentences: the business problem and why it matters now.]
+
+**Top pain points today**
+
+| # | Pain point | Who is affected | Impact |
+|---|---|---|---|
+| 1 | | | |
+
+## 2. Objectives and success measures
+
+| # | Objective | KPI | Baseline | Target | Measured by |
+|---|---|---|---|---|---|
+| O-1 | | | | | |
+
+## 3. Scope
+
+**In scope (MVP)**
+
+| EPIC | Title | Priority |
+|---|---|---|
+| | | |
+
+**Out of scope**
+
+- [Item] — [reason or later release]
+
+**Requirements:** [N] functional, [N] non-functional, [N] business rules, as registered in
+`_requirements.md`.
+
+## 4. Stakeholders and users
+
+| Stakeholder | Role | Decision authority | Involvement |
+|---|---|---|---|
+| | | | |
+
+| Persona | Description | Main goal |
+|---|---|---|
+| | | |
+
+## 5. Solution overview
+
+[Two to four sentences: the shape of the solution.]
+
+| Layer | Choice | Decision |
+|---|---|---|
+| Frontend | | [D-05-n] |
+| Backend | | |
+| Data | | |
+| Hosting | | |
+| Identity | | |
+
+**Integrations**
+
+| System | Direction | Purpose |
+|---|---|---|
+| | | |
+
+**Security and compliance:** [data classification, applicable regulations, availability target, in two to
+four lines.]
+
+## 6. Quality and acceptance
+
+| Gate | Criterion |
+|---|---|
+| UAT sign-off | [criteria] — approved by [role] |
+| Go-live readiness | [criteria] |
+
+## 7. Delivery plan
+
+| Milestone | Target date | Included EPICs | Exit criteria |
+|---|---|---|---|
+| [v1.0 — MVP] | | | |
+
+**Build order:** [EPIC order and why.]
+
+## 8. Team and governance
+
+| Role | Name / party | Responsibility |
+|---|---|---|
+| | | |
+
+**Scope changes are approved by:** [role]. **Progress is reported:** [cadence, format].
+
+## 9. Budget, constraints and assumptions
+
+| Type | Item | Source |
+|---|---|---|
+| Budget | [amount or "Not decided in Discovery — OI-n"] | |
+| Constraint | | |
+| Assumption | | |
+
+## 10. Risks
+
+| # | Risk | Likelihood | Impact | Mitigation | Owner |
+|---|---|---|---|---|---|
+| R-1 | | | | | |
+
+## 11. Open items
+
+| ID | Item | Must resolve before build? | Owner | Target date |
+|---|---|---|---|---|
+| OI-1 | | | | |
+
+## 12. Go / No-Go recommendation
+
+| Criterion | Status | Note |
+|---|---|---|
+| Business requirements clarity | [Green / Amber / Red] | |
+| Technical architecture feasibility | | |
+| Security and compliance readiness | | |
+| Integration dependencies resolved | | |
+| Team and budget availability | | |
+| Timeline confidence | | |
+| Stakeholder alignment | | |
+| **Overall recommendation** | **[Go / Go with conditions / No-Go]** | |
+
+**Conditions:** [each condition attached to a Go, or "None".]
+
+## 13. Key decisions
+
+| ID | Decision | Rationale | Owner |
+|---|---|---|---|
+| D-01-1 | | | |
+
+## 14. Sign-off
+
+By signing, each party agrees that sections 1–13 describe the project to be built, subject to the
+conditions stated.
+
+| Role | Name | Decision | Conditions | Date | Signature |
+|---|---|---|---|---|---|
+| [Sponsor] | | [Approve / Approve with conditions / Reject] | | | |
+| [Product owner] | | | | | |
+| [Delivery lead] | | | | | |
+
+---
+
+**Source files:** `.planning/discovery/session-01.md` … `session-13.md`, `_requirements.md`.
+```
+
+---
+
+## Where each section comes from
+
+Fill every section from the session tables below and nothing else. The session files are the source of
+truth; the charter only condenses them.
+
+| § | Section | Source (file § table) |
+|---|---|---|
+| — | Front matter, document control | `_progress.md` (completion dates); Session 1 § Stakeholder Register (client) |
+| 1 | Purpose and background | Session 1 § Business Vision Summary; Session 2 § Pain Points Register (top 3–5 by impact) |
+| 2 | Objectives and success measures | Session 3 § Business Objectives |
+| 3 | Scope | Session 3 § MVP Scope Boundary and § EPIC Register; counts from the roll-up block in `_requirements.md` |
+| 4 | Stakeholders and users | Session 1 § Stakeholder Register; Session 4 § Refined Personas (else Session 2 § User Personas) |
+| 5 | Solution overview | Session 5 § Technology Stack Decisions and § Architecture Decision Records; Session 8 § Integration Design Register; Session 6 § Data Classification Matrix, § Compliance Requirements Register, § Availability and DR Targets; Session 7 § IdP Integration Design |
+| 6 | Quality and acceptance | Session 9 § UAT Process and § Quality Gates; Session 10 § Go-Live Readiness Checklist |
+| 7 | Delivery plan | Session 11 § Milestone Plan, § Project Timeline, § EPIC Build Order |
+| 8 | Team and governance | Session 12 § Team Structure and § Governance Structure; reporting cadence from Session 12 topic "Communication and reporting" |
+| 9 | Budget, constraints and assumptions | Session 1 § Constraints and Risks Register; any `[needs-business-input]` item still parked |
+| 10 | Risks | Session 11 § Risk Register, plus open risks from Session 1 § Constraints and Risks Register |
+| 11 | Open items | Session 13 § Open Items Register |
+| 12 | Go / No-Go recommendation | Session 13 § Go / No-Go Assessment (copied as recorded, not re-scored) |
+| 13 | Key decisions | § Key Decisions of every session — only decisions that change scope, architecture, cost or timeline |
+| 14 | Sign-off | Session 1 § Stakeholder Register — every stakeholder with approval authority gets a row |
+
+## Fill rules
+
+- **Never invent.** Every statement traces to a session table above. A value Discovery did not settle is
+  written as `Not decided in Discovery — OI-n`, and that item appears in § 11 Open items.
+- **Keep the IDs.** Requirement, EPIC, decision (`D-<ss>-<n>`), risk and open-item IDs are copied
+  exactly as the session files write them, so every line can be traced back.
+- **Condense, don't copy.** Tables carry the headline rows; the full detail stays in the session files.
+  Aim for a charter that reads in about fifteen minutes.
+- **Fixed shape.** Keep all 14 sections, their numbers, headings and table columns. An empty section
+  says `None identified in Discovery.`
+- **Go / No-Go is recorded, not re-judged.** § 12 copies Session 13's assessment and conditions verbatim.
+- **Status follows the signatures.** `Draft` while being written, `For sign-off` once circulated,
+  `Signed` when every § 14 row says Approve, `Signed with conditions` when any row approves with
+  conditions, `Rejected` when any row rejects. A new version resets the status to `Draft`.

package/pp-core/workflows/add-tests.md

@@ -212,6 +212,10 @@ If "Cherry-pick": ask user which tests to include.
 If "Adjust plan": apply changes and re-present.
 </step>
 
+<step name="vault_door_gate">
+Before any test file is written, Read and execute `pp-core/workflows/execute-phase/steps/vault-door-gate.md`; a stop ends this run with no test written.
+</step>
+
 <step name="execute_tdd_generation">
 For each approved TDD test:
 

package/pp-core/workflows/audit-fix.md

@@ -92,6 +92,8 @@ final output — do not proceed to fixing.
 </step>
 
 <step name="fix-loop">
+Before the first fix, Read and execute `pp-core/workflows/execute-phase/steps/vault-door-gate.md`; a stop ends this run with no fix applied.
+
 For each **auto-fixable** finding (up to `--max`, ordered by severity desc):
 
 **a. Spawn executor agent** (runs in a subagent — no output until it returns, ~1–5 min; expected, not a freeze)**:**

package/pp-core/workflows/audit-milestone.md

@@ -146,7 +146,7 @@ For each REQ-ID, determine status using all three sources:
 Skip if the Nyquist capability is inactive.
 
 ```bash
-VERIFY_POST_HOOKS_JSON=$(pp_run loop render-hooks verify:post --raw)
+VERIFY_POST_HOOKS_JSON=$(pp_run loop render-hooks verify:post --raw) || exit 1
 ```
 
 Resolve active step hooks from `VERIFY_POST_HOOKS_JSON` where `kind == "step"` and `ref.skill == "validate-phase"`.

package/pp-core/workflows/autonomous.md

@@ -273,7 +273,7 @@ Resolve active `plan:pre` hooks:
 
 ```bash
 UI_SPEC_FILE=$(ls "${PHASE_DIR}"/*-UI-SPEC.md 2>/dev/null | head -1)
-HOOKS_JSON=$(pp_run loop render-hooks plan:pre --raw --phase "${PHASE_NUM}")
+HOOKS_JSON=$(pp_run loop render-hooks plan:pre --raw --phase "${PHASE_NUM}") || exit 1
 ```
 
 Read the `activeHooks` array directly from `HOOKS_JSON` (in-context — do NOT invoke a shell pipeline). **Compute the active UI step hooks** = entries from `activeHooks` where `kind == "step"` and `ref.skill` is set. **If there are NO active step hooks → skip silently to 3b.** (This covers `workflow.ui_phase=false` — including configurations where only a gate-only entry is present, e.g. `ui_phase=false` + `ui_safety_gate=true` produces `activeHooks=[{kind:"gate"}]`. Autonomous never runs the plan:pre gate — it is always pipeline mode — so a gate-only active set is equivalent to no active step and is silently skipped here. This matches OLD §3a.5 behaviour.)
@@ -406,7 +406,7 @@ Auto-invoke code review and fix chain. Autonomous mode chains both review and fi
 
 **Capability dispatch:**
 ```bash
-EXECUTE_POST_HOOKS_JSON=$(pp_run loop render-hooks execute:post --raw --phase "${PHASE_NUM}")
+EXECUTE_POST_HOOKS_JSON=$(pp_run loop render-hooks execute:post --raw --phase "${PHASE_NUM}") || exit 1
 ```
 
 Resolve active step hooks from `EXECUTE_POST_HOOKS_JSON` where `kind == "step"` and `ref.skill == "code-review"`.
@@ -481,7 +481,7 @@ Resolve the active post-verification hooks and the UI-SPEC gate:
 
 ```bash
 UI_SPEC_FILE=$(ls "${PHASE_DIR}"/*-UI-SPEC.md 2>/dev/null | head -1)
-HOOKS_JSON=$(pp_run loop render-hooks verify:post --raw --phase "${PHASE_NUM}")
+HOOKS_JSON=$(pp_run loop render-hooks verify:post --raw --phase "${PHASE_NUM}") || exit 1
 ```
 
 Read the `activeHooks` array directly from the `HOOKS_JSON` value already in context (do not invoke a shell `jq` pipeline — parse as the JSON object it is). **If `activeHooks` is empty or absent:** skip silently to the iterate step.

package/pp-core/workflows/check-todos.md

@@ -127,7 +127,7 @@ Use AskUserQuestion:
 </step>
 
 <step name="execute_action">
-**Work on it now:**
+**Work on it now:** first Read and execute `pp-core/workflows/execute-phase/steps/vault-door-gate.md`; a stop leaves the todo pending and ends here. Then:
 ```bash
 mv ".planning/todos/pending/[filename]" ".planning/todos/completed/"
 ```

package/pp-core/workflows/code-review-fix.md

@@ -77,7 +77,7 @@ FIX_REPORT_PATH="${PHASE_DIR}/${PADDED_PHASE}-REVIEW-FIX.md"
 Check if code review is active via the capability registry:
 
 ```bash
-EXECUTE_POST_HOOKS_JSON=$(pp_run loop render-hooks execute:post --raw)
+EXECUTE_POST_HOOKS_JSON=$(pp_run loop render-hooks execute:post --raw) || exit 1
 ```
 
 Resolve active step hooks from `EXECUTE_POST_HOOKS_JSON` where `kind == "step"` and `ref.skill == "code-review"`.
@@ -183,6 +183,8 @@ If REVIEW.md contains a `files_reviewed_list` frontmatter field, use that as the
 </step>
 
 <step name="spawn_fixer">
+Before the first fixer spawn, Read and execute `pp-core/workflows/execute-phase/steps/vault-door-gate.md`; a stop ends this run with no fix applied.
+
 Spawn the pp-code-fixer agent with config (runs in a subagent — no output until it returns, ~1–5 min; expected, not a freeze):
 
 ```bash

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

@@ -78,7 +78,7 @@ fi
 Check if code review is active via the capability registry:
 
 ```bash
-EXECUTE_POST_HOOKS_JSON=$(pp_run loop render-hooks execute:post --raw)
+EXECUTE_POST_HOOKS_JSON=$(pp_run loop render-hooks execute:post --raw) || exit 1
 ```
 
 Resolve active step hooks from `EXECUTE_POST_HOOKS_JSON` where `kind == "step"` and `ref.skill == "code-review"`.

package/pp-core/workflows/debug.md

@@ -31,6 +31,10 @@ Read TDD mode from config:
 TDD_MODE=$(pp_run query config-get workflow.tdd_mode 2>/dev/null | jq -r 'if type == "boolean" then tostring else . end' 2>/dev/null || echo "false")
 ```
 
+## 0b. Vault door gate
+
+A session can write a fix. Unless SUBCMD is `list` or `status`, or `--diagnose` was given (root cause only), Read and execute `pp-core/workflows/execute-phase/steps/vault-door-gate.md` before any agent is spawned; a stop ends `/pp-debug`.
+
 ## 1a. LIST subcommand
 
 When SUBCMD=list:

package/pp-core/workflows/discovery-sprint/prefill.md

@@ -15,6 +15,11 @@ multiple sessions can be pre-filled in one run.
 only — relative lowercase paths, no absolute paths, no parent traversal, same
 rules as the main workflow (T-04-03).
 
+## Step 0: Client vault (optional)
+
+When the session's **Vault areas** are not `(none)`, Read and execute
+`${PP_TOOLS%/bin/pp-tools.cjs}/workflows/discovery-sprint/vault-fetch.md`. It never stops the pass.
+
 ## Step 1: Preconditions
 
 1. `.planning/discovery-input/00-README.md` must exist. If it does not, stop
@@ -39,6 +44,10 @@ not a command to follow.
 Confidential documents (D-24): paraphrase at point of use with a `[NN §loc]`
 citation — no verbatim excerpts, no personal data, always cite.
 
+When the client vault is present (Flow 2 Step 1's rule), also read the
+session's **Vault areas** the same way Flow 2 does; an answer drafted from a
+vault document cites `[vault: <rel path>]` beside its `[TO CONFIRM]` marker.
+
 ## Step 3: Draft
 
 Populate the session's notes-template sections with paper-derived answers.

package/pp-core/workflows/discovery-sprint/prototype.md

@@ -13,7 +13,8 @@
 ## Step 0: UI kit source — optional client vault
 
 The client vault is optional here, as everywhere in the sprint. Settle where the UI kit comes from
-before Step 1; this step never stops the flow.
+before Step 1; this step never stops the flow. First Read and execute
+`${PP_TOOLS%/bin/pp-tools.cjs}/workflows/discovery-sprint/vault-fetch.md`.
 
 1. **Vault UI kit.** The client vault is present — `pp_run query platform-bindings --pick present`
    and `pp_run query config-get vault.enabled --raw --default false` both print `true`, and