@rasensio/aidlc-content 1.49.0 → 1.51.0

package/docs/roadmap.md

@@ -0,0 +1,347 @@
+# The roadmap
+
+## Why this exists
+
+An idea arrives while you are mid-implementation on something else. You have three options: derail
+what you are doing, write it on a sticky note, or lose it. The roadmap is a fourth — capture it in
+five seconds and get back to work.
+
+The design decision that matters is that **capture is legal at any moment**. No instance, no claim, no
+phase. Capture never reads or writes anything under `.aidlc/state/`, so two sessions capturing
+simultaneously just produce two files and no locking is needed or exists.
+
+The second reason is social. Projects have more than one person proposing work, with mixed technical
+depth, so the roadmap distinguishes *submitted* from *agreed*. An item in `inbox/` is somebody waiting
+on a decision; an item in `backlog/` is a decision already made. Collapsing those two into one list is
+how a backlog becomes a place ideas go to die.
+
+**What breaks without it:** the thing this project measured — a backlog that only grows is the same as
+no backlog. Over eleven days the product backlog moved zero items while self-repair items were
+promoted within one to three days. The roadmap did not cause that, but it is what made it visible.
+
+## How to use it
+
+**Capture is not a CLI command.** The roadmap is files plus a skill, on purpose — capture friction
+kills inboxes, and shelling out to a CLI mid-thought is friction. Ask the agent to capture an item,
+and it writes one. `aidlc roadmap` does exist, but only for the GitHub Issues projection described
+below; it never captures, triages or promotes.
+
+**The directory an item sits in is its status.** There is no `status:` field, and you must never add
+one:
+
+```
+.aidlc/roadmap/
+  inbox/         submitted, nobody has triaged it
+  backlog/       accepted, will do, not started
+  in-progress/   an instance exists
+  done/          shipped
+  hold/          parked or declined
+```
+
+Changing status means moving the file. Two representations of one fact drift apart, and a wrong status
+is indistinguishable from a right one.
+
+One item per file, `YYYYMMDD-<slug>.md`, with frontmatter carrying `id`, `title`, `created_at`,
+`source`, `promoted_to`, `depends_on` and an append-only `history`.
+
+**Always quote the title.** `title: "..."` with double quotes, every time, with no judgement call
+about whether this one needs it. An unquoted YAML plain scalar may not begin with a reserved
+character, so the single most natural way to name a code defect — a title starting with a backtick —
+does not parse. Nothing reports it: the item vanishes from browse, from promotion lookup, from the
+completion action and from `aidlc doctor`, because an item that will not parse and an item that was
+never written look identical. Five of this project's first 49 items were lost this way for up to ten
+days.
+
+**Every item opens with a six-line executive summary** — what it is, who benefits, customer value,
+revenue, cost and risk, recommendation. This exists so triage can happen from the top of the file.
+`None` is a real answer for revenue and usually the correct one; writing `Indirect` for everything
+makes the field useless. It is also the cheapest check against building things that only watch the
+lifecycle: a feature that has to write *"Revenue — None"* and *"Customer value — none, it observes the
+lifecycle"* has declared itself.
+
+The rule binds **every** path into `inbox/`, including an item written by an instance mid-phase.
+`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 never writes one — see
+[Hygiene and compliance](hygiene-and-compliance.md).
+
+**A `hold/` entry says whether it is parked or declined.** One directory holds both, and the
+`history` entry carries the reason: `{ status: hold, at: 2026-09-23, reason: "parked — gated on the
+accounts table" }`, prefixed `parked — ` or `declined — `. Because `history` is frontmatter, browse
+reads it without opening the body. The consequence worth knowing: 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 makes every count of what is ready wrong.
+
+Three flows: **capture** writes to `inbox/`, after checking whether an open item already owns the area
+— if one does, the finding is appended there as a dated `## Received from <source>` section instead of
+becoming a new file. **Triage** moves to `backlog/` or `hold/`, and is the one flow allowed to read
+into an item's body — as far as the executive summary and no further. **Promote** creates an instance,
+sets `promoted_to`, and moves the file to `in-progress/`. When the instance completes, the
+`roadmap-done` action moves every item whose `promoted_to` names it to `done/` by itself; do not do
+that by hand.
+
+**Promotion is one command, not a checklist.** `aidlc start <template> --name <name> --roadmap-item
+<item>` finds the item in `backlog/` or `inbox/` by file name or id, sets `promoted_to`, moves it to
+`in-progress/` in the primary checkout, and copies it into the instance as `roadmap-item.md`. It works
+with `--worktree`. Why a flag rather than prose: on 2026-10-02 two unattended runs of the same
+worktree flow disagreed — one linked the item by hand, the other left it in `backlog/` with
+`promoted_to: null`, so `roadmap-done` would never have found it. The reference is matched against
+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.
+
+**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
+works the backlog may ask it what is next, but promoting stays a person's decision, so the command
+that picks has no way to write. `priority` is an ordinary extension field (a rank, 1 first) that a
+project declares in `roadmap.item_fields`.
+
+**Ranking the backlog** is `aidlc roadmap rank <item> <n>`: it puts a `backlog/` item at rank `n` and
+renumbers every ranked backlog item 1…k in their existing order, so ranks stay unique and gap-free —
+hand-typed ranks drift, because an item leaving the backlog leaves a hole and two items typed at one
+number tie. `--dry-run` prints the resulting order and writes nothing; the roadmap skill shows it at
+triage, proposes a rank, and runs the command only after the person answers. Only the `priority:`
+lines that change are rewritten, unranked items stay unranked, and the command refuses — writing
+nothing — when the project does not declare `priority`, when the item is not in `backlog/`, or when
+any backlog item carries a malformed rank. Where `priority` is declared, `roadmap next --explain`
+also lists every unranked backlog item, so one sitting last is visible rather than silently last.
+
+**Parking from an instance** is `aidlc roadmap park <instance> --reason "<why>"`: it moves the item
+promoted to that instance into `hold/` with a `parked — ` reason. It exists for unattended mode's hard
+stops — see [Skills and platforms](skills-and-platforms.md) — where the agent works in a worktree but
+the item's status lives in the primary checkout.
+
+Keep the raw idea count around a dozen. At the cap, promote or drop before capturing anything new. A
+completed instance queues **at most two** follow-up items and records the rest in its own
+`retrospective.md` as observed, not queued — the same cap, in the same shape, as the one on lessons.
+Without it, closing an instance reliably grew the backlog: one project emitted five to nine items per
+close and triage kept three of eighteen.
+
+## Working the backlog unattended
+
+Ask your agent to "do the next 3 items" (or "do all the items"), or run it yourself:
+
+```
+aidlc autopilot run --items 3
+aidlc autopilot run --all
+```
+
+It starts one background process and returns at once, printing its process id, its log file, and the
+commands to watch and stop it. There is nothing to schedule. The run passes over the backlog every
+minute (`--interval` to change it) and ends when the items it started are each released or parked —
+or, with `--all`, when nothing is ready and nothing is in flight. A restart ends it; asking again
+resumes.
+
+Each item goes through these steps:
+
+1. **Pick.** `aidlc roadmap next` names the next ready backlog item.
+2. **Build.** `aidlc start … --worktree --roadmap-item <item>` creates the instance in its own
+   worktree, then the configured agent runs there with `AIDLC_UNATTENDED=1`. The agent follows the
+   unattended rule and stops at the release boundary, or parks the item on a hard stop.
+3. **PR and CI.** Autopilot pushes the branch and opens the pull request. Green checks queue it;
+   a failure relaunches the agent once with the failing checks, and a second failure parks the item.
+4. **Up to date with main.** Before merging, autopilot merges `origin/main` into the branch in the
+   item's worktree — locally, so the repository's `merge=union` rules apply — pushes, and waits for
+   CI on the new head. A conflict goes back to the item's agent to resolve, twice at most, then the
+   item is parked. A pull request with no checks that GitHub reports as conflicting is handled the
+   same way: GitHub runs no checks on a conflicting PR, so waiting for them would wait forever.
+5. **Merge and release**, one at a time, never while a release workflow is running: merge the exact
+   commit CI passed (`--match-head-commit`), pull `main`, run the release step, then
+   `aidlc transition` to close the instance. A failure halts the queue. Running
+   `aidlc autopilot run` again retries a failure that came before the merge; from the pull onward
+   nothing is retried — a half-finished release is for a person.
+
+At most two items build at once, and never more than you asked for. Autopilot never moves anything
+between `inbox/`, `backlog/` and `hold/` except to park what it is building, and never edits a rank or
+a dependency: deciding what is agreed work stays a person's job.
+
+**Setup** comes first, once per machine: `aidlc autopilot setup` (or `aidlc init --autopilot`). It
+asks four questions, each a list with one choice marked recommended:
+
+- **The agent, and what it may do.** Claude Code limited to editing files and running git, pnpm,
+  node and read-only shell tools (recommended); Claude Code with full access; Codex in full-auto
+  mode; or a command you type. This decides what an unattended agent may do on your machine, so
+  it is never picked for you: with no terminal, setup needs `--agent <preset>` or
+  `--non-interactive`.
+- **How many items build at once** — two (recommended) or one.
+- **A cost cap per item** — an item past it is stopped and parked.
+- **The release step.** In a project with `scripts/autopilot-release.sh`, running it after each
+  merge (recommended); otherwise merge only, and you release when you choose. This repository's
+  script runs `release-bookkeeping --write`, commits the manifest and `.aidlc`, and runs
+  `scripts/release.sh` with the bump bookkeeping printed.
+
+Flags skip the questions: `--agent`, `--parallel`, `--cost-cap <usd|none>`, `--release
+<repo-script|merge-only>`. The answers go to `<git-common-dir>/aidlc/autopilot/config.json`, per
+machine and never committed, beside autopilot's `state.json`, `run.json`, `logs/` and `STOP` file.
+
+**Watching and stopping.** `aidlc autopilot status` shows the active run and each item's step, pull
+request, CI failure count and last error. `aidlc autopilot stop` (or `/aidlc-autopilot-stop`) ends the
+run at its next step: nothing further is started, merged or released, and agents already running
+finish their item. `aidlc autopilot forget <instance>` stops tracking an item you finished or
+abandoned by hand; a pull request merged by hand is noticed and dropped on its own. A rate limit
+from `gh` or the agent backs off five minutes, doubling to at most
+two hours. `aidlc autopilot tick --dry-run` prints every command one pass would run and runs only the
+reads.
+
+## Projecting the roadmap onto GitHub Issues
+
+Opt-in, and off until the config block exists. `aidlc roadmap sync` renders eligible items as
+GitHub issues; `aidlc roadmap import <issue-url>` seeds one `inbox/` item from an existing issue.
+
+`aidlc init` offers to write the block for you — it is the last question in the wizard, and it
+defaults to no. Say yes and it lists all five statuses with every one checked, so unchecking
+`inbox` and `hold` is a choice you make with the list in front of you rather than one made on your
+behalf. `done` cannot be turned off; without it the close path never runs and the projection never
+converges. Then it prints `aidlc roadmap sync --dry-run` and stops — nothing is published by
+answering a setup question.
+
+```yaml
+# .aidlc/config.yaml, in the PRIMARY checkout
+roadmap:
+  sync:
+    provider: github                        # the only value in this version
+    repo: owner/name                        # optional; gh resolves the current repo when absent
+    statuses: [backlog, in-progress, done]  # the default; must include done
+    label: aidlc                            # optional; the discovery label
+```
+
+Writing it by hand stays supported, and re-running `aidlc init` never destroys it: the offer arrives
+pre-answered *yes* when a section already exists, `repo` and `label` are preserved, and a section
+that omits `statuses` pre-checks the three defaults rather than all five — so pressing Enter through
+an update cannot start publishing your `inbox/`. Answering an explicit no removes the section and
+says which keys went with it.
+
+Two things `init` deliberately does not do. It does not hide the question when the GitHub CLI is
+missing — that would make the wizard's contents depend on the machine it ran on, and initializing on
+a laptop while syncing from CI is normal. It probes `gh` only after you say yes, warns with the
+remedy, writes the section anyway, and exits 0. And it never runs the projection, not even
+`--dry-run`: a fresh project has an empty roadmap, so the run would say nothing, and on a machine
+with no `gh` it could not run at all.
+
+`aidlc doctor` reports the matching condition — `roadmap.sync` configured and `gh` not on `PATH` —
+and applies nothing. It probes presence only, never `gh auth status`, so an offline run reports
+only what is true, and it is `report` tier rather than `confirm` for a specific reason: a confirm-tier
+remover applies unprompted under `--yes`, and CI is exactly where `gh` is legitimately absent.
+
+It is a **projection, not sync**. Disk stays the source of truth and the tracker is a rendering of
+it, which buys four properties worth knowing about:
+
+- **Nothing is written to disk.** There is no `remote:` field and no cache. Creating an issue and
+  writing a local link would be two writes to two systems, and every failure of the second leaves an
+  issue with no link that the next run turns into a duplicate. Instead the item `id` lives on the
+  issue, in an HTML-comment marker, so the projection can be thrown away and rebuilt.
+- **`inbox/` and `hold/` are not projected by default.** The line falls between thinking and work,
+  which happens to be the same line that keeps parked pricing thinking and a competitor teardown off
+  a public, indexed, notification-generating board.
+- **`done/` is never backfilled.** A shipped item gets an issue only if it already had one, so
+  turning this on does not create fifty closed issues nobody will read.
+- **A closed issue is never reopened, and titles you improve on GitHub are overwritten.** Closing an
+  issue is the primary triage act of the person this feature is for, so `sync` reports the divergence
+  and leaves it alone. Titles follow disk.
+
+### What the issue body contains
+
+The body carries the item: its frontmatter facts, its whole prose, and links. Specifically a facts
+block (status, created date, author, source, dependencies, promoted-to instance), a permalink to the
+roadmap file, the item's body text, and the `aidlc-item` marker. So a reader with no checkout can
+decide from the issue instead of being redirected to a file they cannot open.
+
+Three things about it are worth knowing:
+
+- **The projection owns one region, and only that region.** Everything between
+  `<!-- aidlc-body:begin -->` and `<!-- aidlc-body:end -->` is regenerated on every sync. Anything you
+  write above or below those markers is preserved, so an issue description stays usable as a place to
+  add a note. Comments are separate from the body and are never touched.
+- **Editing the item on disk updates the issue on the next sync**, as an `update-body` write. Bodies
+  used to be written once at creation, which left every issue quietly contradicting its item as soon
+  as the item changed. Issues created before v1.22.0 get the new body on the next run.
+- **Item prose is sanitized before publication, and the sanitizer is code-aware.** HTML comments are
+  stripped from prose (so an item that quotes a marker cannot hijack another issue), and `@name` and
+  `#123` spans in prose are wrapped in backticks so a sync notifies nobody and cross-links nothing.
+  Anything inside a fence or an inline code span is left byte-identical — measured over this
+  project's own roadmap, 40 of the 41 hazard-shaped spans are in code (`@clack/prompts`,
+  `actions/checkout@v4`, colour hexes such as `#0891b2`), so a code-unaware sanitizer would corrupt
+  forty spans to defuse one. Item ids in the prose become links to their item files; they are
+  deliberately *not* linked as `#N`, because that is the cross-reference being defused and it would
+  make the body depend on remote issue numbers.
+
+Nothing volatile ever enters the body — no timestamp, no commit sha, no metrics. A body containing
+the current time would differ from the stored copy on every run, so every item would plan a write
+forever and the projection would never converge.
+
+Writes always need consent: `--dry-run` prints the plan and touches nothing, an interactive run asks,
+and a non-interactive run without `--yes` prints the plan and exits **non-zero** — a green run that
+wrote nothing is how an automation comes to believe it is syncing when it never was. The plan names
+the resolved repository before the first write, which is the only moment a projection aimed at the
+wrong repo is still reversible.
+
+An item that has left a projected status keeps its open issue and is reported every run;
+`--retire-ineligible` closes those. Nothing here installs a lifecycle action: wrapping `sync` in CI is
+a user-side step, and a shipped action would start firing in every project on the next
+`aidlc update`.
+
+### Moving a Project board
+
+Put the issues on a GitHub Project and they all land in one column. That is the projection stopping
+where it should: setting a Project's Status field needs a token with `project: write`, and the
+workflow-provided `GITHUB_TOKEN` cannot do it at any permission level. The tool would need every
+project to create and store a token before it could move a board, so it does not try.
+
+The other half ships as a file:
+
+```bash
+aidlc roadmap board-workflow > .github/workflows/aidlc-project-status.yml
+```
+
+The five setup steps print to the terminal as it runs; only the workflow goes into the file.
+Do them in the order shown: label changes made before the token and project number exist are
+skipped and never replayed.
+
+That prints a GitHub Actions workflow which, on every issue event, reads the issue's current
+`aidlc:<status>` label and sets the Status field to match. Its header has the setup: create the
+Status columns (or edit its `STATUS_MAP` to name the ones you have), store a classic token with the
+`project` and `read:org` scopes — plus `repo` for a private repository — as the secret
+`AIDLC_PROJECT_TOKEN`, and set the variable `AIDLC_PROJECT_NUMBER`. A renamed discovery
+label goes in `AIDLC_DISCOVERY_LABEL`. It needs `gh` 2.97.0 or later on the runner and checks for it.
+
+The tool prints the file and never writes it into `.github/workflows/`. The token is the real setup
+cost, not the paste, and CI running in your repository with your token is yours to own.
+
+**The labels are a supported interface.** The discovery label (`aidlc` unless `label` renames it)
+and the five `aidlc:<status>` labels — `aidlc:inbox`, `aidlc:backlog`, `aidlc:in-progress`,
+`aidlc:done`, `aidlc:hold` — may be bound to by automation. Renaming or removing one is a breaking
+change and will be released as one. Each issue carries exactly one status label; the workflow refuses
+an issue with two rather than guess which is right.
+
+This repository runs the same file from `.github/workflows/project-status.yml`, and a test fails if
+the two differ.
+
+## Where the code lives
+
+- `packages/content/skills/04-roadmap.md` — the capture, triage and promote protocol. This is the
+  authority for the item format and the three flows.
+- `packages/cli/src/roadmap/sync` — the GitHub projection: `plan.ts` is pure and imports no
+  filesystem, no subprocess and not the `gh` seam, so planning is testable with no network at all;
+  `execute.ts` is the only writer and imports no `node:fs`; `gh.ts` is the single subprocess boundary,
+  argument-array only. `body.ts` renders the projection-owned region and merges it into an existing
+  issue; `sanitize.ts` defuses item prose; `markdown.ts` is the one place that decides what counts as
+  code, shared by the sanitizer and the marker scanner so the two cannot disagree.
+- `packages/cli/src/commands/roadmap.ts` — the `sync`, `import` and `board-workflow` commands,
+  consent, and exit codes.
+- `packages/content/resources/recipes/project-status.yml` — the board workflow, loaded by
+  `loadBoardWorkflow()` in `packages/content/src/recipes.ts`.
+- `packages/cli/src/commands/init.ts` — the wizard step that offers the projection, plus the
+  `gh` warning and the removal notice. `packages/cli/src/setup/setup-compute.ts` owns the merge:
+  not-asked, yes, and an explicit no are three different answers, and collapsing any two of them
+  makes a re-run of `init` delete somebody's configuration.
+- `packages/cli/src/doctor/migrations/roadmap-sync-gh-missing.ts` — the report-tier check. It
+  spawns nothing at all: the primary checkout comes from `ctx.gitCommonDir`, already resolved, not
+  from `primaryCheckout()`, which shells out to `git rev-parse`.
+- `packages/content/resources` — a portable version of the item-authoring skill, loadable into any
+  agent, so a contributor with no checkout can write an item and commit it to `inbox/`.
+- `packages/cli/src/operational` — the `roadmap-done` completion action. Its history is instructive:
+  it resolved the roadmap root to the primary checkout, so an instance finishing on a worktree branch
+  stranded its item, found nothing, printed nothing, and the transition reported success over it. An
+  action that can legitimately find nothing has to say so. Later it filed only the first of two items
+  promoted to one instance; it now files all of them and prints how many it moved.
+- `.aidlc/roadmap` — this project's own items, including the ones that became the features documented
+  elsewhere in this folder.

