@the-bearded-bear/claude-craft 8.23.3 → 8.26.0-next.2a54921

package/Project/i18n/pt/templates/sprint-status.md

@@ -0,0 +1,60 @@
+# Esquema do Sprint Status (`.bmad/sprint-status.yaml`)
+
+`.bmad/sprint-status.yaml` é a **fonte única de verdade para o STATUS das stories e das tarefas**. Os arquivos markdown (`US-*.md`, `EPIC-*.md`, `TASK-*.md`, `board.md`) contêm **apenas conteúdo**: nenhum campo de status, nenhum emoji de status. O status de um epic é **derivado** dos status de suas stories (nunca armazenado).
+
+- Status das stories: `backlog | ready-for-dev | in-progress | review | done | blocked`
+- Status das tarefas: `to-do | in-progress | done | blocked`
+- As transições de stories seguem a máquina de estados BMAD (ver `/project:backlog move story`).
+
+```yaml
+# .bmad/sprint-status.yaml
+version: "1.0"
+metadata:
+  sprint_id: "sprint-2"
+  name: "Gestão de usuários"
+  start_date: "2026-11-02"
+  end_date: "2026-11-13"
+  goal: "Os usuários podem se cadastrar, entrar e editar seu perfil"
+  capacity_points: 21
+stories:
+  US-010:
+    title: "Cadastro de usuário"
+    status: "in-progress"
+    previous_status: "ready-for-dev"
+    tdd_phase: "green"
+    story_points: 5
+    epic_id: "EPIC-002"
+    priority: "must"
+    dependencies: ["US-001"]
+    tasks:
+      total: 2
+      completed: 1
+      list: ["TASK-001", "TASK-002"]
+      status:
+        TASK-001: "done"
+        TASK-002: "in-progress"
+    history:
+      - timestamp: "2026-11-02T09:00:00Z"
+        from: "ready-for-dev"
+        to: "in-progress"
+        by: "dev"
+        reason: "Implementação iniciada"
+archived_sprints:
+  sprint-1:
+    stories:
+      US-001: { status: "done", points: 5 }
+routing:
+  auto_transitions:
+    enabled: true
+    run_on_session_start: false
+    run_on_task_complete: true
+    rules: []
+```
+
+## Regras
+
+- O conteúdo (título, descrição, critérios de aceitação, detalhes das tarefas) é escrito nos arquivos markdown; o status é escrito somente neste arquivo.
+- `tasks.completed` é o número de tarefas cujo status é `done`; `tasks.total` é o tamanho de `tasks.list`.
+- Toda transição de story atualiza `status` e `previous_status` e adiciona uma entrada em `history` (`timestamp`, `from`, `to`, `by`, `reason`).
+- O status do epic é calculado a partir de suas stories (todas `backlog` = não iniciado, qualquer outra não `done` = em andamento, todas `done` = concluído); nunca é escrito em lugar algum.
+- Se o arquivo não existir, criá-lo a partir do esqueleto de `/workflow:init` antes de escrever.

package/Project/i18n/pt/templates/task.md

@@ -4,7 +4,7 @@
 - **ID**: TASK-{ID}
 - **US**: {US_ID}
 - **Tipo**: {TYPE}
-- **Status**: 🔴 To Do
+- **Status**: acompanhado em .bmad/sprint-status.yaml
 - **Estimativa**: {ESTIMATION}h
 - **Tempo gasto**: 0h
 - **Criado em**: {DATE}

package/Project/i18n/pt/templates/user-story.md

@@ -4,14 +4,14 @@
 - **ID**: US-{ID}
 - **EPIC**: {EPIC_ID}
 - **Sprint**: {SPRINT}
-- **Status**: 🔴 To Do
+- **Status**: acompanhado em .bmad/sprint-status.yaml
 - **Pontos**: {POINTS}
 - **Persona**: {PERSONA_ID}
 - **Criado em**: {DATE}
 - **Atualizado**: {DATE}
 
 ## Rastreabilidade
-- **Implementa**: {FR-001, FR-003} <!-- IDs dos requisitos PRD que esta story implementa -->
+- **Implements**: {FR-001, FR-003} <!-- IDs dos requisitos PRD que esta story implementa -->
 - **Depende de**: {US-xxx} <!-- Stories que devem ser concluídas primeiro -->
 - **Spec Técnica**: {section_reference} <!-- Referência à seção da spec técnica -->
 
