@mknightzzz/stw 0.1.0

package/dist/spec-templates.js

@@ -0,0 +1,285 @@
+const TEMPLATES = {
+    bugfix: `# Spec: <!-- Title: Fix [describe the bug] -->
+
+## Context
+
+<!-- What's broken? Include error messages, reproduction steps, and where it was observed. -->
+
+## Objective
+
+<!-- One sentence: what will be true after this fix ships? -->
+
+## Requirements
+
+### T1: <!-- Root-cause fix -->
+
+<!-- Describe the fix. Include:
+- Which file(s) and function(s) are affected
+- What the current behavior is vs expected behavior
+- The fix approach
+-->
+
+Modified file: <!-- e.g. src/foo.ts -->
+
+### T2: <!-- Regression test -->
+
+<!-- Add a test that would have caught this bug. -->
+
+Modified file: <!-- e.g. tests/foo.test.ts -->
+
+## Constraints
+
+- Fix must not change public API or break existing tests
+- Existing tests must continue to pass
+
+## Acceptance Criteria
+
+- The bug no longer reproduces
+- A regression test covers the failure case
+- \`npx vitest run\` passes with no regressions
+- \`npx tsc --noEmit\` passes
+
+## Risk Assessment
+
+- <!-- What could go wrong with this fix? What's the blast radius? -->
+
+## Commands to Validate
+
+- npx vitest run
+- npx tsc --noEmit
+
+## Non-Goals
+
+- <!-- What are you explicitly NOT fixing in this milestone? -->
+`,
+    feature: `# Spec: <!-- Title: Add [feature name] -->
+
+## Context
+
+<!-- Why does this feature need to exist? What problem does it solve? -->
+
+## Objective
+
+<!-- One sentence: what new capability will exist after this ships? -->
+
+Task Count: <!-- Exactly N tasks. -->
+
+## Requirements
+
+### T1: <!-- Core implementation -->
+
+<!-- Describe what to build. Include:
+- New files to create
+- Existing files to modify
+- Key interfaces/functions
+- Behavior specification
+-->
+
+New file: <!-- e.g. src/new-feature.ts -->
+Modified file: <!-- e.g. src/cli.ts -->
+
+### T2: <!-- Tests -->
+
+<!-- Describe test coverage needed. -->
+
+New file: <!-- e.g. tests/new-feature.test.ts -->
+
+## Constraints
+
+- <!-- Boundaries: what this feature should NOT do -->
+- Existing tests must continue to pass
+
+## Acceptance Criteria
+
+- <!-- Concrete observable outcomes, one per bullet -->
+- \`npx vitest run\` passes with no regressions
+- \`npx tsc --noEmit\` passes
+
+## Risk Assessment
+
+- <!-- What could go wrong? How is it mitigated? -->
+
+## Commands to Validate
+
+- npx vitest run
+- npx tsc --noEmit
+
+## Non-Goals
+
+- <!-- What's explicitly out of scope? -->
+`,
+    refactor: `# Spec: <!-- Title: Refactor [what] -->
+
+## Context
+
+<!-- Why refactor now? What's the current pain point (duplication, complexity, performance)? -->
+
+## Objective
+
+<!-- One sentence: what structural improvement will exist after this ships? Behavior must not change. -->
+
+Task Count: <!-- Exactly N tasks. -->
+
+## Requirements
+
+### T1: <!-- Structural change -->
+
+<!-- Describe the refactor. Include:
+- Before: current structure
+- After: target structure
+- Invariants: what must remain true
+-->
+
+Modified file: <!-- e.g. src/foo.ts -->
+
+## Constraints
+
+- **No behavior change** — all existing tests must pass without modification
+- No new features or bug fixes bundled into the refactor
+- Existing tests must continue to pass
+
+## Acceptance Criteria
+
+- All existing tests pass without modification
+- <!-- Structural goal achieved, e.g. "No function exceeds 50 lines" -->
+- \`npx vitest run\` passes with no regressions
+- \`npx tsc --noEmit\` passes
+
+## Risk Assessment
+
+- <!-- What invariants could break? How do you verify they hold? -->
+
+## Commands to Validate
+
+- npx vitest run
+- npx tsc --noEmit
+
+## Non-Goals
+
+- <!-- What cleanup are you NOT doing in this refactor? -->
+`,
+    greenfield: `# Spec: <!-- Title: Scaffold [project name] -->
+
+## Tech Stack
+
+- Language: <!-- e.g. TypeScript, Python, Go -->
+- Framework: <!-- e.g. React, Express, FastAPI -->
+- Package Manager: <!-- e.g. npm, pnpm, yarn, pip -->
+- Test Runner: <!-- e.g. vitest, jest, pytest -->
+
+## Context
+
+<!-- Why is this project being created from scratch? What need does it serve? -->
+
+## Objective
+
+<!-- One sentence: what project will exist after scaffolding is complete? -->
+
+## Project Skeleton
+
+<!-- Describe the directory structure. Example:
+\\\`\\\`\\\`
+├── src/
+│   ├── index.ts
+│   └── ...
+├── tests/
+├── package.json
+├── tsconfig.json
+└── ...
+\\\`\\\`\\\`
+-->
+
+## Requirements
+
+### T1: Scaffolding — create project, install dependencies, verify build
+
+<!-- Set up the project from scratch. Include:
+- Initialize the project (e.g. npm init, cargo init)
+- Install core dependencies and dev dependencies
+- Configure the build toolchain
+- Verify the project compiles/builds and tests pass
+-->
+
+New files: <!-- e.g. package.json, tsconfig.json, src/index.ts -->
+
+## Constraints
+
+- Project must build and pass tests after scaffolding
+- No application logic beyond a minimal hello-world entry point
+
+## Acceptance Criteria
+
+- \\\`<!-- test command, e.g. npm test, pytest, cargo test -->\\\` passes
+- \\\`<!-- typecheck command, e.g. npx tsc --noEmit, mypy ., cargo check -->\\\` passes
+- Project directory structure matches the skeleton above
+
+## Risk Assessment
+
+- <!-- What could go wrong during scaffolding? Dependency conflicts, toolchain issues? -->
+
+## Commands to Validate
+
+- <!-- test command matching the chosen stack -->
+- <!-- typecheck/build command matching the chosen stack -->
+
+## Non-Goals
+
+- <!-- What features or setup are explicitly NOT part of this scaffolding? -->
+`,
+    cleanup: `# Spec: <!-- Title: Clean up [scope] -->
+
+## Context
+
+<!-- What accumulated mess needs cleaning? Be specific about what and where. -->
+
+## Objective
+
+<!-- One sentence: what will be cleaner after this ships? -->
+
+Task Count: <!-- Exactly N tasks. -->
+
+## Requirements
+
+### T1: <!-- Cleanup scope -->
+
+<!-- Describe exactly what to clean. Include:
+- Which files
+- What to remove/rename/consolidate
+- Safety: how to verify nothing breaks
+-->
+
+Modified file: <!-- e.g. src/foo.ts -->
+
+## Constraints
+
+- Each task must be independently verifiable
+- No behavior changes unless explicitly noted
+- Existing tests must continue to pass
+
+## Acceptance Criteria
+
+- <!-- Concrete cleanup outcome per bullet -->
+- \`npx vitest run\` passes with no regressions
+- \`npx tsc --noEmit\` passes
+
+## Risk Assessment
+
+- <!-- What could break during cleanup? What's the rollback plan? -->
+
+## Commands to Validate
+
+- npx vitest run
+- npx tsc --noEmit
+
+## Non-Goals
+
+- <!-- What cleanup is explicitly NOT part of this milestone? -->
+`,
+};
+export function getTemplate(name) {
+    return TEMPLATES[name] ?? null;
+}
+export function listTemplates() {
+    return Object.keys(TEMPLATES);
+}
+//# sourceMappingURL=spec-templates.js.map

