@trieungoctam/speckit 0.3.5 → 0.4.0

package/dist/commands/validate.js

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

package/dist/core/colors.d.ts

@@ -0,0 +1,11 @@
+type ColorOutput = {
+    isTTY?: boolean;
+};
+type ColorName = "blue" | "cyan" | "dim" | "green" | "red" | "yellow" | "bold";
+export type Colors = Record<ColorName, (text: string) => string> & {
+    enabled: boolean;
+    status(ok: boolean, okText?: string, failText?: string): string;
+};
+export declare function createColors(output?: ColorOutput): Colors;
+export declare function colorsEnabled(output?: ColorOutput): boolean;
+export {};

package/dist/core/colors.js

@@ -0,0 +1,40 @@
+const ansi = {
+    blue: [34, 39],
+    cyan: [36, 39],
+    dim: [2, 22],
+    green: [32, 39],
+    red: [31, 39],
+    yellow: [33, 39],
+    bold: [1, 22],
+};
+export function createColors(output) {
+    const enabled = colorsEnabled(output);
+    const style = (name) => (text) => {
+        if (!enabled)
+            return text;
+        const [open, close] = ansi[name];
+        return `\u001B[${open}m${text}\u001B[${close}m`;
+    };
+    return {
+        enabled,
+        blue: style("blue"),
+        cyan: style("cyan"),
+        dim: style("dim"),
+        green: style("green"),
+        red: style("red"),
+        yellow: style("yellow"),
+        bold: style("bold"),
+        status(ok, okText = "ok", failText = "missing") {
+            return ok ? this.green(okText) : this.red(failText);
+        },
+    };
+}
+export function colorsEnabled(output) {
+    if (process.env.NO_COLOR || process.env.SPECKIT_COLOR === "0")
+        return false;
+    if (process.env.FORCE_COLOR === "0")
+        return false;
+    if (process.env.FORCE_COLOR || process.env.SPECKIT_COLOR === "1")
+        return true;
+    return output?.isTTY ?? process.stdout.isTTY ?? false;
+}

package/dist/core/scaffold.js

