@rasensio/aidlc-content 1.37.1 → 1.38.0

package/package.json

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

package/resources/rules/next-steps.md

@@ -0,0 +1,38 @@
+# The next-steps rule
+
+This file is the only statement of the rule. The phase skills and the review skill point here instead of restating it.
+
+**Never end a phase or a review on a state.** "26 findings", "gate failed" and "phase in progress" tell the user where things are and leave them to work out the path. End instead with what they must decide, what you can fix, and one command.
+
+## When it applies
+
+- At the end of a phase, once its exit criteria are met or it cannot go further without the user.
+- At the end of a review, after the findings file is written.
+- After an `aidlc gate` or `aidlc transition` failure you are reporting.
+
+## Sort what is still open
+
+Put every open item — finding, gap, failed criterion — into exactly one of two groups:
+
+1. **Needs your decision.** Different answers would change an artifact, the scope, or the product: which principal is refused, whether production behaviour changes, what an edge case should return. Ask these through the **Question Protocol** (`.aidlc/resources/rules/question-protocol.md`) — in place when the options fit one line, in `.aidlc/state/<instance>/<phase>-questions.md` when they need context. Name the item each question came from.
+2. **I can fix these.** One correct answer exists and you can apply it: a wrong rule id, a stale sentence, an over-broad permission, a missing test, a task out of order. List them, one line each, and offer to apply them all in one step. Do not ask about each one separately.
+
+An item you cannot place is a decision. Do not quietly fix something that was the user's to choose.
+
+When both groups are empty, say so in one line.
+
+## End with one next command
+
+Close the turn with exactly one next step. It names a command the user can run as written — the real instance name, the real phase or artifact — or, when decisions are open, says to answer them first.
+
+- Decisions are open → answer them first; no command yet.
+- Fixes are offered and not yet applied → the fixes, then the command below.
+- The phase's exit criteria are met → `aidlc transition <instance>`. That is the step that marks the phase complete; `aidlc gate` only checks, and fails on an open phase until it runs.
+- A review finished with no open critical finding → `aidlc transition <instance>` for the phase the artifact belongs to.
+- The instance's last phase is done → the retrospective (**aidlc-retrospective**).
+
+If the CLI printed a `Next steps:` block, use it — it names the fix for each failure it reported.
+
+## What this rule does not do
+
+It changes what you report, not what you write. It adds no writer of `phase-<name>.yaml` or `transitions.log`: the Completion section of each skill still says how the phase is closed.

package/skills/00-overview.md

@@ -92,6 +92,10 @@ On each lifecycle event — `on-instance-start`, `on-phase-enter`, `on-phase-exi
 
 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`.
 
+## Ending a Phase or a Review
+
+How to end a turn: decisions asked, fixes offered together, and one next command. The rule is in `.aidlc/resources/rules/next-steps.md`.
+
 ## Roadmap Capture
 
 When the user shares an idea tangential to the current work, offer to record it in `.aidlc/roadmap/inbox/` (see **aidlc-roadmap**) and continue the current phase — do not derail into ideation. Capture touches no instance state, so it is safe at any point in any phase.

package/skills/10-ideation.md

