@rasensio/aidlc-content 1.19.0 → 1.20.0

package/package.json

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

package/skills/00-overview.md

@@ -167,6 +167,26 @@ 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/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.
 
+## Amendments — changing a completed phase's artifact
+
+A completed phase's artifact is changed **only through an amendment**, never edited in
+place. The gates check that artifacts exist, not that they still agree with each other, so a
+direct edit leaves the phase `complete`, the downstream artifacts describing the old
+requirement, and every gate passing. That silent disagreement is the failure mode
+amendments exist to prevent.
+
+The protocol: retire the criterion in place (`- AC-<n> (retired YYYY-MM-DD, superseded by
+AC-<m>): ...`), issue its replacement with a fresh ID, append an
+`## Amendment <n> — YYYY-MM-DD` section carrying `Retires:` / `Issues:` / `Reopens:` /
+`Reason:` bullets, then run `aidlc amend <instance>`. Start with `aidlc amend <instance>
+--impact`, which is read-only and lists every task, test and artifact still citing the
+retired criteria. See **aidlc-requirements** for the grammar.
+
+Reopening a phase sets it and every phase between it and the current one back to
+`in-progress`, which re-arms the gates that already exist — no new gate is involved — and
+appends a `type: reopen` record so churn is legible in history. Amendments apply in order,
+a second run is a stated no-op, and a completed instance is refused: its change is new work.
+
 ## 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.

package/skills/20-requirements.md

@@ -70,3 +70,42 @@ If requirements reference sensitive data handling, authentication flows, or acce
 ## Completion
 
 When exit criteria are met, update `phase-requirements.yaml` status to `complete` and append a transition record to `transitions.log`.
+
+## Amending a Completed Phase
+
+A completed phase's artifact is changed **only through an amendment**. Editing
+`requirements.md` after its phase closed leaves `phase-requirements.yaml` saying
+`complete`, leaves the design and the code describing the old criterion, and leaves every
+gate passing — because gates check that artifacts exist, not that they still agree with
+each other. That is silent drift, and it is the most common real-world mess in any
+lifecycle.
+
+To change a criterion after its phase closed:
+
+1. Edit the definition bullet in place into the retired form — `- AC-<n> (retired
+   YYYY-MM-DD, superseded by AC-<m>): <one-line summary of what it said>` — and add the
+   replacement as a new criterion with a fresh ID. IDs are never renumbered or reused.
+2. Append an amendment section to `requirements.md`:
+
+   ```markdown
+   ## Amendment 1 — 2026-09-07, after the design review
+   - **Retires:** AC-4, AC-9
+   - **Issues:** AC-31
+   - **Reopens:** design
+   - **Reason:** the customer integration needs JSON as well as CSV
+   ```
+
+   Field bullets accept `Retires:`, `**Retires**:` and `**Retires:**` alike. AC lists take
+   whole `AC-<n>` tokens only — `AC-4..AC-6` is not a range and contributes nothing. A
+   wrapped bullet is still one bullet.
+3. Run `aidlc amend <instance> --impact` to see which tasks, tests and artifacts still cite
+   the retired criteria. The walk is advisory: it suggests phases, it does not choose them.
+4. Put the phases you actually want reopened in `Reopens:`, then run
+   `aidlc amend <instance>`. It reopens that phase and every phase between it and the
+   current one, re-arming their gates, and records a `type: reopen` entry in
+   `transitions.log` so the churn is visible in history rather than reading as a normal
+   forward pass. From testing onwards it requires `--confirm`.
+
+Amendments append; the definition bullet's status changes. Never rewrite an amendment that
+has already been applied — write the next one.
+

package/skills/30-design.md

@@ -74,3 +74,10 @@ You MUST flag these explicitly in the design document and note that implementati
 ## Completion
 
 When exit criteria are met, update `phase-design.yaml` status to `complete` and append a transition record to `transitions.log`.
+
+**Changing a completed phase's artifact.** Do it only through an amendment — append an
+`## Amendment <n> — YYYY-MM-DD` section to `requirements.md` with `Retires:`, `Issues:`,
+`Reopens:` and `Reason:` bullets, then run `aidlc amend <instance>` (start with `--impact`
+to see what still cites the retired criteria). Editing the artifact directly leaves every
+gate passing while the requirements and the code disagree.
+

package/skills/40-implementation.md

@@ -67,3 +67,10 @@ Never store credentials, API keys, tokens, or passwords in source code or state
 ## Completion
 
 When exit criteria are met, update `phase-implementation.yaml` status to `complete` and append a transition record to `transitions.log`.
+
+**Changing a completed phase's artifact.** Do it only through an amendment — append an
+`## Amendment <n> — YYYY-MM-DD` section to `requirements.md` with `Retires:`, `Issues:`,
+`Reopens:` and `Reason:` bullets, then run `aidlc amend <instance>` (start with `--impact`
+to see what still cites the retired criteria). Editing the artifact directly leaves every
+gate passing while the requirements and the code disagree.
+

package/skills/50-testing.md

@@ -85,3 +85,10 @@ You MUST describe the action, confirm it targets a safe environment, and wait fo
 ## Completion
 
 When exit criteria are met, update `phase-testing.yaml` status to `complete` and append a transition record to `transitions.log`.
+
+**Changing a completed phase's artifact.** Do it only through an amendment — append an
+`## Amendment <n> — YYYY-MM-DD` section to `requirements.md` with `Retires:`, `Issues:`,
+`Reopens:` and `Reason:` bullets, then run `aidlc amend <instance>` (start with `--impact`
+to see what still cites the retired criteria). Editing the artifact directly leaves every
+gate passing while the requirements and the code disagree.
+