@pareto4/pp-core 1.12.1 → 1.17.1

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

@@ -21,14 +21,22 @@ 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.
 
-Every practice file's frontmatter needs exactly these five keys:
+## The six frontmatter keys
+
+Every practice file's frontmatter needs the first five keys below. The sixth,
+`check`, is optional.
 
 | Key | Meaning |
 |-----|---------|
@@ -37,6 +45,7 @@ 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". |
 
 ### `scoped` vs `global`
 
@@ -77,6 +86,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: pp-core
+looks at the files a change actually touched and decides deterministically
+whether your rule was followed.
+
+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.
+
+The full reasoning is recorded in
+`docs/adr/71924-declarative-check-blocks.md`.
+
+`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 +184,62 @@ 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 an invalid `check:` block before it reaches
+the vault, rather than committing one 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`), or a `schemaVersion` newer than it
+supports. 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 or a newer
+`schemaVersion` 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,
+and a warning names the defect.
+
+*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

@@ -67,6 +67,47 @@ Present banner:
 ```
 </step>
 
+<step name="vault_admission_gate">
+Vault admission and load gate (D-11, D-12, D-28): runs before a test is written or committed. A config the gate cannot
+read halts here with the bindings present (D-05); without bindings, or with `vault.enabled` false,
+nothing below prints or writes anything (D-13).
+
+```bash
+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 the fence printed no `VAULT_ADMIT=on` line** (`off` and `inert` print nothing): skip the rest of this block silently. Otherwise run the load
+gate on the `execute:pre` payload, filtered in the fence to the `vault` and `vault-practices`
+capabilities (D-30):
+
+```bash
+AT_EXECUTE_PRE_HOOKS_JSON=$(pp_run loop render-hooks execute:pre --raw | node -e "const d=require('fs').readFileSync(0,'utf-8');try{const j=JSON.parse(d);j.activeHooks=(j.activeHooks||[]).filter((x)=>x&&(x.capId==='vault'||x.capId==='vault-practices'));process.stdout.write(JSON.stringify(j));}catch{process.stdout.write('');}")
+printf '%s' "$AT_EXECUTE_PRE_HOOKS_JSON" | node -e "let h=[];try{h=JSON.parse(require('fs').readFileSync(0,'utf-8')).activeHooks||[]}catch{}console.log('AT_EXECUTE_PRE_HOOKS_JSON='+JSON.stringify({activeHooks:h}))"
+```
+
+Set `VAULT_FETCH_HOOKS_JSON=$AT_EXECUTE_PRE_HOOKS_JSON`, then Read and execute
+`pp-core/workflows/execute-phase/steps/vault-fetch.md` (hook mode). Then, in the
+`AT_EXECUTE_PRE_HOOKS_JSON=` line that fence printed, find active entries where `kind == "gate"` and `check.query ==
+"vault.status"`; if none, skip silently. Otherwise set `GATE_POINT=execute:pre` and
+`GATE_HOOKS_JSON=$AT_EXECUTE_PRE_HOOKS_JSON`, leave `GATE_POSITIONAL_ARG`, `GATE_WS` and
+`GATE_STAGE` empty, then Read and follow `pp-core/workflows/execute-phase/steps/check-query-gate.md`;
+it owns the halt.
+
+Then record the door's START anchor, before the first test file is written (`execute_tdd_generation`) (D-31):
+
+```bash
+pp_run vault door-record --begin --door add-tests --raw
+```
+
+It records HEAD in `.planning/.vault-door-starts.json`, where the record step reads it back: a shell
+variable would not survive into that later step, and the agent never types a sha. It prints nothing
+and writes nothing unless `vault admission` answers `on`.
+Take `padded_phase` from the same init JSON for the record below.
+</step>
+
 <step name="analyze_implementation">
 Extract the list of files modified by the phase from SUMMARY.md ("Files Changed" or equivalent section).
 
