arcane-cli 0.24.0 → 0.25.0

package/dist/assets/.github/prompts/spell-full-cycle.prompt.md

@@ -10,7 +10,7 @@ agent: agent
 - This prompt chains all Spell Loop phases into a single autonomous pipeline.
 - Includes optional PRD enchantment (spell-enchant) between Plan and Architect for quality enhancement.
 - Only one human touchpoint: approving the PR at ship time.
-- Delegates each phase to the appropriate specialized agent role (research, architecture, build, QA, marketing review). Resolve concrete personas from [agent-policies](../../.arcane/governance/agent-policies.md) / [naming-conventions](../../.arcane/governance/naming-conventions.md); if neither is present, proceed with role names directly.
+- Delegates each phase to the appropriate specialized agent role (research, architecture, build, QA, marketing review) — **in practice, a single agent switches hats per phase** unless a real per-tool subagent registry is configured (e.g. `.claude/agents/` for Claude Code); this framework ships no such registry by default, so "delegates" names the intended role model, not a literal handoff between separately running agents (2026-07-22 dogfooding finding). Resolve concrete personas from [agent-policies](../../.arcane/governance/agent-policies.md) / [naming-conventions](../../.arcane/governance/naming-conventions.md); if neither is present, proceed with role names directly.
 - If any phase fails, the pipeline halts and reports the blocker — no silent failures.
 
 ---
@@ -58,8 +58,9 @@ Execute the `spell-plan` workflow:
 
 1. Gather requirements from the feature description.
 2. Check existing ADRs and business docs for constraints.
-3. Produce `PRD.md` with requirements, acceptance criteria, constraints, and tracking configuration (`tracking_mode`, optional `external_provider`, optional `adoWorkItemId`/`githubIssueId`).
-4. **Gate:** Validate every requirement has at least one testable acceptance criterion. If scope is too large for one sprint, halt and recommend splitting.
+3. **If the feature description hands in a pre-diagnosed root cause** (a specific file/line/mechanism already named as the cause of a bug), re-verify it against current source before accepting it — a handed-in diagnosis can be stale (2026-07-22 dogfooding finding: a filed root-cause lead was already fixed and the real causes were elsewhere). Do not carry a stale diagnosis into the PRD or stories unexamined.
+4. Produce `PRD.md` with requirements, acceptance criteria, constraints, and tracking configuration (`tracking_mode`, optional `external_provider`, optional `adoWorkItemId`/`githubIssueId`).
+5. **Gate:** Validate every requirement has at least one testable acceptance criterion. If scope is too large for one sprint, halt and recommend splitting.
 
 Store the PRD in the working directory. Proceed automatically to Phase 1.5.
 
@@ -118,6 +119,7 @@ Execute the `spell-implement` workflow:
 2. Loop:
    a. Pick the next story where `passes: false`, ordered by priority.
    b. Implement the story — minimum code to satisfy acceptance criteria.
+   b1. **DB migration guard.** If `architecture.md`/the PRD did not name a database migration as part of this feature's scope, but implementing this story is about to produce one anyway, **halt and flag it** — do not write the migration file silently (2026-07-22 dogfooding finding: this is a scoped hard guard, not a blanket ban). If a migration genuinely is in scope, **re-derive its sequence number from a fresh `git pull --ff-only` of the target branch immediately before writing the file** — not once at branch-creation time in step 0 — so a concurrent epic that landed a migration in the meantime is reflected. This is the concrete fix for a real incident: two epics run in parallel worktrees each independently claimed the same migration sequence number, invisible until human merge review.
    c. Write tests per `governance/testing-standards.md`.
    d. Run tests. If passing:
       - In `external/ado` mode, commit with `#{adoWorkItemId} type(scope): description` and agent attribution trailers (`Agent`, `Model`, `Provider`).
@@ -136,8 +138,9 @@ Execute the `spell-test` workflow:
 1. Run the full test suite (not just per-story — full regression).
 2. Validate coverage: 80% line minimum, 95% critical path.
 3. Map each acceptance criterion from the PRD to a specific passing test.
-4. Update `stories.json` with consolidated test evidence.
-5. **Gate:** If coverage is below threshold or any acceptance criterion lacks a test, loop back to Phase 3 to add missing tests. Maximum 2 coverage-fix loops before halting.
+4. **If this run produced a database migration:** a fresh/empty test database is not sufficient evidence by itself — this is a real incident's root cause (a unique index conflicted with legitimate duplicate rows the target app allows by design; every test passed against an empty DB, then broke the consumer's actual deploy). If the execution sandbox has access to a snapshot or copy of the target environment's real data, replay the migration against it and report the result. **If it does not** (the common case for an isolated sandbox), do not silently proceed as if this were validated — name the gap explicitly in the ship report's disclosure (see below) so a human reviews the migration against real data before it ships.
+5. Update `stories.json` with consolidated test evidence.
+6. **Gate:** If coverage is below threshold or any acceptance criterion lacks a test, loop back to Phase 3 to add missing tests. Maximum 2 coverage-fix loops before halting.
 
 Proceed automatically to Phase 5.
 
