peaks-loop 4.0.48 → 4.0.49

package/dist/services/feedback/feedback-promotion-service.js

@@ -8,25 +8,30 @@
  * primitive behind the `peaks feedback promote` and
  * `peaks feedback check-unpromoted` CLI commands.
  *
- * Promotion tracking convention: a feedback memory is considered
- * "promoted" when one of the following is true:
+ * Promotion tracking convention — two parts, and BOTH are required:
  *
- *   (a) The memory file contains an HTML comment near the top of the
- *       body: `<!-- peaks-feedback-promoted: layer=<A|B|C> -->`.
- *       Written by `peaks feedback promote` so a single read of the
- *       memory file is enough to determine promotion state.
+ *   (a) A MARKER, either an HTML comment near the top of the body
+ *       (`<!-- peaks-feedback-promoted: layer=<A|B|C> -->`) or a sibling
+ *       `.peaks/memory/<name>.promotion.json` sidecar with
+ *       `{ layer: "A" | "B" | "C", ... }`. Written by `peaks feedback
+ *       promote` so a single read of the memory file is enough to see the
+ *       claimed layer.
  *
- *   (b) A sibling `.peaks/memory/<name>.promotion.json` exists with
- *       `{ layer: "A" | "B" | "C", ... }`. Written as a sidecar for
- *       tooling that prefers machine-readable state over embedded
- *       comments (e.g. `verify-pipeline` Gate H).
+ *   (b) The ARTIFACT that layer implies — see `promotionArtifactChecks`.
+ *       rid 2026-09-14-gate-h-promotion: the marker alone used to count,
+ *       which made the gate self-certifying, because the only thing a marker
+ *       proves is that `peaks feedback promote` ran. Every layer-A marker in
+ *       this repo pointed at `sops/<name>.md`, a file that did not exist and
+ *       that no engine reads.
  *
- * The comment marker is the SOURCE OF TRUTH for human review; the
- * sidecar is the source of truth for the scanner. Either is enough
- * to mark a feedback memory as promoted.
+ * The comment marker is the SOURCE OF TRUTH for human review; the sidecar is
+ * the source of truth for the scanner. Neither is evidence on its own.
  */
 import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
