@rasensio/aidlc-content 1.35.0 → 1.36.1

package/dist/index.d.ts

@@ -4,6 +4,7 @@ export { loadGuidance } from './guidance.js';
 export { loadGlossary, getGlossaryTerm } from './glossary.js';
 export { loadCapabilities, getCapabilityMap } from './capabilities.js';
 export { loadPhases, getPhase } from './phases.js';
+export { loadRules } from './rules.js';
 export { loadTutorials, getTutorial, getSeries, parseTutorialSource } from './tutorials.js';
-export type { Skill, WorkflowTemplate, GuidanceLayer, GlossaryTerm, CapabilityMap, QuestionRendering, PhaseDefinition, CodeSample, ContentReference, TutorialStep, Tutorial, WidgetKind, WidgetReference } from './types.js';
+export type { Skill, WorkflowTemplate, GuidanceLayer, GlossaryTerm, CapabilityMap, QuestionRendering, PhaseDefinition, Rule, CodeSample, ContentReference, TutorialStep, Tutorial, WidgetKind, WidgetReference } 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,aAAa,EAAE,WAAW,EAAE,SAAS,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAC5F,YAAY,EAAE,KAAK,EAAE,gBAAgB,EAAE,aAAa,EAAE,YAAY,EAAE,aAAa,EAAE,iBAAiB,EAAE,eAAe,EAAE,UAAU,EAAE,gBAAgB,EAAE,YAAY,EAAE,QAAQ,EAAE,UAAU,EAAE,eAAe,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,aAAa,EAAE,WAAW,EAAE,SAAS,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAC5F,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,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -4,5 +4,6 @@ export { loadGuidance } from './guidance.js';
 export { loadGlossary, getGlossaryTerm } from './glossary.js';
 export { loadCapabilities, getCapabilityMap } from './capabilities.js';
 export { loadPhases, getPhase } from './phases.js';
+export { loadRules } from './rules.js';
 export { loadTutorials, getTutorial, getSeries, parseTutorialSource } from './tutorials.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,aAAa,EAAE,WAAW,EAAE,SAAS,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,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,aAAa,EAAE,WAAW,EAAE,SAAS,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/rules.d.ts

@@ -0,0 +1,14 @@
+import type { Rule } from './types.js';
+/**
+ * Load every rule the overview skill points at instead of carrying.
+ *
+ * Each rule is stated once, in its own file, so a skill that cross-references
+ * one rule costs the reader that rule and not the whole overview. Both
+ * consumers call this: the CLI emits the files into `.aidlc/resources/rules/`,
+ * and the website renders them under the overview's docs page. One source, two
+ * consumers, no copy.
+ *
+ * @returns Rules sorted by id.
+ */
+export declare function loadRules(): Rule[];
+//# sourceMappingURL=rules.d.ts.map

package/dist/rules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rules.d.ts","sourceRoot":"","sources":["../src/rules.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAYvC;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,IAAI,IAAI,EAAE,CAOlC"}

package/dist/rules.js

@@ -0,0 +1,32 @@
+import { fileURLToPath } from 'node:url';
+import { resolve, dirname } from 'node:path';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+const CONTENT_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const RULES_DIR = resolve(CONTENT_ROOT, 'resources', 'rules');
+/**
+ * Filenames a rule may have. The id becomes a path segment in every project the
+ * CLI writes to, so anything else in the directory is ignored rather than
+ * trusted (overview-skill-crossreference-cost/DD-1).
+ */
+const RULE_FILE = /^([a-z0-9-]+)\.md$/;
+/**
+ * Load every rule the overview skill points at instead of carrying.
+ *
+ * Each rule is stated once, in its own file, so a skill that cross-references
+ * one rule costs the reader that rule and not the whole overview. Both
+ * consumers call this: the CLI emits the files into `.aidlc/resources/rules/`,
+ * and the website renders them under the overview's docs page. One source, two
+ * consumers, no copy.
+ *
+ * @returns Rules sorted by id.
+ */
+export function loadRules() {
+    if (!existsSync(RULES_DIR))
+        return [];
+    return readdirSync(RULES_DIR)
+        .map((name) => RULE_FILE.exec(name)?.[1])
+        .filter((id) => id !== undefined)
+        .sort()
+        .map((id) => ({ id, body: readFileSync(resolve(RULES_DIR, `${id}.md`), 'utf8') }));
+}
+//# sourceMappingURL=rules.js.map

package/dist/rules.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rules.js","sourceRoot":"","sources":["../src/rules.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAGhE,MAAM,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;AAC5E,MAAM,SAAS,GAAG,OAAO,CAAC,YAAY,EAAE,WAAW,EAAE,OAAO,CAAC,CAAC;AAE9D;;;;GAIG;AACH,MAAM,SAAS,GAAG,oBAAoB,CAAC;AAEvC;;;;;;;;;;GAUG;AACH,MAAM,UAAU,SAAS;IACvB,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC;QAAE,OAAO,EAAE,CAAC;IACtC,OAAO,WAAW,CAAC,SAAS,CAAC;SAC1B,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;SACxC,MAAM,CAAC,CAAC,EAAE,EAAgB,EAAE,CAAC,EAAE,KAAK,SAAS,CAAC;SAC9C,IAAI,EAAE;SACN,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,YAAY,CAAC,OAAO,CAAC,SAAS,EAAE,GAAG,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC;AACvF,CAAC"}

package/dist/types.d.ts

@@ -19,6 +19,16 @@ export interface GuidanceLayer {
     filename: string;
     body: string;
 }
