@rasensio/aidlc-content 1.30.0 → 1.31.0

package/package.json

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

package/resources/skills/roadmap-item/SKILL.md

@@ -51,6 +51,7 @@ promoted_to: null
 depends_on: []
 history:
   - { status: inbox, at: YYYY-MM-DD }
+{{project_item_fields}}
 ---
 ```
 
@@ -69,8 +70,7 @@ Rules for those fields:
   written, not who asked for it.
 - `promoted_to` stays `null`. Leave `depends_on` empty — you cannot know the identifiers of
   other items in the project.
-- Do not add any other field, and do not add a `status` field. Status is recorded by which
-  folder the file sits in, not inside the file.
+{{project_item_fields_rule}}
 
 Then the body, with these five headings and nothing else at this level:
 

package/skills/04-roadmap.md

@@ -63,6 +63,30 @@ history:
 
 Bodies are otherwise free-form. Items authored through the portable skill carry four further headings — Problem, Who it's for, What success looks like, Out of scope — which is a useful shape, not a validated one.
 
+### Project-Declared Extension Fields
+
+A project that outgrows those eight keys declares its own in `.aidlc/config.yaml`, and everything that writes an item then emits them:
+
+```yaml
+roadmap:
+  item_fields:
+    - name: requirements
+      required: true
+      default: []
+```
+
+`name` must be lowercase letters, digits and underscores, and may not shadow a stock key. `status` is refused by name — status is the directory, and a second representation of it is the one extension the layout can never allow. `required` defaults to `true`; `default` defaults to `null`.
+
+The worked example is real. `fieldmodel-apps` keeps requirements traceability as data: `docs/requirements-traceability.md` holds the requirement IDs, every item declares which ones it delivers in `requirements: [...]`, and `scripts/check-roadmap-requirements.mjs` computes coverage as a set difference. It requires the key even when empty, because a set difference over an optional key silently under-reports. Before this existed, the portable `roadmap-item` skill said *"Do not add any other field"* while that check demanded one — two individually-correct rules that no agent could satisfy at once, in a framework-owned file the project was not allowed to edit.
+
+Declaring a field changes three things and nothing else:
+
+- The portable `roadmap-item` skill's template carries the field, and its "add no other field" rule becomes bounded rather than absolute. `aidlc update` re-emits it.
+- `aidlc roadmap import` and the `roadmap-layout` doctor migration write the declared default into items they create. Triage moves and `roadmap-done` already preserve the field, because they edit frontmatter as text rather than re-serializing it.
+- `aidlc doctor` reports items missing a required declared field and offers to backfill the declared default.
+
+**The framework checks presence and shape, never contents.** Shape is taken from the declared `default` — a list default means a list value, a scalar means a scalar — and a `default: null` declares no shape, so only presence is checked. There is no config key that could express a rule about what goes *in* a field, and that absence is deliberate: `requirements: [not-a-real-id]` is the project's own script's business. A wrong-shaped value is reported and never rewritten, because only the person who wrote it knows what they meant.
+
 ### Every Item Opens With an Executive Summary
 
 The first section of the body, before anything else, is `## Executive Summary` — six labelled lines, nothing more: