sdg-agents 1.14.2 → 1.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sdg-agents",
-  "version": "1.14.2",
+  "version": "1.16.0",
   "description": "Structured working protocol and engineering rules for AI agents. Works with Claude Code, Antigravity, Codex, and others.",
   "type": "module",
   "main": "./src/engine/bin/index.mjs",

package/src/assets/instructions/commands/sdg-docs.md

@@ -2,18 +2,9 @@
 
 Executing documentation for: $ARGUMENTS. This command prepares the context for the **Docs Cycle**.
 
-## Step 0 — Document Classification
-
-1. **Context Check**: Identify the document type needed based on the goal:
-   - **CHANGELOG**: Release entry or version synchronization → `CHANGELOG.md` at project root.
-   - **FEAT (Especificação da Funcionalidade)**: Document _what_ was built and _how_ it fits the pipeline → `docs/specs/FEAT-NNN-slug.md`.
-   - **ADR (Architecture Decision Record)**: Document _why_ a technical path was chosen (trade-offs) → `docs/decisions/ADR-NNN-slug.md`.
-2. **Numbering**: Use sequential zero-padded numbers (`ADR-001`, `FEAT-042`). Check existing files to find the next available number.
-3. **Current Alignment**: Read existing files in the target directory to maintain style and numbering consistency.
-
 ---
 
-## Phase: SPEC (Draft Specialization)
+## Phase: SPEC (The Contract) — MODE: PLANNING
 
 Follow the **Phase: SPEC** from the **Working Protocol**, using these templates for the "Drafting" logic:
 
@@ -27,7 +18,7 @@ Follow the **Phase: SPEC** from the **Working Protocol**, using these templates
 - [Brief entries from Unreleased]
 ```
 
-### Template B: FEAT (Especificação da Funcionalidade)
+### Template B: FEAT (Feature Specification)
 
 ```md
 # FEAT-[NNN]: [Feature Name]
@@ -47,11 +38,9 @@ Follow the **Phase: SPEC** from the **Working Protocol**, using these templates
 
 ---
 
----
-
-## Phase: END (Hardened)
+## Phase: END (The Delivery) — MODE: PLANNING
 
-Follow the **Phase: END** from the **Working Protocol**. Documentation must be accurate and mirror the code state perfectly. Sync the backlog and **WAIT** for authorization before `commit`/`push`.
+Follow the **Phase: END** from the **Working Protocol**. Documentation must be accurate and mirror the code state perfectly. Sync the backlog and **WAIT** for authorization before any `commit`/`push` proposal.
 
 ---
 

package/src/assets/instructions/commands/sdg-end.md

@@ -1,80 +1,70 @@
-# Cycle Terminator — END Phase
+# Phase: END (The Delivery) — MODE: PLANNING
 
-This command has no arguments. Type `end:` to close the active cycle.
-
-Executing the **Phase: END** checklist from the **Working Protocol** in strict order. Each item must be completed before advancing to the next.
+This command closes the current development cycle and is the **Ultimate Guarantor of Zero Context Leak**. Follow all 7 steps with total rigor.
 
 ---
 
-## Step 1 — SUMMARIZE
-
-Write one sentence per completed PLAN task. If no PLAN existed (e.g. `[S]` tasks), write a one-line summary of what changed.
-
-## Step 2 — CHANGELOG
+## Step 1 — Task Summary
 
-Prepare your technical narrative in the `CHANGELOG.md`.
+Write a concise summary of the work performed.
 
-1. **Identify Strategy**:
-   - **Automated**: If `auto-bump.mjs` exists, you **MUST** first manually populate the `## [Unreleased]` section with your technical narrative. The automated pipeline will promote this content to the new version header during the commit. **DO NOT commit with an empty [Unreleased] section.**
-   - **Manual**: If no automation is present, you must promote the header manually (e.g., `## [1.2.0] - 2026-04-11`) or run the designated `bump` script.
+- One sentence per completed task from `.ai-backlog/tasks.md`.
+- Focus on technical outcomes.
 
-2. **Append Entry**:
-   - `feat:` cycle → Add under `### Added`
-   - `fix:` cycle → Add under `### Fixed`
-   - `docs:` cycle → Optional (for major architectural docs)
-   - `land:` cycle → Skip
+## Step 2 — Changelog Narrative
 
-3. **Verify Header**: Ensure `## [Unreleased]` exists at the top. If missing, create it above the most recent version entry.
+Update `CHANGELOG.md` to maintain the project's technical history.
 
-## Step 3 — BACKLOG: tasks.md
+- **Action**: Add entries under `## [Unreleased]`.
+- **Categorization**: Use `### Added` for `feat:` or `### Fixed` for `fix:`.
+- **Integrity**: Ensure the narrative allows for a professional semantic release.
 
-- Move all `[DONE]` tasks to `## Done`.
-- If no active `tasks.md` existed (`[S]` cycle), skip.
+## Step 3 — Backlog Sync & Catch-all Staging
 
-## Step 4 — BACKLOG: context.md
+Synchronize state and ensure ALL side-effects are captured.
 
-Update `## Now` with the next objective, or set it to `Ready for next instruction.` if nothing is pending.
+- **Backlog**: Move all `Active` tasks to `Done` in `.ai-backlog/tasks.md`.
+- **Catch-all Stage**: Run `git add .` to capture metadata updates (package-lock.json, manifests) and any uncommitted side-effects.
+- **Audit**: Perform a **Zero Context Leak** check: no `TODO` remnants or internal-only files.
 
-## Step 5 — KNOWLEDGE (INSIGHTS)
+## Step 4 — Context Resilience (Bootstrap & Update)
 
-Log any patterns, findings, or rework discovered during this cycle. Curate stale or irrelevant entries.
+Update the project context. If the project state is lost, this is the healing moment.
 
-- [ ] **KNOWLEDGE** — Log findings in `.ai-backlog/learned.md` or `troubleshoot.md`. Curate stale items.
-- [ ] **CURATE** — Final scan for slop/AI-isms. Run `git status`.
-- [ ] **PURGE SESSION (GSD)** — Mandatório se chat longo (>10 mensagens). Sugira fechar chat e abrir novo após commit. Limpa "context rot".
-- [ ] **LINT** — Run `lint`, `lint:fix`, or equivalent. Block commit if errors remain.
+- **Self-Healing**: If `.ai-backlog/context.md` is missing, analyze the project and **Bootstrap** it using the template from `workflow.md`.
+- **Update**: Set `## Now` to `Ready for next instruction.`.
 
-## Step 6 — CURATE (Zero Context Leak)
+## Step 5 — Technical Quality (Self-Healing Lint)
 
-Scan all changed files for technical slop. Run `git status` — **You MUST ensure the workspace is 100% clean.**
+Perform a final quality sweep. No delivery with broken quality.
 
-- No uncommitted files (like `package-lock.json` or modified instructions).
-- No unfinished comments (`TODO`, `FIXME`, `...`).
-- No "AI-isms" or promotional language.
-- Run `git status` — confirm only intended files are staged/committed.
+- **Lint**: Run the project's linting script.
+- **Self-Healing**: If lint fails, you **MUST** run a one-time repair attempt (e.g., `npm run lint -- --fix`) before reporting a failure.
+- **Blocker**: If non-auto-fixable errors remain, you **MUST** report them and stop.
 
-## Step 7 — LINT
+## Step 6 — Semantic Release (Audit & Commit)
 
-If a lint script exists (`lint`, `lint:fix`, `lint:all`, or a config file is detected):
+Execute the delivery using the automated semantic pipeline.
 
-- Run it and auto-fix what's possible.
-- If non-auto-fixable violations remain, surface them explicitly.
-- Block commit if errors remain.
+1. **Identify**: Determine if the cycle was a `feat` or `fix`.
+2. **Execute**: Run `npm run bump <feat|fix>`.
+3. **Workspace Audit**: Run `git status` to ensure the staging area is 100% clean and nothing was left behind after the bump. Stage any remaining metadata changes with `git add .`.
+4. **Semantic Commit**: Propose exactly: `git commit -m "<feat|fix>: release v<version>"`.
+5. **Approval**: **PROPOSE** and **WAIT** for explicit Developer authorization.
 
-## Step 8 — COMMIT & RELEASE
+## Step 7 — Final Stroke (Push & Purge)
 
-Propose the commit message and **WAIT** for explicit Developer approval before committing.
+Complete the delivery cycle.
 
-- **Option A (Manual)**: If you just want to save progress without a version bump, commit with `feat:` or `fix:`. Remember you **MUST** have content in `[Unreleased]`.
-- **Option B (End Cycle)**: If the cycle is complete, run `npm run bump <fix|feat|major>` to consolidate the narrative and bump the version.
+- **Push**: Propose `git push` to synchronize remote.
+- **GSD**: Suggest starting a brand new chat session to purge the current context and prevent token rot.
 
-## Step 9 — PUSH
+---
 
-**ASK** for explicit permission before pushing to remote.
-The `pre-push` hook will **BLOCK** the push if any `[Unreleased]` narrative remains (preventing unversioned leaks to main).
+> [!WARNING]
+> The cycle is **INCOMPLETE** until all 7 steps are checked.
+> You are **FORBIDDEN** from accepting new work until this phase is finalized and the workspace is clean.
 
 ---
 
-> [!WARNING]
-> The cycle is **INCOMPLETE** until all applicable steps above are checked.
-> Do not accept new work until END is fully executed.
+> Read `.ai/instructions/core/agent-roles.md` for the multi-agent handoff protocol (Planning + Fast roles).

package/src/assets/instructions/commands/sdg-feat.md

@@ -2,44 +2,22 @@
 
 We are initializing a new feature: $ARGUMENTS. This command prepares the context for the development lifecycle following the **Working Protocol**.
 
