@rasensio/aidlc-content 1.31.0 → 1.33.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.33.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/skills/00-overview.md

@@ -197,6 +197,11 @@ With no interactive terminal, write the file, say where it is, and end the turn.
 
 When the user shares an idea tangential to the current work, offer to record it in `.aidlc/roadmap/inbox/` (see **aidlc-roadmap**) and continue the current phase — do not derail into ideation. Capture touches no instance state, so it is safe at any point in any phase.
 
+Safe for the instance is not the same as free for the person, so two rules bind every item an instance writes, exactly as they bind the capture flow:
+
+- **Merge first.** If an open item already owns the area, append a dated `## Received from <instance>` section to that item instead of writing a new one.
+- **No item enters `inbox/` without its six-line executive summary** (the labels are in **aidlc-roadmap**). Write it from what you know; `Not yet decided.` is a valid value for any label, an absent section is not. An item nobody can triage from the top of the file is not a captured idea, it is a decision deferred onto somebody else.
+
 ## Amendments — changing a completed phase's artifact
 
 A completed phase's artifact is changed **only through an amendment**, never edited in
@@ -225,9 +230,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/04-roadmap.md

@@ -35,7 +35,15 @@ Projects have more than one person proposing work, with mixed technical depth, s
 
 **The directory an item sits in is its status.** There is no `status` field, and you must never add one — two representations of one fact drift apart, and a wrong status is indistinguishable from a right one. Changing status means moving the file.
 
-`hold/` holds both parked and declined items. That conflation is deliberate; `history` and the git log distinguish them when anyone asks.
+`hold/` holds both parked and declined items, and **the history entry says which**. One directory is deliberate — a sixth status would have to be threaded through every count, every move and every projection — but "not now" and "not ever" are different decisions, and until the reason was written down they were indistinguishable on disk. So every move into `hold/` carries a reason, prefixed `parked — ` or `declined — `:
+
+```yaml
+history:
+  - { status: backlog, at: 2026-09-22 }
+  - { status: hold, at: 2026-09-23, reason: "parked — gated on the accounts table" }
+```
+
+The consequence worth stating: **agreed work waiting on a trigger belongs in `hold/`, parked, not in `backlog/`.** `backlog/` means "could start now", and an item gated on something that does not exist yet sitting there makes every count of what is ready wrong. Parking it is not dropping it, and the reason is what proves that.
 
 ## Item Format
 
@@ -59,7 +67,7 @@ history:
 - **`id`** is assigned once and never recomputed. Renaming the file or moving it between statuses leaves it unchanged. The `item-` prefix keeps it textually distinct from the filename so nothing derives one from the other.
 - **`source`** records how the item was written: `human` directly, `agent` drafted by an AI agent from someone's description, `import` migrated from an older format.
 - **`depends_on`** names other items by `id`, so a dependency survives its target moving. Build order is derived from this graph when needed — there is no global `order` field, because concurrent capture from independent sessions cannot coordinate a sequence.
-- **`history`** is append-only and advisory. Append `{ status, at }` when you move an item. An absent or incomplete history is never an error, and current status always comes from the directory — never from the last history entry.
+- **`history`** is append-only and advisory. Append `{ status, at }` when you move an item. An absent or incomplete history is never an error, and current status always comes from the directory — never from the last history entry. An entry may carry a third key, `reason`, and a move into `hold/` must; always write it **inside double quotes**, because the entry is a flow mapping and a reason containing a comma or a colon ends it early and takes the whole item's frontmatter with it.
 
 Bodies are otherwise free-form. Items authored through the portable skill carry four further headings — Problem, Who it's for, What success looks like, Out of scope — which is a useful shape, not a validated one.
 
@@ -104,6 +112,8 @@ The first section of the body, before anything else, is `## Executive Summary`
 
 This exists so a triage decision can be made from the top of the file. An item whose value cannot be stated in six lines is an item nobody can decide about, and it will sit in `inbox/` until somebody re-derives the case from scratch.
 
+**The rule binds every path that writes into `inbox/`, not just this skill's capture flow.** That includes an item written by an instance mid-phase, one drafted from a conversation that never touched capture, and one you write by hand. It was already the rule here and it was already followed here; what went wrong is that the other paths were never told. On 2026-09-23, 13 of the 18 items in one project's inbox had no summary — every one of them written by an instance, none of them triageable without re-deriving the case first. `Not yet decided.` is a valid value for any label; an absent section is not a valid item. `aidlc doctor` reports `inbox/` items missing one, by name and by missing label; it never writes one, because an invented case reads exactly like a real one.
+
 Four rules keep it honest:
 
 - **`None` is a real answer for revenue, and often the correct one.** Lifecycle plumbing earns nothing directly. Writing `Indirect` for everything makes the field useless, which is worse than leaving it blank because it reads as answered. This is also the cheapest available check against the self-repair trap: a meta-feature that has to write `Revenue — None` and `Customer value — none, it observes the lifecycle` has declared itself.
