@trieungoctam/speckit 0.2.2 → 0.3.1

package/dist/commands/sprint.js

@@ -0,0 +1,54 @@
+import { markdown, text, writeManagedFiles } from "../core/managed-files.js";
+import { readSyncedStories, selectableStories } from "../core/synced-stories.js";
+export async function sprintCommand(options) {
+    const stdout = options.stdout ?? console;
+    const stories = await readSyncedStories(options.root);
+    switch (options.action) {
+        case "plan": {
+            const selected = selectableStories(stories);
+            await writeManagedFiles(options.root, [
+                {
+                    path: ".speckit/sprint/status.yaml",
+                    content: text(renderStatus(stories)),
+                },
+                {
+                    path: ".speckit/sprint/plan.md",
+                    content: markdown(renderPlan(selected)),
+                },
+            ], true);
+            stdout.log(`Planned sprint with ${selected.length} selectable stories`);
+            return 0;
+        }
+        case "next": {
+            const next = selectableStories(stories)[0] ?? null;
+            stdout.log(options.json ? JSON.stringify({ next }, null, 2) : renderNext(next));
+            return next ? 0 : 1;
+        }
+        default:
+            stdout.error("Usage: speckit sprint plan|next [--json]");
+            return 1;
+    }
+}
+function renderStatus(stories) {
+    const rows = stories.map((story) => `  ${story.id}: ${story.status}`);
+    return `version: 1\nsource: .speckit/sync/beads-sync.jsonl\ndevelopment_status:\n${rows.join("\n") || "  none: empty"}\n`;
+}
+function renderPlan(stories) {
+    const rows = stories.map((story) => `- [ ] ${story.id} (${story.status}) - \`${story.path}\``);
+    return `# Spec Sprint Plan
+
+## Goal
+Deliver the highest-priority ready stories while preserving TDD evidence and graph traceability.
+
+## Selected Stories
+${rows.join("\n") || "- No selectable stories. Run `speckit quick`, `speckit sync`, then retry."}
+
+## Automation
+- Run \`speckit graph triage --json\` before claiming work.
+- Run \`speckit context <story>\` and \`speckit ready <story>\` before implementation.
+- Run \`speckit session checkpoint\` at task boundaries.
+`;
+}
+function renderNext(story) {
+    return story ? `Next sprint story: ${story.id} (${story.path})` : "Next sprint story: none";
+}

package/dist/commands/start.js

@@ -1,9 +1,10 @@
 import { markdown, writeManagedFiles } from "../core/managed-files.js";
-import { slugify, timestamp } from "../core/slug.js";
+import { createSession } from "../core/session-manager.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 session = await createSession(options.root, options.intent);
+    const sessionId = session.id;
+    const handoffPath = `${session.dir}/handoff.md`;
     const contextPath = ".speckit/context/current.md";
     await writeManagedFiles(options.root, [
         {

package/dist/commands/sync.js

@@ -2,6 +2,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";
+import { writeBeadsMirror } from "../core/beads-mirror.js";
 export async function syncCommand(options) {
     const stdout = options.stdout ?? console;
     const storiesDir = join(options.root, ".speckit", "stories");
@@ -43,6 +44,8 @@ bv --robot-next --format json
 `),
         },
     ], true);
+    const beadsPath = await writeBeadsMirror(options.root, stories);
     stdout.log(`Synced ${stories.length} stories to .speckit/sync/beads-sync.jsonl`);
+    stdout.log(`Prepared Beads Viewer mirror at ${beadsPath}`);
     return 0;
 }

package/dist/commands/triage.js

@@ -1,9 +1,8 @@
-import { readFile } from "node:fs/promises";
-import { join } from "node:path";
+import { readSyncedStories, selectableStories } from "../core/synced-stories.js";
 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 open = selectableStories(stories);
     const ready = stories.filter((story) => story.status !== "open");
     const report = {
         source: ".speckit/sync/beads-sync.jsonl",
@@ -19,15 +18,3 @@ export async function triageCommand(options) {
     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/commands/validate.d.ts

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

package/dist/commands/validate.js

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

package/dist/core/agent-scaffold.d.ts

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

package/dist/core/agent-scaffold.js

@@ -0,0 +1,57 @@
+import { markdown } from "./managed-files.js";
+import { specSkillFiles } from "./skill-catalog.js";
+export function agentFiles() {
+    return [
+        {
+            path: ".speckit/agents/super-agent.md",
+            content: markdown(`# Spec Super Agent
+
+## Mission
+
+Act as the controller for Speckit enterprise work. Do not be the only worker when context isolation is useful; route work through focused skills and subagent handoffs.
+
+## Load Order
+
+1. \`.speckit/memory/project-context.md\`
+2. \`.speckit/sessions/active.md\` and the linked session summary
+3. \`.speckit/skills/catalog.md\`
+4. \`.speckit/context/current.md\`
+5. \`.speckit/context/subagent-handoff.md\`
+
+## Routing Rules
+
+- Use planning skills before implementation.
+- Select the smallest matching Speckit skill for the current phase.
+- Route by the story state first, then by the requested action.
+- Use TDD execution skills only after \`speckit ready <story>\` passes.
+- Use graph skills before choosing or reordering work.
+- Use session skills at every task boundary.
+- Use review skills before closure.
+
+## Delegation Contract
+
+Every handoff must include:
+
+- Work context path.
+- Reports path.
+- Plans path.
+- Files to read.
+- Files to modify.
+- Acceptance criteria.
+- Constraints and stop conditions.
+
+Subagents must finish with one status: \`DONE\`, \`DONE_WITH_CONCERNS\`, \`BLOCKED\`, or \`NEEDS_CONTEXT\`.
+
+## Long Session Contract
+
+- Keep durable facts in files, not in chat.
+- Checkpoint after red, green, refactor, and review.
+- Compact before handoff, after noisy tool output, or before switching stories.
+- Prefer focused subagent handoffs over passing full conversation history.
+- Hydrate runtime tasks from unchecked plan/story checkboxes at session start.
+- Sync completed runtime tasks back to durable plan/story files before close.
+`),
+        },
+        ...specSkillFiles(),
+    ];
+}