@@ -159,12 +162,24 @@ Proceed automatically to Phase 6.
 Execute the `spell-ship` workflow:
 
 1. Verify all prior phases passed (PRD, architecture, all stories, tests, review).
+1a. **PR strategy: one branch, one PR, per invocation.** This is the default and it is not optional to
+   restate per run — a 2026-07-22 dogfooding finding found this pattern had to be imposed by the
+   operator each time because the spell never stated it. If a later invocation would touch files an
+   earlier, still-open PR from a prior invocation already changed, do not open a second, conflicting PR
+   — rebase this branch onto the earlier PR's branch (or wait for it to merge, per this spell's own
+   multi-epic serialization default in the Rules section) before opening this one.
 2. Run pre-deploy checklist:
    - No merge conflicts with target branch.
    - No secrets or credentials in the diff.
    - DECISIONS.md updated if new ADRs were created.
    - Documentation updated for user-facing changes.
 3. Generate the ship report (phase status table, test evidence, review findings, recommendation).
+   **Mandatory disclosure section:** explicitly list anything this run could not verify in its own
+   execution sandbox — a real-data migration replay Phase 4 couldn't attempt, an external integration
+   it couldn't reach, a manual step it couldn't perform — never omit this section just because nothing
+   applies (state "Nothing withheld" in that case). Fold it into the consumer repo's own QA checklist
+   so a human reviewer sees exactly what still needs a human look, not just what passed (2026-07-22
+   dogfooding finding: honest disclosure of sandbox limits, not just of failures).
 4. Create the PR:
    - `external/ado` mode: `az repos pr create --repository {repo} --source-branch {branch} --target-branch main --title "{feature}" --work-items {adoWorkItemId}`
    - `internal` mode (or provider TODO mode): create PR without `--work-items`.

package/dist/index.js

@@ -6,7 +6,7 @@ const require = __createRequire(import.meta.url);
 import { Command } from "commander";
 import { createRequire as createRequire2 } from "module";
 import { fileURLToPath } from "url";
-import { dirname as dirname4, join as join12 } from "path";
+import { dirname as dirname4, join as join14 } from "path";
 
 // src/commands/init.ts
 import { select as select2, confirm, input as input2 } from "@inquirer/prompts";
