empirical-sdd 0.20.0

package/dist/integrations.d.ts

@@ -0,0 +1,3 @@
+import type { IntegrationReport } from "./types.js";
+export declare function installProjectIntegrations(root: string): Promise<IntegrationReport>;
+export declare function installGlobalAgentSkills(homeRoot?: string): Promise<IntegrationReport>;

package/dist/mcp.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function createMcpServer(defaultRoot?: string): McpServer;
+export declare function runMcpServer(defaultRoot?: string): Promise<void>;

package/dist/specifications.d.ts

@@ -0,0 +1,12 @@
+import { type ProjectStore } from "./storage.js";
+import type { ArchiveReport, CapabilityDelta, CapabilitySummary, DeltaValidationReport } from "./types.js";
+export interface CapabilityArchivePlan {
+    report: Omit<ArchiveReport, "feature" | "converged">;
+    commit: () => Promise<() => Promise<void>>;
+}
+export declare function loadCapabilityDeltas(store: ProjectStore, feature: string): Promise<CapabilityDelta[]>;
+export declare function parseCapabilityDelta(capability: string, markdown: string, source?: string): CapabilityDelta;
+export declare function validateFeatureDeltas(store: ProjectStore, feature: string): Promise<DeltaValidationReport>;
+export declare function capabilityDeltaDigest(store: ProjectStore, feature: string): Promise<string | null>;
+export declare function planCapabilityArchive(store: ProjectStore, feature: string): Promise<CapabilityArchivePlan>;
+export declare function listCapabilities(store: ProjectStore): Promise<CapabilitySummary[]>;

package/dist/storage.d.ts

@@ -0,0 +1,74 @@
+import { type ProjectPolicy, type ProjectConfig, type WorkflowState } from "./types.js";
+export declare class ProjectStore {
+    readonly root: string;
+    readonly feature: string | null;
+    constructor(root: string, feature?: string | null);
+    get directory(): string;
+    get configPath(): string;
+    get policyPath(): string;
+    get stateDirectory(): string;
+    get statePath(): string;
+    get eventsDirectory(): string;
+    get capabilitiesDirectory(): string;
+    forFeature(feature: string): ProjectStore;
+    capabilityDirectory(capability: string): string;
+    capabilitySpecPath(capability: string): string;
+    specDirectory(feature: string): string;
+    specPath(feature: string): string;
+    evidencePath(feature: string): string;
+    deltaDirectory(feature: string): string;
+    exists(): Promise<boolean>;
+    ensureLayout(): Promise<void>;
+    loadPolicy(): Promise<ProjectPolicy>;
+    writePolicy(policy: ProjectPolicy): Promise<void>;
+    loadConfig(): Promise<ProjectConfig>;
+    loadState(recover?: boolean): Promise<WorkflowState>;
+    writeConfig(config: ProjectConfig): Promise<void>;
+    writeInitial(config: ProjectConfig): Promise<void>;
+    writeInitialFeature(state: WorkflowState, actor?: string, summary?: string): Promise<void>;
+    configure(update: Partial<ProjectConfig>): Promise<ProjectConfig>;
+    activeFeature(recover?: boolean): Promise<string | null>;
+    listFeatureIds(): Promise<string[]>;
+    transition(expectedRevision: number, actor: string, summary: string, mutate: (state: WorkflowState) => WorkflowState): Promise<WorkflowState>;
+    transaction<T>(prepare: (current: WorkflowState) => Promise<{
+        actor: string;
+        summary: string;
+        state: WorkflowState;
+        value: T;
+        validate?: () => Promise<void>;
+        effect?: () => Promise<() => Promise<void>>;
+    }>): Promise<{
+        state: WorkflowState;
+        value: T;
+    }>;
+    migrateSchema(): Promise<Record<string, unknown>>;
+    writeSpec(feature: string, contents: string): Promise<void>;
+    readSpec(feature: string): Promise<string>;
+    writeEvidence(feature: string, evidence: unknown): Promise<void>;
+    readEvidence<T>(feature: string): Promise<T[]>;
+    listCapabilityNames(): Promise<string[]>;
+    readCapability(capability: string): Promise<string | null>;
+    writeCapability(capability: string, contents: string): Promise<void>;
+    removeCapability(capability: string): Promise<void>;
+    withResourceLock<T>(resource: "specs" | "capabilities" | "policy", operation: () => Promise<T>): Promise<T>;
+    assertCurrentSchemaReadOnly(): Promise<void>;
+    private eventPath;
+    private latestEvent;
+    private commitInitialState;
+    private withLock;
+    private requireFeature;
+    private assertCapabilityPathSafe;
+    assertFeaturePathSafe(feature: string, additional?: string[]): Promise<void>;
+    private assertProjectPathSafe;
+    private ensureProjectMetadata;
+    private ensureCurrentConfigSchema;
+}
+export declare function isRetryableLockOpenError(error: unknown, platform?: NodeJS.Platform): boolean;
+export declare function discoverProject(start: string): Promise<ProjectStore>;
+export declare function writeJsonAtomic(path: string, value: unknown): Promise<void>;
+export declare function writeTextAtomic(path: string, contents: string): Promise<void>;
+export declare function isFile(path: string): Promise<boolean>;
+export declare function isSymbolicLink(path: string): Promise<boolean>;
+export declare function readJson<T>(path: string, code?: string): Promise<T>;
+export declare function assertFeatureId(feature: string): void;
+export declare function assertCapabilityId(capability: string): void;

