@rasensio/aidlc-content 1.50.0 → 1.52.0

package/capabilities/claude-code.yaml

@@ -25,3 +25,10 @@ capabilities:
       the problem space, identify constraints, and outline the approach before
       committing to a structure. Exit plan mode only when you begin writing the
       artifact.
+  subagents:
+    phases: [implementation]
+    activation: >-
+      Sub-agents are available on this platform: the Agent tool starts an agent
+      with a fresh context of its own. When a tasks.md is being implemented, one
+      agent per task may be offered, as .aidlc/resources/rules/task-agents.md
+      describes.

package/dist/explain.d.ts

@@ -0,0 +1,30 @@
+import type { DocTopic } from './types.js';
+/**
+ * Where the explanation pages live. Resolved from this module's own location, so
+ * in an installed project it points inside the installed package — the pages
+ * are read where npm put them and never copied out
+ * (docs-unreachable-from-installed-projects/AC-3).
+ */
+export declare const DOCS_DIR: string;
+/**
+ * Every topic page the manifest declares, in manifest order.
+ *
+ * Throws when the manifest is missing or has no `entries` list rather than
+ * returning nothing: an absent manifest and an empty one must not look alike,
+ * or a packaging mistake reads as "no topics" instead of failing.
+ */
+export declare function loadDocTopics(): DocTopic[];
+/**
+ * Resolve what a reader typed to a topic: its id, or a top-level command a page
+ * claims. Ids are matched first, so a future command named like a topic cannot
+ * shadow the page.
+ *
+ * Anything containing a path separator or `..` is unknown before any lookup.
+ * The query is only ever compared with manifest values and never joined into a
+ * path, so this is belt and braces — but it keeps "is it a path?" from being a
+ * question anyone has to re-derive (docs-unreachable-from-installed-projects/AC-9).
+ */
+export declare function findDocTopic(query: string): DocTopic | undefined;
+/** The page's Markdown, exactly as written. */
+export declare function readDocPage(topic: DocTopic): string;
+//# sourceMappingURL=explain.d.ts.map

package/dist/explain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"explain.d.ts","sourceRoot":"","sources":["../src/explain.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAI3C;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,QAAgC,CAAC;AAWtD;;;;;;GAMG;AACH,wBAAgB,aAAa,IAAI,QAAQ,EAAE,CAgB1C;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CAOhE;AAED,+CAA+C;AAC/C,wBAAgB,WAAW,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM,CAEnD"}

package/dist/explain.js

@@ -0,0 +1,56 @@
+import { fileURLToPath } from 'node:url';
+import { resolve, dirname, join } from 'node:path';
+import { readFileSync } from 'node:fs';
+import { parse as parseYaml } from 'yaml';
+const CONTENT_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+/**
+ * Where the explanation pages live. Resolved from this module's own location, so
+ * in an installed project it points inside the installed package — the pages
+ * are read where npm put them and never copied out
+ * (docs-unreachable-from-installed-projects/AC-3).
+ */
+export const DOCS_DIR = resolve(CONTENT_ROOT, 'docs');
+/**
+ * Every topic page the manifest declares, in manifest order.
+ *
+ * Throws when the manifest is missing or has no `entries` list rather than
+ * returning nothing: an absent manifest and an empty one must not look alike,
+ * or a packaging mistake reads as "no topics" instead of failing.
+ */
+export function loadDocTopics() {
+    const parsed = parseYaml(readFileSync(join(DOCS_DIR, 'index.yaml'), 'utf8'));
+    if (!parsed || !Array.isArray(parsed.entries)) {
+        throw new Error(`${join(DOCS_DIR, 'index.yaml')} did not parse into a manifest with an entries list`);
+    }
+    return parsed.entries
+        .filter((e) => e.kind === 'topic')
+        .map((e) => ({
+        id: String(e.id),
+        title: String(e.title),
+        file: String(e.file),
+        source: String(e.source),
+        commands: Array.isArray(e.commands) ? e.commands.map(String) : [],
+    }));
+}
+/**
+ * Resolve what a reader typed to a topic: its id, or a top-level command a page
+ * claims. Ids are matched first, so a future command named like a topic cannot
+ * shadow the page.
+ *
+ * Anything containing a path separator or `..` is unknown before any lookup.
+ * The query is only ever compared with manifest values and never joined into a
+ * path, so this is belt and braces — but it keeps "is it a path?" from being a
+ * question anyone has to re-derive (docs-unreachable-from-installed-projects/AC-9).
+ */
+export function findDocTopic(query) {
+    const wanted = query.trim().toLowerCase();
+    if (wanted.length === 0 || /[/\\]|\.\./.test(wanted))
+        return undefined;
+    const topics = loadDocTopics();
+    return (topics.find((t) => t.id === wanted) ?? topics.find((t) => t.commands.includes(wanted)));
+}
+/** The page's Markdown, exactly as written. */
+export function readDocPage(topic) {
+    return readFileSync(join(DOCS_DIR, topic.file), 'utf8');
+}
+//# sourceMappingURL=explain.js.map