@@ -3858,8 +3858,8 @@ async function checkVSCodeExtension(id, label) {
   ];
   for (const dir of extDirs) {
     try {
-      const { readdir: readdir5 } = await import("fs/promises");
-      const entries = await readdir5(dir);
+      const { readdir: readdir7 } = await import("fs/promises");
+      const entries = await readdir7(dir);
       const prefix = id.toLowerCase() + "-";
       const found = entries.some(
         (e) => e.toLowerCase() === id.toLowerCase() || e.toLowerCase().startsWith(prefix)
@@ -4194,6 +4194,215 @@ async function runDoctor(targetDir, options = {}, assetsDir) {
   }
 }
 
+// src/modules/ward.ts
+import { readdir as readdir6, readFile as readFile8 } from "fs/promises";
+import { join as join13, relative as relative2 } from "path";
+
+// src/modules/denylist-scan.ts
+import { readFile as readFile7, readdir as readdir5 } from "fs/promises";
+import { join as join12, relative } from "path";
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function createDenylistRules(tokens, labelPrefix) {
+  return tokens.map((token, index) => ({
+    label: `${labelPrefix}-${index + 1}`,
+    pattern: new RegExp(
+      `(?:^|[^A-Za-z0-9])${escapeRegExp(token)}(?=$|[^A-Za-z0-9])`,
+      "i"
+    )
+  }));
+}
+var SKIP_DIRECTORIES = /* @__PURE__ */ new Set([
+  "node_modules",
+  ".git",
+  "dist",
+  "coverage",
+  ".vitest"
+]);
+var DEFAULT_SCANNABLE_EXTENSIONS = [".md", ".ts", ".js", ".json", ".yml", ".yaml"];
+async function collectScannableFiles(root, repoRoot = root, extensions = DEFAULT_SCANNABLE_EXTENSIONS) {
+  const collected = [];
+  let entries;
+  try {
+    entries = await readdir5(root, { withFileTypes: true });
+  } catch {
+    return collected;
+  }
+  for (const entry of entries) {
+    const absolutePath = join12(root, entry.name);
+    if (entry.isDirectory()) {
+      if (SKIP_DIRECTORIES.has(entry.name)) continue;
+      collected.push(...await collectScannableFiles(absolutePath, repoRoot, extensions));
+    } else if (extensions.some((ext) => entry.name.endsWith(ext))) {
+      const displayPath = relative(repoRoot, absolutePath).replace(/\\/g, "/");
+      collected.push([absolutePath, displayPath]);
+    }
+  }
+  return collected;
+}
+
+// src/modules/ward.ts
+async function scanFileAllRules(absolutePath, displayPath, rules) {
+  const findings = [];
+  let content;
+  try {
+    content = await readFile8(absolutePath, "utf8");
+  } catch {
+    return findings;
+  }
+  const lines = content.split("\n");
+  for (let index = 0; index < lines.length; index++) {
+    const searchable = lines[index].replace(/\{[A-Z][A-Z0-9_]*\}/g, "");
+    for (const rule of rules) {
+      if (rule.pattern.test(searchable)) {
+        findings.push({ file: displayPath, line: index + 1, rule: rule.label });
+      }
+    }
+  }
+  return findings;
+}
+var VENDOR_IDENTIFIER_PROTECTION_LIST = [
+  "claude",
+  "gpt-4",
+  "gpt-3.5",
+  "gemini",
+  "llama",
+  "mistral",
+  "copilot",
+  "anthropic",
+  "openai"
+];
+var GREP_PROOF_EXTENSIONS = [".gif", ".png", ".jpg", ".jpeg", ".mp4", ".mov", ".mp3", ".wav"];
+var WARD_TEXT_EXTENSIONS = [
+  ".md",
+  ".ts",
+  ".tsx",
+  ".js",
+  ".jsx",
+  ".json",
+  ".yml",
+  ".yaml",
+  ".txt",
+  ".mdx"
+];
+function applyExclusions(findings, fileLines, exclusions) {
+  if (exclusions.length === 0) return findings;
+  return findings.filter((finding) => {
+    const applicable = exclusions.filter((e) => e.rule === finding.rule);
+    if (applicable.length === 0) return true;
+    const lines = fileLines.get(finding.file);
+    const lineText = lines?.[finding.line - 1] ?? "";
+    return !applicable.some((e) => lineText.includes(e.context));
+  });
+}
+async function scanFilenames(root, rules, repoRoot = root) {
+  const findings = [];
+  let entries;
+  try {
+    entries = await readdir6(root, { withFileTypes: true });
+  } catch {
+    return findings;
+  }
+  for (const entry of entries) {
+    const absolutePath = join13(root, entry.name);
+    if (entry.isDirectory()) {
+      if (SKIP_DIRECTORIES.has(entry.name)) continue;
+      findings.push(...await scanFilenames(absolutePath, rules, repoRoot));
+      continue;
+    }
+    const displayPath = relative2(repoRoot, absolutePath).replace(/\\/g, "/");
+    for (const rule of rules) {
+      if (rule.pattern.test(entry.name)) {
+        findings.push({ file: displayPath, line: 0, rule: rule.label });
+        break;
+      }
+    }
+  }
+  return findings;
+}
+async function flagGrepProofMedia(root, repoRoot = root) {
+  const files = await collectScannableFiles(root, repoRoot, GREP_PROOF_EXTENSIONS);
+  return files.map(([, displayPath]) => ({
+    file: displayPath,
+    reason: "binary media format -- text extraction is unreliable; review manually for embedded identifiers"
+  }));
+}
+async function runWard(repoRoot, options = {}) {
+  const userTerms = options.terms ?? [];
+  const exclusions = options.exclusions ?? [];
+  const extensions = [...WARD_TEXT_EXTENSIONS, ...options.binaryExtensions ?? []];
+  const userRules = createDenylistRules(userTerms, "ward-term");
+  const vendorRules = createDenylistRules([...VENDOR_IDENTIFIER_PROTECTION_LIST], "ward-vendor");
+  const allRules = [...userRules, ...vendorRules];
+  const contentFiles = await collectScannableFiles(repoRoot, repoRoot, extensions);
+  const fileLines = /* @__PURE__ */ new Map();
+  const contentFindings = [];
+  for (const [absolutePath, displayPath] of contentFiles) {
+    const findings2 = await scanFileAllRules(absolutePath, displayPath, allRules);
+    if (findings2.length > 0) {
+      try {
+        fileLines.set(displayPath, (await readFile8(absolutePath, "utf8")).split("\n"));
+      } catch {
+      }
+    }
+    contentFindings.push(...findings2);
+  }
+  const filenameFindings = await scanFilenames(repoRoot, allRules);
+  const combined = [...contentFindings, ...filenameFindings];
+  const excluded = applyExclusions(combined, fileLines, exclusions);
+  const vendorLabels = new Set(vendorRules.map((r) => r.label));
+  const findings = excluded.map((f) => ({
+    ...f,
+    category: vendorLabels.has(f.rule) ? "protected-vendor-identifier" : "leak"
+  }));
+  const mediaFlags = await flagGrepProofMedia(repoRoot);
+  return { findings, mediaFlags };
+}
+
+// src/commands/ward.ts
+function parseTerms(raw) {
+  if (!raw) return [];
+  return raw.split(",").map((t) => t.trim()).filter(Boolean);
+}
+async function runWardCli(targetDir, options = {}, exclusions = []) {
+  const terms = parseTerms(options.terms);
+  const report = await runWard(targetDir, { terms, exclusions });
+  console.log("\nspell ward \u2014 scanning for leaked identifiers\n");
+  const leaks = report.findings.filter((f) => f.category === "leak");
+  const protectedHits = report.findings.filter((f) => f.category === "protected-vendor-identifier");
+  if (leaks.length === 0 && protectedHits.length === 0) {
+    console.log("  \u2713 No denylisted terms found.");
+  }
+  for (const finding of leaks) {
+    const where = finding.line === 0 ? `${finding.file} (filename)` : `${finding.file}:${finding.line}`;
+    console.log(`  \u2717 [leak] ${where} \u2014 rule: ${finding.rule}`);
+  }
+  for (const finding of protectedHits) {
+    const where = finding.line === 0 ? `${finding.file} (filename)` : `${finding.file}:${finding.line}`;
+    console.log(
+      `  \u26A0 [protected-vendor-identifier] ${where} \u2014 rule: ${finding.rule} \u2014 verify before any automated rename touches this line`
+    );
+  }
+  if (report.mediaFlags.length > 0) {
+    console.log("\n  Grep-proof media flagged for manual review:");
+    for (const flag of report.mediaFlags) {
+      console.log(`    ? ${flag.file} \u2014 ${flag.reason}`);
+    }
+  }
+  console.log();
+  if (options.gate && leaks.length > 0) {
+    console.log(`  ${leaks.length} leak(s) found. Failing (--gate mode).
+`);
+    process.exitCode = 1;
+    return;
+  }
+  if (leaks.length > 0) {
+    console.log(`  ${leaks.length} leak(s) found. Run with --gate to fail CI on this.
+`);
+  }
+}
+
 // src/commands/unblock-push.ts
 import { basename as basename2, resolve as resolve2 } from "path";
 import { input as input4 } from "@inquirer/prompts";
@@ -4296,7 +4505,7 @@ Name did not match ("${typed.trim()}" \u2260 "${repoName}"). Nothing changed.`);
 import { realpathSync } from "fs";
 var require3 = createRequire2(import.meta.url);
 var pkg = require3("../package.json");
-var ASSETS_DIR = process.env["ARCANE_ASSETS_DIR"] ?? join12(dirname4(fileURLToPath(import.meta.url)), "assets");
+var ASSETS_DIR = process.env["ARCANE_ASSETS_DIR"] ?? join14(dirname4(fileURLToPath(import.meta.url)), "assets");
 var program = new Command();
 program.name("spell").description("Arcane framework CLI \u2014 scaffold and manage governance files").version(pkg.version).action(async () => {
   if (program.args.length > 0) {
@@ -4362,6 +4571,9 @@ program.command("unblock-push").description("Lift this repository's push block (
 program.command("doctor").description("Check your environment for Arcane prerequisites").option("--fix", "Automatically create missing session continuity files").action(async (opts) => {
   await runDoctor(process.cwd(), { fix: opts.fix }, ASSETS_DIR);
 });
+program.command("ward").description("Scan the repo for leaked third-party identifiers and trademarks (T18)").option("--terms <terms>", "Comma-separated denylist terms, in addition to the built-in vendor-identifier list").option("--gate", "Exit non-zero if any leak is found (for CI)").action(async (opts) => {
+  await runWardCli(process.cwd(), opts);
+});
 var agentsCommand = program.command("agents").description("Manage the portable agent system (init, sync, list)");
 agentsCommand.command("init").description(
   "Interactive agent roster setup \u2014 choose profile, naming strategy, and install definitions"