peaks-loop 4.0.47 → 4.0.49

package/dist/services/evidence/evidence-generator.js

@@ -7,22 +7,34 @@
  * gates plus the verify-pipeline, so the orchestrator no longer hand-writes
  * them per mechanical file-split (or similar) slice.
  *
- * The content markers emitted here are the exact strings the CLI gates +
- * verify-pipeline mechanically check — see
- * `src/services/artifacts/artifact-prerequisites.ts` (mustContain /
- * mustContainAny / headingMustContain) and
- * `src/services/workflow/pipeline-verify-gate-support.ts` +
- * `src/services/workflow/artifact-paths.ts` (suffixed security/performance
- * findings). Do NOT reword the marker lines.
+ * The content markers emitted here are the exact strings the CLI gates
+ * mechanically check — see `src/services/artifacts/artifact-prerequisites.ts`
+ * (mustContain / mustContainAny / headingMustContain — the authoritative
+ * table). `peaks workflow verify-pipeline` reads that same table for both the
+ * evidence paths it probes and the markers it enforces
+ * (`src/services/workflow/pipeline-verify-gate-support.ts#contractEvidencePaths`).
+ * Do NOT reword the marker lines.
+ *
+ * This paragraph used to send editors to `src/services/workflow/artifact-paths.ts`
+ * as the checker of "suffixed security/performance findings". That is no longer
+ * true: the `security-findings-<rid>.md` / `performance-findings-<rid>.md` gates
+ * were removed in rid `2026-09-14-verify-pipeline-contract-drift` (no
+ * `qa:verdict-issued` table names those paths; security and perf evidence is
+ * resolved on the RD side at `audit/security-<rid>.md` / `audit/perf-<rid>.md`),
+ * and `artifact-paths.ts` has had zero code consumers since. It is not a marker
+ * authority, so it is not a pointer worth keeping.
  *
  * Karpathy §2 (Simplicity First): a single generator function + a handful of
  * pure body builders. No speculative options, no validation beyond what the
  * reference prototype performs.
  */