package/docs/skills-and-platforms.md

@@ -0,0 +1,126 @@
+# Skills and platforms
+
+## Why this exists
+
+The lifecycle is not code that runs — it is instructions an AI agent follows. So the framework's real
+payload is prose, and the problem is that every agent platform wants that prose in a different place and
+a different shape. Claude Code wants `.claude/skills/<name>/SKILL.md`. Cursor wants
+`.cursor/rules/<name>.mdc`. Codex wants one `AGENTS.md`. Kiro wants skills plus a steering file.
+
+The naive answer is to write the instructions once per platform. That answer fails on the second edit:
+five copies of "how the design phase works" become five slightly different phases, and nobody can tell
+which one is right.
+
+So there is exactly one canonical body per skill, and a **platform adapter** that packages it. The seam
+is *platform-neutral content, platform-specific packaging*. Content never knows which platform it is
+going to; adapters never contain instructions.
+
+**What breaks without it:** the same instruction drifts across five files, and a fix applied to one
+platform silently leaves the other four wrong. This is the same single-source argument as the glossary
+and the guidance layers, and it is the reason guidance is referenced by skills rather than pasted into
+them.
+
+## How to use it
+
+```
+aidlc init
+aidlc update
+aidlc add
+aidlc docs
+aidlc explain [topic]
+```
+
+`explain` prints these pages from the installed package: bare, it lists the topics; with a topic id, or
+a command a page covers (`aidlc explain claim`), it prints that page. Nothing is copied into your
+project, so there is no second version to drift.
+
+`init` installs skills for the platforms listed in `.aidlc/config.yaml`. `update` refreshes them after
+the framework changes, and also rewrites the managed block in `CLAUDE.md`.
+
+**Anything you write inside that managed block is lost on the next update.** Put project instructions
+above the start marker or below the end marker. This repo's own `CLAUDE.md` says so at the top, and the
+"Lessons That Keep Costing Us" section sits deliberately outside the block for exactly that reason.
+
+**Run the workspace build, not the installed one.** During development, invoke
+`node packages/cli/dist/cli.js update`, never `npx aidlc update`. `npx` prefers a globally installed
+binary, and it once reported "0 files updated, 35 unchanged" while the edited files sat changed on disk;
+the same command through the built path reported 7. A verification step that reads a different artifact
+than the one you changed fails green.
+
+Six adapters ship today — Claude Code, Kiro, Cursor, Codex, Windsurf and GitHub Copilot. Each
+implements one method, `plan(skills, caps, ctx)`, returning an install plan. All of them also
+copy the canonical bodies to `.aidlc/skills/`, which is what lets the framework work with no CLI present
+at runtime: the skill files on disk are self-sufficient.
+
+Platform **capabilities** are a separate axis, declared in `packages/content/capabilities`. These are
+per-platform features a phase can opt into — plan mode during ideation, for instance — keyed by platform
+and phase. Note the vocabulary collision: "capability" in that directory means a platform feature, not a
+subsystem of this repo. These pages are organised by **topic** for that reason.
+
+Those files also carry a **top-level `questions:` key**, outside the phase-keyed `capabilities:` map, and
+the reason it sits outside is not cosmetic. Capability resolution returns exactly one activation string
+per phase, and three platforms already occupy `requirements` and `design` — the two phases questions
+actually get asked in. A second entry for those phases would silently lose to the first, so question
+rendering could not live there at all.
+
+Every question opens with **what it is**: the thing being decided, in plain words, on one concrete
+example. The emitted rendering file states this once, under `## Every platform`, and every directive
+names the line again where it lists what a prompt contains. That looks like duplication and is not. An
+agent follows the most specific list it has, and five directives spell out the prompt's contents in
+order, so a rule stated only in the shared section would be dropped exactly where it is needed. The
+option half of the rule exists because Claude Code shows an option's consequence as its whole
+description: written in schema terms, the prompt was unreadable even when the question file was fine.
+The first real test (fieldmodel-apps, 2026-09-26) had all four questions declined as incomprehensible;
+rewritten with a primer and one running example, all four were answered, three against the
+recommendation.
+
+**Not everything that emits a file is an adapter.** Two emitters sit beside the adapter pass rather than
+inside it — the roadmap authoring skill and the per-platform question rendering. Both are excluded for the
+same two reasons. Adapters re-serialize frontmatter from a fixed key whitelist, so any key they do not
+already know about is dropped on round-trip; and an adapter packages one body for one platform, whereas
+these write one file carrying every configured platform's section, so a developer running two agents
+against one checkout reads one file instead of guessing which of two applies. If you are tempted to add
+an adapter to emit a file, check which of those two shapes you have first.
+
+If you are adding an operational skill of your own, reuse this seam rather than writing platform files
+directly.
+
+**Unattended mode.** Every skill assumes a person is there to answer. With `AIDLC_UNATTENDED=1`, an
+agent follows `.aidlc/resources/rules/unattended.md` instead: each place a skill would ask, wait or
+confirm has one written outcome — take the named default and log it to the instance's
+`unattended-stops.md`, or hard-stop (constitution, deleting data the session did not create,
+credentials and permissions, scope beyond the roadmap item), which parks the item and ends the session.
+Completing testing is the normal end: the agent writes the release plan and stops, and whatever runs
+it owns the push, merge and release. The list of stops came from two dry runs on 2026-10-02 that
+logged the same thirteen on two machines. The mode is a rule the agent reads, not a switch the CLI
+reads — no command behaves differently when the variable is set, because a branch in every command
+would be a cost every future change pays.
+
+## Where the code lives
+
+- `packages/cli/src/compile` — the compiler and the adapters. `adapters/index.ts` is the registry; each
+  adapter file maps one canonical body to one platform's packaging.
+- `packages/content/skills` — the canonical bodies, numbered by lifecycle order (`00-overview.md`
+  through `90-retrospective.md`). This is the only place instructions are authored.
+- `packages/content/capabilities` — per-platform capability declarations, plus each platform's
+  `questions:` rendering.
+- `packages/cli/src/compile/question-rendering.ts` — emits `.aidlc/resources/questions/rendering.md`, the
+  one file holding how each configured platform puts a question in front of the user. The protocol it
+  serves is in `packages/content/resources/rules/question-protocol.md` and names no platform tool
+  anywhere; that split is what stops the question shape from being written for one platform's UI.
+- `packages/content/resources/rules` — the six rules skills send readers to (the context rule, the
+  always-read rule, the constitution rule, the Question Protocol, Creating an Instance, Lifecycle or
+  Skill?), one file each. `packages/cli/src/compile/rules.ts` emits them to `.aidlc/resources/rules/`
+  on `init` and `update`. They used to be sections of the overview, and following one cross-reference
+  cost the reader the whole 24KB file; now it costs the rule. The overview keeps a one-line pointer per
+  rule and states none of them. On Cursor the overview is always applied, so its size is also what every
+  turn carries.
+- `packages/content/glossary.yaml` — canonical vocabulary, resolved into skill bodies where they write
+  `{{glossary:<term>}}`. Deliberately not installable into a project: guidance is yours to edit,
+  framework vocabulary is not, and a second copy drifts.
+- `packages/cli/test/skill-code-contract.test.ts` — the guard that keeps prose and code honest. It
+  asserts that every artifact filename a skill mentions is one some template actually requires, and that
+  every `aidlc <cmd>` a skill mentions resolves on the real command tree. Skills claiming commands that
+  do not exist is a class of defect this closed.
+- `packages/content/test/skill-prose.test.ts` — forbids internal type names standing in for English in
+  text a user reads.

