@rasensio/aidlc-content 1.40.2 → 1.42.0

package/package.json

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

package/resources/rules/question-protocol.md

@@ -38,4 +38,6 @@ Each question in the file ends with an `[Answer]:` tag — blank while open, car
 
 With no interactive terminal, write the file, say where it is, and end the turn. Never assume an answer.
 
+**Unattended (`AIDLC_UNATTENDED=1`)** is the one exception, and it is not an assumption: take the recommended option, write it into `[Answer]:` followed by `(unattended default)`, and log it — or, when the recommended option falls in a hard-stop class, stop. Both per `.aidlc/resources/rules/unattended.md`.
+
 **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.

package/resources/rules/unattended.md

@@ -0,0 +1,60 @@
+# The unattended rule
+
+This file is the only statement of the rule. Skills point here instead of restating it, so there is no second copy to drift.
+
+Unattended mode is on exactly when the environment variable `AIDLC_UNATTENDED` is `1` (`printenv AIDLC_UNATTENDED`). Otherwise every skill behaves as written. Nobody answers in this mode, so every place a skill would stop for a person has one outcome:
+
+- **Default and log** — take the named default, log it, carry on.
+- **Hard stop** — log it, park the item, release the claim, end the session.
+- **Release boundary** — the normal end of an unattended run. Not a hard stop, and the item is not parked.
+
+A situation no entry below covers is a hard stop. Guessing is what this mode exists to prevent.
+
+## The log
+
+Append one entry per default or hard stop to `.aidlc/state/<instance>/unattended-stops.md`: a `## <n>. <title> — <slug>` heading, then **Source:** (skill and section, or rule), **Instruction:** (the exact text), **Decided:** (the default, or "hard stop"), **Why:** (why it is safe, or which hard-stop class). A Question Protocol answer also carries `(unattended default)` in its `[Answer]:` — how a reviewer finds every choice nobody made.
+
+## Hard stop
+
+Always a hard stop:
+
+1. Crossing a prohibition in `.aidlc/context/constitution.md`.
+2. Deleting or overwriting data this session did not create.
+3. Changing authentication, secrets, permissions or CI tokens, or handling real credentials.
+4. Growing scope beyond the roadmap item's "What success looks like".
+
+To stop:
+
+1. Append the log entry.
+2. Run `aidlc roadmap park <instance> --reason "<slug>: <one line>"`.
+3. Run `aidlc release <instance>`.
+4. End the session. Commit nothing more; try no other route to the same outcome.
+
+## The release boundary
+
+When testing completes, write the deployment record's release plan and end the session. Do not push, open a pull request, merge or release: whatever runs the agent owns those, and two actors on one release lane is how two releases collided on 2026-10-01.
+
+## Every known stop
+
+Each bullet begins with its one outcome; a condition after it is part of the rule.
+
+- `entry-menu` — **default and log**: route to what the prompt names.
+- `instance-name-taken` — **hard stop**: another session's work or an abandoned start, indistinguishable from here.
+- `template-choice` — **default and log**: what the item or prompt names, else `defaults:` in `.aidlc/config.yaml`.
+- `worktree-hand-off` — **default and log**: when the prompt says to continue, continue in the worktree.
+- `roadmap-move-uncommitted` — **default and log**: leave it uncommitted; the caller commits.
+- `roadmap-item-unlinked` — **default and log**: use `aidlc start --roadmap-item`; never move the item by hand.
+- `requirements-input` — **default and log**: read `roadmap-item.md`; with neither it nor an ideation artifact, hard stop.
+- `open-question` — **default and log**: the recommended option, marked `(unattended default)`; if it is a hard-stop class, hard stop — never another option.
+- `requirements-confirmation` — **default and log**: hard stop if the requirements exceed the roadmap item.
+- `design-confirmation` — **default and log**: the same scope test.
+- `phase-end-turn` — **default and log**: continue into the next phase.
+- `fresh-session` — **default and log**: continue; the runner decides where sessions start.
+- `own-change-revert` — **default and log**: reverting this session's own change, after keeping a copy.
+- `generated-output-discard` — **hard stop**: discarding output this session did not write.
+- `sensitive-operation` — **hard stop**: deletions, infrastructure, permissions, credentials — except `own-change-revert`.
+- `shared-state-prune` — **default and log**: it removes only entries whose worktree is gone and branch merged or deleted, and names each; log the names.
+- `commit-incrementally` — **default and log**: on the instance branch only; never `main`, never push.
+- `testing-security` — **hard stop**: production-like environments, real credentials, destructive operations.
+- `platform-unknown` — **default and log**: carry on; the runner sets `AIDLC_AGENT`.
+- `release-boundary` — **release boundary**: completing testing.

