raptor-aios 0.12.2 → 0.13.1

package/CHANGELOG.md

@@ -5,6 +5,62 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.13.1] - 2026-06-19
+
+### Fixed
+
+- **`raptor new` agora empilha as specs de verdade — auto-commit da spec na sua
+  branch.** O empilhamento de branches (v0.13.0) dependia de a spec anterior estar
+  **commitada** antes da próxima `raptor new`, mas havia um impasse: o `new` deixava
+  a spec *untracked* e o pre-commit hook **bloqueava** commitá-la manualmente (a spec
+  recém-criada falha nos gates M1–M5, que valem para uma feature já preenchida). Sem
+  commit, a árvore ficava suja, o guard pulava a criação da próxima branch e o
+  empilhamento nunca acontecia — a nova spec não herdava as anteriores. Agora o `new`
+  **commita automaticamente** a spec scaffolded na sua branch de feature (escopo
+  restrito a `.raptor/specs/<NNN-slug>`, sem varrer outras mudanças; `--no-verify`
+  porque os gates não se aplicam a um scaffold). A árvore fica limpa, a próxima
+  `raptor new` forka de uma base commitada e **cada branch carrega todas as specs
+  anteriores** — preservando dependências entre specs. Use `--no-commit` para
+  desativar. Novo helper `commitPaths` em `@raptor/core`.
+
+### Fixed
+
+- **`raptor new` parou de "sobrescrever" specs anteriores — resolução de feature por slug
+  exato.** `featureDir()`/`auditableDir()` casavam o slug informado por **sufixo**
+  (`d.endsWith('-'+slug)`) e devolviam o primeiro match, então um slug curto resolvia
+  silenciosamente para um diretório irmão mais longo (`home-screen` →
+  `001-dashboard-home-screen`). Os ~22 comandos a jusante (`plan`, `tasks`, `implement`,
+  `clarify`, `verify`, `status`, `audit`, …) passavam a operar sobre a feature **errada**,
+  parecendo sobrescrever os artefatos da anterior. Agora o match é **exato** (nome completo
+  `NNN-slug` ou slug após o número); múltiplos diretórios casando viram **erro de
+  ambiguidade** em vez de adivinhação.
+- **`raptor new` não quebra mais quando `.raptor/specs` não existe.** Git não versiona
+  diretórios vazios, então um clone novo (ou após `git clean`) podia não ter a pasta; o
+  `readdir` agora tolera a ausência e trata como "sem features".
+
+### Changed
+
+- **Branches de feature passam a empilhar (forkam do HEAD atual, não mais de `main`).** Com
+  `git.branch_per_feature`, cada feature nascia de uma `main` sem as specs das irmãs
+  (commitadas só nas branches delas); ao trocar de branch o Git esvaziava a pasta da spec
+  anterior (deixando só a casca `contracts/`), dando a impressão de perda de artefatos. Agora
+  a branch nova forka da **branch ativa**, então as specs anteriores são herdadas no working
+  tree e o histórico empilha. A primeira feature ainda nasce de `main` naturalmente (é onde
+  você começa); HEAD destacado cai no fallback da branch-base.
+- **Numeração `NNN` à prova de colisão entre branches.** O próximo número agora vem da
+  **união** das pastas em `.raptor/specs/` **e** dos números embutidos nos nomes de **todas
+  as branches** (locais e remotas, via novo `listBranches()` do core), eliminando o
+  `feat/002-*` duplicado que surgia quando o contador só via a árvore da branch atual. O
+  reuso-por-slug também consulta as branches, preservando a idempotência de `raptor new`
+  (re-rodar um slug que vive só em uma branch irmã volta para o número dela).
+
+### Docs
+
+- **Novo:** [`docs/feature-branching-and-numbering.md`](docs/feature-branching-and-numbering.md)
+  documenta o diagnóstico completo do falso "o `new` sobrescreve a spec anterior" (resolução
+  por sufixo + branch forkando da `main` + casca vazia ao trocar de branch) e o modelo de
+  branches empilhadas / numeração por união a partir desta release.
+
 ## [0.12.2] - 2026-06-16
 
 ### Changed

package/README.md