package/docs/state-and-concurrency.md

@@ -0,0 +1,75 @@
+# State, claims and concurrent work
+
+## Why this exists
+
+Two agent sessions in one checkout do not collide on state. They collide on **git**.
+
+That sentence cost this project real money to learn. The intuition is that the danger is two sessions
+writing the same YAML file, so the obvious fix is a lock on the state. It is the wrong fix, because
+the actual damage happens elsewhere: one session runs `git add -A` and stages whatever the other
+session left on disk. Creating a branch in place yanks the other session off its branch. And on
+2026-08-26 both live instances lost their cost data entirely — the recorder saw overlapping claims,
+found `6 candidate records — ambiguous`, and attributed nothing to either.
+
+So there are two mechanisms here, and they answer different questions.
+
+A **claim** is a lock saying which session is currently working on an instance. It is not an
+assertion, a ticket, or an expense claim. It exists so that the ownership gate can tell "the session
+entitled to advance this phase" from "some other session", and so the cost recorder knows whose
+tokens these were.
+
+A **worktree** is the answer to the git problem. Two sessions get two checkouts of one repository,
+each on its own branch, sharing one `.git`. Nothing either one stages can surprise the other.
+
+**What breaks without them:** cost becomes unattributable, and one session's `git add -A` commits the
+other's half-finished work. Neither failure announces itself — you find out at the retrospective when
+the numbers are null.
+
+## How to use it
+
+```
+aidlc claim my-thing
+aidlc release my-thing
+```
+
+Claims live in `<git-common-dir>/aidlc/claims/`, not in the instance folder, so they are shared
+across worktrees of the same repository. A claim carries `claimed_at`, `renewed_at`, the session id,
+and the `worktree_path` it was taken from. It goes **stale** after `claim_timeout_minutes` (default
+60, set in `.aidlc/config.yaml`) — a long conversation will outlive its own claim, and re-claiming
+renews 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,
+plus a claim that has since gone stale, produces a gate failure that names two identities and blames
+the wrong one. Re-claim rather than reaching for `--override`.
+
+For concurrent work, use a worktree:
+
+```
+git worktree add -b feat/20260907-my-thing ../aidlc-my-thing main
+aidlc start quick-feature --name my-thing --worktree
+```
+
+The `--worktree` flag does this for you, including the branch-prefix convention (`fix/` for bugfix,
+`chore/` for micro-task and spike, `feat/` otherwise). When another live session holds a claim, the
+entry-point skill offers exactly three options — separate worktree, stop, or continue with no code
+changes — and takes none of them without being told.
+
+The hook declarations are tracked, but their capture-shim target is machine-local and gitignored.
+`aidlc start --worktree` now regenerates that shim in the new checkout before returning,
+using the same helper as `aidlc doctor`; a real worktree test keeps the raw, unarmed Git path as its
+negative control. If you create the worktree with `git worktree add` yourself, run `aidlc doctor`
+inside it before starting the agent session.
+
+## Where the code lives
+
+- `packages/cli/src/concurrency` — the claim store, staleness logic, and worktree helpers.
+  `claim-store.ts` is the single place a claim is written or read.
+- `packages/cli/src/state` — instance folders, `phase-<name>.yaml`, and the append-only
+  `transitions.log`.
+- `packages/cli/src/commands/claim.ts` — the `claim` and `release` commands, which also write the
+  session intervals that cost attribution later reads.
+- `packages/cli/src/commands/transition.ts` — `getActorIdentity`, the function that decides whose
+  turn it is. Its docblock records both 2026-09-01 reproductions where comparing a Unix username
+  against an `agent-<uuid>` session id blocked the one session entitled to proceed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rasensio/aidlc-content",
-  "version": "1.49.0",
+  "version": "1.51.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -22,6 +22,7 @@
     "tutorials/",
     "howto/",
     "resources/",