-## Step 0 — Context Preparation
-
-1. **Roadmap Check**: If `ROADMAP.md` exists, read it to identify where this feature fits in the project's long-term vision.
-2. **Domain Scope**:
-   - **Backend** (API/Domain/DB) → read `.ai/instructions/competencies/backend.md`
-   - **Frontend** (UI/UX) → read `.ai/instructions/competencies/frontend.md`
-   - **Fullstack** → read both
-3. **Architecture Standards**: If `.ai/instructions/flavor/principles.md` exists, read the established data pipeline (Vertical Slice, MVC, etc.).
-4. **Backlog Knowledge**: Read `.ai-backlog/learned.md` to load successful patterns and past research findings.
-5. **Code Style Load** (mandatory — do not skip):
-   - **Engineering Standards** → read `.ai/instructions/core/engineering-standards.md`
-   - **Code Style & NarrativeCascade** → read `.ai/instructions/core/code-style.md`
-6. **Quality & Debugging**:
-   - **Testing Strategy** → read `.ai/instructions/core/testing-principles.md`
-   - **Observability** → read `.ai/instructions/core/observability.md`
-
 ---
 
-## Phase: SPEC (Especificação da Funcionalidade)
+## Phase: SPEC (The Contract) — MODE: PLANNING
 
-Follow the **Phase: SPEC** from the **Working Protocol**, with these mandatory additions:
+Follow the **Phase: SPEC** from the **Working Protocol**, ensuring all 5 steps are executed and announced. Mandatory technical density:
 
-- **Domain Modeling**: Explicitly define the primary entities and aggregate roots involved.
-- **Configuration Contract**: Define the environment variables required for this feature (keys must be **abstract**; pro-tip: `AUTH_SECRET` over `CLERK_SECRET`).
-- **Contract-First**: Define the Public Interface (API endpoints, public methods, or Component Props) before listing implementation steps.
-- **Storytelling**: The SPEC must describe the "User Journey" or the "Data Life Cycle".
-- **Backend SPEC (mandatory addition)**: If the domain includes API work, define the response contract before listing implementation steps:
-  - Use the Contract template from `backend.md`'s ContractFirst rule
-  - Define: endpoint method + path, input fields with types, output shape (envelope fields), and all error codes with conditions
-  - This contract must appear in the SPEC and be approved before PLAN begins
-- **Frontend SPEC (mandatory addition)**: If the domain includes UI work, define the section structure before any code:
-  - List each section by type (`section.hero`, `section.cards`, `section.form`, etc.)
-  - Define the layout skeleton: grid columns, main content blocks, and their data sources
-  - Identify which states must be handled: Loading / Empty / Error
-  - This wireframe contract must appear in the SPEC and be approved before PLAN begins
-- **Testing SPEC (mandatory addition)**: Explicitly define at least three scenarios: One Happy Path, one Edge Case, and one Expected Failure.
-  - Format as: `Scenario [Name] (Input: { ... }) -> Expected: [Result/State]`
-  - This testing contract must appear in the SPEC and be approved before PLAN begins
+- **1. Intent Classification**: Confirmed as `feat:`.
+- **2. Goal Definition**: Writes one sentence describing what will be built and why.
+- **3. Domain & Contracts**:
+  - **Domain Modeling**: Defines the domain (Backend / Frontend / Fullstack) and primary entities.
+  - **Configuration Contract**: Define environment variables (abstract keys).
+  - **Contract-First**: Defines the inputs and outputs (API or Props) before implementation.
+  - **Backend SPEC**: Define response contract template (method, path, input/output types, error codes). Load `competencies/backend.md`.
+  - **Frontend SPEC**: Define section structure, layout skeleton (grid/columns), and states (Loading/Empty/Error). Load `competencies/frontend.md`.
+- **4. Verification Checklist**: Creates up to 5 yes/no checkpoints to confirm the work is done right (min 3: Happy Path, Edge Case, Expected Failure).
+- **5. Approval Gate**: Stops and waits for your approval before writing any code.
 
 ---
 

package/src/assets/instructions/commands/sdg-fix.md

@@ -2,40 +2,28 @@
 
 We are correcting a recorded incident: $ARGUMENTS. This command prepares the context for the **Fix Cycle** defined in the **Working Protocol**.
 
-## Step 0 — Incident Analysis
-
-1. **Reproduction Scenario**: Read existing logs or provided data to define the exact steps to reproduce the issue.
-2. **Domain Scope**:
-   - **Backend** (Logic/Data) → read `.ai/instructions/competencies/backend.md`
-   - **Frontend** (UI/UX) → read `.ai/instructions/competencies/frontend.md`
-   - **Fullstack** → read both
-3. **Architecture Standards**: If `.ai/instructions/flavor/principles.md` exists, read the architectural principles.
-4. **Backlog Knowledge**: Read `.ai-backlog/troubleshoot.md` to load previous RCA logs and critical failure records.
-5. **Code Style & Standards** (mandatory):
-   - **Engineering Standards** → read `.ai/instructions/core/engineering-standards.md`
-   - **Code Style & Narrative Scansion** → read `.ai/instructions/core/code-style.md`
-6. **Diagnostic Standards**:
-   - **Testing Principles** → read `.ai/instructions/core/testing-principles.md`
-   - **Observability** → read `.ai/instructions/core/observability.md`
-
 ---
 
-## Phase: SPEC (Fix Specialization)
+## Phase: SPEC (The Contract) — MODE: PLANNING
 
