mandrel 2.59.0 → 2.61.0

package/.agents/scripts/lib/temp-retention.js

@@ -1,47 +1,7 @@
 /**
- * temp-retention.js — allowlisted auto-purge of spent temp artifacts (Story #4794).
- *
- * The workspace temp tree grew without bound: every landed Story left its
- * close-gate transcript (~1.4MB each), its terse-result detail dumps, and its
- * validation-evidence envelope behind forever, because no code path had ever
- * removed them. This module is the single engine that reclaims them.
- *
- * ## Allowlist, never a blocklist
- *
- * The safety property that matters is not "delete the right things" but
- * "never delete the wrong thing". So classification is positive: an artifact
- * is a purge candidate only when a declared class claims it. Everything else —
- * an operator's scratch directory, a hand-parked file, a family a future
- * Story adds without teaching this module about it — is **unrecognized**, is
- * never touched, and is reported with its byte size so a human decides. A
- * blocklist would have the opposite failure mode: anything the framework
- * forgot to exclude gets deleted.
- *
- * ## Two eligibility signals, deliberately different in strength
- *
- * - **Story-keyed.** An artifact whose name carries a Story id is purged when
- *   that Story's merge has been *confirmed* by the caller — the post-land tail
- *   or a boot sweep that read live state. This is the primary path and the one
- *   the operator asked for: spent the moment the work lands.
- * - **Age-floored.** Artifacts no Story id can be recovered from (audit
- *   reports, abandoned `plan-<slug>/` dirs) fall back to a `staleDays` floor.
- *   Only the sweep opts into this; the per-Story purge never does, so a
- *   post-land tail can never reap a sibling's in-flight artifact.
- *
- * ## Keep-class
- *
- * `signals.ndjson` is the artifact whose value *starts* when the run ends —
- * `acceptance-eval` and the loop-health check both read it
- * long after the Story merged. It is excluded twice over: it is not in the
- * evidence basename allowlist, and {@link KEEP_BASENAMES} is re-checked at
- * the deletion site. Defence in depth is warranted for the one file whose
- * loss is silent and unrecoverable.
- *
- * ## Best-effort, never load-bearing
- *
- * Every entry point resolves rather than throws. This is hygiene: a purge
- * that fails must never fail a land, a boot, or a persist that already did
- * its real work. Failures are collected into `errors[]` and reported.
+ * Allowlisted auto-purge of spent temp artifacts: only a declared class's
+ * entries are candidates; the rest are reported, never touched. Never throws
+ * — a failed purge must not fail a land, boot, or persist.
  */
 
 import fsPromises from 'node:fs/promises';