package/dist/explain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"explain.js","sourceRoot":"","sources":["../src/explain.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,KAAK,IAAI,SAAS,EAAE,MAAM,MAAM,CAAC;AAG1C,MAAM,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;AAE5E;;;;;GAKG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,OAAO,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC;AAWtD;;;;;;GAMG;AACH,MAAM,UAAU,aAAa;IAC3B,MAAM,MAAM,GAAG,SAAS,CAAC,YAAY,CAAC,IAAI,CAAC,QAAQ,EAAE,YAAY,CAAC,EAAE,MAAM,CAAC,CAEnE,CAAC;IACT,IAAI,CAAC,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC;QAC9C,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,CAAC,QAAQ,EAAE,YAAY,CAAC,qDAAqD,CAAC,CAAC;IACxG,CAAC;IACD,OAAO,MAAM,CAAC,OAAO;SAClB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,OAAO,CAAC;SACjC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACX,EAAE,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;QAChB,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC;QACtB,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;QACpB,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC;QACxB,QAAQ,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE;KAClE,CAAC,CAAC,CAAC;AACR,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,YAAY,CAAC,KAAa;IACxC,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC1C,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,IAAI,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC;QAAE,OAAO,SAAS,CAAC;IACvE,MAAM,MAAM,GAAG,aAAa,EAAE,CAAC;IAC/B,OAAO,CACL,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CACvF,CAAC;AACJ,CAAC;AAED,+CAA+C;AAC/C,MAAM,UAAU,WAAW,CAAC,KAAe;IACzC,OAAO,YAAY,CAAC,IAAI,CAAC,QAAQ,EAAE,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,CAAC;AAC1D,CAAC"}

package/dist/index.d.ts

@@ -8,5 +8,6 @@ export { loadRules } from './rules.js';
 export { loadBoardWorkflow, BOARD_WORKFLOW_PATH } from './recipes.js';
 export { loadTutorials, getTutorial, getSeries, parseTutorialSource } from './tutorials.js';
 export { loadHowTos, getHowTo, parseHowToSource, HOWTO_SECTIONS } from './howto.js';
-export type { Skill, WorkflowTemplate, GuidanceLayer, GlossaryTerm, CapabilityMap, QuestionRendering, PhaseDefinition, Rule, CodeSample, ContentReference, TutorialStep, Tutorial, WidgetKind, WidgetReference, HowTo } from './types.js';
+export { DOCS_DIR, loadDocTopics, findDocTopic, readDocPage } from './explain.js';
+export type { Skill, WorkflowTemplate, GuidanceLayer, GlossaryTerm, CapabilityMap, QuestionRendering, PhaseDefinition, Rule, CodeSample, ContentReference, TutorialStep, Tutorial, WidgetKind, WidgetReference, HowTo, DocTopic } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC5D,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACvE,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACtE,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,SAAS,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAC5F,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACpF,YAAY,EAAE,KAAK,EAAE,gBAAgB,EAAE,aAAa,EAAE,YAAY,EAAE,aAAa,EAAE,iBAAiB,EAAE,eAAe,EAAE,IAAI,EAAE,UAAU,EAAE,gBAAgB,EAAE,YAAY,EAAE,QAAQ,EAAE,UAAU,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC5D,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACvE,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACtE,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,SAAS,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAC5F,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACpF,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAClF,YAAY,EAAE,KAAK,EAAE,gBAAgB,EAAE,aAAa,EAAE,YAAY,EAAE,aAAa,EAAE,iBAAiB,EAAE,eAAe,EAAE,IAAI,EAAE,UAAU,EAAE,gBAAgB,EAAE,YAAY,EAAE,QAAQ,EAAE,UAAU,EAAE,eAAe,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -8,4 +8,5 @@ export { loadRules } from './rules.js';
 export { loadBoardWorkflow, BOARD_WORKFLOW_PATH } from './recipes.js';
 export { loadTutorials, getTutorial, getSeries, parseTutorialSource } from './tutorials.js';
 export { loadHowTos, getHowTo, parseHowToSource, HOWTO_SECTIONS } from './howto.js';