@@ -311,6 +352,20 @@ git add {test files}
 git commit -m "test(phase-${phase_number}): add unit and E2E tests from add-tests command"
 ```
 
+Vault door record (D-12): after the door's last source commit, set `DOOR_DIR="${phase_dir}"`,
+`DOOR_PADDED="${padded_phase}"` and `DOOR_PHASE="${phase_number}"`, then run:
+
+```bash
+DOOR_RUN=$(date -u +%Y%m%dT%H%M%SZ)
+pp_run vault door-record --door add-tests --artifact "${DOOR_DIR}/${DOOR_PADDED}-door-${DOOR_RUN}-ADD-TESTS.md" --phase "$DOOR_PHASE" --raw
+```
+
+The verb writes a `## Vault Door Record` (mode, vault ref and sha, governing phase, the start `--begin`
+recorded and the end commit; the agent never types a sha) into a fresh per-run artifact, because it refuses a second record
+in one file (D-57) and a rewritten report would drop the earlier run's coverage (D-79). It prints
+nothing and writes nothing unless `vault admission` answers `on`. When it wrote the file and
+`commit_docs` is true, commit the `artifact` path it printed: `pp_run query commit "docs(phase-${phase_number}): vault door record for add-tests" --files "<that artifact>"`.
+
 Present next steps:
 
 ```

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

@@ -91,6 +91,48 @@ If `--dry-run` was specified, **stop here and exit**. The classification table i
 final output — do not proceed to fixing.
 </step>
 
+<step name="vault_admission_gate">
+Skipped under `--dry-run` (nothing is fixed).
+
+Vault admission and load gate (D-11, D-12, D-28): runs before any finding is fixed. A config the gate cannot
+read halts here with the bindings present (D-05); without bindings, or with `vault.enabled` false,
+nothing below prints or writes anything (D-13).
+
+```bash
+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 the fence printed no `VAULT_ADMIT=on` line** (`off` and `inert` print nothing): skip the rest of this block silently. Otherwise run the load
+gate on the `execute:pre` payload, filtered in the fence to the `vault` and `vault-practices`
+capabilities (D-30):
+
+```bash
+AF_EXECUTE_PRE_HOOKS_JSON=$(pp_run loop render-hooks execute:pre --raw | node -e "const d=require('fs').readFileSync(0,'utf-8');try{const j=JSON.parse(d);j.activeHooks=(j.activeHooks||[]).filter((x)=>x&&(x.capId==='vault'||x.capId==='vault-practices'));process.stdout.write(JSON.stringify(j));}catch{process.stdout.write('');}")
+printf '%s' "$AF_EXECUTE_PRE_HOOKS_JSON" | node -e "let h=[];try{h=JSON.parse(require('fs').readFileSync(0,'utf-8')).activeHooks||[]}catch{}console.log('AF_EXECUTE_PRE_HOOKS_JSON='+JSON.stringify({activeHooks:h}))"
+```
+
+Set `VAULT_FETCH_HOOKS_JSON=$AF_EXECUTE_PRE_HOOKS_JSON`, then Read and execute
+`pp-core/workflows/execute-phase/steps/vault-fetch.md` (hook mode). Then, in the
+`AF_EXECUTE_PRE_HOOKS_JSON=` line that fence printed, find active entries where `kind == "gate"` and `check.query ==
+"vault.status"`; if none, skip silently. Otherwise set `GATE_POINT=execute:pre` and
+`GATE_HOOKS_JSON=$AF_EXECUTE_PRE_HOOKS_JSON`, leave `GATE_POSITIONAL_ARG`, `GATE_WS` and
+`GATE_STAGE` empty, then Read and follow `pp-core/workflows/execute-phase/steps/check-query-gate.md`;
+it owns the halt.
+
+Then record the door's START anchor, before the first `pp-executor` spawn of the fix loop (D-31):
+
+```bash
+pp_run vault door-record --begin --door audit-fix --raw
+```
+
+It records HEAD in `.planning/.vault-door-starts.json`, where the record step reads it back: a shell
+variable would not survive into that later step, and the agent never types a sha. It prints nothing
+and writes nothing unless `vault admission` answers `on`.
+</step>
+
 <step name="fix-loop">
 For each **auto-fixable** finding (up to `--max`, ordered by severity desc):
 
@@ -140,6 +182,27 @@ must halt to avoid cascading issues. Remaining auto-fixable findings will appear
 report as `not-attempted`.
 </step>
 
+<step name="vault_door_record">
+After the loop, once for EACH phase directory whose findings were fixed in this run (the directory of
+the UAT or VERIFICATION file the finding came from): the record's range, from the start captured
+before the loop to HEAD now, covers every finding commit, and it lands in each fixed phase so that
+phase's gate sees it.
+
+Vault door record (D-12): after the door's last source commit, set `DOOR_DIR="<that phase directory>"`,
+`DOOR_PADDED="<its padded phase>"` and `DOOR_PHASE="<that phase directory>"`, then run:
+
+```bash
+DOOR_RUN=$(date -u +%Y%m%dT%H%M%SZ)
+pp_run vault door-record --door audit-fix --artifact "${DOOR_DIR}/${DOOR_PADDED}-door-${DOOR_RUN}-AUDIT-FIX.md" --phase "$DOOR_PHASE" --raw
+```
+
+The verb writes a `## Vault Door Record` (mode, vault ref and sha, governing phase, the start `--begin`
+recorded and the end commit; the agent never types a sha) into a fresh per-run artifact, because it refuses a second record
+in one file (D-57) and a rewritten report would drop the earlier run's coverage (D-79). It prints
+nothing and writes nothing unless `vault admission` answers `on`. When it wrote the file and
+`commit_docs` is true, commit the `artifact` path it printed: `pp_run query commit "docs: vault door record for audit-fix" --files "<that artifact>"`.
+</step>
+
 <step name="report">
 Present the final summary:
 

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) || exit 1
+VERIFY_POST_HOOKS_JSON=$(pp_run loop render-hooks verify:post --raw)
 ```
 
 Resolve active step hooks from `VERIFY_POST_HOOKS_JSON` where `kind == "step"` and `ref.skill == "validate-phase"`.