@pareto4/pp-core 1.18.0 → 1.20.0

package/pp-core/bin/lib/vault-index.cjs

@@ -39,7 +39,7 @@
  * has already sanitised.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.VAULT_INDEX_WITHHELD_KINDS = exports.VAULT_INDEX_UNCHECKED_CAUSES = exports.VAULT_INDEX_UNPARSEABLE_CAUSES = exports.VAULT_INDEX_REASON = exports.DISPLAY_UNSAFE_TEXT_CHAR_RE = exports.VAULT_BINDING_NOTE = exports.VAULT_PATH_REASONS = exports.VAULT_INDEX_LIST_BOUND = exports.VAULT_TEXT_MAX = exports.VAULT_INDEX_GRAMMAR = exports.VAULT_SECTION_HEADING_PREFIX = exports.VAULT_USED_WHEN_RE = exports.VAULT_USED_WHEN_MARKER = exports.VAULT_ENTRY_SEPARATOR = exports.VAULT_ENTRY_PREFIX = exports.VAULT_INDEX_BYTE_CAP = exports.VAULT_INDEX_FILENAME = void 0;
+exports.VAULT_INDEX_WITHHELD_KINDS = exports.VAULT_INDEX_UNCHECKED_CAUSES = exports.VAULT_INDEX_UNPARSEABLE_CAUSES = exports.VAULT_INDEX_REASON = exports.DISPLAY_UNSAFE_TEXT_CHAR_RE = exports.VAULT_BINDING_NOTE = exports.VAULT_PATH_REASONS = exports.VAULT_INDEX_LIST_BOUND = exports.VAULT_TEXT_MAX = exports.VAULT_INDEX_GRAMMAR = exports.VAULT_CROSS_CUTTING_MARK = exports.VAULT_SECTION_HEADING_PREFIX = exports.VAULT_USED_WHEN_RE = exports.VAULT_USED_WHEN_MARKER = exports.VAULT_ENTRY_SEPARATOR = exports.VAULT_ENTRY_PREFIX = exports.VAULT_INDEX_BYTE_CAP = exports.VAULT_INDEX_FILENAME = void 0;
 exports.classifyVaultPath = classifyVaultPath;
 exports.isSafeVaultPath = isSafeVaultPath;
 exports.splitVaultEntryLine = splitVaultEntryLine;
@@ -74,6 +74,13 @@ exports.VAULT_USED_WHEN_MARKER = '; used when ';
 exports.VAULT_USED_WHEN_RE = /;\s+used when\s+/i;
 /** A section is opened by a level-2 ATX heading at column 0. */
 exports.VAULT_SECTION_HEADING_PREFIX = '## ';
