@rasensio/aidlc-content 1.6.0 → 1.7.0

package/package.json

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

package/skills/00-overview.md

@@ -116,10 +116,15 @@ When a phase needs substantial input from the user — open decisions, structure
 
 When the user shares an idea tangential to the current work, offer to record it in `.aidlc/ideas/` (see **aidlc-idea**) 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.
 
+## Instance Completion and Retrospective
+
+An instance's **completion moment** is when the last applicable phase (template × scope) reaches `complete` — except when that phase is maintenance: maintenance is open-ended, so maintenance-terminal instances complete on maintenance **entry**. At the completion moment, run the **aidlc-retrospective** skill *before* any cleanup (worktree removal, claim release) and fire `on-instance-complete`. If a retro cannot run (declined, absent), completion proceeds anyway — the retro never blocks. Pending retros are tracked as markers in `<git-common-dir>/aidlc/retro-pending/`; the entry-point and continue skills pick them up.
+
 ## Context and Guidance
 
 - 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
 
 ## Security

package/skills/01-getting-started.md

@@ -53,6 +53,10 @@ Follow the **aidlc-continue** skill: it reads the instance state and identifies
 
 Read each instance's `instance.yaml` and `phase-<name>.yaml` files and summarize: current phase, completion percentage (complete artifacts ÷ required artifacts), and stalled instances. (CLI shortcut: `aidlc status`.)
 
+### "How is the project doing overall?"
+
+Run `aidlc metrics` (add `--json` for machine-readable output): change failure rate per template, lead time per phase and instance, which features caused bugfixes (`caused_by` linkage), and true cost — an instance's own cost plus the bugfixes it caused. Values without data show as "no data"/"unknown", never fabricated zeros.
+
 ### "How does the lifecycle work?"
 
 AIDLC guides your work through phases:

package/skills/03-entry-point.md

@@ -24,6 +24,7 @@ If `.aidlc/context/` does not exist or contains no `.md` files, defer to the **a
 2. For each instance, read `instance.yaml` (current phase, template, scope, claim) and the `phase-<name>.yaml` files to compute completion (complete artifacts ÷ total required artifacts).
 3. Read `.aidlc/config.yaml` for project defaults (scope, template) if present.
 4. Count ideas in `.aidlc/ideas/` by status — read only the frontmatter (and title line if needed), never idea bodies.
+5. Check `<git-common-dir>/aidlc/retro-pending/` (resolve via `git rev-parse --git-common-dir`) for pending-retrospective markers. Each marker adds a menu entry: **Run retrospective for `<instance>`** (routes to the **aidlc-retrospective** skill). A marker whose instance has no state dir and no registry entry is stale — remove it and note the cleanup in one line.
 
 Do not read artifact bodies or transition history to build the menu — the compact state files are enough.
 

package/skills/10-ideation.md

@@ -21,7 +21,7 @@ Explore the problem space before committing to a solution. Define what we are bu
 
 ## Instructions
 
-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 — the graph is the first source of understanding; re-explore only what it doesn't cover.
+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 — the graph is the first source of understanding; re-explore only what it doesn't cover. 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.
 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