package/skills/00-overview.md

@@ -90,7 +90,7 @@ On each lifecycle event — `on-instance-start`, `on-phase-enter`, `on-phase-exi
 
 ## Question Protocol
 
-When to ask the user something, how the question is written, and where it is recorded. The rule is in `.aidlc/resources/rules/question-protocol.md`.
+When to ask the user something, how the question is written, and where it is recorded. The rule is in `.aidlc/resources/rules/question-protocol.md`. With nobody there: `.aidlc/resources/rules/unattended.md`.
 
 ## Ending a Phase or a Review
 

package/skills/03-entry-point.md

@@ -8,11 +8,13 @@ native_mode_hint:
   claude-code: >-
     This skill is an interactive entry point, not a phase artifact. Do not
     enter plan mode. Read lifecycle state, present the menu, and wait for
-    the user's choice before doing any work.
+    the user's choice before doing any work — unless their message already
+    says what they want; then route to it directly.
   copilot: >-
     This skill is an interactive entry point, not a phase artifact. Stay in the
     default agent — do not switch to plan mode. Read lifecycle state, present the
-    menu, and wait for the user's choice before doing any work.
+    menu, and wait for the user's choice before doing any work — unless their
+    message already says what they want; then route to it directly.
 ---
 # AIDLC Entry Point
 

package/skills/04-roadmap.md

@@ -176,9 +176,8 @@ When the user asks for a worktree ("create a new worktree for roadmap `<file>`")
 
 1. **Find the item** by file name, `id`, or title, in `backlog/` or `inbox/`. Asking for a worktree counts as choosing to skip triage. When more than one item matches, list them and ask which one.
 2. **Instance name**: the item's file name without its date prefix and extension (the item filed as `20260929-say-what-to-do-next` becomes `say-what-to-do-next`). Template and scope come from the config defaults, unless the item or the user names them.
-3. **Create the instance with** `aidlc start <template> --name <name> --scope <scope> --worktree --non-interactive`. Take the worktree path from the `Worktree:` line it prints. That command creates the branch and the worktree and fires `on-instance-start`; do not repeat any of it by hand.
-4. **Seed the instance inside the worktree** (`<worktree>/.aidlc/state/<name>/`), not the primary checkout. Copy the item into it per step 5 above. Keep the roadmap move (step 6) in the primary checkout, as always.
-5. **Hand off. Do not start the phase in this session.** The work belongs to the new session. End with the exact command that opens it:
+3. **Create the instance with** `aidlc start <template> --name <name> --scope <scope> --worktree --non-interactive --roadmap-item <item-file>`. Take the worktree path from the `Worktree:` line it prints. That one command creates the branch and the worktree, fires `on-instance-start`, sets the item's `promoted_to`, moves it to `in-progress/` in the primary checkout, and copies it into the instance as `roadmap-item.md` — which is the seeding step 5 above asks for. Do none of it by hand: a hand-made move is the step that got skipped. The move is left uncommitted in the primary checkout; committing it is yours.
+4. **Hand off. Do not start the phase in this session** — unless the user's own message asks you to continue here, in which case `cd` into the worktree and follow **aidlc-continue** there. Otherwise the work belongs to the new session. End with the exact command that opens it:
    ```
    cd <worktree> && claude "/aidlc-continue <name>"
    ```

package/skills/20-requirements.md

@@ -39,35 +39,46 @@ See **The context rule** (`.aidlc/resources/rules/context.md`).
 
 > {{glossary:artifact}}
 
-1. **Gather requirements.** If a Full scope, read the ideation phase's artifact for context (`idea.md` for the feature templates, `research-question.md` for `spike`; `phase-ideation.yaml` names it). Otherwise, ask the user to describe desired behavior. Read the always-read guidance layers from `.aidlc/guidance/index.yaml` — see **The always-read rule** (`.aidlc/resources/rules/always-read.md`) for which layers those are and when to reach for the full `lessons.md`. Read `.aidlc/context/constitution.md` when it exists and apply the constitution rule in `.aidlc/resources/rules/constitution.md`.
+1. **Gather requirements.** If a Full scope, read the ideation phase's artifact for context (`idea.md` for the feature templates, `research-question.md` for `spike`; `phase-ideation.yaml` names it). At Standard scope, read the roadmap item the instance was promoted from (`roadmap-item.md` in its state directory). Ask the user to describe the desired behaviour only when there is neither. Unattended (`AIDLC_UNATTENDED=1`): no artifact and no item is a hard stop, per `.aidlc/resources/rules/unattended.md`. Read the always-read guidance layers from `.aidlc/guidance/index.yaml` — see **The always-read rule** (`.aidlc/resources/rules/always-read.md`) for which layers those are and when to reach for the full `lessons.md`. Read `.aidlc/context/constitution.md` when it exists and apply the constitution rule in `.aidlc/resources/rules/constitution.md`.
 2. **Write user stories.** Use the format: "As a [role], I want [capability], so that [benefit]."
 3. **Define acceptance criteria.** Each criterion must be:
    - Specific and unambiguous
    - Testable (an observable outcome)
    - Independent (not relying on unstated assumptions)
    - **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.
+   - **Shaped**, when the criterion is a behaviour. Write the text after the colon in one of four shapes, each naming its own test — the condition to set up and the response to check:
+     - Event — `- AC-1: WHEN the user presses Save, THE SYSTEM SHALL write the draft to disk`
+     - State — `- AC-2: WHILE the draft is unsaved, THE SYSTEM SHALL show a dot in the tab`
+     - Unwanted — `- AC-3: IF the disk is full, THEN THE SYSTEM SHALL keep the draft in memory and say so`
+     - Optional — `- AC-4: WHERE autosave is on, THE SYSTEM SHALL save the draft every 30 seconds`
+
+     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.
 
 ## Bugfix Reproduction (bugfix template)
 
-When the instance uses the `bugfix` template, this phase produces `reproduction.md` instead of full requirements:
+When the instance uses the `bugfix` template, this phase produces `reproduction.md` and a bugfix-shaped `requirements.md`:
 
 1. **Reproduce first.** Capture: observed behavior, expected behavior, minimal reproduction steps, affected versions/environment. A bug that cannot be reproduced gets documented as such — with the evidence tried — before any fix work.
 2. **Acceptance criteria** for the fix follow the same `AC-<n>` ID rules as regular requirements (the reproduction steps typically become the test).
-3. **Propose defect linkage (`caused_by`).** Identify which instance(s) likely introduced the defect:
+3. **Write `requirements.md` in three sections, in this order.** The testing gate reads criteria from `requirements.md` only, so they go here, not in `reproduction.md`:
+   - **Current behaviour** — what happens today. Description only; no IDs.
+   - **Expected behaviour** — what the fix makes happen. Each line an `AC-<n>` criterion.
+   - **Unchanged behaviour** — what works next to the fix today and must still work after it. Each line an `AC-<n>` criterion, so the gate demands a test for it. If you find nothing, write "None found" and say why; never leave the section out.
+4. **Propose defect linkage (`caused_by`).** Identify which instance(s) likely introduced the defect:
    - `git blame` the defective lines and match commits to instance branches (`fix|feat|chore/<YYYYMMDD>-<name>`)
    - Query the knowledge graph for the module's history
    - Check instance state dirs and the registry for names
    Present the candidates *as guesses* with the evidence. The user confirms, edits, or declines — `caused_by` is **never written without explicit user confirmation**, and declining leaves the field absent (absent = unknown, never an error).
-4. **Write the confirmed linkage** to `instance.yaml` as a list: `caused_by: [<instance>, ...]` (single cause = one-element list). Validate every name against existing state dirs or registry entries — an unknown name needs re-confirmation; reject the bugfix's own name (no self-reference).
+5. **Write the confirmed linkage** to `instance.yaml` as a list: `caused_by: [<instance>, ...]` (single cause = one-element list). Validate every name against existing state dirs or registry entries — an unknown name needs re-confirmation; reject the bugfix's own name (no self-reference).
 
 ## Exit Criteria
 
 - `requirements.md` exists with at least one user story and corresponding acceptance criteria
 - Each acceptance criterion is testable (has an observable pass/fail condition)
-- The user has confirmed the requirements are complete for the chosen scope
+- The user has confirmed the requirements are complete for the chosen scope. Unattended (`AIDLC_UNATTENDED=1`): log the confirmation as a default, or hard-stop when the requirements reach beyond the roadmap item, per `.aidlc/resources/rules/unattended.md`.
 
 ## Guidance
 

package/skills/30-design.md

@@ -66,7 +66,7 @@ transcript. See **The context rule** (`.aidlc/resources/rules/context.md`).
 - Every knowledge-graph symbol the design builds on was checked against the source
 - The design addresses all acceptance criteria from `requirements.md`
 - For templates requiring it: `tasks.md` exists and every active acceptance criterion is claimed by at least one task, or the gap is deliberate
-- The user has confirmed the design direction
+- The user has confirmed the design direction. Unattended (`AIDLC_UNATTENDED=1`): log the confirmation as a default, or hard-stop when the design reaches beyond the roadmap item, per `.aidlc/resources/rules/unattended.md`.
 
 ## Guidance
 

package/skills/40-implementation.md

@@ -44,7 +44,7 @@ Then the source files that task touches. See **The context rule** (`.aidlc/resou
 2. **Load guidance.** Read the always-read guidance layers from `.aidlc/guidance/index.yaml` — see **The always-read rule** (`.aidlc/resources/rules/always-read.md`) for which layers those are and when to reach for the full `lessons.md`. Apply their rules during implementation.
 3. **Execute the task breakdown.** When the instance has a `tasks.md` (produced in Design for full/quick-feature scope), read it and execute tasks in order: complete a task, then mark its checkbox `[x]` as part of the same work unit — never batch checkbox updates for later. A task that should not be done is deferred in place (`- [>] T<n>: <title> (deferred YYYY-MM-DD: <reason>)`) with a dated reason, never skipped silently or deleted; the implementation→testing gate blocks on open tasks. For bugfix scope, create the optional `tasks.md` at implementation start when the fix spans more than one commit-sized unit. For Micro scope, reference the task description and acceptance criteria directly — no task file.
 4. **Write code.** Follow the design interfaces. Match existing code style (naming, formatting, error handling patterns).
