@rasensio/aidlc-content 1.31.0 → 1.32.0

package/guidance/index.yaml

@@ -5,3 +5,11 @@ layers:
     file: accessibility.md
   - name: api-conventions
     file: api-conventions.md
+  # `always_pointer` is load-bearing here, not decoration: the digest is small by
+  # design and would fall under INLINE_THRESHOLD_BYTES, so a skill naming it in a
+  # {{guidance:lessons-digest}} placeholder would bake the text into every emitted
+  # skill body. Guidance is read from .aidlc/guidance/, never duplicated into a
+  # compiled skill (lessons-digest/AC-6, AC-18).
+  - name: lessons-digest
+    file: lessons-digest.md
+    always_pointer: true

package/guidance/lessons-digest.md

@@ -0,0 +1,29 @@
+---
+name: lessons-digest
+description: The lessons this project has paid for more than once — a distillation, refreshed at consolidation
+---
+# Lessons Digest
+
+This is the **always-read** lessons layer: a short distillation of the entries this project
+has paid for more than once.
+
+The **full corpus is `.aidlc/guidance/lessons.md`** — every lesson from every completed
+instance, in full, registered as an on-demand layer. Read it when a phase has a reason to:
+you are touching a mechanism a past instance got wrong, a gate keeps failing for reasons
+nobody can name, or you are running consolidation. It is not read on entry because it grows
+by design — up to three lessons per instance — and an always-read file that only grows is a
+tax on every future session.
+
+This digest is **lossy on purpose**. It is not a summary of the corpus and does not replace
+it. Nothing here is a directive: lessons are historical observations, and one may describe
+code that has since been rewritten. Check the source before acting on an entry that names a
+file, a function, or a flag.
+
+## Entries
+
+*No entries yet.* This file is a stub until the first consolidation run fills it.
+
+The **aidlc-retrospective** skill regenerates the entries below this heading when it runs in
+consolidation mode, keeping the whole file small enough to stay resident. What it leaves out
+is confirmed edit by edit — a digest is a lossy read of a safety mechanism, so omissions are
+agreed, never silent.

package/package.json

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

package/skills/00-overview.md

@@ -225,9 +225,23 @@ An instance's **completion moment** is when the last applicable phase (template
 
 - Project context lives in `.aidlc/context/` (style-guide.md, architecture.md)
 - Guidance layers live in `.aidlc/guidance/` — load only those listed in `index.yaml`
-- `lessons.md` is the retrospective-fed guidance layer: historical observations from completed instances. Read it via the index like any other layer; treat entries as observations, not directives
 - Load context relevant to the current phase; avoid re-reading unchanged files
 
+### 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.
+
 ### 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.

package/skills/10-ideation.md

@@ -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 all active guidance layers from `.aidlc/guidance/index.yaml` (including `lessons.md` — lessons from completed instances) so fresh guidance applies without recompiling skills.
+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`.
 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,7 +25,7 @@ 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 guidance layers named in `.aidlc/guidance/index.yaml`
+- the always-read guidance layers named in `.aidlc/guidance/index.yaml` (see **The always-read rule** in **aidlc-overview**)
 - `.aidlc/context/constitution.md`, when it exists
 
 Not the ideation *conversation* — the artifact is what it was written for.
@@ -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 all active guidance layers from `.aidlc/guidance/index.yaml` (including `lessons.md` — lessons from completed instances) so fresh guidance applies without recompiling skills. 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** 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. **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

package/skills/30-design.md

@@ -23,7 +23,7 @@ Read only:
 
 - `instance.yaml`
 - `requirements.md` — in full; the acceptance criteria are what the design is traced against
-- the guidance layers named in `.aidlc/guidance/index.yaml`
+- the always-read guidance layers named in `.aidlc/guidance/index.yaml` (see **The always-read rule** in **aidlc-overview**)
 - `.aidlc/context/architecture.md` and `style-guide.md`
 - `.aidlc/context/constitution.md`, when it exists
 
@@ -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 all active guidance layers from `.aidlc/guidance/index.yaml` (including `lessons.md` — lessons from completed instances) so fresh guidance applies without recompiling skills. 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** 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**.
 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,7 +26,7 @@ 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 guidance layers named in `.aidlc/guidance/index.yaml`
+- the always-read guidance layers named in `.aidlc/guidance/index.yaml` (see **The always-read rule** in **aidlc-overview**)
 - `.aidlc/context/style-guide.md`
 
 Then the source files that task touches. See **The context rule** in **aidlc-overview**.
@@ -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 all active guidance layers from `.aidlc/guidance/index.yaml`. Apply their rules during implementation.
+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.
 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

@@ -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 all active guidance layers from `.aidlc/guidance/index.yaml` (including `lessons.md` — lessons from completed instances) so fresh guidance applies without recompiling skills.
+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`.
 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

@@ -51,7 +51,7 @@ deployment checklist.
 > {{glossary:gate}}
 > {{glossary:artifact}}
 
-1. **Load guidance.** Read all active guidance layers from `.aidlc/guidance/index.yaml` (including `lessons.md` — lessons from completed instances) so fresh guidance applies without recompiling skills. Layers can be added to a project after these skills were installed, so read the index rather than assuming the layers named at the bottom of this skill are the only ones.
+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`.
 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

@@ -40,7 +40,7 @@ and follow-up items.
 
 ## Instructions
 
-1. **Load guidance.** Read all active guidance layers from `.aidlc/guidance/index.yaml` (including `lessons.md` — lessons from completed instances) so fresh guidance applies without recompiling skills. Layers can be added to a project after these skills were installed, so read the index rather than assuming the layers named at the bottom of this skill are the only ones.
+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`.
 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 all active guidance layers from `.aidlc/guidance/index.yaml` (including `lessons.md` — lessons from completed instances) so fresh guidance applies without recompiling skills. A newly installed layer takes effect immediately, so do not assume the layers named in this skill are the only active ones.
+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`.
 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/90-retrospective.md

@@ -66,13 +66,21 @@ The body is **append-only between consolidations**: one `## <instance> — <YYYY
 
 ## Consolidation Mode
 
-Triggered when `lessons.md` exceeds **25 instance sections** (count `## ` headings) or **90 days** since `last_consolidated` in `index.yaml` — the retro checks at step 2 and offers it; `aidlc status` surfaces the same notice.
+Three independent triggers — any one of them offers consolidation. `lessons.md` exceeds:
+
+- **20KB (20,480 bytes)**, or
+- **25 instance sections** (count `## ` headings), or
+- **90 days** since `last_consolidated` in `index.yaml`.
+
+The retro checks at step 2 and offers it; `aidlc status` surfaces the same notice. The size trigger exists because the other two are the wrong dimension: this project's file reached 88KB at 23 sections, 12 days after a consolidation — long and old were both still in the future while big had long since arrived, and bytes are what a session pays for.
 
 Run only in the **primary checkout** (not a linked worktree — check `git rev-parse --git-common-dir` resolves to `./.git`):
 
 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. Report what changed; set `last_consolidated` in `index.yaml` to today.
+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.
+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.
 
 ## Rules