@@ -39,13 +39,15 @@ ENTÃO {resultado esperado}
 
 ## Tarefas
 
-| ID | Tipo | Descrição | Status | Estimativa |
-|----|------|-----------|--------|------------|
-| - | - | - | 🔴 | - |
+| ID | Tipo | Descrição | Estimativa |
+|----|------|-----------|------------|
+| - | - | - | - |
+
+_Os status das tarefas são acompanhados em `.bmad/sprint-status.yaml`._
 
 ## Progresso
 
-0/0 tarefas concluídas (0%)
+0/0 tarefas concluídas (0%) <!-- derivado de .bmad/sprint-status.yaml -->
 
 ## Definition of Done
 

package/Project/install-project-commands.sh

@@ -119,6 +119,9 @@ if [ -d "$GATE_CMD_SRC" ]; then
     ui_success "$GATE_COUNT gate commands copied"
 fi
 
+# Delete commands retired from the distribution (config/removed-commands.yaml)
+bash "$SCRIPT_DIR/../Dev/scripts/prune-removed-commands.sh" "$PROJECT_DIR"
+
 # Copy agents from i18n source
 AGT_SRC="$SRC_DIR/agents"
 if [ ! -d "$AGT_SRC" ]; then
@@ -195,20 +198,12 @@ echo "   /project:decompose-tasks [N]   - Décomposer sprint N en tâches"
 echo "   /project:generate-prd          - Générer le PRD"
 echo "   /project:generate-tech-spec    - Générer la spécification technique"
 echo ""
-echo "   EPICs (/project:) :"
-echo "   /project:add-epic              - Créer un EPIC"
-echo "   /project:list-epics            - Lister les EPICs"
-echo "   /project:update-epic           - Modifier un EPIC"
-echo ""
-echo "   User Stories (/project:) :"
-echo "   /project:add-story             - Créer une User Story"
-echo "   /project:list-stories          - Lister les US"
-echo "   /project:update-story          - Modifier une US"
-echo ""
-echo "   Tasks (/project:) :"
-echo "   /project:add-task              - Créer une tâche"
-echo "   /project:list-tasks            - Lister les tâches"
-echo "   /project:move-task             - Changer le statut"
+echo "   Backlog et analyse (/project:) :"
+echo "   /project:backlog add|list|edit|move epic|story|task - Gérer le backlog"
+echo "   /project:reverse [scan|prd|stories|gaps|all]       - Rétro-ingénierie (brownfield)"
+echo "   /project:trace [--gaps] [--by-priority]            - Traçabilité exigences → code → tests"
+echo "   /project:report burndown|metrics|deps              - Burndown, métriques, dépendances"
+echo "   /project:migrate [--analyze|--resync|--stories]    - Migration vers BMAD v6"
 echo ""
 echo "   Visualisation (/project:) :"
 echo "   /project:board                 - Kanban du sprint"
@@ -224,12 +219,9 @@ echo "   /sprint:auto-route             - Routage automatique"
 echo "   /sprint:dev                    - Développer une story"
 echo ""
 echo "   Quality Gates (/gate:) :"
-echo "   /gate:validate-backlog         - Valider la conformité SCRUM"
-echo "   /gate:validate-prd             - Valider le PRD"
-echo "   /gate:validate-techspec        - Valider la spécification technique"
-echo "   /gate:validate-story           - Valider une User Story (DoD)"
-echo "   /gate:validate-sprint          - Valider un sprint"
-echo "   /gate:report                   - Rapport de qualité"
+echo "   /gate:check prd|spec|backlog|sprint|story|alignment - Portes documentaires"
+echo "   /gate:check commit|merge|release                    - Portes de code"
+echo "   /gate:check all | --phase=<phase>                   - Rapport complet / checkpoint"
 echo ""
 echo "🤖 Agents disponibles :"
 echo "   @po   - Product Owner (backlog, US, priorisation)"
@@ -239,9 +231,9 @@ echo "📁 Structure créée :"
 echo "   $PROJECT_DIR/"
 echo "   ├── CLAUDE.md"
 echo "   ├── .claude/"