@@ -118,9 +128,10 @@ Older items may predate this section. Add it when you next touch such an item
 1. **Resolve the roadmap root.** Always write to the **primary checkout's** `.aidlc/roadmap/`, never a worktree's copy: resolve via `git rev-parse --git-common-dir` (the directory containing that path is the primary checkout). Outside a git repo, use the current project root. Create `inbox/` if missing.
 2. **Name the file.** `YYYYMMDD-<slug>.md` — today's date plus a short (2–4 word) slug.
 3. **Handle collisions.** If the filename already exists in *any* status directory, ask one question — extend the existing item or new item? On extend, append a dated `## Update (YYYY-MM-DD)` section to it where it is; on new, suffix the slug (`-2`). Never silently overwrite.
-4. **Write the file** into `inbox/`, with `source: human`, `promoted_to: null`, and one `history` entry dated today. Record `depends_on` only if the braindump itself names other items; never ask for dependencies. Do not interrogate the user for structure — capture friction kills inboxes; one braindump in, one file out.
-5. **Draft the executive summary from the braindump, do not extract it by interview.** You write those six lines; the user does not. Ask at most one question, and only when the braindump says nothing about who wants this or why — a good one is "would this make money, save money, or is it just something that needs doing?". Anything still unknown is `Not yet decided.`, which is the point of having the label.
-6. **Confirm and return.** Report the file path and the `Recommendation` line, then return to whatever was happening. Showing the recommendation lets the user correct a wrong read immediately, while the context is still in front of them.
+4. **Merge first.** Before writing a new file, check whether an open item — anything in `inbox/`, `backlog/` or `in-progress/` — already owns the area this is about. If one does, append a dated `## Received from <source>` section to **that** item and stop; say which item it went to. This is about *subject*, where step 3 is about *filename*: four of those eighteen items were findings about areas an existing item already owned, one of them literally asking somebody to triage another item. Merging them took minutes and removed four files. A new file is the right answer when no open item owns the area — which is most of the time, and the check costs one read of a list you are already looking at.
+5. **Write the file** into `inbox/`, with `source: human`, `promoted_to: null`, and one `history` entry dated today. Record `depends_on` only if the braindump itself names other items; never ask for dependencies. Do not interrogate the user for structure — capture friction kills inboxes; one braindump in, one file out.
+6. **Draft the executive summary from the braindump, do not extract it by interview.** You write those six lines; the user does not. Ask at most one question, and only when the braindump says nothing about who wants this or why — a good one is "would this make money, save money, or is it just something that needs doing?". Anything still unknown is `Not yet decided.`, which is the point of having the label.
+7. **Confirm and return.** Report the file path and the `Recommendation` line, then return to whatever was happening. Showing the recommendation lets the user correct a wrong read immediately, while the context is still in front of them.
 
 **Hard rule:** capture never reads or writes anything under `.aidlc/state/` — no claims, no phase files, no transitions log. Two sessions capturing simultaneously just produce two files; no locking exists or is needed. Do not auto-commit; staging is the user's.
 
@@ -130,13 +141,17 @@ If the user includes credentials, tokens, or secrets in a braindump, flag it and
 
 List each status directory, reading **only frontmatter and the containing directory** — never item bodies. Show each item's date, title, status, and dependencies. Group by status in lifecycle order and give a count per status. Flag `inbox/` items first: they are waiting on a decision only a human can make. Then flag `backlog/` items whose dependencies are all `done` — those are the natural next candidates. Offer to open, triage, promote, or drop.
 
+For a `hold/` item, show whether it is **parked or declined**, with its reason, from the last `history` entry — that entry is in the frontmatter, so this costs nothing extra. An item with no reason recorded is reported as `hold — reason not recorded`, never guessed at: parked and declined are opposite answers, and a wrong one either revives work somebody killed or buries work somebody agreed to.
+
 The frontmatter-only rule holds for browsing, which is a list and must stay cheap enough to run over the whole roadmap. **Triage** below is the one flow allowed into the body, and only as far as the executive summary.
 
 A filename appearing in two status directories is an error: report it rather than guessing which one is current.
 
 ## Triage
 
