mandrel 1.88.0 → 1.90.0

package/.agents/scripts/standalone-feedback-rollup.js

@@ -0,0 +1,188 @@
+#!/usr/bin/env node
+
+/**
+ * standalone-feedback-rollup.js — end-of-run feedback rollup for the
+ * `/deliver` standalone multi-Story path (Epic #4406 / Story #4416).
+ *
+ * The standalone delivery path (`helpers/deliver-stories`) drives one or
+ * more Epic-free Stories to green, and each per-Story sub-agent appends
+ * `friction` records to its **standalone** signals stream at
+ * `temp/standalone/stories/story-<sid>/signals.ndjson` (written via
+ * `appendSignal({ epicId: null, storyId })`). Before this rollup that
+ * tree was write-only — nothing ever read it back. This CLI closes the
+ * gap: it scans the standalone streams for the delivered Story set and
+ * emits a per-category friction summary that `deliver-stories.md`
+ * surfaces in its Phase 3 run summary.
+ *
+ * Usage:
+ *   node standalone-feedback-rollup.js --stories <id,...>
+ *
+ * Contract:
+ *   - Stream paths resolve **exclusively** through the `temp-paths`
+ *     helpers via `forEachLine(null, storyId, cb, config)` — the `null`
+ *     Epic sentinel routes to the standalone tree. No hand-built path
+ *     strings.
+ *   - Aggregates `friction` records by their **top-level** `category`
+ *     (Epic #4406 canonical envelope shape); a record with no category
+ *     buckets under `Unknown`.
+ *   - **Never fails a run.** A missing or empty stream degrades to an
+ *     empty contribution; the CLI always prints a JSON summary and
+ *     exits 0. Observability MUST NOT take down the delivering flow.
+ *
+ * Output (stdout, one JSON object):
+ *   {
+ *     "kind": "standalone-feedback-rollup",
+ *     "stories": [<id>, ...],
+ *     "totalFriction": <int>,
+ *     "byCategory": { "<category>": <count>, ... },
+ *     "perStory": { "<id>": { "friction": <int>, "missing": <bool> }, ... }
+ *   }
+ *
+ * @see .agents/scripts/lib/observability/signals-writer.js (forEachLine, appendSignal)
+ * @see .agents/scripts/lib/config/temp-paths.js (signalsFile — null Epic sentinel)
+ * @see .agents/workflows/helpers/deliver-stories.md (Phase 3 summary wiring)
+ */
+
+import { runAsCli } from './lib/cli-utils.js';
+import { resolveConfig } from './lib/config-resolver.js';
+import { forEachLine } from './lib/observability/signals-writer.js';
+
+const FRICTION_KIND = 'friction';
+const UNKNOWN_CATEGORY = 'Unknown';
+
+/**
+ * Parse `--stories <id,...>` into an ordered, de-duplicated array of
+ * positive-integer Story IDs. Accepts a single comma-separated value or
+ * repeated `--stories` flags. Non-integer / non-positive tokens are
+ * rejected so a typo surfaces as an input error rather than a silently
+ * empty rollup.
+ *
+ * @param {string[]} args
+ * @returns {{ stories: number[] }}
+ */
+export function parseArguments(args) {
+  const raw = [];
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--stories') {
+      const value = args[++i];
+      if (typeof value === 'string') {
+        raw.push(...value.split(','));
+      }
+    }
+  }
+
+  const seen = new Set();
+  const stories = [];
+  for (const token of raw) {
+    const trimmed = token.trim();
+    if (trimmed.length === 0) continue;
+    const id = Number(trimmed);
+    if (!Number.isInteger(id) || id <= 0) {
+      throw new Error(
+        `--stories expects comma-separated positive integers; got ${JSON.stringify(trimmed)}`,
+      );
+    }
+    if (seen.has(id)) continue;
+    seen.add(id);
+    stories.push(id);
+  }
+
+  if (stories.length === 0) {
+    throw new Error(
+      'Usage: node standalone-feedback-rollup.js --stories <id,...>',
+    );
+  }
+
+  return { stories };
+}
+
+/**
+ * Read one standalone Story's signals stream and aggregate its `friction`
+ * records by top-level `category`, mutating the shared `byCategory` tally.
+ *
+ * Degrades to a zero contribution on a missing / empty / unreadable
+ * stream — `forEachLine` already swallows fs + JSON faults and reports a
+ * missing file via `{ missing: true }` rather than throwing.
+ *
+ * @param {number} storyId
+ * @param {Record<string, number>} byCategory Mutated in place.
+ * @param {object} config
+ * @returns {Promise<{ friction: number, missing: boolean }>}
+ */
+async function rollupStory(storyId, byCategory, config) {
+  let friction = 0;
+  // `epicId: null` routes forEachLine → signalsFile(null, storyId, config)
+  // → the standalone tree. Never a hand-built path string.
+  const result = await forEachLine(
+    null,
+    storyId,
+    (record) => {
+      if (
+        record === null ||
+        typeof record !== 'object' ||
+        record.kind !== FRICTION_KIND
+      ) {
+        return;
+      }
+      const category =
+        typeof record.category === 'string' && record.category.length > 0
+          ? record.category
+          : UNKNOWN_CATEGORY;
+      byCategory[category] = (byCategory[category] ?? 0) + 1;
+      friction += 1;
+    },
+    config,
+  );
+
+  return { friction, missing: Boolean(result?.missing) };
+}
+
+/**
+ * Aggregate friction across every named standalone Story stream.
+ *
+ * @param {number[]} stories
+ * @param {object} [config]
+ * @returns {Promise<{
+ *   kind: string,
+ *   stories: number[],
+ *   totalFriction: number,
+ *   byCategory: Record<string, number>,
+ *   perStory: Record<string, { friction: number, missing: boolean }>,
+ * }>}
+ */
+export async function buildRollup(stories, config) {
+  const byCategory = {};
+  const perStory = {};
+  let totalFriction = 0;
+
+  for (const storyId of stories) {
+    const { friction, missing } = await rollupStory(
+      storyId,
+      byCategory,
+      config,
+    );
+    perStory[storyId] = { friction, missing };
+    totalFriction += friction;
+  }
+
+  return {
+    kind: 'standalone-feedback-rollup',
+    stories,
+    totalFriction,
+    byCategory,
+    perStory,
+  };
+}
+
+export async function main(args = process.argv.slice(2)) {
+  const { stories } = parseArguments(args);
+  const config = resolveConfig();
+  const summary = await buildRollup(stories, config);
+  process.stdout.write(`${JSON.stringify(summary, null, 2)}\n`);
+  return 0;
+}
+
+runAsCli(import.meta.url, main, {
+  source: 'StandaloneFeedbackRollup',
+  propagateExitCode: true,
+});