-Follow the **Phase: SPEC** from the **Working Protocol**, with these mandatory additions:
+Follow the **Phase: SPEC** from the **Working Protocol**, ensuring all 5 steps are executed and announced. Fix specialization:
 
-- **Root Cause Analysis (RCA)**: Explicitly identify the layer, file, and line where the contract or logic breaks.
-- **Observed vs Expected**: Contrast the current broken behavior with the desired outcome.
-- **Minimal Surface**: Ensure the proposed fix targets ONLY the bug. No refactors allowed in this cycle.
-- **Configuration Contract**: If this fix introduces or changes any environment variable, list it here with its abstract key and purpose. Keys must hide vendor/infrastructure details (e.g., `AUTH_PROVIDER_SECRET` over `CLERK_SECRET`). No committed templates.
+- **1. Intent Classification**: Confirmed as `fix:`.
+- **2. Goal Definition**: Writes one sentence describing the incident and the reason for the fix.
+- **3. Domain & Contracts**:
+  - **Root Cause Analysis (RCA)**: Explicitly identify the layer, file, and line where the contract or logic breaks.
+  - **Observed vs Expected**: Contrast the current broken behavior with the desired outcome.
+  - **Minimal Surface**: Ensure the proposed fix targets ONLY the bug. No refactors allowed.
+- **4. Verification Checklist**: Creates up to 5 yes/no checkpoints, including the **Reproduction Case** as the primary validator.
+- **5. Approval Gate**: Stops and waits for your approval before writing any code.
 
 ---
 
-## Phase: PLAN (Regression Focus)
+## Phase: PLAN (The Strategy) — MODE: PLANNING
 
 Follow the **Phase: PLAN** from the **Working Protocol**, with this mandatory addition:
 
-- **Regression Test**: Include a task specifically for a test that reproduces the bug (Characterization Test). Use the patterns from `testing-principles.md`. This task must appear in the PLAN before approval.
+- **Regression Test**: Include a task specifically for a test that reproduces the bug (Characterization Test). Use the patterns from `testing-principles.md`.
 
 ---
 

package/src/assets/instructions/commands/sdg-land.md

@@ -14,7 +14,7 @@ We are landing on a project: $ARGUMENTS. This command runs once, at the very beg
 
 ---
 
-## Phase: VISION
+## Phase: VISION — MODE: PLANNING
 
 Parse the input prompt. Extract only what was explicitly stated — no assumptions, no embellishments.
 
@@ -29,7 +29,7 @@ If the prompt is too vague to extract these three points, ask one clarifying que
 
 ---
 
-## Phase: SURVEY (legacy only — skip if greenfield)
+## Phase: SURVEY — MODE: PLANNING (legacy only — skip if greenfield)
 
 Read the project silently. Do not announce findings yet.
 
@@ -41,7 +41,7 @@ If the project has no code at all, treat it as greenfield.
 
 ---
 
-## Phase: SCOPE
+## Phase: SCOPE — MODE: PLANNING
 
 Define the MVP boundary. This is the most important step.
 
@@ -56,7 +56,7 @@ Present the scope boundary before generating the backlog. If the vision is clear
 
 ---
 
-## Phase: BACKLOG
+## Phase: BACKLOG — MODE: PLANNING
 
 Generate two outputs:
 
@@ -104,6 +104,7 @@ Structure the backlog as ordered epics, each decomposed into concrete `feat:` ta
 
 ### Epic 2 — [Name]
 
+- [TODO] feat: [atomic task]
 - [TODO] feat: [atomic task]
 ```
 
@@ -111,7 +112,7 @@ Move the first task of Epic 1 to `## Active` as `[IN_PROGRESS]` only after the d
 
 ---
 
-## Phase: STOP
+## Phase: STOP — MODE: PLANNING
 
 Present a summary of what was produced:
 

package/src/assets/instructions/core/agent-roles.md

@@ -6,7 +6,7 @@
 
 ## Roles
 
-| Role         | Phases                  | Model default              | Mindset                          |
+| Role         | Phases (Cycles)         | Model default              | Mindset                          |
 | :----------- | :---------------------- | :------------------------- | :------------------------------- |
 | **Planning** | SPEC, PLAN, Review, END | claude-sonnet-4-6 thinking | Analytical — strategy and design |
 | **Fast**     | CODE, TEST              | claude-sonnet-4-6          | Operational — execute and verify |
@@ -18,7 +18,7 @@ Dev → Planning: SPEC + PLAN → [Dev approval]
                ↓
     Planning spawns Fast via Agent tool
                ↓
-         Fast: CODE + TEST
+          Fast: CODE + TEST
                ↓
     Fast returns output to Planning
                ↓
@@ -33,7 +33,7 @@ Dev → Planning: SPEC + PLAN → [Dev approval]
 ## Planning Role — Responsibilities
 
 - Load full governance context before SPEC: backlog, flavor, competencies.
-- Produce SPEC and PLAN. Stop and wait for Dev approval at each.
+- Produce SPEC and PLAN (MODE: PLANNING). Stop and wait for Dev approval at each.
 - When PLAN is approved, invoke the Agent tool to delegate CODE + TEST to Fast.
 - **Handoff prompt must include** (never omit):
   - The approved SPEC (goal, inputs/outputs, verification checklist)