+    "docs/",
     "glossary.yaml"
   ],
   "engines": {

package/skills/00-overview.md

@@ -133,7 +133,7 @@ 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`
-- Load context relevant to the current phase; avoid re-reading unchanged files
+- Why AIDLC works as it does: `aidlc explain` lists topics, `aidlc explain <topic>` prints one
 
 ### The always-read rule
 

package/skills/04-roadmap.md

@@ -197,7 +197,7 @@ When the user asks for a worktree ("create a new worktree for roadmap `<file>`")
    ```
    For Codex, swap `claude` for `codex`. If the user names a session manager, give them the worktree path to point it at.
 
-When the instance completes, the `roadmap-done` lifecycle action moves the item to `done/` on its own — do not do it by hand, and do not remove that action to do it manually.
+When the instance completes, the `roadmap-done` lifecycle action moves every item whose `promoted_to` names it to `done/` on its own, and says how many it moved — do not do it by hand, and do not remove that action to do it manually.
 
 ## Drop
 

package/skills/40-implementation.md

@@ -42,16 +42,17 @@ Then the source files that task touches. See **The context rule** (`.aidlc/resou
 
 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 the always-read guidance layers from `.aidlc/guidance/index.yaml` — see **The always-read rule** (`.aidlc/resources/rules/always-read.md`) 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 (unattended, `AIDLC_UNATTENDED=1`: each is a hard stop except reverting this session's own changes, per `.aidlc/resources/rules/unattended.md`):
+3. **Check that the planning artifacts agree.** Before the first task, run `aidlc cross-check <instance>` and show the user the list. It reads `requirements.md`, `design.md` and `tasks.md` side by side and prints one line per gap — a criterion no task cites, a task citing no criterion, a criterion design never mentions — each naming both artifacts and the ID. It is a report: it writes nothing and never blocks, and acting on a gap is the user's call. A gap in `tasks.md` is fixed in place, since its phase is still open here; a gap in a completed `requirements.md` or `design.md` is fixed through an amendment (**Amending a Completed Phase**, in the requirements skill), never by editing it silently. Unattended (`AIDLC_UNATTENDED=1`): record the list in `code-complete.md` and carry on.
+4. **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.
+5. **Write code.** Follow the design interfaces. Match existing code style (naming, formatting, error handling patterns).
+6. **Handle sensitive operations.** Before executing any of the following, describe the action and wait for explicit user confirmation (unattended, `AIDLC_UNATTENDED=1`: each is a hard stop except reverting this session's own changes, per `.aidlc/resources/rules/unattended.md`):
    - File deletions or destructive operations
    - Infrastructure changes (provisioning, configuration)
    - Permission or access control modifications
    - Credential or secret handling
-6. **Commit incrementally.** Produce working code at each step; avoid large uncommittable diffs.
-7. **Update the knowledge graph.** After modifying code, record what changed with `aidlc knowledge add` / `relate` / `update`: new or restructured modules, decisions taken, debt introduced or paid down. Keep the graph in sync with the code you just changed.
-8. **Update state.** As implementation artifacts are produced, mark them in `phase-implementation.yaml`.
+7. **Commit incrementally.** Produce working code at each step; avoid large uncommittable diffs.
+8. **Update the knowledge graph.** After modifying code, record what changed with `aidlc knowledge add` / `relate` / `update`: new or restructured modules, decisions taken, debt introduced or paid down. Keep the graph in sync with the code you just changed.
+9. **Update state.** As implementation artifacts are produced, mark them in `phase-implementation.yaml`.
 
 ## Exit Criteria
 

package/skills/84-autopilot.md

@@ -35,7 +35,8 @@ The CLI does the work. This skill starts it and says how to watch and stop it. D
 
 - Takes items in `aidlc roadmap next` order. Builds at most two at once, and never more than the count asked for.
 - Parks an item (moves it to `hold/` with a reason) when its agent stops short, when CI fails twice, or when it passes the cost cap.
-- Halts the merge queue when a merge or release step fails, and never retries it. A half-done release is for a person — `aidlc autopilot status` shows the error.
+- Before each merge, brings the item's branch up to date with main and waits for CI on the new head. A conflict with main goes back to the item's agent, twice at most, then the item is parked. A pull request someone merged by hand is dropped from tracking.
+- Halts the merge queue when a step fails. Running `aidlc autopilot run` again retries a failure that came before the merge; a failed release is for a person — `aidlc autopilot status` shows the error. `aidlc autopilot forget <instance>` stops tracking an item finished by hand.
 - Ends when the asked-for items are each released or parked, or, with `--all`, when nothing is ready and nothing is in flight.
 
 ## Exit Criteria