-echo "   │   ├── commands/project/    (22 commandes)"
-echo "   │   ├── commands/sprint/     (5 commandes)"
-echo "   │   ├── commands/gate/       (6 commandes)"
+echo "   │   ├── commands/project/"
+echo "   │   ├── commands/sprint/"
+echo "   │   ├── commands/gate/"
 echo "   │   ├── agents/              (2 agents)"
 echo "   │   └── templates/project/   (5 templates)"
 echo "   └── project-management/"
@@ -255,11 +247,11 @@ echo ""
 echo "🚀 Pour commencer :"
 echo "   cd $PROJECT_DIR"
 echo "   claude"
-echo "   > /project:add-epic \"Mon premier EPIC\""
+echo "   > /project:backlog add epic \"Mon premier EPIC\""
 echo ""
 echo "📊 Workflow strict des statuts :"
-echo "   🔴 To Do → 🟡 In Progress → 🟢 Done"
-echo "   (⏸️ Blocked possible à tout moment)"
+echo "   backlog → ready-for-dev → in-progress → review → done"
+echo "   (blocked possible à tout moment ; statut dans .bmad/sprint-status.yaml)"
 else
 echo "✅ Installation complete!"
 echo ""
@@ -271,20 +263,12 @@ echo "   /project:decompose-tasks [N]   - Break sprint N into tasks"
 echo "   /project:generate-prd          - Generate the PRD"
 echo "   /project:generate-tech-spec    - Generate the technical spec"
 echo ""
-echo "   EPICs (/project:):"
-echo "   /project:add-epic              - Create an EPIC"
-echo "   /project:list-epics            - List EPICs"
-echo "   /project:update-epic           - Edit an EPIC"
-echo ""
-echo "   User Stories (/project:):"
-echo "   /project:add-story             - Create a User Story"
-echo "   /project:list-stories          - List User Stories"
-echo "   /project:update-story          - Edit a User Story"
-echo ""
-echo "   Tasks (/project:):"
-echo "   /project:add-task              - Create a task"
-echo "   /project:list-tasks            - List tasks"
-echo "   /project:move-task             - Change status"
+echo "   Backlog and analysis (/project:):"
+echo "   /project:backlog add|list|edit|move epic|story|task - Manage the backlog"
+echo "   /project:reverse [scan|prd|stories|gaps|all]       - Reverse engineering (brownfield)"
+echo "   /project:trace [--gaps] [--by-priority]            - Requirements → code → tests traceability"
+echo "   /project:report burndown|metrics|deps              - Burndown, metrics, dependencies"
+echo "   /project:migrate [--analyze|--resync|--stories]    - Migrate to BMAD v6"
 echo ""
 echo "   Visualization (/project:):"
 echo "   /project:board                 - Sprint Kanban"
@@ -300,12 +284,9 @@ echo "   /sprint:auto-route             - Automatic routing"
 echo "   /sprint:dev                    - Develop a story"
 echo ""
 echo "   Quality Gates (/gate:):"
-echo "   /gate:validate-backlog         - Validate SCRUM compliance"
-echo "   /gate:validate-prd             - Validate the PRD"
-echo "   /gate:validate-techspec        - Validate the technical spec"
-echo "   /gate:validate-story           - Validate a User Story (DoD)"
-echo "   /gate:validate-sprint          - Validate a sprint"
-echo "   /gate:report                   - Quality report"
+echo "   /gate:check prd|spec|backlog|sprint|story|alignment - Document gates"
+echo "   /gate:check commit|merge|release                    - Code gates"
+echo "   /gate:check all | --phase=<phase>                   - Full report / checkpoint"
 echo ""
 echo "🤖 Available agents:"
 echo "   @po   - Product Owner (backlog, User Stories, prioritization)"
@@ -315,9 +296,9 @@ echo "📁 Structure created:"
 echo "   $PROJECT_DIR/"
 echo "   ├── CLAUDE.md"
 echo "   ├── .claude/"
-echo "   │   ├── commands/project/    (22 commands)"
-echo "   │   ├── commands/sprint/     (5 commands)"
-echo "   │   ├── commands/gate/       (6 commands)"
+echo "   │   ├── commands/project/"
+echo "   │   ├── commands/sprint/"
+echo "   │   ├── commands/gate/"
 echo "   │   ├── agents/              (2 agents)"
 echo "   │   └── templates/project/   (5 templates)"
 echo "   └── project-management/"
@@ -331,9 +312,9 @@ echo ""
 echo "🚀 Getting started:"
 echo "   cd $PROJECT_DIR"
 echo "   claude"