@@ -21,7 +21,7 @@ Translate the ideation output (or the user's direct request) into precise, testa
 
 ## Instructions
 
-1. **Gather requirements.** If a Full scope, read `ideation.md` for context. Otherwise, ask the user to describe desired behavior.
+1. **Gather requirements.** If a Full scope, read `ideation.md` for context. 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.
 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
@@ -32,6 +32,19 @@ Translate the ideation output (or the user's direct request) into precise, testa
 5. **Non-functional requirements.** Address performance, security, accessibility, and compatibility where relevant.
 6. **For complex input or open decisions**: If requirements are extensive, or unresolved decisions block the draft, create an Input_File in `.aidlc/inbox/` following the User Input Protocol in **aidlc-overview**, rather than asking many sequential questions. Prefer drafting `requirements.md` early with unresolved points marked as explicit decision blocks — users decide better reacting to a concrete draft than answering abstract questions.
 
+## Bugfix Reproduction (bugfix template)
+
+When the instance uses the `bugfix` template, this phase produces `reproduction.md` instead of full requirements:
+
+1. **Reproduce first.** Capture: observed behavior, expected behavior, minimal reproduction steps, affected versions/environment. A bug that cannot be reproduced gets documented as such — with the evidence tried — before any fix work.
+2. **Acceptance criteria** for the fix follow the same `AC-<n>` ID rules as regular requirements (the reproduction steps typically become the test).
+3. **Propose defect linkage (`caused_by`).** Identify which instance(s) likely introduced the defect:
+   - `git blame` the defective lines and match commits to instance branches (`fix|feat|chore/<YYYYMMDD>-<name>`)
+   - Query the knowledge graph for the module's history
+   - Check instance state dirs and the registry for names
+   Present the candidates *as guesses* with the evidence. The user confirms, edits, or declines — `caused_by` is **never written without explicit user confirmation**, and declining leaves the field absent (absent = unknown, never an error).
+4. **Write the confirmed linkage** to `instance.yaml` as a list: `caused_by: [<instance>, ...]` (single cause = one-element list). Validate every name against existing state dirs or registry entries — an unknown name needs re-confirmation; reject the bugfix's own name (no self-reference).
+
 ## Exit Criteria
 
 - `requirements.md` exists with at least one user story and corresponding acceptance criteria

package/skills/30-design.md

@@ -22,7 +22,7 @@ Produce a technical design that satisfies the requirements. Define architecture,
 ## Instructions
 
 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.** If the project has a knowledge graph (`.aidlc/knowledge/` exists), run `aidlc knowledge context --scope phase --phase design` for existing architecture, decisions, and conventions before re-deriving them from code.
+2. **Consult the knowledge graph.** If the project has a knowledge graph (`.aidlc/knowledge/` exists), run `aidlc knowledge context --scope phase --phase design` for existing architecture, decisions, and conventions before re-deriving them from code. 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.
 3. **Define architecture.** Describe the high-level structure: components, their responsibilities, and how they communicate.
 4. **Specify interfaces.** For each component boundary, define the contract (function signatures, API shapes, data types).
 5. **Data flow.** Document how data moves through the system — inputs, transformations, storage, outputs.

package/skills/50-testing.md

@@ -22,7 +22,7 @@ Verify that the implementation satisfies all acceptance criteria. Produce eviden
 
 ## Instructions
 
-1. **Review acceptance criteria.** Read `requirements.md` (or task description for Micro scope). Each criterion needs at least one test.
+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.
 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

@@ -61,3 +61,5 @@ Never deploy without explicit user confirmation. If the user cancels, halt and l
 ## Completion
 
 When exit criteria are met, update `phase-deployment.yaml` status to `complete` and append a transition record to `transitions.log`.
+
+Then check for the **completion moment**: derive the instance's applicable phases (template × scope). If deployment is the last applicable phase, or the next phase is maintenance (maintenance-terminal templates complete on maintenance *entry*, since maintenance is open-ended), this transition completes the instance — run the **aidlc-retrospective** skill now, before any completion cleanup (worktree removal, claim release), and fire the `on-instance-complete` event.

package/skills/70-maintenance.md

@@ -53,4 +53,6 @@ You MUST describe the change, confirm the target environment, and wait for expli
 
 ## Completion
 
-When exit criteria are met, update `phase-maintenance.yaml` status to `complete`, append a transition record to `transitions.log`, and fire the `on-instance-complete` event.
+For maintenance-terminal instances the completion moment already fired on maintenance *entry* (see **aidlc-deployment**) — entering this phase means the instance is complete and its retrospective has run or is pending. Do not fire `on-instance-complete` again when closing the phase.
+
+When exit criteria are met, update `phase-maintenance.yaml` status to `complete` and append a transition record to `transitions.log`. If no retrospective exists for the instance (legacy completion paths), offer to run the **aidlc-retrospective** skill.

package/skills/81-continue.md

@@ -16,6 +16,8 @@ Resume an in-progress lifecycle instance efficiently. Determine where work left
    - Current phase
    - Template name
    - Scope
+
+   Also check `<git-common-dir>/aidlc/retro-pending/` for markers. A marker for this instance → run the **aidlc-retrospective** skill first. A marker whose instance has no state dir and no registry entry is stale — remove it and report the cleanup in one line.
 2. **Check claim.** Claims live in `<git-common-dir>/aidlc/claims/<instance>.yaml` (resolve via `git rev-parse --git-common-dir`); fall back to the `claim:` field in `instance.yaml` outside a git repo or for unmigrated instances. If another session holds the claim:
    - Check `renewed_at` against the staleness timeout (default: 60 minutes)
    - If stale: warn and request override confirmation before taking over
@@ -26,7 +28,8 @@ Resume an in-progress lifecycle instance efficiently. Determine where work left
    - If the current phase is implementation and a task-bearing `tasks.md` exists → resume at the lowest-numbered open (`[ ]`) task; do NOT re-derive the plan from design.md
    - If current phase is complete but not transitioned → evaluate transition (check gates)
    - If transition is allowed → move to next pending phase
-   - If all phases complete → report instance complete and fire `on-instance-complete`
+   - If the transition is the instance's **completion moment** (last applicable phase for the template × scope reaches complete; for maintenance-terminal instances, maintenance *entry*) → run the **aidlc-retrospective** skill before any cleanup, then fire `on-instance-complete`
+   - If all phases complete → report instance complete; if no `retrospective.md` exists, offer the retro
 5. **Load minimal context.** Read only:
    - The skill for the determined phase
    - Artifact summaries (`.summary.md`) instead of full artifacts where available

package/skills/90-retrospective.md

@@ -0,0 +1,77 @@
+---
+name: aidlc-retrospective
+description: Runs the completion retrospective — captures lessons into the guidance layer, and consolidates the lessons file on demand
+phase: maintenance
+priority: 55
+trigger: When an instance reaches its completion moment, a retro-pending marker exists, or the user asks for a retrospective or lessons consolidation
+---
+# Retrospective
+
+## Purpose
+
+Close the feedback loop: when an instance completes, capture what the work taught us while it is fresh, and write durable lessons where the next instance will read them. This is the system-level quality mechanism — gates and reviews protect one instance; retrospectives make the next one start smarter.
+
+## When to Run
+
+- **At every instance's completion moment**, regardless of scope or template. The completion moment is the last applicable phase (template × scope) reaching complete — except when that phase is maintenance, where **entering** maintenance is the moment (maintenance is open-ended).
+- **When a retro-pending marker exists** for an instance: markers live in `<git-common-dir>/aidlc/retro-pending/<instance>` (resolve via `git rev-parse --git-common-dir`; fallback `.aidlc/state/<instance>/retro-pending` outside git). The entry-point and continue skills route here when they see one.
+- **In consolidation mode** when the user accepts a consolidation prompt (see Consolidation below).
+
+Run the retro **before** any completion cleanup (worktree removal, claim release) — its outputs must be committed to the instance's branch first.
+
+## Retro Flow
+
+1. **Idempotency check.** If `retrospective.md` already exists in the instance state dir, offer to update or skip — never duplicate. A skip still removes the retro-pending marker.
+2. **Gather state.** Read `instance.yaml`, `phase-*.yaml`, and `transitions.log`. For the cost summary, prefer `aidlc cost report <instance>` (it applies fidelity precedence); only read `costs.ndjson` raw when the CLI is unavailable, and mark that summary approximate. No cost data → omit the cost section entirely, never write zeros.
+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.
+
+## Lessons Layer — Write Rules
+
+Target: `.aidlc/guidance/lessons.md` in the **current checkout/worktree**, on the instance's branch (entries travel with the merge — never write another checkout's copy).
+
+**First use.** If `.aidlc/guidance/` or `index.yaml` is missing, create them. `index.yaml` gains (or is created with) the entry:
+
+```yaml
+layers:
+  - name: lessons
+    file: lessons.md
+    last_consolidated: null
+```
+
+If `index.yaml` already exists, add only the lessons entry — never modify other entries. After registering, verify the layer loads (e.g. `aidlc update --dry-run` or re-reading the index); surface any loader warning to the user instead of swallowing it.
+
+**File shape.** The frontmatter is immutable — created once, never rewritten (all mutable metadata lives in `index.yaml`):
+
+```markdown
+---
+name: lessons
+description: Lessons from completed instances — historical observations, not directives.
+---
+```
+
+The body is **append-only between consolidations**: one `## <instance> — <YYYY-MM-DD>` section per retro run, containing 1–3 bullet lessons, each ending with `— from <instance>, <date>`. A lesson that belongs in a context doc gets the suffix `[promote-to-context]` instead of editing `.aidlc/context/` directly — the retro never touches context docs.
+
+**Re-runs supersede by appending**: write a new dated section for the same instance rather than editing the old one; readers use the latest section per instance; consolidation collapses the rest.
+
+**Concurrent-write discipline** (two sessions may complete instances simultaneously): write the full updated file to a temp name in the same directory, rename it over `lessons.md`, then **re-read and verify your section is present**. If it vanished (a concurrent writer won the rename), re-append and re-verify.
+
+## 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.
+
+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.
+
+## Rules
+
+- The retro never blocks completion: it is non-blocking, declinable, and its absence is never an error.
+- 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.