@@ -66,3 +66,5 @@ If any ideation option involves sensitive operations (new credentials, infrastru
 ## Completion
 
 When exit criteria are met, update `phase-ideation.yaml` status to `complete` and append a transition record to `transitions.log`.
+
+Then end the turn as **The next-steps rule** (`.aidlc/resources/rules/next-steps.md`) says.

package/skills/20-requirements.md

@@ -85,6 +85,8 @@ If requirements reference sensitive data handling, authentication flows, or acce
 
 When exit criteria are met, update `phase-requirements.yaml` status to `complete` and append a transition record to `transitions.log`.
 
+Then end the turn as **The next-steps rule** (`.aidlc/resources/rules/next-steps.md`) says.
+
 ## Amending a Completed Phase
 
 A completed phase's artifact is changed **only through an amendment**. Editing

package/skills/30-design.md

@@ -89,6 +89,8 @@ You MUST flag these explicitly in the design document and note that implementati
 
 When exit criteria are met, update `phase-design.yaml` status to `complete` and append a transition record to `transitions.log`.
 
+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
 `## Amendment <n> — YYYY-MM-DD` section to `requirements.md` with `Retires:`, `Issues:`,
 `Reopens:` and `Reason:` bullets, then run `aidlc amend <instance>` (start with `--impact`

package/skills/40-implementation.md

@@ -82,6 +82,8 @@ Never store credentials, API keys, tokens, or passwords in source code or state
 
 When exit criteria are met, update `phase-implementation.yaml` status to `complete` and append a transition record to `transitions.log`.
 
+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
 `## Amendment <n> — YYYY-MM-DD` section to `requirements.md` with `Retires:`, `Issues:`,
 `Reopens:` and `Reason:` bullets, then run `aidlc amend <instance>` (start with `--impact`

package/skills/50-testing.md

@@ -100,6 +100,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`.
 
+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
 `## Amendment <n> — YYYY-MM-DD` section to `requirements.md` with `Retires:`, `Issues:`,
 `Reopens:` and `Reason:` bullets, then run `aidlc amend <instance>` (start with `--impact`

package/skills/60-deployment.md

@@ -100,3 +100,5 @@ Never deploy without explicit user confirmation. If the user cancels, halt and l
 When exit criteria are met, update `phase-deployment.yaml` status to `complete` and append a transition record to `transitions.log`.
 
 Then check for the **completion moment**: derive the instance's applicable phases (template × scope). If deployment is the last applicable phase, or the next phase is maintenance (maintenance-terminal templates complete on maintenance *entry*, since maintenance is open-ended), this transition completes the instance — run the **aidlc-retrospective** skill now, before any completion cleanup (worktree removal, claim release), and fire the `on-instance-complete` event.
+
+End the turn as **The next-steps rule** (`.aidlc/resources/rules/next-steps.md`) says.

package/skills/70-maintenance.md

@@ -78,3 +78,5 @@ You MUST describe the change, confirm the target environment, and wait for expli
 For maintenance-terminal instances the completion moment already fired on maintenance *entry* (see **aidlc-deployment**) — entering this phase means the instance is complete and its retrospective has run or is pending. Do not fire `on-instance-complete` again when closing the phase.
 
 When exit criteria are met, update `phase-maintenance.yaml` status to `complete` and append a transition record to `transitions.log`. If no retrospective exists for the instance (legacy completion paths), offer to run the **aidlc-retrospective** skill.
+
+Then end the turn as **The next-steps rule** (`.aidlc/resources/rules/next-steps.md`) says.

package/skills/80-review.md

@@ -150,4 +150,11 @@ If the review identifies security vulnerabilities:
 
 ## Completion
 
-After writing the findings file, report the review summary: total findings count by severity, and whether any critical findings block phase transition.
+After writing the findings file, report the review summary in two lines: total findings count by severity, and whether any critical findings block phase transition.
+
+The summary is not the end of the turn. A review's output is mostly decisions, and a count leaves the user to dig them out. Follow **The next-steps rule** (`.aidlc/resources/rules/next-steps.md`):
+
+1. Split the open findings into **needs your decision** and **I can fix these**. A finding whose fix changes what the product does, who it refuses, or what it returns is a decision, whatever its severity.
+2. Ask the decisions through the **Question Protocol** (`.aidlc/resources/rules/question-protocol.md`), each naming its finding id. When the reviewed artifact belongs to a phase, the question file is that phase's `<phase>-questions.md`.
+3. List the fixes one line each, by finding id, and offer to apply them together. When the user accepts, apply them and mark each finding `resolved` in the findings file.
+4. End with one next command — usually `aidlc transition <instance>` once no critical finding is open.