@trieungoctam/speckit 0.3.0 → 0.3.3

package/README.md

@@ -21,6 +21,8 @@ npx @trieungoctam/speckit@latest context .speckit/stories/<story>.md
 npx @trieungoctam/speckit@latest sync
 npx @trieungoctam/speckit@latest sprint plan
 npx @trieungoctam/speckit@latest graph triage --json
+npx @trieungoctam/speckit@latest validate --json
+npx @trieungoctam/speckit@latest permissions audit --path .env --json
 npx @trieungoctam/speckit@latest ready .speckit/stories/<story>.md
 npx @trieungoctam/speckit@latest session checkpoint --note "red complete"
 npx @trieungoctam/speckit@latest review
@@ -68,9 +70,11 @@ For implementation stories, red-green-refactor evidence is mandatory. A story is
 | `speckit init --enterprise` | Add flow, tool policy, and prompt harness files on top of the shared runtime. |
 | `speckit init --ide <name>` | Generate shared Speckit runtime plus one adapter: `claude-code`, `codex`, `antigravity`, `opencode`, or `cursor`. |
 | `speckit doctor` | Report required tools, optional integrations, test commands, and adapter readiness. |
-| `speckit doctor --deep` | Verify core enterprise harness files. |
+| `speckit doctor --deep` | Verify core enterprise harness files and workflow contract checks. |
+| `speckit validate` | Validate flow order, core skills, super-agent routing, prompts, and installed adapter contracts. |
 | `speckit start "<idea>"` | Create a durable session handoff and current context. |
 | `speckit memory refresh` | Create durable project memory files for long-running agent work. |
+| `speckit permissions audit` | Check a path or command against the Speckit permission policy. |
 | `speckit session start` | Create or resume the active session state. |
 | `speckit session checkpoint` | Append a long-session checkpoint and artifact log entry. |
 | `speckit session compact` | Create an anchored summary for resume or handoff. |
@@ -105,6 +109,13 @@ Speckit generates native instruction/config files for:
 
 See `docs/adapters.md` for exact output paths.
 