package/.agents/scripts/story-close.js

@@ -10,6 +10,9 @@
  * envelope. Pipeline shape:
  *
  *   1. parse + resolveCloseInputs (lib/orchestration/story-close/close-inputs.js)
+ *   1.5. already-done no-op guard (inline below) — a Story already at
+ *      `agent::done` AND closed short-circuits here so no phase below it
+ *      ever flips the label away from `agent::done` or reopens the issue.
  *   2. preflight                  (phases/preflight.js)
  *   3. state-flip → closing       (inline helper below)
  *   4. capture starting branch    (phases/branch-restore.js)
@@ -152,6 +155,51 @@ export async function runStoryClose({
     storyBranch,
   } = resolved;
 
+  // Phase 0 — idempotency guard. A re-run against a Story that is already
+  // fully closed must be a safe no-op. Without this guard, Phase 3 below
+  // (`transitionToClosing`) unconditionally flips the label to
+  // `agent::closing` — and `transitionTicketState`
+  // (lib/orchestration/ticketing/transition.js) unconditionally sends
+  // `state: 'open'` for any non-`agent::done` target — so re-running close
+  // against an already-closed Story reopens the GitHub issue and strips
+  // `agent::done` *before* the post-merge pipeline even starts. If the
+  // pipeline then throws or a phase silently no-ops (the merge is already
+  // fully reaped, so there is nothing left to redo), the Story is left
+  // regressed at `agent::closing`/OPEN instead of a safe no-op.
+  //
+  // The "already fully closed" test mirrors the deepest-level guard in the
+  // post-merge `ticketClosurePhase` (post-merge/phases/ticket-closure.js):
+  // label `agent::done` AND issue `state === 'closed'`, an AND — never a
+  // state-alone check. The `state === 'closed'` disjunct is deliberately
+  // excluded per the hard-won reasoning in
+  // `lib/single-story/confirm-merge.js`: a Story can arrive here closed at
+  // the GitHub layer (a `Closes #<id>` PR footer, or a prior close that set
+  // `state: closed` but was killed before the label flip landed) while its
+  // label is legitimately still `agent::closing`. Treating that as
+  // already-done would skip the very `closing → done` re-assertion the
+  // re-run exists to perform, stranding the label. Requiring BOTH signals
+  // no-ops only a genuinely finished Story.
+  const alreadyDone =
+    Array.isArray(story?.labels) &&
+    story.labels.includes(STATE_LABELS.DONE) &&
+    story?.state === 'closed';
+  if (alreadyDone) {
+    progress(
+      'SKIP',
+      `Story #${storyId} is already ${STATE_LABELS.DONE} and closed — no-op re-run.`,
+    );
+    return {
+      success: true,
+      result: {
+        storyId,
+        epicId,
+        action: 'noop',
+        reason: 'already-done',
+        merged: true,
+      },
+    };
+  }
+
   const notifyFn = (ticketId, payload, opts = {}) =>
     notify(ticketId, payload, { config, provider, ...opts });
 

package/.agents/scripts/story-plan.js

@@ -10,9 +10,11 @@
  *
  *   1. `--emit-context` mode — given a `--idea`/`--from-notes` seed,
  *      build the context envelope (seed, refine heuristic, persona,
- *      body template, duplicate candidates, tech-stack summary) and
- *      print it as JSON on stdout. Logs route to stderr so the
- *      envelope is byte-clean for `JSON.parse`.
+ *      body template, duplicate candidates, tech-stack summary, and a
+ *      corpus-aware `corpusContext` — the docs digest plus relevant
+ *      existing-Epic Tech Spec excerpts, Story #4432) and print it as
+ *      JSON on stdout. Logs route to stderr so the envelope is
+ *      byte-clean for `JSON.parse`.
  *   2. Persist mode — given a `--body <file>` authored by the host
  *      LLM after operator confirmation, validate the shape and persist
  *      via `provider.createIssue` (which also adds the new Story to
@@ -30,12 +32,14 @@
  */
 
 import { readFile } from 'node:fs/promises';
+import path from 'node:path';
 import { parseArgs } from 'node:util';
 import { runAsCli } from './lib/cli-utils.js';
 import { PROJECT_ROOT, resolveConfig } from './lib/config-resolver.js';
 import { exec as ghExec } from './lib/gh-exec.js';
 import { Logger, routeAllOutputToStderr } from './lib/Logger.js';
 import { TYPE_LABELS } from './lib/label-constants.js';
+import { buildCorpusContext } from './lib/planning-corpus.js';
 import { createProvider } from './lib/provider-factory.js';
 import {
   buildContextEnvelope,
@@ -130,7 +134,17 @@ export function extractTitle(body) {
   return m ? m[1].trim() : 'Untitled standalone Story';
 }
 
-async function runEmitContext({ values, provider, projectRoot }) {
+async function runEmitContext({
+  values,
+  provider,
+  projectRoot,
+  config,
+  // Injectable stdout port so unit tests can capture the emitted envelope
+  // without stubbing the process-global stream (mirrors the `runPersist`
+  // pattern above — raw stdout writes corrupt the `node --test` runner's
+  // structured report stream).
+  write = (s) => process.stdout.write(s),
+}) {
   const seed = await resolveSeed({
     idea: values.idea,
     fromNotes: values['from-notes'],
@@ -139,11 +153,29 @@ async function runEmitContext({ values, provider, projectRoot }) {
   const refine = shouldRefine({ seed, override });
   const persona = values.persona ?? 'engineer';
 
-  const [bodyTemplate, openStories, techStack] = await Promise.all([
-    loadBodyTemplate(projectRoot),
-    fetchOpenStories(provider),
-    readTechStackSummary(projectRoot),
-  ]);
+  // Corpus lookup uses the raw (un-defaulted) docsContextFiles list, same
+  // as the `/deliver` per-Epic digest builder: `config.project` fills in
+  // the framework's default four-file set even when the operator
+  // configured nothing, so a null-vs-configured distinction requires
+  // reading `config.raw` directly.
+  const docsContextFiles = config?.raw?.project?.docsContextFiles ?? [];
+  // Resolve docsRoot against PROJECT_ROOT (not process.cwd()) so the
+  // corpus digest reads the project's actual docs directory regardless
+  // of the directory this CLI happens to be invoked from — matching the
+  // sibling resolution pattern in
+  // epic-plan-spec/phases/authoring-context.js.
+  const docsRoot = path.resolve(
+    PROJECT_ROOT,
+    config?.project?.paths?.docsRoot ?? 'docs',
+  );
+
+  const [bodyTemplate, openStories, techStack, corpusContext] =
+    await Promise.all([
+      loadBodyTemplate(projectRoot),
+      fetchOpenStories(provider),
+      readTechStackSummary(projectRoot),
+      buildCorpusContext({ seed, provider, docsContextFiles, docsRoot }),
+    ]);
 
   const duplicateCandidates = rankDuplicateCandidates({
     seed,
@@ -157,12 +189,13 @@ async function runEmitContext({ values, provider, projectRoot }) {
     bodyTemplate,
     duplicateCandidates,
     techStack,
+    corpusContext,
   });
 
   const json = values.pretty
     ? JSON.stringify(envelope, null, 2)
     : JSON.stringify(envelope);
-  process.stdout.write(`${json}\n`);
+  write(`${json}\n`);
 }
 
 async function runPersist({
@@ -267,7 +300,7 @@ async function main() {
     // unconditionally parseable by `JSON.parse`. Mirrors the contract
     // `epic-plan-spec.js` enforces for its own --emit-context mode.
     routeAllOutputToStderr();
-    return runEmitContext({ values, provider, projectRoot });
+    return runEmitContext({ values, provider, projectRoot, config });
   }
 
   return runPersist({
@@ -281,4 +314,10 @@ runAsCli(import.meta.url, main, { source: 'story-plan' });
 
 // Test surface — exported so unit tests can drive the helpers
 // without importing the CLI side.
-export { fetchOpenStories, renderGhArgv, runPersist };
+export {
+  fetchOpenStories,
+  renderGhArgv,
+  resolveSeed,
+  runEmitContext,
+  runPersist,
+};

package/.agents/scripts/validate-docs-freshness.js

@@ -1,5 +1,4 @@
 #!/usr/bin/env node
-/* node:coverage ignore file -- pre-push docs-freshness gate; pure git-mtime walk with no testable branching beyond filesystem state */
 
 /**
  * .agents/scripts/validate-docs-freshness.js — Documentation Freshness Gate
@@ -10,18 +9,28 @@
  *
  *   1. `git log --all --grep="#<epicId>" -- <file>` returns a commit —
  *      the Epic ID was referenced in a commit message that touched the
- *      file.
- *   2. The file's current body contains `#<epicId>` — a human annotation
- *      (e.g., a CHANGELOG entry) explicitly ties the change to this Epic.
+ *      file. This is the pass path for **every** doc.
+ *   2. The file's current body contains `#<epicId>` — but this
+ *      body-annotation path is accepted **only for changelog-class files**
+ *      (basename matches `/changelog/i`), where an appended release note
+ *      keyed to the Epic is the legitimate, expected update. Any other doc
+ *      (architecture, decisions, README, …) MUST pass via condition 1: the
+ *      living doc has to be **rewritten in an Epic-referencing commit**, not
+ *      merely annotated with `#<epicId>`.
  *
  * The prior gate accepted any diff against the base branch — a stray
  * whitespace edit or a one-line unrelated cleanup passed, defeating the
  * purpose of the check. Requiring an Epic-ID reference makes "did you
  * update the docs for this Epic?" a falsifiable question instead of a
- * checkbox.
+ * checkbox. The changelog-only restriction on condition 2 closes the
+ * follow-on perverse incentive: without it, the gate rewarded appending
+ * `#<epicId>` history into living docs (manufacturing fake provenance) to
+ * satisfy the check. Restricting the annotation path to changelog files
+ * makes the gate ask "was this doc rewritten for the Epic?" rather than
+ * "does it mention the Epic?".
  *
  * Usage:
- *   node .agents/scripts/validate-docs-freshness.js --epic <EPIC_ID> [--base main] [--docs <comma-separated>] [--json]
+ *   node .agents/scripts/validate-docs-freshness.js --epic <EPIC_ID> [--docs <comma-separated>] [--json]
  *
  * `--json` emits a single JSON object on stdout with
  *   { ok, epicId, results: [{ file, pass, reason }, ...] }
@@ -76,6 +85,20 @@ export function resolveDocList(config) {
   return Array.from(new Set(resolved));
 }
 
+/**
+ * A doc is "changelog-class" when its basename matches `/changelog/i`
+ * (e.g. `CHANGELOG.md`, `docs/CHANGELOG.md`, `changelog.mdx`). Only these
+ * files may satisfy the freshness gate via a body annotation (pass
+ * condition 2); every other doc must pass via an Epic-referencing commit
+ * (pass condition 1).
+ *
+ * @param {string} file
+ * @returns {boolean}
+ */
+export function isChangelogClass(file) {
+  return /changelog/i.test(path.basename(file));
+}
+
 function epicRefMatcher(epicId) {
   // Match `#N` as a standalone token. `(?!\d)` prevents `#10` from
   // satisfying a search for `#1` — a subtle bug the prior diff-only gate
@@ -83,6 +106,8 @@ function epicRefMatcher(epicId) {
   return new RegExp(`#${epicId}(?!\\d)`);
 }
 
+/* node:coverage disable -- real `git log` shell-out; exercised via the
+   injectable `commitsForFile` seam in runFreshnessGate, not directly. */
 function commitsMentioningEpic(docPath, epicId, cwd = PROJECT_ROOT) {
   const res = gitSpawn(
     cwd,
@@ -99,6 +124,7 @@ function commitsMentioningEpic(docPath, epicId, cwd = PROJECT_ROOT) {
     .map((s) => s.trim())
     .filter(Boolean);
 }
+/* node:coverage enable */
 
 function fileBodyMentionsEpic(
   docPath,
@@ -145,17 +171,29 @@ export function runFreshnessGate({
         reason: `${commits.length} commit(s) reference Epic #${epicId}`,
       };
     }
-    if (fileBodyMentionsEpic(file, epicId, cwd, readFileImpl)) {
+    // Pass condition 2 (body annotation) is restricted to changelog-class
+    // files. For every other doc, an appended `#<epicId>` no longer passes —
+    // the living doc must be rewritten in an Epic-referencing commit.
+    const changelogClass = isChangelogClass(file);
+    if (
+      changelogClass &&
+      fileBodyMentionsEpic(file, epicId, cwd, readFileImpl)
+    ) {
       return {
         file,
         pass: true,
-        reason: `body mentions #${epicId}`,
+        reason: `changelog body annotation references #${epicId}`,
       };
     }
     return {
       file,
       pass: false,
-      reason: `no commit message or body reference to #${epicId}`,
+      reason: changelogClass
+        ? `no commit message or changelog body reference to #${epicId}`
+        : `${file} was not rewritten in an Epic-referencing commit for #${epicId} — ` +
+          `living docs must be REWRITTEN in a commit whose message references ` +
+          `#${epicId} (not annotated with #${epicId}); the body-annotation path ` +
+          `passes only for changelog-class files`,
     };
   });
   return { ok: results.every((r) => r.pass), results };
@@ -172,7 +210,6 @@ export function parseFreshnessArgs(argv) {
     args: argv,
     options: {
       epic: { type: 'string' },
-      base: { type: 'string' },
       docs: { type: 'string' },
       json: { type: 'boolean', default: false },
     },
@@ -196,12 +233,25 @@ export function renderFreshnessLine(result) {
   return `[docs-freshness] ${result.pass ? '✅' : '❌'} ${result.file} — ${result.reason}`;
 }
 
-/** Pure: build the failure message for the operator. */
-export function renderFreshnessFailureMessage(epicId) {
+/**
+ * Pure: build the failure message for the operator. Names the failing
+ * file(s) and states the rewrite-not-append contract explicitly.
+ *
+ * @param {number} epicId
+ * @param {Array<{ file: string, pass: boolean }>} [results]
+ */
+export function renderFreshnessFailureMessage(epicId, results = []) {
+  const failing = results.filter((r) => !r.pass).map((r) => r.file);
+  const fileList = failing.length > 0 ? failing.join(', ') : '(see rows above)';
   return (
     `[docs-freshness] ❌ Documentation freshness gate FAILED for Epic #${epicId}.\n\n` +
-    `Update each failing file so its commit message or body references #${epicId}, ` +
-    `then re-run /deliver.`
+    `Failing file(s): ${fileList}\n\n` +
+    `Living docs satisfy this gate by being REWRITTEN in an Epic-referencing ` +
+    `commit — a commit whose message references #${epicId} and touches the ` +
+    `file — NOT by appending a #${epicId} annotation to the body. The ` +
+    `body-annotation path passes ONLY for changelog-class files (basename ` +
+    `matches /changelog/i). Rewrite each failing file for the Epic, then ` +
+    `re-run /deliver.`
   );
 }
 
@@ -210,6 +260,9 @@ export function renderFreshnessSuccessMessage(epicId, count) {
   return `[docs-freshness] ✅ All ${count} doc(s) reference Epic #${epicId}.`;
 }
 
+/* node:coverage disable -- process I/O + real config/git wiring (stdout,
+   process.exit, resolveConfig, runAsCli); the pure logic these thin wrappers
+   call is covered directly above. */
 function reportEmptyDocs(epicId, json) {
   if (json) {
     process.stdout.write(
@@ -234,7 +287,7 @@ function reportGateOutcome({ epicId, json, ok, results }) {
     Logger.info(renderFreshnessSuccessMessage(epicId, results.length));
     return;
   }
-  Logger.error(renderFreshnessFailureMessage(epicId));
+  Logger.error(renderFreshnessFailureMessage(epicId, results));
   process.exit(1);
 }
 
@@ -257,3 +310,4 @@ async function main() {
 }
 
 runAsCli(import.meta.url, main, { source: 'validate-docs-freshness' });
+/* node:coverage enable */

package/.agents/skills/core/documentation-and-adrs/SKILL.md

@@ -316,6 +316,64 @@ For shipped features:
 - Task list now loads 50 items per page (was 20) for better UX (#126)
 ```
 
+## Pruning & Archiving
+
+Living docs accrete history — dated changelog entries, closed decision-log
+rows, completed rollout checklists, resolved runbook incidents. Left
+unpruned, that verbatim history crowds out the live guidance a reader (human
+or agent) actually needs, and every task that loads the doc re-pays the cost.
+The fix is to **archive, don't delete**: relocate the cold history so the live
+doc stays lean while the record stays recoverable.
+
+### The archive-don't-delete rule
+
+**History is preserved by _moving_ it, never by deleting it.** Pruning a doc
+never destroys its past — the verbatim content is relocated to a dated archive
+file under version control, so the full record remains diffable and
+recoverable. Deleting history outright (even with "git has it") is the
+anti-pattern this convention exists to prevent: the archive is discoverable
+from the live doc, a buried git revision is not.
+
+### How to prune a doc
+
+1. **Extract the still-live signal first — before you archive anything.**
+   Gotchas, traps, and hard-won caveats buried in the history are the most
+   valuable lines in the doc. Lift them into the live doc's standing guidance
+   (a "Known gotchas" list, an inline warning, or an ADR) **before** the
+   history moves. Archiving first risks stranding a live trap in a cold file
+   nobody rereads.
+2. **Move the verbatim history to a dated archive file.** Relocate the cold
+   content — untouched, word-for-word — to
+   `docs/archive/<name>-<YYYY-MM>.md`, where `<name>` is the source doc's base
+   name and `<YYYY-MM>` is the archive date (e.g. `docs/archive/changelog-2025-01.md`,
+   `docs/archive/decisions-2024-11.md`). The archive is an exact copy of what
+   was live; do not summarize or rewrite it in the move.
+3. **Collapse completed checklists to a one-line summary.** A finished
+   checklist (a rollout runbook, a migration plan, a release gate) does not
+   need to keep every ticked box in the live doc. Replace it with a single
+   line recording the outcome and date — e.g.
+   `Auth-migration rollout — completed 2025-01-18, all 12 steps green` — and
+   let the archived copy carry the full detail.
+4. **Leave a one-line pointer behind.** Every archived doc leaves exactly one
+   line in the live doc pointing at where its history went, so the record is
+   never orphaned — e.g.
+   `Older entries archived to docs/archive/changelog-2024.md`. The pointer is
+   what makes "moved, not deleted" true from the reader's vantage point.
+
+### When to prune
+
+- A changelog, decision log, or runbook has grown long enough that the live
+  entries are hard to find among the historical ones.
+- A checklist or rollout plan is fully complete and its step-by-step detail is
+  now reference-only.
+- A doc reloaded into agent context on many tasks carries more cold history
+  than live guidance.
+
+Do **not** prune ADRs by archiving — an ADR that no longer holds is
+**superseded** in place (see [ADR Lifecycle](#adr-lifecycle)), keeping the
+numbered chain intact. Archiving is for the accreted history of living docs,
+not for the immutable decision record.
+
 ## Documentation for Agents
 
 Special consideration for AI agent context:

package/.agents/skills/core/epic-plan-decompose-author/SKILL.md

@@ -17,7 +17,8 @@ allowed_tools:
 
 - Run only after `epic-plan-decompose.js --emit-context` has written `temp/epic-<Epic_ID>/decomposer-context.json`; fail loudly if the file is missing.
 - Emit exactly one artifact: `temp/epic-<Epic_ID>/tickets.json` (a JSON array). Do not write anywhere else, and never call the GitHub API from this Skill — persistence belongs to the script.
-- Output is JSON only — no prose, no Markdown fence. The downstream validator (`lib/orchestration/ticket-validator.js`) is the authoritative gate; re-author rather than hand-patching when it rejects.
+- Output is JSON only — no prose, no Markdown fence. The downstream validator (`lib/orchestration/ticket-validator.js`) is the authoritative gate.
+- **Re-emit rule (amend, don't regenerate — Story #4431).** On a re-emit — the validator rejecting the draft, or a Phase 8.3/8.4/8.5 critic flagging specific Stories — apply **targeted edits** to the existing `temp/epic-<Epic_ID>/tickets.json`, fixing only the rejected or flagged Stories, rather than re-authoring the whole array from scratch. `helpers/plan-epic.md` bounds each critic's feedback to **one refinement pass** — apply the edit and re-run the downstream step once; do not loop.
 - Treat **`maxTickets`** from the context envelope as a **reviewability budget**, not a hard authoring cap (Story #2798). Merge narrow, single-module Stories into their capability first; if the plan genuinely needs more, emit the full plan and add a compact `over_budget_rationale` note inside the first Story's `## Goal` section explaining why the plan exceeds the budget. Operator persistence then requires the explicit `--allow-over-budget` override on `epic-plan-decompose.js`; without it the persist step rejects the over-budget array. Never truncate the JSON array to fit.
 - Honour the 2-tier hierarchy: every ticket is a **Story** attached directly to the Epic. Stories carry the implementation scope inline; no Feature and no lower ticket tier exists. Thematic grouping is prose in the Epic body / Tech Spec, never a ticket.
 - **Decompose at deliverable granularity, not module/task level.** A Story is a capability slice a frontier model delivers and self-verifies in one pass — a shippable slice a reviewer would accept as a single PR — not a single module or file. See the STORY SIZING section for the full guidance and the single-consumer merge rule.
@@ -435,5 +436,6 @@ any logical ordering requirement via Story-level `depends_on`.
   loudly. Instruct the caller to run `--emit-context` first.
 - The validator
   ([`lib/orchestration/ticket-validator.js`](../../../scripts/lib/orchestration/ticket-validator.js))
-  is the authoritative gate. Re-author when it rejects rather than
-  patching tickets by hand.
+  is the authoritative gate. On rejection, apply the re-emit rule above —
+  a targeted edit to the existing `tickets.json` fixing only what was
+  rejected — rather than re-authoring the array from scratch.