package/dist/core/beads-mirror.d.ts

@@ -0,0 +1,3 @@
+import { SyncedStory } from "./synced-stories.js";
+export declare function writeBeadsMirror(root: string, stories: SyncedStory[]): Promise<string>;
+export declare function prepareBeadsMirror(root: string): Promise<string>;

package/dist/core/beads-mirror.js

@@ -0,0 +1,46 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { readSyncedStories } from "./synced-stories.js";
+export async function writeBeadsMirror(root, stories) {
+    const path = ".beads/beads.jsonl";
+    const now = new Date().toISOString();
+    const jsonl = stories
+        .map((story) => JSON.stringify(toBeadIssue(story, now)))
+        .join("\n");
+    const target = join(root, path);
+    await mkdir(dirname(target), { recursive: true });
+    await writeFile(target, `${jsonl}${jsonl ? "\n" : ""}`, "utf8");
+    return path;
+}
+export async function prepareBeadsMirror(root) {
+    return writeBeadsMirror(root, await readSyncedStories(root));
+}
+function toBeadIssue(story, timestamp) {
+    return {
+        id: story.id,
+        title: story.title,
+        description: `Speckit story: ${story.path}`,
+        status: mapStatus(story.status),
+        priority: 2,
+        issue_type: "task",
+        labels: ["speckit", "story"],
+        created_at: timestamp,
+        updated_at: timestamp,
+    };
+}
+function mapStatus(status) {
+    switch (status) {
+        case "in-progress":
+            return "in_progress";
+        case "ready-for-review":
+        case "review-ready":
+            return "review";
+        case "closed":
+        case "done":
+            return "closed";
+        case "draft":
+            return "draft";
+        default:
+            return "open";
+    }
+}

package/dist/core/memory.d.ts

@@ -0,0 +1 @@
+export declare function refreshMemory(root: string): Promise<string[]>;

package/dist/core/memory.js