+export { DOCS_DIR, loadDocTopics, findDocTopic, readDocPage } from './explain.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC5D,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACvE,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACtE,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,SAAS,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAC5F,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC5D,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACvE,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACtE,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,SAAS,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAC5F,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACpF,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC"}

package/dist/types.d.ts

@@ -151,4 +151,21 @@ export interface HowTo {
         checkItWorked: string;
     };
 }
+/**
+ * One explanation page: why a subsystem exists, what breaks without it, how to
+ * use it. Declared in `docs/index.yaml`, shipped in this package and read from
+ * it — never installed into a project, for the reason the glossary is not
+ * (docs-unreachable-from-installed-projects DD-1).
+ */
+export interface DocTopic {
+    /** Short slug, unique across the manifest; what `aidlc explain <topic>` takes. */
+    id: string;
+    title: string;
+    /** Filename under `docs/`. A manifest value, never user input. */
+    file: string;
+    /** Repo path the page is about. Informational once installed: the path is in this repo, not yours. */
+    source: string;
+    /** Top-level CLI commands the page covers; each also resolves to this page. */
+    commands: string[];
+}
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/docs/README.md

@@ -0,0 +1,70 @@
+# How AIDLC works
+
+Nine pages explaining what this repo built — why each part exists, and how to use it.
+
+These are for two readers with the same gap: a person trying to understand the system, and an
+AI agent about to change it. If you are about to modify a subsystem, read its page first. The
+reasons are the point: several of the designs here look arbitrary until you know which bug bought
+them, and an agent that only knows the shape will simplify the reason away.
+
+## The pages
+
+| Page | What it covers |
+|---|---|
+| [lifecycle.md](lifecycle.md) | Instances, templates, scope, phases, gates, transitions |
+| [state-and-concurrency.md](state-and-concurrency.md) | State files, claims, the registry, worktrees |
+| [roadmap.md](roadmap.md) | Capture, triage, promote — statuses as directories |
+| [reviews-and-guidance.md](reviews-and-guidance.md) | Adversarial review, guidance layers, context docs, the constitution |
+| [cost-tracking.md](cost-tracking.md) | What a feature cost, and how the number is attributed |
+| [metrics.md](metrics.md) | Change failure rate, lead times, true cost |
+| [knowledge-graph.md](knowledge-graph.md) | Persistent codebase memory for agents |
+| [skills-and-platforms.md](skills-and-platforms.md) | One canonical skill body, six platform packagings |
+| [hygiene-and-compliance.md](hygiene-and-compliance.md) | `aidlc doctor`, compliance packs |
+
+## What these pages are not
+
+**Not the framework reference.** The website documents the framework itself — phases, skills,
+templates, the CLI, the glossary. These pages document what was *built with* it.
+
+**Not the release story.** `packages/website/content/blog/` holds a post per release, written as
+narrative at the moment the work landed. Good for "what happened in v1.8.0", no use for "how does
+cost tracking work now". These pages are the second thing.
+
+**Not the knowledge graph.** That split is the one worth understanding before you add a page, and
+it is stated in full at the top of [index.yaml](index.yaml). In short: the graph answers *where is
+it and what shape is it*, terse and loaded into every prompt. These pages answer *why does it
+exist, what breaks without it, how do I use it*, in prose, read on demand. A page that restates a
+fact the graph already carries is the drift the split exists to prevent.
+
+**Not vocabulary.** Framework terms have exactly one definition, in
+`packages/content/glossary.yaml`, consumed by both the CLI and the website. These pages link to it
+and never restate a definition — a third copy is a copy that goes wrong.
+
+## Adding or changing a page
+
+Every page is declared in [index.yaml](index.yaml), which is also where the two allowlists live.
+Guards in `packages/cli/test/docs-topics.test.ts` check the structure: that declared pages exist
+and undeclared ones do not, that every page carries its three required sections with content in
+them, that every top-level CLI command is claimed by some page, and that every repo path a page
+mentions still resolves. The command check reads the set from
+`packages/website/src/data/cli-reference.json`, which the docs-drift gate keeps in step with the
+shipped binary — so this sentence deliberately names no count. The one it used to name ("all 20")
+was wrong by the next release.
+
+That last check is the one you will meet. It exists because the knowledge graph rotted exactly
+this way — 17 of its entries still describe a package deleted months ago — and structural rot is
+the half a test can catch. When it fires you have two honest options: update the page, or, if you
+are deliberately naming something that was removed, add it to `historical_paths:` with a reason.
+Deleting the guard is not the third option.
+
+Each topic page needs these three headings, matched literally:
+
+```
+## Why this exists
+## How to use it
+## Where the code lives
+```
+
+`## Why this exists` is the section the whole folder is for. It carries the reason and what breaks
+without the thing. Anything that could equally have been read off the code belongs in the
+knowledge graph instead.