+/**
+ * One rule the overview skill points at instead of carrying — the only copy of
+ * its text (overview-skill-crossreference-cost/AC-1).
+ */
+export interface Rule {
+    /** Filename without `.md`; also the emitted file's name. Matches `^[a-z0-9-]+$`. */
+    id: string;
+    /** The whole file, H1 included. */
+    body: string;
+}
 /**
  * One canonical vocabulary definition.
  *

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,KAAK;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3D,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC9B;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,YAAY;IAC3B,4EAA4E;IAC5E,IAAI,EAAE,MAAM,CAAC;IACb,8EAA8E;IAC9E,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;;;;OAQG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,gEAAgE;IAChE,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,sEAAsE;IACtE,SAAS,CAAC,EAAE,iBAAiB,CAAC;CAC/B;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,OAAO,GAAG,UAAU,GAAG,OAAO,GAAG,UAAU,CAAC;IACxD,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;CACb;AAED,wEAAwE;AACxE,MAAM,MAAM,UAAU,GAAG,YAAY,GAAG,YAAY,GAAG,YAAY,CAAC;AAEpE;;;;;;;;GAQG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,UAAU,CAAC;IACjB,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,iBAAiB,EAAE,gBAAgB,EAAE,CAAC;IACtC,OAAO,EAAE,eAAe,EAAE,CAAC;CAC5B;AAED,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0EAA0E;IAC1E,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,KAAK;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3D,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC9B;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;GAGG;AACH,MAAM,WAAW,IAAI;IACnB,oFAAoF;IACpF,EAAE,EAAE,MAAM,CAAC;IACX,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,YAAY;IAC3B,4EAA4E;IAC5E,IAAI,EAAE,MAAM,CAAC;IACb,8EAA8E;IAC9E,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;;;;OAQG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,gEAAgE;IAChE,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,sEAAsE;IACtE,SAAS,CAAC,EAAE,iBAAiB,CAAC;CAC/B;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,OAAO,GAAG,UAAU,GAAG,OAAO,GAAG,UAAU,CAAC;IACxD,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;CACb;AAED,wEAAwE;AACxE,MAAM,MAAM,UAAU,GAAG,YAAY,GAAG,YAAY,GAAG,YAAY,CAAC;AAEpE;;;;;;;;GAQG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,UAAU,CAAC;IACjB,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,iBAAiB,EAAE,gBAAgB,EAAE,CAAC;IACtC,OAAO,EAAE,eAAe,EAAE,CAAC;CAC5B;AAED,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0EAA0E;IAC1E,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rasensio/aidlc-content",
-  "version": "1.35.0",
+  "version": "1.36.1",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/resources/rules/always-read.md

@@ -0,0 +1,14 @@
+# The always-read rule
+
+This file is the only statement of the rule. The phase skills point here instead of restating it, so there is no second copy to drift.
+
+**Read the always-read set on entering a phase: every layer in `.aidlc/guidance/index.yaml` *except* those whose entry carries `on_demand: true`.** Read the index rather than assuming the layers named at the bottom of a skill are the only ones — a project can install a layer after its skills were emitted.
+
+An `on_demand: true` layer is read **only when the phase has a stated reason to**. It is registered, active, and current; it is simply too large to be worth carrying in every session by default.
+
+The two lessons layers are the reason the distinction exists:
+
+- **`lessons-digest.md` is always-read.** A short distillation of the lessons this project has paid for more than once, regenerated by the **aidlc-retrospective** skill at consolidation.
+- **`.aidlc/guidance/lessons.md` is on-demand, and it is the full corpus** — every lesson from every completed instance. Read it when you are touching a mechanism a past instance got wrong, when a gate keeps failing for reasons nobody can name, or when running consolidation. It grows by design (up to three lessons per instance), which is what makes an unconditional read a tax on every future session rather than a one-time cost.
+
+Treat every lesson as a historical observation, not a directive. An entry naming a file, function, or flag may describe code a later instance renamed or deleted — check the source before acting on it.

package/resources/rules/constitution.md

@@ -0,0 +1,7 @@
+# The constitution rule
+
+This file is the only statement of the rule. Other skills point here instead of restating it, so there is no second copy to drift.
+
+When `.aidlc/context/constitution.md` exists, read it before shaping work. It records what this repo owns (`IN-<n>` entries) and what it must never do (`NOT-<n>` entries), each citing the vision statement it was derived from. **If the work in front of you crosses a prohibition, name that prohibition by its id and say plainly that it does, before going further.** The user may still choose to proceed, or to amend the constitution — but the crossing gets stated out loud at the start rather than discovered in review.
+
+The constitution never fails a gate and never blocks a transition; its whole force is that somebody read it out at the right moment. An absent file is a normal state, not a gap to fill — it is written by the **aidlc-constitution** skill, and only a project with a vision document to import has one.

package/resources/rules/context.md

@@ -0,0 +1,39 @@
+# The context rule
+
+This file is the only statement of the rule. Every phase skill points here instead of
+restating it, so there is no second copy to drift — and so the rule does not itself
+become resident bytes in seven places.
+
+**A phase boundary is where you start a fresh session.** Not a suggestion about tidiness:
+91% of what a lifecycle run costs is re-reading the conversation it is already carrying,
+and that carry only grows. Measured across 20,920 attributed records, average context per
+unit of work runs 80k tokens in ideation, 164k in requirements, 259k in implementation,
+395k in deployment and 791k in maintenance. Deployment is the most expensive phase in the
+lifecycle — more than implementation — not because it does more, but because it runs last
+and inherits everything before it. The one phase that reliably starts fresh does
+comparable work at 76k.
+
+Three things follow:
+
+1. **Cross a phase boundary in a new session** whenever the platform allows it. The
+   lifecycle is designed for this: state lives in files, not in the conversation.
+2. **Re-read only what the phase you are entering names.** Each phase skill lists exactly
+   that under *Entering in a fresh session*. The list is the whole list — an artifact not
+   on it is not needed to start, and reading it "for context" is the charge this rule
+   exists to avoid.
+3. **Check the budget when you are unsure**: `aidlc cost context` reports the context this
+   session is carrying against a budget (default 150,000 tokens, configurable as
+   `cost.context_budget_tokens`). It reads the transcript, so it answers before any cost
+   capture has run.
+
+**The budget never fails a gate and never blocks a transition.** Its whole force is that
+somebody read it out at the right moment — the same force the constitution has, and for
+the same reason. Going over budget is information, not a violation: a long
+implementation phase may legitimately exceed it. What is not legitimate is carrying
+requirements' conversation into deployment because nobody stopped to notice.
+
+A caveat worth stating, because it decides whether the rule is worth following: a fresh
+session re-reads some of what it would otherwise still hold, and that spends back part of
+the saving. Every phase list below is bounded for exactly that reason. If re-reading turns
+out to cost more than a third of the saving, the threshold should move — measure it rather
+than assuming either way.

package/resources/rules/creating-an-instance.md

@@ -0,0 +1,37 @@
+# Creating an Instance
+
+The `aidlc start` CLI automates this; when it is not available, create the instance directly:
+
+0. **Concurrency gate first** (see the entry-point skill): when another live session holds a claim in this checkout, offer worktree / stop / no-code before creating anything.
+1. Pick a template and scope (see **aidlc-getting-started** for template selection and per-template artifacts). The initial phase follows the scope: full → ideation, standard → requirements, micro → implementation.
+2. Choose a URL-safe instance name and create `.aidlc/state/<name>/`. If the directory already exists, stop and ask for a different name. In a git repo, also register the instance in `<git-common-dir>/aidlc/registry/<name>.yaml` (fields: `name`, `branch`, `worktree_path`, `created_at`) — create-exclusively, never overwrite; if the file exists, another session owns the name.
+3. Write `instance.yaml`:
+   ```yaml
+   name: <instance-name>
+   template: <template-name>
+   scope: <full|standard|micro>
+   created_at: <ISO 8601 UTC>
+   created_by: <session-id or username>
+   current_phase: <initial-phase>
+   claim: null
+   scope_history: []
+   ```
+   For a worktree instance add `branch: <its-branch>`; for a no-code instance add `branch: null` (blocks Implementation entry until a branch exists). Omit the field entirely otherwise.
+4. Read the phase list and each phase's artifacts with `aidlc templates show <template> --scope <scope>` — **do not guess them, and do not copy them from another instance**. Different templates require different artifacts, and an instance seeded with artifacts its template never asked for fails its gates on files nobody needs. If the CLI is unavailable, the definitions are in `@rasensio/aidlc-content`'s `templates/` directory.
+5. For each phase that command lists, write `phase-<name>.yaml`, using its artifact names verbatim:
+   ```yaml
+   phase: <phase-name>
+   status: pending
+   owner: null
+   entered_at: null      # except the initial phase, which gets created_at
+   completed_at: null
+   completed_by: null
+   skip_reason: null
+   artifacts:
+     - name: <artifact-name-from-templates-show>
+       status: not-started
+   metrics: { elapsed_seconds: 0 }
+   ```
+   The initial phase takes `entered_at: <the instance's created_at>`. It is the one phase no transition ever enters, so leaving it null means it completes with `elapsed_seconds: 0` and drops out of every lead-time figure.
+6. Fire the `on-instance-start` lifecycle actions (see **Lifecycle Actions** in **aidlc-overview**). Do not skip this — automation the user configured (branch creation, issue tracking, notifications) depends on it. When the instance was created via the worktree flow or as no-code, set `AIDLC_WORKTREE=1` in the action environment so the branch-creation action no-ops (the worktree flow already made its branch; a no-code instance must not get one).
+7. Report the instance name, phases, state path, and any actions that fired, then begin the initial phase with its skill.

package/resources/rules/lifecycle-or-skill.md

@@ -0,0 +1,37 @@
+# Lifecycle or Skill?
+
+**The rule: lifecycle for changes to the system; skills for repeatable operations of the system.**
+
+Not every task belongs in a lifecycle instance. Ask which of the two a request is:
+
+- **A change to the system** — a new capability, a fix, a refactor, anything that alters what the
+  system can do. This goes through the lifecycle: phases, artifacts, gates.
+- **A repeatable operation of the system** — running a chore the system already supports, over and
+  over, with the same steps each time. This belongs in a **skill**, not an instance.
+
+Worked example, a blog application:
+
+| Request | Which | Why |
+|---|---|---|
+| "Add a series feature so posts can belong to a series" | **Lifecycle** | The system cannot do this yet. New capability → requirements, design, tests. |
+| "Publish a post about last week's release" | **Skill** | The system already supports posts. Same steps every time. Wrapping each post in phases is ceremony. |
+
+Running an operational skill is **never** a lifecycle instance. Do not create an instance, claim, or
+phase artifacts to publish a post, rotate a log, or regenerate a report.
+
+## The escape hatch
+
+An operation sometimes reveals a missing capability — you go to publish a post and discover the system
+has no way to mark it as a draft. When that happens, the *operation* stops being the work and the
+missing capability re-enters the lifecycle as a normal instance. Capture it with **aidlc-roadmap** or start
+an instance; do not quietly extend the skill into building the feature.
+
+## Quality mechanisms live inside the skill
+
+An operational skill's output still needs checking — facts verified, schema validated, the build run,
+links resolved. Those checks belong **inside the skill's own instructions**, not as lifecycle phases
+wrapped around each invocation. A skill that carries its own verification produces checked output every
+time it runs; a skill that relies on a review phase produces checked output only when someone remembers
+to run one.
+
+`aidlc add skill` scaffolds an operational skill with verification steps already embedded.

package/resources/rules/question-protocol.md

@@ -0,0 +1,41 @@
+# Question Protocol
+
+Ask the user something when **different answers would change an artifact, a design decision, or scope** — the trigger is consequence, not volume. A question whose answers change nothing is not asked. A question that an answer already given in this instance resolves is not re-asked: name that answer and ask the narrow follow-up instead.
+
+## The spec
+
+Every question is written first as a **spec** — platform-neutral, and never printed into the conversation. It carries, at minimum:
+
+- **The decision**, as one interrogative sentence.
+- **What it is** — what the thing being decided is and what it does, in plain words, shown on one concrete example with names, values or dates. Required on every question: the person answering owns the decision but was not in your research, and does not carry the vocabulary you just read. For an everyday concept this is one sentence; its length scales, its presence does not.
+- **Why it matters** — what it blocks, and what goes wrong if it is guessed.
+- **What the repo already says** — cited as `path:line`, or `path` when the whole file is the point. "Nothing found" is a valid citation; saying nothing is not. Schema terms, mechanism names and citations belong here, not in the options.
+- **Two to four options**, each defined by its observable effect — who sees what, what gets rejected, what gets flagged — with its consequence spelled out. Say what would happen, not how it would be built.
+- **A recommendation**, marked as such — exactly one, with the reason it wins.
+- **If you say nothing** — the outcome of no answer, so that not answering is a choice rather than a stall.
+
+When several questions in one file share a concept, open the file with one shared primer that explains it, and have every question reuse the same running example rather than inventing a new one. The reader learns the example once and then sees each option applied to it.
+
+The example shows what would really happen. One simplified until it changes the answer misleads as badly as jargon does, and it is harder to spot.
+
+Expand every identifier on first use, writing the thing out with the tag in parentheses — "the citation rule (AC-1)", not a bare `AC-1`, `FR3` or `unit-4`. A bare tag assumes the reader carries a mapping they do not have.
+
+## Rendering the spec
+
+The spec is input to a rendering, never output. How to render it on this platform is in `.aidlc/resources/questions/rendering.md` — read that before asking. Routing is decided by the question, never by asking the user which mode they want:
+
+- Options self-explanatory and the stake fits one line → render it directly and let the user answer in place.
+- Needs citations, trade-offs, or more than three lines of context → write the question file first, then render a prompt naming its path in one line.
+
+## The question file
+
+Written in **every** branch, including when the user answers in place — it is the record of what was asked and decided, not a fallback. Two locations, and no others are valid:
+
+- Inside an instance: `.aidlc/state/<instance>/<phase>-questions.md`.
+- No instance (constitution update, first activation): `.aidlc/questions/<topic>.md`.
+
+Each question in the file ends with an `[Answer]:` tag — blank while open, carrying the chosen option label verbatim once answered. Fold answers into the phase artifact they were gathered for and leave the file in place as the record.
+
+With no interactive terminal, write the file, say where it is, and end the turn. Never assume an answer.
+
+**At most five questions stand open at once.** At the limit, answering — or accepting the stated defaults — comes before asking another. The cap counts open questions, not questions asked: a long negotiation is fine, an accumulating pile is not.

package/skills/00-overview.md

@@ -43,41 +43,7 @@ The AIDLC defines seven ordered phases. Not all apply to every task:
 
 ## Lifecycle or Skill?
 
-**The rule: lifecycle for changes to the system; skills for repeatable operations of the system.**
-
-Not every task belongs in a lifecycle instance. Ask which of the two a request is:
-
-- **A change to the system** — a new capability, a fix, a refactor, anything that alters what the
-  system can do. This goes through the lifecycle: phases, artifacts, gates.
-- **A repeatable operation of the system** — running a chore the system already supports, over and
-  over, with the same steps each time. This belongs in a **skill**, not an instance.
-
-Worked example, a blog application:
-
-| Request | Which | Why |
-|---|---|---|
-| "Add a series feature so posts can belong to a series" | **Lifecycle** | The system cannot do this yet. New capability → requirements, design, tests. |
-| "Publish a post about last week's release" | **Skill** | The system already supports posts. Same steps every time. Wrapping each post in phases is ceremony. |
-
-Running an operational skill is **never** a lifecycle instance. Do not create an instance, claim, or
-phase artifacts to publish a post, rotate a log, or regenerate a report.
-
-### The escape hatch
-
-An operation sometimes reveals a missing capability — you go to publish a post and discover the system
-has no way to mark it as a draft. When that happens, the *operation* stops being the work and the
-missing capability re-enters the lifecycle as a normal instance. Capture it with **aidlc-roadmap** or start
-an instance; do not quietly extend the skill into building the feature.
-
-### Quality mechanisms live inside the skill
-
-An operational skill's output still needs checking — facts verified, schema validated, the build run,
-links resolved. Those checks belong **inside the skill's own instructions**, not as lifecycle phases
-wrapped around each invocation. A skill that carries its own verification produces checked output every
-time it runs; a skill that relies on a review phase produces checked output only when someone remembers
-to run one.
-
-`aidlc add skill` scaffolds an operational skill with verification steps already embedded.
+Whether a request is a lifecycle instance or an operational skill, and what to do when an operation turns out to need a new capability. The rule is in `.aidlc/resources/rules/lifecycle-or-skill.md`.
 
 ## State Protocol
 
@@ -107,41 +73,7 @@ Each line in `transitions.log` is a JSON object:
 
 ### Creating an Instance
 
-The `aidlc start` CLI automates this; when it is not available, create the instance directly:
-
-0. **Concurrency gate first** (see the entry-point skill): when another live session holds a claim in this checkout, offer worktree / stop / no-code before creating anything.
-1. Pick a template and scope (see **aidlc-getting-started** for template selection and per-template artifacts). The initial phase follows the scope: full → ideation, standard → requirements, micro → implementation.
-2. Choose a URL-safe instance name and create `.aidlc/state/<name>/`. If the directory already exists, stop and ask for a different name. In a git repo, also register the instance in `<git-common-dir>/aidlc/registry/<name>.yaml` (fields: `name`, `branch`, `worktree_path`, `created_at`) — create-exclusively, never overwrite; if the file exists, another session owns the name.
-3. Write `instance.yaml`:
-   ```yaml
-   name: <instance-name>
-   template: <template-name>
-   scope: <full|standard|micro>
-   created_at: <ISO 8601 UTC>
-   created_by: <session-id or username>
-   current_phase: <initial-phase>
-   claim: null
-   scope_history: []
-   ```
-   For a worktree instance add `branch: <its-branch>`; for a no-code instance add `branch: null` (blocks Implementation entry until a branch exists). Omit the field entirely otherwise.
-4. Read the phase list and each phase's artifacts with `aidlc templates show <template> --scope <scope>` — **do not guess them, and do not copy them from another instance**. Different templates require different artifacts, and an instance seeded with artifacts its template never asked for fails its gates on files nobody needs. If the CLI is unavailable, the definitions are in `@rasensio/aidlc-content`'s `templates/` directory.
-5. For each phase that command lists, write `phase-<name>.yaml`, using its artifact names verbatim:
-   ```yaml
-   phase: <phase-name>
-   status: pending
-   owner: null
-   entered_at: null      # except the initial phase, which gets created_at
-   completed_at: null
-   completed_by: null
-   skip_reason: null
-   artifacts:
-     - name: <artifact-name-from-templates-show>
-       status: not-started
-   metrics: { elapsed_seconds: 0 }
-   ```
-   The initial phase takes `entered_at: <the instance's created_at>`. It is the one phase no transition ever enters, so leaving it null means it completes with `elapsed_seconds: 0` and drops out of every lead-time figure.
-6. Fire the `on-instance-start` lifecycle actions (see **Lifecycle Actions**). Do not skip this — automation the user configured (branch creation, issue tracking, notifications) depends on it. When the instance was created via the worktree flow or as no-code, set `AIDLC_WORKTREE=1` in the action environment so the branch-creation action no-ops (the worktree flow already made its branch; a no-code instance must not get one).
-7. Report the instance name, phases, state path, and any actions that fired, then begin the initial phase with its skill.
+Creating an instance by hand when the `aidlc start` CLI is not available. The rule is in `.aidlc/resources/rules/creating-an-instance.md`.
 
 ## Lifecycle Actions
 
@@ -158,45 +90,7 @@ On each lifecycle event — `on-instance-start`, `on-phase-enter`, `on-phase-exi
 
 ## Question Protocol
 
-Ask the user something when **different answers would change an artifact, a design decision, or scope** — the trigger is consequence, not volume. A question whose answers change nothing is not asked. A question that an answer already given in this instance resolves is not re-asked: name that answer and ask the narrow follow-up instead.
-
-### The spec
-
-Every question is written first as a **spec** — platform-neutral, and never printed into the conversation. It carries, at minimum:
-
-- **The decision**, as one interrogative sentence.
-- **What it is** — what the thing being decided is and what it does, in plain words, shown on one concrete example with names, values or dates. Required on every question: the person answering owns the decision but was not in your research, and does not carry the vocabulary you just read. For an everyday concept this is one sentence; its length scales, its presence does not.
-- **Why it matters** — what it blocks, and what goes wrong if it is guessed.
-- **What the repo already says** — cited as `path:line`, or `path` when the whole file is the point. "Nothing found" is a valid citation; saying nothing is not. Schema terms, mechanism names and citations belong here, not in the options.
-- **Two to four options**, each defined by its observable effect — who sees what, what gets rejected, what gets flagged — with its consequence spelled out. Say what would happen, not how it would be built.
-- **A recommendation**, marked as such — exactly one, with the reason it wins.
-- **If you say nothing** — the outcome of no answer, so that not answering is a choice rather than a stall.
-
-When several questions in one file share a concept, open the file with one shared primer that explains it, and have every question reuse the same running example rather than inventing a new one. The reader learns the example once and then sees each option applied to it.
-
-The example shows what would really happen. One simplified until it changes the answer misleads as badly as jargon does, and it is harder to spot.
-
-Expand every identifier on first use, writing the thing out with the tag in parentheses — "the citation rule (AC-1)", not a bare `AC-1`, `FR3` or `unit-4`. A bare tag assumes the reader carries a mapping they do not have.
-
-### Rendering the spec
-
-The spec is input to a rendering, never output. How to render it on this platform is in `.aidlc/resources/questions/rendering.md` — read that before asking. Routing is decided by the question, never by asking the user which mode they want:
-
-- Options self-explanatory and the stake fits one line → render it directly and let the user answer in place.
-- Needs citations, trade-offs, or more than three lines of context → write the question file first, then render a prompt naming its path in one line.
-
-### The question file
-
-Written in **every** branch, including when the user answers in place — it is the record of what was asked and decided, not a fallback. Two locations, and no others are valid:
-
-- Inside an instance: `.aidlc/state/<instance>/<phase>-questions.md`.
-- No instance (constitution update, first activation): `.aidlc/questions/<topic>.md`.
-
-Each question in the file ends with an `[Answer]:` tag — blank while open, carrying the chosen option label verbatim once answered. Fold answers into the phase artifact they were gathered for and leave the file in place as the record.
-
-With no interactive terminal, write the file, say where it is, and end the turn. Never assume an answer.
-
-**At most five questions stand open at once.** At the limit, answering — or accepting the stated defaults — comes before asking another. The cap counts open questions, not questions asked: a long negotiation is fine, an accumulating pile is not.
+When to ask the user something, how the question is written, and where it is recorded. The rule is in `.aidlc/resources/rules/question-protocol.md`.
 
 ## Roadmap Capture
 
@@ -239,26 +133,11 @@ An instance's **completion moment** is when the last applicable phase (template
 
 ### The always-read rule
 
-This is the canonical statement of the rule. The phase skills point here instead of restating it, so there is no second copy to drift.
-
-**Read the always-read set on entering a phase: every layer in `.aidlc/guidance/index.yaml` *except* those whose entry carries `on_demand: true`.** Read the index rather than assuming the layers named at the bottom of a skill are the only ones — a project can install a layer after its skills were emitted.
-
-An `on_demand: true` layer is read **only when the phase has a stated reason to**. It is registered, active, and current; it is simply too large to be worth carrying in every session by default.
-
-The two lessons layers are the reason the distinction exists:
-
-- **`lessons-digest.md` is always-read.** A short distillation of the lessons this project has paid for more than once, regenerated by the **aidlc-retrospective** skill at consolidation.
-- **`.aidlc/guidance/lessons.md` is on-demand, and it is the full corpus** — every lesson from every completed instance. Read it when you are touching a mechanism a past instance got wrong, when a gate keeps failing for reasons nobody can name, or when running consolidation. It grows by design (up to three lessons per instance), which is what makes an unconditional read a tax on every future session rather than a one-time cost.
-
-Treat every lesson as a historical observation, not a directive. An entry naming a file, function, or flag may describe code a later instance renamed or deleted — check the source before acting on it.
+Which guidance layers to read on entering a phase, and when to reach for the full `lessons.md`. The rule is in `.aidlc/resources/rules/always-read.md`.
 
 ### The constitution rule
 
-This is the canonical statement of the rule. Other skills point here instead of restating it, so there is no second copy to drift.
-
-When `.aidlc/context/constitution.md` exists, read it before shaping work. It records what this repo owns (`IN-<n>` entries) and what it must never do (`NOT-<n>` entries), each citing the vision statement it was derived from. **If the work in front of you crosses a prohibition, name that prohibition by its id and say plainly that it does, before going further.** The user may still choose to proceed, or to amend the constitution — but the crossing gets stated out loud at the start rather than discovered in review.
-
-The constitution never fails a gate and never blocks a transition; its whole force is that somebody read it out at the right moment. An absent file is a normal state, not a gap to fill — it is written by the **aidlc-constitution** skill, and only a project with a vision document to import has one.
+What to do before shaping work when `.aidlc/context/constitution.md` exists. The rule is in `.aidlc/resources/rules/constitution.md`.
 
 ## Security
 
@@ -277,40 +156,4 @@ Never store credentials, tokens, or secrets in state files or artifacts.
 
 ### The context rule
 
-This is the canonical statement of the rule. Every phase skill points here instead of
-restating it, so there is no second copy to drift — and so the rule does not itself
-become resident bytes in seven places.
-
-**A phase boundary is where you start a fresh session.** Not a suggestion about tidiness:
-91% of what a lifecycle run costs is re-reading the conversation it is already carrying,
-and that carry only grows. Measured across 20,920 attributed records, average context per
-unit of work runs 80k tokens in ideation, 164k in requirements, 259k in implementation,
-395k in deployment and 791k in maintenance. Deployment is the most expensive phase in the
-lifecycle — more than implementation — not because it does more, but because it runs last
-and inherits everything before it. The one phase that reliably starts fresh does
-comparable work at 76k.
-
-Three things follow:
-
-1. **Cross a phase boundary in a new session** whenever the platform allows it. The
-   lifecycle is designed for this: state lives in files, not in the conversation.
-2. **Re-read only what the phase you are entering names.** Each phase skill lists exactly
-   that under *Entering in a fresh session*. The list is the whole list — an artifact not
-   on it is not needed to start, and reading it "for context" is the charge this rule
-   exists to avoid.
-3. **Check the budget when you are unsure**: `aidlc cost context` reports the context this
-   session is carrying against a budget (default 150,000 tokens, configurable as
-   `cost.context_budget_tokens`). It reads the transcript, so it answers before any cost
-   capture has run.
-
-**The budget never fails a gate and never blocks a transition.** Its whole force is that
-somebody read it out at the right moment — the same force the constitution has, and for
-the same reason. Going over budget is information, not a violation: a long
-implementation phase may legitimately exceed it. What is not legitimate is carrying
-requirements' conversation into deployment because nobody stopped to notice.
-
-A caveat worth stating, because it decides whether the rule is worth following: a fresh
-session re-reads some of what it would otherwise still hold, and that spends back part of
-the saving. Every phase list below is bounded for exactly that reason. If re-reading turns
-out to cost more than a third of the saving, the threshold should move — measure it rather
-than assuming either way.
+Why a phase boundary is where a fresh session starts, and what to re-read after one. The rule is in `.aidlc/resources/rules/context.md`.

package/skills/01-getting-started.md

@@ -34,7 +34,7 @@ All lifecycle work runs on instances — YAML state under `.aidlc/state/<name>/`
 
 > {{glossary:instance}}
 
-1. Create a lifecycle instance from the `bugfix` template (see "Creating an Instance" in **aidlc-overview**).
+1. Create a lifecycle instance from the `bugfix` template (see **Creating an Instance** (`.aidlc/resources/rules/creating-an-instance.md`)).
 2. This gives a focused workflow: reproduce the bug → fix it → test it → deploy. The bugfix template skips the design phase and requires a `reproduction.md` artifact first.
 3. Follow **aidlc-continue** at any point to pick up the next step.
 
@@ -49,7 +49,7 @@ Create an instance from the template that fits:
 
 No. The rule is: **lifecycle for changes to the system; skills for repeatable operations of the system.** Publishing
 a post, rotating a log, regenerating a report — the system already supports these, so they belong in a
-skill rather than a lifecycle instance. See "Lifecycle or Skill?" in **aidlc-overview** for the rule, the
+skill rather than a lifecycle instance. See **Lifecycle or Skill?** (`.aidlc/resources/rules/lifecycle-or-skill.md`) for the rule, the
 escape hatch when an operation reveals a missing capability, and a worked example.
 
 Run `aidlc add skill <name>` to scaffold one with verification steps already built in. If you would

package/skills/03-entry-point.md

@@ -60,9 +60,9 @@ If `.aidlc/state/` is empty or missing, offer just three options: start somethin
 | Choice | Action |
 |--------|--------|
 | Continue an instance | Follow the **aidlc-continue** skill |
-| Start something new | Run the **concurrency gate** (below), then ask what they are building, pick a template (see **aidlc-getting-started**), and create the instance per "Creating an Instance" in **aidlc-overview** |
+| Start something new | Run the **concurrency gate** (below), then ask what they are building, pick a template (see **aidlc-getting-started**), and create the instance per **Creating an Instance** (`.aidlc/resources/rules/creating-an-instance.md`) |
 | Capture a roadmap item | Follow the **aidlc-roadmap** skill (capture flow) |
-| Answer pending questions | Open the question file, re-render its open questions per the **Question Protocol** in **aidlc-overview**, record each answer in the file, then fold them into the artifact they were gathered for |
+| Answer pending questions | Open the question file, re-render its open questions per the **Question Protocol** (`.aidlc/resources/rules/question-protocol.md`), record each answer in the file, then fold them into the artifact they were gathered for |
 | Triage the inbox | Follow the **aidlc-roadmap** skill (triage flow) |
 | Browse / promote the roadmap | Follow the **aidlc-roadmap** skill (browse/promote flow) |
 | Show status | Summarize each instance from its state files — name, template, current phase, completion %, and whether it looks stalled. When the roadmap is non-empty, append the per-status counts (e.g. "roadmap: 3 inbox, 5 backlog, 12 done") |

package/skills/04-roadmap.md

@@ -155,7 +155,7 @@ Work you agree with but cannot start — gated on a trigger, a decision, or some
 
 Triage is the one flow that reads into the body, and it reads **the executive summary and nothing else**. Six labelled lines per item is what makes triaging a full inbox in one sitting possible; opening whole items is what makes triage something nobody ever gets round to. Show the summary, say which way you would go and why, and let the human decide. If an item has no executive summary, write one from what the item says before asking for a decision — a decision made without one is a decision made twice.
 
-Read `.aidlc/context/constitution.md` when it exists and apply the constitution rule in **aidlc-overview**: an item that crosses a prohibition is the clearest `hold/` there is, and naming the prohibition turns "not for us" into a reason the submitter can read.
+Read `.aidlc/context/constitution.md` when it exists and apply the constitution rule in `.aidlc/resources/rules/constitution.md`: an item that crosses a prohibition is the clearest `hold/` there is, and naming the prohibition turns "not for us" into a reason the submitter can read.
 
 ## Promote
 
@@ -166,7 +166,7 @@ Promotion is where the roadmap meets the lifecycle:
 1. Promote from `backlog/` normally; from `inbox/` only when the user is explicitly skipping triage.
 2. If the item's `depends_on` names items that are not yet `done`, say so and confirm before proceeding — promoting out of order is allowed but should be deliberate.
 3. Choose a template and scope as usual (defaults from `.aidlc/config.yaml`; see **aidlc-getting-started**).
-4. Create the instance per "Creating an Instance" in **aidlc-overview** — including firing `on-instance-start` lifecycle actions.
+4. Create the instance per **Creating an Instance** (`.aidlc/resources/rules/creating-an-instance.md`) — including firing `on-instance-start` lifecycle actions.
 5. Seed the instance with the item: Full scope → the item is raw material the Ideation phase refines into that phase's required artifact (`idea.md` for the feature templates, `research-question.md` for `spike`); Standard scope → the item is input context for Requirements.
 6. Set `promoted_to: <instance-name>`, move the file to `in-progress/`, and append the `history` entry.
 

package/skills/05-constitution.md

@@ -136,7 +136,7 @@ risk, and it exits 0 either way. This is advisory. It never fails a phase.
 
 A constitution update has no instance, so its questions go to
 `.aidlc/questions/constitution-update-<YYYY-MM-DD>.md` — one question per change,
-following the **Question Protocol** in the overview skill:
+following the **Question Protocol** (`.aidlc/resources/rules/question-protocol.md`):
 
 ```markdown
 # Constitution update — <date>

package/skills/10-ideation.md

@@ -26,7 +26,7 @@ Ideation is the cheapest phase to enter because it inherits nothing. Read only:
 - `.aidlc/context/constitution.md`, when it exists
 
 Nothing else. There is no prior artifact to re-read; that is the whole advantage of
-starting here. See **The context rule** in **aidlc-overview** for why this list is a list.
+starting here. See **The context rule** (`.aidlc/resources/rules/context.md`) for why this list is a list.
 
 ## Required Artifacts
 
@@ -41,7 +41,7 @@ and open questions.
 
 > {{glossary:artifact}}
 
-1. **Consult the knowledge graph first.** If the project has a knowledge graph (`.aidlc/knowledge/` exists), run `aidlc knowledge context --scope phase --phase ideation` before exploring the codebase — it is the cheapest way to find where in the code to look, and re-exploring what it already covers wastes the phase. It is an index, not an authority: a specific symbol it names may have been renamed or deleted by a later instance, so open the source before treating any named component, table, or registry as real. Also read the always-read guidance layers from `.aidlc/guidance/index.yaml` — see **The always-read rule** in **aidlc-overview** for which layers those are and when to reach for the full `lessons.md`.
+1. **Consult the knowledge graph first.** If the project has a knowledge graph (`.aidlc/knowledge/` exists), run `aidlc knowledge context --scope phase --phase ideation` before exploring the codebase — it is the cheapest way to find where in the code to look, and re-exploring what it already covers wastes the phase. It is an index, not an authority: a specific symbol it names may have been renamed or deleted by a later instance, so open the source before treating any named component, table, or registry as real. Also read the always-read guidance layers from `.aidlc/guidance/index.yaml` — see **The always-read rule** (`.aidlc/resources/rules/always-read.md`) for which layers those are and when to reach for the full `lessons.md`.
 2. **Clarify the problem.** Ask the user what they want to build and why. Identify the core need vs. nice-to-haves.
 3. **Explore constraints.** Document: timeline, technical constraints, platform limitations, team size, budget considerations.
 4. **Generate options.** Propose 2-3 approaches. For each, note trade-offs (complexity, time, risk).

package/skills/20-requirements.md

@@ -25,11 +25,11 @@ Read only:
 - the ideation artifact (`idea.md`, or `research-question.md` for `spike`) — Full scope only
 - the roadmap item this instance was promoted from — Standard scope, where it replaces the
   ideation artifact as input
-- the always-read guidance layers named in `.aidlc/guidance/index.yaml` (see **The always-read rule** in **aidlc-overview**)
+- the always-read guidance layers named in `.aidlc/guidance/index.yaml` (see **The always-read rule** (`.aidlc/resources/rules/always-read.md`))
 - `.aidlc/context/constitution.md`, when it exists
 
 Not the ideation *conversation* — the artifact is what it was written for.
-See **The context rule** in **aidlc-overview**.
+See **The context rule** (`.aidlc/resources/rules/context.md`).
 
 ## Required Artifacts
 
@@ -39,7 +39,7 @@ See **The context rule** in **aidlc-overview**.
 
 > {{glossary:artifact}}
 
-1. **Gather requirements.** If a Full scope, read the ideation phase's artifact for context (`idea.md` for the feature templates, `research-question.md` for `spike`; `phase-ideation.yaml` names it). Otherwise, ask the user to describe desired behavior. Read the always-read guidance layers from `.aidlc/guidance/index.yaml` — see **The always-read rule** in **aidlc-overview** for which layers those are and when to reach for the full `lessons.md`. Read `.aidlc/context/constitution.md` when it exists and apply the constitution rule in **aidlc-overview**.
+1. **Gather requirements.** If a Full scope, read the ideation phase's artifact for context (`idea.md` for the feature templates, `research-question.md` for `spike`; `phase-ideation.yaml` names it). Otherwise, ask the user to describe desired behavior. Read the always-read guidance layers from `.aidlc/guidance/index.yaml` — see **The always-read rule** (`.aidlc/resources/rules/always-read.md`) for which layers those are and when to reach for the full `lessons.md`. Read `.aidlc/context/constitution.md` when it exists and apply the constitution rule in `.aidlc/resources/rules/constitution.md`.
 2. **Write user stories.** Use the format: "As a [role], I want [capability], so that [benefit]."
 3. **Define acceptance criteria.** Each criterion must be:
    - Specific and unambiguous
@@ -48,7 +48,7 @@ See **The context rule** in **aidlc-overview**.
    - **Identified**: write every criterion as a list item `- AC-<n>: <text>` (bold variants `- **AC-<n>**: ...` and `- **AC-<n>:** ...` are also valid). Assign `AC-1`, `AC-2`, ... sequentially. IDs are never renumbered or reused — an amended criterion keeps its meaning or is retired: mark it `- AC-<n> (retired YYYY-MM-DD, superseded by AC-<m>): <text>` and issue a new ID. The testing-phase gate parses these IDs and fails on any active criterion without a referencing test.
 4. **Set scope boundaries.** Explicitly state what is NOT included.
 5. **Non-functional requirements.** Address performance, security, accessibility, and compatibility where relevant.
-6. **For open decisions**: When a decision would change what `requirements.md` says, ask it through the **Question Protocol** in **aidlc-overview** — questions for this phase go to `.aidlc/state/<instance>/requirements-questions.md`. Prefer drafting `requirements.md` early with the unresolved points marked as explicit decision blocks: users decide better reacting to a concrete draft than answering abstract questions. Fold each answer into the draft and leave the question file as the record of what was decided and why.
+6. **For open decisions**: When a decision would change what `requirements.md` says, ask it through the **Question Protocol** (`.aidlc/resources/rules/question-protocol.md`) — questions for this phase go to `.aidlc/state/<instance>/requirements-questions.md`. Prefer drafting `requirements.md` early with the unresolved points marked as explicit decision blocks: users decide better reacting to a concrete draft than answering abstract questions. Fold each answer into the draft and leave the question file as the record of what was decided and why.
 
 ## Bugfix Reproduction (bugfix template)
 

package/skills/30-design.md

@@ -23,13 +23,13 @@ Read only:
 
 - `instance.yaml`
 - `requirements.md` — in full; the acceptance criteria are what the design is traced against
-- the always-read guidance layers named in `.aidlc/guidance/index.yaml` (see **The always-read rule** in **aidlc-overview**)
+- the always-read guidance layers named in `.aidlc/guidance/index.yaml` (see **The always-read rule** (`.aidlc/resources/rules/always-read.md`))
 - `.aidlc/context/architecture.md` and `style-guide.md`
 - `.aidlc/context/constitution.md`, when it exists
 
 The seams the requirements touch are then read from the *source*, as step 3 of the
 instructions says — a handful of files, not a survey, and not the previous phase's
-transcript. See **The context rule** in **aidlc-overview**.
+transcript. See **The context rule** (`.aidlc/resources/rules/context.md`).
 
 ## Required Artifacts
 
@@ -40,7 +40,7 @@ transcript. See **The context rule** in **aidlc-overview**.
 > {{glossary:gate}}
 
 1. **Review requirements.** Read `requirements.md` (or its summary if one exists). Identify the key technical challenges. When requirements carry `AC-n` IDs, note in each design section which criteria it addresses — that linkage is what reviewers and the testing phase trace against.
-2. **Consult the knowledge graph, then check it against the source.** If the project has a knowledge graph (`.aidlc/knowledge/` exists), run `aidlc knowledge context --scope phase --phase design` for existing architecture, decisions, and conventions. The graph is an index into the code, not an authority over it: an entry naming a component, table, column, function, or registry is a pointer to open, and an entry written by an earlier instance may name something a later one renamed or deleted. Confirm a named symbol exists in the source before designing against it — `aidlc knowledge verify <id>` records that you did, and `aidlc knowledge update <id>` corrects an entry that no longer matches. A design built on a symbol that is not there produces code against an API nobody has, and nothing downstream catches it until implementation. Also read the always-read guidance layers from `.aidlc/guidance/index.yaml` — see **The always-read rule** in **aidlc-overview** for which layers those are and when to reach for the full `lessons.md`. Read `.aidlc/context/constitution.md` when it exists and apply the constitution rule in **aidlc-overview**.
+2. **Consult the knowledge graph, then check it against the source.** If the project has a knowledge graph (`.aidlc/knowledge/` exists), run `aidlc knowledge context --scope phase --phase design` for existing architecture, decisions, and conventions. The graph is an index into the code, not an authority over it: an entry naming a component, table, column, function, or registry is a pointer to open, and an entry written by an earlier instance may name something a later one renamed or deleted. Confirm a named symbol exists in the source before designing against it — `aidlc knowledge verify <id>` records that you did, and `aidlc knowledge update <id>` corrects an entry that no longer matches. A design built on a symbol that is not there produces code against an API nobody has, and nothing downstream catches it until implementation. Also read the always-read guidance layers from `.aidlc/guidance/index.yaml` — see **The always-read rule** (`.aidlc/resources/rules/always-read.md`) for which layers those are and when to reach for the full `lessons.md`. Read `.aidlc/context/constitution.md` when it exists and apply the constitution rule in `.aidlc/resources/rules/constitution.md`.
 3. **Find the seams before proposing structure.** A project is brownfield from its second instance onwards, so start from the assumption that something in the codebase already does part of what the requirements ask for. For each capability in `requirements.md`, locate and read the existing code that carries any of it — the scheduler that already fires, the settings shape that already persists, the registry that already dispatches — and name those files in `design.md` before describing a single new component. Keep it narrow: the seams the requirements actually touch, a handful of files, not a survey. When nothing exists, write that down — "no existing seam" is a finding, and stating it is what separates a genuinely new component from one designed alongside the code that should have absorbed it.
 4. **Define architecture.** Describe the high-level structure: components, their responsibilities, and how they communicate. Say for each one whether it extends a seam found in step 3 or is new.
 5. **Specify interfaces.** For each component boundary, define the contract (function signatures, API shapes, data types).

package/skills/40-implementation.md

@@ -26,10 +26,10 @@ Read only:
 - `design.md` — the sections the next task cites, not the whole document once tasks are
   under way
 - `requirements.md` — the acceptance criteria the next task claims
-- the always-read guidance layers named in `.aidlc/guidance/index.yaml` (see **The always-read rule** in **aidlc-overview**)
+- the always-read guidance layers named in `.aidlc/guidance/index.yaml` (see **The always-read rule** (`.aidlc/resources/rules/always-read.md`))
 - `.aidlc/context/style-guide.md`
 
-Then the source files that task touches. See **The context rule** in **aidlc-overview**.
+Then the source files that task touches. See **The context rule** (`.aidlc/resources/rules/context.md`).
 
 ## Required Artifacts
 
@@ -41,7 +41,7 @@ Then the source files that task touches. See **The context rule** in **aidlc-ove
 > {{glossary:gate}}
 
 1. **Load context.** Read `.aidlc/context/style-guide.md` and `.aidlc/context/architecture.md` if they exist. Match the project's established patterns. If the project has a knowledge graph (`.aidlc/knowledge/` exists), also run `aidlc knowledge context --scope phase --phase implementation` and query it (`aidlc knowledge query <term>`) before re-exploring code it already describes — as an index into the source, never a substitute for reading it. Open the file before calling anything the graph names; an entry can outlive the symbol it describes.
-2. **Load guidance.** Read the always-read guidance layers from `.aidlc/guidance/index.yaml` — see **The always-read rule** in **aidlc-overview** for which layers those are and when to reach for the full `lessons.md`. Apply their rules during implementation.
+2. **Load guidance.** Read the always-read guidance layers from `.aidlc/guidance/index.yaml` — see **The always-read rule** (`.aidlc/resources/rules/always-read.md`) for which layers those are and when to reach for the full `lessons.md`. Apply their rules during implementation.
 3. **Execute the task breakdown.** When the instance has a `tasks.md` (produced in Design for full/quick-feature scope), read it and execute tasks in order: complete a task, then mark its checkbox `[x]` as part of the same work unit — never batch checkbox updates for later. A task that should not be done is deferred in place (`- [>] T<n>: <title> (deferred YYYY-MM-DD: <reason>)`) with a dated reason, never skipped silently or deleted; the implementation→testing gate blocks on open tasks. For bugfix scope, create the optional `tasks.md` at implementation start when the fix spans more than one commit-sized unit. For Micro scope, reference the task description and acceptance criteria directly — no task file.
 4. **Write code.** Follow the design interfaces. Match existing code style (naming, formatting, error handling patterns).
 5. **Handle sensitive operations.** Before executing any of the following, describe the action and wait for explicit user confirmation:

package/skills/50-testing.md

@@ -27,7 +27,7 @@ inherited. Read only:
 
 Not `design.md`: the design's job ended when the code existed, and the test verifies the
 code against the *requirements*. Not the implementation conversation.
-See **The context rule** in **aidlc-overview**.
+See **The context rule** (`.aidlc/resources/rules/context.md`).
 
 ## Required Artifacts
 
@@ -41,7 +41,7 @@ See **The context rule** in **aidlc-overview**.
 > {{glossary:gate}}
 > {{glossary:artifact}}
 
-1. **Review acceptance criteria.** Read `requirements.md` (or task description for Micro scope). Each criterion needs at least one test. Read the always-read guidance layers from `.aidlc/guidance/index.yaml` — see **The always-read rule** in **aidlc-overview** for which layers those are and when to reach for the full `lessons.md`.
+1. **Review acceptance criteria.** Read `requirements.md` (or task description for Micro scope). Each criterion needs at least one test. Read the always-read guidance layers from `.aidlc/guidance/index.yaml` — see **The always-read rule** (`.aidlc/resources/rules/always-read.md`) for which layers those are and when to reach for the full `lessons.md`.
 2. **Write automated tests.** Follow the project's existing test patterns:
    - Unit tests for pure logic and edge cases
    - Integration tests for component interactions

package/skills/60-deployment.md

@@ -37,7 +37,7 @@ Read only:
 Not `requirements.md`, not `design.md`, not `code-complete.md`. The release is prepared from
 what the *preceding phases concluded*, and each of those conclusions is already a compact
 artifact. Read one of them only if a specific question sends you there.
-See **The context rule** in **aidlc-overview**.
+See **The context rule** (`.aidlc/resources/rules/context.md`).
 
 ## Required Artifacts
 
@@ -51,7 +51,7 @@ deployment checklist.
 > {{glossary:gate}}
 > {{glossary:artifact}}
 
-1. **Load guidance.** Read the always-read guidance layers from `.aidlc/guidance/index.yaml` — see **The always-read rule** in **aidlc-overview** for which layers those are and when to reach for the full `lessons.md`.
+1. **Load guidance.** Read the always-read guidance layers from `.aidlc/guidance/index.yaml` — see **The always-read rule** (`.aidlc/resources/rules/always-read.md`) for which layers those are and when to reach for the full `lessons.md`.
 2. **Validate readiness.** Check the phase state files: every preceding required phase must be complete (all required artifacts `complete`). If any gate fails, address the gap before proceeding. (CLI shortcut: `aidlc gate <instance> deployment` — the phase name is the second argument, not the first.)
 3. **Write release plan.** Document in the phase's required artifact (see Required Artifacts above):
    - What is being deployed (version, changes summary)

package/skills/70-maintenance.md

@@ -29,7 +29,7 @@ Read only:
 - `deployment-record.md` — what shipped, and what was deferred
 - whatever the specific maintenance question sends you to
 
-Nothing from before deployment by default. See **The context rule** in **aidlc-overview**.
+Nothing from before deployment by default. See **The context rule** (`.aidlc/resources/rules/context.md`).
 
 ## Required Artifacts
 
@@ -40,7 +40,7 @@ and follow-up items.
 
 ## Instructions
 
-1. **Load guidance.** Read the always-read guidance layers from `.aidlc/guidance/index.yaml` — see **The always-read rule** in **aidlc-overview** for which layers those are and when to reach for the full `lessons.md`.
+1. **Load guidance.** Read the always-read guidance layers from `.aidlc/guidance/index.yaml` — see **The always-read rule** (`.aidlc/resources/rules/always-read.md`) for which layers those are and when to reach for the full `lessons.md`.
 2. **Monitor.** Check that the deployed changes behave as expected in their target environment. Note any anomalies.
 3. **Update documentation.** Ensure project docs reflect the new state:
    - README or user-facing docs updated if behavior changed

package/skills/80-review.md

@@ -42,7 +42,7 @@ The split is also the better review. Reviewing `design.md` and `tasks.md` into o
 
 1. **Read the target artifact completely.** Do not skim.
    - When the phase requires a `tasks.md` as well as a `design.md`, review the breakdown **with the design in hand** — breakdown completeness (every design section covered by a task), task sizing (commit-sized units), and AC linkage (tasks reference the criteria they satisfy) are all judgements about the design/breakdown pair, not about `tasks.md` alone. Read both, then record the breakdown's findings in its own findings file.
-2. **Load guidance.** Read the always-read guidance layers from `.aidlc/guidance/index.yaml` — see **The always-read rule** in **aidlc-overview** for which layers those are and when to reach for the full `lessons.md`.
+2. **Load guidance.** Read the always-read guidance layers from `.aidlc/guidance/index.yaml` — see **The always-read rule** (`.aidlc/resources/rules/always-read.md`) for which layers those are and when to reach for the full `lessons.md`.
 3. **Check for installed compliance controls.** Run `aidlc compliance list`. If nothing is installed, skip this step and the compliance findings stream below entirely — there is nothing to check and no file to write. If a pack is installed, run `aidlc compliance check` to get the controls that apply to this phase, each with what it requires, where to look, and its fail condition. Apply those fail conditions **as written**: they are the pack's, and reinterpreting one turns a stated control into your opinion.
 4. **Examine for each dimension:**
    - **Ambiguities** — Vague terms, undefined behavior, unclear scope

package/skills/81-continue.md

@@ -42,7 +42,7 @@ Resume an in-progress lifecycle instance efficiently. Determine where work left
    instance to a new phase, run `aidlc cost context` and report the line it prints. Crossing a
    boundary is the one moment a fresh session is free, and the reading is what makes that
    visible instead of leaving it to be noticed on the bill. Over budget is information, never a
-   blocker — see **The context rule** in **aidlc-overview**.
+   blocker — see **The context rule** (`.aidlc/resources/rules/context.md`).
 7. **Execute.** Follow the phase skill for the determined step.
 
 ## Multiple Instances

package/skills/83-add-skill.md

@@ -21,7 +21,7 @@ separate request made after the skill exists.
 The user describes something they do **repeatedly** with the **same steps** — publishing a post,
 rotating credentials, regenerating a report, cutting a release note.
 
-Before generating anything, apply the rule from **aidlc-overview**: *lifecycle for changes to the
+Before generating anything, apply the rule in `.aidlc/resources/rules/lifecycle-or-skill.md`: *lifecycle for changes to the
 system; skills for repeatable operations of the system.*
 
 ## Instructions

package/skills/90-retrospective.md

@@ -80,7 +80,7 @@ Run only in the **primary checkout** (not a linked worktree — check `git rev-p
 
 1. Propose merges of duplicate/superseded sections, retirement of stale entries, and application of `[promote-to-context]` flags (drafting the context-doc edit for approval).
 2. **Every edit is confirmed by the user individually.** Nothing is deleted silently.
-3. **Regenerate `lessons-digest.md`** — the always-read distillation that stands in for the full corpus (see **The always-read rule** in **aidlc-overview**). Rewrite everything under its `## Entries` heading with the lessons this project has paid for **more than once**, each ending with `— from <instance>, <date>` as in `lessons.md`. Keep the whole file **at or under 4096 bytes**; that bound is the point of the file, so a digest that needs more entries needs shorter ones, not a larger cap. Leave the text above `## Entries` alone — it states that the digest is lossy and names the full corpus, and a reader who only has the digest depends on both.
+3. **Regenerate `lessons-digest.md`** — the always-read distillation that stands in for the full corpus (see **The always-read rule** (`.aidlc/resources/rules/always-read.md`)). Rewrite everything under its `## Entries` heading with the lessons this project has paid for **more than once**, each ending with `— from <instance>, <date>` as in `lessons.md`. Keep the whole file **at or under 4096 bytes**; that bound is the point of the file, so a digest that needs more entries needs shorter ones, not a larger cap. Leave the text above `## Entries` alone — it states that the digest is lossy and names the full corpus, and a reader who only has the digest depends on both.
 4. **Confirm what the digest omits**, not only what it keeps. A digest is a lossy read of a safety mechanism: show which entries did not make it and get the same individual confirmation step 2 requires. Dropping a lesson from the always-read layer is a decision the user makes, never a side effect of fitting a byte budget.
 5. Report what changed; set `last_consolidated` in `index.yaml` to today.