@@ -0,0 +1,47 @@
+import { markdown, writeManagedFiles } from "./managed-files.js";
+export async function refreshMemory(root) {
+    const files = [
+        {
+            path: ".speckit/memory/project-context.md",
+            content: markdown(`# Spec Project Context
+
+## Technology Stack & Versions
+- Update this section with project-specific runtime, framework, test, and deployment facts.
+
+## Critical Implementation Rules
+- Prefer existing project patterns over generic framework defaults.
+- Keep implementation scoped to the active story and acceptance criteria.
+- Record red-green-refactor evidence for code stories.
+- Use robot-safe graph commands only.
+
+## Context Loading Rules
+- Load this file before implementation, review, sprint planning, and session resume.
+- Treat this file as durable guidance, not as proof that the current environment still matches it.
+`),
+        },
+        {
+            path: ".speckit/memory/decisions.md",
+            content: markdown(`# Spec Decisions
+
+## Active Decisions
+- Record durable architecture and workflow decisions here.
+
+## Superseded Decisions
+- Move stale decisions here with the replacement decision and date.
+`),
+        },
+        {
+            path: ".speckit/memory/lessons.md",
+            content: markdown(`# Spec Lessons
+
+## Repeated Mistakes To Avoid
+- Add a lesson when an agent repeats a mistake or review catches a missed project rule.
+
+## Useful Verification Commands
+- Add commands that reliably validate this project.
+`),
+        },
+    ];
+    const results = await writeManagedFiles(root, files, false);
+    return results.map((result) => result.path);
+}

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,7 @@
 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 [
         {
@@ -13,6 +15,14 @@ tdd:
 task_graph:
   provider: beads
   bv_robot_only: true
+memory:
+  project_context: .speckit/memory/project-context.md
+  session_dir: .speckit/sessions
+skills:
+  catalog: .speckit/skills/catalog.md
+  super_agent: .speckit/agents/super-agent.md
+sprint:
+  status: .speckit/sprint/status.yaml
 adapters:
   enabled: []`),
         },
@@ -22,68 +32,17 @@ 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) },
         {
             path: ".speckit/templates/story.md",
-            content: markdown(`---
-status: draft
-evidence: .speckit/evidence/{{slug}}-tdd-evidence.md
-context: pending
----
-
-# Story: {{title}}
-
-## Intent
-{{intent}}
-
-## Acceptance Criteria
-- Given ...
-- When ...
-- Then ...
-
-## TDD Checklist
-- [ ] Test targets identified
-- [ ] Red evidence recorded
-- [ ] Green evidence recorded
-- [ ] Refactor validation recorded
-
-## 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.
-`),
+            content: markdown(storyTemplate),
         },
         {
             path: ".speckit/templates/tdd-evidence.md",
-            content: markdown(`---
-status: missing
-story: {{story}}
----
-
-# TDD Evidence: {{story}}
-
-## Test Intent
-
-## Red
-- Command:
-- Result:
-
-## Green
-- Command:
-- Result:
-
-## Refactor
-- Command:
-- Result:
-`),
+            content: markdown(tddEvidenceTemplate),
         },
     ];
 }
@@ -94,12 +53,14 @@ export function enterpriseFiles() {
             content: markdown(`# Spec Flow
 
 ## Order
-start -> shape -> plan -> context -> sync -> triage -> run -> review -> close
+start -> memory -> sprint -> context -> sync -> triage -> ready -> run -> checkpoint -> review -> close
 
 ## Traceability
 - A session links the original idea to every downstream artifact.
+- Project memory links durable rules to every new session.
 - A story links acceptance criteria to TDD evidence.
 - Sync links stories to graph-ready JSONL.
+- Session checkpoints preserve file changes, decisions, and next steps across compaction.
 - Close links review output back to story and graph sync.
 `),
         },
@@ -127,6 +88,11 @@ graph:
 
 - Current context: \`.speckit/context/current.md\`
 - Subagent handoff: \`.speckit/context/subagent-handoff.md\`
+- Project memory: \`.speckit/memory/project-context.md\`
+- Active session summary: \`.speckit/sessions/active.md\` and the linked \`summary.md\`
+- Active artifact log: linked \`artifact-log.md\`
+- Super agent router: \`.speckit/agents/super-agent.md\`
+- Skill catalog: \`.speckit/skills/catalog.md\`
 - Story with acceptance criteria
 - Matching TDD evidence file
 - Tool policy: \`.speckit/tool-policy.yaml\`
@@ -136,6 +102,7 @@ graph:
 - Story status is \`ready-for-dev\`.
 - Context status is \`fresh\`.
 - \`speckit ready <story>\` returns ready.
+- \`speckit session status\` identifies the active session.
 
 ## Allowed Edits
 
@@ -149,26 +116,31 @@ graph:
 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.
+2. Read the super agent router and select the smallest matching Speckit skill.
+3. Confirm the story path, acceptance criteria, and evidence path.
+4. Write or run the smallest failing test first.
+5. Record red evidence before implementation.
+6. Implement the smallest change that satisfies the failing test.
+7. Record green evidence after tests pass.
+8. Refactor only while tests stay green, then record validation.
+9. Use graph commands only through robot-safe flags such as \`bv --robot-next --format json\`.
+10. Run \`speckit session checkpoint --note "<phase complete>"\` after red, green, refactor, and review boundaries.
+11. Run \`speckit session compact\` before context gets noisy or before handing off to another agent.
+12. 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 if active session state cannot be written.
 - 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.
+- Session checkpoint and compact summary are current.
 - Review handoff is ready.
 `),
         },

package/dist/core/session-manager.d.ts

@@ -0,0 +1,15 @@
+export type SessionCheckpointOptions = {
+    root: string;
+    note?: string;
+    story?: string;
+};
+export type SessionRef = {
+    id: string;
+    dir: string;
+};
+export declare function ensureSession(root: string, intent?: string): Promise<SessionRef>;
+export declare function createSession(root: string, intent?: string): Promise<SessionRef>;
+export declare function checkpointSession(options: SessionCheckpointOptions): Promise<SessionRef>;
+export declare function compactSession(root: string): Promise<SessionRef>;
+export declare function resumeSession(root: string, id?: string): Promise<SessionRef | undefined>;
+export declare function sessionStatus(root: string): Promise<Record<string, string>>;