package/docs/cost-tracking.md

@@ -0,0 +1,188 @@
+# Cost tracking
+
+## Why this exists
+
+You cannot decide whether a feature was worth building if you do not know what it cost. With an AI
+agent doing the work, the cost is tokens, and the tokens are spent in a session that has no idea which
+feature it is working on.
+
+Cost tracking closes that gap: it reads what the agent platform recorded about a session and attributes
+it to a lifecycle instance, so `aidlc cost` can answer "what did this feature cost".
+
+The number changed decisions here. Cost tracking's *own* cost was $153.65. Its **true** cost — adding
+the two bugfixes it caused — was $219.78. Own cost understated it by a third, and hid the fact that
+building a feature to watch the lifecycle is not a one-week spend but a tax on every future instance.
+That is the whole argument for the module existing, and it is also the argument for reading `aidlc
+metrics` rather than `aidlc cost`.
+
+> **Those two figures are as-metered, and the meter over-reported.** Until 2026-09-10 the
+> claude-code provider counted usage once per transcript *line*, and Claude Code writes one line per
+> content block with the response's `usage` repeated on each — so one API call was charged up to
+> seven times. Measured over 53 transcripts: **1.848x**. Every absolute dollar figure published
+> before that date, including the two above and the warning in `CLAUDE.md` built on them, runs
+> roughly 1.85x high. The *ratio* between them survives, because the duplicate rate was stable day
+> to day, so "own cost understated true cost by a third" still holds. `aidlc cost dedupe` re-derives
+> history; it has not been applied, so figures in older retrospectives and blog posts are still the
+> as-metered ones.
+
+## The bill is context, not thinking
+
+Measured over 20,920 attributed records: **91% of spend is cache traffic** — re-reading the same
+conversation prefix, turn after turn. Output is 13%. Assistant prose and reasoning together are 2.4%
+of the bytes in context.
+
+The prefix only grows, and nothing used to reset it. Average context per unit of work by phase:
+
+```
+ideation         80k        testing         344k
+requirements    164k        deployment      395k
+design          173k        maintenance     791k
+implementation  259k        complete         76k   <- the only phase that starts fresh
+```
+
+`complete` is the proof. It does real work at 76k because it runs in its own session; deployment does
+comparable work at 395k because it inherits every phase before it. That is why **deployment is the
+most expensive phase in the lifecycle, ahead of implementation** — not because it does more, but
+because it runs last.
+
+So a phase boundary is a free context reset. `aidlc cost context` reports what this session is
+carrying against a budget (`cost.context_budget_tokens`, default 150,000), and the phase skills name
+exactly what to re-read when a phase starts fresh. The canonical statement of the rule lives in the
+`aidlc-overview` skill; every phase skill points at it rather than restating it.
+
+**It is a report and never a gate.** Deliberately: this project shipped 11 features and 7 bugfixes,
+five of the six traceable ones caused by meta-features that each added a gate every future instance
+had to pass. The budget's whole force is that somebody reads it out at the right moment — the same
+force the constitution has, and for the same reason. Do not turn it into a transition check.
+
+**What breaks without it:** every estimate is a guess, and meta-work looks cheap because its downstream
+cost lands on somebody else's instance.
+
+## How to use it
+
+```
+aidlc cost
+aidlc cost my-thing
+aidlc cost --by-template
+aidlc cost context          # resident context vs budget — reads the transcript, not the ledger
+aidlc cost dedupe           # plan the correction for pre-2026-09-10 double counting
+aidlc cost hooks install
+aidlc cost sync
+```
+
+`aidlc cost` reports the *driver* alongside the total, because `$578.45` on its own gives a reader
+nothing to act on: cache-read share of spend, average context per response, and cost per response.
+Entries captured before 2026-09-10 carry no response count, so their per-response figures read
+`unmeasured` rather than zero.
+
+Two rules keep the per-response figures honest (2026-09-14, cost-driver-integrity). First, the
+averages divide sums taken over exactly the entries that carry a response count — never the whole
+ledger over a subset count, and each ratio narrows further to the entries that can supply *its*
+numerator (a credit-unit entry has a response count and no token count, so counting it against
+context reported `avg context: 0`). The original shipped shape divided all-entry token sums by the
+handful of counted entries and printed a 21.5M-token "average context" as if it were a measurement.
+When the counted entries are only part of the ledger the derived figures carry a `~`, which marks
+them as computed over part of the ledger — not as a floor. `responses` itself *is* a floor, and
+carries `~` for that reason; a subset average can sit either side of the whole-ledger one.
+Second, the response count is a fact the *provider* owns: `claude-code.ts` groups
+by `message.id`, so each segment it emits is exactly one response and says so; both writers — `sync`
+for reconciled entries and `recorder.ts` for metered buckets — *sum what the segments declare* rather
+than counting segments themselves. A provider whose records are not response-shaped (kiro, codex)
+sets nothing, and absence stays "unknown", never a fabricated count. The recorder used to add 1 per
+segment regardless of provider, which put a tally of kiro usage records where a response count
+belongs — on the highest-precedence entries, where it outranked the honest absence beside it.
+
+The default report also prices the **unattributed pool** (`.aidlc/cost/unattributed.ndjson`) on its
+last line, with the same read-time precedence weighting instances get. On this repo that pool was
+~44% of total spend while the only surface for it printed a bare entry count. `aidlc cost
+--unattributed` breaks the pool down by fidelity and model; `aidlc cost sync` drains what claim
+windows cover.
+
+`aidlc cost context` reads the transcript rather than the ledger on purpose. The question is asked at
+a phase boundary, which is exactly when no capture has run recently and the ledger is stale — and it
+has to answer on a machine where no hook was ever installed.
+
+Capture is passive. A hook fires on each agent turn, and the recorder attributes the usage. Without the
+hook installed there is no data, and — the failure that produced two bugfixes — a broken hook looked
+exactly like an idle one. Hence `capture.log` and `lastCaptureError`, so "captured nothing" can be told
+apart from "was never asked".
+
+**How attribution works**, because this is where the surprises are. A usage record gets an instance and
+a phase by intersecting two windows:
+
+- **Claim intervals** — when was this instance claimed, by which session. From `sessions.ndjson`.
+- **Phase windows** — derived from `transitions.log`, so a record's timestamp resolves to whichever
+  phase was current at that moment. Re-entering a phase sums rather than replaces.
+
+Two consequences follow, and both cost real money before they were understood:
+
+**Concurrent claims destroy attribution.** If two instances were claimed at once in one checkout, a
+record falls inside both windows and the recorder reports `ambiguous` rather than guessing. On
+2026-08-26 both live instances lost their cost data entirely this way. Use a worktree for concurrent
+work — see [state-and-concurrency.md](state-and-concurrency.md).
+
+**A finished instance stops collecting.** A claim nobody released stays open for the claim timeout,
+so for up to an hour after an instance closed, capture went on crediting it with whatever its session
+did next, and appending `renew` events to its `sessions.ndjson`. Every one of those writes landed in a
+tracked file of a finished instance, in the checkout releases run from, and `release.sh` refused the
+dirty tree. Now `cost/completion.ts` ends every claim interval at the instance's completion moment
+(`completionInfo`'s answer, so maintenance-terminal templates count from maintenance entry). It does
+this before capture and `cost sync` decide anything. Usage from before the close still attributes.
+Usage after it goes to the unattributed pool. The cut is on the *interval* rather than on each write,
+because capture, reconcile, backfill and recover all decide from intervals, so one cut keeps all four
+in agreement.
+
+The pool itself still changes whenever a session with no claim ends, and no recorder change can stop
+that without dropping records. So `release.sh` commits churn that is *only* cost ledger files
+(`scripts/commit-cost-ledgers.sh --preflight`) and still refuses anything else.
+
+**Null is not zero.** When there is no ledger data, the report says null. It never zero-fills, because
+a zero reads as "this was free" and a null reads as "we do not know", and those are different claims.
+Anything that aggregates costs nulls the total if any constituent is null, for the same reason.
+
+Rates come from a bundled table, refreshed from LiteLLM and cacheable, with model-id normalization so a
+provider-prefixed id matches its bundled rate. An override file exists for models the table does not
+know.
+
+## Where the code lives
+
+Everything is under `packages/cli/src/cost`:
+
+- `ledger.ts` — append-only NDJSON with a closed schema, cursor-based reads, and read-time fidelity
+  precedence (a more precise later record reduces an earlier estimate pro-rata rather than
+  double-counting the overlap).
+- `sessions.ts` — session events and claim intervals.
+- `completion.ts` — ends claim intervals at the instance's completion moment.
+- `providers` — the platform seam. Each provider parses one agent platform's session records.
+  `resolveSource` returns a `ResolveResult` of `ok` or `reason`, deliberately not `null`: a null could
+  not distinguish "no transcript on disk" from "transcript found but no matching turns", and telling
+  those apart is what a bugfix bought. Do not simplify it back.
+  `claude-code.ts` groups usage by `message.id` and **collapses** repeats rather than summing them —
+  correct only because the repeats are byte-identical, which was measured (7,935 repeats, zero
+  differing) rather than assumed. Two things there look removable and are not: a group's cursor
+  advances to its *last* line (keeping the first re-charges the tail on the next capture), and the
+  final segment's cursor is *assigned* from the last usage-bearing uuid rather than inherited from
+  array order, because array order is only right while response groups stay contiguous and the
+  transcript format is internal to Claude Code. If contiguity broke, inferring would send the cursor
+  backwards and re-charge a span of transcript.
+- `context.ts` — resident-context reading for `aidlc cost context`. Reads token counts only; never
+  copies transcript content, so nothing here can carry a prompt or a secret into a report.
+- `dedupe-history.ts` — the corrective pass over existing ledgers. It distinguishes a *proven
+  duplicate* (transcript resolved, but the deduped read emits nothing at that entry's instant, so the
+  charge is carried elsewhere) from a *transcript that is gone* (an honest unknown, left
+  byte-identical and never scaled by the measured factor). Those two justify opposite actions, which
+  is why they are separate fields and not one "unresolvable" count.
+- `recorder.ts` — attribution, the per-session lock, and `capture.log`. `phaseWindows` is the
+  phase-attribution seam, called from four places.
+- `rates.ts`, `rates-bundled.ts` — pricing and model-id normalization.
+- `report.ts`, `sync.ts` — per-instance and by-template reports; reconciliation, backfill, and
+  recovery of unattributed records.
+- `hooks` — installers that merge into the platform's own settings file rather than replacing it.
+- `packages/cli/src/commands/cost.ts` — the command surface.
+
+The one design rule to keep: any figure that becomes money needs a duplicate-cursor audit across every
+path that writes it. Two of the bugfixes here were double-counting — and then the meter fix of
+2026-09-10 was a third, which had been sitting in the *provider* the whole time while both earlier
+audits looked at the recorder and the ledger. The rule was right; the audit had never been run one
+level further out. When auditing for duplicates, start at the thing that produces records, not at the
+thing that stores them.

package/docs/hygiene-and-compliance.md

@@ -0,0 +1,135 @@
+# Repo hygiene and compliance
+
+## Why this exists
+
+Running a lifecycle in a repository leaves debris. Cost ledgers that must never be committed. Claim
+files from sessions that died. Ephemera from an instance that finished three weeks ago. Nested
+`.gitignore` files that quietly stopped covering what they were written to cover.
+
+None of it breaks anything on the day it appears, which is exactly why it accumulates. `aidlc doctor`
+checks for it and repairs what is safely repairable.
+
+**Compliance packs** answer a different question: an auditor's. A pack declares controls — what each one
+requires, where to look for evidence, and what counts as failing — and the framework checks them against
+the artifacts the lifecycle already produces. The lifecycle generates requirements, designs, reviews and
+deployment records as a matter of course, so most of the evidence exists already; the pack just knows
+where to look.
+
+The design decision that makes packs usable is that **control findings are advisory by default**. They
+are written to `<artifact>.compliance.md`, a separate file, and the phase transition gate reads only
+`*.review.md`. Keeping the two streams apart is what stops a compliance pack from becoming an
+unreviewable blocker on every phase.
+
+**What breaks without them:** a cost file gets committed with a session id in it, a stale claim blocks
+the one session entitled to proceed, and an audit becomes an archaeology project.
+
+### Why a pack registration says `pack:` and not just `always_pointer:`
+
+A guidance layer installed by a compliance pack carries two keys in `.aidlc/guidance/index.yaml`, and
+they are easy to mistake for one thing:
+
+- `always_pointer: true` is a **rendering** instruction. It tells the skill compiler to emit a pointer
+  to the layer file rather than inlining its text, whatever the layer's size. Pack layers must set it,
+  because inlining pack control text into an emitted skill is forbidden outright.
+- `pack: <id>` is **provenance**. It records which pack installed the entry.
+
+The keys always travel together on a pack layer, which makes it tempting to read the first as proof of
+the second. `aidlc doctor` did exactly that until v1.25.0, and the consequence was not cosmetic. A
+project may legitimately set `always_pointer` on a layer it wrote itself — that is how you ask for a
+long layer to be linked rather than pasted into every skill — and doctor read those entries as
+registrations belonging to an uninstalled pack. It reported them on every run, could never clear
+(no pack will ever claim a file the project authored), and dropped the registration under `--yes`. The
+file stayed on disk, but the registration is what makes a layer reach an agent, so the layer silently
+stopped being delivered.
+
+The rule now: **an entry with no `pack` key is the project's or the framework's, and doctor leaves it
+alone.** Entries whose provenance cannot be proven default to project-authored, because the two errors
+cost very different amounts. Wrongly dropping a registration stops delivering guidance an agent was
+instructed to always read, and nothing announces it. Wrongly keeping one leaves a stale pointer, which
+is visible in the index and cheap to remove. Where the evidence is missing, take the reversible error.
+
+The same reasoning governs a broken config. `readComplianceConfig` deliberately degrades an
+unparseable `compliance:` section to "no packs installed" so that a hand-mangled config cannot break
+unrelated commands — right for every consumer asking what governs the project, and dangerous for one
+that acts on a record's *absence*. So the two provenance-dependent migrations consult
+`complianceSectionState()` first and decline to run at all when the section is present but
+unreadable, rather than concluding a live pack was uninstalled.
+
+## How to use it
+
+```
+aidlc doctor
+aidlc doctor --fix
+aidlc compliance list
+aidlc compliance check
+aidlc compliance report
+```
+
+`doctor` reports; `--fix` repairs. Run it after anything structural — a new top-level directory, a
+worktree removed, an instance abandoned.
+
+Some checks report and repair nothing, on purpose. A `report`-tier migration states a condition whose
+only remedy is a decision, and it never touches `doctor`'s exit code, so `--fix` and `--yes` cannot
+make it write. Four conditions qualify today: an out-of-date compliance pack, a configured roadmap
+projection with no `gh` on `PATH`, `knowledge-stale-sources`, and `roadmap-item-summary`.
+
+**`roadmap-item-summary`** names every `inbox/` item with no complete six-line executive summary, and
+the labels each one is missing. Two paths write into the inbox — the capture flow, which has always
+required the summary, and an instance writing an item mid-phase, which until recently required
+nothing — and 13 of the 18 items in one project's inbox had no summary at all, so triaging it meant
+re-deriving thirteen cases from scratch. It is report tier because the only remedy is writing six
+lines of judgement about somebody else's idea: an invented case reads exactly like a real one, and a
+no-op repair at confirm tier would make `doctor` exit 1 forever over one thin item. It looks at
+`inbox/` only — the other statuses have already been decided about — and skips items whose
+frontmatter will not parse, because `roadmap-item-titles` already reports those by name.
+
+**`knowledge-stale-sources`** resolves every knowledge-graph entity's `source` against the disk, and
+every relationship endpoint against the entity set, and names what does not resolve. It is the check
+that was missing when 15 graph entities described `packages/web` for 17 days after the website cutover
+deleted it. It is report tier because 12 of those 15 wanted deleting and 3 wanted their path corrected
+to a different manifest, and the data cannot tell you which — so it names the entries and leaves the
+edit to you. See [The knowledge graph](knowledge-graph.md).
+
+Two properties it holds deliberately, and which are easy to break by extending it. It **spawns
+nothing** — the graph's own `KNOWLEDGE_DIR` constant had to move out of `engine.ts` because that
+module imports `SqliteIndex`, which would have put `node:sqlite`'s experimental warning on the
+default path of every `doctor` run. And a `source` that is absolute, or that escapes the project root
+once resolved, is reported as a defect in the entry and **never passed to a filesystem call**: a
+tracked YAML file is not a trusted one, and it must not be able to make `doctor` probe paths outside
+the repo.
+
+`compliance remove` and `upgrade` follow the same rule for the pack record in `.aidlc/config.yaml`.
+They delete only files whose recorded path stays inside `.aidlc/guidance/`, and only when that
+entry's own recorded hash matches what is on disk. The record is tracked, so a cloned repo writes
+it. The hash used to be looked up by file *basename*, so a second entry named `victim.md` could
+vouch for `../../victim.md` and get a file outside the project deleted (security-review-findings).
+
+`compliance list` shows packs available and installed. `soc2` ships with the framework. `check` returns
+the controls applying to the current phase, each with its requirement, where to look, and its fail
+condition.
+
+Two rules for anyone acting on a `check`:
+
+**Apply the fail conditions as written.** They belong to the pack. Reinterpreting one turns a stated
+control into your opinion, which is the one thing an audit trail cannot absorb.
+
+**Never record a control as cleared unless you actually examined it.** Every applicable control must
+appear either as a finding carrying its id, or in `## Controls Checked` as `<id> — no issues`. An
+unchecked control reported as covered is worse than no check at all — it converts an unknown into a
+false assurance, and the next reader has no way to tell.
+
+There is a related trap in `doctor`'s own history worth knowing if you extend it: a migration that
+reports pending work and a migration that has already drained its directory can look identical, and
+removal that only runs when the check reports pending work never runs at all. Run a new migration twice
+and read what it says the second time. Steady-state bugs are invisible on the first run by definition.
+
+## Where the code lives
+
+- `packages/cli/src/doctor` — the checks and repairs. `migrations` holds the one-off repairs, including
+  the nested-`.gitignore` coverage fix.
+- `packages/cli/src/compliance` — pack loading, control evaluation, and the evidence report.
+- `packages/content/packs` — the shipped packs; `soc2` is the only one today.
+- `packages/content/skills/80-review.md` — where the compliance findings stream is specified, including
+  the two-places rule for every applicable control.
+- `packages/cli/src/operational/redact.ts` — redaction used when repo state is turned into something
+  shareable, so a report does not carry what a ledger recorded.