-Moving an `inbox/` item to `backlog/` means "we agree to do this". Moving it to `hold/` means "not now". Move the file and append the matching `history` entry. Triage is the one flow that exists purely because more than one person can submit work — do not skip it by promoting straight from `inbox/` unless the user says so.
+Moving an `inbox/` item to `backlog/` means "we agree to do this". Moving it to `hold/` means "not now", and carries a reason prefixed `parked — ` or `declined — `. Move the file and append the matching `history` entry. Triage is the one flow that exists purely because more than one person can submit work — do not skip it by promoting straight from `inbox/` unless the user says so.
+
+Work you agree with but cannot start — gated on a trigger, a decision, or something that does not exist yet — goes to `hold/` as `parked`, not to `backlog/`. Parking it with its trigger written down is the whole difference between a backlog you can read as "ready" and one where two of eleven entries are waiting on something.
 
 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.
 
@@ -159,7 +174,7 @@ When the instance completes, the `roadmap-done` lifecycle action moves the item
 
 ## Drop
 
-Move the item to `hold/` and append the `history` entry. Dropping is an explicit act — never delete or overwrite an item to get rid of it.
+Move the item to `hold/` and append the `history` entry, with a reason prefixed `declined — `. Dropping is an explicit act — never delete or overwrite an item to get rid of it, and never leave the reason off: `hold/` holds parked work too, and an unexplained entry there is a decision nobody can tell apart from the opposite one.
 
 ## Projecting to GitHub Issues
 

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

@@ -30,9 +30,11 @@ Run the retro **before** any completion cleanup (worktree removal, claim release
 3. **Ask — one round-trip.** Three questions in a single message: what surprised us? what would we do differently? what took longer than expected? For **Micro scope**, compress to one question: "anything surprising, worth doing differently, or slower than expected?" Declining the retro is fine: remove the marker, write nothing.
 4. **Write `retrospective.md`** in the instance state dir: the answers; instance metadata (template, scope); per-phase durations (pair each transitions.log `to: X` with the next `from: X`; fall back to the phase YAML's `entered_at`/`completed_at`; note inconsistencies rather than guessing); and the cost summary when available.
 5. **Distill lessons — 0 to 3.** A lesson is a durable, project-general observation ("NDJSON merge=union false-dedups identical same-second events"), not an instance anecdote ("we finished late"). If nothing generalizes, write no lesson — an empty distillation is a valid outcome.
-6. **Confirm, then append.** Show the distilled entry verbatim and get one confirmation for the whole entry. Never append unconfirmed text — lessons are auto-loaded into every future session, so this confirmation is the injection gate. Redact anything resembling credentials or secrets. On confirm, append to the lessons layer per the write rules below.
-7. **Commit** `retrospective.md` and the lessons append to the **current branch** now, before any worktree cleanup runs.
-8. **Remove the retro-pending marker** if one exists.
+6. **Cap the follow-ups — 0 to 2 queued roadmap items.** Rank what the work turned up and queue at most the top two into `.aidlc/roadmap/inbox/`, each with its six-line executive summary (see **aidlc-roadmap**). **Zero is a valid outcome**, and often the right one. This is the same cap, in the same shape, as the 0–3 on lessons, and it exists because the lessons cap alone was half a brake: the framework capped what an instance *learned* and capped nothing about what it *queued*, so closing an instance reliably grew the backlog. One measured project emitted five to nine items per close; triage kept three of eighteen.
+7. **Record the rest as observed, not queued.** Everything past the cap goes into `retrospective.md` under `## Observed, not queued`, one line each. **The cap is on queued items, not on observations** — a retro that noticed nine things writes nine and queues two. Findable, attributable, and costing nobody a triage decision. If one of them matters later, it is already written down; promote it then, with the same summary rule.
+8. **Confirm, then append.** Show the distilled entry verbatim and get one confirmation for the whole entry. Never append unconfirmed text — lessons are auto-loaded into every future session, so this confirmation is the injection gate. Redact anything resembling credentials or secrets. On confirm, append to the lessons layer per the write rules below.
+9. **Commit** `retrospective.md` and the lessons append to the **current branch** now, before any worktree cleanup runs.
+10. **Remove the retro-pending marker** if one exists.
 
 ## Lessons Layer — Write Rules
 
@@ -66,16 +68,25 @@ 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
 
 - The retro never blocks completion: it is non-blocking, declinable, and its absence is never an error.
+- The follow-up cap is never a reason to *not notice* something. Merge first — if an open roadmap item already owns the area, append a dated `## Received from <instance>` section to it rather than spending one of the two slots on a file that duplicates it.
 - Never write lessons without the step-6 confirmation. Never record credentials or secrets.
 - Lessons are historical observations, not directives — phrase them as what was learned, not as instructions to obey.