@trieungoctam/speckit 0.3.0 → 0.3.3

package/dist/core/templates.js

@@ -2,6 +2,8 @@ export const storyTemplate = `---
 status: draft
 evidence: .speckit/evidence/{{slug}}-tdd-evidence.md
 context: pending
+story_key: {{slug}}
+ac_count: 0
 ---
 
 # Story: {{title}}
@@ -10,9 +12,28 @@ context: pending
 {{intent}}
 
 ## Acceptance Criteria
-- Given ...
-- When ...
-- Then ...
+- AC1: Given ...
+  When ...
+  Then ...
+
+## Implementation Scope
+- In scope:
+- Out of scope:
+- Files likely to read:
+- Files likely to modify:
+
+## Dev Notes
+- Existing patterns to reuse:
+- Architecture constraints:
+- Edge cases:
+- Previous-story learnings:
+
+## Tasks / Subtasks
+- [ ] Map acceptance criteria to tests.
+- [ ] RED: create or identify failing test.
+- [ ] GREEN: implement minimum passing change.
+- [ ] REFACTOR: improve design while tests stay green.
+- [ ] Update evidence, file list, and change log.
 
 ## TDD Checklist
 - [ ] Test targets identified
@@ -24,31 +45,56 @@ context: pending
 - Risks:
 - Dependencies:
 
+## Dev Agent Record
+### Test Intent
+
+### Debug Log
+
+### Completion Notes
+
+### File List
+
+## Change Log
+- {{date}}: Story drafted.
+
 ## Spec Anti-Mistake Checklist
 - Reuse existing project patterns before adding new files.
 - Verify file locations before editing.
 - Do not introduce new libraries without explicit need.
 - Preserve existing behavior unless an acceptance criterion requires change.
 - Capture previous-story learnings if this continues prior work.
+- Do not mark any task complete without test or validation evidence.
 `;
 export const tddEvidenceTemplate = `---
 status: missing
 story: {{story}}
+phase: not-started
 ---
 
 # TDD Evidence: {{story}}
 
 ## Test Intent
+- Acceptance criteria covered:
+- Test files:
+- Command:
 
 ## Red
 - Command:
 - Result:
+- Failing reason:
 
 ## Green
 - Command:
 - Result:
+- Passing evidence:
 
 ## Refactor
 - Command:
 - Result:
+- Regression evidence:
+
+## Review Evidence
+- Reviewer:
+- Outcome:
+- Follow-ups:
 `;

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 ["Dev Agent Record", "implementation notes"], readonly ["File List", "files changed"], readonly ["Change Log", "changelog"], readonly ["spec compliance", "AC coverage"], readonly ["edge-case", "edge case"]];
+    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,43 @@
+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"],
+        ["Dev Agent Record", "implementation notes"],
+        ["File List", "files changed"],
+        ["Change Log", "changelog"],
+        ["spec compliance", "AC coverage"],
+        ["edge-case", "edge case"],
+    ],
+    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.3`.
 
 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,13 +21,16 @@ 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. |
+| Prompt architecture | Complete | Generated prompts now enforce artifact contracts, hard gates, common mistake prevention, TDD evidence, and review layers across adapters. |
+| 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. |
 
 ## Next Roadmap
 
-- Add `review --deep` with blind, edge-case, and acceptance audit prompts.
+- Add `review --deep` with multi-layer acceptance, edge-case, and production-readiness prompts.
 - Add graph drift and history correlation commands.
 - Add GitHub trusted publishing for npm releases.
 - Add snapshot tests for full adapter file contents.

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,44 @@
 # Project Changelog
 
+## 0.3.3 - 2026-05-11
+
+### Added
+
+- Added `docs/prompt-architecture.md` to define Speckit prompt layers, required sections, implementation contract, review contract, long-session contract, and adapter parity policy.
+
+### Changed
+
+- Strengthened generated story and TDD evidence templates with AC IDs, implementation scope, Dev Notes, Dev Agent Record, File List, Change Log, and review evidence.
+- Strengthened generated skill files with inputs, outputs, common mistakes, hard gates, validation guidance, and durable artifact requirements.
+- Strengthened the super-agent, enterprise run prompt, and IDE adapter prompts with workflow state, just-in-time context loading, spec compliance, edge-case review, and production readiness expectations.
+
+### Quality
+
+- Expanded workflow contract terms so `speckit validate` checks Dev Agent Record, File List, Change Log, spec compliance, and edge-case prompt coverage across installed adapters.
+
+## 0.3.2 - 2026-05-11
+
+### Fixed
+
+- Fixed OpenCode, Cursor, and Claude Code JSON generation so schema-strict config files no longer include the internal `x-speckit-managed` marker.
+- Fixed generated YAML-frontmatter files so IDE agents, Cursor rules, stories, evidence, and current context start with `---` and keep the Speckit marker after frontmatter.
+- Preserved idempotent `speckit init` behavior for strict JSON files by matching generated JSON fingerprints and legacy marker-based files.
+
+### Quality
+
+- Added regression tests for strict JSON compatibility, frontmatter placement, legacy config upgrades, and adapter output quality.
+- `npm test` passes with 42 tests.
+
+## 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 +50,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 +73,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