cclaw-cli 0.15.0 → 0.15.1

package/dist/content/stages/spec.js

@@ -0,0 +1,136 @@
+// ---------------------------------------------------------------------------
+// SPEC
+// ---------------------------------------------------------------------------
+export const SPEC = {
+    stage: "spec",
+    skillFolder: "specification-authoring",
+    skillName: "specification-authoring",
+    skillDescription: "Specification stage. Produce measurable, testable requirements without ambiguity.",
+    hardGate: "Do NOT plan tasks or write implementation code. This stage produces a specification document only. Every requirement must be expressed in observable, testable terms.",
+    ironLaw: "EVERY ACCEPTANCE CRITERION MUST BE OBSERVABLE AND TESTABLE — OR IT DOES NOT EXIST.",
+    purpose: "Create a testable specification aligned with approved design and constraints.",
+    whenToUse: [
+        "After design lock",
+        "Before planning and implementation",
+        "When acceptance criteria must be measurable"
+    ],
+    whenNotToUse: [
+        "Design decisions are still unresolved or disputed",
+        "The task is implementation-only cleanup with unchanged behavior",
+        "You still need to challenge scope rather than author requirements"
+    ],
+    checklist: [
+        "Read upstream — load design artifact and scope contract. Cross-reference architecture decisions.",
+        "Define measurable acceptance criteria — each criterion must be observable and falsifiable. No vague adjectives.",
+        "Capture edge cases — for each criterion, define at least one boundary condition and one error condition.",
+        "Document constraints and assumptions — regulatory, system, integration, and performance boundaries. Surface implicit assumptions explicitly.",
+        "Confirm testability — for each acceptance criterion, describe the test that would prove it. If untestable, rewrite the criterion.",
+        "Write spec artifact and request user approval — wait for explicit confirmation before proceeding."
+    ],
+    interactionProtocol: [
+        "Express each requirement in observable terms.",
+        "Resolve ambiguity before moving to plan. Challenge vague language.",
+        "Capture assumptions explicitly, not implicitly.",
+        "Require user confirmation on the written spec. **STOP.** Do NOT proceed to plan until user approves.",
+        "For each criterion, ask: how would you test this? If the answer is unclear, rewrite.",
+        "When encountering ambiguity, classify it before acting: (A) ask user for missing info, (B) enumerate interpretations and pick one with justification, (C) propose hypothesis with validation path. Do NOT silently resolve ambiguity."
+    ],
+    process: [
+        "Define measurable acceptance criteria.",
+        "Capture constraints, assumptions, and edge cases.",
+        "Build testability map: criterion -> test description.",
+        "Confirm testability for each criterion.",
+        "Write spec artifact and request approval."
+    ],
+    requiredGates: [
+        { id: "spec_acceptance_measurable", description: "Acceptance criteria are measurable and observable." },
+        { id: "spec_edge_cases_documented", description: "Boundary and error conditions are defined for each criterion." },
+        { id: "spec_constraints_documented", description: "Constraints and assumptions are explicit." },
+        { id: "spec_testability_confirmed", description: "Each criterion has a described test method." },
+        { id: "spec_user_approved", description: "User approved the final written spec." }
+    ],
+    requiredEvidence: [
+        "Artifact written to `.cclaw/artifacts/04-spec.md`.",
+        "Each acceptance criterion maps to a testable outcome.",
+        "Edge cases documented per criterion.",
+        "Approval marker captured in artifact."
+    ],
+    inputs: ["design artifact", "business constraints", "quality requirements"],
+    requiredContext: [
+        "design lock baseline",
+        "regulatory or system boundaries",
+        "integration constraints"
+    ],
+    outputs: [
+        "measurable specification",
+        "acceptance-to-testability map",
+        "approved spec artifact"
+    ],
+    blockers: [
+        "non-measurable criteria",
+        "constraints missing",
+        "open ambiguities remain"
+    ],
+    exitCriteria: [
+        "spec approved by user",
+        "required gates marked satisfied",
+        "plan-ready acceptance mapping exists",
+        "testability confirmed for all criteria"
+    ],
+    antiPatterns: [
+        "High-level goals without measurable outcomes",
+        "Implicit assumptions",
+        "Proceeding to plan before approval",
+        "Using vague adjectives (fast, intuitive, robust) without thresholds"
+    ],
+    redFlags: [
+        "Criteria use vague language (fast, intuitive, robust) without thresholds",
+        "No explicit assumptions section",
+        "No approval record",
+        "No testability mapping",
+        "Edge cases missing or deferred"
+    ],
+    policyNeedles: ["Acceptance Criteria", "Constraints", "Testability", "approved spec", "Edge Cases"],
+    artifactFile: "04-spec.md",
+    next: "plan",
+    reviewSections: [
+        {
+            title: "Acceptance Criteria Audit",
+            evaluationPoints: [
+                "Is every criterion observable (can you point to evidence of pass/fail)?",
+                "Is every criterion measurable (numeric threshold or boolean outcome)?",
+                "Is every criterion falsifiable (can you describe what failure looks like)?",
+                "Does every criterion trace to a design decision (Design Decision Ref)?",
+                "Are there any vague adjectives (fast, intuitive, robust) without thresholds?"
+            ],
+            stopGate: true
+        },
+        {
+            title: "Testability Audit",
+            evaluationPoints: [
+                "Does every criterion have a concrete test description in the Testability Map?",
+                "Does every test specify a verification approach (unit, integration, e2e, manual)?",
+                "Does every test include a runnable command or manual steps?",
+                "Are edge cases (boundary + error) defined for every criterion?",
+                "Can you run every verification command right now and get a meaningful result?"
+            ],
+            stopGate: true
+        }
+    ],
+    completionStatus: ["DONE", "DONE_WITH_CONCERNS", "BLOCKED"],
+    crossStageTrace: {
+        readsFrom: [".cclaw/artifacts/03-design.md", ".cclaw/artifacts/02-scope.md"],
+        writesTo: [".cclaw/artifacts/04-spec.md"],
+        traceabilityRule: "Every acceptance criterion must trace to a design decision. Every downstream plan task must trace to a spec criterion."
+    },
+    artifactValidation: [
+        { section: "Acceptance Criteria", required: true, validationRule: "Each criterion is observable, measurable, and falsifiable. Table must include a Requirement Ref column linking to R# IDs in 02-scope.md and a Design Decision Ref column tracing back to design artifact. AC IDs (AC-1, AC-2…) are stable across revisions — dropped ACs stay with Priority `DROPPED`." },
+        { section: "Edge Cases", required: true, validationRule: "At least one boundary and one error condition per criterion." },
+        { section: "Constraints and Assumptions", required: true, validationRule: "All implicit assumptions surfaced. Constraints have sources." },
+        { section: "Testability Map", required: true, validationRule: "Each criterion maps to a concrete test description with verification approach (unit, integration, e2e, manual) and command or manual steps." },
+        { section: "Vague to Fixed", required: false, validationRule: "If present: table with original vague wording and rewritten observable/testable version for each ambiguous requirement." },
+        { section: "Non-Functional Requirements", required: false, validationRule: "If present: performance thresholds, security constraints, scalability limits, reliability targets with measurable values." },
+        { section: "Interface Contracts", required: false, validationRule: "If present: for each module boundary list produces (outputs) and consumes (inputs) with data types." },
+        { section: "Approval", required: true, validationRule: "Explicit user approval marker present." }
+    ]
+};

