@trieungoctam/speckit 0.1.0 → 0.2.2

package/dist/commands/run.js

@@ -1,42 +1,37 @@
-import { access } from "node:fs/promises";
-import { join } from "node:path";
+import { resolveStory } from "../core/story.js";
+import { evaluateReadiness } from "../core/readiness.js";
 export async function runCommand(options) {
     const stdout = options.stdout ?? console;
-    const storyPath = await resolveStory(options.root, options.target);
-    if (!storyPath) {
+    const story = await resolveStory(options.root, options.target);
+    if (!story) {
         stdout.error(`Story not found: ${options.target}`);
         return 1;
     }
+    const readiness = await evaluateReadiness(options.root, options.target);
+    if (readiness.status !== "ready") {
+        stdout.error(`Story is not ready for implementation: ${story.path}`);
+        for (const check of readiness.checks.filter((item) => !item.ok)) {
+            stdout.error(`- ${check.name}: ${check.detail}`);
+        }
+        stdout.error(`Run \`speckit ready ${story.id}\` after preparing context and sync.`);
+        return 1;
+    }
     stdout.log(`# Speckit TDD Run
 
-Story: ${storyPath}
+Story: ${story.path}
+
+Status: ready-for-dev
 
-1. Read the story and acceptance criteria.
+1. Read \`.speckit/context/current.md\`, story, acceptance criteria, and subagent handoff.
 2. Identify the smallest executable test that should fail.
-3. Record red evidence in the matching \`.speckit/evidence/*tdd-evidence.md\` file.
+3. Record red evidence in the linked TDD evidence file.
 4. Implement the minimal behavior.
 5. Record green evidence.
 6. Refactor only after tests are green, then record validation.
+7. Continue until all acceptance criteria are satisfied or a stop condition is hit.
 
 Recommended handoff:
 \`speckit review\` before commit or PR.
 `);
     return 0;
 }
-async function resolveStory(root, target) {
-    const candidates = [
-        target,
-        `.speckit/stories/${target}`,
-        `.speckit/stories/${target}.md`,
-    ];
-    for (const candidate of candidates) {
-        try {
-            await access(join(root, candidate));
-            return candidate;
-        }
-        catch {
-            // Try the next candidate.
-        }
-    }
-    return undefined;
-}

package/dist/commands/start.d.ts

@@ -0,0 +1,6 @@
+export type StartOptions = {
+    root: string;
+    intent: string;
+    stdout?: Pick<typeof console, "log">;
+};
+export declare function startCommand(options: StartOptions): Promise<number>;

package/dist/commands/start.js

@@ -0,0 +1,47 @@
+import { markdown, writeManagedFiles } from "../core/managed-files.js";
+import { slugify, timestamp } from "../core/slug.js";
+export async function startCommand(options) {
+    const stdout = options.stdout ?? console;
+    const sessionId = `${timestamp()}-${slugify(options.intent)}`;
+    const handoffPath = `.speckit/sessions/${sessionId}/handoff.md`;
+    const contextPath = ".speckit/context/current.md";
+    await writeManagedFiles(options.root, [
+        {
+            path: handoffPath,
+            content: markdown(`# Spec Session: ${sessionId}
+
+## Idea
+${options.intent}
+
+## Current Phase
+shape
+
+## Linked Artifacts
+- Context: \`${contextPath}\`
+
+## Next Command
+\`speckit shape "${options.intent}"\`
+`),
+        },
+        {
+            path: contextPath,
+            content: markdown(`# Current Spec Context
+
+## Session
+${sessionId}
+
+## Idea
+${options.intent}
+
+## Active Artifact
+\`${handoffPath}\`
+
+## Next Command
+\`speckit shape "${options.intent}"\`
+`),
+        },
+    ], true);
+    stdout.log(sessionId);
+    stdout.log(handoffPath);
+    return 0;
+}

package/dist/commands/sync.js

@@ -1,6 +1,7 @@
 import { readdir, readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { markdown, writeManagedFiles } from "../core/managed-files.js";
+import { firstHeading, frontmatterValue } from "../core/story.js";
 export async function syncCommand(options) {
     const stdout = options.stdout ?? console;
     const storiesDir = join(options.root, ".speckit", "stories");
@@ -19,7 +20,7 @@ export async function syncCommand(options) {
             id: entry.replace(/\.md$/, ""),
             path: `.speckit/stories/${entry}`,
             title: firstHeading(content) ?? entry.replace(/\.md$/, ""),
-            status: content.includes("- [ ]") ? "open" : "ready-for-review",
+            status: frontmatterValue(content, "status") ?? (content.includes("- [ ]") ? "open" : "ready-for-review"),
         });
     }
     const jsonl = stories.map((story) => JSON.stringify(story)).join("\n");
@@ -45,10 +46,3 @@ bv --robot-next --format json
     stdout.log(`Synced ${stories.length} stories to .speckit/sync/beads-sync.jsonl`);
     return 0;
 }
