@rasensio/aidlc-content 1.29.0 → 1.30.0

package/capabilities/claude-code.yaml

@@ -1,4 +1,18 @@
 platform: claude-code
+questions:
+  mechanism: AskUserQuestion
+  directive: >-
+    Render each question spec as one question in an AskUserQuestion call. The
+    interrogative sentence is the question; each option's label is its choice and
+    its consequence is the description; mark the recommendation by putting it
+    first and appending "(Recommended)" to its label. At most four options per
+    question and at least two — a spec with more must be split or narrowed. Never
+    add an explicit "Other" option: the tool supplies one, and a second is a dead
+    choice the user has to rule out. The header is a chip of at most 12
+    characters, so it names the decision, not the question. Put "Why it matters",
+    the citations and "If you say nothing" in the question file and name its path
+    in one line of the message that carries the call — they do not fit an option
+    description, and truncating them is what made questions unanswerable.
 capabilities:
   plan-mode:
     phases: [ideation, requirements, design]

package/capabilities/codex.yaml

@@ -1,4 +1,14 @@
 platform: codex
+questions:
+  mechanism: request_user_input
+  directive: >-
+    Render each question spec through the structured user-input request when the
+    running Codex build exposes one — the interrogative as the prompt, one entry
+    per option carrying its consequence, the recommendation named as such. When it
+    is not available, fall back to numbered prose in the message and do not
+    pretend a picker exists. Either way the question file is written first and its
+    path named in one line, because a sandboxed turn can end before an answer
+    arrives and the file is what survives it.
 capabilities:
   code-generation:
     phases: [implementation, testing]

package/capabilities/copilot.yaml

@@ -1,4 +1,14 @@
 platform: copilot
+questions:
+  mechanism: null
+  directive: >-
+    Copilot Chat has no structured question prompt, so render each spec as
+    numbered prose in the message: the interrogative as a bold line, then the
+    options as a numbered list with the consequence on each, then the
+    recommendation and the no-answer outcome. Restart option numbering at 1 for
+    every question, whatever was numbered earlier in the message — a user
+    answering "3" must be answering the third option of that question. Ask the
+    user to reply with the option number or its label.
 capabilities:
   plan-mode:
     phases: [ideation, requirements, design]

package/capabilities/cursor.yaml

@@ -1,4 +1,14 @@
 platform: cursor
+questions:
+  mechanism: null
+  directive: >-
+    Cursor has no structured question prompt, so render each spec as numbered
+    prose in the chat: the interrogative as a bold line, then the options as a
+    numbered list with the consequence on each, then the recommendation and the
+    no-answer outcome. Restart option numbering at 1 for every question, whatever
+    was numbered earlier in the message. Name the question file by path so the
+    user can open it in the editor — Cursor puts the file a click away, which is
+    what makes the longer questions cheap to route there.
 capabilities:
   composer:
     phases: [design, implementation]

package/capabilities/kiro.yaml

@@ -1,4 +1,14 @@
 platform: kiro
+questions:
+  mechanism: null
+  directive: >-
+    Kiro has no structured question prompt, so render each spec as numbered prose
+    in the chat: the interrogative as a bold line, then the options as a numbered
+    list with the consequence on each, then the recommendation and the no-answer
+    outcome. Restart option numbering at 1 for every question, whatever was
+    numbered earlier in the message. The question file stays under `.aidlc/`, not
+    `.kiro/specs/` — a spec session is where the answer lands, not where the
+    question is recorded.
 capabilities:
   spec-driven-development:
     phases: [requirements, design, implementation]

package/capabilities/windsurf.yaml

@@ -1,4 +1,15 @@
 platform: windsurf
+questions:
+  mechanism: null
+  directive: >-
+    Windsurf has no structured question prompt, so render each spec as numbered
+    prose in Cascade: the interrogative as a bold line, then the options as a
+    numbered list with the consequence on each, then the recommendation and the
+    no-answer outcome. Restart option numbering at 1 for every question, whatever
+    was numbered earlier in the message. Windsurf's context window is the tightest
+    of the supported platforms, so route to the question file sooner here — keep
+    the rendered prompt to the interrogative, the option labels and the file path,
+    and leave the citations in the file.
 capabilities:
   cascade:
     phases: [implementation]

