@pareto4/pp-core 1.19.0 → 1.21.0

package/pp-core/bin/pp-tools.cjs

@@ -64,6 +64,19 @@
  *                                      Returns JSON { valid, errors[], slots: {role,capability,outcome} | null }
  *                                      --pick valid  Emit bare boolean (for workflow boolean checks)
  *
+ * Timeline (Phase 35):
+ *   timeline start <role> <phase>      Append a run record before an Agent() spawn; prints the run id
+ *     [--plan P] [--agent A] [--model M] [--source S]
+ *   timeline end <role> <phase> <outcome>  Close the most recent open run of that role (and plan)
+ *     [--plan P] [--id ID]
+ *   timeline summary <phase> [--banner]    Fold a phase's runs: wall-clock, agent time, longest
+ *
+ * Ceremony (Phase 37):
+ *   ceremony classify <phase> [--full] [--research] [--skip-research] [--skip-verify] [--write]
+ *                                      Classify a phase (trust boundary, codebase to match, single-concern), print the
+ *                                      verdict table; --write records it as {padded}-CEREMONY.md
+ *   ceremony get <phase>               Read the recorded verdict; full when none is recorded
+ *
  * Drift Guard (ADR-22):
  *   drift-guard authority                Resolve effective source-grounding authority
  *                                        (reads plan_review.source_grounding_authority + intel.enabled from config)
@@ -177,7 +190,7 @@
  *   learnings delete <id>                Delete a learning by ID
  *
  * Loop Extension Point Queries (ADR-857 phase 3c):
- *   loop render-hooks <point>            Resolve + render active Capability hooks at a loop point
+ *   loop render-hooks <point> [--phase <N>]  Resolve + render active Capability hooks at a loop point
  *                                        Returns JSON envelope { point, activeHooks, rendered }
  *                                        Valid points: discuss:pre/post, plan:pre/post,
  *                                        execute:pre/wave:pre/wave:post/post, verify:pre/post, ship:pre/post
@@ -212,6 +225,7 @@ const roadmap = require('./lib/roadmap.cjs');
 const verify = require('./lib/verify.cjs');
 const config = require('./lib/config.cjs');
 const platformBindings = require('./lib/platform-bindings.cjs');
+const timeline = require('./lib/timeline.cjs');
 const composeBindings = require('./lib/compose-bindings.cjs');
 const initContract = require('./lib/init-contract.cjs');
 const initInteractive = require('./lib/init-interactive.cjs');
@@ -529,9 +543,9 @@ async function main() {
     'current-timestamp, detect-custom-files, discovery, docs-init, drift-guard, effort, extract-messages, find-phase, ' +
     'from-gsd2, frontmatter, gap-analysis, generate-claude-md, generate-claude-profile, ' +
     'generate-client-context, generate-dev-preferences, generate-slug, graphify, history-digest, init, init-contract, intel, ' +
-    'capability, classify-confidence, git, learnings, list-todos, loop, milestone, package-legitimacy, phase, phase-plan-index, phases, platform-bindings, platform-latest-tag, profile-questionnaire, ' +
+    'capability, ceremony, classify-confidence, git, learnings, list-todos, loop, milestone, package-legitimacy, phase, phase-plan-index, phases, platform-bindings, platform-latest-tag, profile-questionnaire, ' +
     'profile-sample, progress, prompt-budget, requirements, research-plan, research-store, resolve-granularity, resolve-model, roadmap, scaffold, state, ' +
-    'task, template, user-story, validate, validate-bindings, verify, verify-path-exists, verify-summary, workstream, worktree\n\n' +
+    'task, template, timeline, user-story, validate, validate-bindings, verify, verify-path-exists, verify-summary, workstream, worktree\n\n' +
     'Global flags:\n' +
     '  --raw              Emit raw output without post-processing\n' +
     '  --pick <field>     Extract a single field from JSON output (dot/bracket notation)\n' +
@@ -788,6 +802,32 @@ function makePlatformBindingsPresentResolver(cwd) {
   };
 }
 
