Skip to content

v1.50.0 ·

The documents were never read together

The problem

aidlc review reads one artifact at a time. Nothing reads requirements, design and tasks side by side, so a criterion that design forgot, or a task nobody asked for, passes every review and is found later in the code.

How it could be solved

Three decisions, each about making a check people will believe without making one they must pass.

The first was who does the comparing. An agent asked to read three documents and list what disagrees gives a different list every run, and nothing can test it. So it is a plain command, and it compares only references: which acceptance criteria each task names, and which ones the design mentions. That is also what it gives up. It cannot tell whether a task really does what its criterion asks. The original request also wanted the design checked against the project's charter; that was dropped, because it is a judgment, not a lookup.

The second was how to read the files. The command uses the same code that the lifecycle's pass-or-fail checks use, so the two can never disagree about what a file says. The price is strictness. Most "no task names this" results in this repo were criteria written next to a task but not in its list of criteria, which those checks cannot see either. They stay as gaps, but each line now says where the stray mention is. The design is read a little more loosely, so a range of criteria counts every one inside it. The first version missed the most common way of writing a range; running it over the real files caught that.

The third was what it may do with a gap. Nothing but show it. Every new pass-or-fail check here is a cost that all later work pays, so nothing that decides whether work moves on reads this output. The trade is that nothing forces a fix, and a report that can be ignored is only worth running if it is mostly right. That is why its output was counted across all 86 pieces of work in the repo before release. The largest group, tasks that name no criterion, is mostly housekeeping, and it was kept because it is true.

How AIDLC solves it

cross-artifact-check

aidlc cross-check <instance>: before code is written, it reads an instance's requirements.md, design.md and tasks.md side by side and prints one line per gap, naming both artifacts and the criterion or task — a criterion no task cites, a task citing no criterion or a retired one, a criterion design never mentions. It writes nothing, changes no phase, exits 0 whatever it finds, and no gate runs it. The implementation skill offers it before the first task.

Minor, not patch: a new top-level command and a new step in the implementation skill. Nothing a user had changes; no gate, transition or state format is touched.

Changes

  • packages/cli/src/crosscheck/analyze.ts — the comparison (new).
  • packages/cli/src/commands/cross-check.ts — the command (new); registered in cli.ts.
  • packages/cli/src/menu/roster.ts — cross-check excluded from the menu, with its reason.
  • packages/content/skills/40-implementation.md — new step 3; later steps renumbered 4–9.
  • Regenerated skills across all adapters (version marker only, apart from the implementation skill), CLAUDE.md/AGENTS.md knowledge block, and packages/website/src/data/cli-reference.json.
  • Tests: crosscheck-analyze.test.ts, cross-check-cli.test.ts, cross-check-offered.test.ts; pins updated in cli-entrypoint.test.ts, the website's cli-reference.test.ts, and packages/content/test/unattended-rule.test.ts (now finds a step by name, not number).
  • Spec delta: ADDED cross-check: Read-only cross-artifact check — folds into a new .aidlc/specs/cross-check.md at completion (spec fold --dry-run is clean).

roadmap-done-one-item

When several roadmap items are promoted to one piece of work, finishing that work now files all of them, not just the first. The completion output names each item and says how many were moved. If one item cannot be moved, the others still are, and the output says which moved and which did not. aidlc doctor finds and files every item a finished piece of work left behind, including ones stranded before this fix.

autopilot-merge-lane-stalls-on-conflicts

Autopilot finishes a multi-item run without a person.

  • Knowledge records no longer conflict. A new knowledge entity or relationship is written to its own file (.aidlc/knowledge/decisions/<id>.yaml) instead of being appended to the shared per-type file. Two branches that each record a decision now merge cleanly. Existing records stay where they are and are still read.
  • Up to date before merging. Autopilot merges origin/main into the queue head's branch in its worktree, pushes, and waits for CI on the new head; it merges with --match-head-commit.
  • Conflicts are handed back. A conflict, or a conflicting PR with no checks, relaunches the item's agent to resolve it (twice at most), then parks it. A PR merged by hand is dropped.
  • Resume and forget. aidlc autopilot run retries failures from before the merge. aidlc autopilot forget <instance> stops tracking an item finished by hand.
  • Close step marks the deployment record complete whatever its status.

Minor, not patch: a new subcommand (autopilot forget) and a new on-disk layout for new knowledge records. Nothing a user has changes meaning: a repository with only the per-type files reads and updates exactly as before.

Changes

  • packages/cli/src/knowledge/types.ts, yaml-source.ts, compact.ts — record files.
  • packages/cli/src/autopilot/driver.ts, state.ts, run.ts — merge lane, resume, forget, close.
  • packages/cli/src/commands/autopilot.ts — forget; run prints what it resumed.
  • packages/content/skills/84-autopilot.md and its generated copies — what the run does on its own.
  • docs/knowledge-graph.md, docs/roadmap.md, packages/website/src/data/cli-reference.json.
  • .aidlc/knowledge/decisions/, .aidlc/knowledge/relationships/ — the first two record files and one edge, written by the new code.
  • Tests: knowledge-record-files.test.ts (new); merge-lane cases in autopilot-driver.test.ts and autopilot-run.test.ts; adapted knowledge-engine, cli-knowledge, knowledge-add-corrupts-tags.