package/dist/capabilities.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../src/capabilities.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAKhD,wBAAgB,gBAAgB,IAAI,aAAa,EAAE,CAclD;AAED,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAE5E"}
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../src/capabilities.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,aAAa,EAAqB,MAAM,YAAY,CAAC;AAKnE,wBAAgB,gBAAgB,IAAI,aAAa,EAAE,CAqBlD;AAED,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAE5E"}

package/dist/capabilities.js

@@ -11,9 +11,15 @@ export function loadCapabilities() {
     return files.map(filename => {
         const raw = readFileSync(resolve(CAPABILITIES_DIR, filename), 'utf8');
         const parsed = parseYaml(raw);
+        // `questions` is carried through rather than folded into `capabilities`, so
+        // that a null `mechanism` stays distinguishable from a missing block: the
+        // first selects the numbered-prose fallback, the second is a capability file
+        // that forgot AC-7 and must fail the adapter tripwire.
+        const questions = parsed['questions'];
         return {
             platform: parsed['platform'] ?? '',
             capabilities: parsed['capabilities'] ?? {},
+            ...(questions ? { questions } : {}),
         };
     });
 }

package/dist/capabilities.js.map

@@ -1 +1 @@
-{"version":3,"file":"capabilities.js","sourceRoot":"","sources":["../src/capabilities.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACpD,OAAO,EAAE,KAAK,IAAI,SAAS,EAAE,MAAM,MAAM,CAAC;AAG1C,MAAM,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;AAC5E,MAAM,gBAAgB,GAAG,OAAO,CAAC,YAAY,EAAE,cAAc,CAAC,CAAC;AAE/D,MAAM,UAAU,gBAAgB;IAC9B,MAAM,KAAK,GAAG,WAAW,CAAC,gBAAgB,CAAC;SACxC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;SACtD,IAAI,EAAE,CAAC;IAEV,OAAO,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE;QAC1B,MAAM,GAAG,GAAG,YAAY,CAAC,OAAO,CAAC,gBAAgB,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,CAAC;QACtE,MAAM,MAAM,GAAG,SAAS,CAAC,GAAG,CAA4B,CAAC;QAEzD,OAAO;YACL,QAAQ,EAAG,MAAM,CAAC,UAAU,CAAY,IAAI,EAAE;YAC9C,YAAY,EAAG,MAAM,CAAC,cAAc,CAA6B,IAAI,EAAE;SACxE,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,QAAgB;IAC/C,OAAO,gBAAgB,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC;AAC/D,CAAC"}
+{"version":3,"file":"capabilities.js","sourceRoot":"","sources":["../src/capabilities.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACpD,OAAO,EAAE,KAAK,IAAI,SAAS,EAAE,MAAM,MAAM,CAAC;AAG1C,MAAM,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;AAC5E,MAAM,gBAAgB,GAAG,OAAO,CAAC,YAAY,EAAE,cAAc,CAAC,CAAC;AAE/D,MAAM,UAAU,gBAAgB;IAC9B,MAAM,KAAK,GAAG,WAAW,CAAC,gBAAgB,CAAC;SACxC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;SACtD,IAAI,EAAE,CAAC;IAEV,OAAO,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE;QAC1B,MAAM,GAAG,GAAG,YAAY,CAAC,OAAO,CAAC,gBAAgB,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,CAAC;QACtE,MAAM,MAAM,GAAG,SAAS,CAAC,GAAG,CAA4B,CAAC;QAEzD,4EAA4E;QAC5E,0EAA0E;QAC1E,6EAA6E;QAC7E,uDAAuD;QACvD,MAAM,SAAS,GAAG,MAAM,CAAC,WAAW,CAAkC,CAAC;QAEvE,OAAO;YACL,QAAQ,EAAG,MAAM,CAAC,UAAU,CAAY,IAAI,EAAE;YAC9C,YAAY,EAAG,MAAM,CAAC,cAAc,CAA6B,IAAI,EAAE;YACvE,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACpC,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,QAAgB;IAC/C,OAAO,gBAAgB,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC;AAC/D,CAAC"}

package/dist/index.d.ts

@@ -5,5 +5,5 @@ export { loadGlossary, getGlossaryTerm } from './glossary.js';
 export { loadCapabilities, getCapabilityMap } from './capabilities.js';
 export { loadPhases, getPhase } from './phases.js';
 export { loadTutorials, getTutorial, getSeries, parseTutorialSource } from './tutorials.js';
-export type { Skill, WorkflowTemplate, GuidanceLayer, GlossaryTerm, CapabilityMap, PhaseDefinition, CodeSample, ContentReference, TutorialStep, Tutorial, WidgetKind, WidgetReference } from './types.js';
+export type { Skill, WorkflowTemplate, GuidanceLayer, GlossaryTerm, CapabilityMap, QuestionRendering, PhaseDefinition, CodeSample, ContentReference, TutorialStep, Tutorial, WidgetKind, WidgetReference } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC5D,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACvE,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,SAAS,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAC5F,YAAY,EAAE,KAAK,EAAE,gBAAgB,EAAE,aAAa,EAAE,YAAY,EAAE,aAAa,EAAE,eAAe,EAAE,UAAU,EAAE,gBAAgB,EAAE,YAAY,EAAE,QAAQ,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC5D,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACvE,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,SAAS,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAC5F,YAAY,EAAE,KAAK,EAAE,gBAAgB,EAAE,aAAa,EAAE,YAAY,EAAE,aAAa,EAAE,iBAAiB,EAAE,eAAe,EAAE,UAAU,EAAE,gBAAgB,EAAE,YAAY,EAAE,QAAQ,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC"}

package/dist/types.d.ts

@@ -45,9 +45,29 @@ export interface GlossaryTerm {
      */
     not?: string;
 }
+/**
+ * How one platform renders a question spec (explanatory-questions/AC-7).
+ *
+ * Deliberately a top-level sibling of `capabilities`, not an entry inside it:
+ * `resolveActivation` returns exactly one activation string per phase, and
+ * `claude-code`, `copilot` and `kiro` already occupy `requirements` and `design`
+ * — the phases questions get asked in. A second entry for the same phase would
+ * silently lose to the first.
+ */
+export interface QuestionRendering {
+    /**
+     * The platform's native question mechanism, or `null` when it has none.
+     * Null selects the numbered-prose fallback (explanatory-questions/AC-10).
+     */
+    mechanism: string | null;
+    /** What the agent must do to render a spec on this platform. */
+    directive: string;
+}
 export interface CapabilityMap {
     platform: string;
     capabilities: Record<string, unknown>;
+    /** Absent only for a platform whose capability file predates AC-7. */
+    questions?: QuestionRendering;
 }
 export interface PhaseDefinition {
     name: string;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,KAAK;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3D,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC9B;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,YAAY;IAC3B,4EAA4E;IAC5E,IAAI,EAAE,MAAM,CAAC;IACb,8EAA8E;IAC9E,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;;;;OAQG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACvC;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,OAAO,GAAG,UAAU,GAAG,OAAO,GAAG,UAAU,CAAC;IACxD,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;CACb;AAED,wEAAwE;AACxE,MAAM,MAAM,UAAU,GAAG,YAAY,GAAG,YAAY,GAAG,YAAY,CAAC;AAEpE;;;;;;;;GAQG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,UAAU,CAAC;IACjB,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,iBAAiB,EAAE,gBAAgB,EAAE,CAAC;IACtC,OAAO,EAAE,eAAe,EAAE,CAAC;CAC5B;AAED,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0EAA0E;IAC1E,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,KAAK;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3D,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC9B;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,YAAY;IAC3B,4EAA4E;IAC5E,IAAI,EAAE,MAAM,CAAC;IACb,8EAA8E;IAC9E,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;;;;OAQG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,gEAAgE;IAChE,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,sEAAsE;IACtE,SAAS,CAAC,EAAE,iBAAiB,CAAC;CAC/B;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,OAAO,GAAG,UAAU,GAAG,OAAO,GAAG,UAAU,CAAC;IACxD,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;CACb;AAED,wEAAwE;AACxE,MAAM,MAAM,UAAU,GAAG,YAAY,GAAG,YAAY,GAAG,YAAY,CAAC;AAEpE;;;;;;;;GAQG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,UAAU,CAAC;IACjB,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,iBAAiB,EAAE,gBAAgB,EAAE,CAAC;IACtC,OAAO,EAAE,eAAe,EAAE,CAAC;CAC5B;AAED,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0EAA0E;IAC1E,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB"}

package/package.json

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

package/skills/00-overview.md

@@ -156,14 +156,42 @@ On each lifecycle event — `on-instance-start`, `on-phase-enter`, `on-phase-exi
 5. If an action fails and it is `blocking: true`, stop and report the failure to the user before continuing the lifecycle. If `blocking: false`, report and continue.
 6. Report every action you ran and its outcome — never run configured automation silently.
 
-## User Input Protocol (Inbox)
+## Question Protocol
 
-When a phase needs substantial input from the user — open decisions, structured requirements, extensive details — write an input file to `.aidlc/inbox/` instead of asking many sequential chat questions or scattering files in ad-hoc locations (`temp/`, project root):
+Ask the user something when **different answers would change an artifact, a design decision, or scope** — the trigger is consequence, not volume. A question whose answers change nothing is not asked. A question that an answer already given in this instance resolves is not re-asked: name that answer and ask the narrow follow-up instead.
 
-1. Name the file `<instance>-<topic>.md` (e.g. `local-knowledge-graph-open-decisions.md`).
-2. Give each question its own section: plain-language background first (assume the user has not read the underlying spec), then the options as `- [ ]` checkboxes with trade-offs spelled out. Mark your recommendation.
-3. Tell the user the file path and wait for their edits — do not proceed on unanswered questions.
-4. When the user has answered, fold the outcomes into the phase artifact and state records. The inbox file is scratch input, not an artifact — offer to delete it once its content has landed.
+### The spec
+
+Every question is written first as a **spec** — platform-neutral, and never printed into the conversation. It carries, at minimum:
+
+- **The decision**, as one interrogative sentence.
+- **Why it matters** — what it blocks, and what goes wrong if it is guessed.
+- **What the repo already says** — cited as `path:line`, or `path` when the whole file is the point. "Nothing found" is a valid citation; saying nothing is not.
+- **Two to four options**, each with its consequence spelled out.
+- **A recommendation**, marked as such — exactly one, with the reason it wins.
+- **If you say nothing** — the outcome of no answer, so that not answering is a choice rather than a stall.
+
+Expand every identifier on first use, writing the thing out with the tag in parentheses — "the citation rule (AC-1)", not a bare `AC-1`, `FR3` or `unit-4`. A bare tag assumes the reader carries a mapping they do not have.
+
+### Rendering the spec
+
+The spec is input to a rendering, never output. How to render it on this platform is in `.aidlc/resources/questions/rendering.md` — read that before asking. Routing is decided by the question, never by asking the user which mode they want:
+
+- Options self-explanatory and the stake fits one line → render it directly and let the user answer in place.
+- Needs citations, trade-offs, or more than three lines of context → write the question file first, then render a prompt naming its path in one line.
+
+### The question file
+
+Written in **every** branch, including when the user answers in place — it is the record of what was asked and decided, not a fallback. Two locations, and no others are valid:
+
+- Inside an instance: `.aidlc/state/<instance>/<phase>-questions.md`.
+- No instance (constitution update, first activation): `.aidlc/questions/<topic>.md`.
+
+Each question in the file ends with an `[Answer]:` tag — blank while open, carrying the chosen option label verbatim once answered. Fold answers into the phase artifact they were gathered for and leave the file in place as the record.
+
+With no interactive terminal, write the file, say where it is, and end the turn. Never assume an answer.
+
+**At most five questions stand open at once.** At the limit, answering — or accepting the stated defaults — comes before asking another. The cap counts open questions, not questions asked: a long negotiation is fine, an accumulating pile is not.
 
 ## Roadmap Capture
 

package/skills/03-entry-point.md

@@ -32,7 +32,8 @@ If `.aidlc/context/` does not exist or contains no `.md` files, defer to the **a
 2. For each instance, read `instance.yaml` (current phase, template, scope, claim) and the `phase-<name>.yaml` files to compute completion (complete artifacts ÷ total required artifacts).
 3. Read `.aidlc/config.yaml` for project defaults (scope, template) if present.
 4. Count roadmap items per status directory under `.aidlc/roadmap/` (`inbox`, `backlog`, `in-progress`, `done`, `hold`) — count files, and read frontmatter only if a title is needed. Never read item bodies. Status is the directory; there is no status field to read.
-5. Check `<git-common-dir>/aidlc/retro-pending/` (resolve via `git rev-parse --git-common-dir`) for pending-retrospective markers. Each marker adds a menu entry: **Run retrospective for `<instance>`** (routes to the **aidlc-retrospective** skill). A marker whose instance has no state dir and no registry entry is stale — remove it and note the cleanup in one line.
+5. Count pending questions — the question files matching `.aidlc/state/*/*-questions.md` and `.aidlc/questions/*.md` that contain at least one blank `[Answer]:` tag. Grep for the tag; do not read the question bodies. This is the only read that opens a question file at menu time.
+6. Check `<git-common-dir>/aidlc/retro-pending/` (resolve via `git rev-parse --git-common-dir`) for pending-retrospective markers. Each marker adds a menu entry: **Run retrospective for `<instance>`** (routes to the **aidlc-retrospective** skill). A marker whose instance has no state dir and no registry entry is stale — remove it and note the cleanup in one line.
 
 Do not read artifact bodies or transition history to build the menu — the compact state files are enough.
 
@@ -43,6 +44,7 @@ Compose a short menu from the state. Include only the options that make sense:
 - **Continue `<instance>`** — one entry per incomplete instance, showing current phase and completion percentage. Most recently updated first.
 - **Start something new** — always.
 - **Capture a roadmap item** — always.
+- **Answer pending questions** — when the pending-question count is above zero; show it and where they are (e.g. "2 questions waiting — `my-feature`, constitution update"). List this first among the roadmap and question entries: an unanswered question is work already blocked.
 - **Triage the inbox** — when `inbox/` is non-empty; show the count (e.g. "3 items awaiting triage"). List this above **Browse** — an untriaged submission is somebody waiting on a decision.
 - **Browse / promote the roadmap** — when any status directory outside `hold/` is non-empty; show counts per status (e.g. "3 inbox, 5 backlog, 1 in progress, 12 done").
 - **Show status** — when at least one instance exists.
@@ -60,6 +62,7 @@ If `.aidlc/state/` is empty or missing, offer just three options: start somethin
 | Continue an instance | Follow the **aidlc-continue** skill |
 | Start something new | Run the **concurrency gate** (below), then ask what they are building, pick a template (see **aidlc-getting-started**), and create the instance per "Creating an Instance" in **aidlc-overview** |
 | Capture a roadmap item | Follow the **aidlc-roadmap** skill (capture flow) |
+| Answer pending questions | Open the question file, re-render its open questions per the **Question Protocol** in **aidlc-overview**, record each answer in the file, then fold them into the artifact they were gathered for |
 | Triage the inbox | Follow the **aidlc-roadmap** skill (triage flow) |
 | Browse / promote the roadmap | Follow the **aidlc-roadmap** skill (browse/promote flow) |
 | Show status | Summarize each instance from its state files — name, template, current phase, completion %, and whether it looks stalled. When the roadmap is non-empty, append the per-status counts (e.g. "roadmap: 3 inbox, 5 backlog, 12 done") |

package/skills/05-constitution.md

@@ -8,12 +8,12 @@ native_mode_hint:
   claude-code: >-
     This skill imports a document and drafts prose for the user to correct. Do
     not enter plan mode. Never rewrite an existing constitution from the vision
-    in one step — propose changes into the inbox and apply only what the user
+    in one step — propose changes as a question file and apply only what the user
     accepts.
   copilot: >-
     This skill imports a document and drafts prose for the user to correct. Stay
     in the default agent — do not switch to plan mode. Never rewrite an existing
-    constitution from the vision in one step — propose changes into the inbox and
+    constitution from the vision in one step — propose changes as a question file and
     apply only what the user accepts.
 ---
 # Constitution
@@ -134,35 +134,40 @@ risk, and it exits 0 either way. This is advisory. It never fails a phase.
 
 ### Step 2 — Propose, do not apply
 
-Write a proposal to `.aidlc/inbox/constitution-update-<YYYY-MM-DD>.md`, one
-checkbox per change, following the User Input Protocol in the overview skill:
+A constitution update has no instance, so its questions go to
+`.aidlc/questions/constitution-update-<YYYY-MM-DD>.md` — one question per change,
+following the **Question Protocol** in the overview skill:
 
 ```markdown
 # Constitution update — <date>
 
 Vision source: <path> (<n> statements added, <m> removed)
 
-## NOT-2 cites V-99887766, which is gone
+## Should NOT-2 still stand, now that the statement it cites is gone?
 
+**Why it matters:** NOT-2 is a boundary this repo is held to. Left citing a
+statement the vision no longer carries, it is enforced without a source.
+
+**What the repo already says:** `.aidlc/constitution.md` NOT-2 cites V-99887766.
 The vision no longer says: "<old statement text>"
 It now says: "<new statement text, if there is a successor>"
 
-- [ ] Re-cite NOT-2 against V-<new id>, wording unchanged
-- [ ] Reword NOT-2: <proposed wording>
-- [ ] Retire NOT-2 — the vision no longer supports it
-- [ ] Leave NOT-2 as it is (a deliberate local rule the vision never carried)
+1. Re-cite NOT-2 against V-<new id>, wording unchanged — the boundary survives, only its source moves.
+2. Reword NOT-2: <proposed wording> — the boundary narrows to what the vision now supports.
+3. Retire NOT-2 — the repo may do this again, with nothing recording that it once must not.
+4. Leave NOT-2 as it is — it becomes a deliberate local rule the vision never carried.
 
-## V-<new id> is new and nothing covers it
+**Recommended:** 1, when a successor statement exists — the boundary was agreed
+on its own merits and a re-citation is the smallest change that keeps it sourced.
 
-"<statement text>"
+**If you say nothing:** NOT-2 is left as it is and the drift is recorded in
+Amendments, so the next reader sees an unsourced rule rather than a silent one.
 
-- [ ] Add IN-<next>: <proposed wording>
-- [ ] Add NOT-<next>: <proposed wording>
-- [ ] Nothing — this statement is about a different repo
+[Answer]:
 ```
 
-Include the last option every time. "The vision changed and this repo's boundary
-did not" is a common and correct answer.
+Offer the leave-as-it-is option every time. "The vision changed and this repo's
+boundary did not" is a common and correct answer.
 
 ### Step 3 — Apply only what is checked
 
@@ -174,7 +179,8 @@ aidlc constitution import <path>
 
 Append one line to Amendments for every applied change — date, entry id, what
 changed, why. Amendments are how the next reader tells a deliberate local rule from
-a stale derivation. Offer to delete the inbox file once its content has landed.
+a stale derivation. Record each answer in the question file and leave it in place —
+it is the record of what was asked and decided.
 
 ## Consulting the constitution
 

package/skills/20-requirements.md

@@ -48,7 +48,7 @@ See **The context rule** in **aidlc-overview**.
    - **Identified**: write every criterion as a list item `- AC-<n>: <text>` (bold variants `- **AC-<n>**: ...` and `- **AC-<n>:** ...` are also valid). Assign `AC-1`, `AC-2`, ... sequentially. IDs are never renumbered or reused — an amended criterion keeps its meaning or is retired: mark it `- AC-<n> (retired YYYY-MM-DD, superseded by AC-<m>): <text>` and issue a new ID. The testing-phase gate parses these IDs and fails on any active criterion without a referencing test.
 4. **Set scope boundaries.** Explicitly state what is NOT included.
 5. **Non-functional requirements.** Address performance, security, accessibility, and compatibility where relevant.
-6. **For complex input or open decisions**: If requirements are extensive, or unresolved decisions block the draft, create an input file in `.aidlc/inbox/` following the User Input Protocol in **aidlc-overview**, rather than asking many sequential questions. Prefer drafting `requirements.md` early with unresolved points marked as explicit decision blocks — users decide better reacting to a concrete draft than answering abstract questions.
+6. **For open decisions**: When a decision would change what `requirements.md` says, ask it through the **Question Protocol** in **aidlc-overview** — 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)