@@ -55,9 +15,8 @@ import {
 import { Logger } from './Logger.js';
 
 /**
- * Shipped defaults for `delivery.tempRetention`. `enabled` defaults to `true`:
- * the operator asked for auto-purge to be the behaviour, with the knob there
- * to turn it off rather than to turn it on.
+ * Defaults for `delivery.tempRetention`; purge is on unless turned off.
+ * `staleDays` is not configurable — only switches that turn a deletion off are.
  */
 export const TEMP_RETENTION_DEFAULTS = Object.freeze({
   enabled: true,
@@ -70,50 +29,36 @@ export const TEMP_RETENTION_DEFAULTS = Object.freeze({
   }),
 });
 
-/** Every declared purge class, in classification order. */
 export const PURGE_CLASS_NAMES = Object.freeze(
   Object.keys(TEMP_RETENTION_DEFAULTS.classes),
 );
 
 /**
- * Basenames no path may ever delete, re-checked at the deletion site even
- * though classification already excludes them. See the module header.
+ * Never deleted, re-checked at the deletion site: `signals.ndjson` is read
+ * long after merge and its loss is silent and unrecoverable.
  */
 export const KEEP_BASENAMES = Object.freeze(['signals.ndjson']);
 
-/**
- * The per-Story artifact basenames `validationEvidence` claims. An explicit
- * allowlist rather than a "delete everything but signals" rule: a file this
- * module has not been taught about is kept, not guessed at.
- */
+/** Explicit allowlist: an untaught file in a Story dir is kept. */
 const STORY_EVIDENCE_BASENAMES = Object.freeze([
   'validation-evidence.json',
   'lifecycle.ndjson',
   'manifest.md',
 ]);
 
-/**
- * Top-level temp entries that belong to the framework but are never purge
- * candidates: `qa/` holds resumable operator-owned session ledgers, `cache/`
- * has its own invalidation, and `*.lock` files are live coordination state.
- */
+/** Framework-owned, never purged (`*.lock` files are also skipped). */
 const RESERVED_TOP_LEVEL = Object.freeze(['qa', 'cache']);
 
 const MS_PER_DAY = 24 * 60 * 60 * 1000;
 
-/** `story-4794` → `4794`. */
 const STORY_DIR_PATTERN = /^story-(\d+)$/;
-/** `close-gates-4794`, `sync-result-story-4794` → `4794`. */
 const TRAILING_ID_PATTERN = /-(\d+)$/;
-/** `audit-story-4794-audit-clean-code.md` → `4794`. */
 const AUDIT_STORY_PATTERN = /^audit-story-(\d+)-/;
-/** `run-1030` — a per-run temp tree holding `stories/story-<id>/` children. */
+/** Per-run temp tree holding `stories/story-<id>/` children. */
 const RUN_DIR_PATTERN = /^run-\d+$/;
 
 /**
- * Resolve the effective retention policy, filling every field from
- * {@link TEMP_RETENTION_DEFAULTS}. An unset block yields the defaults, so a
- * consumer that never heard of this feature gets the purge.
+ * Effective retention policy, defaults filled in.
  *
  * @param {object} [config] Resolved config bag.
  * @returns {{ enabled: boolean, staleDays: number, classes: Record<string, boolean> }}
@@ -127,15 +72,13 @@ export function resolveTempRetention(config) {
   }
   return {
     enabled: raw.enabled ?? TEMP_RETENTION_DEFAULTS.enabled,
-    staleDays: raw.staleDays ?? TEMP_RETENTION_DEFAULTS.staleDays,
+    staleDays: TEMP_RETENTION_DEFAULTS.staleDays,
     classes,
   };
 }
 
 /**
- * `readdir` that yields `[]` for a directory that does not exist or cannot be
- * read. Every scan below walks optional trees, so an absent one is the normal
- * case, not an error.
+ * `readdir` yielding `[]` for an absent or unreadable directory.
  *
  * @param {typeof fsPromises} fsp
  * @param {string} dir
@@ -150,8 +93,7 @@ async function safeReaddir(fsp, dir) {
 }
 
 /**
- * Total bytes under a path — the file's own size, or the recursive sum for a
- * directory. Reporting-only: a vanished child is skipped rather than fatal.
+ * Recursive byte total; a vanished child is skipped.
  *
  * @param {typeof fsPromises} fsp
  * @param {string} target
@@ -180,10 +122,8 @@ async function sizeOf(fsp, target) {
 }
 
 /**
- * Build one classified entry. `mtimeMs` is the entry's **own** mtime, not the
- * newest mtime beneath it — that is the semantics the shipped stale-plan-dir
- * reap has always used, and widening it here would silently change when an
- * abandoned directory becomes eligible.
+ * One classified entry. `mtimeMs` is the entry's own mtime, not the newest
+ * beneath it; widening it would change when an abandoned dir becomes eligible.
  *
  * @param {typeof fsPromises} fsp
  * @param {string} target
@@ -209,19 +149,12 @@ async function makeEntry(fsp, target, className, storyId, keep = false) {
   };
 }
 
-/**
- * Extensions this class owns inside `orchestration/`. Story #4816 added
- * `.json`: the persisted terminal envelope lands beside the gate log, and a
- * `.log`-only scan would have left one immortal file per delivered Story in a
- * directory the purge otherwise keeps clean.
- */
+/** `.json` covers the persisted terminal envelope beside each gate log. */
 const ORCHESTRATION_EXTENSIONS = Object.freeze(['.log', '.json']);
 
 /**
- * Recover the Story id a run-artifact basename carries. Every writer that
- * lands in `orchestration/` ends its name with the scope: `close-gates-4794.log`
- * from the gate sink, `sync-result-story-4794.log` from the terse-result dump,
- * `story-deliver-terminal-4794.json` from the terminal-envelope persist.
+ * Story id from an `orchestration/` basename; every writer there ends the
+ * name with `-<id>`.
  *
  * @param {string} name
  * @returns {number|null}
@@ -231,12 +164,7 @@ function storyIdFromLogName(name) {
   return match ? Number(match[1]) : null;
 }
 
-/**
- * `<tempRoot>/orchestration/*.{log,json}` — close gate transcripts,
- * terse-result detail dumps, and persisted terminal envelopes. An artifact
- * whose name carries no id (there are none today, but the class owns the
- * directory) is age-floored rather than dropped from the class.
- */
+/** `<tempRoot>/orchestration/*.{log,json}`; an id-less name is age-floored. */
 async function scanOrchestrationLogs(tempRoot, fsp) {
   const dir = path.join(tempRoot, ORCHESTRATION_DIRNAME);
   const entries = [];
@@ -258,10 +186,7 @@ async function scanOrchestrationLogs(tempRoot, fsp) {
   return entries;
 }
 
-/**
- * Every directory that holds `story-<id>/` children: the standalone tree and
- * each per-run tree.
- */
+/** Directories holding `story-<id>/` children: standalone and per-run. */
 async function storyParentDirs(tempRoot, fsp) {
   const parents = [path.join(tempRoot, 'standalone', 'stories')];
   for (const dirent of await safeReaddir(fsp, tempRoot)) {
@@ -273,11 +198,8 @@ async function storyParentDirs(tempRoot, fsp) {
 }
 
 /**
- * `<…>/stories/story-<id>/*` — the per-Story delivery artifacts.
- *
- * Every file in the directory is emitted, but only the declared evidence
- * basenames are purge candidates; `signals.ndjson` and anything unrecognized
- * are emitted with `keep: true` so the envelope can show what survived.
+ * `<…>/stories/story-<id>/*`; non-allowlisted files are emitted `keep: true`
+ * so the envelope shows what survived.
  */
 async function scanValidationEvidence(tempRoot, fsp) {
   const entries = [];
@@ -302,10 +224,7 @@ async function scanValidationEvidence(tempRoot, fsp) {
   return entries;
 }
 
-/**
- * `<tempRoot>/audits/*` — audit reports. `audit-story-<id>-<lens>.md` is
- * Story-keyed; the roster-level reports and profiling output are age-floored.
- */
+/** `<tempRoot>/audits/*`; `audit-story-<id>-*` is Story-keyed, rest age-floored. */
 async function scanAuditResults(tempRoot, fsp) {
   const dir = path.join(tempRoot, 'audits');
   const entries = [];
@@ -322,10 +241,7 @@ async function scanAuditResults(tempRoot, fsp) {
   return entries;
 }
 
-/**
- * `<tempRoot>/plan-<slug>/` — plan authoring dirs. Never Story-keyed: the
- * directory predates the Stories it creates, so age is the only safe signal.
- */
+/** `<tempRoot>/plan-<slug>/`: predates its Stories, so age is the only signal. */
 async function scanPlanDirs(tempRoot, fsp) {
   const entries = [];
   for (const dirent of await safeReaddir(fsp, tempRoot)) {
@@ -341,7 +257,6 @@ async function scanPlanDirs(tempRoot, fsp) {
   return entries;
 }
 
-/** Class name → scanner. Iteration order matches {@link PURGE_CLASS_NAMES}. */
 const SCANNERS = Object.freeze({
   orchestrationLogs: scanOrchestrationLogs,
   validationEvidence: scanValidationEvidence,
@@ -350,9 +265,8 @@ const SCANNERS = Object.freeze({
 });
 
 /**
- * Does a top-level temp entry belong to a declared class? Kept in lockstep
- * with the scanners above: an entry no class walks must show up as
- * unrecognized, never be silently ignored.
+ * Keep in lockstep with the scanners: an entry no class walks must surface
+ * as unrecognized.
  *
  * @param {string} name
  * @returns {boolean}
@@ -368,9 +282,7 @@ function isClassOwnedTopLevel(name) {
 }
 
 /**
- * Top-level entries that no class claims and that are not framework-reserved.
- * Reported with byte sizes, never deleted — this is what makes a 49MB scratch
- * directory visible to the operator instead of invisible to the tooling.
+ * Unclaimed, non-reserved top-level entries: reported with sizes, never deleted.
  *
  * @param {string} tempRoot
  * @param {typeof fsPromises} fsp
@@ -389,8 +301,7 @@ async function collectUnrecognized(tempRoot, fsp) {
 }
 
 /**
- * Classify a whole temp tree without deleting anything. Exported so a caller
- * (or a test) can see exactly what the purge would consider.
+ * Classify a temp tree without deleting anything.
  *
  * @param {{ config?: object, tempRoot?: string, fsp?: typeof fsPromises }} [args]
  * @returns {Promise<{ tempRoot: string, entries: object[], unrecognized: Array<{ path: string, bytes: number }> }>}
@@ -413,8 +324,6 @@ export async function collectTempEntries({
 }
 
 /**
- * Is this entry eligible for deletion under the current policy and signals?
- *
  * @param {object} entry
  * @param {object} ctx
  * @returns {boolean}
@@ -430,23 +339,20 @@ function isPurgeable(entry, ctx) {
 }
 
 /**
- * The purge core. Deliberately **module-private**: the two exported entry
- * points below are the whole public surface, and each encodes a policy
- * decision (Story-keyed vs. age-floored) that a caller reaching this directly
- * could get wrong. Exporting it would also be a dead export — nothing outside
- * this file has a reason to call it.
+ * Purge core; module-private because each exported entry point encodes the
+ * Story-keyed vs. age-floored policy a direct caller could get wrong.
  *
  * @param {object} [args]
- * @param {object} [args.config] Resolved config bag.
+ * @param {object} [args.config]
  * @param {number[]} [args.storyIds] Stories whose merge the caller CONFIRMED.
  * @param {boolean} [args.sweepStale] Opt into the age floor for un-keyed entries.
- * @param {string[]|null} [args.only] Restrict to these class names.
- * @param {string[]} [args.excludePaths] Absolute paths to leave alone.
- * @param {number} [args.now] Clock seam.
- * @param {string} [args.tempRoot] Temp root override (tests).
- * @param {typeof fsPromises} [args.fsp] Filesystem seam.
- * @param {{ info: Function }} [args.logger] Logger seam.
- * @param {string} [args.label] Prefix for the single summary line.
+ * @param {string[]|null} [args.only]
+ * @param {string[]} [args.excludePaths]
+ * @param {number} [args.now]
+ * @param {string} [args.tempRoot]
+ * @param {typeof fsPromises} [args.fsp]
+ * @param {{ info: Function }} [args.logger]
+ * @param {string} [args.label]
  * @returns {Promise<object>} Result envelope; never throws.
  */
 async function purgeTempArtifacts({
@@ -501,7 +407,6 @@ async function purgeTempArtifacts({
       result.purged.push({ path: entry.path, bytes: entry.bytes });
       result.bytesReclaimed += entry.bytes;
     } catch (err) {
-      // A racing writer or a permission error: leave it for the next run.
       result.errors.push(`${entry.path}: ${String(err?.message ?? err)}`);
     }
   }
@@ -516,8 +421,6 @@ async function purgeTempArtifacts({
 }
 
 /**
- * Human-readable byte count for the one summary line.
- *
  * @param {number} bytes
  * @returns {string}
  */
@@ -534,9 +437,7 @@ export function formatBytes(bytes) {
 }
 
 /**
- * Purge one merged Story's spent artifacts. Called from the post-land tail,
- * where "merged" is already confirmed — so this never applies the age floor
- * and can never touch a sibling Story's in-flight artifacts.
+ * Purge one confirmed-merged Story's artifacts; never applies the age floor.
  *
  * @param {{ storyId: number, config?: object, now?: number, tempRoot?: string,
  *   fsp?: typeof fsPromises, logger?: object }} args
@@ -552,10 +453,8 @@ export async function purgeStoryTempArtifacts({ storyId, config, ...rest }) {
 }
 
 /**
- * Catch-up sweep: purge the artifacts of every Story the caller confirmed
- * merged, plus every age-floored entry past `staleDays`. This is the path
- * that reclaims a backlog — Stories merged in an earlier run, merged through
- * the GitHub UI, or delivered before this feature existed.
+ * Catch-up sweep: confirmed-merged Stories plus age-floored entries past
+ * `staleDays`.
  *
  * @param {{ config?: object, mergedStoryIds?: number[], now?: number,
  *   tempRoot?: string, fsp?: typeof fsPromises, logger?: object,

package/.agents/scripts/lib/templates/decomposer-prompts.js

@@ -5,43 +5,13 @@ import {
 import { BODY_FORMAT_LINTS } from '../story-body/body-format-lints.js';
 
 /**
- * The story-author system prompt (Story #5312 — rendered from the draft's
- * Story count).
- *
- * **Single source of the prompt body (Story #4162).** This module is the sole
- * carrier of the story-author system prompt, delivered to the host LLM in the
- * `systemPrompts.story` field of the `/mandrel-plan` context envelope (via
- * `lib/orchestration/plan-context.js#buildSystemPrompts`), so no second
- * verbatim copy can drift.
- *
- * Two layers, composed by {@link renderStoryAuthorPrompt}:
- *
- *   - **The N=1 core** ({@link renderStoryAuthorCore}) — what every draft
- *     needs: the body schema, the contract-level Spec rule, the deterministic
- *     body-format lints, and acceptance defined as outcomes a PR reviewer can
- *     confirm from the diff and the verify output. It carries no delivery
- *     schedule, no per-file behavior paragraphs, no reviewability budget and
- *     no verify-tier suffix — every one of those either scored a shape the
- *     authoring model already judges or prescribed a proxy that became the
- *     goal.
- *   - **The N>1 rules** ({@link renderStorySplitRules}) — the schedule rules
- *     that only mean anything once a draft has siblings: every Story must
- *     earn its slot in the wave schedule, and no same-wave pair may collide
- *     on a declared path (Story #5332 replaced the acceptance partition with
- *     the dispatcher's own collision predicate, armed as a refusal).
- *   - **The tickets-mode rules** ({@link ticketsModePromptField}, Story
- *     #5323) — what to re-derive rather than carry when the seed is an
- *     existing ticket whose body is already in Story shape.
- *
- * The envelope carries the core as `systemPrompts.story`, the split rules as
- * `systemPrompts.storySplitRules` and the tickets rules as
- * `systemPrompts.storyTicketsRules`; a planner reads the second only when the
- * default-single split policy clears, and the third only in tickets mode.
+ * The sole source of the story-author system prompt, shipped in the
+ * `/mandrel-plan` envelope as `systemPrompts.story` (the N=1 core),
+ * `storySplitRules` (read only at N>1) and `storyTicketsRules` (tickets mode
+ * only).
  */
 
 /**
- * The N=1 core of the story-author prompt.
- *
  * @returns {string}
  */
 export function renderStoryAuthorCore() {
@@ -55,11 +25,8 @@ export function renderStoryAuthorCore() {
     advisoryCaveat,
     newFileContract,
   } = AUTHORING_ALTITUDE_GUIDANCE;
-  // The deterministic body-format lints (structured `## Changes` bullet shape,
-  // non-empty sections) rendered example-first from their single source
-  // (`lib/story-body/body-format-lints.js`) so an authored draft is lint-clean
-  // by construction rather than discovered as a persist dry-run failure and
-  // re-authored at resident-context prices (Story #4684).
+  // Rendered example-first so a draft is lint-clean by construction rather
+  // than re-authored after a persist dry-run failure.
   const bodyFormatLintChecklist = BODY_FORMAT_LINTS.map(
     (lint) =>
       `- **${lint.id}** — ${lint.summary} Example: \`${lint.goodExample}\``,
@@ -117,7 +84,8 @@ The **persisted** \`body\` renders these markdown sections (in order) — you au
     <optional technical approach at contract level — do NOT restate Goal / Acceptance / Verify>
 
     ## Changes
-    - {"path": "<file path>", "assumption": "creates" | "refactors-existing" | "deletes"}
+    - <file path>
+    - {"path": "<file path>", "assumption": "deletes"}
     - ...
 
     ## Acceptance          <-- synthesized by persist from acceptance[]; do not author
@@ -137,9 +105,9 @@ The **persisted** \`body\` renders these markdown sections (in order) — you au
 - **goal** (in body string): One sentence stating WHY this Story exists.
 - **spec** (optional, in body string as \`## Spec\`): The technical approach at the altitude the SPEC PROSE CONTRACT below fixes — contract and invariants, never implementation narration. Write as much as the work needs and no more; persist keeps Specs inline at any length and never writes them under \`docs/\`.
 - **slicing** (optional): Ordered intra-session checkpoints for one Story, one line each. A checkpoint is a **stage of the work** — a commit boundary the deliverer passes through inside one session, stated as the step it performs. An acceptance item is a **state of the codebase** a PR reviewer confirms once the Story has landed. The same Story therefore carries both: the checkpoints say in what order it is built, \`acceptance[]\` says what must then be true. Never a fan-out table, never a second acceptance list, and never sibling tickets — a broad sweep with many stages is still one Story, sliced here.
-- **changes** (in body string): Each entry is an object \`{ path, assumption }\` where \`assumption\` is one of \`creates | refactors-existing | deletes\`. **Name the files the deliverer authors, and omit generated artifacts** — quality baselines, generated test indexes, migration journals, lockfiles and the like are regenerated by the work itself, the refresh is a close-gate concern, and declaring one needlessly reserves a footprint that serializes sibling Stories at dispatch. Acceptable path shapes include explicit files (\`src/components/Foo.tsx\`), glob patterns (\`tests/e2e/*.spec.ts\`, \`**/*.astro\`), and module identifiers that resolve to files. Use \`refactors-existing\` for in-place edits to a file already on \`main\`; \`creates\` for net-new files; \`deletes\` for removals. Persist probes every path against the base branch and repairs a plain-string bullet or a trailing parenthetical into the object form for you; a \`creates\` on an existing path or a \`refactors-existing\` on an absent one is a dry-run warning, and only a \`deletes\` naming an absent path is refused.
+- **changes** (in body string): Each entry is a **bare path string** — the default form; persist derives its assumption by probing the base branch and reports the derivation. Use the object form \`{ path, assumption }\` (\`assumption\` one of \`creates | refactors-existing | deletes\`) only to pin one yourself, and always for a \`deletes\`, which a bare path can never express. **Name the files the deliverer authors, and omit generated artifacts** — quality baselines, generated test indexes, migration journals, lockfiles and the like are regenerated by the work itself, the refresh is a close-gate concern, and declaring one needlessly reserves a footprint that serializes sibling Stories at dispatch. Acceptable path shapes include explicit files (\`src/components/Foo.tsx\`), glob patterns (\`tests/e2e/*.spec.ts\`, \`**/*.astro\`), and module identifiers that resolve to files. Pin \`refactors-existing\` for an in-place edit, \`creates\` for a net-new file, \`deletes\` for a removal, whenever the probe would get it wrong. Persist probes every path against the base branch and derives the assumption for you, so a \`creates\` on an existing path or a \`refactors-existing\` on an absent one is a dry-run warning; only a \`deletes\` naming an absent path is refused.
 - **acceptance** (top-level array on the ticket object): Each item is an **outcome a PR reviewer can confirm from the diff and the verify output** — what is true of the codebase once the Story lands, stated at the altitude of the capability (a command that now exits 0 against a named input, a behavior a named test now asserts, a config that now fails validation on a retired key, a document that now records a decision). State as many outcomes as the capability has and no more — the list has no target, floor or ceiling, and a long one is never a reason to split the Story. Push grep-shaped probes, file-exists checks and exit-code tests down into \`verify[]\`; never pin an internal helper name or a private file path into an acceptance item the advisory \`changes[]\` is free to reshape. UNACCEPTABLE: "verify by reading the diff", "looks good", "matches the spec".
-- **verify** (top-level array on the ticket object): The **mechanical checks** — exact commands or test paths the deliverer runs and the acceptance critic consumes as evidence: \`node --test tests/x.test.js\`, \`npm run lint\`, \`npm run validate\`, a scoped grep. Every acceptance item should be confirmable from at least one verify entry's output plus the diff. Stories with zero verify entries fail validation.
+- **verify** (top-level array on the ticket object): The **mechanical checks** — exact commands or test paths the deliverer runs and the acceptance critic consumes as evidence: \`node --test tests/x.test.js\`, \`npm run lint\`, \`npm run validate\`, a scoped grep. Every acceptance item should be confirmable from at least one verify entry's output plus the diff. A Story with no verify entry is warned about, not rejected — but the critic then has nothing to read as evidence, so author the commands.
 - **Bodies record decisions, never questions to the operator.** Never persist an open question ("Flag if…", "TBD", "confirm with the operator") into a Story body — the executing sub-agent is non-interactive and cannot answer it, and the dry-run warns on every one it finds. Triage each unknown by who can resolve it: an AFK-shaped unknown (a fact in docs, a third-party API surface, observable repo behavior) MUST be resolved by your own research before authoring — never restated as an assumption; only a HITL-shaped unknown (a genuine product or architecture call the operator owns) may be restated as a declarative Key Assumption the agent can act on, stating the default chosen (a decision-made-by-default).
 - **non_goals** (OPTIONAL, in body string as the \`## Non-Goals\` section): A short list of capabilities or changes this Story explicitly does NOT deliver — an advisory negative-scope bound that fences the executing agent away from adjacent work. It is **advisory and NON-GATING**: the validator does not require, count, or reject on it, and an absent or empty section renders nothing. Use the EXACT single-word hyphenated heading spelling \`## Non-Goals\` (a space-separated heading like \`## Out of Scope\` is NOT recognized by the parser and will be dropped). Reach for it when a Story's negative boundary is non-obvious from its \`acceptance[]\` alone; omit it otherwise.
 
@@ -180,19 +148,10 @@ ${envelopeFloor}
 - **A remediation sweep over one subsystem is one Story.** A batch of findings in the same subsystem shares one reason to exist — the subsystem is wrong — so it arrives as one Story whose \`## Slicing\` checkpoints carry the stages, not as one Story per finding.
 - ${singleConsumerRule}
 
-#### UI / TESTID INVARIANCE (per CLAUDE.md safety rule):
-
-Every \`changes[]\` entry is a \`{ path, assumption }\` object — a prose bullet there is rejected by the parser, so the testid contract is carried where prose belongs:
+#### UI AND COPY WORK — where the contract is written down:
 
-- Stories that touch UI (\`*.tsx\`, \`*.astro\`, \`*.svelte\`, \`*.vue\`, components folders) MUST carry the testid contract as a top-level \`acceptance[]\` item, one of:
-  - \`"data-testid invariance: <list of testids that MUST be preserved>"\`, or
-  - \`"data-testid changes: <old> -> <new>, with the matching tests/e2e/*.spec.ts selector updated"\` — paired with that \`tests/e2e/*.spec.ts\` file in \`changes[]\`, in the same Story or a depends_on Story.
-- State the preserved-testid set in \`## Non-Goals\` prose as well when the Story deliberately renames nothing.
-- Renaming a testid without the matching e2e edit is FORBIDDEN.
-
-#### BRAND / COPY / STYLE WORK:
-
-- Stories that touch user-visible copy, brand assets, or visual style MUST cite the relevant section of \`docs/style-guide.md\` in \`acceptance\` (e.g. \`"acceptance": ["Hero copy matches docs/style-guide.md §3 (voice & tone)"]\`). If \`docs/style-guide.md\` does not exist or has no relevant section, state that explicitly: \`"acceptance": ["docs/style-guide.md absent — copy reviewed against the inline brand brief in the plan seed"]\`. Silence on style sourcing is a smell.
+- A Story touching UI (\`*.tsx\`, \`*.astro\`, \`*.svelte\`, \`*.vue\`, a components folder) states the \`data-testid\` contract in \`acceptance[]\` per the testid contract in \`.agents/skills/stack/qa/playwright/SKILL.md\`.
+- A Story touching user-visible copy, brand assets or visual style cites the relevant section of \`docs/style-guide.md\` in \`acceptance[]\` when that file exists.
 
 CRITICAL: Dependencies should follow execution blockers. There is no parent ticket — never emit a 'parent_slug' field.
 IMPORTANT DEPENDENCY RULE: Story-to-Story dependencies are expressed via \`depends_on\` (one Story depends_on another Story's slug). Use this to express execution ordering across the plan.
@@ -200,10 +159,6 @@ IMPORTANT DEPENDENCY RULE: Story-to-Story dependencies are expressed via \`depen
 }
 
 /**
- * The rules that only apply once a draft has more than one Story: the
- * delivery-schedule simulation that makes each Story earn its slot, and the
- * same-wave collision refusal persist enforces at N>1.
- *
  * @returns {string}
  */
 export function renderStorySplitRules() {
@@ -229,16 +184,9 @@ Each Story carries its **own** \`## Spec\`; a shared \`techspec.md\` cannot be f
 }
 
 /**
- * The rules that only apply when the seed is an existing ticket (Story
- * #5323).
- *
- * A `--tickets` seed arrives already in Story shape — rendered `AC-<n>:`
- * checkboxes, a `## Verify` list, a `## Changes` footprint — and an author
- * reading it as a template carries that shape forward instead of re-deriving
- * it. The observed failure (swarm-os #2707 / #2708, planned from #2542 under
- * mandrel 2.57.0) was a Story whose acceptance list was the source's, handles
- * and all, and whose verify entries carried a tier suffix retired two
- * releases earlier. The source ticket is **evidence**, not a draft.
+ * A `--tickets` seed already arrives in Story shape, and an author reading it
+ * as a template carries stale handles and retired suffixes forward; the
+ * source is evidence, not a draft.
  *
  * @returns {string}
  */
@@ -255,10 +203,6 @@ You are planning from one or more existing tickets. Read them for **what the wor
 }
 
 /**
- * Render the story-author prompt for a draft of `storyCount` Stories: the
- * N=1 core, plus the schedule and partition rules when the draft has
- * siblings.
- *
  * @param {{ storyCount?: number }} [args]
  * @returns {string}
  */
@@ -268,14 +212,8 @@ export function renderStoryAuthorPrompt({ storyCount = 1 } = {}) {
 }
 
 /**
- * The mode-conditional slice of `systemPrompts`.
- *
- * `storyTicketsRules` only means anything when the seed is an existing
- * ticket, and an envelope carrying it in every mode teaches the author to
- * look for a source ticket a `--seed` run does not have. Returning a
- * spreadable object rather than a nullable string keeps the decision here,
- * beside the prompt it selects, instead of as a branch in the envelope
- * builder.
+ * Spreadable into `systemPrompts`: present only in tickets mode, since
+ * elsewhere it would send the author looking for a source ticket.
  *
  * @param {string|undefined} mode The plan-context mode.
  * @returns {{ storyTicketsRules?: string }}

package/.agents/scripts/lib/test-env.js

@@ -5,49 +5,20 @@ import path from 'node:path';
 import { TEST_TEMP_ROOT_ENV } from './config/temp-paths.js';
 import { reapOnExit } from './test-temp.js';
 
-/**
- * Per-process memo for the created scratch dir, so repeated calls in one
- * runner process (e.g. building env bags for several chunks) share a single
- * scratch tree instead of minting one dir per call.
- */
+/** Per-process memo: one scratch tree per runner process. */
 let _createdScratchDir = null;
 
-/**
- * Test-only: clear the per-process scratch memo so a suite can exercise the
- * creation branch repeatedly in one process.
- */
+/** Test-only: clear the scratch memo. */
 export function _clearTestScratchTempRootCache() {
   _createdScratchDir = null;
 }
 
 /**
- * Ensure an absolute per-process scratch tempRoot is available for the test
- * run and return it (Story #4696).
- *
- * If `baseEnv` already carries an absolute `MANDREL_TEST_TEMP_ROOT` (the
- * common case for a child process that inherits the parent runner's env),
- * that value is reused verbatim so every chunk / worker of a single suite
- * run shares one scratch dir. Otherwise a fresh `os.tmpdir()` directory is
- * created once per process (memoized). Every stream writer that resolves a
- * relative tempRoot then lands under this dir instead of the repo's real
- * `temp/` telemetry tree — the regression that let 99% of friction records
- * be test-fixture pollution.
- *
- * Reaping (Story #4808): the minting process registers removal of the
- * scratch dir at exit. This branch is creator-only by construction — a
- * process that inherited an absolute root returns above without ever
- * touching the memo, so a child can never delete its parent's scratch
- * while the parent is still writing to it. Left unreaped, this seam was
- * the single largest contributor to the OS-temp-root leak (870 surviving
- * `mandrel-test-temp-` roots on one host), because it mints one per
- * `run-tests.js` invocation.
- *
- * Directly unit-tested via the injectable `mkdtemp` seam in
- * `tests/lib/test-env.test.js` (Story #4711).
+ * Per-process scratch tempRoot keeping tests out of real `temp/` telemetry.
+ * An inherited absolute root is reused; only the minting process reaps it.
  *
  * @param {NodeJS.ProcessEnv} [baseEnv=process.env]
  * @param {{ mkdtemp?: typeof mkdtempSync, onExit?: (fn: () => void) => void }} [deps]
- *   Injectable for tests.
  * @returns {string} absolute scratch tempRoot
  */
 export function ensureTestScratchTempRoot(
@@ -70,39 +41,15 @@ export function ensureTestScratchTempRoot(
 }
 
 /**
- * Build a webhook-safe child-process environment for test runners.
- *
- * Operators keep a real `NOTIFICATION_WEBHOOK_URL` in `.env` for development
- * (the production `notify()` path reads it via `process.env` after
- * `resolveConfig()` calls `loadEnv()`). Without scrubbing, any test that
- * transitively reaches `notify()` POSTs to the live endpoint.
- *
- * This helper produces the env bag that test child processes inherit:
+ * Env bag for test child processes:
  *
- *   - `NOTIFICATION_WEBHOOK_URL` is deleted unless the operator opted in
- *     via `MANDREL_ALLOW_TEST_WEBHOOKS=1` (e.g., a contract test
- *     deliberately exercising a sandbox endpoint). With the URL scrubbed,
- *     `resolveWebhookUrl()` returns nothing and `notify()` never POSTs.
- *   - `NODE_ENV=test` is set for the rest of the suite's environment
- *     expectations. (It no longer gates `notify()`'s webhook delivery —
- *     the NODE_ENV band-aid was removed in Story #3342. Tests that need to
- *     exercise the webhook POST inject `opts.fetchImpl` instead, so the
- *     request never reaches the real network even if a URL resolves.)
- *   - Every `GIT_*` variable is dropped. When the suite runs inside a git
- *     hook (husky pre-push via the coverage-capture path), the parent git
- *     invocation exports `GIT_DIR` — from a linked worktree, the absolute
- *     `<main>/.git/worktrees/<name>` path. A test fixture's `git init`
- *     under that env re-initializes the shared gitdir and writes
- *     `core.bare=true` into the MAIN checkout's `.git/config`, breaking
- *     every worktree at once (#4580). Production git call sites are
- *     covered by `cleanGitEnv` in `git-utils.js`; this is the same scrub
- *     for test child processes, which may spawn git directly. Tests that
- *     need a `GIT_*` variable set it explicitly on their own spawn.
- *   - `MANDREL_TEST_TEMP_ROOT` is set to an absolute per-process scratch
- *     dir (Story #4696). Any test that reaches a stream writer without
- *     injecting its own absolute tempRoot lands under scratch instead of
- *     the repo's real `temp/` telemetry tree, so the suite can no longer
- *     append fixture records to friction / lifecycle / trace streams.
+ *   - `NOTIFICATION_WEBHOOK_URL` is deleted (unless
+ *     `MANDREL_ALLOW_TEST_WEBHOOKS=1`) so no test POSTs to a live endpoint;
+ *   - `NODE_ENV` defaults to `test`;
+ *   - every `GIT_*` is dropped: inside a git hook `GIT_DIR` points at the
+ *     shared gitdir, and a fixture's `git init` there writes `core.bare=true`
+ *     into the main checkout, breaking every worktree;
+ *   - `MANDREL_TEST_TEMP_ROOT` points at the per-process scratch root.
  *
  * @param {NodeJS.ProcessEnv} baseEnv
  * @returns {NodeJS.ProcessEnv}