+/**
+ * Phase 37 D-14: the ceremony verdict `loop render-hooks --phase <N>` injects,
+ * built here at the CLI entry so the pure resolver imports no ceremony code.
+ * Returns `(phase) => gateFn`; gateFn reads the phase's recorded verdict once
+ * (any throw is a null verdict) and answers `ceremonyGateOpen(verdict, gate)`.
+ * Every failure answers true (T-37-13): a missing, unreadable or unknown-phase
+ * verdict leaves the hook rendered, so a doubt never lowers ceremony.
+ */
+function makeCeremonyGateResolver(cwd) {
+  return (phase) => {
+    let verdict = null;
+    try {
+      verdict = require('./lib/ceremony.cjs').readRecordedVerdict(cwd, phase);
+    } catch {
+      verdict = null;
+    }
+    return (gate) => {
+      try {
+        return require('./lib/ceremony.cjs').ceremonyGateOpen(verdict, gate) !== false;
+      } catch {
+        return true;
+      }
+    };
+  };
+}
+
 async function runCommand(command, args, cwd, raw, defaultValue, originalCommand, workstreamContext = null) {
   switch (command) {
     case 'agent': {
@@ -821,6 +861,18 @@ async function runCommand(command, args, cwd, raw, defaultValue, originalCommand
       break;
     }
 
+    case 'timeline': {
+      timeline.cmdTimeline(cwd, args.slice(1), raw);
+      break;
+    }
+
+    case 'ceremony': {
+      // WR-04: loaded here, not at the top, so a missing ceremony-gates.json fails
+      // only the ceremony command, never every pp-tools command.
+      require('./lib/ceremony.cjs').cmdCeremony(cwd, args.slice(1), raw);
+      break;
+    }
+
     case 'platform-latest-tag': {
       // quick 261003-my0: the init.md / new-project.md preflights read
       // `--pick latest` from here instead of composing the platform URL in
@@ -1655,7 +1707,7 @@ async function runCommand(command, args, cwd, raw, defaultValue, originalCommand
     }
 
     case 'loop': {
-      // loop render-hooks <point> [--config-dir <dir>] [--active-cap <capId>] [--into <role>]
+      // loop render-hooks <point> [--config-dir <dir>] [--active-cap <capId>] [--into <role>] [--phase <N>]
       const loopSubcommand = args[1];
       if (loopSubcommand === 'render-hooks') {
         let loopConfigDir = null;
@@ -1703,10 +1755,25 @@ async function runCommand(command, args, cwd, raw, defaultValue, originalCommand
           }
           loopInto = value;
         }
+        // --phase <N>: read the phase's recorded ceremony verdict (Phase 37 D-14).
+        // Unlike the flags above, a missing, empty or `--`-prefixed value is NOT an
+        // error: a workflow whose phase variable is unset must keep today's hooks (T-37-13).
+        let loopPhase = undefined;
+        const phaseEqArg = args.find(arg => arg.startsWith('--phase='));
+        const phaseIdx = args.indexOf('--phase');
+        if (phaseEqArg) {
+          const value = phaseEqArg.slice('--phase='.length).trim();
+          if (value) loopPhase = value;
+        } else if (phaseIdx !== -1) {
+          const value = (args[phaseIdx + 1] || '').trim();
+          if (value && !value.startsWith('--')) loopPhase = value;
+        }
         loopResolver.cmdLoopRenderHooks(cwd, args[2], raw, {
           configDir: loopConfigDir ? path.resolve(loopConfigDir) : undefined,
           activeCap: loopActiveCap,
           into: loopInto,
+          phase: loopPhase,
+          resolveCeremonyGate: makeCeremonyGateResolver(cwd),
           resolveRecordedArtifacts: makeRecordedArtifactsResolver(cwd),
           resolvePlatformBindingsPresent: makePlatformBindingsPresentResolver(cwd),
         });
@@ -2564,13 +2631,155 @@ async function runCommand(command, args, cwd, raw, defaultValue, originalCommand
         } catch (vaultCheckErr) {
           error(`discovery vault-check: ${vaultCheckErr && vaultCheckErr.message ? vaultCheckErr.message : String(vaultCheckErr)}`, ERROR_REASON.UNKNOWN);
         }
+      } else if (subcommand === 'charter-check') {
+        // discovery charter-check [--require-signed]
+        //
+        // Structural check of docs/discovery/PROJECT-CHARTER.md: frontmatter
+        // enums, the twenty `<!-- charter:<key> -->` sections in order, every
+        // cited ID resolving to a session table or _requirements.md row, the
+        // Go / No-Go table equal to Session 13's, must-resolve open items
+        // closed or listed as conditions, sign-off rows agreeing with status.
+        // --require-signed also fails (discovery_charter_unsigned) unless the
+        // status is Signed or Signed with conditions — the handoff gate's arm.
+        const charter = require('./lib/discovery-charter.cjs');
+        try {
+          charter.cmdDiscoveryCharterCheck(cwd, args, raw);
+        } catch (charterCheckErr) {
+          error(`discovery charter-check: ${charterCheckErr && charterCheckErr.message ? charterCheckErr.message : String(charterCheckErr)}`, ERROR_REASON.UNKNOWN);
+        }
+      } else if (subcommand === 'entity-check') {
+        // discovery entity-check [--require-complete] — _entities.md structure
+        // (improvement plan, Batch 2): named entities, closed lifecycle and
+        // classification cells, attributes per entity, Mermaid cardinalities,
+        // step-matrix data objects resolving. --require-complete also fails on
+        // pending `—` cells (discovery_entity_check_incomplete).
+        const entities = require('./lib/discovery-entities.cjs');
+        try {
+          entities.cmdDiscoveryEntityCheck(cwd, args, raw);
+        } catch (entityCheckErr) {
+          error(`discovery entity-check: ${entityCheckErr && entityCheckErr.message ? entityCheckErr.message : String(entityCheckErr)}`, ERROR_REASON.UNKNOWN);
+        }
+      } else if (subcommand === 'process-check') {
+        // discovery process-check [--require-cited] — _processes.md structure:
+        // PRC-/MP- sequences, Replaces resolving, one swimlane and one step
+        // matrix per main process, actors, data objects, requirement IDs.
+        // --require-cited also fails on a step citing no requirement.
+        const processes = require('./lib/discovery-processes.cjs');
+        try {
+          processes.cmdDiscoveryProcessCheck(cwd, args, raw);
+        } catch (processCheckErr) {
+          error(`discovery process-check: ${processCheckErr && processCheckErr.message ? processCheckErr.message : String(processCheckErr)}`, ERROR_REASON.UNKNOWN);
+        }
+      } else if (subcommand === 'rules-check') {
+        // discovery rules-check — _rules.md structure: BR- sequence, layer
+        // vocabulary, every rule citing an existing requirement and an existing
+        // entity or process.
+        const rules = require('./lib/discovery-rules.cjs');
+        try {
+          rules.cmdDiscoveryRulesCheck(cwd, args, raw);
+        } catch (rulesCheckErr) {
+          error(`discovery rules-check: ${rulesCheckErr && rulesCheckErr.message ? rulesCheckErr.message : String(rulesCheckErr)}`, ERROR_REASON.UNKNOWN);
+        }
+      } else if (subcommand === 'stories-check') {
+        // discovery stories-check — _stories.md structure (improvement plan,
+        // Batch 4): US- sequence, EPIC shape, every story citing an existing
+        // requirement, source step resolving, every MVP domain requirement
+        // carrying at least one story.
+        const stories = require('./lib/discovery-stories.cjs');
+        try {
+          stories.cmdDiscoveryStoriesCheck(cwd, args, raw);
+        } catch (storiesCheckErr) {
+          error(`discovery stories-check: ${storiesCheckErr && storiesCheckErr.message ? storiesCheckErr.message : String(storiesCheckErr)}`, ERROR_REASON.UNKNOWN);
+        }
+      } else if (subcommand === 'phases-check') {
+        // discovery phases-check — _phases.md structure (improvement plan,
+        // Batch 4): contiguous phases, requirement IDs resolving and not
+        // dropped, dependencies on earlier phases, every MVP requirement in
+        // exactly one phase.
+        const phasesCheck = require('./lib/discovery-phases.cjs');
+        try {
+          phasesCheck.cmdDiscoveryPhasesCheck(cwd, args, raw);
+        } catch (phasesCheckErr) {
+          error(`discovery phases-check: ${phasesCheckErr && phasesCheckErr.message ? phasesCheckErr.message : String(phasesCheckErr)}`, ERROR_REASON.UNKNOWN);
+        }
+      } else if (subcommand === 'for-phase') {
+        // discovery for-phase <N> [--markdown | --conformance-template |
+        // --verify <file>] — the rows of every canonical artifact that cite
+        // the phase's requirement IDs as one extract between
+        // <!-- discovery:auto --> markers (improvement plan, Batch 4, R1);
+        // the verifier's conformance block and its check (R3). Fails loud on
+        // artifact structure only; no discovery package → exit 0, empty.
+        const forPhase = require('./lib/discovery-for-phase.cjs');
+        try {
+          forPhase.cmdDiscoveryForPhase(cwd, args, raw);
+        } catch (forPhaseErr) {
+          error(`discovery for-phase: ${forPhaseErr && forPhaseErr.message ? forPhaseErr.message : String(forPhaseErr)}`, ERROR_REASON.UNKNOWN);
+        }
+      } else if (subcommand === 'roles-check') {
+        // discovery roles-check — _roles.md structure (improvement plan,
+        // Batch 3): every role a persona, a step-matrix actor or System;
+        // permissions naming a known role, an existing entity, lowercase
+        // operations and at least one requirement; screen rows resolving.
+        const roles = require('./lib/discovery-access.cjs');
+        try {
+          roles.cmdDiscoveryRolesCheck(cwd, args, raw);
+        } catch (rolesCheckErr) {
+          error(`discovery roles-check: ${rolesCheckErr && rolesCheckErr.message ? rolesCheckErr.message : String(rolesCheckErr)}`, ERROR_REASON.UNKNOWN);
+        }
+      } else if (subcommand === 'integrations-check') {
+        // discovery integrations-check [--require-cited] — _integrations.md
+        // structure: IF- sequence, direction vocabulary, contract and error
+        // rows naming a known interface, step-matrix IF- tokens resolving.
+        // --require-cited also fails on an uncited interface and on a step
+        // naming a system without an IF- (discovery_integrations_uncited).
+        const integrations = require('./lib/discovery-integrations.cjs');
+        try {
+          integrations.cmdDiscoveryIntegrationsCheck(cwd, args, raw);
+        } catch (integrationsCheckErr) {
+          error(`discovery integrations-check: ${integrationsCheckErr && integrationsCheckErr.message ? integrationsCheckErr.message : String(integrationsCheckErr)}`, ERROR_REASON.UNKNOWN);
+        }
+      } else if (subcommand === 'migration-check') {
+        // discovery migration-check [--require-cited] — _migration.md
+        // structure: MG- sequence, source system in Session 2's landscape,
+        // entities resolving, requirement IDs resolving. --require-cited
+        // also fails on an uncited row (discovery_migration_uncited).
+        const migration = require('./lib/discovery-migration.cjs');
+        try {
+          migration.cmdDiscoveryMigrationCheck(cwd, args, raw);
+        } catch (migrationCheckErr) {
+          error(`discovery migration-check: ${migrationCheckErr && migrationCheckErr.message ? migrationCheckErr.message : String(migrationCheckErr)}`, ERROR_REASON.UNKNOWN);
+        }
+      } else if (subcommand === 'session-check') {
+        // discovery session-check <N> [<N>…] | --all — every Notes Template
+        // section of the session content file present exactly once in
+        // session-NN.md, each table with a data row or the literal
+        // `None identified in Discovery.`; --all covers the Completed sessions.
+        const sessionCheck = require('./lib/discovery-session-check.cjs');
+        try {
+          sessionCheck.cmdDiscoverySessionCheck(cwd, args, raw);
+        } catch (sessionCheckErr) {
+          error(`discovery session-check: ${sessionCheckErr && sessionCheckErr.message ? sessionCheckErr.message : String(sessionCheckErr)}`, ERROR_REASON.UNKNOWN);
+        }
+      } else if (subcommand === 'deviations-check') {
+        // discovery deviations-check [--require-approved] — _deviations.md
+        // structure: DEV- sequence, a [vault: path] standard present in the
+        // cache, reversible and status vocabularies, approver in Session 1's
+        // Approval Matrix, decision ID shape. --require-approved also fails
+        // on a hard-to-reverse deviation still Proposed
+        // (discovery_deviations_unapproved).
+        const deviations = require('./lib/discovery-deviations.cjs');
+        try {
+          deviations.cmdDiscoveryDeviationsCheck(cwd, args, raw);
+        } catch (deviationsCheckErr) {
+          error(`discovery deviations-check: ${deviationsCheckErr && deviationsCheckErr.message ? deviationsCheckErr.message : String(deviationsCheckErr)}`, ERROR_REASON.UNKNOWN);
+        }
       } else {
         // WIRING, NOT HELP TEXT: tests/discovery-artifacts.test.cjs derives each
         // subcommand spelling by regexing `<namespace>_<subcommand>_failed` out of
         // the engine's exported exit identity, splits this string on commas and
         // asserts membership. A spelling missing here is a command the engine
         // claims to be and the router does not dispatch.
-        error('Unknown discovery subcommand. Available: rollup, input-check, research-check, screen-check, element-sweep, rebaseline-check, vault-check', ERROR_REASON.SDK_UNKNOWN_COMMAND);
+        error('Unknown discovery subcommand. Available: rollup, input-check, research-check, screen-check, element-sweep, rebaseline-check, vault-check, charter-check, entity-check, process-check, rules-check, stories-check, phases-check, for-phase, roles-check, integrations-check, migration-check, deviations-check, session-check', ERROR_REASON.SDK_UNKNOWN_COMMAND);
       }
       break;
     }

package/pp-core/bin/shared/ceremony-gates.json

@@ -0,0 +1,17 @@
+{
+  "_comment": "The single gate vocabulary for per-phase ceremony (Phase 37). Read by src/ceremony.cts (table order), src/capability-activation.cts and scripts/gen-capability-registry.cjs (validation of `ceremony.<gate>` conjuncts). Keys are in verdict-table order; add a gate here and nowhere else.",
+  "schema_version": 1,
+  "gates": [
+    { "key": "research", "label": "Researcher" },
+    { "key": "pattern_mapper", "label": "Pattern mapper" },
+    { "key": "threat_model", "label": "Threat model" },
+    { "key": "plan_check", "label": "Plan checker" },
+    { "key": "code_review", "label": "Code review" },
+    { "key": "verifier", "label": "Verifier" },
+    { "key": "security_review", "label": "Security review" },
+    { "key": "nyquist", "label": "Nyquist audit" },
+    { "key": "ui_review", "label": "UI review" },
+    { "key": "ui", "label": "UI contract" },
+    { "key": "vault", "label": "Vault" }
+  ]
+}

package/pp-core/bin/shared/config-schema.manifest.json

@@ -33,6 +33,7 @@
     "workflow.plan_bounce_passes",
     "workflow.plan_chunked",
     "workflow.plan_review_convergence",
+    "workflow.ceremony",
     "code_quality.fallow.enabled",
     "code_quality.fallow.scope",
     "code_quality.fallow.profile",

package/pp-core/references/ceremony.md

@@ -0,0 +1,81 @@
+# Phase Ceremony
+
+Before any agent runs, plan-phase classifies the phase from what it touches (`/pp-plan-phase` writes the verdict in the classify step, ahead of research). Only `pp_run ceremony classify` computes a verdict; every other workflow, hook and agent reads the recorded one. The verdict is a pure function of the phase's ROADMAP section, its mapped REQUIREMENTS lines, its CONTEXT.md, the git file inventory, the completion state of other phases and the gate keys in `.planning/config.json`. No model judgment and no client identity is involved. It is recorded as `{padded}-CEREMONY.md`, and the same table is printed by the CLI.
+
+The verdict only ever lowers ceremony relative to config. A gate that config turns off stays `off (config)`. The full gate stack is one flag (`--full`), one config key (`workflow.ceremony: full`) or one ROADMAP line (`**Ceremony:** full`, or `**Ceremony**: full`, anywhere in the phase section) away, and full mode runs every gate exactly as config says today. A `**Ceremony**` line with any other value is ignored with a warning line.
+
+## The three questions
+
+1. **Trust boundary crossed?** The ROADMAP section (up to its Plans list), the mapped REQUIREMENTS lines and CONTEXT.md (without its `<deferred>` block) are matched, case-insensitively on word boundaries, against four conservative term sets: authentication and authorization, secrets and crypto, personal and payment data, untrusted input. The security verbs also match their inflections and negations (encrypted, unencrypted, authenticated, unauthorized, uploaded, deserialization). "Log in" and "sign in" match only in their authentication sense (users log in, can sign in, allow log in, log in with, a logged-in or logged in user, not signed in, the login page, a sign in page, the log in screen), so logging prose such as "write the logs in JSON" or "structured logging" does not. Any match is "crossed", and the matched terms with their source are the evidence. A bare "token" does not match, because pp-core's own phases talk about context tokens. Over-match is accepted where it only adds ceremony: "logged in" or "signed in" followed by anything but a place or format word (the, a, its, CI, JSON, …), such as "decisions logged in STATE.md", reads as authentication. Detection only pushes a phase up. The residual risk is a phase worded without any trigger term, which reads as no trust boundary; `--full`, `workflow.ceremony: full` or a `**Ceremony:** full` ROADMAP line restore the full stack.
+2. **Codebase to match?** Yes when the repository tracks at least 20 source files outside `.planning/` (vendored and generated directories excluded), or another roadmap phase or an archived milestone is complete. No git means yes (fails toward ceremony). A freshly generated scaffold stays below the threshold. The counts are the evidence.
+3. **Serial single-concern?** Yes when the phase maps at most 3 requirement IDs sharing one category prefix, lists at most 4 success criteria, and does not span a UI surface plus a non-UI surface. `**UI:** none` counts as no UI. Requirement IDs and success criteria are read from the same line or from a numbered or bulleted list under the header. Only ID-shaped tokens (`SLUG-01`) count; other words on the line are dropped, and a range (`DATA-01 – DATA-03`, `to`, `through`) expands into every ID in it, up to 50.
+
+Input the classifier cannot read fails toward ceremony and is named in a warning line. A missing ROADMAP section, no parseable requirement IDs (including `TBD` and `None`), a requirement ID with no REQUIREMENTS.md line, no parseable success criteria or a failed frontend check make the phase not single-concern, so it plans at least standard. An explicit `TBD`/`None`/`N/A` claims nothing; a ROADMAP section that is missing or unreadable, or a mapped requirement ID with no REQUIREMENTS.md line (REQUIREMENTS.md missing included), cannot rule out a trust boundary, so the answer is yes (`phase section unreadable — failing toward ceremony`, `requirement text unread for <IDs> — failing toward ceremony`) and the phase plans heavy. So a phase created by `/pp-phase add` or `insert` (`**Requirements**: TBD`) plans standard until its requirements are mapped, and heavy only when its wording names a trust term.
+
+## Tiers
+
+| Tier | When | Effect |
+|------|------|--------|
+| light | serial single-concern and no trust boundary | one blockers-only checker round, light verifier, quick code review, Nyquist audit and UI review skipped |
+| heavy | not single-concern and a trust boundary crossed | up to 3 checker rounds, full verifier, configured review depth |
+| standard | everything else | same as heavy |
+
+"Codebase to match" never changes the tier; it gates the researcher and the pattern mapper directly. The tier names are the routing tiers' light, standard and heavy vocabulary, and the verdict has no effect on model routing.
+
+## Gate rules
+
+Every gate appears in the verdict with a decision (`run`, `skip` or `off`) and a reason. The hook conjunct is the `ceremony.<gate>` term a capability `when` may carry; it is false only for a `skip` in proportional mode.
+
+| Gate key | Proportional rule | Full mode | Hook conjunct |
+|----------|-------------------|-----------|---------------|
+| `research` | runs only with a codebase to match; `--research` forces, `--skip-research` skips | runs if config enables it | `research` hook |
+| `pattern_mapper` | runs only with a codebase to match | runs if config enables it | `pattern-mapper` hook |
+| `threat_model` | runs only when a trust boundary is crossed, at any tier | runs if config enables it | `security` hook (threat-model contribution) |
+| `plan_check` | light: one blockers-only round; standard and heavy: up to 3 rounds; `--skip-verify` skips | up to 3 rounds | none (read as `plan_check_rounds`, `plan_check_mode`) |
+| `code_review` | light: `quick` depth; otherwise the configured depth, read live (a recorded depth never lowers review below current config) | configured depth | none (read as `code_review_depth`) |
+| `verifier` | light and no trust boundary: `light` depth; otherwise `full` | `full` | none (read as `verifier_depth`) |
+| `security_review` | runs only when a trust boundary is crossed | runs if config enables it | `security` hook (`secure-phase`, ship gate) |
+| `nyquist` | skipped at light; runs at standard and heavy | runs if config enables it | `nyquist` hook |
+| `ui_review` | skipped at light; runs otherwise | runs if config enables it | `ui` hook (`ui-review` step only) |
+| `ui` | follows frontend detection exactly as today | same | none |
+| `vault` | always runs when the vault is enabled | same | none |
+
+A gate that config turns off is listed `off (config)` in every mode. If `workflow.security_enforcement` is off on a trust-boundary phase, the verdict adds a warning line. Deterministic checks (requirements coverage, decision coverage, plan-sizing, test substance, schema and codebase drift) always run. The vault gates and the UI design-contract gates (`ui-phase`, the UI plan gate and the UI safety gate) never depend on the tier. Plan-time VALIDATION.md is built from RESEARCH.md's Validation Architecture section, so when the verdict skips research (no codebase to match) it skips with it, and the research row's reason says so. The checker's Nyquist dimension (Dimension 8) runs with or without RESEARCH.md at every tier, light included, through `check test-substance`; only its VALIDATION.md check (8e) needs the Validation Architecture section. The post-execution Nyquist audit follows its own `nyquist` row.
+
+## Verifier depth
+
+`full` is today's verifier. `light` skips Step 4b (the data-flow trace, Level 4) and the Step 7b behavioural spot-check sweep. Must-haves, artifacts at levels 1-3, key links, requirements coverage, the Step 7 anti-pattern scan and the Step 7c probes always run. A behaviour-dependent truth still needs Step 3's single named passing test or routes to human verification: light depth never turns presence into VERIFIED. Light depth is reachable only at light tier, which has no trust boundary, so a trust-boundary phase is always verified at full depth.
+
+## Blockers-only checker mode
+
+`plan_check_mode: blockers-only` is used for the single light-tier round. The checker runs every dimension but reports only BLOCKER issues, never warnings or info, and returns `## VERIFICATION PASSED` when there is no blocker. If it returns blockers, the orchestrator runs one targeted revision for those blockers and does not re-check. Requirements coverage, decision coverage, plan-sizing and test substance still run deterministically in the planner's own validation. Every `check test-substance` finding is a BLOCKER, so it survives the single blockers-only round. `plan_check_mode: standard` is today's loop of up to 3 iterations.
+
+## Lifecycle
+
+The verdict is rewritten on every plan-phase run until the phase has its first SUMMARY.md, then reused: `--gaps` replans and execute-phase read the recorded verdict, so the phase's own code never flips "codebase to match" between planning and gap closure. `--full` always rewrites the verdict as full. `--skip-research` and `--skip-verify` decide only the run that passes them: the printed table shows them, the recorded verdict never does, and a recorded verdict that carries either reason does not parse. A phase with no CEREMONY.md, or one that does not parse, is treated as full, which is today's behaviour; this covers phases planned before this release and phases that skipped plan-phase.
+
+`/pp-execute-phase` has no `--full`: re-plan with it. A `--full` verdict lasts only until the next plan-phase run without `--full` before the first SUMMARY. That run, a `--reviews` replan included, re-classifies the phase proportionally. Pass `--full` on every re-plan that should stay full; `/pp-autonomous --full` and `/pp-plan-review-convergence --full` forward it to every plan-phase call they make.
+
+## Reading the verdict
+
+No workflow parses CEREMONY.md or evaluates the verdict itself.
+
+- **Init keys.** `pp_run query init.plan-phase` and `pp_run query init.execute-phase` return `ceremony_tier`, `ceremony_mode`, `plan_check_rounds` (1 or 3), `plan_check_mode` (`blockers-only` or `standard`), `verifier_depth` (`light` or `full`) and `code_review_depth`; `init.plan-phase` also returns `research_enabled` already folded through the verdict. `code-review` resolves its depth in the order `--depth` flag, then the verdict, then config. In proportional mode a gate the verdict skips is skipped without prompting; plan-phase's interactive research question is not asked. `--research` and `--full` are the overrides.
+- **Hooks.** `pp_run loop render-hooks <point> --phase <N>` supplies the phase to the `when` evaluator. An empty or unknown phase, or no recorded file, leaves every `ceremony.*` conjunct true, so callers without a phase (`/pp-quick`, `/pp-debug`) are unchanged.
+- **Direct read.** `pp_run ceremony get <N> [--pick <field>]` returns the recorded verdict, else the full default. Each gate carries a `report` string: `run`, `off (config)` or `skipped (ceremony: <reason>)`.
+- **Ship and milestone audit** report a skipped gate as `skipped (ceremony: <reason>)`, never as missing and never as a ship block. Hand-invoked `/pp-secure-phase` and `/pp-validate-phase` always run, since that is an explicit request.
+- A failed read falls back to full, never to less ceremony.
+
+## CEREMONY.md
+
+`{phase_dir}/{padded}-CEREMONY.md` is committed with the phase's planning docs. The YAML frontmatter is the machine contract; the body is the table the CLI printed. A frontmatter whose rows do not follow from its own answers, tier and mode (a hand edit or a half-resolved merge that skips a gate the rules would run) does not parse, so it reads as full. `ceremony get` and a reused `classify` print the table rendered from the frontmatter, not the stored body. There is no timestamp, so identical inputs give a byte-identical file.
+
+| Field | Meaning |
+|-------|---------|
+| `schema_version` | `1` |
+| `phase` | the padded phase token |
+| `mode` | `proportional` or `full` |
+| `forced_by` | `flag`, `config` or `roadmap` when full was forced; `none` otherwise |
+| `tier` | `light`, `standard` or `heavy` |
+| `answers` | `trust_boundary`, `codebase_to_match`, `serial_single_concern`, each `{ value, evidence }` |
+| `gates` | one key per gate in the Gate rules table, each `{ decision: run\|skip\|off, depth?, rounds?, mode?, reason }` |

package/pp-core/references/discovery-access.md

@@ -0,0 +1,112 @@
+# Discovery Access Model — `_roles.md` Template & Parser Contract
+
+Single home for the roles artifact the build reads instead of Session 7's notes (Discovery Sprint
+improvement plan, Batch 3): `_roles.md` holds the roles, what each may do to which entity, and which
+screens each may open. Its gate is `pp_run query discovery.roles-check`. This file is Read lazily; it
+is never `@`-imported.
+
+## When the file appears
+
+| Session | `_roles.md` |
+|---|---|
+| 7 | created from the template; topic 1 writes `## Roles` and `## Permissions`, topic 4 writes `## Screens`; `roles-check` in the session |
+| 8 | `roles-check` in the Closing Step (reporting) |
+| 13 | in the Step 0 gates (reporting) |
+| handoff | `roles-check` hard-blocks |
+
+Session 7's **Roles** section keeps a reading summary and points here: the canonical rows live in
+the artifact, exactly as the requirements table lives in `_requirements.md`. The old preset matrix
+(Admin / Manager / User / Viewer with one CRUD column per entity) is gone: a role is whatever the
+client's process needs, and a permission is one row per role and entity with the operations as a
+list, so a build phase can read exactly the rows that cite its requirements.
+
+## Grammar
+
+- **A role is an actor the process already has.** Every `## Roles` row names a Session 2 persona
+  (spelled as the User Personas table spells it), an actor a step matrix of `_processes.md` names,
+  or `System`. A role nobody plays in any step is a role the build cannot test; name the persona or
+  add the step. Unresolved while neither `session-02.md` nor `_processes.md` is on file.
+- **Recovery path** is how the role is recovered when its last holder leaves or is locked out — the
+  vault's rule that no role may become unreachable (`[vault: <path>]` when the vault states it).
+- **An operation is a lowercase verb** (`create`, `read`, `update`, `delete`, `assign`, `export`,
+  `approve`), comma-separated; the vocabulary is the product's, the shape is fixed.
+- **An entity is a row of `_entities.md`**, one PascalCase token (`references/discovery-data-model.md`).
+- **Condition** narrows a permission (`own team only`, `assignee or lead`); `—` is unconditional.
+- **Requirements** names the `_requirements.md` IDs the permission realises — at least one; a
+  permission nothing requires is a question for the user, not a row.
+- **A screen row is the authorization join**: the role may open the screen. `_screens.md` keeps its
+  own `Role` column as a reading aid (D-50); this table is the one the forbidden-path tests read.
+- **Nothing is deleted.** A retired role keeps its row; a change after sign-off edits the row in
+  place and appends `→ amended by D-<ss>-<n>` (`references/discovery-id-conventions.md` § Precedence).
+
+## `_roles.md`
+
+Illustration only — not part of the template, names invented:
+
+| Role | Description | Scope | Recovery path | Source |
+|---|---|---|---|---|
+| Team lead | Runs a team's work and membership | Teams they lead | An operator with `Teams.Recover` names a member lead | S7 |
+
+| Role | Entity | Operation | Condition | Requirements |
+|---|---|---|---|---|
+| Team lead | Membership | create, delete, update | own team only | K-13, K-14 |
+
+| Role | Screen |
+|---|---|
+| Team lead | SCR-05 |
+
+Bootstrap template — Session 7 copies it verbatim to `.planning/discovery/_roles.md`, replacing
+`[PROJECT_NAME]`:
+
+```markdown
+# Roles — [PROJECT_NAME]
+
+**Conventions:** pp-core reference `references/discovery-access.md`. A role is a Session 2 persona, a step-matrix actor or `System`; one permission row per role and entity, operations as a comma list; a screen row says the role may open the screen. Rows are never deleted; a change after sign-off edits the row in place and appends `→ amended by D-<ss>-<n>`.
+
+## Roles
+
+| Role | Description | Scope | Recovery path | Source |
+|------|-------------|-------|---------------|--------|
+
+## Permissions
+
+| Role | Entity | Operation | Condition | Requirements |
+|------|--------|-----------|-----------|--------------|
+
+## Screens
+
+| Role | Screen |
+|------|--------|
+```
+
+### Parser contract — `pp_run query discovery.roles-check`
+
+No positional path, no flags. Faults name the artifact, the 1-based line, a validated ID or name, a
+section or column name and the reason code — never cell prose. Absent `_roles.md` → exit 0,
+`present: false`.
+
+| Cell / field | Grammar | Fault when violated |
+|---|---|---|
+| `## Roles`, `## Permissions`, `## Screens` | each once as a `##` heading holding one table with the template's columns | `missing_section`, `bad_table_shape` naming the section |
+| Roles `Role` | non-empty, listed once; a Session 2 persona, a step-matrix `Actor` token or `System` | `empty_cell (Role)`, `duplicate_role`, `unknown_role` naming the role. **Not resolved** while neither `session-02.md` nor `_processes.md` is on file |
+| Roles `Description`, `Scope`, `Recovery path` | non-empty (`—` is a pending cell the facilitator owns) | `empty_cell` naming the column |
+| Roles `Source` | free text | **not mechanically checked** |
+| Permissions / Screens `Role` | a `## Roles` row | `unknown_role` |
+| Permissions `Entity` | one PascalCase token present in `_entities.md` § Entities when on file | `bad_entity`; `unknown_entity` naming the entity |
+| Permissions `Operation` | a comma list of `^[a-z][a-z-]*$` tokens | `bad_operation` |
+| Permissions `Condition` | free text (`—` allowed) | **not mechanically checked** |
+| Permissions `Requirements` | at least one requirement ID, each present in `_requirements.md` when on file and parseable | `no_requirement`, `unknown_requirement_id` |
+| Screens `Screen` | `SCR-\d{2}`, present in `_screens.md` § Screens when on file | `bad_screen`; `unknown_screen` naming the screen |
+| `_requirements.md` present but unparseable | the rollup grammar is owned by `discovery rollup` | `requirements_unparseable`, once; IDs are then shape-checked only |
+| a source present but unreadable | present-and-readable | `artifact_unreadable` naming the path |
+
+**Exit identity.** `discovery_roles_check_failed`. Payload: `ok`, `present`, `file`, `roles`,
+`permissions`, `screens`.
+
+## How the build reads it
+
+`pp_run query discovery.for-phase <N>` selects the § Permissions rows citing the phase's requirement
+IDs, then the § Roles row of every role those permissions name and the § Screens rows of those roles
+and of the phase's screens (`references/discovery-build-consumption.md`). The conformance key is the
+role name. The planner's auth phase reads the extract; the forbidden-path tests are written from the
+screen rows and the permission conditions.