package/dist/content/stages/tdd.d.ts

@@ -0,0 +1,2 @@
+import type { StageSchemaInput } from "./schema-types.js";
+export declare const TDD: StageSchemaInput;

package/dist/content/stages/tdd.js

@@ -0,0 +1,184 @@
+// ---------------------------------------------------------------------------
+// TDD — RED → GREEN → REFACTOR cycle (merged test + build)
+// ---------------------------------------------------------------------------
+export const TDD = {
+    stage: "tdd",
+    skillFolder: "test-driven-development",
+    skillName: "test-driven-development",
+    skillDescription: "Full TDD cycle: RED (failing tests), GREEN (minimal implementation), REFACTOR (cleanup). One plan slice at a time with strict traceability.",
+    hardGate: "Do NOT merge, ship, or skip review. Follow RED → GREEN → REFACTOR strictly for each plan slice. Do NOT write implementation code before RED tests exist. Do NOT skip the REFACTOR step.",
+    ironLaw: "NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST — THE RED FAILURE IS THE SPEC.",
+    purpose: "Implement features through the TDD cycle: write failing tests, make them pass with minimal code, then refactor.",
+    whenToUse: [
+        "After plan confirmation",
+        "For every behavior change in scope",
+        "Before review stage"
+    ],
+    whenNotToUse: [
+        "Plan approval is still pending WAIT_FOR_CONFIRM",
+        "The change is docs-only and does not alter behavior",
+        "The stage intent is review/ship sign-off rather than implementation"
+    ],
+    checklist: [
+        "Select plan slice — pick one task from the plan. Do not batch multiple tasks.",
+        "Map to acceptance criterion — identify the specific spec criterion this test proves.",
+        "RED: Write behavior-focused test — test the expected behavior, not implementation details. Tests MUST fail.",
+        "RED: Capture failure output — copy the exact failure output as RED evidence. Record in artifact.",
+        "GREEN: Minimal implementation — write the smallest code change that makes the RED tests pass. No extra features.",
+        "GREEN: Run full suite — execute ALL tests, not just the ones you wrote. The full suite must be GREEN.",
+        "GREEN: Verify no regressions — if any existing test breaks, fix the regression before proceeding.",
+        "REFACTOR: Improve code quality — without changing behavior. Document what you changed and why.",
+        "Record evidence — capture RED failure, GREEN output, and REFACTOR notes in the TDD artifact.",
+        "Annotate traceability — link to plan task ID and spec criterion.",
+        "Repeat for each slice — return to step 1 for the next plan slice."
+    ],
+    interactionProtocol: [
+        "Pick one planned slice at a time.",
+        "Write behavior-focused tests before changing implementation (RED).",
+        "Capture and store failing output as RED evidence.",
+        "Apply minimal change to satisfy RED tests (GREEN).",
+        "Run full suite, not partial checks, for GREEN validation.",
+        "Refactor without changing behavior and document rationale (REFACTOR).",
+        "Stop if regressions appear and fix before proceeding.",
+        "If a test passes unexpectedly, investigate: does the behavior already exist, or is the test wrong?"
+    ],
+    process: [
+        "Select slice and map to acceptance criterion.",
+        "Write test(s) that fail for expected reason (RED).",
+        "Run tests and capture failure output.",
+        "Implement smallest change needed for GREEN.",
+        "Run full tests and build checks.",
+        "Perform refactor pass preserving behavior.",
+        "Record RED, GREEN, and REFACTOR evidence in artifact.",
+        "Annotate traceability to plan task and spec criterion."
+    ],
+    requiredGates: [
+        { id: "tdd_red_test_written", description: "Failing tests exist before implementation changes." },
+        { id: "tdd_red_failure_captured", description: "Failure output is captured as evidence." },
+        { id: "tdd_trace_to_acceptance", description: "RED tests trace to explicit acceptance criteria." },
+        { id: "tdd_red_failure_reason_verified", description: "Failure is for the expected reason, not an unrelated error." },
+        { id: "tdd_green_full_suite", description: "Full relevant suite passes in GREEN state." },
+        { id: "tdd_refactor_completed", description: "Refactor pass completed with behavior preservation verified." },
+        { id: "tdd_refactor_notes_written", description: "Refactor decisions and outcomes are documented." },
+        { id: "tdd_traceable_to_plan", description: "Change traceability to plan slice is explicit." }
+    ],
+    requiredEvidence: [
+        "Artifact updated at `.cclaw/artifacts/06-tdd.md` with RED, GREEN, and REFACTOR sections.",
+        "Failing command output captured (RED).",
+        "Full test/build output recorded (GREEN).",
+        "Acceptance mapping documented.",
+        "Failure reason analysis recorded.",
+        "Refactor rationale captured.",
+        "Traceability to task identifier is documented."
+    ],
+    inputs: ["approved plan slice", "spec acceptance criterion", "test harness configuration", "coding standards and constraints"],
+    requiredContext: ["plan artifact", "spec artifact", "existing test patterns"],
+    outputs: ["failing test set", "passing implementation", "refactor evidence", "review-ready change set"],
+    blockers: [
+        "tests pass before behavior change (RED failure missing)",
+        "full suite not green",
+        "behavior changed during refactor",
+        "no evidence recorded"
+    ],
+    exitCriteria: [
+        "RED evidence exists and is traceable",
+        "GREEN evidence captured with full suite pass",
+        "REFACTOR evidence captured",
+        "required gates marked satisfied",
+        "traceability annotated"
+    ],
+    antiPatterns: [
+        "Writing code before failing test",
+        "Asserting implementation details instead of behavior",
+        "Big-bang implementation across multiple slices",
+        "Partial test runs presented as GREEN",
+        "Skipping evidence capture",
+        "Undocumented refactor changes",
+        "Adding features beyond what RED tests require"
+    ],
+    redFlags: [
+        "No failing test output (RED missing)",
+        "Implementation edits appear before RED evidence",
+        "No full-suite GREEN evidence",
+        "No refactor notes",
+        "Multiple tasks implemented in one pass without justification",
+        "Files changed outside current slice scope"
+    ],
+    policyNeedles: ["RED", "GREEN", "REFACTOR", "failing test", "full test suite", "acceptance criteria", "traceable to plan slice"],
+    artifactFile: "06-tdd.md",
+    next: "review",
+    reviewSections: [
+        {
+            title: "RED Evidence Audit",
+            evaluationPoints: [
+                "Does every slice have a captured failing test output?",
+                "Does each failure reason match the expected missing behavior (not a typo or config error)?",
+                "Were tests written BEFORE any production code for that slice?",
+                "Does each RED test assert observable behavior, not implementation details?",
+                "Is there a test for each acceptance criterion mapped in the plan?"
+            ],
+            stopGate: true
+        },
+        {
+            title: "GREEN/REFACTOR Audit",
+            evaluationPoints: [
+                "Does GREEN evidence show a FULL suite pass (not partial)?",
+                "Is the GREEN implementation minimal — no features beyond what RED tests require?",
+                "Does the REFACTOR step preserve all existing behavior (no new failures)?",
+                "Are REFACTOR notes documented with rationale?",
+                "Is traceability complete: every change links to plan task ID and spec criterion?"
+            ],
+            stopGate: true
+        },
+        {
+            title: "Test Pyramid + Size Audit",
+            evaluationPoints: [
+                "Is the tests-added count skewed toward Small (unit) tests, with Medium and Large used only when a real boundary justifies the cost?",
+                "Does every newly added test declare a size class (Small / Medium / Large) — either inline in the test file or in the TDD artifact table?",
+                "Are Large tests reserved for genuine end-to-end user journeys (not substitutes for unit coverage)?",
+                "Has the slice avoided using Medium/Large tests to paper over testability problems that should be fixed at the design layer?"
+            ],
+            stopGate: false
+        },
+        {
+            title: "Prove-It Reproduction (bug-fix slices)",
+            evaluationPoints: [
+                "Does the artifact identify this slice as a bug fix, and if so, include a reproduction test checked in alongside the fix?",
+                "Is there captured RED evidence from running the reproduction WITHOUT the fix applied?",
+                "Is there captured GREEN evidence from the same reproduction AFTER the fix was applied?",
+                "Is there a note confirming the reproduction test fails again if the fix is reverted (or equivalent evidence that the test is actually pinned to this fix)?"
+            ],
+            stopGate: false
+        },
+        {
+            title: "State-over-Interaction + Beyoncé Coverage",
+            evaluationPoints: [
+                "Do assertions target observable state (return values, persisted data, HTTP responses, logs) rather than which internal helpers were called?",
+                "Are mocks/spies used only at true trust boundaries (network, filesystem, time, external services), not for module-internal collaborators?",
+                "For every public surface touched in this slice (exported API, CLI flag, config key, env var, exit code, schema field) — does at least one test observe it?",
+                "If a bug or review finding revealed an uncovered surface, was a test added alongside the fix, not just the code change?",
+                "Are interaction-style assertions (e.g. `toHaveBeenCalledWith` without a state assertion) justified by an explicit boundary comment, or flagged for follow-up?"
+            ],
+            stopGate: false
+        }
+    ],
+    completionStatus: ["DONE", "DONE_WITH_CONCERNS", "BLOCKED"],
+    crossStageTrace: {
+        readsFrom: [".cclaw/artifacts/05-plan.md", ".cclaw/artifacts/04-spec.md", ".cclaw/artifacts/03-design.md"],
+        writesTo: [".cclaw/artifacts/06-tdd.md"],
+        traceabilityRule: "Every RED test traces to a plan task. Every GREEN change traces to a RED test. Every plan task traces to a spec criterion. Design decisions inform test strategy. Evidence chain must be unbroken."
+    },
+    artifactValidation: [
+        { section: "RED Evidence", required: true, validationRule: "Failing test output captured per slice." },
+        { section: "Acceptance Mapping", required: true, validationRule: "Each RED test links to a plan task and spec criterion." },
+        { section: "Failure Analysis", required: true, validationRule: "Failure reason matches expected missing behavior." },
+        { section: "GREEN Evidence", required: true, validationRule: "Full suite pass output captured." },
+        { section: "REFACTOR Notes", required: true, validationRule: "What changed, why, behavior preservation confirmed." },
+        { section: "Traceability", required: true, validationRule: "Plan task ID and spec criterion linked." },
+        { section: "Verification Ladder", required: false, validationRule: "If present: per-slice verification tier (static, command, behavioral, human) with evidence for highest tier reached." },
+        { section: "Coverage Targets", required: false, validationRule: "If present: per-module or per-code-type coverage thresholds with current values and measurement commands." },
+        { section: "Test Pyramid Shape", required: false, validationRule: "If present: per-slice count of Small/Medium/Large tests added, to let reviewers verify the suite is not drifting top-heavy." },
+        { section: "Prove-It Reproduction", required: false, validationRule: "Required for bug-fix slices: original failing reproduction test (RED without fix), passing output with fix (GREEN), and a note confirming the test fails again if the fix is reverted." }
+    ],
+    waveExecutionAllowed: true
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cclaw-cli",
-  "version": "0.15.0",
+  "version": "0.15.1",
   "description": "Installer-first flow toolkit for coding agents",
   "type": "module",
   "bin": {