+/**
+ * The cross-cutting mark (issue #12, items 16-17): an entry whose remainder
+ * starts with it holds a rule every Discovery session must read — approval
+ * routes, folder layout, naming — whatever the session's topics are. It is
+ * stripped from the description and recorded as `crossCutting: true`.
+ */
+exports.VAULT_CROSS_CUTTING_MARK = '[cross-cutting]';
 /** The six grammar values bundled, frozen, for a consumer that quotes the grammar whole. */
 exports.VAULT_INDEX_GRAMMAR = Object.freeze({
     filename: exports.VAULT_INDEX_FILENAME,
@@ -219,16 +226,22 @@ const LEVEL1_HEADING_RE = /^#(?:[ \t].*)?$/;
 // D-28: an entry prefix indented 1-3 spaces is a near-miss, not a nested list.
 const INDENTED_ENTRY_RE = /^ {1,3}- `/;
 function buildEntry(section, path, rest, line) {
-    const m = exports.VAULT_USED_WHEN_RE.exec(rest);
+    // The mark is read off the front of the remainder; a mark with nothing after
+    // it stays text, so the description is never left empty.
+    const lead = rest.trimStart();
+    const marked = lead.startsWith(exports.VAULT_CROSS_CUTTING_MARK) && lead.slice(exports.VAULT_CROSS_CUTTING_MARK.length).trim() !== '';
+    const body = marked ? lead.slice(exports.VAULT_CROSS_CUTTING_MARK.length) : rest;
+    const flag = marked ? { crossCutting: true } : {};
+    const m = exports.VAULT_USED_WHEN_RE.exec(body);
     if (m) {
-        const usedWhen = rest.slice(m.index + m[0].length).trim();
+        const usedWhen = body.slice(m.index + m[0].length).trim();
         if (usedWhen !== '') {
-            return { section, path, description: rest.slice(0, m.index).trim(), usedWhen, line };
+            return { section, path, description: body.slice(0, m.index).trim(), usedWhen, ...flag, line };
         }
     }
     // No clause, or an empty one: the whole remainder is the description and the
     // key is omitted — a clause is never invented and text is never dropped.
-    return { section, path, description: rest.trim(), line };
+    return { section, path, description: body.trim(), ...flag, line };
 }
 /**
  * Parse an INDEX.md text tolerantly. Never throws; a non-string is read as

package/pp-core/bin/lib/vault-standards-review.cjs

@@ -3,7 +3,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.REVIEW_FILES_CAP = exports.REVIEW_VERDICTS_HEADING = exports.REVIEW_ARTIFACT_MARKER = exports.REVIEW_ARTIFACT_SUFFIX = exports.REVIEW_VERDICTS = void 0;
+exports.DEVIATIONS_FILE = exports.REVIEW_FILES_CAP = exports.REVIEW_VERDICTS_HEADING = exports.REVIEW_ARTIFACT_MARKER = exports.REVIEW_ARTIFACT_SUFFIX = exports.REVIEW_VERDICTS = void 0;
+exports.readDeviations = readDeviations;
 exports.deriveStandardsReview = deriveStandardsReview;
 exports.formatReviewCounts = formatReviewCounts;
 exports.validateReviewArtifact = validateReviewArtifact;
@@ -59,6 +60,8 @@ exports.REVIEW_VERDICTS_HEADING = '## Standard Verdicts';
 exports.REVIEW_FILES_CAP = 200;
 /** Bound on a git query a review makes. */
 const REVIEW_GIT_TIMEOUT_MS = 30_000;
+/** Where the Discovery Sprint records agreed departures from the vault. */
+exports.DEVIATIONS_FILE = '.planning/discovery/_deviations.md';
 // ─── Derivation ──────────────────────────────────────────────────────────────
 const PLAN_RE = /(^|-)PLAN\.md$/;
 const SUMMARY_RE = /(^|-)SUMMARY\.md$/;
@@ -73,6 +76,47 @@ function readBounded(abs) {
         return null;
     }
 }
+/**
+ * The deviations on file, read by header name so Batch 3's full grammar can
+ * add or reorder columns without touching this reader. `gap` is set when the
+ * file exists but yields no readable table with both join columns.
+ */
+function readDeviations(root) {
+    const abs = node_path_1.default.join(root, exports.DEVIATIONS_FILE);
+    if (!node_fs_1.default.existsSync(abs))
+        return { deviations: [], gap: null };
+    const text = readBounded(abs);
+    if (text === null)
+        return { deviations: [], gap: `${exports.DEVIATIONS_FILE} could not be read (unreadable or over the size cap), so deviations on file are unknown` };
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const table = require('./discovery-table.cjs');
+    const deviations = [];
+    let joinable = false;
+    for (const section of table.splitSections(text.split(/\r?\n/), 2)) {
+        for (const tbl of table.parseTables(section.body)) {
+            const names = tbl.header.map((h) => h.trim().toLowerCase());
+            const col = (name) => names.indexOf(name);
+            const standard = col('standard');
+            const status = col('status');
+            if (standard === -1 || status === -1)
+                continue;
+            joinable = true;
+            const cell = (row, i) => (i === -1 ? '' : (row.cells[i] ?? '').trim());
+            for (const row of tbl.rows) {
+                deviations.push({
+                    id: cell(row, col('id')),
+                    standard: cell(row, standard),
+                    status: cell(row, status),
+                    decision: cell(row, col('decision')),
+                    approver: cell(row, col('approver')),
+                });
+            }
+        }
+    }
+    if (!joinable)
+        return { deviations: [], gap: `${exports.DEVIATIONS_FILE} carries no table with Standard and Status columns, so deviations on file are unknown` };
+    return { deviations, gap: null };
+}
 function consultedText(entry, hasSummary) {
     if (!hasSummary)
         return 'no summary';
@@ -206,6 +250,9 @@ function deriveStandardsReview(root, cwd, positional, opts = {}) {
             });
         }
     }
+    const onFile = readDeviations(root);
+    if (onFile.gap !== null)
+        gaps.push(onFile.gap);
     if (plans.length === 0 || documents.size === 0) {
         return {
             status: 'no-records',
@@ -216,9 +263,10 @@ function deriveStandardsReview(root, cwd, positional, opts = {}) {
             plans,
             documents: [],
             gaps,
+            deviations: onFile.deviations,
         };
     }
-    return { status: 'ok', phaseDir: phase.rel, plans, documents: [...documents.values()], gaps };
+    return { status: 'ok', phaseDir: phase.rel, plans, documents: [...documents.values()], gaps, deviations: onFile.deviations };
 }
 /** The counts line, in verdict order: `p PASS · f FAIL · n N-A · i INCONCLUSIVE (of N documents)`. */
 function formatReviewCounts(counts) {

package/pp-core/bin/lib/vault-update.cjs

@@ -109,6 +109,7 @@ function vaultUpdate(cwd, opts = {}) {
         from: null,
         to: null,
         latest: null,
+        newer: null,
         available: [],
         fetch: null,
         nextStep: null,
@@ -152,6 +153,9 @@ function vaultUpdate(cwd, opts = {}) {
     tags = [...new Set(tags)].sort((a, b) => (0, semver_compare_cjs_1.compareSemverCore)(b, a));
     result.available = tags.slice(0, exports.AVAILABLE_TAGS_CAP);
     result.latest = tags[0] ?? null;
+    if (result.from && result.latest && (0, semver_compare_cjs_1.isStableTripletSemver)(result.from) && (0, semver_compare_cjs_1.compareSemverCore)(result.latest, result.from) > 0) {
+        result.newer = result.latest;
+    }
     if (tags.length === 0) {
         return fail('no_tags', `The vault repo "${redactCloneTarget(repo)}" has no stable vX.Y.Z tag to pin to.`);
     }

package/pp-core/bin/lib/vault.cjs

@@ -2809,7 +2809,7 @@ function resolveRefDrift({ cwd, tier, cachedRef }) {
         // DEVIATION from plan 08-01's step 3, recorded so the next reader does not
         // "restore" it: the plan prescribed copying the miss branch's call-site-
         // scoped `require('./git-provider.cjs')` / `require('./vault-coordinates.cjs')`
-        // pair from src/check-command-router.cts:1558-1565. That shape exists THERE
+        // pair from src/check-command-router.cts:1587-1594. That shape exists THERE
         // because the check router does not otherwise import those leaves, so the
         // require genuinely keeps its module graph narrow. It buys nothing HERE:
         // this module already imports `resolveProvider` (:40) and
@@ -2833,7 +2833,7 @@ function resolveRefDrift({ cwd, tier, cachedRef }) {
         //     UNCONDITIONALLY, including when `repo` is null, so an ungated
         //     comparison reports phantom drift on every project that configures no
         //     client vault at all. The miss branch argues the same point at
-        //     src/check-command-router.cts:1567-1570, where it keeps the truthful
+        //     src/check-command-router.cts:1596-1599, where it keeps the truthful
         //     `(no ref pinned)` placeholder for the same reason.
         //
         //     D-08-39(a): a BLANK or WHITESPACE-ONLY `client.vaultRepo` is not a

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

@@ -19,8 +19,8 @@
  *   state signal-resume                Remove WAITING.json signal
  *   resolve-model <agent-type>         Get model for agent based on profile
  *   find-phase <phase>                 Find phase directory by number
- *   commit <message> [--files f1 f2] [--no-verify]   Commit planning docs
- *   commit-to-subrepo <msg> --files f1 f2  Route commits to sub-repos
+ *   commit <message> [--files f1 f2] [--phase id] [--quick id] [--no-verify]   Commit planning docs
+ *   commit-to-subrepo <msg> --files f1 f2 [--phase id]  Route commits to sub-repos
  *   verify-summary <path>              Verify a SUMMARY.md file
  *   generate-slug <text>               Convert text to URL-safe slug
  *   current-timestamp [format]         Get timestamp (full|date|filename)
@@ -1158,6 +1158,10 @@ async function runCommand(command, args, cwd, raw, defaultValue, originalCommand
     }
 
     case 'commit': {
+      // --phase <id> / --quick <id> add a `Phase:` / `Quick:` trailer; pulled out
+      // first so their values are never read as message words or --files paths.
+      const trailerArgs = commands.extractCommitTrailerArgs(args);
+      args = trailerArgs.args;
       const amend = args.includes('--amend');
       const noVerify = args.includes('--no-verify');
       const filesIndex = args.indexOf('--files');
@@ -1168,7 +1172,7 @@ async function runCommand(command, args, cwd, raw, defaultValue, originalCommand
       const messageArgs = args.slice(1, endIndex).filter(a => !a.startsWith('--'));
       const message = messageArgs.join(' ') || undefined;
       const files = filesIndex !== -1 ? args.slice(filesIndex + 1).filter(a => !a.startsWith('--')) : [];
-      commands.cmdCommit(cwd, message, files, raw, amend, noVerify);
+      commands.cmdCommit(cwd, message, files, raw, amend, noVerify, { phase: trailerArgs.phase, quick: trailerArgs.quick });
       break;
     }
 
@@ -1178,10 +1182,12 @@ async function runCommand(command, args, cwd, raw, defaultValue, originalCommand
     }
 
     case 'commit-to-subrepo': {
+      const trailerArgs = commands.extractCommitTrailerArgs(args);
+      args = trailerArgs.args;
       const message = args[1];
       const filesIndex = args.indexOf('--files');
       const files = filesIndex !== -1 ? args.slice(filesIndex + 1).filter(a => !a.startsWith('--')) : [];
-      commands.cmdCommitToSubrepo(cwd, message, files, raw);
+      commands.cmdCommitToSubrepo(cwd, message, files, raw, { phase: trailerArgs.phase, quick: trailerArgs.quick });
       break;
     }
 
@@ -2558,13 +2564,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/org-profile.json

@@ -11,7 +11,7 @@
       "repo": "pareto000/Pareto-Platform"
     },
     "client": {
-      "vaultRepo": "pareto000/Pareto-Vault",
+      "vaultRepo": "pareto-ooo/pareto-vault-releases",
       "vaultHost": "github.com"
     },
     "provisioning": {

package/pp-core/references/autonomous-best-effort.md

@@ -83,7 +83,7 @@ grep -q "^handled=${PHASE_NUM}:" "$RUN_STATE" 2>/dev/null ||
   printf 'handled=%s:%s\n' "$PHASE_NUM" "$OUTCOME" >> "$RUN_STATE"
 PADDED_PHASE=$(basename "$PHASE_DIR" | cut -d- -f1)
 if [ -f "$REPORT" ]; then
-  pp_run query commit "docs(${PADDED_PHASE}): autonomous report" --files "$REPORT"
+  pp_run query commit "docs(planning): autonomous report" --phase "${PADDED_PHASE}" --files "$REPORT"
 fi
 ```
 
@@ -400,6 +400,7 @@ phase. Printed by the lifecycle single-phase banner, the STOPPED banner and the
 Used by `autonomous.md` §3a when `workflow.skip_discuss` is true. Get phase details:
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 DETAIL=$(pp_run query roadmap.get-phase ${PHASE_NUM})
 ```
 
@@ -452,7 +453,7 @@ None — discuss phase skipped.
 Commit the minimal context:
 
 ```bash
-pp_run query commit "docs(${padded_phase}): auto-generated context (discuss skipped)" --files "${phase_dir}/${padded_phase}-CONTEXT.md"
+pp_run query commit "docs(planning): auto-generated context (discuss skipped)" --phase "${padded_phase}" --files "${phase_dir}/${padded_phase}-CONTEXT.md"
 ```
 
 ## Banner math

package/pp-core/references/autonomous-lifecycle.md

@@ -109,6 +109,7 @@ Skill(skill="pp-complete-milestone", args="${milestone_version}")
 After complete-milestone returns, verify it produced output:
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 ls .planning/milestones/v${milestone_version}-ROADMAP.md 2>/dev/null || true
 ```
 

package/pp-core/references/autonomous-smart-discuss.md

@@ -5,6 +5,7 @@ Smart discuss is the autonomous-optimized variant of `pp-discuss-phase`. It prop
 **Inputs:** `PHASE_NUM` from execute_phase. Run init to get phase paths:
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 PHASE_STATE=$(pp-tools query init.phase-op ${PHASE_NUM})
 ```
 
@@ -34,6 +35,7 @@ Extract from these:
 **Read all prior CONTEXT.md files:**
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 (find "$(dirname "$STATE_PATH")/phases" -name "*-CONTEXT.md" 2>/dev/null || true) | sort
 ```
 
@@ -68,6 +70,7 @@ Lightweight codebase scan to inform grey area identification and proposals. Keep
 **Check for existing codebase maps:**
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 ls .planning/codebase/*.md 2>/dev/null || true
 ```
 
@@ -96,6 +99,7 @@ Read the 3-5 most relevant files to understand existing patterns.
 **Get phase details:**
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 DETAIL=$(pp-tools query roadmap.get-phase ${PHASE_NUM})
 ```
 
@@ -270,7 +274,7 @@ Write the file.
 **Commit:**
 
 ```bash
-pp-tools query commit "docs(${PADDED_PHASE}): smart discuss context" --files "${phase_dir}/${padded_phase}-CONTEXT.md"
+pp_run query commit "docs(planning): smart discuss context" --phase "${PADDED_PHASE}" --files "${phase_dir}/${padded_phase}-CONTEXT.md"
 ```
 
 Display confirmation:

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.