@rasensio/aidlc-content 1.47.0 → 1.49.0

package/package.json

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

package/skills/04-roadmap.md

@@ -143,7 +143,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.
+**`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.
 
 The frontmatter-only rule holds for browsing, which is a list and must stay cheap enough to run over the whole roadmap. **Triage** below is the one flow allowed into the body, and only as far as the executive summary.
 
@@ -159,6 +159,18 @@ Triage is the one flow that reads into the body, and it reads **the executive su
 
 Read `.aidlc/context/constitution.md` when it exists and apply the constitution rule in `.aidlc/resources/rules/constitution.md`: an item that crosses a prohibition is the clearest `hold/` there is, and naming the prohibition turns "not for us" into a reason the submitter can read.
 
+### Ranking on the way in
+
+When the project declares `priority` in `roadmap.item_fields`, moving an item into `backlog/` includes giving it a rank — otherwise it sorts last, and the order `aidlc roadmap next` and autopilot follow becomes the order nobody chose.
+
+1. Read the current order with `aidlc roadmap next --explain`.
+2. **Propose** a rank with a one-line reason drawn from the executive summaries — this item against its neighbours, not a score.
+3. Show where it lands: `aidlc roadmap rank <item> <n> --dry-run` prints the whole order with the item marked.
+4. Ask once: accept rank `n`, or give another number. One answer settles it.
+5. Run `aidlc roadmap rank <item> <answer>` without `--dry-run`. Never edit `priority:` by hand — the command is what keeps ranks unique and gap-free.
+
+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.
+
 ## Promote
 
 Promotion is where the roadmap meets the lifecycle:

package/skills/20-requirements.md

@@ -27,6 +27,7 @@ Read only:
   ideation artifact as input
 - the always-read guidance layers named in `.aidlc/guidance/index.yaml` (see **The always-read rule** (`.aidlc/resources/rules/always-read.md`))
 - `.aidlc/context/constitution.md`, when it exists
+- the spec corpus files in `.aidlc/specs/` for the capabilities the change touches — `aidlc spec show` lists them
 
 Not the ideation *conversation* — the artifact is what it was written for.
 See **The context rule** (`.aidlc/resources/rules/context.md`).
@@ -55,7 +56,8 @@ See **The context rule** (`.aidlc/resources/rules/context.md`).
      A criterion that is not a behaviour — a performance budget, a docs change, a file that must exist — stays a plain sentence. A plain criterion is valid: the gate checks the ID, never the shape.
 4. **Set scope boundaries.** Explicitly state what is NOT included.
 5. **Non-functional requirements.** Address performance, security, accessibility, and compatibility where relevant.
-6. **For open decisions**: When a decision would change what `requirements.md` says, ask it through the **Question Protocol** (`.aidlc/resources/rules/question-protocol.md`) — questions for this phase go to `.aidlc/state/<instance>/requirements-questions.md`. Prefer drafting `requirements.md` early with the unresolved points marked as explicit decision blocks: users decide better reacting to a concrete draft than answering abstract questions. Fold each answer into the draft and leave the question file as the record of what was decided and why.
+6. **Write the change as a spec delta.** `.aidlc/specs/<capability>.md` says what the system does today. Read the files your change touches, then end `requirements.md` with a `## Spec delta` section: one `### ADDED <capability>: <requirement name>`, `### MODIFIED …` or `### REMOVED …` block per change. ADDED and MODIFIED blocks hold the requirement's full new text, written as what the system does. MODIFIED and REMOVED blocks start with `Base: <revision>`, copied from `aidlc spec show <capability>`. Capabilities are lowercase kebab-case names; a new one is created by its first ADDED block. Run `aidlc spec fold <instance> --dry-run` before the phase closes — it reports every error and conflict, and the same fold runs at completion, where a conflict blocks it. Skip the section when the change alters no lasting behaviour, as most bugfixes do not.
+7. **For open decisions**: When a decision would change what `requirements.md` says, ask it through the **Question Protocol** (`.aidlc/resources/rules/question-protocol.md`) — questions for this phase go to `.aidlc/state/<instance>/requirements-questions.md`. Prefer drafting `requirements.md` early with the unresolved points marked as explicit decision blocks: users decide better reacting to a concrete draft than answering abstract questions. Fold each answer into the draft and leave the question file as the record of what was decided and why.
 
 ## Bugfix Reproduction (bugfix template)
 

package/skills/30-design.md

@@ -26,6 +26,9 @@ Read only:
 - the always-read guidance layers named in `.aidlc/guidance/index.yaml` (see **The always-read rule** (`.aidlc/resources/rules/always-read.md`))
 - `.aidlc/context/architecture.md` and `style-guide.md`
 - `.aidlc/context/constitution.md`, when it exists
+- the spec corpus files in `.aidlc/specs/` named by `requirements.md`'s `## Spec delta` section —
+  the current spec, which is what the design is built against. Not a past instance's
+  `requirements.md`: it describes a change, and later instances may have changed it again.
 
 The seams the requirements touch are then read from the *source*, as step 3 of the
 instructions says — a handful of files, not a survey, and not the previous phase's