+import { registerSop } from '../sop/sop-registry-service.js';
+import { projectRegistryPath, projectSopManifestPath } from '../sop/sop-paths.js';
+import { artifactEvidenceFailure } from './promotion-artifact-evidence.js';
 /**
  * PRD-002b slice 2 — extract magic numbers used by the promotion
  * helper. `slice(0, 5)` was used as a heuristic on the user's body
@@ -41,7 +46,131 @@ export const PROMOTION_LAYER_DETAILS = [
     { layer: 'B', label: 'peaks-hooks PreToolUse', description: 'Append a matcher to .peaks/.claude-settings-template.json. Tool-call interception.' },
     { layer: 'C', label: 'mode-gate hardFloorCategory', description: 'Extend HardFloorCategory + shouldPauseAtGate. Always pauses regardless of mode.' }
 ];
+/**
+ * rid 2026-09-14-gate-h-promotion — what actually backs a promotion.
+ *
+ * Before this, a promotion was honored on the marker alone (HTML comment or
+ * sidecar). Both are written by `peaks feedback promote` and neither proves
+ * that anything was enforced: every layer-A promotion in this repo pointed at
+ * `sops/<name>.md`, a file that did not exist and that no engine reads. The
+ * gate was therefore self-certifying — it read only what the command it tells
+ * you to run had written.
+ *
+ * A promotion is now honored only when its layer's enforcement surface carries
+ * the artifact. The three layers keep artifacts in three different shapes, so
+ * the check is a small table rather than one rule:
+ *
+ *   - A (peaks-sop gate): a SOP manifest at `.peaks/sops/<id>/sop.json` AND an
+ *     entry for `<id>` in `.peaks/sops/registry.json`. The registry half is not
+ *     decoration: `gate-enforce-service.enforceBashCommand` enumerates SOPs via
+ *     `readRegistry()`, so an unregistered manifest is off the enforcement path
+ *     no matter how valid it is.
+ *   - B (peaks-hooks PreToolUse): `.peaks/.claude-settings-template.json` must
+ *     register the rule inside its `hooks` block. The file always exists, so
+ *     existence proves nothing — the evidence is the registration inside it.
+ *   - C (mode-gate hardFloorCategory): `src/services/code/mode-gate.ts` must
+ *     register the rule in the hard-floor vocabulary, for the same reason. This
+ *     is the repo's existing convention: the one real layer-C promotion cites
+ *     its memory by path, from the category's doc block.
+ *
+ * R2 (2026-09-14-gate-h-promotion): each of those is now a PARSE plus a shape
+ * assertion, in `promotion-artifact-evidence.ts`. Every check used to be a
+ * `text.includes(<rule>)` over the whole file, which certified a tree that was
+ * a refusal — an invalid-JSON registry, a template saying "do NOT add a
+ * matcher", a mode-gate line saying the rule is deliberately not a category —
+ * because in each case the rule's name was still in the file's bytes. A name in
+ * a file is not a registration, and a file that cannot be parsed is a finding,
+ * not a permit.
+ */
+/**
+ * SOP id used for a feedback memory's layer-A artifact.
+ *
+ * Prefixed because `peaks-*` SOP ids are reserved for the built-in namespace
+ * (`reservedIdReason` in sop-service.ts) and several feedback memories start
+ * with `peaks-`, which would make them unregistrable under their own name.
+ */
+export function sopIdForFeedback(memoryName) {
+    return `feedback-${memoryName}`;
+}
+/** The artifact(s) and the structural evidence each must carry for `layer` to mean anything. */
+export function promotionArtifactChecks(memoryName, layer) {
+    if (layer === 'A') {
+        const id = sopIdForFeedback(memoryName);
+        return [
+            { path: `.peaks/sops/${id}/sop.json`, evidence: 'sop-manifest', id },
+            { path: '.peaks/sops/registry.json', evidence: 'sop-registry-entry', id }
+        ];
+    }
+    if (layer === 'B') {
+        return [{ path: '.peaks/.claude-settings-template.json', evidence: 'hook-registration', id: memoryName }];
+    }
+    return [{ path: 'src/services/code/mode-gate.ts', evidence: 'hard-floor-category', id: memoryName }];
+}
+/**
+ * Which of `checks` are not satisfied under `projectRoot`. Empty means the
+ * promotion is backed by its artifact. Never throws, and never permits: a file
+ * that is absent, unreadable, or unparseable is a finding, not a warning —
+ * "cannot read the evidence" must not read as "the evidence is good".
+ */
+export function missingArtifacts(checks, projectRoot) {
+    const missing = [];
+    for (const check of checks) {
+        const absolute = resolve(projectRoot, check.path);
+        if (!existsSync(absolute)) {
+            missing.push(`${check.path} (absent)`);
+            continue;
+        }
+        let text;
+        try {
+            text = readFileSync(absolute, 'utf8');
+        }
+        catch {
+            missing.push(`${check.path} (unreadable)`);
+            continue;
+        }
+        const failure = artifactEvidenceFailure(check, text);
+        if (failure !== null) {
+            missing.push(`${check.path} (${failure})`);
+        }
+    }
+    return missing;
+}
 const COMMENT_MARKER_RE = /<!--\s*peaks-feedback-promoted:\s*layer=([ABC])\s*-->/;
