@rasensio/aidlc-content 1.86.0 → 1.88.0

package/docs/index.yaml

@@ -106,6 +106,11 @@ entries:
 undocumented: []
 
 historical_paths:
+  - path: .claude/hooks/aidlc-approval-guard.mjs
+    reason: >-
+      Written into a user's project by `aidlc hook install` (agent-cannot-approve-itself);
+      lifecycle.md names where it lands. This repo has not installed it, so the path
+      does not resolve here.
   - path: packages/web
     reason: >-
       Deleted at the website cutover (nextjs-website-revamp, T27). Named in

package/docs/lifecycle.md

@@ -71,7 +71,7 @@ instance, phase and artifact names filled in. When the `CI` environment variable
 words that block for a pipeline and names no command that changes lifecycle state. `--json` output
 carries no such block.
 
-Two gates are worth knowing because they block real work (three, in verified mode):
+Three gates are worth knowing because they block real work (four, in verified mode):
 
 - The **traceability gate** requires every active acceptance criterion in `requirements.md` to be
   referenced by some test. Criteria are written `- AC-1: <text>`, and tests refer to them as
@@ -85,6 +85,13 @@ Two gates are worth knowing because they block real work (three, in verified mod
 - The **ownership gate** checks that the session transitioning a phase is the one that claimed it.
   This one has an override, and the honest observation from the retrospectives is that having the
   override meant it got waved through by reflex on every phase.
+- The **blocking-action gate** runs your own checks. An `on-phase-exit` action marked
+  `blocking: true` in `.aidlc/actions.yaml` runs once every other gate has passed and before anything
+  is written; if it fails, the transition does not happen. `on-phase-enter` and `on-instance-complete`
+  actions run after the move, so a blocking failure there keeps the move, says so, and exits 1 —
+  undoing a written move would mean restoring four files and a log line, and a crash part way would
+  leave state no command expects. Up to v1.87.0 none of this happened: blocking actions ran after the
+  move and their failures were not even printed, so put a check that must pass on `on-phase-exit`.
 - The **receipt gate** exists because `test-results.md` is written by the agent, and nothing ran the
   tests to check it. Opt in with `assurance: { default: verified }` and a person-chosen
   `verify: { command: pnpm test }` in `.aidlc/config.yaml`. `aidlc verify <instance>` then runs that
@@ -98,6 +105,20 @@ Two gates are worth knowing because they block real work (three, in verified mod
   nothing changes. The receipt is not tamper-proof yet: an agent could still write the file by hand
   until a guard on that lands.
 
+**Commands that need a person.** Three commands exist so that a person can say yes:
+`aidlc autopilot approve`, `aidlc transition --override` and `aidlc amend --confirm`. An agent that
+ran one would be approving its own work, so each refuses — exit code 2, before it reads or writes
+anything — when stdin is not a terminal or `AIDLC_UNATTENDED=1`, and names the reason. No agent
+harness gives its shell a terminal, so that check covers every harness. At a terminal they work as
+they always did; `transition` without `--override` and `amend` without `--confirm` are unaffected.
+In Claude Code the approval guard (`.claude/hooks/aidlc-approval-guard.mjs`, written by
+`aidlc hook install` and `aidlc init`) blocks the same commands earlier, and blocks file edits to the
+autopilot approval record. It fails closed: a missing script, a missing `node` or a crash blocks the
+call and says to reinstall. A shell guard can be talked around, which is why the terminal check is the
+line and the guard is the early warning. Every refusal, from either, is one line in
+`<git-common-dir>/aidlc/refusals.ndjson`. An existing project gets the guard by running
+`aidlc hook install`.
+
 Bare `aidlc`, or `aidlc menu`, opens the console if you would rather not remember the commands:
 `/help` lists them, `/doctor` runs one, plain words go to your agent, and autopilot changes print
 as they happen.
@@ -221,6 +242,8 @@ during implementation and never on `main`.
 - `packages/cli/src/traceability` — the acceptance-criteria parser and the test scanner behind the
   traceability gate. The AC grammar is closed on purpose; near-misses warn rather than vanish.
 - `packages/cli/src/tasks` — the `tasks.md` breakdown parser, including the `(wave: <n>)` marker.
+- `packages/cli/src/hooks/human-only.ts` and `approval-guard.ts` — the commands only a person may
+  run, the terminal check, the refusal log, and the Claude Code guard rendered from the same table.
 - `packages/cli/src/change` — the amendment grammar, the read-only impact walk, and the `reopen`
   transition. `parser.ts` is fence-aware and treats a wrapped bullet as one bullet, because the first
   version truncated a wrapped `Retires:` list to half its ids and dropped three fields silently.

package/docs/roadmap.md

@@ -88,6 +88,15 @@ worktree flow disagreed — one linked the item by hand, the other left it in `b
 listed items and never opened as a path, and an item that already has a `promoted_to` is refused before
 anything is created. The move is left uncommitted; committing it is the caller's.
 
+**The instance's copy is the fallback when an item loses its link.** When no item names a completing
+instance, `roadmap-done` reads the instance's own `roadmap-item.md`. If that copy's `promoted_to`
+names the instance, every open item with the copy's `id` and `promoted_to: null` is linked and moved
+to `done/`, with a line saying it was matched by id. `aidlc doctor` files such items for instances
+that already completed. Why: on 2026-10-09 two items reached `in-progress/` with `promoted_to: null`
+while their instances' copies still carried the link, and completion filed neither. What reverted
+them was never reproduced, so the fix makes the outcome right whatever the cause. An item linked to
+another instance is never taken.
+
 **Picking the next item** is `aidlc roadmap next`: the `backlog/` item with the lowest `priority`
 among those whose `depends_on` are all done, unranked items last, ties by file name. `--explain` shows
 the whole order and why anything was skipped; `--json` is for scripts. It only reads. A script that

package/docs/state-and-concurrency.md

@@ -38,6 +38,10 @@ and the `worktree_path` it was taken from. It goes **stale** after `claim_timeou
 60, set in `.aidlc/config.yaml`) — a long conversation will outlive its own claim, and re-claiming
 renews it.
 
+Completing an instance releases its claim: the `aidlc transition` that completes it removes the claim
+file and logs the release. A claim left on a completed instance by an older CLI is orphaned —
+`aidlc status` warns about it and `aidlc status --prune` removes it.
+
 Note the wrinkle, because it will bite you: `owner` in a phase file is a *label*, not a lock. Nothing
 in the CLI writes it. The ownership gate resolves the current actor from the live claim, falling back
 to `$USER` when no claim is live. So a phase file whose `owner` was hand-written to one identity,

package/package.json

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

package/skills/00-overview.md

@@ -87,7 +87,7 @@ On each lifecycle event — `on-instance-start`, `on-phase-enter`, `on-phase-exi
 2. Select actions where `enabled: true`, `event` matches, and any `phase` filter matches the current phase.
 3. For each matched action with a `run` script: execute it as a shell command with these environment variables set: `AIDLC_EVENT`, `AIDLC_INSTANCE`, `AIDLC_PHASE`, `AIDLC_TEMPLATE`.
 4. Actions marked `use` (built-ins) require the CLI — run `aidlc transition`/`aidlc start` for those, or tell the user the action needs the CLI.
-5. If an action fails and it is `blocking: true`, stop and report the failure to the user before continuing the lifecycle. If `blocking: false`, report and continue.
+5. If a `blocking: true` action fails on `on-phase-exit`, do not move; on `on-phase-enter` or `on-instance-complete`, keep the move. Non-blocking: carry on.
 6. Report every action you ran and its outcome — never run configured automation silently.
 
 ## Question Protocol

package/skills/20-requirements.md

@@ -136,7 +136,8 @@ To change a criterion after its phase closed:
    `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`.
+   forward pass. From testing onwards it requires `--confirm`, which only a person can give: the
+   command refuses it without a terminal or under `AIDLC_UNATTENDED=1`, so ask the user to run it.
 
    When the correction is confined to the phase you are in — nothing in a completed phase
    cites what you retired — write `Reopens: none` (naming the current phase means the same).

package/skills/82-add-action.md

@@ -29,7 +29,7 @@ Help the user create lifecycle actions from natural language descriptions. Trans
    - **event**: The lifecycle event from step 2
    - **phase_filter** (optional): Which phase(s) this applies to
    - **action**: A built-in action name (`git-branch`, `github-issue`, `doc-update`) or a custom shell command
-   - **blocking**: `true` if the transition should halt on failure, `false` otherwise
+   - **blocking**: `true` if a failure should stop the lifecycle, `false` otherwise. What stops depends on the event: on `on-phase-exit` the transition does not happen and nothing is written; on `on-phase-enter` and `on-instance-complete` the move has already been recorded, so it stays and the command exits 1 naming the action; on `on-instance-start` the instance exists and `aidlc start` exits 1. Choose `on-phase-exit` for a check that must pass before work moves on.
    - **description**: Preserve the user's original natural language intent
 
 4. **Present for confirmation.** Show the user: