peaks-loop 4.0.52 → 4.0.54

package/dist/services/memory/project-memory-service/store/atomic-write.js

@@ -5,9 +5,13 @@
 //     PEM private keys, JWTs, GitHub / GitLab tokens, AWS access keys. Used
 //     both by the extract path (`assertSafeMemory`) and the backup path
 //     (`assertSafeMemoryFileContent`).
+//   - `findSensitiveMemoryTitleTerm` — the PROSE predicate for
+//     `memory.title`. It is deliberately NOT the config-key predicate: see
+//     the block comment above it (slice C0).
 //   - `assertSafeMemory` — full safety gate applied during extraction.
-//     Combines title/body content scan + config-service secret check +
-//     sensitive-path check on the title.
+//     Combines the metadata key scan + the content pattern scan + the title
+//     scan. Each failure names the check that fired, and the title one names
+//     the term it matched.
 //   - `assertSafeMemoryFileContent` — lighter version for backup: just
 //     the content pattern scan, since the file already lives in
 //     `.peaks/memory/` and was authored through the normal pipeline.
@@ -17,7 +21,109 @@
 //     for index.json regeneration.
 // ---------------------------------------------------------------------------
 import { closeSync, constants, openSync, writeFileSync } from 'node:fs';
-import { containsSensitiveConfigValue, isSensitiveConfigPath } from '../../../config/config-service.js';
+import { containsSensitiveConfigValue } from '../../../config/config-service.js';
+/**
+ * The names of the three checks `assertSafeMemory` can fail on, written once.
+ *
+ * The name of the check that fired rides the refusal message, so the reader is
+ * told WHICH rule stopped the write instead of only that something was
+ * refused. Callers route their remedy on these same constants (see
+ * `memoryExtractNextActions` in `src/cli/commands/core/memory-command.ts`) —
+ * two strings kept equal by hand is how a message and its advice drift apart.
+ */
+export const SENSITIVE_MEMORY_CHECKS = {
+    metadataKey: 'metadata key scan',
+    content: 'content scan',
+    title: 'title scan'
+};
+/** The stable prefix of every refusal this module raises on the extract path. */
+const SENSITIVE_MEMORY_REFUSAL = 'Refusing to store sensitive memory content';
+/**
+ * Credential TERMS as they appear in prose — the word-level counterpart of the
+ * config-key predicate `config-service.isSensitiveConfigPath`.
+ *
+ * WHY THE TITLE CHECK EXISTS AT ALL (it is not redundant with the content
+ * scanner). `hasSensitiveMemoryContent` looks for a credential *value*: its
+ * first pattern needs a `:` or `=`, so a title that is nothing but `apiKey`
+ * carries no value and slips past it. The title scan is the only rule that can
+ * see "the title IS a credential name" — so this check was kept, and only its
+ * predicate was replaced.
+ *
+ * WHY IT DOES NOT REUSE `isSensitiveConfigPath`. That predicate answers "is
+ * this a CONFIG KEY", and it answers by SUBSTRING: `includes('auth')` is true
+ * for `authority`, `author`, `unauthorized`. On a config key that breadth is
+ * harmless — an auth-bearing key IS a credential key, and the config domain is
+ * untouched here. On a prose title it is a false refusal the author cannot see
+ * the cause of: slice C0, where `peaks memory extract` refused a memory titled
+ * "Derive from the authority, never re-declare it" and told the user to
+ * "remove secrets" from a memory that had none.
+ *
+ * HOW IT MATCHES. The title is cut into alphanumeric segments (camelCase
+ * boundaries included) and a match is a CONTIGUOUS RUN of segments whose
+ * concatenation is one of the terms below. Runs — not single words — are what
+ * keep the credential-name spellings a substring check caught and a naive
+ * word-per-word check would lose: `private_key`, `api key`, `myApiKey` and
+ * `access token` all still match, while `authority`, `author`, `tokenizer`,
+ * `secretary` and `credentialed` do not.
+ *
+ * The residual narrowing is named rather than hidden: an UNSEPARATED compound
+ * with a term buried mid-word (`mysecretstuff`) no longer matches. That is the
+ * same class as the false refusals above — a word containing `secret` is not a
+ * credential term — and the memory body is scanned for values either way.
+ *
+ * The plural forms are listed explicitly instead of deriving them by stripping
+ * a trailing `s` from each match: that rule would turn `secretaries` into
+ * `secretarie` → `secret`, which is precisely the substring confusion this
+ * predicate exists to end.
+ */
+const SENSITIVE_PROSE_TERMS = new Set([
+    'apikey', 'apikeys',
+    'accesskey', 'accesskeys',
+    'privatekey', 'privatekeys',
+    'secretkey', 'secretkeys',
+    'accesstoken', 'accesstokens',
+    'authtoken', 'authtokens',
+    'authkey', 'authkeys',
+    'refreshtoken', 'refreshtokens',
+    'token', 'tokens',
+    'secret', 'secrets',
+    'password', 'passwords',
+    'passwd',
+    'bearer',
+    'credential', 'credentials'
+]);
+/** A lower→upper transition: the boundary between the words of `apiKey`. */
+const CAMEL_CASE_BOUNDARY = /([a-z0-9])([A-Z])/g;
+/** `myApiKey` → `['my', 'api', 'key']`; `private_key` → `['private', 'key']`. */
+function proseSegments(text) {
+    return text
+        .replace(CAMEL_CASE_BOUNDARY, '$1 $2')
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((segment) => segment.length > 0);
+}
+/**
+ * The credential term this title contains (as a run of words), or `null`.
+ *
+ * Returns the MATCHED TERM rather than a boolean because the refusal message
+ * names it: `title scan matched the credential term "apikey"` is actionable,
+ * while "Refusing to store sensitive memory content" is what sent slice C0's
+ * user looking for a secret that was not there. The returned string is a
+ * dictionary word from the list above — never the title's own text, and never
+ * a value — so echoing it into the error envelope cannot leak anything.
+ */
+export function findSensitiveMemoryTitleTerm(title) {
+    const segments = proseSegments(title);
+    for (let start = 0; start < segments.length; start += 1) {
+        let run = '';
+        for (let end = start; end < segments.length; end += 1) {
+            run += segments[end];
+            if (SENSITIVE_PROSE_TERMS.has(run))
+                return run;
+        }
+    }
+    return null;
+}
 export function hasSensitiveMemoryContent(content) {
     return /(?:api[_-]?key|token|secret|password|credential|bearer)\s*[:=]/i.test(content)
         || /\bauthorization\s*:\s*bearer\s+\S+/i.test(content)
@@ -30,14 +136,68 @@ export function hasSensitiveMemoryContent(content) {
         || /-----BEGIN [A-Z ]*PRIVATE KEY-----/.test(content)
         || /\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/.test(content);
 }
+/**
+ * The refusal `assertSafeMemory` raises: the check that fired and the term it
+ * matched travel as DATA, not only as prose.
+ *
+ * WHY A TYPE RATHER THAN A MESSAGE. The envelope redactor behind every
+ * `fail()` (`packages/peaks-loop-shared/src/result.ts`) strips the words
+ * secret / token / password / api-key out of every failure MESSAGE — a blanket
+ * rule, applied to messages this module does not own. So a message that names
+ * the matched term reaches the CLI reading `… the credential term
+ * "[redacted]" …`: the term is named, and then removed, on the way out.
+ *
+ * The term is a word from `SENSITIVE_PROSE_TERMS` — a fixed vocabulary, never a
+ * value — so there is nothing about it to redact, and it rides a field
+ * instead: `fail()` redacts `message` only. The CLI routes its remedy on
+ * `check` for the same reason — a substring test against a message whose words
+ * can be rewritten is not a routing rule, it is a guess.
+ *
+ * NOTHING HERE WEAKENS THE REDACTOR. The content scan never puts its match in
+ * this object (see `matchedTerm` below), so no value can reach an envelope
+ * through it; the redactor's guarantee is intact and is pinned by the cases in
+ * `tests/unit/services/memory/memory-title-sensitive-scan.test.ts`.
+ */
+export class UnsafeMemoryError extends Error {
+    /** One of `SENSITIVE_MEMORY_CHECKS` — which rule refused the write. */
+    check;
+    /**
+     * The credential term the TITLE scan matched, or `null` for the other two
+     * checks. `null` is not an omission: their match can BE the credential
+     * (`ghp_…`, the PEM header, the JWT), which is why their messages describe
+     * the pattern family and never echo the text.
+     */
+    matchedTerm;
+    constructor(check, detail, matchedTerm = null) {
+        super(`${SENSITIVE_MEMORY_REFUSAL}: ${check} ${detail}.`);
+        this.name = 'UnsafeMemoryError';
+        this.check = check;
+        this.matchedTerm = matchedTerm;
+    }
+}
 export function assertSafeMemory(memory) {
     const content = `${memory.title}\n${memory.kind}\n${memory.body}`;
     const metadata = { title: memory.title, kind: memory.kind, body: memory.body };
-    if (containsSensitiveConfigValue(metadata) || hasSensitiveMemoryContent(content)) {
-        throw new Error('Refusing to store sensitive memory content');
+    if (containsSensitiveConfigValue(metadata)) {
+        throw new UnsafeMemoryError(SENSITIVE_MEMORY_CHECKS.metadataKey, 'matched a credential key in the memory metadata');
+    }
+    if (hasSensitiveMemoryContent(content)) {
+        // The match is deliberately NOT echoed, in the message or in the error's
+        // fields: for most of these patterns the match IS the credential, so
+        // copying it would write the value this scan exists to keep out.
+        //
+        // The DETAIL is worded around the envelope redactor's vocabulary on
+        // purpose. Its catch-all (`/(secret|token|password|api[-_ ]?key)/gi`)
+        // rewrites those four words wherever they appear in a failure message, so
+        // naming the pattern families in their own words arrives on the CLI as
+        // "an [redacted] / [redacted] / [redacted] assignment" — a remedy sentence
+        // redacted into uselessness by the very policy it agrees with. Measured on
+        // the real CLI, both wordings; this one survives intact.
+        throw new UnsafeMemoryError(SENSITIVE_MEMORY_CHECKS.content, 'matched a credential value in the memory content (a `key=value` credential assignment, a Bearer header, a PEM private key, a JWT, or a provider credential)');
     }
-    if (isSensitiveConfigPath(memory.title)) {
-        throw new Error('Refusing to store sensitive memory content');
+    const titleTerm = findSensitiveMemoryTitleTerm(memory.title);
+    if (titleTerm !== null) {
+        throw new UnsafeMemoryError(SENSITIVE_MEMORY_CHECKS.title, `matched the credential term "${titleTerm}" in memory.title`, titleTerm);
     }
 }
 export function assertSafeMemoryFileContent(content) {

package/dist/services/prd/gate-evidence-derivation.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Where `gateEvidence` comes FROM, and where its promise is checked.
+ *
+ * B2 (merged with the B1 repair), rid `rid-b2-gate-evidence-wiring`.
+ *
+ * B1 made the field real at the SERVICE layer and QA found the hole that
+ * mattered (F1 of `rid-b1-qa`): all three frontmatter producers passed
+ * nothing, so no capsule on disk ever carried the field — the dead surface
+ * had moved one layer out, from "no producer function" to "no production
+ * caller". This module closes that by DERIVING the map instead of accepting
+ * it from a caller.
+ *
+ * WHY DERIVED, NOT PASSED IN. Every path in the map is a function of the
+ * session id, the request id and the REQUEST TYPE, all of which the producer
+ * already has. Asking the caller to supply the map would put a second source
+ * next to the derivation, and a CLI flag (`--gate-evidence <json>`) would
+ * additionally require the user to hand-author JSON, which the project's
+ * Human-NL-Choice-Only rule forbids. So: one function, computed, no flag.
+ *
+ * THE TYPE-AWARE TENSION, AND HOW IT IS RESOLVED. The schema doc
+ * (`skills/bee/peaks-rd/references/writing-handoff-frontmatter.md:53`) calls
+ * the five keys a schema and says "Missing keys → Gate C failure". Taken
+ * literally that demands all five paths in every capsule — and then a `docs`
+ * slice, which Gate C requires NO evidence from, would fail the gate for
+ * "declaring" `audit/perf-<rid>.md` and `audit/security-<rid>.md`, two files
+ * its type is not supposed to produce. Declaring evidence that does not and
+ * should not exist is a false claim, and a gate that fails on a false claim
+ * the writer invented is worse than useless.
+ *
+ * Resolution, and the reason it is not a special case: the map declares
+ * EXACTLY what this request type's transition gate requires, read from
+ * `PREREQUISITES_BY_TYPE` — the same table `checkPrerequisites` enforces at
+ * `rd:qa-handoff`. So:
+ *
+ *   - feature / refactor → projectScan, prdHandoff, codeReview,
+ *     securityReview, perfBaseline (all five)
+ *   - bugfix             → the same five
+ *   - config             → projectScan, securityReview (TWO keys, verified
+ *     against the table rather than assumed — `CONFIG_TABLE['rd:qa-handoff']`
+ *     is `[SECURITY_REVIEW]` alone, so there is no `prdHandoff`: config has no
+ *     `AUDIT_REQUIRES_HANDOFF` row. An earlier revision of this comment
+ *     claimed three, and QA caught prose that disagreed with the code, which
+ *     is the defect this module exists to end. The security path declared is
+ *     the config-specific `rd/security-review.md` — genuinely ridless, per its
+ *     own row — not the documented `audit/security-<rid>.md`, which no config
+ *     slice writes)
+ *   - docs / chore       → NOTHING. No `rd:qa-handoff` row ⇒ nothing for Gate C
+ *     to validate ⇒ nothing declared (see below)
+ *
+ * WHY `projectScan` IS DECLARED, AND WHY ONLY FOR GATED TYPES. It is not read
+ * from the table — it is Gate A's artifact, and Gate A is type-independent
+ * ("After workspace init + project scan", step 0.6 of every workflow). But a
+ * declaration is only worth making when something VERIFIES it, and the only
+ * verifier is `checkDeclaredGateEvidence`, which runs on `rd:qa-handoff`. For a
+ * type with a gate row, Gate C therefore does check this path like any other.
+ * For `docs`/`chore` nothing ever reads it, so it is not declared: keeping an
+ * inert statement in every docs capsule would recreate, in miniature, the exact
+ * defect this whole line of work exists to remove — a claim no one reads, which
+ * is how the field was dead in the first place (F1 of `rid-b2-qa`). Scope, in
+ * one sentence: **this map declares the evidence paths Gate C will check for
+ * this slice**, so an empty declaration is the honest one when there is no such
+ * gate.
+ *
+ * THE REJECTED ALTERNATIVE, named so it is not silently revisited: declaring
+ * all five unconditionally and teaching Gate C to check only the
+ * type-required subset. Rejected because the capsule would then carry
+ * permanent false statements about files that must never exist, and every
+ * reader of the frontmatter (peaks-qa's own checklist among them) would need
+ * the same type-conditioned filter to avoid mis-reading them.
+ *
+ * NO DERIVATION → NO DECLARATION. When there is no request artifact to read
+ * the type off, this returns `undefined` and the producers write no
+ * `gateEvidence` block at all. Never a partial map: a half-derived declaration
+ * is a false statement about the missing half's keys, and the pre-B2 bytes are
+ * the honest fallback. An id the artifact service REFUSES is not this case and
+ * is not reported as `undefined` — see `deriveGateEvidenceForRequest`.
+ */
+import { type RequestType } from '../artifacts/artifact-prerequisites.js';
+import { type GateEvidence } from './handoff-types.js';
+/**
+ * The `gateEvidence` map for a slice of `requestType` — the evidence paths
+ * Gate C will check for it. Pure: no disk access, so a caller can compute it
+ * without side effects. Empty (`{}`) — never a partial map — when the type has
+ * no `rd:qa-handoff` row, because then there is no gate to declare anything to.
+ */
+export declare function deriveGateEvidence(opts: {
+    readonly sessionId: string;
+    readonly requestId: string;
+    readonly requestType: RequestType;
+}): GateEvidence;
+/**
+ * Derive for a request by reading its PRD artifact — the only place the
+ * request TYPE is recorded (`- type: <t>`, written by `peaks request init`
+ * and read back by `request-artifact-service.extractMetadata`).
+ *
+ * Returns `undefined` when there is NO artifact to read — the one case the
+ * producers turn into "write no block" (see the header). That is now the ONLY
+ * `undefined`: a `showRequestArtifact` that THROWS is deliberately not caught,
+ * so a caller can tell "this slice has nothing to declare" apart from "the
+ * artifact could not be read".
+ *
+ * F4 (`rid-f4-ceiling-breach`). This used to be `catch { return undefined }`,
+ * which folded those two into one value — and the repository's own ratchet
+ * caught it (`capability-guard-runner/contracts/J03.ts`, rule
+ * `catch-return-null`; the ceiling was written for exactly this shape). Nothing
+ * is lost by letting the throw through. The refusals `showRequestArtifact` can
+ * raise are the rid/sid ones, and BOTH callers reach a byte-identical message
+ * on the next statement anyway — `assertSafeHandoffIds` (`handoff-service.ts`)
+ * for `prd handoff init`, `generateEvidence`'s own guard for the evidence
+ * generator — so the user-visible failure is unchanged; only its origin moves
+ * two lines earlier. What the catch DID cover in practice was an I/O failure
+ * while reading the artifact file, and swallowing that writes a capsule with no
+ * declaration at all, which Gate C reads as "nothing declared, nothing to
+ * check" (`field-absent` is not this check's business, below). A silent hole is
+ * worse than a loud, already-duplicated one.
+ */
+export declare function deriveGateEvidenceForRequest(opts: {
+    readonly projectRoot: string;
+    readonly sessionId: string;
+    readonly requestId: string;
+}): Promise<GateEvidence | undefined>;
+/** `missing` / `warnings` in the same shape `checkPrerequisites` reports. */
+export interface GateEvidenceDeclarationCheck {
+    readonly ok: boolean;
+    readonly missing: ReadonlyArray<{
+        path: string;
+        description: string;
+    }>;
+    readonly warnings: ReadonlyArray<{
+        path: string;
+        code: string;
+        message: string;
+    }>;
+}
+/**
+ * GATE C — is the capsule's OWN declaration true?
+ *
+ * The division of labour, stated so the two checks cannot drift: the
+ * prerequisite table says which artifacts this type MUST produce (it owns the
+ * requirement and its file existence); this function says the capsule must
+ * not CLAIM evidence it does not have (it owns the declaration). Neither
+ * re-implements the other, and both read their paths from wherever the path
+ * really comes from.
+ *
+ * A missing declared path FAILS and names the key, because a declaration the
+ * gate cannot verify is exactly the "prose pretending to be data" state this
+ * field was created to end. Outcomes that are not failures, each for its own
+ * reason:
+ *   - no capsule → not this check's business (`AUDIT_REQUIRES_HANDOFF` owns it)
+ *   - `field-absent` → the capsule declares nothing; every pre-B1 capsule,
+ *     and every slice whose producer could not derive a type
+ *   - an unknown key → a WARNING: the five-key vocabulary is a typo trap, and
+ *     the type's real requirement is still enforced by the table, so this
+ *     informs without blocking
+ */
+export declare function checkDeclaredGateEvidence(opts: {
+    readonly projectRoot: string;
+    readonly sessionId: string;
+    readonly requestId: string;
+}): Promise<GateEvidenceDeclarationCheck>;

package/dist/services/prd/gate-evidence-derivation.js

@@ -0,0 +1,270 @@
+/**
+ * Where `gateEvidence` comes FROM, and where its promise is checked.
+ *
+ * B2 (merged with the B1 repair), rid `rid-b2-gate-evidence-wiring`.
+ *
+ * B1 made the field real at the SERVICE layer and QA found the hole that
+ * mattered (F1 of `rid-b1-qa`): all three frontmatter producers passed
+ * nothing, so no capsule on disk ever carried the field — the dead surface
+ * had moved one layer out, from "no producer function" to "no production
+ * caller". This module closes that by DERIVING the map instead of accepting
+ * it from a caller.
+ *
+ * WHY DERIVED, NOT PASSED IN. Every path in the map is a function of the
+ * session id, the request id and the REQUEST TYPE, all of which the producer
+ * already has. Asking the caller to supply the map would put a second source
+ * next to the derivation, and a CLI flag (`--gate-evidence <json>`) would
+ * additionally require the user to hand-author JSON, which the project's
+ * Human-NL-Choice-Only rule forbids. So: one function, computed, no flag.
+ *
+ * THE TYPE-AWARE TENSION, AND HOW IT IS RESOLVED. The schema doc
+ * (`skills/bee/peaks-rd/references/writing-handoff-frontmatter.md:53`) calls
+ * the five keys a schema and says "Missing keys → Gate C failure". Taken
+ * literally that demands all five paths in every capsule — and then a `docs`
+ * slice, which Gate C requires NO evidence from, would fail the gate for
+ * "declaring" `audit/perf-<rid>.md` and `audit/security-<rid>.md`, two files
+ * its type is not supposed to produce. Declaring evidence that does not and
+ * should not exist is a false claim, and a gate that fails on a false claim
+ * the writer invented is worse than useless.
+ *
+ * Resolution, and the reason it is not a special case: the map declares
+ * EXACTLY what this request type's transition gate requires, read from
+ * `PREREQUISITES_BY_TYPE` — the same table `checkPrerequisites` enforces at
+ * `rd:qa-handoff`. So:
+ *
+ *   - feature / refactor → projectScan, prdHandoff, codeReview,
+ *     securityReview, perfBaseline (all five)
+ *   - bugfix             → the same five
+ *   - config             → projectScan, securityReview (TWO keys, verified
+ *     against the table rather than assumed — `CONFIG_TABLE['rd:qa-handoff']`
+ *     is `[SECURITY_REVIEW]` alone, so there is no `prdHandoff`: config has no
+ *     `AUDIT_REQUIRES_HANDOFF` row. An earlier revision of this comment
+ *     claimed three, and QA caught prose that disagreed with the code, which
+ *     is the defect this module exists to end. The security path declared is
+ *     the config-specific `rd/security-review.md` — genuinely ridless, per its
+ *     own row — not the documented `audit/security-<rid>.md`, which no config
+ *     slice writes)
+ *   - docs / chore       → NOTHING. No `rd:qa-handoff` row ⇒ nothing for Gate C
+ *     to validate ⇒ nothing declared (see below)
+ *
+ * WHY `projectScan` IS DECLARED, AND WHY ONLY FOR GATED TYPES. It is not read
+ * from the table — it is Gate A's artifact, and Gate A is type-independent
+ * ("After workspace init + project scan", step 0.6 of every workflow). But a
+ * declaration is only worth making when something VERIFIES it, and the only
+ * verifier is `checkDeclaredGateEvidence`, which runs on `rd:qa-handoff`. For a
+ * type with a gate row, Gate C therefore does check this path like any other.
+ * For `docs`/`chore` nothing ever reads it, so it is not declared: keeping an
+ * inert statement in every docs capsule would recreate, in miniature, the exact
+ * defect this whole line of work exists to remove — a claim no one reads, which
+ * is how the field was dead in the first place (F1 of `rid-b2-qa`). Scope, in
+ * one sentence: **this map declares the evidence paths Gate C will check for
+ * this slice**, so an empty declaration is the honest one when there is no such
+ * gate.
+ *
+ * THE REJECTED ALTERNATIVE, named so it is not silently revisited: declaring
+ * all five unconditionally and teaching Gate C to check only the
+ * type-required subset. Rejected because the capsule would then carry
+ * permanent false statements about files that must never exist, and every
+ * reader of the frontmatter (peaks-qa's own checklist among them) would need
+ * the same type-conditioned filter to avoid mis-reading them.
+ *
+ * NO DERIVATION → NO DECLARATION. When there is no request artifact to read
+ * the type off, this returns `undefined` and the producers write no
+ * `gateEvidence` block at all. Never a partial map: a half-derived declaration
+ * is a false statement about the missing half's keys, and the pre-B2 bytes are
+ * the honest fallback. An id the artifact service REFUSES is not this case and
+ * is not reported as `undefined` — see `deriveGateEvidenceForRequest`.
+ */
+import { join } from 'node:path';
+import { pathExists } from 'peaks-loop-shared/fs';
+import { getPrerequisitesFor } from '../artifacts/artifact-prerequisites.js';
+import { showRequestArtifact } from '../artifacts/request-artifact-service.js';
+import { readHandoffGateEvidence } from './handoff-gate-evidence.js';
+import { resolveHandoffPath } from './handoff-service.js';
+import { GATE_EVIDENCE_KEYS } from './handoff-types.js';
+import { PROJECT_SCAN_RELATIVE } from './project-scan-reader.js';
+/**
+ * Map ONE prerequisite of the `rd:qa-handoff` table onto the five-key
+ * vocabulary. The PATHS come from the table (single source); this function
+ * only names which key each required artifact answers to, so a change to a
+ * prerequisite's path moves the declared path with it.
+ *
+ * `mut/mut-report.json`, `rd/karpathy-review-<rid>.md`,
+ * `rd/third-party-review.md`, `qa/test-cases/<rid>.md` and the unit-test
+ * marker have no key — the vocabulary is five keys, and those artifacts are
+ * already enforced by the table itself, so they are deliberately not
+ * declared here rather than being forced into a key that does not mean them.
+ */
+function gateKeyOfPrerequisitePath(relativePath) {
+    if (relativePath.startsWith('prd/handoff'))
+        return 'prdHandoff';
+    if (relativePath.startsWith('rd/code-review'))
+        return 'codeReview';
+    if (relativePath.startsWith('audit/security') || relativePath.startsWith('rd/security-review')) {
+        return 'securityReview';
+    }
+    if (relativePath.startsWith('audit/perf'))
+        return 'perfBaseline';
+    return null;
+}
+/**
+ * The `gateEvidence` map for a slice of `requestType` — the evidence paths
+ * Gate C will check for it. Pure: no disk access, so a caller can compute it
+ * without side effects. Empty (`{}`) — never a partial map — when the type has
+ * no `rd:qa-handoff` row, because then there is no gate to declare anything to.
+ */
+export function deriveGateEvidence(opts) {
+    const requirements = getPrerequisitesFor('rd', 'qa-handoff', opts.requestType);
+    // docs / chore land here: `MINIMAL_TABLE` has no row at that transition, so
+    // nothing is required and nothing is declared. An empty map renders no block
+    // at all (`handoff-frontmatter.ts`), so such a capsule is byte-identical to a
+    // pre-B2 one and carries no statement that nothing verifies.
+    if (requirements.length === 0)
+        return {};
+    const sessionRoot = join('.peaks', '_runtime', opts.sessionId);
+    const evidence = {
+        projectScan: PROJECT_SCAN_RELATIVE
+    };
+    for (const prerequisite of requirements) {
+        const key = gateKeyOfPrerequisitePath(prerequisite.relativePath);
+        if (key === null)
+            continue;
+        // `<rid>` is the table's own placeholder, resolved the way the table's
+        // resolver resolves it, so the declaration names the file the gate looks
+        // for.
+        evidence[key] = join(sessionRoot, prerequisite.relativePath.replace('<rid>', opts.requestId));
+    }
+    return evidence;
+}
+/**
+ * Derive for a request by reading its PRD artifact — the only place the
+ * request TYPE is recorded (`- type: <t>`, written by `peaks request init`
+ * and read back by `request-artifact-service.extractMetadata`).
+ *
+ * Returns `undefined` when there is NO artifact to read — the one case the
+ * producers turn into "write no block" (see the header). That is now the ONLY
+ * `undefined`: a `showRequestArtifact` that THROWS is deliberately not caught,
+ * so a caller can tell "this slice has nothing to declare" apart from "the
+ * artifact could not be read".
+ *
+ * F4 (`rid-f4-ceiling-breach`). This used to be `catch { return undefined }`,
+ * which folded those two into one value — and the repository's own ratchet
+ * caught it (`capability-guard-runner/contracts/J03.ts`, rule
+ * `catch-return-null`; the ceiling was written for exactly this shape). Nothing
+ * is lost by letting the throw through. The refusals `showRequestArtifact` can
+ * raise are the rid/sid ones, and BOTH callers reach a byte-identical message
+ * on the next statement anyway — `assertSafeHandoffIds` (`handoff-service.ts`)
+ * for `prd handoff init`, `generateEvidence`'s own guard for the evidence
+ * generator — so the user-visible failure is unchanged; only its origin moves
+ * two lines earlier. What the catch DID cover in practice was an I/O failure
+ * while reading the artifact file, and swallowing that writes a capsule with no
+ * declaration at all, which Gate C reads as "nothing declared, nothing to
+ * check" (`field-absent` is not this check's business, below). A silent hole is
+ * worse than a loud, already-duplicated one.
+ */
+export async function deriveGateEvidenceForRequest(opts) {
+    // F4 (`rid-f4-ceiling-breach`). The throw from `showRequestArtifact` is
+    // propagated, so a caller can tell "this slice has nothing to declare"
+    // (artifact missing → `artifact === null` → `requestType === null` →
+    // `undefined`) apart from "the artifact could not be read" (an id the
+    // service refuses → rejected with `Invalid request id: ...`). The old
+    // `catch { return undefined }` collapsed both into the same value, and the
+    // `catch-return-null` ratchet caught it. The refusals `showRequestArtifact`
+    // raises are the rid / sid ones, and both callers reach a byte-identical
+    // guard a few lines up — `assertSafeHandoffIds` for `prd handoff init`,
+    // `generateEvidence`'s own guard for the evidence generator — so the
+    // user-visible failure is unchanged; only its origin moves earlier.
+    const artifact = await showRequestArtifact({
+        projectRoot: opts.projectRoot,
+        role: 'prd',
+        requestId: opts.requestId,
+        sessionId: opts.sessionId
+    });
+    const requestType = artifact?.requestType ?? null;
+    if (requestType === null)
+        return undefined;
+    return deriveGateEvidence({
+        sessionId: opts.sessionId,
+        requestId: opts.requestId,
+        requestType
+    });
+}
+/**
+ * GATE C — is the capsule's OWN declaration true?
+ *
+ * The division of labour, stated so the two checks cannot drift: the
+ * prerequisite table says which artifacts this type MUST produce (it owns the
+ * requirement and its file existence); this function says the capsule must
+ * not CLAIM evidence it does not have (it owns the declaration). Neither
+ * re-implements the other, and both read their paths from wherever the path
+ * really comes from.
+ *
+ * A missing declared path FAILS and names the key, because a declaration the
+ * gate cannot verify is exactly the "prose pretending to be data" state this
+ * field was created to end. Outcomes that are not failures, each for its own
+ * reason:
+ *   - no capsule → not this check's business (`AUDIT_REQUIRES_HANDOFF` owns it)
+ *   - `field-absent` → the capsule declares nothing; every pre-B1 capsule,
+ *     and every slice whose producer could not derive a type
+ *   - an unknown key → a WARNING: the five-key vocabulary is a typo trap, and
+ *     the type's real requirement is still enforced by the table, so this
+ *     informs without blocking
+ */
+export async function checkDeclaredGateEvidence(opts) {
+    const capsule = resolveHandoffPath({
+        projectRoot: opts.projectRoot,
+        sessionId: opts.sessionId,
+        requestId: opts.requestId
+    });
+    if (capsule === null)
+        return { ok: true, missing: [], warnings: [] };
+    const declared = await readHandoffGateEvidence(capsule);
+    if (declared.status === 'field-absent' || declared.status === 'file-missing') {
+        return { ok: true, missing: [], warnings: [] };
+    }
+    // A capsule with NO frontmatter block cannot declare anything, and
+    // `AUDIT_REQUIRES_HANDOFF` — the prereq that owns capsule validity — accepts
+    // that shape on a substring check (`schemaVersion: 2` + `sha256:` appearing
+    // anywhere). Failing it here would make Gate C refuse capsules the gate next
+    // to it accepts, breaking the "the checker and `request transition` agree"
+    // property that `pipeline-verify-contract-drift.test.ts` pins. So the line is
+    // drawn at the fence, not at readability: no fence ⇒ nothing declared;
+    // a fence whose YAML will not parse ⇒ a declaration that may be inside and
+    // unreadable, and THAT fails below.
+    if (declared.status === 'frontmatter-malformed' && declared.reason === 'no-frontmatter-fence') {
+        return { ok: true, missing: [], warnings: [] };
+    }
+    if (declared.status !== 'ok') {
+        return {
+            ok: false,
+            missing: [
+                {
+                    path: `gateEvidence(${declared.status})`,
+                    description: `the handoff's gateEvidence declaration is unusable (${declared.status}) — ` +
+                        'a declaration that cannot be read is not the same as no declaration'
+                }
+            ],
+            warnings: []
+        };
+    }
+    const missing = [];
+    for (const key of GATE_EVIDENCE_KEYS) {
+        const declaredPath = declared.evidence[key];
+        if (declaredPath === undefined)
+            continue;
+        if (await pathExists(join(opts.projectRoot, declaredPath)))
+            continue;
+        missing.push({
+            path: `gateEvidence.${key}`,
+            description: `gateEvidence.${key} declares "${declaredPath}", which does not exist`
+        });
+    }
+    const warnings = declared.unknownKeys.map((key) => ({
+        path: `gateEvidence.${key}`,
+        code: 'gate-evidence-unknown-key',
+        message: `gateEvidence declares "${key}", which is not one of the five keys ` +
+            `(${GATE_EVIDENCE_KEYS.join(', ')}) — a misspelled key is why a required gate ` +
+            'can read as undeclared'
+    }));
+    return { ok: missing.length === 0, missing, warnings };
+}

package/dist/services/prd/handoff-auto-regen.js

@@ -21,6 +21,7 @@ import { dirname, join } from 'node:path';
 import { createHash } from 'node:crypto';
 import { showRequestArtifact } from '../artifacts/request-artifact-service.js';
 import { serializeHandoffFrontmatter } from './handoff-frontmatter.js';
+import { deriveGateEvidence } from './gate-evidence-derivation.js';
 import { handoffRelativePath, sha256OfBody } from './handoff-service.js';
 import { normalizePath } from '../../shared/path-utils.js';
 /**
@@ -64,7 +65,18 @@ export async function autoRegenPrdHandoff(opts) {
         goals: [],
         acceptanceCriteria: [],
         preservedBehavior: [],
-        handoffPath: normalizePath(handoffPath.replace(opts.projectRoot, '')).replace(/^\//, '')
+        handoffPath: normalizePath(handoffPath.replace(opts.projectRoot, '')).replace(/^\//, ''),
+        // B2: DERIVED from the request type of the artifact this producer just
+        // read. B1 gave this function an optional caller-supplied map instead;
+        // with a single-source derivation available that option was the wrong
+        // shape — it left the one production caller (`request-commands.ts`) able
+        // to pass nothing, which is exactly the F1 hole. There is no input to
+        // forget now.
+        gateEvidence: deriveGateEvidence({
+            sessionId: opts.sessionId,
+            requestId: opts.requestId,
+            requestType: artifact.requestType
+        })
     };
     const content = `${serializeHandoffFrontmatter(frontmatter)}${body}`;
     mkdirSync(dirname(handoffPath), { recursive: true });