@@ -7,8 +7,8 @@
 [![npm](https://img.shields.io/npm/v/raptor-aios?color=ef4444&label=raptor-aios&logo=npm)](https://www.npmjs.com/package/raptor-aios)
 [![node](https://img.shields.io/badge/node-%E2%89%A5%2020-3c873a?logo=node.js&logoColor=white)](https://nodejs.org)
 [![platform](https://img.shields.io/badge/target-React%20Native-61dafb?logo=react&logoColor=black)](https://reactnative.dev)
-[![tests](https://img.shields.io/badge/tests-1356%20passing-22c55e)](#️-desenvolvimento-local)
-[![version](https://img.shields.io/badge/version-0.12.2-ef4444)](CHANGELOG.md)
+[![tests](https://img.shields.io/badge/tests-1374%20passing-22c55e)](#️-desenvolvimento-local)
+[![version](https://img.shields.io/badge/version-0.13.0-ef4444)](CHANGELOG.md)
 [![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
 
 </div>
@@ -621,7 +621,7 @@ Monorepo pnpm (`packages/core` = `@raptor/core`, `packages/cli` = binário `rapt
 ```bash
 pnpm install
 pnpm build
-pnpm -r test && pnpm test:e2e     # ~1356 testes (1071 core + ~251 cli + 34 e2e)
+pnpm -r test && pnpm test:e2e     # ~1374 testes (1071 core + 258 cli + 45 e2e)
 
 # usar a CLI local em outro projeto:
 cd packages/cli && npm link        # ou: pnpm link --global

package/dist/_core/dist/git/repo.js

@@ -14,6 +14,15 @@ export function branchExists(exec, cwd, name) {
     });
     return r.status === 0;
 }
+export function listBranches(exec, cwd) {
+    const r = exec(["for-each-ref", "--format=%(refname:short)", "refs/heads", "refs/remotes"], { cwd });
+    if (r.status !== 0 || !r.stdout)
+        return [];
+    return r.stdout
+        .split("\n")
+        .map((s) => s.trim())
+        .filter(Boolean);
+}
 export function isWorkingTreeClean(exec, cwd) {
     const r = exec(["status", "--porcelain"], { cwd });
     return r.status === 0 && r.stdout === "";
@@ -47,3 +56,17 @@ export function stagedFiles(exec, cwd) {
         .map((s) => s.trim())
         .filter(Boolean);
 }
+export function commitPaths(exec, cwd, paths, message) {
+    if (paths.length === 0)
+        return { status: 0, committed: false };
+    const status = exec(["status", "--porcelain", "--", ...paths], { cwd });
+    if (status.status !== 0)
+        return { status: status.status, committed: false };
+    if (status.stdout.trim() === "")
+        return { status: 0, committed: false };
+    const add = exec(["add", "--", ...paths], { cwd });
+    if (add.status !== 0)
+        return { status: add.status, committed: false };
+    const commit = exec(["commit", "--no-verify", "-m", message, "--", ...paths], { cwd });
+    return { status: commit.status, committed: commit.status === 0 };
+}

package/dist/_core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raptor/core",
-  "version": "0.12.2",
+  "version": "0.13.1",
   "type": "module",
   "main": "dist/index.js"
 }

package/dist/commands/new.js

@@ -3,7 +3,7 @@ import { BaseCommand } from "../base-command.js";
 import { step, heading } from "../shared/ui.js";
 import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync, } from "node:fs";
 import { join } from "node:path";
-import { appendAuditEvent, buildCanonicalPrompt, deriveBranchName, executeWorkflow, extractFigmaRefs, hashString, inferKindFromJiraIssueType, loadAgentsConfig, mapDesignToSpecContext, mapIssueToSpecContext, parseFrontmatter, renderBundled, selectAgent, writeDesignScaffold, } from "../_core/dist/index.js";
+import { appendAuditEvent, buildCanonicalPrompt, commitPaths, deriveBranchName, execSyncGitExecutor, executeWorkflow, isGitRepo, listBranches, extractFigmaRefs, hashString, inferKindFromJiraIssueType, loadAgentsConfig, mapDesignToSpecContext, mapIssueToSpecContext, parseFrontmatter, renderBundled, selectAgent, writeDesignScaffold, } from "../_core/dist/index.js";
 import { currentActor, readConfig, readInitOptions, requireProjectRoot, } from "../shared/project.js";
 import { ensureWorkItemBranch, resolveInteractive, } from "../shared/git-prompt.js";
 import { jiraConn, jiraReadyNonInteractive, openJiraClient, } from "../shared/jira.js";
@@ -14,6 +14,12 @@ import { waitForPhaseArtifact, } from "../shared/artifact-io.js";
 import { resolveWorkflow } from "../shared/workflow-resolver.js";
 import { writeFeaturePrompt } from "../shared/feature-prompt.js";
 import { cliCommandExecutor } from "../workflow/executor.js";
+function parseFeatureBranch(name) {
+    const m = /(?:^|\/)(\d{3})-(.+)$/.exec(name);
+    if (!m)
+        return null;
+    return { nnn: m[1], slug: (m[2] ?? "").split(".")[0] };
+}
 export default class New extends BaseCommand {
     static description = "Create a new feature spec in the current Raptor project";
     static examples = [
@@ -61,6 +67,11 @@ export default class New extends BaseCommand {
             description: "Skip automatic branch creation even when git.branch_per_feature is enabled",
             default: false,
         }),
+        commit: Flags.boolean({
+            description: "Auto-commit the scaffolded spec on its feature branch (bypasses the pre-commit hook so the tree stays clean and the next `raptor new` stacks the next spec on top). Use --no-commit to leave the spec uncommitted.",
+            allowNo: true,
+            default: true,
+        }),
         "non-interactive": Flags.boolean({
             description: "Never prompt; on a dirty work tree, skip branch creation instead of asking",
             default: false,
@@ -88,17 +99,25 @@ export default class New extends BaseCommand {
         if (!/^[a-z][a-z0-9-]*$/.test(args.slug)) {
             this.error("Slug must be kebab-case (lowercase letters, digits, hyphens; starts with a letter).");
         }
-        const existing = readdirSync(specsDir).filter((d) => /^\d{3}-/.test(d));
+        const existing = existsSync(specsDir)
+            ? readdirSync(specsDir).filter((d) => /^\d{3}-/.test(d))
+            : [];
+        const branchFeatures = listBranches(execSyncGitExecutor, root)
+            .map(parseFeatureBranch)
+            .filter((b) => b !== null);
         const reusedDir = existing.find((d) => d.replace(/^\d{3}-/, "") === args.slug);
-        const reusing = reusedDir !== undefined;
-        const numbers = existing
+        const reusedBranch = branchFeatures.find((b) => b.slug === args.slug);
+        const reusedNnn = reusedDir
+            ? reusedDir.slice(0, 3)
+            : reusedBranch?.nnn;
+        const reusing = reusedNnn !== undefined;
+        const dirNumbers = existing
             .map((d) => parseInt(d.slice(0, 3), 10))
             .filter((n) => !Number.isNaN(n));
-        const nextN = (numbers.length ? Math.max(...numbers) : 0) + 1;
-        const nnn = reusing
-            ? reusedDir.slice(0, 3)
-            : String(nextN).padStart(3, "0");
-        const featureName = reusing ? reusedDir : `${nnn}-${args.slug}`;
+        const branchNumbers = branchFeatures.map((b) => parseInt(b.nnn, 10));
+        const maxN = Math.max(0, ...dirNumbers, ...branchNumbers);
+        const nnn = reusing ? reusedNnn : String(maxN + 1).padStart(3, "0");
+        const featureName = reusing && reusedDir ? reusedDir : `${nnn}-${args.slug}`;
         const featureDir = join(specsDir, featureName);
         const actor0 = currentActor("human");
         runBeforeHook(this, {
@@ -365,6 +384,12 @@ export default class New extends BaseCommand {
         else if (branchResult?.outcome === "already") {
             this.log(`  Branch:    ${branchResult.branch} (already checked out)`);
         }
+        this.maybeAutoCommitSpec({
+            root,
+            featureName,
+            branchResult,
+            doCommit: flags.commit,
+        });
         this.log("");
         if (flags["wait-artifact"] && agentInfo.commandFile) {
             await waitForPhaseArtifact({
@@ -467,6 +492,22 @@ export default class New extends BaseCommand {
             interactive: resolveInteractive(ctx.nonInteractive),
         });
     }
+    maybeAutoCommitSpec(ctx) {
+        if (!ctx.doCommit)
+            return;
+        if (!ctx.branchResult || ctx.branchResult.outcome === "skipped")
+            return;
+        if (!isGitRepo(execSyncGitExecutor, ctx.root))
+            return;
+        const rel = join(".raptor", "specs", ctx.featureName);
+        const res = commitPaths(execSyncGitExecutor, ctx.root, [rel], `chore: scaffold spec ${ctx.featureName}`);
+        if (res.committed) {
+            this.log(`  Committed: ${rel} (spec sealed on ${ctx.branchResult.branch} — next \`raptor new\` will stack on top)`);
+        }
+        else if (res.status !== 0) {
+            this.warn(`Auto-commit of the spec failed (git exit ${res.status}). Spec is saved; commit it manually so the next \`raptor new\` stacks.`);
+        }
+    }
     async fetchJiraContext(root, key) {
         const conn = jiraConn(readConfig(root));
         if (!conn) {

package/dist/shared/git-prompt.js

@@ -21,7 +21,7 @@ export async function confirmPrompt(question) {
 }
 async function promptDirtyTree(cmd, branchName) {
     cmd.log("");
-    cmd.warn(`Your working tree has uncommitted changes, and the new branch "${branchName}" forks from the base branch.`);
+    cmd.warn(`Your working tree has uncommitted changes, and the new branch "${branchName}" will fork from the current branch.`);
     cmd.log("  How do you want to proceed?");
     cmd.log("    1) stash  — set the changes aside, branch from a clean base");
     cmd.log("    2) carry  — take the uncommitted changes onto the new branch");
@@ -86,7 +86,7 @@ export async function ensureWorkItemBranch(input) {
         }
         return { outcome: "switched", branch: branchName, base: null };
     }
-    const base = defaultBaseBranch(exec, root);
+    const base = currentBranch(exec, root) ?? defaultBaseBranch(exec, root);
     const st = createBranch(exec, root, branchName, base);
     if (st !== 0) {
         const hint = carry

package/dist/shared/project.js

@@ -59,17 +59,30 @@ export function activePresetIds(cfg) {
         ordered.push(singular);
     return ordered;
 }
-export function featureDir(root, slug) {
-    const specs = join(root, '.raptor', 'specs');
-    const dirs = existsSync(specs) ? readdirSync(specs) : [];
-    const match = dirs.find((d) => d === slug || d.endsWith(`-${slug}`));
-    if (match)
-        return join(specs, match);
+function resolveFeatureDir(base, slug) {
+    if (!existsSync(base))
+        return null;
+    const dirs = readdirSync(base);
+    const matches = dirs.filter((d) => d === slug || d.replace(/^\d{3}-/, '') === slug);
+    if (matches.length === 1)
+        return join(base, matches[0]);
+    if (matches.length > 1) {
+        throw new Error(`Ambiguous feature '${slug}' — matches ${matches
+            .sort()
+            .join(', ')}. Pass the full directory name (e.g. ${matches.sort()[0]}).`);
+    }
     if (/^\d{3}-/.test(slug)) {
-        const direct = join(specs, slug);
+        const direct = join(base, slug);
         if (existsSync(direct))
             return direct;
     }
+    return null;
+}
+export function featureDir(root, slug) {
+    const specs = join(root, '.raptor', 'specs');
+    const resolved = resolveFeatureDir(specs, slug);
+    if (resolved)
+        return resolved;
     throw new Error(`feature not found: ${slug} (under ${specs})`);
 }
 export function auditableDir(root, slug) {
@@ -78,17 +91,9 @@ export function auditableDir(root, slug) {
         join(root, '.raptor', 'hotfixes'),
     ];
     for (const base of candidates) {
-        if (!existsSync(base))
-            continue;
-        const dirs = readdirSync(base);
-        const match = dirs.find((d) => d === slug || d.endsWith(`-${slug}`));
-        if (match)
-            return join(base, match);
-        if (/^\d{3}-/.test(slug)) {
-            const direct = join(base, slug);
-            if (existsSync(direct))
-                return direct;
-        }
+        const resolved = resolveFeatureDir(base, slug);
+        if (resolved)
+            return resolved;
     }
     throw new Error(`slug not found: ${slug} (checked .raptor/specs and .raptor/hotfixes)`);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "raptor-aios",
-  "version": "0.12.2",
+  "version": "0.13.1",
   "description": "Raptor — Spec-Driven Development (SDD) CLI for modern mobile apps. Constitutional gates, audit trail, real verification (a11y/perf/stores/OS matrix), and AI-agent slash commands.",
   "type": "module",
   "bin": {

package/scripts/prepare-npm.mjs

@@ -29,7 +29,7 @@ const CLI = join(ROOT, "packages", "cli");
 const CORE = join(ROOT, "packages", "core");
 const OUT = join(ROOT, "build", "npm");
 
-const VERSION = "0.12.2";
+const VERSION = "0.13.1";
 
 function log(msg) {
   process.stdout.write(`  ${msg}\n`);

package/dist/_core/dist/agents/materialize.js

@@ -1,156 +0,0 @@
-/**
- * Cross-Agent Materialization Pipeline — Materializes slash commands
- * for all registered agents.
- *
- * Given a canonical prompt (agent-neutral), this pipeline:
- *   1. Resolves placeholders (renderer)
- *   2. Packs the prompt for each agent (adapter.packPrompt)
- *   3. Writes command files to the agent's expected location
- *
- * Spec Kit ref: E11 — "Pipeline de materialização cross-agent"
- */
-import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
-import { join, basename } from "node:path";
-import { listAgents, getAgent } from "../agents/registry.js";
-import { renderPrompt, autoResolveContext } from "../prompts/renderer.js";
-// ---------------------------------------------------------------------------
-// Pipeline
-// ---------------------------------------------------------------------------
-/**
- * Materialize all canonical prompts for the specified agents.
- *
- * Reads templates from `templates/commands/` and extension `commands/`,
- * renders them, packs them for each agent, and writes output files.
- */
-export function materializeAllCommands(options) {
-    const results = [];
-    const ctx = autoResolveContext(options.projectRoot, options.context);
-    // Determine target agents
-    const registeredAgents = listAgents();
-    const targetIds = options.agentIds ?? registeredAgents.map((a) => a.id);
-    // Collect prompt templates
-    const templates = collectPromptTemplates(options.projectRoot);
-    for (const agentId of targetIds) {
-        const adapter = getAgent(agentId);
-        if (!adapter) {
-            results.push({
-                agentId,
-                commandName: "*",
-                outputPath: "",
-                written: false,
-                error: `Agent '${agentId}' not registered`,
-            });
-            continue;
-        }
-        for (const { name, content } of templates) {
-            const result = materializeSingleCommand(options.projectRoot, adapter, name, content, ctx, options.dryRun);
-            results.push(result);
-        }
-    }
-    return results;
-}
-/**
- * Materialize a single command for a specific agent.
- */
-function materializeSingleCommand(projectRoot, adapter, commandName, templateContent, ctx, dryRun) {
-    const agentId = adapter.id;
-    try {
-        // 1. Render placeholders
-        const rendered = renderPrompt(templateContent, ctx);
-        // 2. Pack for agent (converts to agent-specific format)
-        // We construct a mock CanonicalPrompt because static slash commands
-        // don't have dynamic feature context yet (handled at runtime).
-        const canonical = {
-            command: commandName,
-            feature: adapter.argumentSyntax, // e.g. "$ARGUMENTS"
-            promptHash: "static-template",
-            generatedAt: new Date().toISOString(),
-            body: rendered,
-            scope: { read: [], write: [], forbidden: [] },
-            invariants: [],
-            inputs: [],
-            expectedOutput: "",
-            outputSchema: "",
-            articles: [],
-        };
-        const packed = adapter.packPrompt(canonical);
-        // 3. Determine output path
-        const outputDir = resolveOutputDir(projectRoot, adapter);
-        const fileName = adapter.commandFileName(`rpt.${commandName}`);
-        const outputPath = join(outputDir, fileName);
-        // 4. Write
-        if (!dryRun) {
-            if (!existsSync(outputDir)) {
-                mkdirSync(outputDir, { recursive: true });
-            }
-            writeFileSync(outputPath, packed);
-        }
-        return {
-            agentId,
-            commandName,
-            outputPath,
-            written: !dryRun,
-        };
-    }
-    catch (err) {
-        return {
-            agentId,
-            commandName,
-            outputPath: "",
-            written: false,
-            error: err.message,
-        };
-    }
-}
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-/**
- * Collect all prompt templates from the project.
- */
-function collectPromptTemplates(projectRoot) {
-    const templates = [];
-    // Core prompts
-    const coreDir = join(projectRoot, "templates", "commands");
-    if (existsSync(coreDir)) {
-        for (const file of readdirSync(coreDir)) {
-            if (!file.endsWith(".md"))
-                continue;
-            const name = basename(file, ".md");
-            const content = readFileSync(join(coreDir, file), "utf-8");
-            templates.push({ name, content });
-        }
-    }
-    // Extension prompts
-    const extDir = join(projectRoot, "extensions");
-    if (existsSync(extDir)) {
-        for (const ext of readdirSync(extDir)) {
-            const cmdDir = join(extDir, ext, "commands");
-            if (!existsSync(cmdDir))
-                continue;
-            for (const file of readdirSync(cmdDir)) {
-                if (!file.endsWith(".md"))
-                    continue;
-                const name = basename(file, ".md");
-                const content = readFileSync(join(cmdDir, file), "utf-8");
-                templates.push({ name, content });
-            }
-        }
-    }
-    return templates;
-}
-/**
- * Resolve the output directory for an agent's command files.
- */
-function resolveOutputDir(projectRoot, adapter) {
-    // Agent-specific directories
-    const agentDirMap = {
-        "claude-code": ".claude/commands",
-        "cursor": ".cursor/commands",
-        "antigravity": ".gemini/commands",
-        "gemini": ".gemini/commands",
-        "human": ".raptor/commands",
-    };
-    const dir = agentDirMap[adapter.id] ?? `.raptor/agents/${adapter.id}/commands`;
-    return join(projectRoot, dir);
-}