-5. **Handle sensitive operations.** Before executing any of the following, describe the action and wait for explicit user confirmation:
+5. **Handle sensitive operations.** Before executing any of the following, describe the action and wait for explicit user confirmation (unattended, `AIDLC_UNATTENDED=1`: each is a hard stop except reverting this session's own changes, per `.aidlc/resources/rules/unattended.md`):
    - File deletions or destructive operations
    - Infrastructure changes (provisioning, configuration)
    - Permission or access control modifications
@@ -70,6 +70,8 @@ Then the source files that task touches. See **The context rule** (`.aidlc/resou
 
 ## Security Confirmation
 
+Unattended (`AIDLC_UNATTENDED=1`): nobody can confirm, so everything this section asks to confirm is a hard stop, per `.aidlc/resources/rules/unattended.md`.
+
 Before proceeding with any sensitive operation during implementation:
 1. Describe what the operation does and what it affects
 2. State whether it is reversible

package/skills/50-testing.md

@@ -47,6 +47,8 @@ See **The context rule** (`.aidlc/resources/rules/context.md`).
    - Integration tests for component interactions
    - Property-based tests where inputs have broad domains
    - **Reference AC IDs.** When `requirements.md` defines `AC-n` criteria, each test names the criteria it verifies — in the test name or a comment (e.g. `// AC-3`). The testing-phase gate scans test files for these references and fails on any active criterion with none. If two instances define the same ID, qualify the reference as `<instance>/AC-n`.
+   - **Test the shape.** A `WHEN`/`WHILE`/`IF`/`WHERE` criterion names its own test: set up the condition, assert the `SHALL` response. An `IF` criterion is tested by causing the unwanted condition, not by the happy path.
+   - **Unchanged behaviour (bugfix).** Each criterion in that section of `requirements.md` gets a test that passes before the fix and after it. Run it once against the unfixed code to see it pass.
 3. **Run tests.** Execute the project's test suite. All new tests must pass.
 4. **Document results.** Write the phase's required artifact (see Required Artifacts above) with:
    - Test plan (what was tested and why)
@@ -89,6 +91,8 @@ testing phase and record newly introduced advisories as findings.
 
 ## Security Confirmation
 
+Unattended (`AIDLC_UNATTENDED=1`): nobody can confirm, so everything this section asks to confirm is a hard stop, per `.aidlc/resources/rules/unattended.md`.
+
 If testing requires:
 - Access to production-like environments
 - Use of real credentials or sensitive data
@@ -100,6 +104,8 @@ You MUST describe the action, confirm it targets a safe environment, and wait fo
 
 When exit criteria are met, update `phase-testing.yaml` status to `complete` and append a transition record to `transitions.log`.
 
+Unattended (`AIDLC_UNATTENDED=1`): this is the release boundary. Write the deployment record's release plan and end the session — no push, pull request, merge or release — per `.aidlc/resources/rules/unattended.md`.
+
 Then end the turn as **The next-steps rule** (`.aidlc/resources/rules/next-steps.md`) says.
 
 **Changing a completed phase's artifact.** Do it only through an amendment — append an

package/skills/60-deployment.md

@@ -82,6 +82,8 @@ deployment checklist.
 
 ## Security Confirmation
 
+Unattended (`AIDLC_UNATTENDED=1`): nobody can confirm, so everything this section asks to confirm is a hard stop, per `.aidlc/resources/rules/unattended.md`.
+
 Deployment is inherently sensitive. You MUST:
 1. Confirm the target environment with the user (production vs. staging vs. dev)
 2. Present the full list of changes being deployed