@pareto4/pp-core 1.19.0 → 1.21.0

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

@@ -0,0 +1,1342 @@
+"use strict";
+/**
+ * Ceremony: the pure phase classifier core (Phase 37).
+ *
+ * ADR-457 build-at-publish: this TypeScript file is the SOURCE OF TRUTH. It
+ * compiles to the gitignored `pp-core/bin/lib/ceremony.cjs`; do NOT hand-edit
+ * the compiled output.
+ *
+ * Before any agent runs, a phase is classified by three questions: is a trust
+ * boundary crossed, is there a codebase to match, and is this serial
+ * single-concern work (D-01..D-04). The answers give a tier (D-05) and a
+ * decision for every gate (D-06..D-08); a forced full mode runs every gate as
+ * config says (D-09).
+ *
+ * Everything in this file is a pure function of its arguments: no file, git,
+ * config, environment or clock read, so the verdict is a function of its
+ * inputs (CLAS-07) and identical inputs serialize byte-identically (SC1). The
+ * module takes no tenant-identifying input. The I/O shell at the bottom of the
+ * file (marked) gathers the inputs and serves the `ceremony classify|get` CLI;
+ * everything above that marker stays pure.
+ *
+ * `serializeCeremony` writes the `{padded}-CEREMONY.md` text (D-11): the
+ * machine contract in the frontmatter, then the same table the CLI prints
+ * (D-13). `parseCeremony` reads it back and returns null on any contract
+ * violation, so a corrupt file falls back to full rather than to less ceremony.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EXCLUDED_PATH_SEGMENTS = exports.SOURCE_EXTENSIONS = exports.BACKEND_TERMS = exports.TRUST_TERMS = exports.CEREMONY_GATES = exports.CEREMONY_SCHEMA_VERSION = exports.MAX_SCAN_CHARS = exports.MAX_SUCCESS_CRITERIA = exports.MAX_REQ_IDS = exports.MIN_SOURCE_FILES = void 0;
+exports.scanTrustTerms = scanTrustTerms;
+exports.sanitizeEvidence = sanitizeEvidence;
+exports.classify = classify;
+exports.defaultFullVerdict = defaultFullVerdict;
+exports.renderCeremonyTable = renderCeremonyTable;
+exports.serializeCeremony = serializeCeremony;
+exports.parseCeremony = parseCeremony;
+exports.deriveCeremonyKeys = deriveCeremonyKeys;
+exports.ceremonyGateOpen = ceremonyGateOpen;
+exports.resolveGateConfig = resolveGateConfig;
+exports.parseReqIds = parseReqIds;
+exports.gatherInputs = gatherInputs;
+exports.readRecordedVerdict = readRecordedVerdict;
+exports.effectiveVerdict = effectiveVerdict;
+exports.cmdCeremony = cmdCeremony;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_child_process_1 = require("node:child_process");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const frontmatterMod = require("./frontmatter.cjs");
+const security_cjs_1 = require("./security.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const io = require("./io.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const phaseScopeMod = require("./phase-scope.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const phaseIdMod = require("./phase-id.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const planningWorkspaceMod = require("./planning-workspace.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const roadmapMod = require("./roadmap.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const configLoaderMod = require("./config-loader.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const capabilityActivationMod = require("./capability-activation.cjs");
+const { extractFrontmatter, spliceFrontmatter } = frontmatterMod;
+const { output, ERROR_REASON } = io;
+const { resolvePhaseForRead, resolvePhaseForWrite } = phaseScopeMod;
+const { extractPhaseToken } = phaseIdMod;
+const { planningPaths } = planningWorkspaceMod;
+const { getRoadmapPhaseWithFallback } = roadmapMod;
+const { loadConfig } = configLoaderMod;
+const { resolveConfigKey } = capabilityActivationMod;
+/** Explicitly typed so TypeScript narrows after a failing guard. */
+function error(message, reason) {
+    return io.error(message, reason);
+}
+// ─── Thresholds and limits (named constants; D-03, D-04, T-37-03) ────────────
+/** D-03: tracked source files outside `.planning/` that make a codebase to match. */
+exports.MIN_SOURCE_FILES = 20;
+/** D-04: at most this many requirement IDs for a serial single-concern phase. */
+exports.MAX_REQ_IDS = 3;
+/** D-04: at most this many success criteria for a serial single-concern phase. */
+exports.MAX_SUCCESS_CRITERIA = 4;
+/** T-37-03: each scanned source is truncated to this many characters. */
+exports.MAX_SCAN_CHARS = 200000;
+exports.CEREMONY_SCHEMA_VERSION = 1;
+const MAX_EVIDENCE_CHARS = 160;
+const MAX_LISTED_TERMS = 6;
+// Resolve the shared vocabulary through a candidate list so the module works in
+// every layout: the installed `pp-core/bin/shared/` first, then the source tree.
+const _require = require;
+const _gateCandidates = [
+    node_path_1.default.resolve(__dirname, '..', 'shared', 'ceremony-gates.json'),
+    node_path_1.default.resolve(__dirname, '..', '..', 'pp-core', 'bin', 'shared', 'ceremony-gates.json'),
+];
+function loadGateVocabulary() {
+    let lastErr = null;
+    for (const candidate of _gateCandidates) {
+        try {
+            return _require(candidate);
+        }
+        catch (e) {
+            const code = e?.code;
+            if (code !== 'MODULE_NOT_FOUND' && code !== 'ENOENT')
+                throw e;
+            lastErr = e;
+        }
+    }
+    throw new Error(`ceremony-gates.json not found. Tried:\n${_gateCandidates.map((p) => `  ${p}`).join('\n')}\nLast error: ${String(lastErr?.message)}`);
+}
+const _vocabulary = loadGateVocabulary();
+/** The gate keys in verdict-table order. */
+exports.CEREMONY_GATES = _vocabulary.gates.map((g) => g.key);
+const GATE_LABELS = Object.fromEntries(_vocabulary.gates.map((g) => [g.key, g.label]));
+// ─── Term sets (D-02, D-04) ──────────────────────────────────────────────────
+/**
+ * D-02: trust-boundary terms. A heuristic that only ever pushes ceremony UP:
+ * a phase worded without any of these terms reads as no trust boundary, and
+ * `--full`, `workflow.ceremony: full` or a ROADMAP `**Ceremony:** full` line
+ * restores the full stack (residual risk, stated in references/ceremony.md).
+ * A bare "token" is deliberately absent: pp-core's own phases talk about
+ * context tokens.
+ */
+exports.TRUST_TERMS = [
+    {
+        category: 'authentication and authorization',
+        terms: [
+            'auth', 'authentication', 'authorization', 'login', 'logout', 'sign-in', 'session',
+            'password', 'credential', 'OAuth', 'OIDC', 'SSO', 'JWT', 'bearer', 'API key',
+            'access token', 'refresh token', 'permission', 'role-based', 'RBAC', 'ACL', 'access control',
+        ],
+    },
+    {
+        category: 'secrets and crypto',
+        terms: ['secret', 'encrypt', 'decrypt', 'signing key', 'certificate'],
+    },
+    {
+        category: 'personal and payment data',
+        terms: ['PII', 'personal data', 'GDPR', 'payment', 'card', 'billing'],
+    },
+    {
+        category: 'untrusted input',
+        terms: [
+            'upload', 'webhook', 'user input', 'untrusted', 'external API', 'third-party callback', 'deserialize',
+            'SQL', 'shell exec', 'shell command', 'command injection', 'CORS', 'CSRF', 'cookie', 'multi-tenant',
+            'tenant isolation',
+        ],
+    },
+];
+/**
+ * CR-01: the word forms a term also matches, as a regex source without the word
+ * boundaries. A term not listed here matches its literal words plus a plural
+ * `s`. Each form is opt-in per term (a blanket suffix rule would let `auth` match
+ * "author"), and every alternation is flat, so matching stays linear (T-37-03).
+ * NEGATED (CR-01 iteration 2) lets "unauthorized", "unencrypted", "preauthorized",
+ * "reauthorize" and "non-authenticated" match: the word boundary stays in front of
+ * the prefix, and the stem after it is unchanged, so "author" still does not match.
+ */
+const NEGATED = '(?:un-?|non-?|re-?|pre-?)?';
+/**
+ * WR-02 (iteration 2): "log in" and "sign in" only in their authentication sense,
+ * so logging prose ("Write the logs in JSON", "structured logging in the
+ * executor", "commits signed in CI") stays unmatched. `authVerbForms` builds one
+ * term's alternation from seven named rules; each is tested on its own. Every
+ * lookaround is fixed or bounded, so matching stays linear (T-37-03).
+ */
+/** The verb followed by with, to, using, via, as, through, or the end of the clause. */
+const AUTH_VERB_AFTER = '(?=[ \\t]{1,8}(?:with|to|using|via|as|through)(?![A-Za-z0-9])|[.,;:!?)](?!\\S)|[ \\t]{0,8}(?:\\r?\\n|$))';
+/** A person or account right before the verb ("users log in", "who signed in"). */
+const AUTH_VERB_ACTOR = '(?<=(?<![A-Za-z0-9])(?:users?|customers?|members?|admins?|operators?|visitors?|employees?|staff|accounts?|people|who|you|they)[ \\t]{1,8})';
+/** A modal, "to" or "allow" right before the base verb ("can log in", "to sign in", "allow log in"). */
+const AUTH_VERB_MODAL = '(?<=(?<![A-Za-z0-9])(?:can|cannot|must|to|allows?|allowed|allowing)[ \\t]{1,8})';
+/**
+ * CR-02 (iteration 3): the spaced participle ("logged in users", "not signed in"),
+ * unless a place or a format follows ("logged in the audit file", "signed in CI",
+ * "logged in JSON"). Over-match ("logged in STATE.md") only adds ceremony.
+ */
+const AUTH_PARTICIPLE_NOT_PLACE = '(?![ \\t]{1,8}(?:CI|the|a|an|its|their|this|that|each|JSON|stdout|stderr)(?![A-Za-z0-9]))';
+/** CR-02 (iteration 3): the spaced noun before a UI or flow word ("sign in page", "log in screen"). */
+const AUTH_NOUN_UI = '(?=[ \\t-]{1,8}(?:pages?|screens?|forms?|flows?|buttons?|dialogs?|modals?|links?|prompts?|time|attempts?)(?![A-Za-z0-9]))';
+/** The closed nouns, unless they name a log artefact ("login lines", "sign-in files"). */
+const AUTH_NOUN_NOT_ARTEFACT = '(?![ \\t-]{1,8}(?:lines?|files?)(?![A-Za-z0-9]))';
+function authVerbForms(stem, past, progressive) {
+    const verb = `${stem}(?:s|${past}|${progressive})?[ \\t-]+in`;
+    return '(?:' + [
+        `${verb}${AUTH_VERB_AFTER}`,
+        `${AUTH_VERB_ACTOR}${verb}`,
+        `${AUTH_VERB_MODAL}${stem}[ \\t-]+in`,
+        `${stem}${past}-in`,
+        `${stem}${past}[ \\t]+in${AUTH_PARTICIPLE_NOT_PLACE}`,
+        `${stem}[ \\t-]+in${AUTH_NOUN_UI}`,
+        `${stem}-?ins?${AUTH_NOUN_NOT_ARTEFACT}`,
+    ].join('|') + ')';
+}
+const TERM_FORMS = {
+    authentication: `${NEGATED}authenticat(?:e|es|ed|ing|ion|ions|or|ors)`,
+    authorization: `${NEGATED}authori[sz](?:e|es|ed|ing|ation|ations|er|ers)`,
+    login: authVerbForms('log', 'ged', 'ging'),
+    logout: '(?:log(?:s|ged|ging)?[\\s-]+out|log-?outs?)',
+    'sign-in': authVerbForms('sign', 'ed', 'ing'),
+    encrypt: `${NEGATED}encrypt(?:s|ed|ing|ion|ions)?`,
+    decrypt: `${NEGATED}decrypt(?:s|ed|ing|ion|ions)?`,
+    upload: 'upload(?:s|ed|ing|er|ers)?',
+    deserialize: 'deseriali[sz](?:e|es|ed|ing|ation|ations|er|ers)',
+};
+/** D-04: a UI phase that also touches one of these is not single-concern. */
+exports.BACKEND_TERMS = [
+    'api', 'endpoint', 'database', 'schema', 'migration', 'server', 'backend', 'service',
+];
+function escapeRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * One case-insensitive regex per term (T-37-03): the term's TERM_FORMS entry, else
+ * the escaped literal words joined by `[\s-]+` and an optional plural `s`, with
+ * fixed lookarounds as the word boundary. No nested quantifier, so matching is
+ * linear in the (capped) source length.
+ */
+function termRegex(term) {
+    const form = Object.prototype.hasOwnProperty.call(TERM_FORMS, term) ? TERM_FORMS[term] : null;
+    const body = form ?? `${term.split(/[\s-]+/).filter(Boolean).map(escapeRegex).join('[\\s-]+')}s?`;
+    return new RegExp(`(?<![A-Za-z0-9])${body}(?![A-Za-z0-9])`, 'i');
+}
+const TRUST_REGEXES = exports.TRUST_TERMS.flatMap((cat) => cat.terms).map((term) => ({ term, re: termRegex(term) }));
+const BACKEND_REGEXES = exports.BACKEND_TERMS.map((term) => ({ term, re: termRegex(term) }));
+function scanTerms(list, sources) {
+    const texts = [
+        ['roadmap', String(sources.roadmap ?? '').slice(0, exports.MAX_SCAN_CHARS)],
+        ['requirements', String(sources.requirements ?? '').slice(0, exports.MAX_SCAN_CHARS)],
+        ['context', String(sources.context ?? '').slice(0, exports.MAX_SCAN_CHARS)],
+    ];
+    const out = [];
+    for (const { term, re } of list) {
+        for (const [source, text] of texts) {
+            if (re.test(text)) {
+                out.push({ term, source });
+                break;
+            }
+        }
+    }
+    return out;
+}
+/** D-02: the trust terms found in the sources, in TRUST_TERMS order, deduplicated. */
+function scanTrustTerms(sources) {
+    return scanTerms(TRUST_REGEXES, sources);
+}
+const QUESTIONS = ['trust_boundary', 'codebase_to_match', 'serial_single_concern'];
+const QUESTION_LABELS = {
+    trust_boundary: 'Trust boundary crossed',
+    codebase_to_match: 'Codebase to match',
+    serial_single_concern: 'Serial single-concern',
+};
+const TIERS = ['light', 'standard', 'heavy'];
+const MODES = ['proportional', 'full'];
+const FORCED_BY = ['flag', 'config', 'roadmap'];
+const DECISIONS = ['run', 'skip', 'off'];
+const REVIEW_DEPTHS = ['quick', 'standard', 'deep'];
+// ─── Evidence hygiene (T-37-02) ──────────────────────────────────────────────
+/**
+ * One safe line for the verdict file and the printed table: no newline, no ANSI
+ * or control character, no leading quote or bracket (the frontmatter helper would
+ * strip or misread it), at most 160 characters; an empty result is `none`.
+ */
+function sanitizeEvidence(value) {
+    let s = typeof value === 'string' ? value : typeof value === 'number' || typeof value === 'boolean' ? String(value) : '';
+    s = String((0, security_cjs_1.sanitizeForPrompt)(s) ?? '');
+    s = s.replace(/\u001b\[[0-9;?]*[ -/]*[@-~]/g, '').replace(/\u001b[@-Z\\-_]/g, '');
+    s = s.replace(/[\u0000-\u001f\u007f-\u009f]/g, ' ').replace(/\s+/g, ' ').trim();
+    s = s.replace(/^["'`[{#\s]+/, '').replace(/["'\s]+$/, '');
+    if (s.length > MAX_EVIDENCE_CHARS) {
+        s = s.slice(0, MAX_EVIDENCE_CHARS).replace(/["'\s]+$/, '');
+    }
+    return s === '' ? 'none' : s;
+}
+// ─── Gate rows (D-06..D-09) ──────────────────────────────────────────────────
+function normalizeDepth(depth) {
+    return REVIEW_DEPTHS.includes(depth) ? depth : 'standard';
+}
+function row(decision, reason, extra = {}) {
+    const out = { decision };
+    if (extra.depth !== undefined)
+        out.depth = extra.depth;
+    if (extra.rounds !== undefined)
+        out.rounds = extra.rounds;
+    if (extra.mode !== undefined)
+        out.mode = extra.mode;
+    out.reason = sanitizeEvidence(reason);
+    return out;
+}
+const OFF_KEY = {
+    research: 'workflow.research',
+    pattern_mapper: 'workflow.pattern_mapper',
+    security: 'workflow.security_enforcement',
+    plan_check: 'workflow.plan_check',
+    code_review: 'workflow.code_review',
+    verifier: 'workflow.verifier',
+    nyquist: 'workflow.nyquist_validation',
+    ui_review: 'workflow.ui_review',
+    ui: 'workflow.ui_phase and workflow.ui_safety_gate',
+    vault: 'vault',
+};
+function off(key) {
+    return row('off', `${OFF_KEY[key] ?? key} is off in config`);
+}
+function buildGates(ctx) {
+    const { full, tier, trust, codebase, flags, cfg } = ctx;
+    const prop = !full;
+    const light = prop && tier === 'light';
+    const reviewDepth = normalizeDepth(cfg.code_review_depth);
+    const gates = {};
+    // research: a flag decides first, then config, then the codebase rule.
+    if (flags.skipResearch)
+        gates.research = row('skip', 'flag --skip-research');
+    else if (flags.research)
+        gates.research = row('run', 'flag --research');
+    else if (!cfg.research)
+        gates.research = off('research');
+    else if (prop && !codebase) {
+        // WR-05: plan-time VALIDATION.md is built from RESEARCH.md, so it skips with research.
+        // The checker's Dimension 8 does not: it runs without RESEARCH.md (Phase 38, D-05).
+        gates.research = row('skip', cfg.nyquist
+            ? 'no codebase to match; plan-time VALIDATION.md skips with it'
+            : 'no codebase to match');
+    }
+    else
+        gates.research = row('run', full ? 'full mode' : 'codebase to match');
+    if (!cfg.pattern_mapper)
+        gates.pattern_mapper = off('pattern_mapper');
+    else if (prop && !codebase)
+        gates.pattern_mapper = row('skip', 'no codebase to match');
+    else
+        gates.pattern_mapper = row('run', full ? 'full mode' : 'codebase to match');
+    if (!cfg.security)
+        gates.threat_model = off('security');
+    else if (prop && !trust)
+        gates.threat_model = row('skip', 'no trust boundary crossed');
+    else
+        gates.threat_model = row('run', full ? 'full mode' : 'trust boundary crossed');
+    if (flags.skipVerify)
+        gates.plan_check = row('skip', 'flag --skip-verify');
+    else if (!cfg.plan_check)
+        gates.plan_check = off('plan_check');
+    else if (light) {
+        gates.plan_check = row('run', 'light tier: one blockers-only round, one targeted revision, no re-check', { rounds: 1, mode: 'blockers-only' });
+    }
+    else {
+        gates.plan_check = row('run', full ? 'full mode: up to 3 rounds' : 'standard or heavy tier: up to 3 rounds', { rounds: 3, mode: 'standard' });
+    }
+    if (!cfg.code_review)
+        gates.code_review = off('code_review');
+    else if (light)
+        gates.code_review = row('run', 'light tier: quick depth', { depth: 'quick' });
+    else
+        gates.code_review = row('run', 'configured depth', { depth: reviewDepth });
+    if (!cfg.verifier)
+        gates.verifier = off('verifier');
+    else if (light && !trust)
+        gates.verifier = row('run', 'light tier: skips the data-flow trace and spot-checks', { depth: 'light' });
+    else
+        gates.verifier = row('run', full ? 'full mode' : 'standard, heavy tier or trust boundary: full depth', { depth: 'full' });
+    if (!cfg.security)
+        gates.security_review = off('security');
+    else if (prop && !trust)
+        gates.security_review = row('skip', 'no trust boundary crossed');
+    else
+        gates.security_review = row('run', full ? 'full mode' : 'trust boundary crossed');
+    if (!cfg.nyquist)
+        gates.nyquist = off('nyquist');
+    else if (light)
+        gates.nyquist = row('skip', 'light tier');
+    else
+        gates.nyquist = row('run', full ? 'full mode' : 'standard or heavy tier');
+    if (!cfg.ui_review)
+        gates.ui_review = off('ui_review');
+    else if (light)
+        gates.ui_review = row('skip', 'light tier');
+    else
+        gates.ui_review = row('run', full ? 'full mode' : 'standard or heavy tier');
+    if (!cfg.ui_phase && !cfg.ui_safety_gate)
+        gates.ui = off('ui');
+    else {
+        const f = ctx.frontend === null ? '' : ` (frontend: ${ctx.frontend ? 'yes' : 'no'})`;
+        gates.ui = row('run', `follows frontend detection${f}`);
+    }
+    if (!cfg.vault)
+        gates.vault = off('vault');
+    else
+        gates.vault = row('run', 'client standards govern every phase');
+    // Return in table order whatever the order above.
+    const ordered = {};
+    for (const key of exports.CEREMONY_GATES)
+        ordered[key] = gates[key];
+    return ordered;
+}
+// ─── Classifier ──────────────────────────────────────────────────────────────
+function prefixOf(id) {
+    const i = id.lastIndexOf('-');
+    return i > 0 ? id.slice(0, i) : id;
+}
+function plural(n, one, many) {
+    return n === 1 ? one : many;
+}
+/** The three questions, the tier, every gate row and the warnings. Pure. */
+function classify(i) {
+    const sources = {
+        roadmap: String(i.roadmapText ?? ''),
+        requirements: String(i.requirementText ?? ''),
+        context: String(i.contextText ?? ''),
+    };
+    // CR-02: input the shell could not read or parse never reads as a small
+    // phase: each gap makes it not single-concern (so at least standard) and names
+    // itself in the evidence and the warnings. WR-03 (iteration 2): an explicit
+    // `TBD`, `None` or `N/A` claims nothing, so it and a /pp-phase add|insert
+    // template plan standard, not heavy. CR-01 (iteration 3): a missing or
+    // unreadable section, or (WR-01) a mapped ID with no REQUIREMENTS.md line,
+    // cannot rule a trust boundary out, so it answers crossed.
+    const reqIds = Array.isArray(i.reqIds) ? i.reqIds.map(String) : [];
+    const criteria = Math.max(0, Math.trunc(Number(i.successCriteria) || 0));
+    const withoutText = Array.isArray(i.requirementIdsWithoutText) ? i.requirementIdsWithoutText.map(String) : [];
+    const sectionMissing = sources.roadmap.trim() === '';
+    const singleGaps = [];
+    if (sectionMissing)
+        singleGaps.push('ROADMAP phase section not found');
+    if (reqIds.length === 0)
+        singleGaps.push('no requirement IDs parsed');
+    if (withoutText.length > 0)
+        singleGaps.push(`no REQUIREMENTS.md line for ${withoutText.join(', ')}`);
+    if (!sectionMissing && criteria === 0)
+        singleGaps.push('no success criteria parsed');
+    if (i.frontend === null)
+        singleGaps.push('frontend detection failed');
+    // D-02 trust boundary: a matched term, or input that cannot rule one out.
+    const trustHits = scanTrustTerms(sources);
+    const trustGaps = [];
+    if (sectionMissing)
+        trustGaps.push('phase section unreadable');
+    // WR-01 (iteration 3): a named ID whose text was never read is unread input too.
+    if (withoutText.length > 0) {
+        const extra = withoutText.length > MAX_LISTED_TERMS ? `, +${withoutText.length - MAX_LISTED_TERMS} more` : '';
+        trustGaps.push(`requirement text unread for ${withoutText.slice(0, MAX_LISTED_TERMS).join(', ')}${extra}`);
+    }
+    const trust = trustHits.length > 0 || trustGaps.length > 0;
+    const listed = trustHits.slice(0, MAX_LISTED_TERMS).map((m) => `${m.term} (${m.source})`);
+    const more = trustHits.length > MAX_LISTED_TERMS ? `, +${trustHits.length - MAX_LISTED_TERMS} more` : '';
+    const trustEvidence = trustHits.length > 0
+        ? `matched: ${listed.join(', ')}${more}`
+        : trustGaps.length > 0
+            ? `${trustGaps.join('; ')} — failing toward ceremony`
+            : singleGaps.length > 0
+                ? 'no trust term in the input read; input incomplete (see warning)'
+                : 'no trust term in roadmap, requirements or context';
+    // D-03 codebase to match.
+    const completed = Math.max(0, Math.trunc(Number(i.completedOtherPhases) || 0));
+    const archived = Math.max(0, Math.trunc(Number(i.archivedMilestones) || 0));
+    const files = i.trackedSourceFiles;
+    const unavailable = files === null || files === undefined;
+    const codebase = unavailable || files >= exports.MIN_SOURCE_FILES || completed > 0 || archived > 0;
+    const tail = `${completed} completed other ${plural(completed, 'phase', 'phases')}; ${archived} archived ${plural(archived, 'milestone', 'milestones')}`;
+    const codebaseEvidence = unavailable
+        ? `git inventory unavailable; ${tail}`
+        : `${files} tracked source ${plural(files, 'file', 'files')} (threshold ${exports.MIN_SOURCE_FILES}); ${tail}`;
+    // D-04 serial single-concern.
+    const prefixes = new Set(reqIds.map(prefixOf));
+    const backendHits = i.frontend ? scanTerms(BACKEND_REGEXES, sources).map((m) => m.term) : [];
+    const uiBackend = Boolean(i.frontend) && backendHits.length > 0;
+    const surface = i.frontend === null
+        ? 'unknown'
+        : !i.frontend ? 'none' : uiBackend ? `ui + backend (${backendHits.slice(0, 4).join(', ')})` : 'ui only';
+    const single = singleGaps.length === 0 &&
+        reqIds.length <= exports.MAX_REQ_IDS && prefixes.size <= 1 && criteria <= exports.MAX_SUCCESS_CRITERIA && !uiBackend;
+    const singleEvidence = `${reqIds.length} requirement ${plural(reqIds.length, 'ID', 'IDs')} (max ${exports.MAX_REQ_IDS}); ` +
+        `${prefixes.size} ${plural(prefixes.size, 'prefix', 'prefixes')} (max 1); ` +
+        `${criteria} success ${plural(criteria, 'criterion', 'criteria')} (max ${exports.MAX_SUCCESS_CRITERIA}); UI surface ${surface}` +
+        (singleGaps.length > 0 ? `; not single-concern: ${singleGaps.join('; ')}` : '');
+    // D-05 tier.
+    const tier = single && !trust ? 'light' : !single && trust ? 'heavy' : 'standard';
+    // D-09 mode.
+    const warnings = [];
+    if (singleGaps.length > 0)
+        warnings.push(`input incomplete, failing toward ceremony: ${singleGaps.join('; ')}`);
+    const forcedAll = [];
+    if (i.flags.full)
+        forcedAll.push('flag');
+    const cm = i.configMode;
+    if (cm !== undefined && cm !== null && cm !== 'proportional') {
+        forcedAll.push('config');
+        if (cm !== 'full') {
+            warnings.push(`workflow.ceremony '${sanitizeEvidence(cm)}' is not proportional or full; treated as full`);
+        }
+    }
+    if (i.roadmapForcesFull)
+        forcedAll.push('roadmap');
+    else if (typeof i.roadmapCeremonyIgnored === 'string') {
+        warnings.push(`ROADMAP Ceremony line '${sanitizeEvidence(i.roadmapCeremonyIgnored)}' is not full; ignored`);
+    }
+    const full = forcedAll.length > 0;
+    if (!i.gateConfig.security && trust) {
+        warnings.push('security enforcement is off in config but a trust boundary is crossed');
+    }
+    const gates = buildGates({
+        full, tier, trust, codebase, frontend: i.frontend === null ? null : Boolean(i.frontend), flags: i.flags, cfg: i.gateConfig,
+    });
+    return {
+        schema_version: 1,
+        phase: String(i.phase),
+        mode: full ? 'full' : 'proportional',
+        forced_by: forcedAll.length > 0 ? forcedAll[0] : null,
+        forced_by_all: forcedAll,
+        tier,
+        answers: {
+            trust_boundary: { value: trust, evidence: sanitizeEvidence(trustEvidence) },
+            codebase_to_match: { value: codebase, evidence: sanitizeEvidence(codebaseEvidence) },
+            serial_single_concern: { value: single, evidence: sanitizeEvidence(singleEvidence) },
+        },
+        gates,
+        warnings,
+    };
+}
+/**
+ * D-12, D-15: the verdict that applies when none is recorded. Full mode, every
+ * enabled gate at full depth, so a missing verdict never lowers ceremony.
+ */
+function defaultFullVerdict(phase, gateConfig) {
+    const none = 'no recorded verdict';
+    return {
+        schema_version: 1,
+        phase: String(phase),
+        mode: 'full',
+        forced_by: null,
+        forced_by_all: [],
+        tier: 'heavy',
+        answers: {
+            trust_boundary: { value: true, evidence: none },
+            codebase_to_match: { value: true, evidence: none },
+            serial_single_concern: { value: false, evidence: none },
+        },
+        gates: buildGates({
+            full: true,
+            tier: 'heavy',
+            trust: true,
+            codebase: true,
+            frontend: null,
+            flags: { full: false, research: false, skipResearch: false, skipVerify: false },
+            cfg: gateConfig,
+        }),
+        warnings: [],
+    };
+}
+// ─── Table (D-13) ────────────────────────────────────────────────────────────
+function cell(s) {
+    return sanitizeEvidence(s).replace(/\|/g, '\\|');
+}
+function decisionText(g) {
+    const parts = [];
+    if (g.depth !== undefined)
+        parts.push(`depth ${g.depth}`);
+    if (g.rounds !== undefined)
+        parts.push(`rounds ${g.rounds}`);
+    if (g.mode !== undefined)
+        parts.push(`mode ${g.mode}`);
+    return parts.length > 0 ? `${g.decision} (${parts.join(', ')})` : g.decision;
+}
+/** Plain text, no ANSI: the header, the answers table and the gate table. */
+function renderCeremonyTable(v) {
+    let mode = v.mode;
+    if (v.mode === 'full' && v.forced_by) {
+        const rest = (v.forced_by_all || []).filter((s) => s !== v.forced_by);
+        mode = `full, forced by ${v.forced_by}${rest.length > 0 ? `; also ${rest.join(', ')}` : ''}`;
+    }
+    const lines = [`Ceremony: ${v.tier} (${mode})`];
+    for (const w of v.warnings || [])
+        lines.push(`Warning: ${sanitizeEvidence(w)}`);
+    lines.push('', '| Question | Answer | Evidence |', '| --- | --- | --- |');
+    for (const q of QUESTIONS) {
+        const a = v.answers[q];
+        lines.push(`| ${QUESTION_LABELS[q]} | ${a.value ? 'yes' : 'no'} | ${cell(a.evidence)} |`);
+    }
+    lines.push('', '| Gate | Decision | Reason |', '| --- | --- | --- |');
+    for (const key of exports.CEREMONY_GATES) {
+        const g = v.gates[key];
+        if (!g)
+            continue;
+        lines.push(`| ${GATE_LABELS[key] ?? key} | ${decisionText(g)} | ${cell(g.reason)} |`);
+    }
+    return `${lines.join('\n')}\n`;
+}
+// ─── CEREMONY.md text (D-11) ─────────────────────────────────────────────────
+function gateFrontmatter(g) {
+    const out = { decision: g.decision };
+    if (g.depth !== undefined)
+        out.depth = sanitizeEvidence(g.depth);
+    if (g.rounds !== undefined)
+        out.rounds = g.rounds;
+    if (g.mode !== undefined)
+        out.mode = sanitizeEvidence(g.mode);
+    out.reason = sanitizeEvidence(g.reason);
+    return out;
+}
+/**
+ * The `{padded}-CEREMONY.md` text: the D-11 frontmatter in a fixed key order, then
+ * the table body. `forced_by` is written as the string `none` when null (the
+ * frontmatter helper drops null). No timestamp, so identical verdicts serialize
+ * byte-identically. `warnings` and `forced_by_all` live in the body only.
+ */
+function serializeCeremony(v) {
+    const answers = {};
+    for (const q of QUESTIONS) {
+        answers[q] = { value: v.answers[q].value, evidence: sanitizeEvidence(v.answers[q].evidence) };
+    }
+    const gates = {};
+    for (const key of exports.CEREMONY_GATES) {
+        const g = v.gates[key];
+        if (g)
+            gates[key] = gateFrontmatter(g);
+    }
+    const front = {
+        schema_version: String(exports.CEREMONY_SCHEMA_VERSION),
+        phase: sanitizeEvidence(v.phase),
+        mode: v.mode,
+        forced_by: v.forced_by ?? 'none',
+        tier: v.tier,
+        answers,
+        gates,
+    };
+    return spliceFrontmatter(renderCeremonyTable(v), front);
+}
+function isRecord(x) {
+    return typeof x === 'object' && x !== null && !Array.isArray(x);
+}
+function nonEmpty(x) {
+    return typeof x === 'string' && x.length > 0;
+}
+/** The text after the CEREMONY.md frontmatter: the table the CLI printed. */
+function bodyOf(text) {
+    const m = text.match(/^---\r?\n[\s\S]+?\r?\n---\r?\n(?:\r?\n)?/);
+    return m ? text.slice(m[0].length) : text;
+}
+const MAX_RECORDED_WARNINGS = 10;
+/**
+ * WR-01: the body-only parts of a verdict, read back from the table header so the
+ * table can be re-rendered from the frontmatter: the other forcing sources named
+ * after `forced by`, and the `Warning:` lines, each re-sanitized. Anything that
+ * does not fit is dropped; neither can open or close a gate.
+ */
+function bodyExtras(text, forcedBy) {
+    const lines = bodyOf(text).split(/\r?\n/);
+    const forcedAll = forcedBy ? [forcedBy] : [];
+    const also = forcedBy ? /^Ceremony: \S+ \(full, forced by \S+; also ([a-z, ]+)\)$/.exec(lines[0] ?? '') : null;
+    if (also) {
+        for (const s of also[1].split(', ')) {
+            if (FORCED_BY.includes(s) && !forcedAll.includes(s))
+                forcedAll.push(s);
+        }
+    }
+    const warnings = [];
+    for (let k = 1; k < lines.length && lines[k] !== '' && warnings.length < MAX_RECORDED_WARNINGS; k++) {
+        const w = /^Warning: (.+)$/.exec(lines[k]);
+        if (w)
+            warnings.push(sanitizeEvidence(w[1]));
+    }
+    return { forcedAll, warnings };
+}
+/**
+ * WR-01: true when every row follows from the verdict's own answers, tier and
+ * mode, as `classify` would have written it. A skip is allowed only where the
+ * rules allow one, and the light-tier depths only at a proportional light tier.
+ * A `flag --skip-research` or `flag --skip-verify` reason is never accepted:
+ * WR-06 keeps those run-only flags out of every recorded verdict, so a file
+ * carrying one was edited by hand (WR-01, iteration 2).
+ */
+function verdictConsistent(mode, tier, forcedBy, answers, gates) {
+    const trust = answers.trust_boundary.value;
+    const codebase = answers.codebase_to_match.value;
+    const single = answers.serial_single_concern.value;
+    if (tier !== (single && !trust ? 'light' : !single && trust ? 'heavy' : 'standard'))
+        return false;
+    const prop = mode === 'proportional';
+    if (prop && forcedBy !== null)
+        return false;
+    const light = prop && tier === 'light';
+    const skipAllowed = new Map([
+        ['research', prop && !codebase],
+        ['pattern_mapper', prop && !codebase],
+        ['threat_model', prop && !trust],
+        ['security_review', prop && !trust],
+        ['plan_check', false],
+        ['nyquist', light],
+        ['ui_review', light],
+    ]);
+    for (const [key, g] of Object.entries(gates)) {
+        if (g.decision === 'skip' && skipAllowed.get(key) !== true)
+            return false;
+    }
+    const v = gates.verifier;
+    if (v?.depth === 'light' && !(light && !trust))
+        return false;
+    const pc = gates.plan_check;
+    if ((pc?.rounds === 1 || pc?.mode === 'blockers-only') && !light)
+        return false;
+    const cr = gates.code_review;
+    if (cr?.depth === 'quick' && !light && cr.reason !== 'configured depth')
+        return false;
+    return true;
+}
+/**
+ * The verdict in a CEREMONY.md text, or null on any contract violation (T-37-05),
+ * including a verdict whose rows do not follow from its own answers (WR-01).
+ */
+function parseCeremony(text) {
+    if (typeof text !== 'string' || text === '')
+        return null;
+    let fm;
+    try {
+        fm = extractFrontmatter(text);
+    }
+    catch {
+        return null;
+    }
+    if (fm.schema_version !== String(exports.CEREMONY_SCHEMA_VERSION))
+        return null;
+    if (!nonEmpty(fm.phase))
+        return null;
+    if (typeof fm.mode !== 'string' || !MODES.includes(fm.mode))
+        return null;
+    if (typeof fm.tier !== 'string' || !TIERS.includes(fm.tier))
+        return null;
+    let forcedBy = null;
+    if (fm.forced_by !== undefined && fm.forced_by !== 'none') {
+        if (typeof fm.forced_by !== 'string' || !FORCED_BY.includes(fm.forced_by))
+            return null;
+        forcedBy = fm.forced_by;
+    }
+    if (!isRecord(fm.answers) || !isRecord(fm.gates))
+        return null;
+    const answers = {};
+    for (const q of QUESTIONS) {
+        const a = fm.answers[q];
+        if (!isRecord(a))
+            return null;
+        if (a.value !== 'true' && a.value !== 'false')
+            return null;
+        if (!nonEmpty(a.evidence))
+            return null;
+        answers[q] = { value: a.value === 'true', evidence: a.evidence };
+    }
+    const gates = {};
+    for (const key of exports.CEREMONY_GATES) {
+        const g = fm.gates[key];
+        if (!isRecord(g))
+            return null;
+        if (typeof g.decision !== 'string' || !DECISIONS.includes(g.decision))
+            return null;
+        if (!nonEmpty(g.reason))
+            return null;
+        const parsed = { decision: g.decision, reason: g.reason };
+        const ordered = { decision: parsed.decision };
+        if (g.depth !== undefined) {
+            if (!nonEmpty(g.depth))
+                return null;
+            ordered.depth = g.depth;
+        }
+        if (g.rounds !== undefined) {
+            const n = Number(g.rounds);
+            if (!Number.isInteger(n) || n < 1)
+                return null;
+            ordered.rounds = n;
+        }
+        if (g.mode !== undefined) {
+            if (!nonEmpty(g.mode))
+                return null;
+            ordered.mode = g.mode;
+        }
+        ordered.reason = parsed.reason;
+        gates[key] = ordered;
+    }
+    if (!verdictConsistent(fm.mode, fm.tier, forcedBy, answers, gates))
+        return null;
+    const extras = bodyExtras(text, forcedBy);
+    return {
+        schema_version: 1,
+        phase: fm.phase,
+        mode: fm.mode,
+        forced_by: forcedBy,
+        forced_by_all: extras.forcedAll,
+        tier: fm.tier,
+        answers,
+        gates,
+        warnings: extras.warnings,
+    };
+}
+// ─── Derivations the callers fold in (D-15) ──────────────────────────────────
+/**
+ * The flat keys `init` returns and workflows read. Anything unexpected in the
+ * verdict reads as the full value, never the lighter one.
+ */
+function deriveCeremonyKeys(verdict, configuredReviewDepth) {
+    const prop = verdict.mode === 'proportional';
+    const pc = verdict.gates?.plan_check;
+    const oneRound = prop && pc?.decision === 'run' && pc.rounds === 1;
+    const lightVerifier = prop && verdict.gates?.verifier?.decision === 'run' && verdict.gates.verifier.depth === 'light';
+    const cr = verdict.gates?.code_review;
+    // WR-04 (iteration 2): the verdict lowers review depth only at the light tier.
+    // At standard or heavy the recorded depth is the config of plan time, so the
+    // live config decides; a stale verdict never lowers review below it.
+    const quick = prop && verdict.tier === 'light' && cr?.decision === 'run' && cr.depth === 'quick';
+    return {
+        ceremony_tier: verdict.tier,
+        ceremony_mode: verdict.mode,
+        plan_check_rounds: oneRound ? 1 : 3,
+        plan_check_mode: oneRound && pc?.mode === 'blockers-only' ? 'blockers-only' : 'standard',
+        verifier_depth: lightVerifier ? 'light' : 'full',
+        code_review_depth: quick ? 'quick' : normalizeDepth(configuredReviewDepth),
+    };
+}
+/**
+ * True unless the verdict is a proportional one that skips this gate. A null
+ * verdict, full mode, an unknown gate and an `off` row (config, not ceremony)
+ * all read as open (D-12, D-15).
+ */
+function ceremonyGateOpen(verdict, gate) {
+    if (!verdict || verdict.mode !== 'proportional')
+        return true;
+    const g = verdict.gates?.[gate];
+    if (!g)
+        return true;
+    return g.decision !== 'skip';
+}
+// ─── I/O shell (D-01, D-10, D-11, D-12, D-15) ────────────────────────────────
+//
+// Everything below reads the repository through its existing owners and serves
+// the `ceremony classify|get` CLI. Nothing above this marker reads a file, git,
+// the environment or a clock. The shell reads no client-identifying input.
+/** D-03 / research A7: file extensions that count as source. */
+exports.SOURCE_EXTENSIONS = [
+    'js', 'cjs', 'mjs', 'jsx', 'ts', 'cts', 'mts', 'tsx', 'py', 'rb', 'go', 'rs', 'java', 'kt',
+    'cs', 'php', 'swift', 'c', 'h', 'cpp', 'hpp', 'vue', 'svelte', 'sh',
+];
+/** D-03: a path with one of these segments is vendored, generated or planning state. */
+exports.EXCLUDED_PATH_SEGMENTS = ['.planning', 'node_modules', 'vendor', 'dist', 'build'];
+const REQUIREMENTS_HEADER_RE = /^\*\*Requirements:?\*\*[^\S\n]*:?[^\S\n]*([^\n]*)$/;
+const SUCCESS_CRITERIA_HEADER_RE = /^\*\*Success Criteria:?\*\*[^\n]*:/i;
+/** A list item: a number with `.` or `)`, or a `-`, `*` or `+` bullet, then whitespace. */
+const LIST_ITEM_RE = /^[ \t]*(?:\d+[.)]|[-*+])[ \t]+(\S[^\n]*)$/;
+const PLANS_LINE_RE = /^\*\*Plans:?\*\*/m;
+/**
+ * CR-03: a `**Ceremony:** value`, `**Ceremony**: value` or `**Ceremony: value**`
+ * line, optionally a list item; group 1 is the value with any bold markers left.
+ */
+const CEREMONY_LINE_RE = /^[ \t]*(?:[-*+][ \t]+)?\*\*Ceremony(?::\*\*|\*\*[ \t]*:|:)[ \t]*([^\n]*)$/gim;
+const DEFERRED_RE = /<deferred>[\s\S]*?<\/deferred>/gi;
+const CHECKBOX_PHASE_RE = /^\s*-\s*\[[xX]\]\s*(?:\*\*)?Phase\s+([0-9]+(?:\.[0-9]+)*)/gm;
+const GIT_TIMEOUT_MS = 30000;
+const GIT_MAX_BUFFER = 256 * 1024 * 1024;
+/**
+ * The only config read. `workflow.ceremony` and every capability-owned gate key go
+ * through `resolveConfigKey` (loadConfig drops keys it does not know); the checker
+ * and verifier toggles come from loadConfig's flat names.
+ */
+function resolveGateConfig(cwd) {
+    const config = loadConfig(cwd);
+    const registry = _require('./capability-registry.cjs');
+    const read = (key) => resolveConfigKey(key, { config, cwd, registry });
+    const flag = (key) => {
+        const r = read(key);
+        return r.found ? Boolean(r.value) : false;
+    };
+    const depth = read('workflow.code_review_depth');
+    const mode = read('workflow.ceremony');
+    return {
+        research: flag('workflow.research'),
+        pattern_mapper: flag('workflow.pattern_mapper'),
+        plan_check: Boolean(config['plan_checker']),
+        verifier: Boolean(config['verifier']),
+        code_review: flag('workflow.code_review'),
+        nyquist: flag('workflow.nyquist_validation'),
+        security: flag('workflow.security_enforcement'),
+        ui_phase: flag('workflow.ui_phase'),
+        ui_safety_gate: flag('workflow.ui_safety_gate'),
+        ui_review: flag('workflow.ui_review'),
+        vault: flag('vault.enabled'),
+        code_review_depth: depth.found && typeof depth.value === 'string' ? depth.value : 'standard',
+        ceremonyMode: mode.found ? mode.value : undefined,
+    };
+}
+/** `1`, `01` and `1.0` compare equal; anything else compares by upper-cased text. */
+function normalizePhaseNumber(token) {
+    const parts = String(token).split('.');
+    if (parts.every((p) => /^\d+$/.test(p)))
+        return parts.map((p) => String(parseInt(p, 10))).join('.');
+    return String(token).toUpperCase();
+}
+function readTextOrEmpty(file) {
+    try {
+        return node_fs_1.default.readFileSync(file, 'utf8');
+    }
+    catch {
+        return '';
+    }
+}
+function isSummaryName(name) {
+    return name.endsWith('-SUMMARY.md') || name === 'SUMMARY.md';
+}
+function listNames(dir) {
+    try {
+        return node_fs_1.default.readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+}
+/** Tracked source files outside planning and vendored paths; null when git cannot answer. */
+function countTrackedSourceFiles(cwd) {
+    let out;
+    try {
+        out = (0, node_child_process_1.execFileSync)('git', ['ls-files', '-z'], {
+            cwd,
+            encoding: 'utf8',
+            maxBuffer: GIT_MAX_BUFFER,
+            timeout: GIT_TIMEOUT_MS,
+            windowsHide: true,
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+    }
+    catch {
+        return null;
+    }
+    let count = 0;
+    for (const file of out.split('\0')) {
+        if (file === '')
+            continue;
+        const segments = file.split('/');
+        const name = segments[segments.length - 1];
+        if (segments.some((s) => exports.EXCLUDED_PATH_SEGMENTS.includes(s)))
+            continue;
+        if (name.includes('.min.'))
+            continue;
+        const dot = name.lastIndexOf('.');
+        if (dot <= 0)
+            continue;
+        if (exports.SOURCE_EXTENSIONS.includes(name.slice(dot + 1).toLowerCase()))
+            count++;
+    }
+    return count;
+}
+/** null when detection throws (CR-02): the classifier then cannot rule out UI + backend. */
+function frontendOf(cwd, phase) {
+    try {
+        const router = _require('./check-command-router.cjs');
+        return Boolean(router.computeUiPlanGate(cwd, phase).frontend);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The list items under a header line: blank lines and indented continuation
+ * lines are passed over, the first other line ends the list.
+ */
+function listItemsAfter(lines, start) {
+    const items = [];
+    for (let k = start; k < lines.length; k++) {
+        const line = lines[k];
+        if (line.trim() === '')
+            continue;
+        const m = line.match(LIST_ITEM_RE);
+        if (m)
+            items.push(m[1]);
+        else if (!/^[ \t]/.test(line))
+            break;
+    }
+    return items;
+}
+/**
+ * CR-02 (iteration 2): the separators between requirement IDs: a comma,
+ * semicolon, slash, ampersand or the word "and" (not inside an ID like AND-01).
+ * The pieces are trimmed by the caller, which is why the pattern carries no
+ * whitespace quantifier (37-W-1: the leading one was quadratic on a long
+ * whitespace run). Whitespace is never part of a separator, so the set of
+ * separator matches is the same as with the quantifiers.
+ */
+const REQ_ID_SEPARATOR_RE = /(?:[,;/&]|(?<![\w-])and(?![\w-]))/i;
+/**
+ * The characters stripped from the end of a token before the ID-shape test. An
+ * index loop strips them: an end-anchored `+` class was quadratic on a long
+ * punctuation run (37-W-1).
+ */
+const REQ_ID_TRAILING_PUNCT = ':;.,!?\'"';
+/**
+ * WR-02 (iteration 3): a requirement ID: a letter, letters or digits, a hyphen,
+ * digits (SLUG-01, VSEC-02), kept in the case it is written in. Nothing else on
+ * the line is an ID, so a placeholder (`TBD`, `None`, `N/A`) and prose map none.
+ */
+const REQ_ID_SHAPE_RE = /^[A-Za-z][A-Za-z0-9]*-\d+$/;
+/**
+ * CR-03 (iteration 3): a range of one prefix ("DATA-01 – DATA-03", "-", "—",
+ * "..", "to", "through", "thru"); group 1 is the prefix, 2 and 3 the endpoints.
+ */
+const REQ_ID_RANGE_RE = /\b([A-Za-z][A-Za-z0-9]*)-(\d+)\s*(?:–|—|-|\.\.|to|through|thru)\s*\1-(\d+)\b/gi;
+/** The most IDs one range expands into; a wider or reversed range is an input gap. */
+const MAX_RANGE_IDS = 50;
+/**
+ * The requirement IDs in one text: every ID-shaped token, in order. A range
+ * expands into every ID in it; one past MAX_RANGE_IDS (or reversed) stays a
+ * single `DATA-01..DATA-99` entry that no REQUIREMENTS.md line names, so it is
+ * reported as unread input. Prose words are dropped, never read as IDs; a line
+ * with no ID at all reads as zero IDs, which is not single-concern.
+ */
+function reqIdsIn(text) {
+    const ids = [];
+    // `N/A` is a placeholder, not the IDs `N` and `A`: drop it before the slash splits it.
+    let cleaned = text.replace(/[[\]*`]/g, '').replace(/(?<![\w-])N\/A(?![\w-])/gi, ' ');
+    cleaned = cleaned.replace(REQ_ID_RANGE_RE, (_m, p, a, b) => {
+        const lo = parseInt(a, 10);
+        const hi = parseInt(b, 10);
+        if (hi < lo || hi - lo + 1 > MAX_RANGE_IDS) {
+            ids.push(`${p}-${a}..${p}-${b}`);
+            return ' , ';
+        }
+        return Array.from({ length: hi - lo + 1 }, (_v, k) => `${p}-${String(lo + k).padStart(a.length, '0')}`).join(', ');
+    });
+    for (const piece of cleaned.split(REQ_ID_SEPARATOR_RE)) {
+        for (const token of piece.trim().split(/[\s()]+/)) {
+            let end = token.length;
+            while (end > 0 && REQ_ID_TRAILING_PUNCT.includes(token[end - 1]))
+                end--;
+            const t = token.slice(0, end);
+            if (REQ_ID_SHAPE_RE.test(t))
+                ids.push(t);
+        }
+    }
+    return [...new Set(ids)];
+}
+/** CR-02: the IDs on the `**Requirements**` line, or in the list under it. */
+function parseReqIds(lines) {
+    const at = lines.findIndex((l) => REQUIREMENTS_HEADER_RE.test(l));
+    if (at < 0)
+        return [];
+    const inline = lines[at].match(REQUIREMENTS_HEADER_RE)[1].trim();
+    if (inline !== '')
+        return reqIdsIn(inline);
+    return listItemsAfter(lines, at + 1).flatMap((item) => reqIdsIn(item.replace(/^\[[ xX]\][ \t]*/, '').split(':')[0]));
+}
+/** CR-02: numbered or bulleted items under `**Success Criteria**`. */
+function countSuccessCriteria(lines) {
+    const at = lines.findIndex((l) => SUCCESS_CRITERIA_HEADER_RE.test(l));
+    return at < 0 ? 0 : listItemsAfter(lines, at + 1).length;
+}
+/**
+ * CR-03: the `**Ceremony**` lines anywhere in the phase section (Plans list
+ * included). `forcesFull` when any reads `full`; else `ignored` is the first value.
+ */
+function readCeremonyMarker(section) {
+    let ignored = null;
+    for (const m of section.matchAll(CEREMONY_LINE_RE)) {
+        const value = m[1].replace(/[*`_]/g, '').trim();
+        if (/^full\b/i.test(value))
+            return { forcesFull: true, ignored: null };
+        if (ignored === null)
+            ignored = value;
+    }
+    return { forcesFull: false, ignored };
+}
+/** The REQUIREMENTS.md lines naming any of the IDs, and the IDs no line names. */
+function requirementLinesFor(text, reqIds) {
+    const res = reqIds.map((id) => ({ id, re: new RegExp(`(?<![A-Za-z0-9_-])${escapeRegex(id)}(?![A-Za-z0-9_])`) }));
+    const found = new Set();
+    const lines = [];
+    for (const line of text.split(/\r?\n/)) {
+        let hit = false;
+        for (const { id, re } of res) {
+            if (re.test(line)) {
+                found.add(id);
+                hit = true;
+            }
+        }
+        if (hit)
+            lines.push(line);
+    }
+    return { lines, withoutText: reqIds.filter((id) => !found.has(id)) };
+}
+/** Distinct completed phase numbers other than this one (research A8: over-inclusion is safe). */
+function countCompletedOtherPhases(cwd, thisToken) {
+    const self = normalizePhaseNumber(thisToken);
+    const paths = planningPaths(cwd);
+    const done = new Set();
+    const roadmapText = readTextOrEmpty(paths.roadmap);
+    for (const m of roadmapText.matchAll(CHECKBOX_PHASE_RE)) {
+        const n = normalizePhaseNumber(m[1]);
+        if (n !== self)
+            done.add(n);
+    }
+    for (const dirName of listNames(paths.phases)) {
+        const n = normalizePhaseNumber(extractPhaseToken(dirName) || dirName);
+        if (n === self || done.has(n))
+            continue;
+        if (listNames(node_path_1.default.join(paths.phases, dirName)).some(isSummaryName))
+            done.add(n);
+    }
+    return done.size;
+}
+function countArchivedMilestones(cwd) {
+    const paths = planningPaths(cwd);
+    let count = listNames(paths.milestonesArchive).filter((n) => n.endsWith('-ROADMAP.md')).length;
+    const archiveDir = node_path_1.default.join(paths.planning, 'archive');
+    for (const name of listNames(archiveDir)) {
+        try {
+            if (node_fs_1.default.statSync(node_path_1.default.join(archiveDir, name)).isDirectory())
+                count++;
+        }
+        catch {
+            /* unreadable entry: not counted */
+        }
+    }
+    return count;
+}
+/** The phase directory (absolute) and its token, or null for an unknown phase. */
+function locatePhase(cwd, phase) {
+    const match = resolvePhaseForRead(cwd, phase);
+    if (!match || typeof match['directory'] !== 'string' || match['directory'] === '')
+        return null;
+    const rel = match['directory'];
+    const dirName = node_path_1.default.posix.basename(rel.replace(/\\/g, '/'));
+    return { dir: node_path_1.default.join(cwd, rel), rel, token: extractPhaseToken(dirName) || dirName };
+}
+/** Every classifier input, each read through its existing owner (D-01, D-03, D-04). */
+function gatherInputs(cwd, phase, flags, resolved) {
+    const gate = resolved ?? resolveGateConfig(cwd);
+    const located = locatePhase(cwd, phase);
+    let section = '';
+    try {
+        section = getRoadmapPhaseWithFallback(cwd, phase) ?? '';
+    }
+    catch {
+        section = '';
+    }
+    // CR-03: the full-ceremony marker counts anywhere in the phase section.
+    const marker = readCeremonyMarker(section);
+    // Pitfall 5: the `**Plans**` list holds titles the planner chose; never scan it.
+    const plansAt = section.search(PLANS_LINE_RE);
+    if (plansAt >= 0)
+        section = section.slice(0, plansAt);
+    const sectionLines = section.split(/\r?\n/);
+    const reqIds = parseReqIds(sectionLines);
+    const successCriteria = countSuccessCriteria(sectionLines);
+    const requirements = requirementLinesFor(readTextOrEmpty(planningPaths(cwd).requirements), reqIds);
+    let contextText = '';
+    if (located) {
+        const names = listNames(located.dir).filter((n) => n.endsWith('-CONTEXT.md') || n === 'CONTEXT.md').sort();
+        contextText = names.map((n) => readTextOrEmpty(node_path_1.default.join(located.dir, n))).join('\n').replace(DEFERRED_RE, '');
+    }
+    return {
+        phase: located ? located.token : String(phase),
+        roadmapText: section,
+        requirementText: requirements.lines.join('\n'),
+        contextText,
+        reqIds,
+        successCriteria,
+        frontend: frontendOf(cwd, phase),
+        requirementIdsWithoutText: requirements.withoutText,
+        trackedSourceFiles: countTrackedSourceFiles(cwd),
+        completedOtherPhases: countCompletedOtherPhases(cwd, located ? located.token : String(phase)),
+        archivedMilestones: countArchivedMilestones(cwd),
+        configMode: gate.ceremonyMode,
+        roadmapForcesFull: marker.forcesFull,
+        roadmapCeremonyIgnored: marker.ignored,
+        flags,
+        gateConfig: gate,
+    };
+}
+function readRecorded(cwd, phase) {
+    const located = locatePhase(cwd, phase);
+    if (!located)
+        return null;
+    const rel = node_path_1.default.posix.join(located.rel.replace(/\\/g, '/'), `${located.token}-CEREMONY.md`);
+    let text;
+    try {
+        text = node_fs_1.default.readFileSync(node_path_1.default.join(cwd, rel), 'utf8');
+    }
+    catch {
+        return null;
+    }
+    const verdict = parseCeremony(text);
+    return verdict ? { verdict, text, rel } : null;
+}
+/** The verdict recorded for a phase, or null when absent, unreadable or invalid (T-37-05). */
+function readRecordedVerdict(cwd, phase) {
+    return readRecorded(cwd, phase)?.verdict ?? null;
+}
+/**
+ * D-15: the recorded verdict, else the full default. Never computes a fresh verdict,
+ * so a missing or broken file never lowers ceremony.
+ */
+function effectiveVerdict(cwd, phase) {
+    const recorded = readRecorded(cwd, phase);
+    if (recorded)
+        return { verdict: recorded.verdict, source: 'recorded', phase_found: true };
+    return {
+        verdict: defaultFullVerdict(String(phase), resolveGateConfig(cwd)),
+        source: 'default',
+        phase_found: locatePhase(cwd, phase) !== null,
+    };
+}
+// ─── CLI router ──────────────────────────────────────────────────────────────
+const CLASSIFY_FLAGS = new Set(['--full', '--research', '--skip-research', '--skip-verify', '--write']);
+function parseCliArgs(argv, allowed) {
+    const positionals = [];
+    const flags = new Set();
+    for (const arg of argv) {
+        if (arg.startsWith('--')) {
+            if (!allowed.has(arg))
+                error(`Unknown ceremony flag: ${arg}`, ERROR_REASON.USAGE);
+            flags.add(arg);
+        }
+        else {
+            positionals.push(arg);
+        }
+    }
+    // WR-02: a flag string that was not word-split (" --full") must fail loudly,
+    // not be filed as an ignored positional while the verdict drops the flag.
+    if (positionals.length > 1) {
+        error(`Unexpected argument(s): ${positionals.slice(1).map((p) => JSON.stringify(p)).join(' ')}`, ERROR_REASON.USAGE);
+    }
+    return { positionals, flags };
+}
+function gateReport(g) {
+    if (g.decision === 'run')
+        return 'run';
+    if (g.decision === 'off')
+        return 'off (config)';
+    return `skipped (ceremony: ${g.reason})`;
+}
+function buildResult(verdict, cfg, meta) {
+    const gates = {};
+    for (const key of exports.CEREMONY_GATES) {
+        const g = verdict.gates[key];
+        if (g)
+            gates[key] = { ...g, report: gateReport(g) };
+    }
+    return {
+        phase: verdict.phase,
+        phase_found: meta.phase_found,
+        source: meta.source,
+        schema_version: verdict.schema_version,
+        mode: verdict.mode,
+        forced_by: verdict.forced_by,
+        forced_by_all: verdict.forced_by_all,
+        tier: verdict.tier,
+        answers: verdict.answers,
+        gates,
+        warnings: verdict.warnings,
+        file: meta.file,
+        written: meta.written,
+        reused: meta.reused,
+        ...deriveCeremonyKeys(verdict, cfg.code_review_depth),
+    };
+}
+function cmdClassify(cwd, argv, raw) {
+    const { positionals, flags } = parseCliArgs(argv, CLASSIFY_FLAGS);
+    const phase = positionals[0];
+    if (phase === undefined || phase === '')
+        error('Missing phase argument', ERROR_REASON.SDK_MISSING_ARG);
+    const located = locatePhase(cwd, phase);
+    if (!located)
+        error(`Phase ${phase} not found`, ERROR_REASON.PHASE_NOT_FOUND);
+    const cfg = resolveGateConfig(cwd);
+    const ceremonyFlags = {
+        full: flags.has('--full'),
+        research: flags.has('--research'),
+        skipResearch: flags.has('--skip-research'),
+        skipVerify: flags.has('--skip-verify'),
+    };
+    // D-12: once the phase has a SUMMARY, the recorded verdict stands unless --full.
+    const frozen = listNames(located.dir).some(isSummaryName) && !ceremonyFlags.full;
+    const recorded = frozen ? readRecorded(cwd, phase) : null;
+    let verdict;
+    // WR-06: the verdict --write records. --skip-research and --skip-verify decide
+    // this run only (plan-phase honours both itself), so they never enter the file.
+    let toRecord;
+    let source;
+    let reused = false;
+    if (recorded) {
+        verdict = toRecord = recorded.verdict;
+        source = 'recorded';
+        reused = true;
+    }
+    else if (frozen) {
+        verdict = toRecord = defaultFullVerdict(located.token, cfg);
+        source = 'default';
+    }
+    else {
+        const inputs = gatherInputs(cwd, phase, { ...ceremonyFlags, skipResearch: false, skipVerify: false }, cfg);
+        toRecord = classify(inputs);
+        verdict = ceremonyFlags.skipResearch || ceremonyFlags.skipVerify ? classify({ ...inputs, flags: ceremonyFlags }) : toRecord;
+        source = 'computed';
+    }
+    const relFile = node_path_1.default.posix.join(located.rel.replace(/\\/g, '/'), `${located.token}-CEREMONY.md`);
+    let written = false;
+    if (flags.has('--write') && !reused) {
+        const target = resolvePhaseForWrite(cwd, phase);
+        if (!target.ok) {
+            error(target.reason === 'archived'
+                ? `Phase ${phase} is archived; CEREMONY.md is written to live phases only`
+                : `Phase ${phase} directory not found`, ERROR_REASON.PHASE_NOT_FOUND);
+        }
+        node_fs_1.default.writeFileSync(node_path_1.default.join(cwd, relFile), serializeCeremony(toRecord));
+        written = true;
+    }
+    // WR-01: always rendered from the parsed verdict, never the stored body.
+    const text = renderCeremonyTable(verdict);
+    output(buildResult(verdict, cfg, {
+        source, phase_found: true, file: written || reused ? relFile : null, written, reused,
+    }), raw, text);
+}
+function cmdGet(cwd, argv, raw) {
+    const { positionals } = parseCliArgs(argv, new Set());
+    const phase = positionals[0];
+    if (phase === undefined || phase === '')
+        error('Missing phase argument', ERROR_REASON.SDK_MISSING_ARG);
+    const recorded = readRecorded(cwd, phase);
+    const eff = effectiveVerdict(cwd, phase);
+    const cfg = resolveGateConfig(cwd);
+    const text = renderCeremonyTable(eff.verdict);
+    output(buildResult(eff.verdict, cfg, {
+        source: eff.source, phase_found: eff.phase_found, file: recorded ? recorded.rel : null, written: false, reused: false,
+    }), raw, text);
+}
+function cmdCeremony(cwd, args, raw) {
+    const sub = args[0];
+    const rest = args.slice(1);
+    switch (sub) {
+        case 'classify':
+            cmdClassify(cwd, rest, raw);
+            return;
+        case 'get':
+            cmdGet(cwd, rest, raw);
+            return;
+        default:
+            error(`Unknown ceremony subcommand: ${String(sub)}. Available: classify, get`, ERROR_REASON.SDK_UNKNOWN_COMMAND);
+    }
+}