@@ -2,6 +2,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";
+import { teamFiles } from "./team-scaffold.js";
 export function coreFiles() {
     return [
         {
@@ -48,6 +49,7 @@ adapters:
 }
 export function enterpriseFiles() {
     return [
+        ...teamFiles(),
         {
             path: ".speckit/flows/spec-flow.md",
             content: markdown(`# Spec Flow

package/dist/core/spec-score.d.ts

@@ -0,0 +1,16 @@
+export type ScoreCategory = {
+    name: string;
+    score: number;
+    passed: number;
+    total: number;
+    detail: string;
+};
+export type SpecScoreReport = {
+    score: number;
+    target?: string;
+    status: "excellent" | "healthy" | "needs-attention" | "blocked";
+    categories: ScoreCategory[];
+    blockers: string[];
+    recommendations: string[];
+};
+export declare function calculateSpecScore(root: string, target?: string): Promise<SpecScoreReport>;

package/dist/core/spec-score.js

@@ -0,0 +1,112 @@
+import { access, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { buildTeamReport } from "./team-report.js";
+import { validateWorkflowContract } from "./workflow-validator.js";
+export async function calculateSpecScore(root, target) {
+    const categories = target
+        ? await storyCategories(root, target)
+        : await projectCategories(root);
+    const score = Math.round(categories.reduce((sum, item) => sum + item.score, 0) / categories.length);
+    const blockers = categories
+        .filter((item) => item.score < 70)
+        .map((item) => `${item.name}: ${item.detail}`);
+    return {
+        score,
+        target,
+        status: statusFor(score, blockers.length),
+        categories,
+        blockers,
+        recommendations: recommendationsFor(categories, Boolean(target)),
+    };
+}
+async function projectCategories(root) {
+    const contract = await validateWorkflowContract(root);
+    return [
+        ratio("Workflow Contract", contract.filter((check) => check.ok).length, contract.length, "Core prompts, skills, adapters, and permissions"),
+        await fileScore(root, "Team Operating Model", [
+            ".speckit/team/roles.md",
+            ".speckit/team/artifact-ownership.md",
+            ".speckit/team/working-agreement.md",
+            ".speckit/team/review-gates.md",
+            ".speckit/team/handoff-protocol.md",
+        ]),
+        await fileScore(root, "Context And Session", [
+            ".speckit/memory/project-context.md",
+            ".speckit/sessions/active.md",
+            ".speckit/context/current.md",
+            ".speckit/context/subagent-handoff.md",
+        ]),
+        await fileScore(root, "Graph Sync", [
+            ".speckit/sync/beads-sync.jsonl",
+            ".beads/beads.jsonl",
+        ]),
+    ];
+}
+async function storyCategories(root, target) {
+    const team = await buildTeamReport(root, target);
+    if (!team.story) {
+        return [ratio("Story", 0, 1, team.blockers[0] ?? "Story not found")];
+    }
+    const allRoleChecks = team.roles.flatMap((role) => role.checks);
+    const qa = team.roles.find((role) => role.role === "QA/Test");
+    const developer = team.roles.find((role) => role.role === "Developer");
+    const reviewer = team.roles.find((role) => role.role === "Reviewer/Lead");
+    return [
+        ratio("Team Readiness", allRoleChecks.filter((check) => check.ok).length, allRoleChecks.length, "Role-owned story artifacts"),
+        ratio("Developer Trace", developer?.checks.filter((check) => check.ok).length ?? 0, developer?.checks.length ?? 1, "Dev Agent Record, File List, Change Log"),
+        ratio("TDD Evidence", qa?.checks.filter((check) => check.ok).length ?? 0, qa?.checks.length ?? 1, "Red, green, and refactor evidence"),
+        ratio("Review Gate", reviewer?.checks.filter((check) => check.ok).length ?? 0, reviewer?.checks.length ?? 1, "Review evidence and follow-ups"),
+    ];
+}
+async function fileScore(root, name, paths) {
+    const checks = await Promise.all(paths.map((path) => exists(root, path)));
+    const passed = checks.filter(Boolean).length;
+    return ratio(name, passed, paths.length, `${passed}/${paths.length} files present`);
+}
+function ratio(name, passed, total, detail) {
+    const denominator = Math.max(total, 1);
+    return {
+        name,
+        score: Math.round((passed / denominator) * 100),
+        passed,
+        total,
+        detail,
+    };
+}
+function statusFor(score, blockers) {
+    if (score >= 90 && blockers === 0)
+        return "excellent";
+    if (score >= 75)
+        return "healthy";
+    if (score >= 50)
+        return "needs-attention";
+    return "blocked";
+}
+function recommendationsFor(categories, storyMode) {
+    const weak = categories.filter((item) => item.score < 100);
+    if (weak.length === 0)
+        return ["Workflow is fully aligned."];
+    return weak.map((item) => {
+        if (storyMode && item.name === "TDD Evidence")
+            return "Complete red, green, and refactor evidence before review.";
+        if (storyMode && item.name === "Developer Trace")
+            return "Update Dev Agent Record, File List, and Change Log.";
+        if (storyMode && item.name === "Review Gate")
+            return "Record review outcome and follow-ups.";
+        if (item.name === "Context And Session")
+            return "Run memory refresh, session start, context, and compact before long work.";
+        if (item.name === "Graph Sync")
+            return "Run speckit sync and speckit graph setup.";
+        return `Fix ${item.name}.`;
+    });
+}
+async function exists(root, path) {
+    try {
+        await access(join(root, path));
+        const content = await readFile(join(root, path), "utf8");
+        return content.trim().length > 0;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/core/team-report.d.ts

@@ -0,0 +1,19 @@
+import { StoryResolution } from "./story.js";
+export type TeamCheck = {
+    name: string;
+    ok: boolean;
+    detail: string;
+};
+export type TeamRoleReport = {
+    role: string;
+    status: "ok" | "blocked" | "needs-attention" | "waiting";
+    checks: TeamCheck[];
+};
+export type TeamReport = {
+    status: "ok" | "blocked";
+    story?: Pick<StoryResolution, "id" | "path" | "title" | "status" | "evidencePath">;
+    roles: TeamRoleReport[];
+    blockers: string[];
+    warnings: string[];
+};
+export declare function buildTeamReport(root: string, target: string): Promise<TeamReport>;

package/dist/core/team-report.js

@@ -0,0 +1,149 @@
+import { access, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { extractSection, resolveStory } from "./story.js";
+export async function buildTeamReport(root, target) {
+    const story = await resolveStory(root, target);
+    if (!story) {
+        return {
+            status: "blocked",
+            roles: [],
+            blockers: [`Story not found: ${target}`],
+            warnings: [],
+        };
+    }
+    const evidence = await readEvidence(root, story.evidencePath);
+    const roles = [
+        productOwner(story.content),
+        analyst(story.content),
+        architect(story.content),
+        developer(story.content),
+        await qa(story.evidencePath, evidence),
+        reviewer(evidence),
+    ];
+    const blockers = roles.flatMap((role) => role.checks.filter((check) => !check.ok).map((check) => `${role.role}: ${check.name} - ${check.detail}`));
+    return {
+        status: blockers.length ? "blocked" : "ok",
+        story: {
+            id: story.id,
+            path: story.path,
+            title: story.title,
+            status: story.status,
+            evidencePath: story.evidencePath,
+        },
+        roles,
+        blockers,
+        warnings: story.status === "ready-for-dev" ? [] : [`Story status is ${story.status ?? "missing"}`],
+    };
+}
+function productOwner(content) {
+    return role("Product Owner", [
+        check("business-goal", sectionHasDetail(content, "Business Goal") || sectionHasDetail(content, "Intent"), "Business goal or intent is filled"),
+        check("priority", sectionHasValue(content, "Business Goal", "Priority"), "Priority is recorded"),
+    ]);
+}
+function analyst(content) {
+    return role("Analyst", [
+        check("acceptance-criteria", hasActionableAcceptanceCriteria(content), "Acceptance criteria are testable"),
+        check("edge-cases", sectionHasDetail(content, "Edge Cases") || sectionHasValue(content, "Dev Notes", "Edge cases"), "Edge cases are recorded"),
+    ]);
+}
+function architect(content) {
+    return role("Architect", [
+        check("implementation-scope", sectionHasDetail(content, "Implementation Scope"), "Implementation scope is recorded"),
+        check("risk-notes", sectionHasDetail(content, "Architecture Notes") || sectionHasValue(content, "Notes", "Risks"), "Constraints or risks are recorded"),
+    ]);
+}
+function developer(content) {
+    return role("Developer", [
+        check("dev-agent-record", sectionHasDetail(content, "Dev Agent Record"), "Dev Agent Record exists"),
+        check("file-list", subsectionHasDetail(content, "File List"), "File List has at least one entry"),
+        check("change-log", sectionHasDetail(content, "Change Log"), "Change Log is updated"),
+    ]);
+}
+async function qa(evidencePath, evidence) {
+    return role("QA/Test", [
+        check("evidence-link", Boolean(evidencePath), evidencePath ?? "Missing linked evidence file"),
+        check("evidence-file", Boolean(evidence), evidencePath ?? "Missing linked evidence file"),
+        check("red-evidence", evidence ? sectionHasDetail(evidence, "Red") : false, "Red evidence is recorded"),
+        check("green-evidence", evidence ? sectionHasDetail(evidence, "Green") : false, "Green evidence is recorded"),
+        check("refactor-evidence", evidence ? sectionHasDetail(evidence, "Refactor") : false, "Refactor validation is recorded"),
+    ]);
+}
+function reviewer(evidence) {
+    const checks = [
+        check("review-evidence", evidence ? sectionHasDetail(evidence, "Review Evidence") : false, "Review outcome is recorded"),
+    ];
+    const report = role("Reviewer/Lead", checks);
+    return report.status === "blocked" ? { ...report, status: "waiting" } : report;
+}
+function role(roleName, checks) {
+    return {
+        role: roleName,
+        status: checks.every((item) => item.ok) ? "ok" : "blocked",
+        checks,
+    };
+}
+function check(name, ok, detail) {
+    return { name, ok, detail };
+}
+function hasActionableAcceptanceCriteria(content) {
+    const criteria = extractSection(content, "Acceptance Criteria");
+    if (!criteria)
+        return false;
+    return /Given .+|When .+|Then .+|AC\d+:/i.test(criteria) && !criteria.includes("...");
+}
+function sectionHasValue(content, heading, label) {
+    const section = extractSection(content, heading);
+    if (!section)
+        return false;
+    const pattern = new RegExp(`${escapeRegExp(label)}:\\s*\\S+`, "i");
+    return pattern.test(section);
+}
+function sectionHasDetail(content, heading) {
+    const section = extractSection(content, heading);
+    if (!section)
+        return false;
+    return hasDetail(section);
+}
+function subsectionHasDetail(content, heading) {
+    const lines = content.split("\n");
+    const start = lines.findIndex((line) => /^#{2,3}\s+/.test(line) && line.replace(/^#{2,3}\s+/, "").trim().toLowerCase() === heading.toLowerCase());
+    if (start === -1)
+        return false;
+    const collected = [];
+    for (const line of lines.slice(start + 1)) {
+        if (/^#{2,3}\s+/.test(line))
+            break;
+        collected.push(line);
+    }
+    return hasDetail(collected.join("\n"));
+}
+function hasDetail(section) {
+    return section
+        .split("\n")
+        .map((line) => line.replace(/^[-*\s]+/, "").trim())
+        .filter((line) => line && !line.startsWith("###"))
+        .some((line) => {
+        if (line.includes("..."))
+            return false;
+        if (/^[A-Za-z -]+:\s*$/.test(line))
+            return false;
+        if (/^(Command|Result|Reviewer|Outcome|Follow-ups):\s*$/i.test(line))
+            return false;
+        return true;
+    });
+}
+async function readEvidence(root, evidencePath) {
+    if (!evidencePath)
+        return undefined;
+    try {
+        await access(join(root, evidencePath));
+        return await readFile(join(root, evidencePath), "utf8");
+    }
+    catch {
+        return undefined;
+    }
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

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

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

package/dist/core/team-scaffold.js

@@ -0,0 +1,92 @@
+import { markdown } from "./managed-files.js";
+export function teamFiles() {
+    return [
+        {
+            path: ".speckit/team/roles.md",
+            content: markdown(`# Spec Team Roles
+
+## Purpose
+
+Speckit maps team collaboration to owned artifacts. Roles do not imply separate people; one person can hold multiple roles, but every story must show which artifact is ready and which role is blocked.
+
+## Roles
+
+| Role | Owns | Exit Signal |
+| --- | --- | --- |
+| Product Owner | business goal, priority, scope intent | story has clear business value |
+| Analyst | acceptance criteria, edge cases, assumptions | story is testable |
+| Architect | implementation scope, constraints, risks | dev can start without guessing |
+| Developer | Dev Agent Record, File List, Change Log | implementation evidence is traceable |
+| QA/Test | red, green, refactor evidence | behavior is validated |
+| Reviewer/Lead | review evidence, approval, follow-ups | story can close |
+`),
+        },
+        {
+            path: ".speckit/team/artifact-ownership.md",
+            content: markdown(`# Spec Artifact Ownership
+
+## Story Artifacts
+
+- Product Owner owns \`Business Goal\`, \`Priority\`, and high-level intent.
+- Analyst owns \`Acceptance Criteria\`, \`Edge Cases\`, and assumptions.
+- Architect owns \`Implementation Scope\`, \`Architecture Notes\`, and risks.
+- Developer owns \`Dev Agent Record\`, \`File List\`, and \`Change Log\`.
+- QA/Test owns the linked TDD evidence file.
+- Reviewer/Lead owns review outcome and closure readiness.
+
+## Rule
+
+Do not move a story to the next gate by chat memory alone. Update the durable artifact first, then run \`speckit team status <story>\` or \`speckit team audit <story>\`.
+`),
+        },
+        {
+            path: ".speckit/team/working-agreement.md",
+            content: markdown(`# Spec Working Agreement
+
+## Agreements
+
+- One story is the unit of planning, implementation, review, and closure.
+- Every implementation story must have a linked TDD evidence file.
+- Agents and humans hand off through files, not conversation history.
+- Graph commands stay robot-safe through Speckit wrappers.
+- Review blocks closure when acceptance criteria, evidence, or file traceability are missing.
+`),
+        },
+        {
+            path: ".speckit/team/review-gates.md",
+            content: markdown(`# Spec Review Gates
+
+## Gates
+
+| Gate | Required Checks |
+| --- | --- |
+| shape | business goal, priority |
+| ready | acceptance criteria, scope, context, graph sync |
+| dev | Dev Agent Record, File List, Change Log |
+| qa | red, green, refactor evidence |
+| review | review outcome, follow-ups, unresolved risk |
+| close | sync, compact summary, docs impact |
+
+Run \`speckit team audit <story>\` before review and close.
+`),
+        },
+        {
+            path: ".speckit/team/handoff-protocol.md",
+            content: markdown(`# Spec Handoff Protocol
+
+## Handoff Contract
+
+Each handoff must include:
+
+- Story path and current status.
+- From role and to role.
+- Current blockers and warnings.
+- Files changed or expected files to inspect.
+- Test evidence state.
+- Next role checklist.
+
+Use \`speckit team handoff <story> --from <role> --to <role>\` to generate a durable handoff.
+`),
+        },
+    ];
+}

package/dist/core/templates.d.ts

@@ -1,2 +1,2 @@
-export declare const storyTemplate = "---\nstatus: draft\nevidence: .speckit/evidence/{{slug}}-tdd-evidence.md\ncontext: pending\nstory_key: {{slug}}\nac_count: 0\n---\n\n# Story: {{title}}\n\n## Intent\n{{intent}}\n\n## Acceptance Criteria\n- AC1: Given ...\n  When ...\n  Then ...\n\n## Implementation Scope\n- In scope:\n- Out of scope:\n- Files likely to read:\n- Files likely to modify:\n\n## Dev Notes\n- Existing patterns to reuse:\n- Architecture constraints:\n- Edge cases:\n- Previous-story learnings:\n\n## Tasks / Subtasks\n- [ ] Map acceptance criteria to tests.\n- [ ] RED: create or identify failing test.\n- [ ] GREEN: implement minimum passing change.\n- [ ] REFACTOR: improve design while tests stay green.\n- [ ] Update evidence, file list, and change log.\n\n## TDD Checklist\n- [ ] Test targets identified\n- [ ] Red evidence recorded\n- [ ] Green evidence recorded\n- [ ] Refactor validation recorded\n\n## Notes\n- Risks:\n- Dependencies:\n\n## Dev Agent Record\n### Test Intent\n\n### Debug Log\n\n### Completion Notes\n\n### File List\n\n## Change Log\n- {{date}}: Story drafted.\n\n## Spec Anti-Mistake Checklist\n- Reuse existing project patterns before adding new files.\n- Verify file locations before editing.\n- Do not introduce new libraries without explicit need.\n- Preserve existing behavior unless an acceptance criterion requires change.\n- Capture previous-story learnings if this continues prior work.\n- Do not mark any task complete without test or validation evidence.\n";
+export declare const storyTemplate = "---\nstatus: draft\nevidence: .speckit/evidence/{{slug}}-tdd-evidence.md\ncontext: pending\nstory_key: {{slug}}\nac_count: 0\n---\n\n# Story: {{title}}\n\n## Intent\n{{intent}}\n\n## Business Goal\n- Goal:\n- Priority: medium\n- Success signal:\n\n## Acceptance Criteria\n- AC1: Given ...\n  When ...\n  Then ...\n\n## Edge Cases\n- Boundary:\n- Error path:\n- State transition:\n\n## Implementation Scope\n- In scope:\n- Out of scope:\n- Files likely to read:\n- Files likely to modify:\n\n## Architecture Notes\n- Constraints:\n- Integration points:\n- Risks:\n\n## Dev Notes\n- Existing patterns to reuse:\n- Architecture constraints:\n- Edge cases:\n- Previous-story learnings:\n\n## Tasks / Subtasks\n- [ ] Map acceptance criteria to tests.\n- [ ] RED: create or identify failing test.\n- [ ] GREEN: implement minimum passing change.\n- [ ] REFACTOR: improve design while tests stay green.\n- [ ] Update evidence, file list, and change log.\n\n## TDD Checklist\n- [ ] Test targets identified\n- [ ] Red evidence recorded\n- [ ] Green evidence recorded\n- [ ] Refactor validation recorded\n\n## Notes\n- Risks:\n- Dependencies:\n\n## Dev Agent Record\n### Test Intent\n\n### Debug Log\n\n### Completion Notes\n\n### File List\n\n## Change Log\n- {{date}}: Story drafted.\n\n## Spec Anti-Mistake Checklist\n- Reuse existing project patterns before adding new files.\n- Verify file locations before editing.\n- Do not introduce new libraries without explicit need.\n- Preserve existing behavior unless an acceptance criterion requires change.\n- Capture previous-story learnings if this continues prior work.\n- Do not mark any task complete without test or validation evidence.\n";
 export declare const tddEvidenceTemplate = "---\nstatus: missing\nstory: {{story}}\nphase: not-started\n---\n\n# TDD Evidence: {{story}}\n\n## Test Intent\n- Acceptance criteria covered:\n- Test files:\n- Command:\n\n## Red\n- Command:\n- Result:\n- Failing reason:\n\n## Green\n- Command:\n- Result:\n- Passing evidence:\n\n## Refactor\n- Command:\n- Result:\n- Regression evidence:\n\n## Review Evidence\n- Reviewer:\n- Outcome:\n- Follow-ups:\n";

package/dist/core/templates.js

@@ -11,17 +11,32 @@ ac_count: 0
 ## Intent
 {{intent}}
 
+## Business Goal
+- Goal:
+- Priority: medium
+- Success signal:
+
 ## Acceptance Criteria
 - AC1: Given ...
   When ...
   Then ...
 
+## Edge Cases
+- Boundary:
+- Error path:
+- State transition:
+
 ## Implementation Scope
 - In scope:
 - Out of scope:
 - Files likely to read:
 - Files likely to modify:
 
+## Architecture Notes
+- Constraints:
+- Integration points:
+- Risks:
+
 ## Dev Notes
 - Existing patterns to reuse:
 - Architecture constraints:

package/docs/adapters.md

@@ -14,6 +14,18 @@ Speckit compiles one workflow into native files for five IDEs.
 
 Generated files include the `speckit:managed` marker. Speckit updates managed files idempotently and skips unmanaged files unless `--force` is provided.
 
+## Shared Enterprise Contract
+
+All adapters point agents back to the shared Speckit runtime:
+
+- `.speckit/agents/super-agent.md`
+- `.speckit/skills/catalog.md`
+- `.speckit/team/*.md`
+- `.speckit/context/current.md`
+- `.speckit/context/subagent-handoff.md`
+
+Adapters should not redefine team workflow rules independently. Update the shared generator and re-run `speckit init --enterprise --ide <name>` when the contract changes.
+
 ## Cursor Policy
 
 Cursor uses `.cursor/rules/*.mdc`. Speckit does not generate the legacy `.cursorrules` file.

package/docs/code-standards.md

@@ -5,5 +5,7 @@
 - Prefer deterministic file generation over runtime prompts.
 - Use `writeManagedFiles` for generated files so unmanaged user files are protected.
 - Keep adapter logic declarative: `name`, `displayName`, `outputPaths`, `render`.
+- Keep enterprise evaluators artifact-based. Team status, audit, and score should inspect durable files instead of chat history.
+- Keep public docs aligned with CLI help whenever a command is added.
 - Add tests for command behavior and adapter contracts before expanding implementation scope.
 - Do not invoke interactive external tools from automation paths.

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.3.5`.
+Current package target: `@trieungoctam/speckit@0.4.0`.
 
-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.
+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 now exposes team-role workflow status, review-gate audit, handoff files, and runtime scoring.
 
 ## Milestones
 
@@ -20,17 +20,21 @@ The CLI is npx-ready, generates Agile + TDD rules, creates workflow artifacts, s
 | Beads integration | MVP Complete | `graph setup` prints install commands and prepares `.beads/beads.jsonl`; `next` and `graph triage/plan/insights` wrap BV robot mode; `sync` exports story metadata JSONL. |
 | 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. |
+| Enterprise team workflow | Complete | `init --enterprise` creates `.speckit/team/*`; `team status`, `team audit`, and `team handoff` expose role-owned artifacts and review blockers. |
+| Runtime scoring | Complete | `score` reports project or story workflow health across contract, team, session/context, graph, TDD, and review categories. |
 | 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. |
+| npm package readiness | Ready | Package scoped as `@trieungoctam/speckit`; `npm pack --dry-run` passes for `0.4.0`. |
 
 ## Next Roadmap
 
+- Add `score --threshold <n>` for CI gating after teams agree on rollout policy.
 - Add `review --deep` with multi-layer acceptance, edge-case, and production-readiness prompts.
 - Add graph drift and history correlation commands.
+- Add lockfile and drift detection for generated Speckit contracts.
 - Add GitHub trusted publishing for npm releases.
 - Add snapshot tests for full adapter file contents.

package/docs/enterprise-rollout.md

@@ -6,9 +6,10 @@ Speckit works best as a repo-local standard, then as an organization template.
 
 1. Pilot in one service repository with `speckit init --ide all`.
 2. Require stories to include acceptance criteria and TDD evidence.
-3. Add `speckit doctor` and project tests to CI.
-4. Export stories with `speckit sync` for task graph visibility.
-5. Roll the generated adapter pack into team templates.
+3. Require `speckit team status <story>` before implementation handoff.
+4. Add `speckit doctor`, `speckit validate`, `speckit score --json`, and project tests to CI.
+5. Export stories with `speckit sync` for task graph visibility.
+6. Roll the generated adapter pack into team templates.
 
 ## Governance Layers
 
@@ -16,12 +17,16 @@ Speckit works best as a repo-local standard, then as an organization template.
 | --- | --- | --- |
 | Company policy | Engineering leadership | `.speckit/rules/enterprise-safety.md` |
 | Team workflow | Tech lead | `.speckit/workflows/*.md` |
+| Team roles | Product / engineering lead | `.speckit/team/*.md` |
 | Repo standard | Maintainers | `AGENTS.md`, `CLAUDE.md`, IDE config |
 | Story evidence | Implementer | `.speckit/evidence/*.md` |
+| Review readiness | Reviewer / lead | `speckit team audit <story>` |
 
 ## Recommended Controls
 
 - Do not allow code stories to merge without red-green-refactor evidence.
 - Keep adapter output generated from Speckit instead of hand-maintaining per-IDE rules.
 - Treat `speckit doctor` warnings as rollout debt.
+- Treat `speckit score` as the adoption health metric. Start non-blocking, then define a threshold after the pilot.
+- Use `speckit team handoff` whenever work moves from development to QA or review.
 - Use Beads Viewer only through robot commands for non-interactive automation.