mandrel 1.87.0 → 1.89.0

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.

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

@@ -34,6 +34,7 @@ allowed_tools:
 
 - Run only during `/plan` Phase 7, after `epic-plan-spec.js --emit-context` has written `temp/epic-<Epic_ID>/planner-context.json`; fail loudly if the file is missing rather than fabricating context.
 - Write exactly three artifacts and only inside `temp/epic-<Epic_ID>/`: `techspec.md`, `risk-verdict.json`, `acceptance-spec.md`. All three MUST exist on disk before returning.
+- **Re-emit rule (amend, don't regenerate — Story #4431).** On a re-emit — the Phase 7 persist call rejecting an artifact (e.g. a missing `## Delivery Slicing` heading, a schema-invalid risk verdict) — apply **targeted edits** to the existing `temp/epic-<Epic_ID>/` artifact that fix only what the rejection named; do NOT rewrite an artifact wholesale from a blank draft. `helpers/plan-epic.md` bounds this to **one refinement pass** per invocation (the same shape as the Epic Clarity Gate's own "one refinement pass per invocation" contract) — do not loop.
 - Start each markdown artifact at the correct `##` heading (Tech Spec → `## Delivery Slicing`, Acceptance Spec → `## Acceptance Table` — never the Epic's own `## Acceptance Criteria` heading, which stays the ideation bullets) — never emit a top-level `#` heading. `risk-verdict.json` is raw JSON conforming to `.agents/schemas/risk-verdict.schema.json`.
 - The Tech Spec MUST open with `## Delivery Slicing` and MUST NOT restate the Epic's Context, Goal, or Scope — your output lands as sections of the same Epic body, which travels into every downstream story agent's prompt, so any restatement is duplication and a drift risk. A `## Technical Overview` section is optional and, when present, is a 2–3 sentence orientation of the *technical approach* only (which subsystems are touched and reused), never a re-narration of the problem statement, goals, or scope.
 - Judge risk from what the change *does* (the Epic body / Tech Spec you just wrote), never from keyword presence — "out of scope: billing" is not a billing change; "rotate the credential vault" is high-risk even without a security keyword.
@@ -75,15 +76,24 @@ reads:
   Fields:
   - `epic.id`, `epic.title`, `epic.body` (or `epic.bodySummary` when the
     planning-context budget downgrades the body to a summary)
-  - `docsContext.items[]` — bounded project docs scraped from the configured
-    `docsRoot` (start with these for "how does the codebase do X today?"
-    context; the validator already capped their size)
+  - `docsContext` — digest-first (Story #4433, hard cutover of the § 3.1
+    planning read contract): `{ mode: 'digest', digestPath }` pointing at
+    the per-Epic docs digest (`<tempRoot>/epic-<Epic_ID>/docs-digest.md` —
+    the same file the `/deliver` story sub-agents already consume, Story
+    #4338 / #4324), or `null` when `project.docsContextFiles` is unset. Read
+    the digest at `digestPath` for "how does the codebase do X today?"
+    orientation (path, byte size, heading outline with line numbers, first
+    paragraph per `##` section), then pull the full file on demand with your
+    own Read tool — jump straight to the line the digest names — only when a
+    section bears on the spec. There is no full-content `items[]` field;
+    embedding whole/summarized doc bodies in this envelope was retired in
+    the same cutover that made the `/deliver` children digest-first.
   - `codebaseSnapshot` — Story #2634 structural view of the consumer repo
     (file tree, `package.json` exports + scripts, recently-touched
     directories, detected test runner + BDD feature roots, and — at the
     `medium` tier — per-file export signatures). Prefer module / file
     names that appear in this snapshot over names that appear only in
-    `docsContext.items[]`; the docs may be stale relative to the actual
+    the docs digest; the docs may be stale relative to the actual
     source tree. When the spec needs to cite a file that is **not** in
     `codebaseSnapshot.files`, surface that as a `<!-- DRIFT -->` callout
     in the Tech Spec body naming the cited path, so the freshness gate
@@ -151,13 +161,16 @@ or (for the verdict) schema-invalid.
 
 Read `temp/epic-<Epic_ID>/planner-context.json` with the `Read` tool. Pull
 the Epic title, body (or body summary, including the Epic's `## User Stories`
-section), the `docsContext` items, and (for reference) the two system prompts.
+section), and the `docsContext` digest pointer (`digestPath`, or `null`).
+When non-null, read the digest file at `digestPath` next — that outline,
+not the planner-context envelope, is where the actual doc orientation
+lives; pull a full doc on demand only when a section looks relevant.
 
 ### Step 2 — Author the Tech Spec (Engineering Architect persona)
 
 Apply the Tech Spec system prompt below to the Epic body (Context / Goal /
-Scope / User Stories), the
-`docsContext` items, and the `codebaseSnapshot` envelope (so the spec is
+Scope / User Stories), the docs digest (plus any full file pulled on
+demand), and the `codebaseSnapshot` envelope (so the spec is
 grounded in the actual codebase, not hallucinated patterns). Cite module
 and file names from `codebaseSnapshot.files` / `codebaseSnapshot.signatures`
 before reaching for names that appear only in the documentation. Write to

package/.agents/skills/core/scope-triage/SKILL.md

@@ -86,6 +86,67 @@ or a small Epic, and neither call is clearly right. **Present the choice rather
 than deciding for the operator.** Do not force a verdict to avoid the third
 option; a borderline scope surfaced as borderline is the correct output.
 
+## Change-Request Triage Rubric
+
+A **change request** — "fix this", "tweak that", "extend the existing X" —
+is the common case this rubric routes cheaply: a delta against a surface the
+project already shipped, not a from-scratch capability. Route it to `story`
+by default when all three delta signals hold; treat any one signal's absence
+as a prompt to re-check, not an automatic `epic` bump.
+
+### Delta signals
+
+- **Delta to an already-delivered surface.** The request references a
+  concrete existing capability (a module, workflow, script, or shipped
+  feature) rather than proposing a new one. "Fix the flaky retry in
+  `evidence-gate.js`" is a delta; "add a retry framework" is not.
+- **Existing corpus covers the touched area.** The project's docs digest
+  and/or an already-closed or in-flight Epic's Tech Spec section already
+  describe the surface being changed — the standalone-Story path can draft
+  against that inherited context (`corpusContext` in the `/plan --idea`
+  envelope) instead of re-deriving architecture from a blank slate. When no
+  corpus hit exists for the touched area, that is a signal the request may
+  be reaching into genuinely new territory — re-check the `epic` signals
+  below before defaulting to `story`.
+- **Footprint fits Story sizing.** The plausible file footprint and
+  acceptance-criteria count still fit the Story width in
+  `DEFAULT_TASK_SIZING` (per the `story` verdict signals above) — a change
+  request that fans out across independent subsystems is sized like an Epic
+  regardless of how small the originating request sounded.
+
+### Story-verdict rationale template
+
+Use this template to record the verdict — it names which delta signal
+carried the call, so a reviewer can sanity-check the routing decision without
+re-deriving it:
+
+```text
+Verdict: story
+Delta: <the existing surface this change targets>
+Corpus hit: <docs digest section / Epic # and Tech Spec excerpt that covers
+  this area, or "none — re-checked epic signals, still story-sized">
+Footprint: <rough file/AC count vs DEFAULT_TASK_SIZING>
+```
+
+### Worked example
+
+> Request: "The `/plan` standalone-Story path always drafts from a blank
+> slate even when a change request is a small delta against something we
+> already shipped — thread the existing docs digest and matching Epic
+> Tech Spec sections into the draft context."
+>
+> ```text
+> Verdict: story
+> Delta: story-plan.js's --emit-context envelope and the plan-story.md
+>   Phase 2 drafting instructions — both already exist and ship today.
+> Corpus hit: Epic #4429's own Tech Spec section (this rubric's parent
+>   Epic) already describes the docs-digest reuse pattern from
+>   orchestration/docs-digest.js.
+> Footprint: one new lib module (planning-corpus.js), one envelope field,
+>   one helper-doc instruction — comfortably inside DEFAULT_TASK_SIZING's
+>   softFiles/softAcceptanceCount band.
+> ```
+
 ## Handoff & no-re-triage rule
 
 A workflow entered via a scope-triage **handoff** MUST NOT re-triage. A handoff

package/.agents/skills/skills.index.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-07-08T12:24:41.101Z",
+  "generatedAt": "2026-07-11T11:32:48.235Z",
   "generator": "generate-skills-index.js@1",
   "skills": [
     {
@@ -138,7 +138,7 @@
       "category": "core",
       "path": ".agents/skills/core/epic-plan-decompose-author/SKILL.md",
       "description": "Author the Story ticket JSON for an Epic from the decomposer authoring context emitted by `epic-plan-decompose.js --emit-context`. Use during Phase 8 of `/plan` when the host LLM needs to write the ticket array before `epic-plan-decompose.js` validates and persists it.",
-      "policyCapsuleBullets": 14,
+      "policyCapsuleBullets": 15,
       "allowedTools": ["Read", "Write", "Bash"],
       "vendor": null
     },
@@ -158,7 +158,7 @@
       "category": "core",
       "path": ".agents/skills/core/epic-plan-spec-author/SKILL.md",
       "description": "Author the Tech Spec, Acceptance Table markdown, and risk-verdict JSON for an Epic from the planner authoring context emitted by `epic-plan-spec.js --emit-context`. Use during Phase 7 of `/plan` when the host LLM needs to write the three artifacts before `epic-plan-spec.js` folds them into the Epic body's managed sections.",
-      "policyCapsuleBullets": 13,
+      "policyCapsuleBullets": 14,
       "allowedTools": ["Read", "Write", "Bash"],
       "vendor": null
     },

package/.agents/workflows/audit-documentation.md

@@ -135,6 +135,7 @@ node .agents/scripts/check-lifecycle-doc-drift.js
 node .agents/scripts/generate-config-docs.js --check
 node .agents/scripts/generate-lifecycle-docs.js --check
 node .agents/scripts/generate-workflows-doc.js --check
+node .agents/scripts/resolve-doc-tiers.js --json
 ```
 
 Fold the results in as findings:
@@ -148,6 +149,13 @@ Fold the results in as findings:
   remediation is "rerun `npm run docs:gen` / `npm run sync:commands` and
   commit the regenerated output".
 
+The **read-tier map** — `resolve-doc-tiers.js --json` — is not itself a
+finding. It emits `{ tiers: { alwaysLoaded, mandatoryRead, digestVisible,
+onDemand } }`, each a `[{ path, bytes }]` list classifying every doc by how
+often it is loaded into agent context. Hold that map for the Context Economy
+severity-weighting rule (Step 2.5) — it decides how much a Context-Economy
+finding's location amplifies its cost.
+
 This lens orchestrates the existing checkers only; it does not add new
 deterministic checker scripts.
 
@@ -182,6 +190,56 @@ works (wrong command, deleted script, contract mismatch); **Medium** =
 materially outdated description or missing coverage of a major surface;
 **Low** = cosmetic drift, stale examples, tone/format inconsistencies.
 
+## Step 2.5: Context Economy
+
+Steps 1–2 verify the docs are **accurate**. This step verifies they are
+**economical** — that a doc still earns the context every reader (human or
+agent) pays to load it. A doc can be entirely accurate and still cost far
+more than it returns: it accretes finished-work history, states the same fact
+two incompatible ways, or claims an authority the code has outgrown. Flag
+these under the three Context Economy categories below. Each carries a
+recognition heuristic — a shape you can spot from the prose itself.
+
+- **History Bloat:** the doc carries verbatim finished-work history that
+  crowds out its live guidance — fully-checked (all-`[x]`) checklists,
+  step-by-step phase / rollout logs, and past-tense "shipped" / "completed"
+  narratives no reader acts on anymore. Recognition: a section whose every
+  checkbox is ticked, or a changelog / decision run whose historical rows
+  dwarf the live ones. **Remediation:** apply the documentation-and-adrs
+  [Pruning & Archiving](../skills/core/documentation-and-adrs/SKILL.md#pruning--archiving)
+  convention — lift any still-live gotcha into the live doc **first**, then
+  **archive, don't delete**: relocate the verbatim history to a dated
+  `docs/archive/<name>-<YYYY-MM>.md`, collapse each completed checklist to a
+  one-line outcome, and leave a one-line pointer behind. Never prune ADRs by
+  archiving — supersede them in place.
+- **Contradiction:** the doc states the same fact two incompatible ways, so a
+  reader cannot tell which is current. Recognition: a footnote- or
+  parenthetical-corrected table cell (a value carrying an inline `(now X)` /
+  `~~old~~` correction), or two prose statements that assert different values
+  for the same command, path, count, or contract. **Remediation:** collapse
+  to the single verified-current statement and delete the stale twin.
+- **Authority Drift:** the doc is crowned the source of truth for a surface
+  the verified code has since outgrown — the prose still presents itself as
+  canonical, but the implementation is now the real authority. Recognition: a
+  doc that declares itself SSOT / "canonical" / "single source of truth" for
+  a contract whose current shape you had to read the code to confirm, because
+  the doc no longer matches it. **Remediation:** either re-sync the doc to the
+  code and keep the SSOT claim, or demote the claim and point at the code as
+  the authority.
+
+### Read-tier severity weighting
+
+A Context-Economy finding's cost scales with how often the doc is actually
+read. Step 1 ran `resolve-doc-tiers.js --json`, which classifies every
+target-set doc into a read tier (`alwaysLoaded`, `mandatoryRead`,
+`digestVisible`, `onDemand`). **A finding whose doc falls in the
+`alwaysLoaded` or `mandatoryRead` tier escalates one severity band**
+(Low→Medium, Medium→High): bloat, contradiction, or drift in a doc every task
+loads costs far more than the same defect in an on-demand reference. Apply the
+escalation **after** assigning the base severity from the Step 2 guidance, and
+name the doc's tier in the finding's Current State so the escalation is
+auditable.
+
 ## Step 3: Output Requirements
 
 Generate and save a highly structured Markdown audit report to
@@ -208,8 +266,8 @@ match the code), the deterministic-gate verdicts, and primary drift themes.]
 
 ### [Short Title of the Issue]
 
-- **Category:** [Broken Instruction | Stale Description | Missing Coverage | Generator Drift | Link Integrity]
-- **Impact:** [High | Medium | Low]
+- **Category:** [Broken Instruction | Stale Description | Missing Coverage | Generator Drift | Link Integrity | History Bloat | Contradiction | Authority Drift]
+- **Impact:** [High | Medium | Low] — for a Context Economy finding, this is the base severity **after** any read-tier escalation (Step 2.5); state the doc's tier in Current State.
 - **Current State:** [The doc, the exact claim, and what the code actually
   does — cite file paths and lines on both sides]
 - **Recommendation & Rationale:** [The specific doc edit (or generator
@@ -218,6 +276,28 @@ match the code), the deterministic-gate verdicts, and primary drift themes.]
   `[A copy-pasteable, highly specific prompt to execute this doc fix independently]`
 ```
 
+## Periodic full-scope sweep
+
+Context Economy findings accrete slowly — a doc that is lean today grows a
+bloated tail over many Epics, and no single change-set-scoped `/deliver`
+Phase 4 run sees the whole picture. Run this lens **full-scope** on a
+recurring cadence so the drift is caught before it compounds:
+
+- **Cron loop** — [`loops:nightly-audit`](loops/nightly-audit.md)
+  runs the audit sweep unattended each night; the host (`/schedule` or a
+  cron-driven `/loop`) owns the cadence. Point it at this lens full-scope
+  (no `--paths`, no change-set filter — the `{{changedFiles}}` block renders
+  the literal token, so the whole target-set union is audited).
+- **Scheduled invocation** — `/schedule` running `/audit-documentation`
+  full-scope on a daily/weekly cron is the equivalent one-shot form when a
+  standing loop is not wired up.
+
+Route the resulting `audit-documentation-results.md` through
+[`/audit-to-stories`](audit-to-stories.md), which groups the findings,
+deduplicates them against existing Issues by fingerprint, and opens
+remediation Stories (or chains into `/plan --idea`) so the Context-Economy
+findings land as actionable, tracked work rather than a report nobody reads.
+
 ## Constraint
 
 This workflow is **read-only** with respect to the repository: run the