@trieungoctam/speckit 0.3.0 → 0.3.1

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,12 @@ 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/spec-quality-gates.md` describes validation gates for release readiness.
+
 ## Validation
 
 ```bash

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

@@ -34,6 +34,22 @@ Use Speckit for Agile + TDD work.
                 content: json({
                     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,
                 }),

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

package/dist/adapters/cursor-adapter.js

@@ -8,6 +8,7 @@ export const cursorAdapter = {
         ".cursor/rules/speckit-review.mdc",
         ".cursor/rules/speckit-enterprise-safety.mdc",
         ".cursor/mcp.json",
+        ".cursor/cli.json",
         "AGENTS.md",
     ],
     render() {
@@ -22,6 +23,28 @@ export const cursorAdapter = {
                     mcpServers: {},
                 }),
             },
+            {
+                path: ".cursor/cli.json",
+                content: json({
+                    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)",
+                        ],
+                    },
+                }),
+            },
             {
                 path: "AGENTS.md",
                 content: markdown(`# Speckit Agent Instructions

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/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/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/permission-auditor.d.ts

@@ -0,0 +1,10 @@
+export type PermissionAuditInput = {
+    path?: string;
+    command?: string;
+};
+export type PermissionAuditResult = {
+    status: "allow" | "ask" | "deny";
+    reasons: string[];
+};
+export declare function auditPermission(input: PermissionAuditInput): PermissionAuditResult;
+export declare function validatePermissionPolicy(root: string): Promise<string[]>;

package/dist/core/permission-auditor.js

@@ -0,0 +1,65 @@
+import { readFile } from "node:fs/promises";
+import { basename, join } from "node:path";
+import { destructiveCommands, heavyPatterns, releaseCommands, sensitivePatterns } from "./permission-policy.js";
+const safeSecretSuffixes = [".example", ".sample", ".template"];
+export function auditPermission(input) {
+    const reasons = [];
+    if (input.path) {
+        if (isSensitivePath(input.path))
+            reasons.push(`privacy:${input.path}`);
+        if (isHeavyPath(input.path))
+            reasons.push(`scout:${input.path}`);
+    }
+    if (input.command) {
+        if (matchesAny(input.command, destructiveCommands))
+            reasons.push(`destructive:${input.command}`);
+        if (matchesAny(input.command, releaseCommands)) {
+            return { status: reasons.length > 0 ? "deny" : "ask", reasons: [`release:${input.command}`, ...reasons] };
+        }
+    }
+    return reasons.length > 0 ? { status: "deny", reasons } : { status: "allow", reasons };
+}
+export async function validatePermissionPolicy(root) {
+    const content = await read(join(root, ".speckit/permissions.yaml"));
+    const missing = [];
+    if (!content)
+        return ["missing .speckit/permissions.yaml"];
+    for (const token of ["precedence:", "privacy:", "scout:", "destructive:", "release:", "file_write: ask"]) {
+        if (!content.includes(token))
+            missing.push(token);
+    }
+    for (const pattern of [".env", "node_modules", "git reset --hard*", "npm publish*"]) {
+        if (!content.includes(pattern))
+            missing.push(pattern);
+    }
+    return missing;
+}
+function isSensitivePath(path) {
+    const clean = normalize(path);
+    const name = basename(clean);
+    if (safeSecretSuffixes.some((suffix) => name.endsWith(suffix)))
+        return false;
+    return sensitivePatterns.some((pattern) => matchGlob(clean, pattern));
+}
+function isHeavyPath(path) {
+    const parts = normalize(path).split("/");
+    return heavyPatterns.some((pattern) => parts.includes(pattern.replace(/"/g, "")));
+}
+function matchesAny(command, patterns) {
+    return patterns.some((pattern) => matchGlob(command.trim(), pattern));
+}
+function matchGlob(value, pattern) {
+    const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*\*/g, ".*").replace(/\*/g, ".*");
+    return new RegExp(`^${escaped}$`).test(value) || new RegExp(escaped).test(value);
+}
+function normalize(value) {
+    return value.replace(/\\/g, "/");
+}
+async function read(path) {
+    try {
+        return await readFile(path, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/core/permission-policy.d.ts

@@ -0,0 +1,6 @@
+import { ManagedFile } from "./managed-files.js";
+export declare const sensitivePatterns: string[];
+export declare const heavyPatterns: string[];
+export declare const destructiveCommands: string[];
+export declare const releaseCommands: string[];
+export declare function permissionPolicyFile(): ManagedFile;

package/dist/core/permission-policy.js

@@ -0,0 +1,93 @@
+import { text } from "./managed-files.js";
+export const sensitivePatterns = [
+    ".env",
+    ".env.*",
+    "**/.env",
+    "**/.env.*",
+    "**/credentials*",
+    "**/secret.yml",
+    "**/secrets.yml",
+    "**/secret.yaml",
+    "**/secrets.yaml",
+    "**/*.pem",
+    "**/*.key",
+    "**/id_rsa",
+    "**/id_ed25519",
+];
+export const heavyPatterns = [
+    "node_modules",
+    "dist",
+    "build",
+    ".next",
+    ".nuxt",
+    "__pycache__",
+    ".venv",
+    "venv",
+    "vendor",
+    "target",
+    ".git",
+    "coverage",
+];
+export const destructiveCommands = [
+    "rm -rf*",
+    "git reset --hard*",
+    "git clean -fd*",
+    "git push --force*",
+    "sudo *",
+    "chmod -R*",
+    "chown -R*",
+];
+export const releaseCommands = ["git push*", "npm publish*", "* deploy*", "vercel --prod*", "fly deploy*"];
+export function permissionPolicyFile() {
+    return {
+        path: ".speckit/permissions.yaml",
+        content: text(`version: 1
+mode: enterprise
+precedence:
+  - deny
+  - ask
+  - allow
+defaults:
+  file_read: allow_workspace
+  file_write: ask
+  shell: ask
+  network: ask
+  external_directory: deny
+guards:
+  privacy:
+    action: deny
+    allow_examples: true
+    patterns:
+${sensitivePatterns.map((pattern) => `      - "${pattern}"`).join("\n")}
+  scout:
+    action: deny
+    patterns:
+${heavyPatterns.map((pattern) => `      - "${pattern}"`).join("\n")}
+  destructive:
+    action: deny
+    commands:
+${destructiveCommands.map((command) => `      - "${command}"`).join("\n")}
+  release:
+    action: ask
+    commands:
+${releaseCommands.map((command) => `      - "${command}"`).join("\n")}
+phases:
+  shape:
+    file_write:
+      - ".speckit/specs/**"
+  plan:
+    file_write:
+      - ".speckit/plans/**"
+      - ".speckit/stories/**"
+      - ".speckit/evidence/**"
+  review:
+    file_write: deny
+    shell_allow:
+      - "git diff*"
+      - "git log*"
+      - "npm test*"
+  ship:
+    shell_ask:
+${releaseCommands.map((command) => `      - "${command}"`).join("\n")}`),
+    };
+}

package/dist/core/scaffold.js

@@ -1,5 +1,6 @@
 import { markdown, text } from "./managed-files.js";
 import { agilePolicy, enterpriseSafetyPolicy, tddPolicy, workflowReview, workflowShape, workflowTddRun, } from "./policy.js";
+import { permissionPolicyFile } from "./permission-policy.js";
 import { storyTemplate, tddEvidenceTemplate } from "./templates.js";
 export function coreFiles() {
     return [
@@ -31,6 +32,7 @@ adapters:
             path: ".speckit/rules/enterprise-safety.md",
             content: markdown(enterpriseSafetyPolicy),
         },
+        permissionPolicyFile(),
         { path: ".speckit/workflows/shape.md", content: markdown(workflowShape) },
         { path: ".speckit/workflows/tdd-run.md", content: markdown(workflowTddRun) },
         { path: ".speckit/workflows/review.md", content: markdown(workflowReview) },

package/dist/core/skill-catalog.d.ts

@@ -1,2 +1,3 @@
 import { ManagedFile } from "./managed-files.js";
 export declare function specSkillFiles(): ManagedFile[];
+export declare function specSkillNames(): string[];

package/dist/core/skill-catalog.js

@@ -87,6 +87,9 @@ function skill(name, phase, purpose, practices) {
 export function specSkillFiles() {
     return [catalogFile(), schemaFile(), ...skills.map(skillFile)];
 }
+export function specSkillNames() {
+    return skills.map((skill) => skill.name);
+}
 function catalogFile() {
     return {
         path: ".speckit/skills/catalog.md",

package/dist/core/workflow-contract.d.ts

@@ -0,0 +1,7 @@
+export declare const workflowContract: {
+    readonly phases: readonly ["start", "memory", "sprint", "context", "sync", "triage", "ready", "run", "checkpoint", "review", "close"];
+    readonly skills: string[];
+    readonly statuses: readonly ["DONE", "DONE_WITH_CONCERNS", "BLOCKED", "NEEDS_CONTEXT"];
+    readonly requiredPromptTerms: readonly [readonly ["project memory", ".speckit/memory/project-context.md"], readonly ["active session", ".speckit/sessions/active.md"], readonly ["current context", ".speckit/context/current.md"], readonly ["subagent handoff", ".speckit/context/subagent-handoff.md"], readonly ["acceptance criteria", "AC coverage", "ACs"], readonly ["red-green-refactor", "red/green/refactor"], readonly ["checkpoint", "speckit session checkpoint"], readonly ["compact", "compaction", "speckit session compact"], readonly ["robot-safe", "bv --robot", "robot commands"], readonly ["ready-for-dev", "speckit ready"]];
+    readonly requiredRouterTerms: readonly ["smallest matching Speckit skill", "Work context path", "Reports path", "Plans path", "Hydrate runtime tasks", "Sync completed runtime tasks"];
+};

package/dist/core/workflow-contract.js

@@ -0,0 +1,38 @@
+import { specSkillNames } from "./skill-catalog.js";
+export const workflowContract = {
+    phases: [
+        "start",
+        "memory",
+        "sprint",
+        "context",
+        "sync",
+        "triage",
+        "ready",
+        "run",
+        "checkpoint",
+        "review",
+        "close",
+    ],
+    skills: specSkillNames(),
+    statuses: ["DONE", "DONE_WITH_CONCERNS", "BLOCKED", "NEEDS_CONTEXT"],
+    requiredPromptTerms: [
+        ["project memory", ".speckit/memory/project-context.md"],
+        ["active session", ".speckit/sessions/active.md"],
+        ["current context", ".speckit/context/current.md"],
+        ["subagent handoff", ".speckit/context/subagent-handoff.md"],
+        ["acceptance criteria", "AC coverage", "ACs"],
+        ["red-green-refactor", "red/green/refactor"],
+        ["checkpoint", "speckit session checkpoint"],
+        ["compact", "compaction", "speckit session compact"],
+        ["robot-safe", "bv --robot", "robot commands"],
+        ["ready-for-dev", "speckit ready"],
+    ],
+    requiredRouterTerms: [
+        "smallest matching Speckit skill",
+        "Work context path",
+        "Reports path",
+        "Plans path",
+        "Hydrate runtime tasks",
+        "Sync completed runtime tasks",
+    ],
+};

package/dist/core/workflow-validator.d.ts

@@ -0,0 +1,6 @@
+export type ContractCheck = {
+    name: string;
+    ok: boolean;
+    detail: string;
+};
+export declare function validateWorkflowContract(root: string): Promise<ContractCheck[]>;

package/dist/core/workflow-validator.js

@@ -0,0 +1,133 @@
+import { access, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { getAdapters } from "../config/adapter-registry.js";
+import { validatePermissionPolicy } from "./permission-auditor.js";
+import { workflowContract } from "./workflow-contract.js";
+export async function validateWorkflowContract(root) {
+    const checks = [];
+    const catalog = await read(root, ".speckit/skills/catalog.md");
+    const router = await read(root, ".speckit/agents/super-agent.md");
+    const flow = await read(root, ".speckit/flows/spec-flow.md");
+    const runPrompt = await read(root, ".speckit/prompts/spec-run.md");
+    checks.push(requiredFile(".speckit/skills/catalog.md", catalog));
+    checks.push(requiredFile(".speckit/agents/super-agent.md", router));
+    checks.push(requiredFile(".speckit/flows/spec-flow.md", flow));
+    checks.push(requiredFile(".speckit/prompts/spec-run.md", runPrompt));
+    checks.push(await skillsCheck(root, catalog));
+    checks.push(containsAll("super-agent router", router, workflowContract.requiredRouterTerms));
+    checks.push(orderedFlowCheck(flow));
+    checks.push(containsAll("enterprise run prompt", runPrompt, workflowContract.requiredPromptTerms));
+    checks.push(await permissionPolicyCheck(root));
+    checks.push(await adapterPromptCheck(root));
+    return checks;
+}
+async function permissionPolicyCheck(root) {
+    const missing = await validatePermissionPolicy(root);
+    return {
+        name: "permission policy",
+        ok: missing.length === 0,
+        detail: missing.length === 0 ? "aligned" : `missing: ${missing.join(", ")}`,
+    };
+}
+function requiredFile(path, content) {
+    return {
+        name: path,
+        ok: content !== undefined,
+        detail: content === undefined ? "missing" : "present",
+    };
+}
+async function skillsCheck(root, catalog) {
+    const missing = [];
+    for (const skill of workflowContract.skills) {
+        if (!(await exists(root, `.speckit/skills/${skill}.md`)) || !catalog?.includes(skill)) {
+            missing.push(skill);
+        }
+    }
+    return {
+        name: "core skills",
+        ok: missing.length === 0,
+        detail: missing.length === 0 ? `${workflowContract.skills.length} skills aligned` : `missing: ${missing.join(", ")}`,
+    };
+}
+function orderedFlowCheck(flow) {
+    if (!flow)
+        return { name: "workflow phase order", ok: false, detail: "flow file missing" };
+    let cursor = -1;
+    const missing = [];
+    for (const phase of workflowContract.phases) {
+        const next = flow.indexOf(phase, cursor + 1);
+        if (next === -1) {
+            missing.push(phase);
+            continue;
+        }
+        cursor = next;
+    }
+    return {
+        name: "workflow phase order",
+        ok: missing.length === 0,
+        detail: missing.length === 0 ? workflowContract.phases.join(" -> ") : `missing or out of order: ${missing.join(", ")}`,
+    };
+}
+function containsAll(name, content, terms) {
+    const haystack = content?.toLowerCase() ?? "";
+    const missing = terms.filter((term) => !matchesTerm(haystack, term)).map(termLabel);
+    return {
+        name,
+        ok: missing.length === 0,
+        detail: missing.length === 0 ? "aligned" : `missing: ${missing.join(", ")}`,
+    };
+}
+function matchesTerm(haystack, term) {
+    const alternatives = Array.isArray(term) ? term : [term];
+    return alternatives.some((alternative) => haystack.includes(alternative.toLowerCase()));
+}
+function termLabel(term) {
+    return typeof term === "string" ? term : term[0];
+}
+async function adapterPromptCheck(root) {
+    const missing = [];
+    const checked = [];
+    for (const adapter of getAdapters("all")) {
+        const content = await readExisting(root, adapter.outputPaths);
+        if (!content)
+            continue;
+        checked.push(adapter.name);
+        const check = containsAll(adapter.name, content, workflowContract.requiredPromptTerms);
+        if (!check.ok)
+            missing.push(`${adapter.name} (${check.detail})`);
+    }
+    if (checked.length === 0) {
+        return { name: "adapter prompt contracts", ok: false, detail: "no adapter files found" };
+    }
+    return {
+        name: "adapter prompt contracts",
+        ok: missing.length === 0,
+        detail: missing.length === 0 ? `aligned: ${checked.join(", ")}` : missing.join("; "),
+    };
+}
+async function readExisting(root, paths) {
+    const chunks = [];
+    for (const path of paths) {
+        const content = await read(root, path);
+        if (content)
+            chunks.push(content);
+    }
+    return chunks.length > 0 ? chunks.join("\n") : undefined;
+}
+async function read(root, path) {
+    try {
+        return await readFile(join(root, path), "utf8");
+    }
+    catch {
+        return undefined;
+    }
+}
+async function exists(root, path) {
+    try {
+        await access(join(root, path));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/docs/development-roadmap.md

@@ -4,7 +4,7 @@
 
 Speckit MVP is implemented and pushed to `git@github.com:trieungoctam/speckit.git` on `main`.
 
-Current package target: `@trieungoctam/speckit@0.3.0`.
+Current package target: `@trieungoctam/speckit@0.3.1`.
 
 The CLI is npx-ready, generates Agile + TDD rules, creates workflow artifacts, supports five IDE adapters, wraps Beads Viewer safely, includes an enterprise harness, and has automated prompt/readiness/session tests plus CI.
 
@@ -21,6 +21,8 @@ The CLI is npx-ready, generates Agile + TDD rules, creates workflow artifacts, s
 | Sprint automation | MVP Complete | `sprint plan` and `sprint next` select work from synced stories. |
 | Enterprise harness | MVP Complete | `init --enterprise` creates flow, tool-policy, and prompt harness files; `doctor --deep` verifies them. |
 | Curated skill catalog | Complete | Speckit now generates focused phase skills, a schema, delegation statuses, and task hydration/sync-back guidance. |
+| Workflow contract validator | Complete | `speckit validate` and `doctor --deep` check phase order, core skills, router terms, run prompt terms, and adapter parity. |
+| Permission policy | MVP Complete | `.speckit/permissions.yaml` and `permissions audit` cover privacy files, heavy paths, destructive commands, and release commands. |
 | Validation | Complete | Build and `node:test` suite pass locally with flow contract gates. |
 | GitHub publish | Complete | Initial code pushed to `trieungoctam/speckit` at commit `7e5c582`; status docs follow-up in progress. |
 | npm package readiness | Ready | Package scoped as `@trieungoctam/speckit`; `npm pack --dry-run` passes. |

package/docs/permission-rules-research.md

@@ -0,0 +1,265 @@
+# Permission Rules Research
+
+Date: 2026-05-10
+
+## Scope
+
+Research goal: define a permission-rule model for Speckit that can compile safely across Claude Code, Codex, Cursor, OpenCode, and Antigravity.
+
+This research focuses on:
+
+- File read/write permissions
+- Shell command permissions
+- Network access
+- Approval modes
+- Phase-specific workflow permissions
+- Enterprise guardrails for secrets, destructive commands, and production access
+
+## Key Findings
+
+### 1. Permission Rules Must Be Deny-First
+
+Claude Code documents allow, ask, and deny rules, with evaluation order `deny -> ask -> allow`; deny rules always take precedence. Cursor CLI also documents deny rules taking precedence over allow rules.
+
+Speckit should use the same mental model across all adapters:
+
+```text
+deny > ask > allow
+```
+
+This should be a product invariant, even when a specific IDE has a different internal matching implementation.
+
+Sources:
+
+- [Claude Code permissions](https://code.claude.com/docs/en/permissions)
+- [Cursor permissions](https://docs.cursor.com/cli/reference/permissions)
+
+### 2. Permissions And Sandboxing Are Different Layers
+
+Claude Code separates permissions from sandboxing: permissions control tool/file/domain access, while sandboxing enforces OS-level limits mainly around shell execution. OpenAI describes the same split for Codex: sandboxing defines execution boundaries, while approval policy decides when the agent must ask.
+
+Speckit should model both layers:
+
+- Permission policy: what the agent may attempt.
+- Sandbox/approval policy: what the runtime may execute without approval.
+
+Sources:
+
+- [Claude Code permissions and sandboxing](https://code.claude.com/docs/en/permissions)
+- [Running Codex safely at OpenAI](https://openai.com/index/running-codex-safely/)
+- [Codex agent approvals and security](https://developers.openai.com/codex/agent-approvals-security)
+
+### 3. Avoid Full Bypass Modes Except In Disposable Environments
+
+Claude Code warns that bypass mode skips permission prompts and should only be used in isolated environments such as containers or VMs. Codex similarly labels no-sandbox/no-approval mode as dangerous and not recommended.
+
+Speckit should never generate full-bypass configs by default.
+
+Recommended default:
+
+```text
+approval: ask/on-request
+sandbox: workspace-write
+network: ask or denied by default
+```
+
+Sources:
+
+- [Claude Code permission modes](https://code.claude.com/docs/en/permissions)
+- [Codex common sandbox and approval combinations](https://developers.openai.com/codex/agent-approvals-security)
+
+### 4. Phase-Scoped Permissions Fit Speckit Best
+
+Speckit already has phases: shape, research, plan, context, graph, session, TDD, test, debug, review, docs, ship.
+
+Permission should follow phase, not only IDE:
+
+| Phase | File Writes | Shell | Network | Notes |
+| --- | --- | --- | --- | --- |
+| shape | `.speckit/specs/**` only | ask | ask | No source edits |
+| research | reports/docs only | ask | allow/ask | Sources required |
+| plan | `.speckit/plans/**`, stories, evidence | ask | ask | No source edits |
+| context | `.speckit/context/**` only | ask | deny/ask | Build handoff only |
+| graph | `.speckit/sync/**`, `.beads/**` | allow Speckit wrappers | deny/ask | Robot-safe graph only |
+| session | `.speckit/sessions/**`, memory | ask | deny | Durable state only |
+| TDD | workspace source + tests | ask | ask | Requires ready gate |
+| test | test artifacts only | allow test/build commands | deny/ask | No production |
+| debug | source + tests after root cause | ask | ask | Capture failure first |
+| review | no edits by default | allow `git diff`, `git log`, tests | deny | Read-only review |
+| docs | docs + Speckit artifacts | ask | deny/ask | No source edits unless requested |
+| ship | package/release files | ask | ask | Push/publish/deploy require explicit approval |
+
+### 5. Adapter Mapping
+
+#### Claude Code
+
+Use `.claude/settings.json`:
+
+- `permissions.defaultMode = "ask"` or conservative equivalent
+- explicit deny rules for secrets and destructive commands
+- ask rules for shell/network/publish/deploy
+- optional hooks for runtime validation
+- managed settings for enterprise to disable bypass/auto modes
+
+Relevant details:
+
+- Permission rule syntax supports `Tool` and `Tool(specifier)`.
+- Bash rules support wildcards.
+- Hooks can deny or force prompts before permission rules finish.
+- Managed settings can prevent bypass mode and restrict user/project rules.
+
+Source: [Claude Code permissions](https://code.claude.com/docs/en/permissions)
+
+#### Codex
+
+Use `.codex/config.toml`:
+
+```toml
+approval_policy = "on-request"
+sandbox_mode = "workspace-write"
+```
+
+Enterprise hardening can use requirements:
+
+```toml
+allowed_approval_policies = ["untrusted", "on-request"]
+allowed_sandbox_modes = ["read-only", "workspace-write"]
+```
+
+Avoid `danger-full-access` and no-approval modes for normal projects.
+
+Sources:
+
+- [Codex config reference](https://developers.openai.com/codex/config-reference)
+- [Codex managed configuration](https://developers.openai.com/codex/enterprise/managed-configuration)
+- [Codex agent approvals and security](https://developers.openai.com/codex/agent-approvals-security)
+
+#### Cursor
+
+Use project-level `.cursor/cli.json` for CLI permissions:
+
+```json
+{
+  "permissions": {
+    "allow": ["Shell(git)", "Shell(npm)", "Read(src/**/*.ts)"],
+    "deny": ["Shell(rm)", "Read(.env*)", "Write(**/*.key)", "Write(**/.env*)"]
+  }
+}
+```
+
+Cursor permission tokens cover:
+
+- `Shell(commandBase)`
+- `Read(pathOrGlob)`
+- `Write(pathOrGlob)`
+
+Source: [Cursor permissions](https://docs.cursor.com/cli/reference/permissions)
+
+#### OpenCode
+
+Use `permission` in `opencode.json` and Markdown agents.
+
+OpenCode supports:
+
+- `ask`
+- `allow`
+- `deny`
+- per-agent override
+- specific bash command patterns
+- task permission controls
+
+For Speckit, keep planner/reviewer read-only, TDD developer ask-gated, and ship commands ask-gated.
+
+Source: [OpenCode agents and permissions](https://opencode.ai/docs/agents/)
+
+#### Antigravity
+
+The accessible public docs emphasize configurable autonomy, artifact review, and approval for critical operations, but the browsable official pages did not expose a stable machine-readable permission schema during this research.
+
+Speckit should treat Antigravity permissions as instruction-level until a stable official config format is confirmed:
+
+- generate `.agents/rules/speckit-enterprise-safety.md`
+- require human approval for destructive commands, production changes, secrets access, deployment
+- require artifact review before close
+- avoid claiming hard enforcement unless adapter support is verified
+
+Source:
+
+- [Antigravity agents overview](https://antigravity.im/agents) — independent guide, not official Google documentation
+
+## Recommended Speckit Permission Model
+
+Speckit should own a portable policy and compile it per IDE:
+
+```yaml
+version: 1
+default:
+  file_read: allow_workspace
+  file_write: ask
+  shell: ask
+  network: ask
+  external_directory: deny
+  secrets: deny
+  destructive: deny
+  production: ask
+phases:
+  review:
+    file_write: deny
+    shell_allow:
+      - git diff*
+      - git log*
+      - npm test*
+  ship:
+    shell_ask:
+      - git push*
+      - npm publish*
+      - "* deploy*"
+```
+
+## Commands To Add
+
+Recommended CLI surface:
+
+```bash
+speckit permissions init
+speckit permissions audit --json
+speckit permissions compile --ide all
+speckit validate --permissions --json
+```
+
+Minimum useful implementation:
+
+1. Generate `.speckit/permissions.yaml`.
+2. Add permission checks to `speckit validate`.
+3. Compile:
+   - Claude Code: `.claude/settings.json`
+   - Codex: `.codex/config.toml`
+   - Cursor: `.cursor/cli.json`
+   - OpenCode: `opencode.json` and agent frontmatter
+   - Antigravity: `.agents/rules/speckit-enterprise-safety.md`
+
+## High-Risk Defaults To Block
+
+Always deny or ask:
+
+- `rm -rf`, `rmdir`, destructive cleanup
+- `git reset --hard`, `git clean -fd`, force push
+- `sudo`, `chmod -R`, `chown -R`
+- shell access to `.env*`, `*.pem`, `*.key`, SSH keys, cloud credentials
+- production deploys
+- package publish
+- arbitrary outbound network from shell
+- external directory writes
+
+## Recommendation
+
+Implement permission rules as the next Speckit enterprise layer.
+
+Priority:
+
+1. Add central `.speckit/permissions.yaml`.
+2. Extend `validateWorkflowContract` with permission checks.
+3. Compile concrete adapter permission files.
+4. Add tests that tamper with dangerous permissions and ensure validation fails.
+
+This keeps Speckit aligned with the strongest common pattern across current agent IDEs: deny-first, least-privilege, phase-scoped, with explicit approval for risky operations.

package/docs/product-contract.md

@@ -5,13 +5,15 @@ Speckit owns the workflow contract for enterprise Agile + TDD development with a
 ## Speckit Owns
 
 - The `.speckit/` source of truth: config, rules, workflows, templates, generated artifacts.
-- The command surface: `init`, `doctor`, `start`, `memory`, `session`, `shape`, `plan`, `context`, `quick`, `sync`, `triage`, `sprint`, `graph`, `next`, `ready`, `run`, `review`, `close`.
+- The command surface: `init`, `doctor`, `validate`, `start`, `memory`, `permissions`, `session`, `shape`, `plan`, `context`, `quick`, `sync`, `triage`, `sprint`, `graph`, `next`, `ready`, `run`, `review`, `close`.
 - The skill catalog and super-agent routing contract for phase-specific agent behavior.
 - IDE-specific initialization that installs the shared Speckit runtime plus only the selected IDE adapter when `--ide <name>` is provided.
 - The long-session contract: project memory, active session state, checkpoints, compaction summaries, and resume handoffs.
+- The workflow validation contract: phase order, core skills, super-agent routing, run prompt terms, and installed adapter prompt parity.
 - The TDD gate: code stories require red, green, and refactor evidence.
 - The adapter compiler for Claude Code, Codex, Antigravity, OpenCode, and Cursor.
 - The safety policy for destructive commands, secrets, production access, and review readiness.
+- The permission policy for privacy-sensitive files, context-heavy paths, destructive commands, and release commands.
 
 ## Speckit Delegates
 

package/docs/project-changelog.md

@@ -1,5 +1,15 @@
 # Project Changelog
 
+## 0.3.1 - 2026-05-11
+
+### Changed
+
+- Prepared npm release for the workflow validation and permission policy package updates.
+
+### Validation
+
+- `npm test` passes with 36 tests.
+
 ## 0.3.0 - 2026-05-10
 
 ### Added
@@ -11,6 +21,11 @@
 - Added `.speckit/agents/super-agent.md` as the portable orchestration router.
 - Added `.speckit/skills/catalog.md` plus a curated Speckit skill set for shape, research, plan, context, graph, session, TDD, test, debug, review, docs, and ship phases.
 - Added `.speckit/skills/schema.json` to define the portable skill contract and delegation statuses.
+- Added `speckit validate` for workflow contract validation across phase order, skills, router, prompts, and installed adapters.
+- Added `contractChecks` to `speckit doctor --deep --json`.
+- Added `docs/use-cases.md` with command recipes and best practices for setup, migration, quick changes, full planning, long sessions, TDD, graph automation, review, CI, and troubleshooting.
+- Added `.speckit/permissions.yaml` and `speckit permissions audit` for privacy, scout, destructive-command, and release-command checks.
+- Added concrete permission output for Claude Code, Codex, and Cursor adapters.
 - Added long-session prompt requirements for project memory, active session state, checkpoints, and compaction summaries.
 - Added automatic `.beads/beads.jsonl` mirror generation so Beads Viewer robot commands can run without missing-project errors.
 - Standard `speckit init --ide <name>` now installs the shared Speckit runtime, super-agent, and skill catalog for the selected IDE.
@@ -29,6 +44,7 @@
 - Added workflow tests for memory/session state, sprint planning, and graph fallback.
 - Expanded prompt quality tests for project memory, active session, checkpoint, and compaction.
 - Added init and flow contract coverage for the curated skill catalog.
+- Added workflow validator tests for passing and tampered contract states.
 
 ## 0.2.2 - 2026-05-10
 

package/docs/use-cases.md

@@ -0,0 +1,206 @@
+# Use Cases And Best Practices
+
+This guide shows how to use Speckit for common product and engineering workflows.
+
+## 1. New Project Setup
+
+Use when a repository does not have Speckit runtime files yet.
+
+```bash
+npx @trieungoctam/speckit@latest init --enterprise --ide cursor
+npx @trieungoctam/speckit@latest doctor --deep
+npx @trieungoctam/speckit@latest validate
+```
+
+Use `--ide all` only when the team actively uses multiple IDEs in the same repository.
+
+Best practices:
+
+- Prefer one IDE adapter per project at first. Add more adapters after the team agrees on the workflow.
+- Run `speckit validate` after init so broken prompts or missing skills are caught immediately.
+- Commit generated Speckit files so every teammate gets the same flow.
+- Keep `.speckit/` local to the repository. Avoid relying on global agent state for enterprise work.
+
+## 2. Existing Project Migration
+
+Use when a project already has code, tests, and team conventions.
+
+```bash
+speckit init --enterprise --ide all --force
+speckit memory refresh
+speckit doctor --deep --json
+speckit validate --json
+```
+
+Best practices:
+
+- Read generated files before pushing. Keep project-specific rules in `.speckit/memory/project-context.md`.
+- Do not start implementation during migration. First make the generated flow pass validation.
+- If an adapter prompt conflicts with local policy, update the adapter generator, not only the generated file.
+- Run project tests after migration even if Speckit only changed documentation and prompt files.
+
+## 3. One Small Change
+
+Use when the request is bounded and can fit into one story.
+
+```bash
+speckit memory refresh
+speckit session start "Add invoice total validation"
+speckit quick "Add invoice total validation"
+speckit context .speckit/stories/<story>.md
+speckit sync
+speckit ready .speckit/stories/<story>.md
+speckit run .speckit/stories/<story>.md
+```
+
+Best practices:
+
+- Use `quick` only for a single focused change.
+- Do not skip `context`, `sync`, or `ready`. They prevent agents from implementing against stale assumptions.
+- Keep acceptance criteria concrete enough to test.
+- Checkpoint after the red test, green test, refactor, and review boundary.
+
+## 4. Full Feature Planning
+
+Use when the work includes multiple stories, architecture decisions, or team rollout.
+
+```bash
+speckit session start "Add subscription lifecycle"
+speckit memory refresh
+speckit shape "Add subscription lifecycle"
+speckit plan "Add subscription lifecycle"
+speckit sync
+speckit sprint plan
+speckit graph triage --json
+```
+
+Best practices:
+
+- Shape before planning. The shape artifact defines scope, non-goals, and risk.
+- Keep stories small enough to pass through TDD evidence independently.
+- Sync stories before graph commands so prioritization uses current metadata.
+- Use `sprint next` or `graph triage` to select work instead of choosing only by recency.
+
+## 5. Long Agent Session
+
+Use when work will span many tool calls, handoffs, or context compaction.
+
+```bash
+speckit memory refresh
+speckit session start "Refactor report export flow"
+speckit session status --json
+speckit session checkpoint --note "red complete"
+speckit session checkpoint --note "green complete"
+speckit session compact
+speckit session resume <session-id>
+```
+
+Best practices:
+
+- Durable files are the source of truth, not chat history.
+- Write decisions to memory when they apply beyond the current story.
+- Compact before handing work to another agent or after noisy command output.
+- Use `DONE`, `DONE_WITH_CONCERNS`, `BLOCKED`, or `NEEDS_CONTEXT` in handoffs.
+- Never pass a full conversation as handoff context. Pass files, acceptance criteria, constraints, and current status.
+
+## 6. TDD Implementation
+
+Use for all code stories.
+
+```bash
+speckit ready .speckit/stories/<story>.md
+speckit run .speckit/stories/<story>.md
+npm test
+speckit session checkpoint --note "red evidence captured"
+npm test
+speckit session checkpoint --note "green evidence captured"
+speckit session checkpoint --note "refactor validated"
+```
+
+Best practices:
+
+- Record test intent before code changes.
+- Capture the red result before implementation.
+- Make the smallest change that turns the failing test green.
+- Refactor only while tests stay green.
+- Put command output summaries in the evidence file. Avoid pasting large logs unless they are necessary.
+
+## 7. Graph And Sprint Automation
+
+Use when multiple stories exist and the next task is not obvious.
+
+```bash
+speckit sync
+speckit sprint plan
+speckit sprint next --json
+speckit graph triage --json
+speckit graph plan --json
+speckit graph insights --json
+```
+
+Best practices:
+
+- Run `sync` before any graph command.
+- Keep graph commands robot-safe. Use Speckit wrappers instead of interactive graph commands.
+- Treat graph output as prioritization input, not automatic permission to implement.
+- Re-run `sprint plan` when story status or dependencies change.
+
+## 8. Review And Closure
+
+Use after implementation and tests pass.
+
+```bash
+speckit review
+speckit session compact
+speckit close .speckit/stories/<story>.md
+speckit sync
+speckit validate
+```
+
+Best practices:
+
+- Review acceptance coverage before style or preference issues.
+- Check TDD evidence, session freshness, docs impact, and graph sync.
+- Close only after the story has current evidence and a clean handoff.
+- Sync after closing so downstream graph and sprint views are current.
+
+## 9. CI And Enterprise Rollout
+
+Use when Speckit becomes a shared team standard.
+
+Recommended CI checks:
+
+```bash
+npm run build
+npm test
+npx @trieungoctam/speckit@latest doctor --deep --json
+npx @trieungoctam/speckit@latest validate --json
+```
+
+Best practices:
+
+- Fail CI when `validate` returns `needs-attention`.
+- Require `doctor --deep` before release branches are merged.
+- Keep generated prompt files reviewed like source code.
+- Add new workflow phases only through the central contract and tests.
+- Do not allow IDE-specific prompts to drift from the shared Speckit contract.
+
+## 10. Troubleshooting
+
+Use these checks when the workflow feels inconsistent.
+
+```bash
+speckit doctor --deep --json
+speckit validate --json
+speckit session status --json
+speckit sync
+speckit graph triage --json
+```
+
+Common fixes:
+
+- Missing skill file: run `speckit init --enterprise --ide <name> --force`.
+- Adapter prompt mismatch: update the adapter generator, rebuild, then init again.
+- Story is blocked: run `speckit context <story>` and `speckit sync`, then retry `speckit ready <story>`.
+- Graph command fails: check that `.beads/beads.jsonl` exists after `speckit sync`.
+- Session context is stale: run `speckit session checkpoint` and `speckit session compact`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trieungoctam/speckit",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Enterprise Agile + TDD workflow compiler for agentic IDEs.",
   "type": "module",
   "files": [