+## Guides
+
+- `docs/use-cases.md` covers setup, migration, quick changes, full planning, long sessions, TDD, graph automation, review, CI, and troubleshooting.
+- `docs/workflow-model.md` describes the quick and full workflow lanes.
+- `docs/prompt-architecture.md` describes the prompt contract used by the super-agent, skills, workflows, run prompt, and IDE adapters.
+- `docs/spec-quality-gates.md` describes validation gates for release readiness.
+
 ## Validation
 
 ```bash

package/dist/adapters/antigravity-adapter.js

@@ -12,12 +12,12 @@ export const antigravityAdapter = {
     ],
     render() {
         return [
-            rule("agile", "Follow Speckit Agile: shape intent, read .speckit/agents/super-agent.md, .speckit/skills/catalog.md, .speckit/memory/project-context.md, .speckit/sessions/active.md, and .speckit/context/current.md, create stories with ACs, preserve session handoff, and emit artifacts for review."),
-            rule("tdd", "For code changes, use TDD: confirm acceptance criteria, use red-green-refactor, checkpoint each boundary, compact before handoff, and record evidence for each step."),
+            rule("agile", "Follow Speckit Agile: shape intent, read .speckit/agents/super-agent.md, .speckit/skills/catalog.md, .speckit/memory/project-context.md, .speckit/sessions/active.md, .speckit/context/current.md, and .speckit/context/subagent-handoff.md, create stories with ACs, preserve session handoff, and emit artifacts for review."),
+            rule("tdd", "For code changes, use TDD: require speckit ready <story>, confirm acceptance criteria, use red-green-refactor, checkpoint each boundary, compact before handoff, and record evidence for each step."),
             rule("enterprise-safety", "Require human approval for destructive commands, production changes, secrets access, and deployment."),
-            workflow("plan", "Create a Speckit plan artifact with PRD, architecture, stories, risks, dependencies, and graph sync notes."),
-            workflow("tdd-run", "Run a story with TDD from the Speckit super agent router, skill catalog, .speckit/memory/project-context.md, .speckit/context/current.md, .speckit/context/subagent-handoff.md, and active session summary. Require speckit ready <story> first. Emit artifact sections: Test Intent, Red, Green, Refactor. Use only robot-safe graph commands."),
-            workflow("review", "Review the produced artifacts and code diff. Flag AC gaps, TDD gaps, security issues, docs needs, session checkpoint freshness, and session handoff gaps."),
+            workflow("plan", "Create a Speckit plan artifact with PRD, architecture, stories, risks, rollback, test strategy, dependencies, and graph sync notes."),
+            workflow("tdd-run", "Run a story with TDD from the Speckit super agent router, skill catalog, .speckit/prompts/spec-run.md, .speckit/memory/project-context.md, .speckit/context/current.md, .speckit/context/subagent-handoff.md, and active session summary. Require speckit ready <story> first. Emit artifact sections: Test Intent, Red, Green, Refactor, Review Evidence. Update Dev Agent Record, File List, and Change Log. Use only robot-safe graph commands."),
+            workflow("review", "Review the produced artifacts and code diff. Run spec compliance, edge-case pathing, and production readiness. Flag AC gaps, TDD gaps, security issues, docs needs, session checkpoint freshness, and session handoff gaps."),
         ];
     },
 };

package/dist/adapters/claude-code-adapter.js

@@ -1,5 +1,5 @@
-import { json, markdown } from "../core/managed-files.js";
-const skillIntro = `Follow Speckit: Agile story flow plus mandatory TDD evidence. Read .speckit/memory/project-context.md, .speckit/context/current.md, and active session summary first. Preserve session handoff, checkpoint long work, use red-green-refactor, and use robot-safe graph commands only.`;
+import { markdown, markdownWithFrontmatter, strictJsonManaged, } from "../core/managed-files.js";
+const skillIntro = `Follow Speckit: Agile story flow plus mandatory TDD evidence. Read .speckit/agents/super-agent.md, .speckit/skills/catalog.md, .speckit/memory/project-context.md, .speckit/sessions/active.md, .speckit/context/current.md, and .speckit/context/subagent-handoff.md before story work. Preserve session handoff, checkpoint long work, use red-green-refactor, and use robot-safe graph commands only.`;
 export const claudeCodeAdapter = {
     name: "claude-code",
     displayName: "Claude Code",
@@ -11,6 +11,28 @@ export const claudeCodeAdapter = {
         ".claude/skills/speckit-review/SKILL.md",
     ],
     render() {
+        const settings = {
+            permissions: {
+                defaultMode: "ask",
+                deny: [
+                    "Read(.env*)",
+                    "Read(**/*.pem)",
+                    "Read(**/*.key)",
+                    "Read(**/id_rsa)",
+                    "Read(**/id_ed25519)",
+                    "Write(.env*)",
+                    "Write(**/*.pem)",
+                    "Write(**/*.key)",
+                    "Bash(rm -rf*)",
+                    "Bash(git reset --hard*)",
+                    "Bash(git clean -fd*)",
+                    "Bash(git push --force*)",
+                    "Bash(sudo *)",
+                ],
+                ask: ["Bash(git push*)", "Bash(npm publish*)", "Bash(* deploy*)"],
+            },
+            includeCoAuthoredBy: false,
+        };
         return [
             {
                 path: "CLAUDE.md",
@@ -31,28 +53,19 @@ Use Speckit for Agile + TDD work.
             },
             {
                 path: ".claude/settings.json",
-                content: json({
-                    permissions: {
-                        defaultMode: "ask",
-                    },
-                    includeCoAuthoredBy: false,
-                }),
+                ...strictJsonManaged(settings),
             },
-            skill("speckit-plan", "Create or update a Speckit Agile plan.", "Read `.speckit/agents/super-agent.md`, `.speckit/skills/catalog.md`, and `.speckit/workflows/shape.md`, preserve the session id, then create PRD, architecture, and story artifacts with acceptance criteria."),
-            skill("speckit-tdd", "Execute a Speckit story with TDD.", "Read `.speckit/memory/project-context.md`, `.speckit/context/current.md`, `.speckit/context/subagent-handoff.md`, active session summary, and `.speckit/workflows/tdd-run.md`. Do not implement before `speckit ready <story>` passes, test intent is clear, and red evidence is recorded. Checkpoint after red, green, and refactor."),
-            skill("speckit-review", "Review a Speckit change.", "Read `.speckit/workflows/review.md` and the active session artifact log. Prioritize AC coverage, TDD evidence gaps, security, docs impact, session checkpoint freshness, and graph sync status."),
+            skill("speckit-plan", "Create or update a Speckit Agile plan.", "Read `.speckit/workflows/shape.md`, preserve the session id, then create PRD, architecture, story, risk, rollback, and test strategy artifacts with acceptance criteria. Do not cross into implementation."),
+            skill("speckit-tdd", "Execute a Speckit story with TDD.", "Read `.speckit/workflows/tdd-run.md` and `.speckit/prompts/spec-run.md`. Do not implement before `speckit ready <story>` passes, test intent is clear, and red evidence is recorded. Checkpoint after red, green, and refactor. Update story Dev Agent Record, File List, Change Log, and evidence."),
+            skill("speckit-review", "Review a Speckit change.", "Read `.speckit/workflows/review.md` and the active session artifact log. Review spec compliance, edge-case paths, production readiness, AC coverage, TDD evidence gaps, security, docs impact, session checkpoint freshness, and graph sync status."),
         ];
     },
 };
 function skill(name, description, body) {
     return {
         path: `.claude/skills/${name}/SKILL.md`,
-        content: markdown(`---
-name: ${name}
-description: "${description}"
----
-
-# ${name}
+        content: markdownWithFrontmatter(`name: ${name}
+description: "${description}"`, `# ${name}
 
 ${skillIntro}
 

package/dist/adapters/codex-adapter.js

@@ -34,6 +34,8 @@ Rules:
                 content: text(`model = "gpt-5.4"
 approval_policy = "on-request"
 sandbox_mode = "workspace-write"
+allowed_approval_policies = ["untrusted", "on-request"]
+allowed_sandbox_modes = ["read-only", "workspace-write"]
 
 [tools]
 web_search = true
@@ -41,9 +43,9 @@ web_search = true
 [features]
 child_agents_md = true`),
             },
-            prompt("plan", "Create a Speckit plan from the user intent. Use the Speckit super agent router and skill catalog. Preserve session context, project memory, PRD, architecture, stories, ACs, TDD checklist, risks, and graph sync notes."),
-            prompt("tdd-run", "Execute the selected Speckit story using .speckit/memory/project-context.md, .speckit/context/current.md, .speckit/context/subagent-handoff.md, active session summary, and red-green-refactor. Require speckit ready <story>, confirm ACs, checkpoint each boundary, record command evidence, and use only robot-safe graph commands."),
-            prompt("review", "Review the current diff against Speckit ACs, TDD evidence, security, docs impact, session handoff, session checkpoint freshness, and graph sync status."),
+            prompt("plan", "Create a Speckit plan from the user intent. Use the Speckit super agent router and skill catalog. Preserve active session context, project memory, PRD, architecture, stories, ACs, TDD checklist, risks, rollback, test strategy, and graph sync notes. Stop before implementation."),
+            prompt("tdd-run", "Execute the selected Speckit story using .speckit/prompts/spec-run.md, .speckit/memory/project-context.md, .speckit/sessions/active.md, .speckit/context/current.md, .speckit/context/subagent-handoff.md, active session summary, and red-green-refactor. Require speckit ready <story>, confirm ACs, checkpoint each boundary, update story Dev Agent Record/File List/Change Log, record command evidence, and use only robot-safe graph commands."),
+            prompt("review", "Review the current diff against Speckit ACs, TDD evidence, security, docs impact, session handoff, session checkpoint freshness, and graph sync status. Run spec compliance first, edge-case pathing second, and production readiness third."),
         ];
     },
 };

package/dist/adapters/cursor-adapter.js

@@ -1,4 +1,4 @@
-import { json, markdown } from "../core/managed-files.js";
+import { markdown, markdownWithFrontmatter, strictJsonManaged, } from "../core/managed-files.js";
 export const cursorAdapter = {
     name: "cursor",
     displayName: "Cursor",
@@ -8,19 +8,44 @@ export const cursorAdapter = {
         ".cursor/rules/speckit-review.mdc",
         ".cursor/rules/speckit-enterprise-safety.mdc",
         ".cursor/mcp.json",
+        ".cursor/cli.json",
         "AGENTS.md",
     ],
     render() {
+        const mcpConfig = {
+            mcpServers: {},
+        };
+        const cliConfig = {
+            permissions: {
+                allow: ["Shell(git)", "Shell(npm)", "Shell(node)", "Read(.speckit/**)", "Read(src/**)", "Read(tests/**)"],
+                deny: [
+                    "Read(.env*)",
+                    "Read(**/*.pem)",
+                    "Read(**/*.key)",
+                    "Read(**/id_rsa)",
+                    "Read(**/id_ed25519)",
+                    "Write(.env*)",
+                    "Write(**/*.pem)",
+                    "Write(**/*.key)",
+                    "Shell(rm)",
+                    "Shell(sudo)",
+                    "Shell(chmod)",
+                    "Shell(chown)",
+                ],
+            },
+        };
         return [
-            rule("agile", "alwaysApply: true", "Use Speckit Agile flow. Read .speckit/agents/super-agent.md, .speckit/skills/catalog.md, .speckit/memory/project-context.md, .speckit/sessions/active.md, .speckit/context/current.md, and .speckit/context/subagent-handoff.md. Preserve session handoff, create stories with ACs, and keep work scoped."),
-            rule("tdd", "description: Apply when implementing or modifying code", "Use red-green-refactor. Run speckit ready <story>, confirm acceptance criteria, checkpoint each TDD boundary, and record TDD evidence before review-ready."),
-            rule("review", "description: Apply when reviewing code or preparing a PR", "Review AC coverage, TDD evidence, security, docs impact, session checkpoint freshness, and graph sync status."),
+            rule("agile", "alwaysApply: true", "Use Speckit Agile flow. Read .speckit/agents/super-agent.md, .speckit/skills/catalog.md, .speckit/memory/project-context.md, .speckit/sessions/active.md, .speckit/context/current.md, and .speckit/context/subagent-handoff.md. Preserve session handoff, create stories with ACs, and keep work scoped to the current artifact phase."),
+            rule("tdd", "description: Apply when implementing or modifying code", "Use red-green-refactor. Run speckit ready <story>, confirm acceptance criteria, checkpoint each TDD boundary, update story Dev Agent Record/File List/Change Log, and record TDD evidence before review-ready."),
+            rule("review", "description: Apply when reviewing code or preparing a PR", "Review spec compliance first, edge-case pathing second, and production readiness third. Check AC coverage, TDD evidence, security, docs impact, session checkpoint freshness, and graph sync status."),
             rule("enterprise-safety", "alwaysApply: true", "Do not expose secrets. Ask before destructive commands, deployment, or production changes."),
             {
                 path: ".cursor/mcp.json",
-                content: json({
-                    mcpServers: {},
-                }),
+                ...strictJsonManaged(mcpConfig),
+            },
+            {
+                path: ".cursor/cli.json",
+                ...strictJsonManaged(cliConfig),
             },
             {
                 path: "AGENTS.md",
@@ -46,11 +71,7 @@ Use Speckit for Agile + TDD work. Cursor-specific rules live in \`.cursor/rules/
 function rule(name, frontmatter, body) {
     return {
         path: `.cursor/rules/speckit-${name}.mdc`,
-        content: markdown(`---
-${frontmatter}
----
-
-# Speckit ${name}
+        content: markdownWithFrontmatter(frontmatter, `# Speckit ${name}
 
 ${body}
 `),

package/dist/adapters/opencode-adapter.js

@@ -1,4 +1,4 @@
-import { json, markdown } from "../core/managed-files.js";
+import { markdownWithFrontmatter, strictJsonManaged } from "../core/managed-files.js";
 export const opencodeAdapter = {
     name: "opencode",
     displayName: "OpenCode",
@@ -10,17 +10,18 @@ export const opencodeAdapter = {
         ".opencode/agent/speckit-docs.md",
     ],
     render() {
+        const config = {
+            $schema: "https://opencode.ai/config.json",
+            instructions: ["AGENTS.md", ".speckit/rules/*.md"],
+            permission: {
+                edit: "ask",
+                bash: "ask",
+            },
+        };
         return [
             {
                 path: "opencode.json",
-                content: json({
-                    $schema: "https://opencode.ai/config.json",
-                    instructions: ["AGENTS.md", ".speckit/rules/*.md"],
-                    permission: {
-                        edit: "ask",
-                        bash: "ask",
-                    },
-                }),
+                ...strictJsonManaged(config),
             },
             agent("planner", "Plan Speckit Agile work without editing files.", "primary", {
                 edit: "deny",
@@ -44,16 +45,12 @@ export const opencodeAdapter = {
 function agent(name, description, mode, permission) {
     return {
         path: `.opencode/agent/speckit-${name}.md`,
-        content: markdown(`---
-description: "${description}"
+        content: markdownWithFrontmatter(`description: "${description}"
 mode: ${mode}
-permission: ${JSON.stringify(permission)}
----
-
-# speckit-${name}
+permission: ${JSON.stringify(permission)}`, `# speckit-${name}
 
 Follow \`.speckit/rules/agile-policy.md\`, \`.speckit/rules/tdd-policy.md\`, and \`.speckit/rules/enterprise-safety.md\`.
-Read \`.speckit/agents/super-agent.md\`, \`.speckit/skills/catalog.md\`, \`.speckit/memory/project-context.md\`, \`.speckit/sessions/active.md\`, \`.speckit/context/current.md\`, and \`.speckit/context/subagent-handoff.md\` before implementation work. Select the smallest matching Speckit skill. Require \`speckit ready <story>\`, confirm acceptance criteria, preserve session handoff, checkpoint red-green-refactor boundaries, compact before handoff, and use only robot-safe graph commands.
+Read \`.speckit/agents/super-agent.md\`, \`.speckit/skills/catalog.md\`, \`.speckit/prompts/spec-run.md\`, \`.speckit/memory/project-context.md\`, \`.speckit/sessions/active.md\`, \`.speckit/context/current.md\`, and \`.speckit/context/subagent-handoff.md\` before implementation work. Select the smallest matching Speckit skill. Require \`speckit ready <story>\`, confirm acceptance criteria, preserve session handoff, checkpoint red-green-refactor boundaries, update story Dev Agent Record/File List/Change Log, compact before handoff, and use only robot-safe graph commands. Reviews run spec compliance, edge-case pathing, and production readiness before approval.
 `),
     };
 }

package/dist/cli.js

@@ -6,9 +6,11 @@ import { contextCommand } from "./commands/context.js";
 import { quickCommand } from "./commands/quick.js";
 import { planCommand } from "./commands/plan.js";
 import { memoryCommand } from "./commands/memory.js";
+import { permissionsCommand } from "./commands/permissions.js";
 import { sessionCommand } from "./commands/session.js";
 import { sprintCommand } from "./commands/sprint.js";
 import { graphCommand } from "./commands/graph.js";
+import { validateCommand } from "./commands/validate.js";
 import { triageCommand } from "./commands/triage.js";
 import { nextCommand } from "./commands/next.js";
 import { syncCommand } from "./commands/sync.js";
@@ -41,6 +43,13 @@ export async function main(argv = process.argv.slice(2), root = process.cwd()) {
                 return planCommand({ root, intent: requiredIntent(parsed) });
             case "memory":
                 return memoryCommand({ root, action: requiredAction(parsed) });
+            case "permissions":
+                return permissionsCommand({
+                    action: requiredAction(parsed),
+                    path: value(parsed, "path"),
+                    command: value(parsed, "command"),
+                    json: has(parsed, "json"),
+                });
             case "session":
                 return sessionCommand({
                     root,
@@ -53,6 +62,8 @@ export async function main(argv = process.argv.slice(2), root = process.cwd()) {
                 return sprintCommand({ root, action: requiredAction(parsed), json: has(parsed, "json") });
             case "graph":
                 return graphCommand({ root, action: requiredAction(parsed), json: has(parsed, "json") });
+            case "validate":
+                return validateCommand({ root, json: has(parsed, "json") });
             case "triage":
                 return triageCommand({ root, json: has(parsed, "json") });
             case "next":
@@ -136,9 +147,11 @@ Usage:
   speckit quick "<intent>"
   speckit plan "<intent>"
   speckit memory refresh
+  speckit permissions audit [--path <path>] [--command <command>] [--json]
   speckit session start|checkpoint|compact|resume|status [target] [--note "..."] [--json]
   speckit sprint plan|next [--json]
   speckit graph triage|plan|insights [--json]
+  speckit validate [--json]
   speckit triage [--json]
   speckit next
   speckit sync

package/dist/commands/context.js

@@ -1,4 +1,4 @@
-import { markdown, writeManagedFiles } from "../core/managed-files.js";
+import { markdown, markdownWithFrontmatter, writeManagedFiles } from "../core/managed-files.js";
 import { extractEvidenceReference, extractSection, resolveStory } from "../core/story.js";
 export async function contextCommand(options) {
     const stdout = options.stdout ?? console;
@@ -14,13 +14,9 @@ export async function contextCommand(options) {
     await writeManagedFiles(options.root, [
         {
             path: contextPath,
-            content: markdown(`---
-status: fresh
+            content: markdownWithFrontmatter(`status: fresh
 story: ${story.path}
-evidence: ${evidenceReference ?? "missing"}
----
-
-# Current Spec Context
+evidence: ${evidenceReference ?? "missing"}`, `# Current Spec Context
 
 ## Story
 ${story.title}

package/dist/commands/doctor.js

@@ -5,11 +5,13 @@ import { checkTools } from "../adapters/tool-checks.js";
 import { detectTestCommands } from "../core/test-detection.js";
 import { coreFiles, enterpriseFiles } from "../core/scaffold.js";
 import { agentFiles } from "../core/agent-scaffold.js";
+import { validateWorkflowContract } from "../core/workflow-validator.js";
 export async function doctorCommand(options) {
     const stdout = options.stdout ?? console;
     const tools = checkTools();
     const tests = await detectTestCommands(options.root);
     const deepChecks = options.deep ? await runDeepChecks(options.root) : [];
+    const contractChecks = options.deep ? await validateWorkflowContract(options.root) : [];
     const adapters = await Promise.all(getAdapters("all").map(async (adapter) => ({
         name: adapter.name,
         ...(await adapterStatus(options.root, adapter.outputPaths)),
@@ -19,8 +21,9 @@ export async function doctorCommand(options) {
         tools,
         tests,
         deepChecks,
+        contractChecks,
         adapters,
-        status: statusFor(tools, deepChecks),
+        status: statusFor(tools, deepChecks, contractChecks),
     };
     if (options.json) {
         stdout.log(JSON.stringify(report, null, 2));
@@ -33,6 +36,9 @@ export async function doctorCommand(options) {
         for (const check of deepChecks) {
             stdout.log(`Deep ${check.name}: ${check.ok ? "ok" : "missing"}`);
         }
+        for (const check of contractChecks) {
+            stdout.log(`Contract ${check.name}: ${check.ok ? "ok" : check.detail}`);
+        }
         for (const adapter of adapters) {
             stdout.log(`Adapter ${adapter.name}: ${adapter.present}/${adapter.total} files present`);
         }
@@ -56,10 +62,11 @@ async function fileExists(root, path) {
         return false;
     }
 }
-function statusFor(tools, deepChecks) {
+function statusFor(tools, deepChecks, contractChecks) {
     const requiredToolsMissing = tools.some((tool) => tool.required && !tool.available);
     const deepChecksMissing = deepChecks.some((check) => !check.ok);
-    return requiredToolsMissing || deepChecksMissing ? "needs-attention" : "ok";
+    const contractChecksFailed = contractChecks.some((check) => !check.ok);
+    return requiredToolsMissing || deepChecksMissing || contractChecksFailed ? "needs-attention" : "ok";
 }
 async function adapterStatus(root, paths) {
     const missing = [];

package/dist/commands/permissions.d.ts

@@ -0,0 +1,8 @@
+export type PermissionsOptions = {
+    action: string;
+    path?: string;
+    command?: string;
+    json?: boolean;
+    stdout?: Pick<typeof console, "log" | "error">;
+};
+export declare function permissionsCommand(options: PermissionsOptions): Promise<number>;

package/dist/commands/permissions.js

@@ -0,0 +1,18 @@
+import { auditPermission } from "../core/permission-auditor.js";
+export async function permissionsCommand(options) {
+    const stdout = options.stdout ?? console;
+    if (options.action !== "audit") {
+        stdout.error?.(`Unknown permissions action: ${options.action}`);
+        return 1;
+    }
+    const result = auditPermission({ path: options.path, command: options.command });
+    if (options.json) {
+        stdout.log(JSON.stringify(result, null, 2));
+    }
+    else {
+        stdout.log(`Speckit permission audit: ${result.status}`);
+        for (const reason of result.reasons)
+            stdout.log(`- ${reason}`);
+    }
+    return result.status === "deny" ? 1 : 0;
+}

package/dist/commands/plan.js

@@ -1,4 +1,4 @@
-import { markdown, writeManagedFiles } from "../core/managed-files.js";
+import { markdown, markdownWithFrontmatter, writeManagedFiles } from "../core/managed-files.js";
 import { slugify, timestamp } from "../core/slug.js";
 export async function planCommand(options) {
     const stdout = options.stdout ?? console;
@@ -36,13 +36,9 @@ export async function planCommand(options) {
         },
         {
             path: `${dir}/story.md`,
-            content: markdown(`---
-status: draft
+            content: markdownWithFrontmatter(`status: draft
 evidence: ${dir}/tdd-evidence.md
-context: pending
----
-
-# Story: ${options.intent}
+context: pending`, `# Story: ${options.intent}
 
 ## Acceptance Criteria
 - Given ...
@@ -63,12 +59,8 @@ context: pending
         },
         {
             path: `${dir}/tdd-evidence.md`,
-            content: markdown(`---
-status: missing
-story: ${dir}/story.md
----
-
-# TDD Evidence: ${options.intent}
+            content: markdownWithFrontmatter(`status: missing
+story: ${dir}/story.md`, `# TDD Evidence: ${options.intent}
 
 ## Red
 

package/dist/commands/quick.js

@@ -1,4 +1,4 @@
-import { markdown, writeManagedFiles } from "../core/managed-files.js";
+import { markdownWithFrontmatter, writeManagedFiles } from "../core/managed-files.js";
 import { slugify, timestamp } from "../core/slug.js";
 import { detectPreferredTestCommand } from "../core/test-detection.js";
 export async function quickCommand(options) {
@@ -11,13 +11,9 @@ export async function quickCommand(options) {
     await writeManagedFiles(options.root, [
         {
             path: storyPath,
-            content: markdown(`---
-status: ready-for-dev
+            content: markdownWithFrontmatter(`status: ready-for-dev
 evidence: ${evidencePath}
-context: pending
----
-
-# Story: ${options.intent}
+context: pending`, `# Story: ${options.intent}
 
 ## Intent
 ${options.intent}
@@ -46,12 +42,8 @@ ${options.intent}
         },
         {
             path: evidencePath,
-            content: markdown(`---
-status: missing
-story: ${storyPath}
----
-
-# TDD Evidence: ${options.intent}
+            content: markdownWithFrontmatter(`status: missing
+story: ${storyPath}`, `# TDD Evidence: ${options.intent}
 
 ## Test Intent
 

package/dist/commands/validate.d.ts

@@ -0,0 +1,6 @@
+export type ValidateOptions = {
+    root: string;
+    json?: boolean;
+    stdout?: Pick<typeof console, "log" | "error">;
+};
+export declare function validateCommand(options: ValidateOptions): Promise<number>;

package/dist/commands/validate.js

@@ -0,0 +1,17 @@
+import { validateWorkflowContract } from "../core/workflow-validator.js";
+export async function validateCommand(options) {
+    const stdout = options.stdout ?? console;
+    const checks = await validateWorkflowContract(options.root);
+    const status = checks.every((check) => check.ok) ? "ok" : "needs-attention";
+    const report = { status, checks };
+    if (options.json) {
+        stdout.log(JSON.stringify(report, null, 2));
+    }
+    else {
+        stdout.log(`Speckit workflow contract: ${status}`);
+        for (const check of checks) {
+            stdout.log(`${check.ok ? "ok" : "fail"} ${check.name}: ${check.detail}`);
+        }
+    }
+    return status === "ok" ? 0 : 1;
+}

package/dist/core/agent-scaffold.js

@@ -8,7 +8,7 @@ export function agentFiles() {
 
 ## Mission
 
-Act as the controller for Speckit enterprise work. Do not be the only worker when context isolation is useful; route work through focused skills and subagent handoffs.
+Act as the controller for Speckit enterprise work. Route intent into the smallest useful skill, preserve artifact continuity, and keep implementation bound to Agile + TDD evidence.
 
 ## Load Order
 
@@ -27,6 +27,19 @@ Act as the controller for Speckit enterprise work. Do not be the only worker whe
 - Use graph skills before choosing or reordering work.
 - Use session skills at every task boundary.
 - Use review skills before closure.
+- Load only the current workflow step and directly referenced artifacts.
+- Prefer artifact evidence over conversational memory.
+- Halt when the next action would cross from plan to code without a ready story.
+
+## Workflow State Machine
+
+1. Shape rough intent into bounded value and non-goals.
+2. Plan PRD, architecture, epics, stories, risks, and rollback.
+3. Prepare sprint status and graph sync.
+4. Build current context and subagent handoff.
+5. Run ready story through red-green-refactor.
+6. Review spec compliance, edge cases, and production readiness.
+7. Close by syncing story, session, docs, and graph artifacts.
 
 ## Delegation Contract
 
@@ -50,6 +63,14 @@ Subagents must finish with one status: \`DONE\`, \`DONE_WITH_CONCERNS\`, \`BLOCK
 - Prefer focused subagent handoffs over passing full conversation history.
 - Hydrate runtime tasks from unchecked plan/story checkboxes at session start.
 - Sync completed runtime tasks back to durable plan/story files before close.
+
+## Output Contract
+
+- State selected skill and why.
+- State artifacts read and artifacts updated.
+- State current story status and evidence status for code work.
+- State next command or halt reason.
+- Never claim completion without verification evidence.
 `),
         },
         ...specSkillFiles(),

package/dist/core/managed-files.d.ts

@@ -2,6 +2,7 @@ export declare const MANAGED_MARKER = "speckit:managed";
 export type ManagedFile = {
     path: string;
     content: string;
+    isManaged?: (content: string) => boolean;
 };
 export type WriteResult = {
     path: string;
@@ -10,5 +11,9 @@ export type WriteResult = {
 };
 export declare function writeManagedFiles(root: string, files: ManagedFile[], force?: boolean): Promise<WriteResult[]>;
 export declare function markdown(content: string): string;
+export declare function markdownWithFrontmatter(frontmatter: string, content: string): string;
 export declare function json(content: unknown): string;
+export declare function strictJson(content: unknown): string;
+export declare function strictJsonManaged(content: unknown): Pick<ManagedFile, "content" | "isManaged">;
+export declare function legacyJsonManaged(content: string): boolean;
 export declare function text(content: string, comment?: string): string;

package/dist/core/managed-files.js

@@ -13,7 +13,10 @@ export async function writeManagedFiles(root, files, force = false) {
         catch {
             existing = undefined;
         }
-        if (existing && !existing.includes(MANAGED_MARKER) && !force) {
+        const isManaged = existing
+            ? existing.includes(MANAGED_MARKER) || file.isManaged?.(existing) === true
+            : false;
+        if (existing && !isManaged && !force) {
             results.push({
                 path: file.path,
                 status: "skipped",
@@ -32,9 +35,38 @@ export async function writeManagedFiles(root, files, force = false) {
 export function markdown(content) {
     return `<!-- ${MANAGED_MARKER} -->\n${content.trim()}\n`;
 }
+export function markdownWithFrontmatter(frontmatter, content) {
+    return `---\n${frontmatter.trim()}\n---\n<!-- ${MANAGED_MARKER} -->\n${content.trim()}\n`;
+}
 export function json(content) {
     return `${JSON.stringify({ "x-speckit-managed": MANAGED_MARKER, ...asObject(content) }, null, 2)}\n`;
 }
+export function strictJson(content) {
+    return `${JSON.stringify(content, null, 2)}\n`;
+}
+export function strictJsonManaged(content) {
+    return {
+        content: strictJson(content),
+        isManaged: (existing) => legacyJsonManaged(existing) || jsonMatches(existing, content),
+    };
+}
+export function legacyJsonManaged(content) {
+    try {
+        const parsed = JSON.parse(content);
+        return parsed["x-speckit-managed"] === MANAGED_MARKER;
+    }
+    catch {
+        return false;
+    }
+}
+function jsonMatches(content, expected) {
+    try {
+        return JSON.stringify(JSON.parse(content)) === JSON.stringify(expected);
+    }
+    catch {
+        return false;
+    }
+}
 export function text(content, comment = "#") {
     return `${comment} ${MANAGED_MARKER}\n${content.trim()}\n`;
 }