+/**
+ * rid 2026-09-14-gate-h-promotion (classify slice) — the "not to be promoted"
+ * declaration.
+ *
+ * The gate used to know only `has artifact` / `has no artifact`, so a memory that
+ * prescribes no action could never pass: promoting it registers a SOP whose only
+ * gate is "the source file still exists", which asserts nothing about behaviour.
+ * That is a permanent false positive — the old vacuity defect facing the other way.
+ *
+ * The declaration closes it, but it must not become a way to silence the gate.
+ * It differs from the refused grandfather channel (`promotedAt` older than this
+ * rule) in that a grandfather exemption is a property of a memory's AGE: every
+ * legacy memory has it, it says nothing about content, and nobody has to assert
+ * or defend it. This is a bounded claim about the memory's CONTENT:
+ *
+ *   1. The code is drawn from a closed vocabulary — free text cannot be used.
+ *   2. Each code binds to a predicate over the memory's own frontmatter, which
+ *      the gate recomputes. The declaration may only RESTATE what the memory
+ *      already says; it cannot introduce a new fact.
+ *   3. A reason string is required (the `closedAt` escape hatch beside it has none).
+ *   4. Coexisting with a promotion marker is a contradiction and fails, so the
+ *      channel cannot be used to bury a promotion whose artifact is missing.
+ *   5. Exempted memories stay REPORTED via `listPromotionExempt`, so the
+ *      unpromoted count never drops silently.
+ */
+export const NOT_TO_PROMOTE_CODES = ['non-actionable', 'closed-slice-note'];
+/**
+ * What each code's predicate requires the memory to already say. The gate does not
+ * and cannot verify that "prescribes no action" is TRUE; it verifies that the
+ * declaration agrees with a claim the memory makes on its own.
+ */
+const NOT_TO_PROMOTE_CORROBORATION = {
+    'non-actionable': 'frontmatter `scope:` containing `non-actionable`, or `nonActionable: true`',
+    'closed-slice-note': 'frontmatter `sourceArtifact:` or `source:` naming the slice it was derived from'
+};
 /**
  * Parse a single `.peaks/memory/<file>.md` into a FeedbackMemory, or
  * `null` when the file is missing / unreadable / not a feedback memory.
@@ -162,12 +291,49 @@ export function listUnpromotedFeedback(opts) {
         // honours the closed state and reports `0 unpromoted` for closed records.
         if (isClosedMemory(join(memoryDir, entry.name)))
             continue;
+        // rid 2026-09-14-gate-h-promotion (classify slice): a memory may declare
+        // itself out of the gate. A malformed declaration is a FAILURE, not a skip —
+        // otherwise "make the fields unusable" would be the quietest way through.
+        const declaration = readNotToPromote(join(memoryDir, entry.name));
+        if (declaration.kind === 'invalid') {
+            out.push({
+                name: parsed.name,
+                path: parsed.path,
+                reason: `not-to-promote declaration rejected: ${declaration.reason}`
+            });
+            continue;
+        }
+        if (declaration.kind === 'valid') {
+            if (parsed.promotion !== null) {
+                out.push({
+                    name: parsed.name,
+                    path: parsed.path,
+                    reason: `carries both a layer ${parsed.promotion.layer} promotion marker and a notToPromote: ${declaration.code} declaration — one of the two claims is false; remove one`
+                });
+                continue;
+            }
+            // Deliberately exempt; `listPromotionExempt` reports it so the count is visible.
+            continue;
+        }
         if (parsed.promotion === null) {
             out.push({
                 name: parsed.name,
                 path: parsed.path,
                 reason: 'no promotion marker (comment or sidecar) found — see `peaks feedback promote`'
             });
+            continue;
+        }
+        // rid 2026-09-14-gate-h-promotion: a marker is a claim, not evidence. It
+        // counts only when the layer's enforcement surface actually carries the
+        // artifact. Before this, the marker alone was accepted, so the gate
+        // certified whatever the promote command had written and nothing else.
+        const missing = missingArtifacts(promotionArtifactChecks(parsed.name, parsed.promotion.layer), opts.projectRoot);
+        if (missing.length > 0) {
+            out.push({
+                name: parsed.name,
+                path: parsed.path,
+                reason: `marker claims layer ${parsed.promotion.layer} but the artifact is missing: ${missing.join('; ')}`
+            });
         }
     }
     return out;
@@ -209,6 +375,109 @@ function isClosedMemory(filePath) {
     }
     return false;
 }
+/** Raw frontmatter text of a memory, or `null` when absent/unreadable. */
+function readFrontmatter(filePath) {
+    if (!existsSync(filePath))
+        return null;
+    let raw;
+    try {
+        raw = readFileSync(filePath, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    const normalized = raw.replace(/\r\n/g, '\n');
+    if (!normalized.startsWith('---\n'))
+        return null;
+    const endIndex = normalized.indexOf('\n---\n', 4);
+    if (endIndex < 0)
+        return null;
+    return normalized.slice(4, endIndex);
+}
+/** Flat `key: value` lookup over frontmatter text; `null` when unset or empty. */
+function frontmatterValue(frontmatter, key) {
+    for (const rawLine of frontmatter.split('\n')) {
+        const line = rawLine.trim();
+        if (!line.startsWith(`${key}:`))
+            continue;
+        const value = line.slice(key.length + 1).trim();
+        if (value.length === 0 || value === '""' || value === "''")
+            return null;
+        return value;
+    }
+    return null;
+}
+/** Does the memory's own frontmatter already say what `code` claims? */
+function corroborates(code, frontmatter) {
+    if (code === 'non-actionable') {
+        const scope = frontmatterValue(frontmatter, 'scope');
+        if (scope !== null && scope.includes('non-actionable'))
+            return true;
+        return frontmatterValue(frontmatter, 'nonActionable') === 'true';
+    }
+    return frontmatterValue(frontmatter, 'sourceArtifact') !== null
+        || frontmatterValue(frontmatter, 'source') !== null;
+}
+/**
+ * Read the memory's not-to-promote declaration. `invalid` is returned rather than
+ * `none` when the fields are present but unusable, so the gate fails with a reason
+ * instead of quietly treating a malformed declaration as "no declaration".
+ */
+export function readNotToPromote(filePath) {
+    const frontmatter = readFrontmatter(filePath);
+    if (frontmatter === null)
+        return { kind: 'none' };
+    const code = frontmatterValue(frontmatter, 'notToPromote');
+    const reason = frontmatterValue(frontmatter, 'notToPromoteReason');
+    if (code === null && reason === null)
+        return { kind: 'none' };
+    if (code === null) {
+        return { kind: 'invalid', reason: '`notToPromoteReason` is set but the `notToPromote` code is missing' };
+    }
+    if (!NOT_TO_PROMOTE_CODES.includes(code)) {
+        return {
+            kind: 'invalid',
+            reason: `\`notToPromote: ${code}\` is not a recognised code (expected ${NOT_TO_PROMOTE_CODES.join(' | ')})`
+        };
+    }
+    if (reason === null) {
+        return { kind: 'invalid', reason: `\`notToPromote: ${code}\` has no \`notToPromoteReason\` — an exemption must state its own reason` };
+    }
+    const typedCode = code;
+    if (!corroborates(typedCode, frontmatter)) {
+        return {
+            kind: 'invalid',
+            reason: `\`notToPromote: ${typedCode}\` is not corroborated by the memory's own frontmatter (needs ${NOT_TO_PROMOTE_CORROBORATION[typedCode]})`
+        };
+    }
+    return { kind: 'valid', code: typedCode, reason };
+}
+/**
+ * The feedback memories that declare themselves out of the gate. Exposed so the
+ * gate can REPORT them: an exemption nobody can see is the vacuity this whole
+ * channel is required to avoid. Never throws.
+ */
+export function listPromotionExempt(opts) {
+    const memoryDir = resolve(opts.projectRoot, '.peaks', 'memory');
+    if (!existsSync(memoryDir))
+        return [];
+    const out = [];
+    for (const entry of readdirSync(memoryDir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+        if (!entry.isFile() || !entry.name.endsWith('.md') || entry.name.startsWith('.'))
+            continue;
+        const filePath = join(memoryDir, entry.name);
+        const parsed = parseFeedbackMemory(filePath);
+        if (parsed === null)
+            continue;
+        const declaration = readNotToPromote(filePath);
+        if (declaration.kind !== 'valid')
+            continue;
+        if (parsed.promotion !== null)
+            continue; // contradiction — reported as a violation instead
+        out.push({ name: parsed.name, path: parsed.path, code: declaration.code, reason: declaration.reason });
+    }
+    return out;
+}
 /**
  * Generate the code stub for a given layer. Returns a Markdown
  * snippet the LLM / human can paste into the appropriate file. Pure
@@ -219,8 +488,8 @@ export function generatePromotionStub(opts) {
     const { layer, feedbackName } = opts;
     if (layer === 'A') {
         return {
-            snippet: `# SOP entry for feedback "${feedbackName}"\n\n<!-- Append the rule + acceptance criteria below. Reference from a new peaks-sop gate. -->\n\n## Rule\n\n${opts.feedbackBody.split('\n').slice(0, RULE_BODY_PREVIEW_LINES).join('\n')}\n\n## Enforcement\n\nAdd a check to sops/<name>.md and reference from .claude/rules/.`,
-            targetFiles: [`sops/${feedbackName}.md`]
+            snippet: `# SOP entry for feedback "${feedbackName}"\n\n<!-- Append the rule + acceptance criteria below. Reference from a new peaks-sop gate. -->\n\n## Rule\n\n${opts.feedbackBody.split('\n').slice(0, RULE_BODY_PREVIEW_LINES).join('\n')}\n\n## Enforcement\n\nAuthor the rule's gates in the generated manifest and reference it from .claude/rules/.`,
+            targetFiles: [`.peaks/sops/${sopIdForFeedback(feedbackName)}/sop.json`]
         };
     }
     if (layer === 'B') {
@@ -235,6 +504,37 @@ export function generatePromotionStub(opts) {
         targetFiles: ['src/services/code/mode-gate.ts', `tests/unit/services/code/${feedbackName}-hard-floor.test.ts`]
     };
 }
+/**
+ * Materialize the layer-A artifact: the SOP manifest the engine reads, plus its
+ * registry entry. Registration is not optional — `gate-enforce-service` walks
+ * `readRegistry()`, so an unregistered manifest enforces nothing.
+ *
+ * Returns the paths written. `registerSop` lints the manifest first, so a
+ * malformed generation throws here rather than leaving a promotion that only
+ * looks real.
+ */
+async function generateLayerAArtifact(parsed, projectRoot) {
+    const id = sopIdForFeedback(parsed.name);
+    const manifestPath = projectSopManifestPath(projectRoot, id);
+    const description = parsed.frontmatter.description ?? '';
+    const manifest = {
+        id,
+        name: parsed.name,
+        description: `Promoted from feedback memory .peaks/memory/${parsed.name}.md${description.length > 0 ? `: ${description}` : ''}`,
+        phases: ['apply'],
+        gates: [
+            {
+                id: 'rule-source-present',
+                phase: 'apply',
+                check: { type: 'file-exists', path: `.peaks/memory/${parsed.name}.md` }
+            }
+        ]
+    };
+    mkdirSync(dirname(manifestPath), { recursive: true });
+    writeFileSync(manifestPath, JSON.stringify(manifest, null, 2), 'utf8');
+    await registerSop({ id, projectRoot });
+    return [manifestPath, projectRegistryPath(projectRoot)];
+}
 /**
  * Write the promotion marker + sidecar. Also writes the envelope to
  * `.peaks/_runtime/<sid>/rd/feedback-promote-<name>.json` for QA
@@ -245,28 +545,39 @@ export function generatePromotionStub(opts) {
  * machine-readable mirror. Both are written; either alone is
  * enough for the scanner.
  */
-export function promoteFeedback(opts) {
+export async function promoteFeedback(opts) {
     const parsed = parseFeedbackMemory(opts.feedbackPath);
     if (parsed === null) {
         throw new Error(`Not a feedback memory: ${opts.feedbackPath}`);
     }
+    // rid 2026-09-14-gate-h-promotion (classify slice): the tool must not create the
+    // contradiction the gate rejects — promoting a memory that declares itself out of
+    // the gate would print `effective: true` while Gate H reports a contradiction.
+    const declaration = readNotToPromote(opts.feedbackPath);
+    if (declaration.kind === 'valid') {
+        throw new Error(`${opts.feedbackPath} declares \`notToPromote: ${declaration.code}\` — promoting it would contradict that declaration. Remove the declaration first if the memory is a rule after all.`);
+    }
     const stub = generatePromotionStub({
         layer: opts.layer,
         feedbackName: parsed.name,
         feedbackBody: parsed.body
     });
     const now = new Date().toISOString();
+    const required = promotionArtifactChecks(parsed.name, opts.layer);
     const envelope = {
         name: parsed.name,
         feedbackPath: parsed.path,
         layer: opts.layer,
         layerDetail: PROMOTION_LAYER_DETAILS.find((l) => l.layer === opts.layer)?.label ?? opts.layer,
-        generatedFiles: stub.targetFiles,
+        generatedFiles: [],
+        requiredArtifacts: required.map((check) => check.path),
+        effective: false,
         snippet: stub.snippet,
         promotedAt: now,
         promotedBy: opts.promotedBy
     };
     if (opts.dryRun === true) {
+        envelope.effective = missingArtifacts(required, opts.projectRoot).length === 0;
         return envelope;
     }
     // 1. Embed comment marker in the memory file.
@@ -283,23 +594,33 @@ export function promoteFeedback(opts) {
             : `${marker}\n${body}`;
         const newContent = normalized.slice(0, endIndex + '\n---\n'.length) + newBody;
         writeFileSync(opts.feedbackPath, newContent, 'utf8');
+        envelope.generatedFiles.push(opts.feedbackPath);
+    }
+    // 2. Layer A: the promotion only means something once the SOP engine can see
+    // it. Generated before the sidecar so the sidecar records the full list.
+    if (opts.layer === 'A') {
+        envelope.generatedFiles.push(...(await generateLayerAArtifact(parsed, opts.projectRoot)));
     }
-    // 2. Sidecar (machine-readable mirror).
+    // 3. Sidecar (machine-readable mirror).
     const sidecarPath = opts.feedbackPath.replace(/\.md$/, '.promotion.json');
     writeFileSync(sidecarPath, JSON.stringify({
         name: parsed.name,
         layer: opts.layer,
         layerDetail: envelope.layerDetail,
-        generatedFiles: stub.targetFiles,
+        generatedFiles: envelope.generatedFiles,
+        requiredArtifacts: envelope.requiredArtifacts,
         promotedAt: now,
         promotedBy: opts.promotedBy
     }, null, 2), 'utf8');
-    // 3. Envelope to `.peaks/_runtime/<sid>/rd/`.
+    envelope.generatedFiles.push(sidecarPath);
+    // 4. Envelope to `.peaks/_runtime/<sid>/rd/`.
     const envelopePath = join(opts.projectRoot, '.peaks', '_runtime', opts.sessionId, 'rd', `feedback-promote-${parsed.name}.json`);
     const envelopeDir = dirname(envelopePath);
     if (!existsSync(envelopeDir)) {
         mkdirSync(envelopeDir, { recursive: true });
     }
+    envelope.generatedFiles.push(envelopePath);
+    envelope.effective = missingArtifacts(required, opts.projectRoot).length === 0;
     writeFileSync(envelopePath, JSON.stringify(envelope, null, 2), 'utf8');
     return envelope;
 }

package/dist/services/feedback/promotion-artifact-evidence.d.ts

@@ -0,0 +1,69 @@
+/**
+ * rid 2026-09-14-gate-h-promotion (R2; repaired by R8) — what a promotion's
+ * artifact has to PROVE.
+ *
+ * The three layers used to be checked with `text.includes(<rule name>)` over the
+ * whole file. A substring test cannot tell "the rule is registered" from "a
+ * comment saying the rule is absent", so a refusal tree passed every layer:
+ *
+ *   - layer A: a `.peaks/sops/registry.json` that is not valid JSON, with the id
+ *     still somewhere in its bytes;
+ *   - layer B: a settings template whose only mention of the rule reads
+ *     "do NOT add a matcher for <rule>";
+ *   - layer C: a `mode-gate.ts` whose only mention reads
+ *     "// TODO: <rule> is DELIBERATELY NOT a hard-floor category".
+ *
+ * All three are the same defect facing the other way: an unreadable artifact is
+ * treated as a permitted one. Each check below therefore parses its evidence and
+ * asserts the SHAPE, and every failure is a finding — never a warning that
+ * permits. Nothing here throws: an unparseable file is reported, not swallowed.
+ *
+ * R8 (same rid) — the same defect survived inside R2's repair, in two places:
+ *
+ *   - layer C matched a member's `doc` by name MENTION, so an adverse line
+ *     sitting between two vocabulary members became the following member's doc
+ *     and the verdict flipped on where the comment sat. The predicate is now this
+ *     repo's own citation form — the memory cited by PATH,
+ *     `.peaks/memory/<id>.md`, exactly as `mode-gate.ts:41` does — rather than
+ *     the memory merely named. That citation requirement is what closes the
+ *     placement dependence; the doc is also read from the comment SPANS attached
+ *     to the member rather than from the raw slice, which states "code is not a
+ *     doc" as an invariant rather than relying on the raw slice to honour it;
+ *   - layer B kept `matcher.includes(id)` / `command.includes(id)` over free
+ *     text, so `command: "echo 'do NOT add a matcher for rule-x'"` registered a
+ *     rule by writing a sentence about it. Both fields are now parsed: a matcher
+ *     is a tool selector, a command is argv.
+ *
+ * R10 (same rid) — layer C read the `HardFloorCategory` union and the
+ * `HARD_FLOOR_CATEGORIES` array as ONE flattened member list, so a member of the
+ * union alone satisfied the check. Measured on the R8 bytes: a union-only literal
+ * — and a union-only member whose doc cited `.peaks/memory/<id>.md` — were both
+ * reported BACKED, while `isHardFloorCategory` (which reads the array) returned
+ * false and `shouldPauseAtGate` returned `shouldPause: false`. The gate certified
+ * a hard floor that paused nothing, contradicting its own message. Only the array
+ * enforces, so only the array is now evidence — for the name and for the citation
+ * alike. The union is still READ, for one reason only: a category's doc belongs
+ * to the category, and this repo documents `commit-boundary-side-effect` beside
+ * the union member while the array enforces it.
+ */
+export type PromotionEvidence = 
+/** A SOP manifest: a JSON object whose `id` is the SOP's and whose `gates` is an array. */
+'sop-manifest'
+/** An entry with the SOP's `id` inside `<registry>.sops[]` — what `readRegistry()` enumerates. */
+ | 'sop-registry-entry'
+/** A hook registration (hook command) inside `hooks` that runs something named after the rule. */
+ | 'hook-registration'
+/** A member of `HARD_FLOOR_CATEGORIES` — the array `isHardFloorCategory` reads — that names the rule. */
+ | 'hard-floor-category';
+export type PromotionArtifactCheck = {
+    /** Project-relative POSIX path whose CONTENT must carry the evidence. */
+    path: string;
+    evidence: PromotionEvidence;
+    /** The rule id the evidence must name (a SOP id for layer A, a memory name for B and C). */
+    id: string;
+};
+/**
+ * The reason `check` is unsatisfied by `text`, or `null` when it is satisfied.
+ * Never throws: a file that cannot be parsed yields the reason it could not be.
+ */
+export declare function artifactEvidenceFailure(check: PromotionArtifactCheck, text: string): string | null;