-function firstHeading(content) {
-    return content
-        .split("\n")
-        .find((line) => line.startsWith("# "))
-        ?.replace(/^#\s+/, "")
-        .trim();
-}

package/dist/commands/triage.d.ts

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

package/dist/commands/triage.js

@@ -0,0 +1,33 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+export async function triageCommand(options) {
+    const stdout = options.stdout ?? console;
+    const stories = await readSyncedStories(options.root);
+    const open = stories.filter((story) => ["open", "ready-for-dev", "in-progress"].includes(story.status));
+    const ready = stories.filter((story) => story.status !== "open");
+    const report = {
+        source: ".speckit/sync/beads-sync.jsonl",
+        open: open.length,
+        ready: ready.length,
+        next: open[0] ?? null,
+    };
+    if (options.json) {
+        stdout.log(JSON.stringify(report, null, 2));
+        return 0;
+    }
+    stdout.log(`Spec triage: ${open.length} open, ${ready.length} ready`);
+    stdout.log(open[0] ? `Next: ${open[0].id} (${open[0].path})` : "Next: none");
+    return 0;
+}
+async function readSyncedStories(root) {
+    try {
+        const content = await readFile(join(root, ".speckit", "sync", "beads-sync.jsonl"), "utf8");
+        return content
+            .split("\n")
+            .filter(Boolean)
+            .map((line) => JSON.parse(line));
+    }
+    catch {
+        return [];
+    }
+}

package/dist/core/readiness.d.ts

@@ -0,0 +1,13 @@
+import { StoryResolution } from "./story.js";
+export type ReadinessCheck = {
+    name: string;
+    ok: boolean;
+    detail: string;
+};
+export type ReadinessReport = {
+    story?: Pick<StoryResolution, "id" | "path" | "title" | "status" | "evidencePath">;
+    checks: ReadinessCheck[];
+    status: "ready" | "blocked";
+};
+export declare function evaluateReadiness(root: string, target: string): Promise<ReadinessReport>;
+export declare function evidenceStatus(root: string, evidencePath: string | undefined): Promise<string | undefined>;

package/dist/core/readiness.js

@@ -0,0 +1,120 @@
+import { access, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { extractSection, frontmatterValue, resolveStory } from "./story.js";
+export async function evaluateReadiness(root, target) {
+    const story = await resolveStory(root, target);
+    if (!story) {
+        return {
+            checks: [{ name: "story", ok: false, detail: `Story not found: ${target}` }],
+            status: "blocked",
+        };
+    }
+    const evidencePath = story.evidencePath;
+    const checks = [
+        {
+            name: "story-status",
+            ok: story.status === "ready-for-dev",
+            detail: story.status ? `status=${story.status}` : "status missing",
+        },
+        {
+            name: "acceptance-criteria",
+            ok: hasActionableAcceptanceCriteria(story.content),
+            detail: "story has testable acceptance criteria",
+        },
+        {
+            name: "evidence-link",
+            ok: Boolean(evidencePath),
+            detail: evidencePath ?? "missing TDD evidence reference",
+        },
+        {
+            name: "evidence-file",
+            ok: evidencePath ? await fileExists(root, evidencePath) : false,
+            detail: evidencePath ?? "missing TDD evidence reference",
+        },
+        {
+            name: "context",
+            ok: await contextIsFreshForStory(root, story.path),
+            detail: ".speckit/context/current.md links this story and is fresh",
+        },
+        {
+            name: "graph-sync",
+            ok: await graphContainsStory(root, story.path),
+            detail: ".speckit/sync/beads-sync.jsonl contains this story",
+        },
+        {
+            name: "tool-policy",
+            ok: await fileExists(root, ".speckit/tool-policy.yaml"),
+            detail: ".speckit/tool-policy.yaml",
+        },
+        {
+            name: "safety-policy",
+            ok: await fileExists(root, ".speckit/rules/enterprise-safety.md"),
+            detail: ".speckit/rules/enterprise-safety.md",
+        },
+    ];
+    return {
+        story: {
+            id: story.id,
+            path: story.path,
+            title: story.title,
+            status: story.status,
+            evidencePath,
+        },
+        checks,
+        status: checks.every((check) => check.ok) ? "ready" : "blocked",
+    };
+}
+function hasActionableAcceptanceCriteria(content) {
+    const criteria = extractSection(content, "Acceptance Criteria");
+    if (!criteria)
+        return false;
+    return /Given .+|When .+|Then .+|\d+\./i.test(criteria) && !criteria.includes("...");
+}
+async function contextIsFreshForStory(root, storyPath) {
+    try {
+        const content = await readFile(join(root, ".speckit", "context", "current.md"), "utf8");
+        return content.includes("status: fresh") && content.includes(storyPath);
+    }
+    catch {
+        return false;
+    }
+}
+async function graphContainsStory(root, storyPath) {
+    try {
+        const content = await readFile(join(root, ".speckit", "sync", "beads-sync.jsonl"), "utf8");
+        return content
+            .split("\n")
+            .filter(Boolean)
+            .some((line) => {
+            try {
+                return JSON.parse(line).path === storyPath;
+            }
+            catch {
+                return false;
+            }
+        });
+    }
+    catch {
+        return false;
+    }
+}
+async function fileExists(root, path) {
+    try {
+        await access(join(root, path));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function evidenceStatus(root, evidencePath) {
+    if (!evidencePath)
+        return undefined;
+    try {
+        const content = await readFile(join(root, evidencePath), "utf8");
+        return frontmatterValue(content, "status");
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/core/scaffold.d.ts

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

package/dist/core/scaffold.js

@@ -27,7 +27,13 @@ adapters:
         { path: ".speckit/workflows/review.md", content: markdown(workflowReview) },
         {
             path: ".speckit/templates/story.md",
-            content: markdown(`# Story: {{title}}
+            content: markdown(`---
+status: draft
+evidence: .speckit/evidence/{{slug}}-tdd-evidence.md
+context: pending
+---
+
+# Story: {{title}}
 
 ## Intent
 {{intent}}
@@ -46,11 +52,23 @@ adapters:
 ## Notes
 - Risks:
 - Dependencies:
+
+## 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.
 `),
         },
         {
             path: ".speckit/templates/tdd-evidence.md",
-            content: markdown(`# TDD Evidence: {{story}}
+            content: markdown(`---
+status: missing
+story: {{story}}
+---
+
+# TDD Evidence: {{story}}
 
 ## Test Intent
 
@@ -69,3 +87,90 @@ adapters:
         },
     ];
 }
+export function enterpriseFiles() {
+    return [
+        {
+            path: ".speckit/flows/spec-flow.md",
+            content: markdown(`# Spec Flow
+
+## Order
+start -> shape -> plan -> context -> sync -> triage -> run -> review -> close
+
+## Traceability
+- A session links the original idea to every downstream artifact.
+- A story links acceptance criteria to TDD evidence.
+- Sync links stories to graph-ready JSONL.
+- Close links review output back to story and graph sync.
+`),
+        },
+        {
+            path: ".speckit/tool-policy.yaml",
+            content: text(`version: 1
+phases:
+  shape:
+    may_edit_code: false
+  plan:
+    may_edit_code: false
+  run:
+    may_edit_code: true
+    requires_tdd_evidence: true
+  review:
+    may_edit_code: false
+graph:
+  robot_only: true`),
+        },
+        {
+            path: ".speckit/prompts/spec-run.md",
+            content: markdown(`# Spec Run Prompt
+
+## Required Inputs
+
+- Current context: \`.speckit/context/current.md\`
+- Subagent handoff: \`.speckit/context/subagent-handoff.md\`
+- Story with acceptance criteria
+- Matching TDD evidence file
+- Tool policy: \`.speckit/tool-policy.yaml\`
+
+## Status Preconditions
+
+- Story status is \`ready-for-dev\`.
+- Context status is \`fresh\`.
+- \`speckit ready <story>\` returns ready.
+
+## Allowed Edits
+
+- Implementation files needed for the story.
+- Matching tests.
+- Linked TDD evidence file.
+- Story completion checkboxes and implementation notes.
+
+## Execution Contract
+
+Use the red-green-refactor loop.
+
+1. Read the current context before touching code.
+2. Confirm the story path, acceptance criteria, and evidence path.
+3. Write or run the smallest failing test first.
+4. Record red evidence before implementation.
+5. Implement the smallest change that satisfies the failing test.
+6. Record green evidence after tests pass.
+7. Refactor only while tests stay green, then record validation.
+8. Use graph commands only through robot-safe flags such as \`bv --robot-next --format json\`.
+9. Run \`speckit review\` before handoff.
+
+## Stop Conditions
+
+- Stop if acceptance criteria are missing.
+- Stop if the evidence file cannot be identified.
+- Stop if \`speckit ready <story>\` reports blocked.
+- Stop before destructive commands, production changes, or secret access.
+
+## Completion Signal
+
+- All acceptance criteria satisfied.
+- TDD evidence status can be advanced through red, green, and refactor.
+- Review handoff is ready.
+`),
+        },
+    ];
+}

package/dist/core/story.d.ts

@@ -0,0 +1,13 @@
+export type StoryResolution = {
+    path: string;
+    content: string;
+    id: string;
+    title: string;
+    status?: string;
+    evidencePath?: string;
+};
+export declare function resolveStory(root: string, target: string): Promise<StoryResolution | undefined>;
+export declare function frontmatterValue(content: string, key: string): string | undefined;
+export declare function extractEvidenceReference(content: string): string | undefined;
+export declare function extractSection(content: string, heading: string): string | undefined;
+export declare function firstHeading(content: string): string | undefined;

package/dist/core/story.js

@@ -0,0 +1,67 @@
+import { access, readFile } from "node:fs/promises";
+import { basename, join } from "node:path";
+export async function resolveStory(root, target) {
+    const candidates = [
+        target,
+        `.speckit/stories/${target}`,
+        `.speckit/stories/${target}.md`,
+    ];
+    for (const candidate of candidates) {
+        try {
+            const fullPath = join(root, candidate);
+            await access(fullPath);
+            const content = await readFile(fullPath, "utf8");
+            return {
+                path: candidate,
+                content,
+                id: basename(candidate).replace(/\.md$/, ""),
+                title: firstHeading(content) ?? basename(candidate).replace(/\.md$/, ""),
+                status: frontmatterValue(content, "status"),
+                evidencePath: frontmatterValue(content, "evidence") ?? extractEvidenceReference(content),
+            };
+        }
+        catch {
+            // Try the next candidate.
+        }
+    }
+    return undefined;
+}
+export function frontmatterValue(content, key) {
+    const lines = content.split("\n");
+    const start = lines.findIndex((line) => line.trim() === "---");
+    if (start === -1)
+        return undefined;
+    const end = lines.findIndex((line, index) => index > start && line.trim() === "---");
+    if (end === -1)
+        return undefined;
+    const prefix = `${key}:`;
+    const found = lines
+        .slice(start + 1, end)
+        .find((line) => line.trim().toLowerCase().startsWith(prefix.toLowerCase()));
+    return found?.slice(found.indexOf(":") + 1).trim().replace(/^["']|["']$/g, "");
+}
+export function extractEvidenceReference(content) {
+    const match = content.match(/`([^`]*tdd-evidence\.md)`/i);
+    return match?.[1];
+}
+export function extractSection(content, heading) {
+    const lines = content.split("\n");
+    const start = lines.findIndex((line) => line.trim().toLowerCase() === `## ${heading}`.toLowerCase());
+    if (start === -1)
+        return undefined;
+    const collected = [];
+    for (const line of lines.slice(start + 1)) {
+        if (line.startsWith("## "))
+            break;
+        if (line.trim())
+            collected.push(line);
+    }
+    return collected.length > 0 ? collected.join("\n") : undefined;
+}
+export function firstHeading(content) {
+    return content
+        .split("\n")
+        .find((line) => line.startsWith("# "))
+        ?.replace(/^#\s+/, "")
+        .trim();
+}

package/docs/development-roadmap.md

@@ -4,9 +4,9 @@
 
 Speckit MVP is implemented and pushed to `git@github.com:trieungoctam/speckit.git` on `main`.
 
-Current package target: `@trieungoctam/speckit@0.1.0`.
+Current package target: `@trieungoctam/speckit@0.2.2`.
 
-The CLI is npx-ready, generates Agile + TDD rules, creates workflow artifacts, supports five IDE adapters, wraps Beads Viewer safely, and has automated tests plus CI.
+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 tests plus CI.
 
 ## Milestones
 
@@ -14,17 +14,18 @@ The CLI is npx-ready, generates Agile + TDD rules, creates workflow artifacts, s
 | --- | --- | --- |
 | Product contract | Complete | Contract, workflow model, and command surface documented. |
 | CLI scaffold | Complete | `bin/speckit`, TypeScript build, command router, managed file writer. |
-| Workflow engine | MVP Complete | `shape`, `plan`, `quick`, `run`, and `review` generate usable artifacts. |
+| Workflow engine | Complete | `start`, `shape`, `plan`, `context`, `quick`, `sync`, `triage`, `ready`, `run`, `review`, and `close` generate linked artifacts. |
 | IDE adapters | Complete | Claude Code, Codex, Antigravity, OpenCode, Cursor. |
 | Beads integration | MVP Complete | `next` wraps BV robot mode; `sync` exports story metadata JSONL. |
-| Validation | Complete | Build and `node:test` suite pass locally. |
+| Enterprise harness | MVP Complete | `init --enterprise` creates flow, tool-policy, and prompt harness files; `doctor --deep` verifies them. |
+| 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
 
-- Publish `@trieungoctam/speckit` to npm.
+- Expand Speckit Enterprise Harness with richer profile and context-pack layers.
+- Add `review --deep` with blind, edge-case, and acceptance audit prompts.
+- Add graph commands: `graph-plan`, `insights`, and `drift`.
 - Add GitHub trusted publishing for npm releases.
-- Add richer config loading from `.speckit/config.yaml`.
-- Add optional direct `br`/`bd` import once command compatibility is pinned.
 - Add snapshot tests for full adapter file contents.

package/docs/product-contract.md

@@ -5,7 +5,7 @@ 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`, `shape`, `plan`, `quick`, `next`, `sync`, `run`, `review`.
+- The command surface: `init`, `doctor`, `start`, `shape`, `plan`, `context`, `quick`, `sync`, `triage`, `next`, `ready`, `run`, `review`, `close`.
 - 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.
@@ -13,15 +13,15 @@ Speckit owns the workflow contract for enterprise Agile + TDD development with a
 ## Speckit Delegates
 
 - Implementation to the selected IDE and agent runtime.
-- Product lifecycle inspiration to BMad-style phases, without copying BMad personas or branding.
-- Execution orchestration inspiration to ClaudeKit-style plan/cook/test/review flows.
+- Product lifecycle, story readiness, and quality gates to Speckit-native phases.
+- Execution orchestration to Speckit-native plan/run/test/review flows.
 - Task graph prioritization to beads and Beads Viewer robot commands.
 - Git, tests, CI, and deployment to project-local tooling.
 
 ## State Model
 
 ```text
-intake -> shaped -> planned -> sliced -> spec-ready -> tests-red -> running -> tests-green -> refactor -> review-ready -> closed
+intake -> session -> shaped -> planned -> context-ready -> synced -> triaged -> ready-for-dev -> tests-red -> running -> tests-green -> refactor -> review-ready -> closed
 ```
 
-Implementation starts only after a story is spec-ready. Review starts only after test evidence exists.
+Implementation starts only after `speckit ready <story>` passes. Review starts only after test evidence exists.