@rasensio/aidlc-content 1.80.0 → 1.82.0

package/docs/knowledge-graph.md

@@ -33,6 +33,17 @@ aidlc knowledge context --scope phase --phase design
 `discover` scans a codebase and seeds the graph — that is how a brownfield project starts. After that,
 record findings as you make them rather than at the end.
 
+**Re-running `discover` only fills gaps.** It replaces a description only when it is empty or still
+one that discovery itself wrote, and never changes an entity's name, source, author, confidence or
+tags. A module it finds is written into the existing entry with the same name or source path, not
+added under a second id; when two entries match, it writes nothing for that module and prints a
+warning naming them. A fact that did not change is not rewritten, so a re-run on an unchanged repo
+leaves an empty diff. The reason is this repo's own graph: a second run replaced a seven-line
+hand-written description with "Module at packages/cli/src/core/ (has index)", added 14 thin copies of
+modules already written up under other ids, and touched about 100 files. Discovery and
+`knowledge add` now take separate paths for this reason — a person adding a description means to
+replace the old one, and discovery never does.
+
 To add several entities at once, pipe YAML documents (separated by `---`) to
 `aidlc knowledge add --stdin`. A `tags:` string there means what `--tags` means: comma-separated.
 **Every document is checked before any is written**, and a run that fails writes nothing. That rule

package/docs/roadmap.md

@@ -129,6 +129,18 @@ nothing — when the project does not declare `priority`, when the item is not i
 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.
 
+**Keeping autopilot off an item** is its `run:` line: `run: autopilot` or `run: attended`.
+Autopilot picks with `aidlc roadmap next --autopilot`, which leaves every `attended` item out of the
+order and lists it under `skipped` with the reason `attended`; autopilot says
+`left for a person (run: attended): <items>` and builds the next autopilot item instead. A plain
+`aidlc roadmap next` still offers attended items in rank order, because a person can pick them — so
+the backlog keeps one order for both. An item with **no** `run:` is one autopilot may build, so a repo
+that never sets the field sees no change. A value that is neither — `run: yes`, a typo — keeps
+autopilot **off** the item (skipped as `bad-run`), and `roadmap next` warns about it in either mode.
+Declare `run` in `roadmap.item_fields` and triage proposes the value with the rank, asking for both
+in one question. With only attended items ready, `aidlc autopilot run --all` finds nothing ready and
+ends.
+
 **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
@@ -165,7 +177,8 @@ resumes.
 
 Each item goes through these steps:
 
-1. **Pick.** `aidlc roadmap next` names the next ready backlog item.
+1. **Pick.** `aidlc roadmap next --autopilot` names the next ready backlog item, leaving items
+   marked `run: attended` for a person.
 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` and `AIDLC_PAUSE_AFTER`
    set to the phases it must stop after. The agent follows the unattended rule and stops at a review

package/package.json

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

package/skills/04-roadmap.md

@@ -145,7 +145,7 @@ List each status directory, reading **only frontmatter and the containing direct
 
 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.
 
-**`aidlc roadmap next`** is the deterministic answer to "what 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 order and what was skipped and why; `--json` for scripts). It is read-only and never promotes — promoting stays a person's decision. `priority` is an ordinary extension field a project declares in `roadmap.item_fields`; a rank, where 1 is first. Where it is declared, `--explain` also lists every unranked backlog item, so one sitting last is visible rather than silently last. **`aidlc roadmap rank <item> <n>`** is the one way to change a rank: it puts the item at `n` and renumbers every ranked backlog item 1…k, so ranks stay unique and gap-free.
+**`aidlc roadmap next`** is the deterministic answer to "what 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 order and what was skipped and why; `--json` for scripts). It is read-only and never promotes — promoting stays a person's decision. `priority` is an ordinary extension field a project declares in `roadmap.item_fields`; a rank, where 1 is first. Where it is declared, `--explain` also lists every unranked backlog item, so one sitting last is visible rather than silently last. `--autopilot` picks as autopilot does: it leaves out items marked `run: attended`, and items whose `run` is neither value, listing each as skipped. **`aidlc roadmap rank <item> <n>`** is the one way to change a rank: it puts the item at `n` and renumbers every ranked backlog item 1…k, so ranks stay unique and gap-free.
 
 **Seeing the roadmap.** When someone asks to see the roadmap or its dependencies, run **`aidlc roadmap view`** rather than drawing a graph. It writes one self-contained HTML page — a kanban board of every item by status, and a zoomable map of the `depends_on` chains with blocked items and unknown ids marked — and opens it in the browser (`--no-open` only writes it; `--out <path>` writes it elsewhere). The page lives in the git common dir, outside every working tree, so it is never committed and nothing rebuilds it on a move; run the command again for a fresh one. `aidlc roadmap graph` is the same command.
 
@@ -175,6 +175,16 @@ When the project declares `priority` in `roadmap.item_fields`, moving an item in
 
 The proposed rank is never written without the person's answer: a rank nobody looked at reads exactly like a decided one. There is no scoring formula; the person decides and the flow only proposes. Projects that do not declare `priority` triage exactly as before, with no rank asked for.
 
+### Run mode on the way in
+
+When the project declares `run` in `roadmap.item_fields`, the same moment also settles whether autopilot may build the item alone: `run: autopilot` or `run: attended`. Autopilot picks with `aidlc roadmap next --autopilot`, which leaves `attended` items for a person; a person's `aidlc roadmap next` still offers them.
+
+1. **Propose** `autopilot` or `attended` with a one-line reason, alongside the proposed rank. `attended` fits an item that changes what a gate trusts, or needs a decision before any code; `autopilot` fits hours of work with a clear reproduction and a clear fix.
+2. Ask it **in the same question as the rank** — one answer gives both, for example "rank 3, attended". Never a second question.
+3. Write the answer to the item's `run:` line as text, adding the line after `priority:` when it is missing. Edit only that line; nothing else in the frontmatter changes.
+
+Never write `run:` without the person's answer, for the reason the rank is never written without one. An item with no `run:` is one autopilot may build, so leaving it unset is a choice, not a neutral default. Projects that do not declare `run` triage exactly as before.
+
 ## Promote
 
 Promotion is where the roadmap meets the lifecycle:

package/skills/84-autopilot.md

@@ -47,7 +47,7 @@ The CLI does the work. This skill starts it and says how to watch and stop it. D
 
 ## What the run does on its own
 
-- Takes items in `aidlc roadmap next` order. Builds at most two at once, and never more than the count asked for.
+- Takes items in `aidlc roadmap next --autopilot` order, which leaves out items marked `run: attended`. 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 of a stop it was told to reach, when CI fails twice, or when it passes the cost cap. An item waiting for a person is never parked, and holds no build slot, so the run goes on starting others.
 - An agent that loses the network exits, and is parked. Sleep cuts the network, so a run on a laptop needs `aidlc autopilot pause` first: it freezes the run and its agents where they are, and `aidlc autopilot resume` carries on.
 - 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.