-echo "   > /project:add-epic \"My first EPIC\""
+echo "   > /project:backlog add epic \"My first EPIC\""
 echo ""
 echo "📊 Strict status workflow:"
-echo "   🔴 To Do → 🟡 In Progress → 🟢 Done"
-echo "   (⏸️ Blocked possible at any time)"
+echo "   backlog → ready-for-dev → in-progress → review → done"
+echo "   (blocked possible at any time; status in .bmad/sprint-status.yaml)"
 fi

package/README.md

@@ -26,7 +26,23 @@ Plus **11 stack-specific reviewers** (@symfony-reviewer, @react-reviewer, @pytho
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Mutation testing badge](https://img.shields.io/endpoint?style=flat&url=https%3A%2F%2Fbadge-api.stryker-mutator.io%2Fgithub.com%2FTheBeardedBearSAS%2Fclaude-craft%2Fmain)](https://dashboard.stryker-mutator.io/reports/github.com/TheBeardedBearSAS/claude-craft/main)
 
-A comprehensive framework for AI-assisted development with [Claude Code](https://claude.ai/code). Install standardized rules, agents, and commands for your projects across multiple technology stacks — **33 specialized agents (+39 infra agents on-demand), 140 commands across 17 namespaces (234 total), 55 skills**, all token-optimized via `context: fork` and sub-agent model routing.
+A comprehensive framework for AI-assisted development with [Claude Code](https://claude.ai/code). Install standardized rules, agents, and commands for your projects across multiple technology stacks — **33 specialized agents (+39 infra agents on-demand), 139 commands across 17 namespaces (238 total, including deprecated redirect stubs kept until 9.0), 55 skills**, all token-optimized via `context: fork` and sub-agent model routing.
+
+## What's New in v8.26.0
+
+**Un parcours principal pour la gestion de projet (2026-10-26, v8.26.0) :** `/workflow:init → plan → design → start → implement → review → retro` (+ `/workflow:status` à tout moment, `/workflow:auto-sprint` de bout en bout). Le namespace `/sprint:` et les générateurs `/project:*` deviennent des stubs de redirection jusqu'en 9.0. Il reste 35 commandes de gestion de projet actives au lieu de 86. Guide : [Quel parcours ?](docs/guides/en/11-which-path.md). Détails : [CHANGELOG](CHANGELOG.md#8260---2026-10-26).
+
+## What's New in v8.25.0
+
+**Fusion des commandes `/project:` et `/gate:` (2026-10-26, v8.25.0) :** 5 commandes `/project:` (`backlog`, `reverse`, `trace`, `report`, `migrate`) et une seule `/gate:check` remplacent 41 commandes ; les anciennes restent des stubs de redirection jusqu'en 9.0. Détails : [CHANGELOG](CHANGELOG.md#8250---2026-10-26).
+
+## What's New in v8.24.0
+
+**Source de vérité unique du statut (2026-10-26, v8.24.0) :** `.bmad/sprint-status.yaml` porte désormais seul le statut des stories et des tâches. Les fichiers markdown ne portent que le contenu, et le Kanban écrit les déplacements dans la YAML. Nouveau guide [Quel parcours ?](docs/guides/en/11-which-path.md). Les commandes retirées sont désormais supprimées à l'upgrade (`config/removed-commands.yaml`), et les commandes mainteneur ne sont plus installées dans les projets. Détails : [CHANGELOG](CHANGELOG.md#8240---2026-10-26).
+
+## What's New in v8.23.4
+
+**Cohérence des commandes de gestion de projet (2026-10-26, v8.23.4) :** 65 références vers des commandes inexistantes corrigées dans les 5 langues (nouveau garde-fou CI `command-refs.test.mjs`) ; gates alignées sur `project-management/` ; arborescence de sprint unique (`board.md` + `tasks/TASK-*.md`) ; `/workflow:init` crée `.bmad/sprint-status.yaml` ; `/workflow:auto-sprint` démarre un sprint inexistant. Détails : [CHANGELOG](CHANGELOG.md#8234---2026-10-26).
 
 ## What's New in v8.23.3
 
@@ -45,7 +61,7 @@ A comprehensive framework for AI-assisted development with [Claude Code](https:/
 
 - **Installation adaptée à la stack** : `--tech=a,b,c` rend le `CLAUDE.md` racine, `AGENTS.md` et `.claude/settings.json` selon les technos réellement installées ; `install-project-commands.sh` n'écrase plus les fichiers existants ; `@tech-lead` agnostique de la stack ; `make config-*` et `check-config.sh` réparés.
 - **Kanban** : lecture des backlogs générés depuis les templates (métadonnées en liste Markdown), plus de documents dupliqués, retrait complet des commentaires HTML imbriqués (alerte CodeQL).
-- **Workflow** : `/workflow:start` crée `.bmad/sprint-status.yaml`, `/gate:validate-sprint` fonctionne sans lui. Dépendances et GitHub Actions à jour. Détails : [CHANGELOG](CHANGELOG.md#8231---2026-10-22).
+- **Workflow** : `/workflow:start` crée `.bmad/sprint-status.yaml`, `/gate:check sprint` fonctionne sans lui. Dépendances et GitHub Actions à jour. Détails : [CHANGELOG](CHANGELOG.md#8231---2026-10-22).
 
 ## What's New in v8.23.0
 
@@ -242,10 +258,10 @@ These are the commands you'll use most:
 |---------|-------------|
 | `/workflow:init` | Start a development workflow (auto-detects track) |
 | `/team:audit` | Full project audit (architecture, security, quality) |
-| `/common:pre-commit-check` | Validate before committing |
-| `/sprint:next-story` | Get next story ready for development |
+| `/gate:check commit` | Validate before committing |
+| `/project:backlog next story` | Get next story ready for development |
 | `/qa:tdd` | Test-Driven Development flow |
-| `/gate:validate-story` | Check story meets Definition of Done |
+| `/gate:check story` | Check story meets Definition of Done |
 | `/{tech}:check-architecture` | Verify architecture compliance |
 | `/{tech}:generate-*` | Generate code following project patterns |
 | `/common:ralph-run "task"` | Run Claude in continuous loop until task is done |
@@ -329,6 +345,7 @@ Context usage is optimized: ~3,500 tokens always loaded vs ~70,000 if everything
 |----------|-------------|
 | [Quickstart](docs/QUICKSTART.md) | Get results in 10 minutes |
 | [**Tutorial: Complete Workflow**](docs/guides/en/10-complete-workflow.md) | End-to-end narrated walkthrough: idea → backlog → sprint → ship |
+| [**Which path?**](docs/guides/en/11-which-path.md) | Decision page: greenfield, brownfield, bugfix or autonomous sprint |
 | [Learning Paths](docs/LEARNING-PATHS.md) | Beginner → Intermediate → Advanced progression |
 | [Installation](docs/INSTALLATION.md) | All installation methods |
 | [Configuration](docs/CONFIGURATION.md) | Project configuration |

package/Tools/Ralph/README.md

@@ -67,8 +67,8 @@ npx @the-bearded-bear/claude-craft ralph --continue=ralph-1704067200-a1b2
 /common:ralph-run "Implement user authentication"
 
 # Autonomous sprint (via team-sprint)
-/common:team-sprint --ralph-mode "Sprint 3" --overnight
-/common:team-sprint --ralph-mode "Sprint 3" --parallel 3 --overnight
+/team:sprint --ralph-mode "Sprint 3" --overnight
+/team:sprint --ralph-mode "Sprint 3" --parallel 3 --overnight
 ```
 
 ### Direct Script
@@ -637,7 +637,7 @@ definition_of_done:
 
 ```bash
 # In sprint workflow
-/project:sprint-dev 1
+/workflow:implement 1
 # Ralph handles each task until DoD passes
 ```
 
@@ -702,13 +702,13 @@ The ASC enables overnight/unattended sprint execution:
 
 ```bash
 # Overnight sprint
-/common:team-sprint --ralph-mode "Sprint 3" --overnight
+/team:sprint --ralph-mode "Sprint 3" --overnight
 
 # Parallel processing
-/common:team-sprint --ralph-mode "Sprint 3" --parallel 3 --overnight
+/team:sprint --ralph-mode "Sprint 3" --parallel 3 --overnight
 
 # Supervised mode
-/common:team-sprint --ralph-mode "Sprint 3" --supervised
+/team:sprint --ralph-mode "Sprint 3" --supervised
 ```
 
 ### Components
@@ -732,10 +732,10 @@ The ASC enables overnight/unattended sprint execution:
 ## Related
 
 - `/common:ralph-run` - Command to start Ralph from Claude Code
-- `/common:team-sprint --ralph-mode` - Autonomous Sprint Conductor
+- `/team:sprint --ralph-mode` - Autonomous Sprint Conductor
 - `@ralph-conductor` - Agent for Ralph orchestration
-- `/common:fix-bug-tdd` - TDD-based bug fixing
-- `/project:sprint-dev` - Sprint development with TDD
+- `/qa:tdd` - TDD-based bug fixing
+- `/workflow:implement` - Sprint development with TDD
 
 ## Credits
 

package/bundles/cursor/.cursorrules

@@ -8,9 +8,9 @@
 
 # Claude-Craft - Multi-Technology Framework
 
-**Version:** 8.23.3 | **Languages:** en, fr, es, de, pt
+**Version:** 8.26.0 | **Languages:** en, fr, es, de, pt
 
-A comprehensive AI-assisted development framework for Claude Code with 13 technology stacks, 33 specialized agents (+39 infra agents on-demand), 140 commands across 17 namespaces, and BMAD v6 project management.
+A comprehensive AI-assisted development framework for Claude Code with 13 technology stacks, 33 specialized agents (+39 infra agents on-demand), 139 commands across 17 namespaces, and BMAD v6 project management.
 
 ---
 

package/bundles/windsurf/.windsurfrules

@@ -8,9 +8,9 @@
 
 # Claude-Craft - Multi-Technology Framework
 
-**Version:** 8.23.3 | **Languages:** en, fr, es, de, pt
+**Version:** 8.26.0 | **Languages:** en, fr, es, de, pt
 
-A comprehensive AI-assisted development framework for Claude Code with 13 technology stacks, 33 specialized agents (+39 infra agents on-demand), 140 commands across 17 namespaces, and BMAD v6 project management.
+A comprehensive AI-assisted development framework for Claude Code with 13 technology stacks, 33 specialized agents (+39 infra agents on-demand), 139 commands across 17 namespaces, and BMAD v6 project management.
 
 ---
 

package/cli/kanban/server/app.js

@@ -8,7 +8,7 @@ import fs from 'node:fs';
 import { csrfGuard, readonlyGuard, resolveSafe } from './middleware/security.js';
 import { validateTransition, validateUnblock, computeTransitionPatch } from './services/state-machine.js';
 import { updateFrontmatter, LockedError, MtimeMismatchError } from './services/file-writer.js';
-import { loadSprintStatus, computeBurndown } from './services/sprint-cache.js';
+import { loadSprintStatus, computeBurndown, updateSprintStatusStory } from './services/sprint-cache.js';
 import { TransitionRequestSchema } from '../shared/schemas.js';
 
 /**
@@ -86,8 +86,8 @@ export function createApp({ repository, port, readonly = false, eventBus = null,
     const filepath = repository.getStoryFile(id);
     const story = repository.getStory(id);
     if (!story) return c.json({ error: 'not_found' }, 404);
-    // YAML-only story (BMAD v6 single-writer) or metadata-list markdown (no
-    // frontmatter): no frontmatter to rewrite safely.
+    // Metadata-list markdown (no frontmatter) not tracked in sprint-status.yaml:
+    // no frontmatter to rewrite safely.
     if (!story._writable) {
       return c.json(
         {
@@ -146,7 +146,12 @@ export function createApp({ repository, port, readonly = false, eventBus = null,
 
     const patch = computeTransitionPatch(story, target, { blocked_reason });
     try {
-      await updateFrontmatter(filepath, patch, { expectedMtime: story._mtime });
+      // sprint-status.yaml is the source of truth for status whenever it tracks the story.
+      if (story._statusSource === 'sprint-status') {
+        await updateSprintStatusStory(resolvedProjectRoot, id, patch);
+      } else {
+        await updateFrontmatter(filepath, patch, { expectedMtime: story._mtime });
+      }
       await repository.refresh();
       const fresh = repository.getStory(id);
       if (eventBus) eventBus.publish('story:updated', { id, story: fresh });

package/cli/kanban/server/services/repository.js

@@ -128,10 +128,11 @@ export class Repository {
   }
 
   /**
-   * Overlay stories declared in <projectRoot>/.bmad/sprint-status.yaml that have
-   * no backing markdown file. Markdown-backed stories (already in this.stories)
-   * always win — the YAML entry is ignored for a colliding id so there is no
-   * double source of truth. Synthetic stories are read-only (path === null).
+   * .bmad/sprint-status.yaml is the single source of truth for story STATUS;
+   * markdown files hold the CONTENT. For an id present in both, the markdown
+   * entry keeps its content and takes its status fields from the YAML. Ids
+   * only present in the YAML become synthetic stories (no backing file).
+   * Either way the status is written back to the YAML (statusSource).
    */
   async #ingestSprintStatusStories() {
     const ss = await this.#loadStatusOnce();
@@ -141,12 +142,26 @@ export class Repository {
     const epicFromMeta = ss.metadata?.epic ?? null;
 
     for (const [id, s] of Object.entries(ss.stories)) {
-      if (this.stories.has(id)) continue; // markdown-backed story wins
+      const existing = this.stories.get(id);
+      if (existing) {
+        if (existing.ok) {
+          existing.data = {
+            ...existing.data,
+            status: s.status,
+            previous_status: s.previous_status ?? '',
+            tdd_phase: s.tdd_phase ?? existing.data.tdd_phase ?? '',
+            blocked_reason: s.blocked_reason ?? '',
+          };
+          existing.statusSource = 'sprint-status';
+        }
+        continue;
+      }
       this.stories.set(id, {
-        path: null, // no backing file -> read-only
+        path: null, // no backing file: content is the YAML entry only
         mtime: 0,
         ok: true,
         source: 'sprint-status',
+        statusSource: 'sprint-status',
         data: {
           id,
           title: s.title ?? id,
@@ -218,7 +233,7 @@ export class Repository {
       if (sprintId && d.sprint_id !== sprintId) continue;
       if (status && d.status !== status) continue;
       if (epicId && d.epic_id !== epicId) continue;
-      out.push({ ...d, _mtime: entry.mtime, _source: entry.source ?? 'markdown', _writable: isWritable(entry) });
+      out.push(view(entry));
     }
     return out.sort((a, b) => a.id.localeCompare(b.id));
   }
@@ -230,7 +245,7 @@ export class Repository {
   getStory(id) {
     const entry = this.stories.get(id);
     if (!entry || !entry.ok) return null;
-    return { ...entry.data, _mtime: entry.mtime, _source: entry.source ?? 'markdown', _writable: isWritable(entry) };
+    return view(entry);
   }
 
   getStoryFile(id) {
@@ -308,9 +323,21 @@ function sourceOf(res) {
 }
 
 function isWritable(entry) {
+  if (entry.statusSource === 'sprint-status') return true;
   return entry.path !== null && entry.source !== 'markdown-metadata';
 }
 
+function view(entry) {
+  const source = entry.source ?? 'markdown';
+  return {
+    ...entry.data,
+    _mtime: entry.mtime,
+    _source: source,
+    _statusSource: entry.statusSource ?? source,
+    _writable: isWritable(entry),
+  };
+}
+
 export function detectCycles(nodes, edges) {
   const adj = new Map();
   for (const n of nodes) adj.set(n.id, []);

package/cli/kanban/server/services/sprint-cache.js

@@ -1,7 +1,8 @@
 import path from 'node:path';
-import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { readFile, writeFile, mkdir, open, rename, unlink } from 'node:fs/promises';
 import * as yaml from 'js-yaml';
 import { SprintStatusSchema } from '../../shared/schemas.js';
+import { LockedError } from './file-writer.js';
 
 /**
  * Load sprint status from .bmad/sprint-status.yaml
@@ -27,6 +28,49 @@ export async function loadSprintStatus(projectRoot) {
   }
 }
 
+/**
+ * Apply a status transition to one story of .bmad/sprint-status.yaml (the
+ * single source of truth for status) and append it to the story history.
+ * Other keys of the file are preserved; YAML comments are not.
+ * @param {string} projectRoot - Parent of project-management/ directory
+ * @param {string} id - Story id (key of `stories`)
+ * @param {object} patch - Fields from computeTransitionPatch()
+ * @param {{ by?: string, now?: string }} [opts]
+ * @returns {Promise<object>} The updated story entry
+ */
+export async function updateSprintStatusStory(projectRoot, id, patch, opts = {}) {
+  const yamlPath = path.join(projectRoot, '.bmad', 'sprint-status.yaml');
+  const lockPath = `${yamlPath}.lock`;
+  const fd = await open(lockPath, 'wx').catch((err) => {
+    if (err.code === 'EEXIST') throw new LockedError(yamlPath);
+    throw err;
+  });
+  await fd.close();
+  try {
+    const doc = yaml.load(await readFile(yamlPath, 'utf8'));
+    const story = doc?.stories?.[id];
+    if (!story) throw new Error(`story ${id} not found in ${yamlPath}`);
+    const from = story.status;
+    Object.assign(story, patch);
+    story.history = [
+      ...(story.history ?? []),
+      {
+        timestamp: opts.now ?? new Date().toISOString(),
+        from,
+        to: patch.status,
+        by: opts.by ?? 'kanban',
+        reason: patch.blocked_reason ?? '',
+      },
+    ];
+    const tmp = `${yamlPath}.tmp`;
+    await writeFile(tmp, yaml.dump(doc, { lineWidth: -1 }), 'utf8');
+    await rename(tmp, yamlPath);
+    return story;
+  } finally {
+    await unlink(lockPath).catch(() => {});
+  }
+}
+
 /**
  * Rebuild sprint-status.yaml from current repository state
  * @param {string} projectRoot - Parent of project-management/ directory

package/cli/kanban/shared/schemas.js

@@ -115,6 +115,8 @@ export const SprintStatusSchema = z
                 total: z.number().int().min(0).default(0),
                 completed: z.number().int().min(0).default(0),
                 list: z.array(z.string()).default([]),
+                // Per-task status (TASK-xxx -> to-do|in-progress|done|blocked).
+                status: z.record(z.string(), z.enum(TASK_STATUSES)).optional(),
               })
               .optional(),
             history: z.array(HistoryEntrySchema).optional().default([]),

package/cli/lib/update.js

@@ -150,6 +150,21 @@ function runUpdate(targetPath, options, cliRoot) {
     }
   }
 
+  // Delete commands retired from the distribution (config/removed-commands.yaml).
+  // The Project installer is not re-run here, so prune every namespace explicitly.
+  const pruneScript = path.join(scriptsDir, 'prune-removed-commands.sh');
+  if (fs.existsSync(pruneScript)) {
+    const result = spawnSync('bash', [pruneScript, safeTarget], { encoding: 'utf8', timeout: 60_000, stdio: 'pipe' });
+    if (result.status !== 0) {
+      console.log(
+        `  ${c.red}[FAIL]${c.reset} Retired commands cleanup: ${result.stderr || result.error?.message || 'unknown'}`
+      );
+      anyFailed = true;
+    } else if (result.stdout.trim()) {
+      console.log(result.stdout.trimEnd());
+    }
+  }
+
   // Rollback on partial failure (CC-REL-14).
   if (anyFailed && backupPath) {
     try {

package/config/removed-commands.yaml

@@ -0,0 +1,14 @@
+# Command files removed from the claude-craft distribution.
+#
+# Installers (Project/install-project-commands.sh, Dev/scripts/install-common-rules.sh)
+# and `claude-craft update` delete these paths from <target>/.claude/commands/ so an
+# upgrade does not leave stale commands behind. Paths are <namespace>/<command>.md.
+# Deprecated commands stay distributed as redirect stubs (frontmatter
+# `deprecated: true` + `replaced-by:`) and are only listed here once retired.
+removed:
+  # 8.24.0 — maintainer-only commands, kept in the claude-craft repository (.claude/commands/common/)
+  - common/add-technology.md
+  - common/audit-claude-alignment.md
+  - common/audit-freshness.md
+  # 8.26.0 — documentation, now the `sub-agents-patterns` skill
+  - common/sub-agents-patterns.md

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@the-bearded-bear/claude-craft",
-  "version": "8.23.3",
+  "version": "8.26.0-next.2a54921",
   "description": "A comprehensive framework for AI-assisted development with Claude Code. Install standardized rules, agents, and commands for your projects.",
   "type": "module",
   "main": "cli/index.js",
@@ -94,6 +94,7 @@
   "files": [
     "bundles/",
     "cli/",
+    "config/removed-commands.yaml",
     "Dev/",
     "Infra/",
     "Project/",
@@ -108,6 +109,7 @@
     "zod": "^4.4.3"
   },
   "overrides": {
-    "qs": "^6.15.2"
+    "qs": "^6.15.2",
+    "typescript": "^6.0.3"
   }
 }