package/dist/types.d.ts

@@ -0,0 +1,283 @@
+export declare const SCHEMA_VERSION: 4;
+export declare const PRODUCT_VERSION = "0.20.0";
+export declare const POLICY_SCHEMA_VERSION: 1;
+export type Workflow = "fast" | "complex";
+export type Profile = Workflow | "quick";
+export type Phase = "idle" | "shape" | "specify" | "design" | "plan" | "implement" | "verify" | "review" | "archive" | "done";
+export type WorkflowStatus = "idle" | "waiting" | "awaiting_human" | "blocked" | "done";
+export type Outcome = "passed" | "failed" | "awaiting_human" | "blocked";
+export type EvidenceKind = "test" | "browser" | "screenshot" | "review" | "human";
+export type ChangeType = "feature" | "fix" | "chore";
+export type IsolationMode = "ask" | "off";
+export type ComplexDecisionMode = "required" | "off";
+export interface IsolationConfig {
+    mode: IsolationMode;
+    baseBranch: string;
+    worktreePath: string;
+    branchPattern: string;
+}
+export interface DecisionConfig {
+    complexRecords: ComplexDecisionMode;
+}
+export interface ProjectConfig {
+    schemaVersion: typeof SCHEMA_VERSION;
+    profile: Profile;
+    maxRepairAttempts: number;
+    evidence: {
+        required: boolean;
+        browserForUi: boolean;
+        screenshotForUi: boolean;
+        codeReview: boolean;
+    };
+    isolation: IsolationConfig;
+    decisions: DecisionConfig;
+    setupComplete: boolean;
+    legacySource: "ai" | null;
+}
+export interface ProjectConfigurationInput {
+    isolation?: Partial<IsolationConfig>;
+    decisions?: Partial<DecisionConfig>;
+    setupComplete?: boolean;
+}
+export interface WorkflowState {
+    schemaVersion: typeof SCHEMA_VERSION;
+    revision: number;
+    activeFeature: string | null;
+    request: string | null;
+    profile: Profile;
+    phase: Phase;
+    status: WorkflowStatus;
+    repairAttempts: number;
+    message: string | null;
+    implementationActor: string | null;
+    specDigest: string | null;
+    capabilityArchiveRequired: boolean;
+    capabilityDeltaDigest: string | null;
+    evidence: Evidence[];
+    updatedAt: string;
+}
+export interface ProjectPolicy {
+    schemaVersion: typeof POLICY_SCHEMA_VERSION;
+    context: string[];
+    phases: Partial<Record<Phase, string[]>>;
+}
+export interface Criterion {
+    id: string;
+    text: string;
+    ui: boolean;
+    checked: boolean;
+}
+export interface Evidence {
+    criterionId: string;
+    kind: EvidenceKind;
+    passed: boolean;
+    summary: string;
+    artifact?: string;
+}
+export interface CompletionInput {
+    revision: number;
+    outcome: Outcome;
+    summary: string;
+    actor?: string;
+    evidence?: Evidence[];
+}
+export interface ActionRationale {
+    currentState: string;
+    nextAction: string;
+    reason: string;
+    requiredContext: string[];
+    missingContext: string[];
+    gate: "proceed" | "stop";
+}
+export interface ActionPacket {
+    kind: "action";
+    protocol: "empirical-sdd";
+    schemaVersion: typeof SCHEMA_VERSION;
+    root: string;
+    feature: string | null;
+    request: string | null;
+    profile: Profile;
+    phase: Phase;
+    status: WorkflowStatus;
+    revision: number;
+    instructions: string;
+    rationale: ActionRationale;
+    acceptanceCriteria: Criterion[];
+    requiredEvidence: EvidenceKind[];
+    artifacts: string[];
+    projectContext: string[];
+    capabilityContext: string[];
+    completion: {
+        available: boolean;
+        mcpTool: "empirical_complete" | "empirical_archive";
+        cli: string;
+        requiredFields: string[];
+    };
+}
+export interface WorktreeProposal {
+    kind: "worktree_proposal";
+    protocol: "empirical-sdd";
+    schemaVersion: typeof SCHEMA_VERSION;
+    root: string;
+    request: string;
+    workflow: Workflow;
+    changeType: ChangeType;
+    feature: string;
+    branch: string;
+    path: string;
+    base: string;
+    baseCommit: string;
+    activeFeature: string;
+    approvalToken: string;
+    command: string[];
+    requiresApproval: true;
+}
+export interface WorktreeCreateInput {
+    request: string;
+    workflow: Workflow;
+    changeType?: ChangeType;
+    feature?: string;
+    branch?: string;
+    path?: string;
+    base?: string;
+    baseCommit: string;
+    activeFeature: string;
+    approvalToken: string;
+    approved: true;
+}
+export interface WorktreeHandoff {
+    kind: "worktree_handoff";
+    protocol: "empirical-sdd";
+    schemaVersion: typeof SCHEMA_VERSION;
+    root: string;
+    path: string;
+    branch: string;
+    base: string;
+    baseCommit: string;
+    feature: string;
+    revision: number;
+    workflow: Workflow;
+    resume: string;
+    action: ActionPacket;
+}
+export type FeatureStartResult = ActionPacket | WorktreeProposal;
+export interface DecisionSummary {
+    id: string;
+    title: string;
+    status: "Accepted" | "Superseded";
+    chosenApproach: string;
+    supersedes: string[];
+    supersededBy: string | null;
+}
+export interface DecisionValidationReport {
+    valid: boolean;
+    decisions: DecisionSummary[];
+    issues: string[];
+}
+export interface ExplainReport {
+    protocol: "empirical-sdd";
+    schemaVersion: typeof SCHEMA_VERSION;
+    root: string;
+    feature: string | null;
+    phase: Phase;
+    status: WorkflowStatus;
+    revision: number;
+    rationale: ActionRationale;
+    decisions: DecisionSummary[];
+}
+export interface ExplorationPacket {
+    protocol: "empirical-sdd";
+    schemaVersion: typeof SCHEMA_VERSION;
+    root: string;
+    problem: string;
+    instructions: string[];
+    questions: string[];
+    projectContext: string[];
+    capabilityContext: string[];
+    next: {
+        fast: string;
+        complex: string;
+    };
+}
+export type DeltaOperation = "added" | "modified" | "removed";
+export interface RequirementDelta {
+    operation: DeltaOperation;
+    name: string;
+    contents: string;
+}
+export interface CapabilityDelta {
+    capability: string;
+    purpose: string | null;
+    requirements: RequirementDelta[];
+    source: string;
+}
+export interface CapabilitySummary {
+    name: string;
+    path: string;
+    requirements: number;
+}
+export interface DeltaValidationReport {
+    valid: boolean;
+    capabilities: string[];
+    operations: number;
+    issues: string[];
+    digest: string | null;
+}
+export interface ArchiveReport {
+    feature: string;
+    capabilities: string[];
+    added: number;
+    modified: number;
+    removed: number;
+    converged: boolean;
+}
+export interface ArchiveResult {
+    action: ActionPacket;
+    report: ArchiveReport;
+}
+export interface TransitionEvent {
+    schemaVersion: typeof SCHEMA_VERSION;
+    revision: number;
+    previousRevision: number;
+    actor: string;
+    summary: string;
+    createdAt: string;
+    state: WorkflowState;
+}
+export interface IntegrationReport {
+    scope: "project" | "global";
+    created: string[];
+    updated: string[];
+    preserved: string[];
+    entrypoints: AgentEntrypointReport[];
+}
+export type AgentIntegrationId = "codex" | "claude" | "cursor" | "gemini" | "windsurf";
+export interface AgentEntrypointReport {
+    id: AgentIntegrationId;
+    agent: string;
+    kind: "skill" | "slash-command";
+    artifactRoot: string;
+    invocations: string[];
+    reload: string;
+}
+export interface InitOptions extends ProjectConfigurationInput {
+    profile?: Workflow;
+    integrations?: boolean;
+}
+export interface StartOptions {
+    profile?: Workflow;
+    id?: string;
+}
+export interface FeatureStartOptions {
+    id?: string;
+}
+export interface AdoptionOptions extends ProjectConfigurationInput {
+    profile?: Workflow;
+    integrations?: boolean;
+}
+export interface ValidationReport {
+    valid: boolean;
+    phase: Phase;
+    criteria: number;
+    missing: string[];
+}