@@ -45,7 +45,7 @@ Dev → Planning: SPEC + PLAN → [Dev approval]
 ## Fast Role — Responsibilities
 
 - Load only what is required for CODE: engineering standards, code style, idiom patterns.
-- Do not re-derive strategy. The SPEC and PLAN are the contract — follow them exactly.
+- Do not re-derive strategy. The SPEC and PLAN are the contract — follow them exactly (MODE: FAST).
 - Apply Narrative Gate before every function body.
 - Run tests and lint. Return a structured report: tasks completed, gate results, test status.
 - Do not proceed to END. Return control to Planning.
@@ -58,7 +58,7 @@ Planning invokes Fast using the Agent tool with `model: "sonnet"`:
 Agent({
   model: "sonnet",
   prompt: `
-    ## Role: Fast — CODE + TEST
+    ## Role: Fast — CODE + TEST — MODE: FAST
 
     You are the Fast agent. Execute only CODE and TEST phases.
     Do not plan, do not strategize. Follow the contract below exactly.
@@ -98,7 +98,7 @@ Any ❌ → Planning fixes inline or sends back to Fast for a targeted correctio
 **If the Agent tool is not available** (Gemini, Cursor, Windsurf, Cline, or any non-Claude Code environment):
 
 - Execute all phases as a single agent.
-- Apply Planning mindset during SPEC and PLAN (analytical, stop for approval).
-- Apply Fast mindset during CODE and TEST (operational, no strategic detours).
-- The role annotations in the workflow (`> **Role: Planning**`, `> **Role: Fast**`) serve as mindset cues — treat them as discipline markers, not execution boundaries.
+- Apply Planning mindset during SPEC and PLAN (MODE: PLANNING, stop for approval).
+- Apply Fast mindset during CODE and TEST (MODE: FAST, no strategic detours).
+- The mode annotations in the workflow (`MODE: PLANNING`, `MODE: FAST`) serve as mindset cues — treat them as discipline markers, not execution boundaries.
 - Proceed through END normally.

package/src/assets/instructions/core/caveman.md

@@ -8,8 +8,8 @@
 
 ## The Rules of the Caveman
 
-1. **Articles Die**: Remove "a", "an", "the" (EN) and "o", "a", "os", "as", "um", "uma" (PT).
-2. **Filler Die**: No "I'd be happy to", "Certamente", "Com certeza", "Claro". Start with the result.
+1. **Articles Die**: Remove "a", "an", "the".
+2. **Filler Die**: No "I'd be happy to", "Certainly", "Sure". Start with the result.
 3. **Hedging Die**: No "I think", "It seems", "Perhaps". State facts or code.
 4. **Fragments Allowed**: Use bullet points or short fragments. "Fix bug. Task done." > "I have fixed the bug and the task is now done."
 5. **Technical Integrity**: NEVER compress paths, code blocks, or identifiers. Code must remain elegant (Narrative Cascade).
@@ -17,7 +17,7 @@
 
 ## Example (Caveman Full)
 
-**Prompt**: "Como está o projeto?"
-**Response**: "Status: v1.10.4. Backlog: 2 itens. Contexto ok. Pronto comando."
+**Prompt**: "How is the project status?"
+**Response**: "Status: v1.10.4. Backlog: 2 items. Context ok. Ready for command."
 
 </ruleset>

package/src/assets/instructions/templates/workflow.md

@@ -20,139 +20,95 @@ On every request, classify intent before acting:
 
 ---
 
-## Phase: SPEC (The Contract)
-
-> **Role: Planning**
+## Phase: SPEC (The Contract) — MODE: PLANNING
 
 > <rule name="PhaseSPEC">
 > [!IMPORTANT]
 > Structure the intent before any implementation. **Stop and wait for approval.**
-
-### Instructions
-
-- **Goal:** One sentence summary.
-- **Domain:** Backend | Frontend | Fullstack.
-- **Inputs / Outputs:** Clearly defined contracts.
-- **Configuration Contract**: List all required environment variables with their purpose (keys must be **abstract**; no committed templates like `.env.example`).
-- **Specialization**:
-  - **Feat**: Focus on **Domain Modeling** and **Public Interfaces**.
-  - **Fix**: Focus on **Root Cause Analysis (RCA)** and **Reproduction Case**.
-  - **Docs**: Focus on **Structure and Accuracy** — select the appropriate template (CHANGELOG / FEAT / ADR) before drafting.
-- **Verification Checklist:** Binary pass/fail criteria (max 5 items).
-- **Hard Rule**: You **MUST STOP** and wait for explicit Developer approval before proceeding.
-  > </rule>
-
-## Phase: PLAN (The Strategy)
-
-> **Role: Planning**
+>
+> **Steps:**
+>
+> 1. **Intent Classification**: Reads the request and identifies the intent: `land:`, `feat:`, `fix:`, `docs:` or `end:`.
+> 2. **Goal Definition**: Writes one sentence describing what will be built and why.
+> 3. **Domain & Contracts**: Defines the domain (Backend / Frontend / Fullstack) and the inputs and outputs.
+> 4. **Verification Checklist**: Creates up to 5 yes/no checkpoints to confirm the work is done right.
+> 5. **Approval Gate**: Stops and waits for your approval before writing any code.
+>    </rule>
+
+## Phase: PLAN (The Strategy) — MODE: PLANNING
 
 > <rule name="PhasePLAN">
 > [!NOTE]
 > After spec is approved, produce a numbered task list ordered by logical execution sequence. **Stop and wait for approval.**
-
-### Instructions
-
-- **Action Verb + Object**: Each task must be atomic (e.g., "1. Create User repository").
-- **Logical Order**: Tasks must be sequenced so each step unblocks the next — foundation before consumers, contracts before implementations, data layer before orchestration.
-- **Effort Estimate**: Tag each task with a relative size — structural criteria are primary, time is a secondary reference:
-  - `[S]` — 1–2 files, isolated scope, no cross-layer tracing (≤ 5 min)
-  - `[M]` — 3–5 files, cross-layer impact, completes in one session (5–15 min)
-  - `[L]` — 6+ files or cross-session risk — **must** be split into sub-tasks (> 15 min)
-- **Task Decomposition**: Any task tagged `[L]` or that spans multiple layers **MUST** be split into numbered sub-tasks (e.g., `1.1`, `1.2`) to prevent context/token exhaustion.
-- **Backlog Sync**:
-  - `[M]` / `[L]`: write all tasks to `.ai-backlog/tasks.md` under `## Backlog` with `[TODO]`; move first to `## Active` as `[IN_PROGRESS]`.
-  - `[S]`: skip `tasks.md` — update only `context.md ## Now` at END.
-- **Hard Rule**: You **MUST STOP** and wait for explicit Developer approval before proceeding.
-  > </rule>
-
-## Phase: CODE (The Execution)
-
-> **Role: Fast**
+>
+> **Steps:**
+>
+> 1. **Task Breakdown**: Breaks the spec into concrete tasks. Each one starts with an action verb.
+> 2. **Logical Sequencing**: Orders tasks by dependency: what needs to exist first, goes first.
+> 3. **Effort Tagging**: Tags each task by size: `[S]` small · `[M]` medium · `[L]` large (must be split).
+> 4. **Sub-task Split**: Breaks every `[L]` task into numbered steps: 1.1, 1.2...
+> 5. **Backlog Sync**: Saves all tasks to `.ai-backlog/tasks.md` and marks the first one as in progress.
+> 6. **Approval Gate**: Stops and waits for your approval before writing any code.
+>    </rule>
+
+## Phase: CODE (The Execution) — MODE: FAST
 
 > <rule name="PhaseCODE">
 > [!IMPORTANT]
 > Follow the approved plan strictly.
-
-### Instructions
-
-- **Context Load**: Before writing any code, load based on domain scope:
-  - `engineering-standards.md` and `code-style.md` — always required
-  - `competencies/backend.md` — if domain includes backend
-  - `competencies/frontend.md` — if domain includes frontend
-  - `flavor/principles.md` — if architectural pattern is relevant to the task
-
-- **Narrative Gate (hard gate — output before writing each function)**:
-  Output this checklist with ✅/❌ before writing any function body.
-  Any ❌ = redesign first. This gate cannot be skipped or internalized.
-
-  _Structure_
-  - [ ] **Stepdown Rule** — entry point is topmost; callers above callees in the file
-  - [ ] **SLA** — this function orchestrates OR implements, never both in the same body
-  - [ ] **Guard Clauses** — all nested conditionals replaced with early returns
-  - [ ] **Lexical Scoping** — one-off helpers defined inside their only caller, not at module level
-
-  _Expression_
-  - [ ] **Explaining Returns** — return value assigned to a named `const`; no bare `return ok(...)` or anonymous inline objects
-  - [ ] **Shallow Boundaries** — no property chain deeper than 3 levels; extract a named `const` slice first
-  - [ ] **Vertical Density** — related variables grouped together; single blank line between logical blocks
-
-  _Naming_
-  - [ ] **Expressive Names** — every name reveals its role without needing a comment
-  - [ ] **Boolean Prefix** — `isLoading`, `hasError`, `isActive`; never bare `loading`, `error`, `active`
-  - [ ] **No Abbreviations** — `request`/`response`; never `req`/`res`; no framework exception
-
-  _Documentation_
-  - [ ] **Code as Documentation** — no "what" comments; only `// why:` for non-obvious constraints or deliberate trade-offs
-
-  _Module (per file)_
-  - [ ] **Revealing Module Pattern** — named object + named export at file footer; no `export default`
-  - [ ] **No God Modules** — no `helpers.js`, `utils.js`, `common.js`; name files by domain + operation
-
-- **Result Pattern**: Prefer `Result<T>` when it meaningfully clarifies the happy/failure split — do not force it where idiomatic error handling is already clear.
-- **YAGNI**: No features or refactors outside the approved SPEC.
-- **Blockers**: Surface issues immediately; do not work around them silently.
-  > </rule>
-
-## Phase: TEST (The Verification)
-
-> **Role: Fast**
+>
+> **Steps:**
+>
+> 1. **Context Load**: Reads the project's standards and style guide before writing anything (read `engineering-standards.md`, `code-style.md`, and competencies).
+> 2. **Quality Gate**: Reviews every function against the guide's readability rules before moving on.
+>
+> _Narrative Gate Checklist:_
+>
+> - [ ] **Stepdown Rule** — entry point is topmost; callers above callees in the file
+> - [ ] **SLA** — this function orchestrates OR implements, never both in same body
+> - [ ] **Guard Clauses** — all nested conditionals replaced with early returns
+> - [ ] **Lexical Scoping** — one-off helpers defined inside their only caller
+> - [ ] **Explaining Returns** — return value assigned to a named `const`; no bare returns
+> - [ ] **Boolean Prefix** — `isLoading`, `hasError`, `isActive`; never bare `loading`, `error`
+> - [ ] **Code as Documentation** — no "what" comments; only `// why:` for non-obvious constraints
+>
+> 3. **Plan Adherence**: Follows the agreed plan. No extra features or refactors outside what was approved.
+> 4. **Blocker Surface**: Raises blockers immediately. Never quietly works around them.
+>    </rule>
+
+## Phase: TEST (The Verification) — MODE: FAST
 
 > <rule name="PhaseTEST">
 > [!IMPORTANT]
 > Verify against the Verification Checklist.
-
-### Instructions
-
-- **Regression Focus**: For `fix:` cycles, the test MUST prove the bug no longer reproduces and no regressions exist.
-- **Fix Loop (max 3x)**: If any test FAILs, fix and re-run.
-- **Lint Fix**: After tests pass, run `lint --fix` (or equivalent) if a lint script is available in the project. Resolve all auto-fixable violations before leaving this phase. If non-auto-fixable violations remain, surface them explicitly.
-- **Reporting**: Report PASS/FAIL for every checklist item plus lint status. If still failing after 3 loops, STOP and report.
-  > </rule>
-
-## Phase: END (The Delivery)
-
-> **Role: Planning**
+>
+> **Steps:**
+>
+> 1. **Checklist Verification**: Goes through every item on the Spec's Verification Checklist.
+> 2. **Regression Check**: For `fix:` cycles: confirms the bug is gone and nothing else broke.
+> 3. **Fix Loop**: If something fails: fix and re-run. Up to 3 attempts before escalating.
+> 4. **Lint Fix**: Runs the linter and fixes what it can before wrapping up.
+> 5. **Report**: Reports the result of each checklist item and lint status before moving on.
+>    </rule>
+
+## Phase: END (The Delivery) — MODE: PLANNING
 
 > <rule name="PhaseEND">
 > [!NOTE]
 > Close the cycle and sync documentation. **No delivery without explicit curation and authorization.**
-
-### END Checklist (mandatory — execute in order, mark each before proceeding)
-
-- [ ] **SUMMARIZE** — one sentence per completed PLAN task written in response
-- [ ] **CHANGELOG** — Prepare your technical narrative in the `CHANGELOG.md` under `## [Unreleased]`. This MUST be done before bumping.
-- [ ] **BUMP** — run \`npm run bump <feat|fix>\` to promote CHANGELOG and package.json version. Skip if not applicable.
-- [ ] **BACKLOG: tasks.md** — all completed tasks moved to `## Done` with `[DONE]` status
-- [ ] **BACKLOG: context.md** — \`## Now\` updated with next objective or cleared
-- [ ] **KNOWLEDGE** — Log any patterns, findings, or rework discovered during this cycle. Update \`.ai-backlog/learned.md\` (for successful feats) or \`.ai-backlog/troubleshoot.md\` (for fixed incidents). Curate stale or irrelevant items.
-- [ ] **CURATE** — final scan for slop, "AI-isms", and unfinished comments. Run `git status` to ensure only intended changes are staged.
-- [ ] **LINT** — if lint script exists (`lint`, `lint:fix`, `lint:all`, or config file detected), run it; auto-fix what's possible; block commit if errors remain
-- [ ] **COMMIT** — **PROPOSE** the commit message and **WAIT** for explicit Developer approval
-- [ ] **PUSH** — **ASK** for explicit permission before pushing to remote
-
+>
+> **Steps:**
+>
+> 1. **Task Summary**: Writes one sentence per completed task.
+> 2. **Changelog**: Adds a narrative entry under `## [Unreleased]`.
+> 3. **Zero-Leak Staging**: Runs `git add .` to capture all side-effects and metadata.
+> 4. **Context Resilience**: Updates `context.md` (or bootstraps it if missing).
+> 5. **Self-Healing Quality**: Runs linting and attempts auto-repair (`lint --fix`) if needed.
+> 6. **Release (Audit & Commit)**: Runs `npm run bump <feat|fix>`, performs a final workspace audit, and proposes a semantic release commit.
+> 7. **Final Delivery**: Proposes `git push` and a fresh session.
+>
 > [!WARNING]
-> Do NOT consider the cycle closed until every applicable item above is checked.
-> If any item is skipped, the cycle is **INCOMPLETE** — return and complete it before accepting new work.
+> Do NOT perform `git commit` or `git push` autonomously. Always **PROPOSE** and **WAIT**.
 > </rule>
 
 ## Rule: Task Handoff (Cross-Session & Cross-Agent Continuity)
@@ -219,6 +175,9 @@ When a message arrives during an active cycle, classify it before acting:
 | **Pivot**                    | "change the approach entirely"            | Return to SPEC, revise, wait for re-approval                                  |
 | **Unrelated request**        | "fix this other thing while you're at it" | Flag it as out-of-scope. Finish the current cycle first, then start a new one |
 
+**State Recovery**: After any conversational interruption, explicitly state your current position before continuing.
+_Example: "Resuming Cycle Feat — Phase: SPEC — Step 3 (Domain & Contracts)."_
+
 **Hard Rule**: Never interpret a conversational message as a new `land:`, `feat:`, or `fix:` while a cycle is active. The cycle closes only at END.
 
 > </rule>

package/src/engine/bin/check-narrative.mjs

@@ -7,7 +7,6 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
-
 import { execSync } from 'node:child_process';
 
 const PROJECT_ROOT = process.cwd();
@@ -17,6 +16,22 @@ async function run() {
   const isPrePush = process.argv.includes('--pre-push');
   const commitMsgFile = isPrePush ? null : process.argv[2];
 
+  let changelog = '';
+  try {
+    // Read STAGED version of CHANGELOG.md (if possible)
+    changelog = execSync('git show :CHANGELOG.md', {
+      stdio: ['pipe', 'pipe', 'ignore'],
+    }).toString();
+  } catch {
+    if (fs.existsSync(CHANGELOG_PATH)) {
+      changelog = fs.readFileSync(CHANGELOG_PATH, 'utf8');
+    }
+  }
+
+  if (!changelog) {
+    process.exit(0);
+  }
+
   if (!isPrePush) {
     if (!commitMsgFile) {
       console.error('  ❌ Error: No commit message file provided.');
@@ -30,29 +45,49 @@ async function run() {
     const commitMsg = fs.readFileSync(commitMsgFile, 'utf8').trim();
     const firstLine = commitMsg.split('\n')[0].trim();
 
-    // ONLY target feat: and fix: (SDG Cycle Triggers) as per maintainer instruction
+    // ONLY target feat: and fix: (SDG Cycle Triggers)
     const isSdgTrigger = /^feat:/.test(firstLine) || /^fix:/.test(firstLine);
     if (!isSdgTrigger) {
       process.exit(0);
     }
-  }
 
-  let changelog = '';
-  try {
-    // Read STAGED version of CHANGELOG.md (if possible)
-    changelog = execSync('git show :CHANGELOG.md', {
-      stdio: ['pipe', 'pipe', 'ignore'],
-    }).toString();
-  } catch {
-    if (fs.existsSync(CHANGELOG_PATH)) {
-      changelog = fs.readFileSync(CHANGELOG_PATH, 'utf8');
-    }
-  }
+    // RELEASE CONTEXT DETECTION
+    const isReleaseCommit = firstLine.toLowerCase().includes('release');
+    const releaseVersionMatch = firstLine.match(/v?(\d+\.\d+\.\d+)/);
+    const releaseVersion = releaseVersionMatch ? releaseVersionMatch[1] : null;
 
-  if (!changelog) {
-    process.exit(0);
+    if (isReleaseCommit && releaseVersion) {
+      const versionHeaderRegex = new RegExp(
+        `##\\s*\\[${releaseVersion}\\].*?\\n([\\s\\S]*?)(?=\\n##\\s|(?:\\n){0,1}$)`,
+        'i'
+      );
+      const versionMatch = changelog.match(versionHeaderRegex);
+
+      if (!versionMatch) {
+        console.error(
+          `\n  ❌ NARRATIVE VIOLATION: Version header "## [${releaseVersion}]" not found in CHANGELOG.md.`
+        );
+        process.exit(1);
+      }
+
+      const versionNarrative = versionMatch[1]
+        .replace(/###\s*(Added|Fixed|Changed|Removed|Security|Deprecated)/gi, '')
+        .replace(/<!--[\s\S]*?-->/g, '')
+        .trim();
+
+      if (versionNarrative.length < 3) {
+        console.error(
+          `\n  ❌ NARRATIVE VIOLATION: Version header "## [${releaseVersion}]" has no narrative.`
+        );
+        process.exit(1);
+      }
+
+      console.log(`  ✅ Narrative Guard: Release v${releaseVersion} validated.`);
+      process.exit(0);
+    }
   }
 
+  // STANDARD NARRATIVE CHECK (Unreleased)
   const unreleasedMatch = changelog.match(
     /##\s*\[Unreleased\].*?\n([\s\S]*?)(?=\n##\s|(?:\n){0,1}$)/i
   );
@@ -96,4 +131,3 @@ run().catch((err) => {
   console.error('  ❌ Narrative Guard Exception:', err.message);
   process.exit(1);
 });
-// test