package/dist/spec-templates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec-templates.js","sourceRoot":"","sources":["../src/spec-templates.ts"],"names":[],"mappings":"AAAA,MAAM,SAAS,GAA2B;IACxC,MAAM,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoDT;IAEC,OAAO,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuDV;IAEC,QAAQ,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiDX;IAEC,UAAU,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmEb;IAEC,OAAO,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgDV;CACA,CAAC;AAEF,MAAM,UAAU,WAAW,CAAC,IAAY;IACtC,OAAO,SAAS,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC;AACjC,CAAC;AAED,MAAM,UAAU,aAAa;IAC3B,OAAO,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;AAChC,CAAC"}

package/dist/spec-validator.d.ts

@@ -0,0 +1,8 @@
+import type { ParsedSpec } from './types.js';
+export interface SpecValidationResult {
+    valid: boolean;
+    spec: ParsedSpec | null;
+    errors: string[];
+    warnings: string[];
+}
+export declare function validateSpec(markdown: string): SpecValidationResult;

package/dist/spec-validator.js

@@ -0,0 +1,144 @@
+import { REQUIRED_SPEC_SECTIONS } from './types.js';
+const WEAK_PLACEHOLDER_PATTERN = /\b(todo|tbd|later|various|misc|stuff|things|etc\.?|somehow|maybe|as needed)\b/i;
+const BROAD_CLEANUP_PATTERN = /\b(clean\s*up|cleanup|refactor|polish|integrate|integration|wire\s*up|hook\s*up|finalize|general improvements?)\b/i;
+const CATCH_ALL_VALIDATION_PATTERN = /\b(run\s+(all|full)\s+(tests|checks|validation)|validate\s+everything|full\s+validation|all\s+tests)\b/i;
+const LOCAL_ONLY_COMMAND_PATTERN = /\b(cd|npm run|pnpm|yarn|node|npx|vitest|jest|tsc|pytest|go test|cargo test|mvn|gradle)\b/i;
+const TASK_SHAPE_SPECIFICITY_PATTERN = /\b(file|files|command|test|api|function|module|component|task|migration|schema|endpoint|cli|script|validator|planner|assignment|graph)\b/i;
+const TASK_SHAPE_AMBIGUITY_PATTERN = /\b(handle|support|improve|update|fix|adjust|address)\b/i;
+const WEAK_ACCEPTANCE_CHECK_PATTERN = /\b(looks good|works as expected|verify manually|manual verification|sanity check|spot check)\b/i;
+export function validateSpec(markdown) {
+    const errors = [];
+    const warnings = [];
+    const titleMatch = markdown.match(/^# Spec:\s*(.+?)\s*$/m);
+    const title = titleMatch?.[1]?.trim() ?? '';
+    const sections = parseSections(markdown);
+    if (!title) {
+        errors.push('Missing required title: # Spec: <title>');
+    }
+    for (const sectionName of REQUIRED_SPEC_SECTIONS) {
+        if (!sections.get(sectionName)) {
+            errors.push(`Missing required section: ${sectionName}`);
+        }
+    }
+    if (errors.length > 0) {
+        return { valid: false, spec: null, errors, warnings: [] };
+    }
+    const spec = {
+        title,
+        objective: sections.get('Objective') ?? '',
+        context: sections.get('Context') ?? '',
+        requirements: sections.get('Requirements') ?? '',
+        constraints: sections.get('Constraints') ?? '',
+        acceptance_criteria: sections.get('Acceptance Criteria') ?? '',
+        risk_assessment: sections.get('Risk Assessment') ?? '',
+        ...optionalField('target_files', sections.get('Target Files')),
+        ...optionalField('non_goals', sections.get('Non-Goals')),
+        ...optionalField('notes_for_reviewer', sections.get('Notes for Reviewer')),
+        ...optionalField('commands_to_validate', sections.get('Commands to Validate')),
+    };
+    warnings.push(...collectSpecWarnings(spec));
+    return {
+        valid: true,
+        spec,
+        errors: [],
+        warnings,
+    };
+}
+function collectSpecWarnings(spec) {
+    const warnings = [];
+    if (isWeakAcceptanceCriteria(spec.acceptance_criteria)) {
+        warnings.push('Acceptance Criteria appear weak or underspecified; include concrete expected outcomes.');
+    }
+    if (isAmbiguousTaskShape(spec.requirements, spec.objective)) {
+        warnings.push('Requirements/objective are ambiguous about the task shape; prefer explicit deliverables and boundaries.');
+    }
+    if (isBroadCleanupOrIntegration(spec.requirements, spec.objective)) {
+        warnings.push('Spec appears to describe broad cleanup/integration work; split into narrower, independently verifiable changes.');
+    }
+    if (hasWeakAcceptanceChecks(spec.acceptance_criteria)) {
+        warnings.push('Acceptance Criteria rely on weak checks like vague manual verification; prefer precise commands or observable outcomes.');
+    }
+    if (hasCatchAllValidation(spec.acceptance_criteria)) {
+        warnings.push('Acceptance Criteria include catch-all validation phrasing; enumerate the specific checks that matter.');
+    }
+    if (hasLocalOnlyCommandValidationGap(spec.commands_to_validate, spec.acceptance_criteria)) {
+        warnings.push('Commands to Validate is missing or weak for a spec that implies command-based validation; list local runnable commands.');
+    }
+    return warnings;
+}
+function isWeakAcceptanceCriteria(value) {
+    const lines = toMeaningfulLines(value);
+    if (lines.length === 0) {
+        return true;
+    }
+    if (lines.length < 3 && value.trim().length < 120) {
+        return true;
+    }
+    return (lines.some((line) => WEAK_PLACEHOLDER_PATTERN.test(line))
+        || hasWeakAcceptanceChecks(value)
+        || hasCatchAllValidation(value));
+}
+function isAmbiguousTaskShape(requirements, objective) {
+    const combined = `${objective}\n${requirements}`;
+    const lines = toMeaningfulLines(combined);
+    if (lines.length === 0) {
+        return true;
+    }
+    const lacksSpecificity = !TASK_SHAPE_SPECIFICITY_PATTERN.test(combined);
+    const hasAmbiguousWords = TASK_SHAPE_AMBIGUITY_PATTERN.test(combined);
+    return lacksSpecificity && hasAmbiguousWords;
+}
+function isBroadCleanupOrIntegration(requirements, objective) {
+    const combined = `${objective}\n${requirements}`;
+    return BROAD_CLEANUP_PATTERN.test(combined) && !/\b(single|specific|only|exact|limited)\b/i.test(combined);
+}
+function hasWeakAcceptanceChecks(value) {
+    return WEAK_ACCEPTANCE_CHECK_PATTERN.test(value);
+}
+function hasCatchAllValidation(value) {
+    return CATCH_ALL_VALIDATION_PATTERN.test(value);
+}
+function hasLocalOnlyCommandValidationGap(commandsToValidate, acceptanceCriteria) {
+    const impliesCommands = LOCAL_ONLY_COMMAND_PATTERN.test(acceptanceCriteria);
+    if (!impliesCommands) {
+        return false;
+    }
+    if (!commandsToValidate || toMeaningfulLines(commandsToValidate).length === 0) {
+        return true;
+    }
+    return !LOCAL_ONLY_COMMAND_PATTERN.test(commandsToValidate);
+}
+function toMeaningfulLines(value) {
+    return value
+        .split('\n')
+        .map((line) => line.replace(/^[-*]\s*/, '').trim())
+        .filter((line) => line.length > 0);
+}
+function parseSections(markdown) {
+    const sections = new Map();
+    const headingRegex = /^##\s+(.+?)\s*$/gm;
+    const headings = [];
+    let match;
+    while ((match = headingRegex.exec(markdown)) !== null) {
+        headings.push({
+            name: match[1].trim(),
+            contentStart: headingRegex.lastIndex,
+            headingStart: match.index,
+        });
+    }
+    for (let index = 0; index < headings.length; index += 1) {
+        const current = headings[index];
+        const next = headings[index + 1];
+        const contentEnd = next?.headingStart ?? markdown.length;
+        const value = markdown.slice(current.contentStart, contentEnd).trim();
+        sections.set(current.name, value);
+    }
+    return sections;
+}
+function optionalField(key, value) {
+    if (!value) {
+        return {};
+    }
+    return { [key]: value };
+}
+//# sourceMappingURL=spec-validator.js.map

package/dist/spec-validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec-validator.js","sourceRoot":"","sources":["../src/spec-validator.ts"],"names":[],"mappings":"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"}

package/dist/status.d.ts

@@ -0,0 +1,68 @@
+import type { RunManifest, RunState, TaskState, TaskStateRecord, TaskStatus } from './types.js';
+import type { EscalationCategory, RunEvent, RunEventsArtifact, RunMetricsArtifact } from './run-artifact-types.js';
+export declare function writeTaskStatus(stwRoot: string, runId: string, taskId: string, input: {
+    agent_id: string;
+    status: TaskStatus['status'];
+    notes: string;
+    question_number?: number;
+    preserved_worktree_path?: string;
+    preserved_worktree_paths?: string[];
+    stop_reason?: string;
+    stopped_at?: string;
+    stopped_by?: string;
+    execution_mode?: TaskStatus['execution_mode'];
+    failure_class?: TaskStatus['failure_class'];
+}): TaskStatus;
+export declare function readTaskStatus(stwRoot: string, runId: string, taskId: string): TaskStatus | null;
+export declare function writeTaskState(stwRoot: string, runId: string, taskId: string, state: TaskState, updatedBy: string): TaskStateRecord;
+export declare function writeRunState(stwRoot: string, runId: string, state: RunState, options?: {
+    pause_reason?: string;
+    drift_detected?: boolean;
+}): RunManifest;
+export declare function readRunStatus(stwRoot: string, runId: string, taskIds: string[]): Record<string, TaskStatus['status'] | 'pending'>;
+export interface StaleTaskReport {
+    taskId: string;
+    taskStatus: TaskStatus;
+    taskState: TaskStateRecord | null;
+}
+export interface RunRecoveryReport {
+    manifest: RunManifest;
+    stale: boolean;
+    reason: 'none' | 'stale_lock' | 'persisted_in_progress_without_live_lock';
+    staleTasks: StaleTaskReport[];
+    guidance: string[];
+}
+export declare function readTaskState(stwRoot: string, runId: string, taskId: string): TaskStateRecord | null;
+export declare function buildRunRecoveryReport(stwRoot: string, runId: string, taskIds: string[]): RunRecoveryReport;
+export declare function readRunEvents(stwRoot: string, runId: string): RunEventsArtifact;
+export declare function recordRunEvent(stwRoot: string, runId: string, input: {
+    event_type: RunEvent['event_type'];
+    actor: string;
+    task_id?: string;
+    summary: string;
+    details?: string;
+    escalation_category?: EscalationCategory;
+    metadata?: Record<string, string | number | boolean | null>;
+}): RunEvent;
+export declare function readRunMetrics(stwRoot: string, runId: string): RunMetricsArtifact | null;
+export declare function writeRunMetrics(stwRoot: string, runId: string, input: Omit<RunMetricsArtifact, 'schema_version' | 'run_id' | 'updated_at'>): RunMetricsArtifact;
+export declare function resetTaskToPending(stwRoot: string, runId: string, taskId: string): void;
+export declare function markTaskSkipped(stwRoot: string, runId: string, taskId: string, reason: string): void;
+export declare function markTaskComplete(stwRoot: string, runId: string, taskId: string): void;
+export interface StatusData {
+    runId: string;
+    manifest: RunManifest;
+    tasks: Array<{
+        id: string;
+        description: string;
+        task_type: string;
+        state: string;
+        status: string | null;
+        agent_id: string | null;
+        notes: string | null;
+        completed_at: string | null;
+        cost_usd: number | null;
+    }>;
+    total_cost_usd: number;
+}
+export declare function getStatusData(stwRoot: string, runId: string): StatusData;