-import { createHash } from 'node:crypto';
 import { mkdir, readdir, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
+import { serializeHandoffFrontmatter } from '../prd/handoff-frontmatter.js';
+import { handoffRelativePath, sha256OfBody } from '../prd/handoff-service.js';
 import { getSessionDir } from '../session/getSessionDir.js';
+import { REQUEST_ID_PATTERN } from '../artifacts/request-artifact-service.js';
+import { isUnsafePathInput } from '../../shared/path-safety.js';
 /** Comma/space tolerant `--files` splitter. */
 export function parseFiles(raw) {
     return raw
@@ -235,40 +247,20 @@ function buildQaRequest(rid, sid, files) {
 `;
 }
 /**
- * Build the `prd/handoff.md` frontmatter + body and compute the sha256
- * fingerprint. The hash is computed over the frontmatter (with the
- * `handoffHash` line left empty — `sha256:`) concatenated with the body,
- * matching the reference prototype exactly.
+ * Build the `prd/handoff-<rid>.md` frontmatter + body. The frontmatter comes from the
+ * ONE canonical serializer and `handoffHash === sha256(body)` — the same
+ * pairing `handoff-service.initHandoff` and `handoff-auto-regen.ts` use, so
+ * this producer cannot drift from them.
+ *
+ * This function used to hand-roll a third, divergent frontmatter: a
+ * `handoffHash: sha256:<hex>` value with **no line beginning `sha256:`**, over
+ * a hash computed on `frontmatter + body` rather than the body. The
+ * `AUDIT_REQUIRES_HANDOFF` gate (a substring check) accepted that file while
+ * `readAndVerifyHandoff` in both audit skills returned `null` — the very
+ * producer/consumer divergence rid `2026-09-14-handoff-writer-gate-divergence`
+ * exists to remove, surviving in a function the same slice edited.
  */
 function buildHandoff(rid, sid, title, files, lineCounts) {
-    const bulletList = files.map((f) => `  - ${f}`).join('\n');
-    const frontmatter = `---
-requestId: ${rid}
-scope:
-${bulletList}
-files:
-${bulletList}
-handoffPath: .peaks/_runtime/${sid}/prd/handoff.md
-handoffHash: sha256:PLACEHOLDER
-decisions:
-  - id: D1
-    summary: "Mechanical verbatim module split"
-    rationale: "Satisfy the 800-line file-size gate."
-risks:
-  - id: R1
-    description: "Public exports may be imported elsewhere"
-    mitigation: "Import sites updated; tsc clean."
-nextActions:
-  - "peaks-qa validates the regression matrix"
-gateEvidence:
-  projectScan: .peaks/project-scan/project-scan.md
-  prdHandoff: .peaks/_runtime/${sid}/prd/handoff.md
-  codeReview: .peaks/_runtime/${sid}/rd/code-review.md
-  securityReview: .peaks/_runtime/${sid}/rd/security-review.md
-  perfBaseline: .peaks/_runtime/${sid}/audit/perf.md
-schemaVersion: 2
----
-`;
     const body = `# PRD Handoff — ${rid}
 
 ${title}. Mechanical verbatim module split; behavior-preserving.
@@ -279,10 +271,19 @@ ${filesMd(files)}
 Line counts:
 ${lineCountsMd(lineCounts)}
 `;
-    const hashInput = frontmatter.replace('sha256:PLACEHOLDER', 'sha256:') + body;
-    const hash = createHash('sha256').update(hashInput, 'utf8').digest('hex');
-    const content = frontmatter.replace('sha256:PLACEHOLDER', `sha256:${hash}`) + body;
-    return { content, hash };
+    const handoffHash = sha256OfBody(body);
+    const frontmatter = {
+        requestId: rid,
+        sessionId: sid,
+        schemaVersion: '2',
+        handoffHash,
+        writtenAt: new Date().toISOString(),
+        goals: [],
+        acceptanceCriteria: [],
+        preservedBehavior: [],
+        handoffPath: handoffRelativePath(sid, rid)
+    };
+    return { content: `${serializeHandoffFrontmatter(frontmatter)}${body}`, hash: handoffHash };
 }
 /** Find the existing numbered QA request file for `rid`, else the default. */
 async function resolveQaRequestPath(qaDir, rid) {
@@ -300,6 +301,21 @@ async function resolveQaRequestPath(qaDir, rid) {
 }
 export async function generateEvidence(options) {
     const { projectRoot, rid, title, files, lineCounts, sessionId } = options;
+    // Both values become path segments below — the rid as a filename, the sid as
+    // the session directory. Guard them BEFORE the first mkdir so a rejected run
+    // leaves nothing behind. `REQUEST_ID_PATTERN` is the repo's own request-id
+    // control (`request-artifact-service.ts`, F-1 slice 025 security); the sid
+    // gets the segment check because `--session-id` has no pinned format.
+    // Measured before these lines existed: `--rid '../../../pwned'` wrote
+    // `.peaks/_runtime/pwned.md`, outside the per-session evidence dir, and a
+    // deeper rid wrote above the project root with the string echoed into the
+    // artifact body.
+    if (!REQUEST_ID_PATTERN.test(rid)) {
+        throw new Error(`Invalid request id: ${rid} (expected letters, digits, dots, underscores, or dashes)`);
+    }
+    if (isUnsafePathInput(sessionId)) {
+        throw new Error(`Invalid session id: ${sessionId} (must be a single path segment)`);
+    }
     const sessionRoot = getSessionDir(projectRoot, sessionId);
     const rdDir = join(sessionRoot, 'rd');
     const qaDir = join(sessionRoot, 'qa');
@@ -319,18 +335,39 @@ export async function generateEvidence(options) {
     }
     const qaRequestPath = await resolveQaRequestPath(qaDir, rid);
     const handoff = buildHandoff(rid, sessionId, title, files, lineCounts);
+    // Four of these twelve paths carry the rid because the `rd:qa-handoff` gate
+    // requires `<rid>` in them: every slice in a session shares `rd/` and
+    // `audit/`, so writing the ridless name silently destroyed the previous
+    // slice's evidence on 2026-09-13 while the gate stayed green (slice
+    // `2026-09-14-audit-artifact-rid-scoping`).
     const writes = [
-        [join(rdDir, 'code-review.md'), buildCodeReview(rid, title, files, lineCounts)],
+        [join(rdDir, `code-review-${rid}.md`), buildCodeReview(rid, title, files, lineCounts)],
+        [join(auditDir, `security-${rid}.md`), buildSecurityReview(rid)],
+        // ...but the `config` type is the one whose `rd:qa-handoff` row is
+        // `SECURITY_REVIEW` — the genuinely ridless `rd/security-review.md` — and
+        // this generator is request-type-agnostic (no `--request-type`). So it
+        // writes BOTH names: the rid-scoped one the fanout types resolve
+        // (`AUDIT_SECURITY`) and the bare one `config` resolves. Nothing is lost
+        // by having both; a `config` slice has nothing else to fall back on, and
+        // dropping this write made a `config` slice fail its own gate while the
+        // generator reported success (repair round: measured `missing:
+        // ['rd/security-review.md']` with the real generator and the real gate).
         [join(rdDir, 'security-review.md'), buildSecurityReview(rid)],
-        [join(rdDir, 'karpathy-review.md'), buildKarpathyReview(rid, lineCounts)],
+        [join(rdDir, `karpathy-review-${rid}.md`), buildKarpathyReview(rid, lineCounts)],
+        // `rd/tech-doc.md` stays ridless on purpose: the TECH_DOC prereq was
+        // removed in v2.11.0, so nothing gates it and there is no rid-scoped
+        // sibling that anything reads.
         [join(rdDir, 'tech-doc.md'), buildTechDoc(rid, title, files, lineCounts)],
-        [join(auditDir, 'perf.md'), buildPerfAudit(rid)],
+        [join(auditDir, `perf-${rid}.md`), buildPerfAudit(rid)],
         [join(qaDir, 'test-cases', `${rid}.md`), buildTestCases(rid)],
         [join(qaDir, 'test-reports', `${rid}.md`), buildTestReport(rid)],
         [join(qaDir, `security-findings-${rid}.md`), buildSecurityFindings(rid)],
         [join(qaDir, `performance-findings-${rid}.md`), buildPerformanceFindings(rid)],
         [qaRequestPath, buildQaRequest(rid, sessionId, files)],
-        [join(prdDir, 'handoff.md'), handoff.content]
+        // The handoff capsule carries the rid for the same reason as the four
+        // above (slice `2026-09-14-prd-capsule-rid-scoping`): one slot per
+        // session means the second slice's capsule overwrites the first's.
+        [join(prdDir, `handoff-${rid}.md`), handoff.content]
     ];
     const writtenFiles = [];
     for (const [path, content] of writes) {
@@ -341,7 +378,7 @@ export async function generateEvidence(options) {
         rid,
         sessionId,
         sessionRoot,
-        handoffPath: join(prdDir, 'handoff.md'),
+        handoffPath: join(prdDir, `handoff-${rid}.md`),
         handoffHash: handoff.hash,
         writtenFiles,
         createdDirectories

package/dist/services/feedback/feedback-promotion-service.d.ts

@@ -8,23 +8,27 @@
  * 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 { type PromotionArtifactCheck, type PromotionEvidence } from './promotion-artifact-evidence.js';
+export type { PromotionArtifactCheck, PromotionEvidence };
 export type PromotionLayer = 'A' | 'B' | 'C';
 export declare const PROMOTION_LAYERS: readonly PromotionLayer[];
 export type PromotionLayerDetail = {
@@ -34,6 +38,59 @@ export type PromotionLayerDetail = {
     description: string;
 };
 export declare const PROMOTION_LAYER_DETAILS: readonly PromotionLayerDetail[];
+/**
+ * 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 declare function sopIdForFeedback(memoryName: string): string;
+/** The artifact(s) and the structural evidence each must carry for `layer` to mean anything. */
+export declare function promotionArtifactChecks(memoryName: string, layer: PromotionLayer): PromotionArtifactCheck[];
+/**
+ * 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 declare function missingArtifacts(checks: readonly PromotionArtifactCheck[], projectRoot: string): string[];
 export type FeedbackMemory = {
     /** File basename (without `.md`). */
     name: string;
@@ -59,6 +116,43 @@ export type UnpromotedFeedbackEntry = {
     path: string;
     reason: string;
 };
+/**
+ * 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 declare const NOT_TO_PROMOTE_CODES: readonly ["non-actionable", "closed-slice-note"];
+export type NotToPromoteCode = (typeof NOT_TO_PROMOTE_CODES)[number];
+export type NotToPromoteRead = {
+    kind: 'none';
+} | {
+    kind: 'valid';
+    code: NotToPromoteCode;
+    reason: string;
+} | {
+    kind: 'invalid';
+    reason: string;
+};
 /**
  * Parse a single `.peaks/memory/<file>.md` into a FeedbackMemory, or
  * `null` when the file is missing / unreadable / not a feedback memory.
@@ -78,6 +172,26 @@ export declare function parseFeedbackMemory(filePath: string): FeedbackMemory |
 export declare function listUnpromotedFeedback(opts: {
     projectRoot: string;
 }): UnpromotedFeedbackEntry[];
+/**
+ * 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 declare function readNotToPromote(filePath: string): NotToPromoteRead;
+export type PromotionExemptEntry = {
+    name: string;
+    path: string;
+    code: NotToPromoteCode;
+    reason: string;
+};
+/**
+ * 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 declare function listPromotionExempt(opts: {
+    projectRoot: string;
+}): PromotionExemptEntry[];
 /**
  * Generate the code stub for a given layer. Returns a Markdown
  * snippet the LLM / human can paste into the appropriate file. Pure
@@ -97,7 +211,16 @@ export type FeedbackPromoteEnvelope = {
     feedbackPath: string;
     layer: PromotionLayer;
     layerDetail: string;
+    /**
+     * Files this call actually wrote. rid 2026-09-14-gate-h-promotion: this used
+     * to be the stub's *targets* — paths the command never wrote yet printed as
+     * `Generated files:` — which is the defect the Gate H rework exists to remove.
+     */
     generatedFiles: string[];
+    /** The artifact(s) `layer` requires before the promotion means anything. */
+    requiredArtifacts: string[];
+    /** `false` when `requiredArtifacts` are not all present — the marker is then a claim without evidence. */
+    effective: boolean;
     snippet: string;
     promotedAt: string;
     promotedBy: string;
@@ -119,5 +242,5 @@ export declare function promoteFeedback(opts: {
     sessionId: string;
     projectRoot: string;
     dryRun?: boolean;
-}): FeedbackPromoteEnvelope;
+}): Promise<FeedbackPromoteEnvelope>;
 export declare function isPromotionLayer(value: string): value is PromotionLayer;