package/dist/worktrees.d.ts

@@ -0,0 +1,13 @@
+import { type ChangeType, type IsolationConfig, type Workflow, type WorktreeProposal } from "./types.js";
+export interface WorktreeOverrides {
+    changeType?: ChangeType;
+    feature?: string;
+    branch?: string;
+    path?: string;
+    base?: string;
+}
+export declare function inferChangeType(request: string): ChangeType;
+export declare function featureSlug(request: string): string;
+export declare function proposeWorktree(root: string, request: string, workflow: Workflow, activeFeature: string, config: IsolationConfig, overrides?: WorktreeOverrides): WorktreeProposal;
+export declare function createGitWorktree(proposal: WorktreeProposal): Promise<void>;
+export declare function detectBase(root: string): string;

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "empirical-sdd",
+  "version": "0.20.0",
+  "description": "Agent-neutral, resumable spec-driven development for every terminal-capable coding agent",
+  "type": "module",
+  "bin": {
+    "empirical": "dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "bun run scripts/build.ts",
+    "check": "tsc -p tsconfig.json --noEmit",
+    "test": "bun test",
+    "test:dist": "bun run build && bun run scripts/smoke-mcp.ts",
+    "prepack": "bun run build",
+    "test:package": "bun run scripts/test-package.ts",
+    "ci": "bun run check && bun test && bun run test:dist && bun run test:package"
+  },
+  "keywords": [
+    "agents",
+    "mcp",
+    "sdd",
+    "spec-driven-development",
+    "codex",
+    "claude"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MateoCerquetella/empirical-sdd.git"
+  },
+  "bugs": {
+    "url": "https://github.com/MateoCerquetella/empirical-sdd/issues"
+  },
+  "homepage": "https://github.com/MateoCerquetella/empirical-sdd#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "@types/node": "^26.1.2",
+    "typescript": "^7.0.2",
+    "zod": "^4.4.3"
+  }
+}