Skip to content

v1.48.0 ·

The changes were written down; the system never was

The problem

Each instance's requirements.md describes a change. After 80 instances nobody can say what the system does today without replaying all of them, so new work designs against stale artifacts or against nothing.

How it could be solved

The first choice was how to tell that a change is out of date. Every edit or removal of an existing requirement names the version it was written against: a short fingerprint computed from the requirement's words. Changing the spacing leaves the fingerprint alone; changing a word does not. Comparing a quoted copy of the old text was rejected as too fragile, and trusting a note of who changed it last would miss a hand edit. The price is one line the author copies in. A mismatch is never merged for them: a person rewrites the change against the current text.

The second was where the change lives and when it lands. It is a section of the instance's own requirements document, not a separate set of files, because that document is already what review and testing read. It is folded in as the instance finishes, before it is recorded as done. Steps that run after completion cannot refuse anything, and a conflict has to be able to hold completion back.

The third was what to leave out. No new check was added at any earlier step, because every check is paid again by every future instance. An instance that changes no requirement pays nothing, and an author who wants to know sooner can run a preview that writes nothing. The description also starts empty. Rebuilding it from every past instance was ruled out, so for now it only knows what has changed since. A rename was left out too, since removing one requirement and adding another says the same thing.

How AIDLC solves it

living-spec-corpus

A standing description of what the system does, kept current by finished instances. A requirements author writes a ## Spec delta — ADDED, MODIFIED and REMOVED blocks — against .aidlc/specs/<capability>.md. When the instance completes, aidlc transition folds the delta in and files it under .aidlc/specs/archive/. If another instance changed the same requirement first, the fold stops and completion waits; nothing is overwritten.

Minor, not patch: a new command (aidlc spec), a new section the requirements skill asks for, and a new step at completion. Nothing a user had changes: an instance with no delta — every instance finished so far — completes exactly as before.

Changes

  • packages/cli/src/spec/ — corpus parser, delta parser, fold (new).
  • packages/cli/src/commands/spec.ts — aidlc spec show [capability], aidlc spec fold <instance> [--dry-run], both with --json (new).
  • packages/cli/src/commands/transition.ts, core/types.ts, core/next-steps.ts — the fold at the completion moment and its spec-fold blocker.
  • packages/cli/src/menu/roster.ts — spec excluded from the menu, with its reason.
  • packages/content/skills/20-requirements.md, 30-design.md — read and write the corpus.
  • Regenerated skills across all adapters, CLAUDE.md/AGENTS.md knowledge block, and packages/website/src/data/cli-reference.json.
  • Tests: spec-fold.test.ts, spec-cli.test.ts, spec-corpus-skills.test.ts; pins updated in cli-entrypoint.test.ts and the website's cli-reference.test.ts.

no-dependency-audit-in-ci

  • .github/workflows/ci.yml — new audit job, beside gate, on every PR to main and every push to main. Reports dependency advisories; never blocks on one; goes red only when the audit itself cannot run.
  • scripts/audit-report.mjs — the wrapper the job runs.
  • Tests: packages/website/src/test/audit-report.test.ts (new), packages/website/src/test/ci-workflow.test.ts (extended).

No runtime code, no published package content, no dependency change. Nothing in release.yml or scripts/release.sh changes. A version bump is optional: the CLI and content packages are byte-identical, so this can ride the next batch release, or none.