cclaw-cli 7.7.1 → 8.1.1

package/dist/content/stages/ship.js

@@ -1,159 +0,0 @@
-import { decisionProtocolInstruction } from "../decision-protocol.js";
-// ---------------------------------------------------------------------------
-// SHIP — reference: superpowers finishing-a-development-branch + gstack /ship
-// ---------------------------------------------------------------------------
-export const SHIP = {
-    schemaShape: "v2",
-    stage: "ship",
-    complexityTier: "standard",
-    skillFolder: "ship",
-    skillName: "ship",
-    skillDescription: "Release handoff stage with preflight checks, rollback readiness, and explicit finalization mode for both git and non-git workflows.",
-    philosophy: {
-        hardGate: "Do NOT merge, push, or finalize without a passed preflight check, written rollback plan, and exactly one explicit finalization mode selected. No exceptions for urgency. If no VCS is available, use FINALIZE_NO_VCS explicitly instead of inventing git steps.",
-        ironLaw: "NO MERGE WITHOUT GREEN CI, A WRITTEN ROLLBACK, AND EXACTLY ONE SELECTED FINALIZATION MODE.",
-        purpose: "Prepare a safe release handoff with clear rollback and branch finalization decision.",
-        whenToUse: [
-            "After review passes with APPROVED or APPROVED_WITH_CONCERNS verdict",
-            "Before creating PR/merge/final branch action",
-            "When release notes and rollback plan are required",
-            "When shipping from non-git environments (docs bundles, script drops, detached artifacts)"
-        ],
-        whenNotToUse: [
-            "Review verdict is BLOCKED or unresolved critical findings remain",
-            "Preflight checks cannot run and no approved exception exists",
-            "The request is still design/spec/implementation work, not release handoff"
-        ],
-        commonRationalizations: [
-            "Shipping without rollback strategy",
-            "Implicit finalization decision",
-            "Bypassing preflight due to urgency",
-            "Selecting multiple finalization modes",
-            "Shipping with BLOCKED review verdict",
-            "No rollback trigger/steps",
-            "More than one finalization mode implied",
-            "No explicit preflight result",
-            "Review verdict not referenced",
-            "Finalization not executed, only planned",
-            "Selecting git-dependent finalization mode when `.git` is unavailable"
-        ]
-    },
-    executionModel: {
-        checklist: [
-            "Validate upstream gates — verify review verdict is APPROVED or APPROVED_WITH_CONCERNS. If BLOCKED, stop immediately.",
-            "Run preflight checks — tests pass, build succeeds, linter clean, type-check clean, no uncommitted changes. Every check must produce fresh output in this message.",
-            "Merge-base detection (git only) — identify the correct base branch. Run `git merge-base HEAD <base>`. If the base has diverged significantly, flag for rebase-first.",
-            "Re-run tests on merged result — if merging locally, run the full test suite AFTER the merge, not just before. Post-merge failures are common.",
-            "Generate release notes — summarize what changed, why, and what it affects. Reference spec criteria. Include: breaking changes, new dependencies, migration steps if any.",
-            "Assemble acceptance traceability matrix — for each spec AC-N, list mapped slice IDs and at least one managed commit proving closure.",
-            "Write rollback plan — trigger conditions (what tells you it is broken), rollback steps (exact commands/git operations), and verification (how to confirm rollback worked).",
-            "Load utility skills — `verification-before-completion` for fresh evidence and `finishing-a-development-branch` for finalization workflow.",
-            "Monitoring checklist — what should be watched after deploy? Error rates, latency, key business metrics. If no monitoring exists, flag it as a risk.",
-            "Detect repository mode — if `.git/` is absent or inaccessible, lock finalization choices to FINALIZE_NO_VCS only and document manual handoff + rollback.",
-            "Victory Detector — valid review verdict, fresh preflight, rollback trigger/steps, exactly one finalization enum, and execution target are present; if any field is stale or missing, keep status BLOCKED and iterate.",
-            "Select finalization mode — exactly ONE enum: (A) FINALIZE_MERGE_LOCAL, (B) FINALIZE_OPEN_PR, (C) FINALIZE_KEEP_BRANCH, (D) FINALIZE_DISCARD_BRANCH, (E) FINALIZE_NO_VCS. For discard: list what will be deleted, require typed confirmation.",
-            "Execute finalization — perform the selected action. For merge: verify clean merge. For PR: include structured body (summary, test plan, rollback). For discard: verify deletion. For NO_VCS: record handoff target, artifact bundle path, and manual rollback owner.",
-            "Branch cleanup — after merge/discard, remove only branches or temporary files the user explicitly approved. Skip for FINALIZE_NO_VCS."
-        ],
-        interactionProtocol: [
-            "Run preflight checks before any release action.",
-            "Document release notes and rollback plan explicitly.",
-            decisionProtocolInstruction("finalization mode", "present modes as labeled options (A/B/C/D/E) with consequences, and mark one as (recommended)", "recommend the mode that best addresses release blast-radius, rollback readiness, observability, and stakeholder communication — ties go to the most reversible option"),
-            "Do not proceed if critical blockers remain from review.",
-            "**STOP.** Present finalization options and wait for user selection before executing any finalization action.",
-            "Behavior anchor: see the shared `## Behavior anchor` block in this skill — the bad/good pair anchors that `Preflight Results` cite fresh command output, exit codes, and the commit SHA from this turn."
-        ],
-        process: [
-            "Validate review and test gates.",
-            "Run preflight: build, test, lint, uncommitted-changes check.",
-            "Generate release notes and rollback procedure.",
-            "Choose one finalization enum: FINALIZE_MERGE_LOCAL, FINALIZE_OPEN_PR, FINALIZE_KEEP_BRANCH, FINALIZE_DISCARD_BRANCH, or FINALIZE_NO_VCS.",
-            "Execute finalization action.",
-            "Write ship artifact with decision, rationale, and execution result."
-        ],
-        requiredGates: [
-            { id: "ship_review_verdict_valid", description: "Review verdict is APPROVED or APPROVED_WITH_CONCERNS." },
-            { id: "ship_preflight_passed", description: "Preflight checks passed or exceptions documented and approved." },
-            { id: "ship_rollback_plan_ready", description: "Rollback trigger, steps, and verification are documented." },
-            { id: "ship_all_acceptance_criteria_have_commits", description: "Every spec AC-N has at least one `Closes: AC-N` slice mapping and a managed slice commit in the active run." },
-            { id: "ship_finalization_executed", description: "Selected finalization action was executed and verified." }
-        ],
-        requiredEvidence: [
-            "Artifact written to `.cclaw/artifacts/08-ship.md`.",
-            "Release notes section is complete.",
-            "Traceability Matrix maps each spec AC-N to slice IDs and managed commit evidence.",
-            "Rollback section includes trigger conditions, steps, and verification.",
-            "Finalization section shows exactly one selected enum token.",
-            "Victory Detector result documented: review verdict valid, preflight fresh, rollback ready, finalization enum selected, and execution result present."
-        ],
-        inputs: ["review verdict", "test/build outputs", "release context"],
-        requiredContext: ["review artifact", "changelog scope", "deployment constraints"],
-        blockers: [
-            "review verdict is BLOCKED",
-            "critical review blockers remain",
-            "rollback plan missing",
-            "finalization mode not selected"
-        ],
-        exitCriteria: [
-            "preflight completed",
-            "rollback and release notes complete",
-            "finalization action explicitly chosen and executed"
-        ],
-        platformNotes: [
-            "Release commands (`npm publish`, `git tag -s`, `gh release create`, `cargo publish`, `goreleaser`) behave the same across OSes, but signing keys differ: macOS Keychain, Windows credential store, Linux GPG agent. Verify the signing flow on the actual release machine before running the real publish.",
-            "Version tags must be pure ASCII and lowercase after an optional `v` prefix (`v1.2.3`, `v1.2.3-rc.1`). Avoid Unicode dashes and non-breaking spaces that sneak in via copy-paste from docs.",
-            "When the rollback plan references timestamps (CI run windows, DB snapshot IDs), pin them to UTC ISO-8601 so the plan reads identically across CI runners in different regions.",
-            "`gh release create` requires a repo-level `GH_TOKEN`/`GITHUB_TOKEN`; document whether it is sourced from the shell env, `.env`, or the OS keychain so another operator on a different OS can reproduce the release."
-        ]
-    },
-    artifactRules: {
-        artifactFile: "08-ship.md",
-        completionStatus: ["SHIPPED", "SHIPPED_WITH_EXCEPTIONS", "BLOCKED"],
-        crossStageTrace: {
-            readsFrom: [".cclaw/artifacts/07-review.md", ".cclaw/artifacts/06-tdd.md", ".cclaw/artifacts/05-plan.md", ".cclaw/artifacts/04-spec.md"],
-            writesTo: [".cclaw/artifacts/08-ship.md"],
-            traceabilityRule: "Ship artifact must reference review verdict and resolution status. Release notes must reference spec criteria. Rollback plan must reference specific changes that could fail."
-        },
-        artifactValidation: [
-            { section: "Upstream Handoff", required: false, validationRule: "Summarizes review/tdd decisions, constraints, open questions, and explicit drift before finalization." },
-            { section: "Preflight Results", required: true, validationRule: "Build, test, lint, type-check results captured with fresh output. Exceptions documented if any." },
-            { section: "Release Notes", required: true, validationRule: "What changed, why, impact. References spec criteria. Breaking changes flagged." },
-            { section: "Traceability Matrix", required: true, validationRule: "One row per spec AC-N with mapped slice IDs (`S-<id>`), managed commit evidence (`^S-<id>/` subject), and coverage status." },
-            { section: "Rollback Plan", required: true, validationRule: "Trigger conditions, rollback steps (exact commands), verification steps." },
-            { section: "Monitoring", required: false, validationRule: "If applicable: what metrics/logs to watch post-deploy. Risk note if no monitoring." },
-            { section: "Finalization", required: true, validationRule: "Exactly one finalization enum token selected (FINALIZE_MERGE_LOCAL | FINALIZE_OPEN_PR | FINALIZE_KEEP_BRANCH | FINALIZE_DISCARD_BRANCH | FINALIZE_NO_VCS). Execution result documented. Worktree cleaned if applicable." },
-            { section: "Completion Status", required: false, validationRule: "If present: exactly one of SHIPPED, SHIPPED_WITH_EXCEPTIONS, BLOCKED. Exceptions documented when applicable. BLOCKED is required when the Victory Detector has stale or missing evidence." },
-            { section: "Compound Step", required: false, validationRule: "Optional retrospective: include overlap assessment before appending duplicate knowledge; distinguish bug-track fixes/tests from knowledge-track process/project guidance; or include an explicit 'No compound insight this run.' line." }
-        ]
-    },
-    reviewLens: {
-        outputs: ["release package handoff", "rollback plan", "final branch decision"],
-        reviewSections: [
-            {
-                title: "Preflight Verification",
-                evaluationPoints: [
-                    "Test suite: full run, all pass, output captured",
-                    "Build: clean build, exit code 0",
-                    "Lint/format: no violations",
-                    "Type-check: no errors",
-                    "Working tree: no uncommitted changes"
-                ],
-                stopGate: true
-            },
-            {
-                title: "Release Readiness",
-                evaluationPoints: [
-                    "Release notes are accurate and reference spec criteria",
-                    "Breaking changes are documented with migration steps",
-                    "Rollback plan has trigger, steps, and verification",
-                    "If applicable: monitoring/alerting is in place for the change"
-                ],
-                stopGate: true
-            }
-        ]
-    },
-    // `done` exits the stage pipeline. Archive semantics are handled by the
-    // closeout substate machine (`idle` -> ... -> `archived`) in flow-state under
-    // ${closeoutSubstateInline()}.
-    next: "done",
-};

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

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

package/dist/content/stages/spec.js

@@ -1,170 +0,0 @@
-// ---------------------------------------------------------------------------
-// SPEC
-// ---------------------------------------------------------------------------
-export const SPEC = {
-    schemaShape: "v2",
-    stage: "spec",
-    complexityTier: "standard",
-    skillFolder: "spec",
-    skillName: "spec",
-    skillDescription: "Specification stage. Produce measurable, testable requirements without ambiguity.",
-    philosophy: {
-        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"
-        ],
-        commonRationalizations: [
-            "High-level goals without measurable outcomes",
-            "Implicit assumptions",
-            "Proceeding to plan before approval",
-            "Using vague adjectives (fast, intuitive, robust) without thresholds",
-            "No explicit assumptions section",
-            "No approval record",
-            "No testability mapping",
-            "Assumptions not surfaced before sign-off",
-            "Edge cases missing or deferred"
-        ]
-    },
-    executionModel: {
-        checklist: [
-            "Read upstream — standard track loads design + scope; medium loads brainstorm/spec handoff; quick loads `00-idea.md` plus any reproduction context. Cross-reference only artifacts that exist on the active track.",
-            "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.",
-            "**Constraints carry-forward (do NOT re-author).** Scope OWNS external/regulatory/system/integration constraints in `## Scope Contract > Constraints`. Cite them in `## Constraints and Assumptions > Constraints` (or mark `See scope: <ref>`). Add a constraint here only when spec-stage analysis surfaced a NEW one not present in scope. Spec OWNS testable assumptions (next bullet). Only non-critical preference/default assumptions may continue; STOP on uncertainty about scope, architecture, security, data loss, public API, migration, auth/pricing, or required user approval.",
-            "**Assumptions Before Finalization (spec-only owner).** Spec OWNS testable assumptions: list each with source/confidence, validation path, and accepted/rejected/open disposition in `## Assumptions Before Finalization`. Do NOT duplicate scope's constraints here as assumptions.",
-            "Build the Acceptance Mapping contract — for each AC, map upstream design decision, observable evidence, verification method, and likely test level. If any column is unclear, rewrite the criterion.",
-            "Run Spec Self-Review — explicitly verify placeholder/consistency/scope/ambiguity checks before approval.",
-            "Present acceptance criteria to the user in 3-5-item batches, pausing for explicit ACK between batches (see Interaction Protocol).",
-            "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.",
-            "Before final spec approval, present the assumptions section as its own checkpoint so the user can accept, revise, or mark an assumption unknown.",
-            "**Chunk acceptance criteria for review.** When presenting the spec to the user for sign-off, deliver acceptance criteria in batches of 3-5 and **pause for explicit ACK** (via Decision Protocol) before sending the next batch. Do not dump the full criteria wall in one message — small batches surface objections earlier and keep the sign-off meaningful. Full spec writeup still lands in `04-spec.md`, but the conversation itself must be digestible.",
-            "Require user confirmation on the written spec. **STOP.** Do NOT proceed to plan until user approves.",
-            "For each criterion, ask: what exact evidence proves this passed? If the evidence or verification command/manual step is vague, rewrite.",
-            "When encountering ambiguity, classify it before acting: (A) ask user for missing info, (B) enumerate non-critical interpretations and pick one with justification, (C) propose hypothesis with validation path. Do NOT silently resolve ambiguity. STOP on scope, architecture, security, data loss, public API, migration, auth/pricing, or user-approval uncertainty.",
-            "Investigation discipline: follow the shared `## Investigation Discipline` block — derive ACs from cited upstream paths/refs (`02-scope.md#R-2`, `03-design.md#DD-1`) instead of pasting their bodies into delegation prompts.",
-            "Behavior anchor: see the shared `## Behavior anchor` block in this skill — the bad/good pair anchors how each `Acceptance Criteria` row must carry an observable predicate plus the evidence path."
-        ],
-        process: [
-            "Define measurable acceptance criteria.",
-            "Capture constraints, assumptions, and edge cases.",
-            "Review assumptions before finalization: source/confidence, validation path, and accepted/rejected/open disposition.",
-            "Annotate parallel-slice metadata on each acceptance criterion: `parallelSafe` (true|false) and `touchSurface` (repo-relative paths/modules expected to change) so downstream plan units and TDD lanes stay conflict-aware.",
-            "Confirm every verification method is concrete enough for plan/TDD to use later.",
-            "Present acceptance criteria to the user in 3-5-item batches, pausing for explicit ACK between batches (see Interaction Protocol).",
-            "Write spec artifact and request approval."
-        ],
-        requiredGates: [
-            { id: "spec_ac_ids_present", description: "Acceptance Criteria rows include stable `AC-N` identifiers." },
-            { id: "spec_acceptance_measurable", description: "Acceptance criteria are measurable and observable." },
-            { id: "spec_testability_confirmed", description: "Each criterion has a described test method." },
-            { id: "spec_assumptions_surfaced", description: "Assumptions were explicitly reviewed with source/confidence, validation path, and disposition before approval." },
-            { id: "spec_self_review_complete", description: "Spec Self-Review covers placeholder, consistency, scope, and ambiguity checks before approval." },
-            { 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 upstream design decision, observable evidence, verification method, and likely test level.",
-            "Edge cases documented per criterion.",
-            "Assumptions Before Finalization section records source/confidence, validation path, and accepted/rejected/open disposition.",
-            "Spec Self-Review section covers placeholder, consistency, scope, and ambiguity checks with any patches noted.",
-            "Approval marker captured in artifact.",
-            "For quick bug-fix specs, reproduction contract records symptom, repro steps, expected RED test, and acceptance criterion."
-        ],
-        inputs: ["design artifact", "business constraints", "quality requirements"],
-        requiredContext: [
-            "design lock baseline",
-            "regulatory or system boundaries",
-            "integration constraints"
-        ],
-        blockers: [
-            "non-measurable criteria",
-            "constraints missing",
-            "assumptions not surfaced before approval",
-            "open ambiguities remain"
-        ],
-        exitCriteria: [
-            "spec approved by user",
-            "required gates marked satisfied",
-            "plan-ready acceptance mapping exists",
-            "assumptions reviewed before finalization",
-            "testability confirmed for all criteria"
-        ],
-        platformNotes: [
-            "Acceptance criteria that reference CLI commands must name the executable portably (`node`, `npm`, `pytest`) and avoid OS-specific shell features (`&&` is safe, `||` differs subtly between cmd.exe and POSIX — prefer explicit multi-step descriptions).",
-            "When a criterion specifies file-content expectations, use `LF` as the canonical newline and state any CRLF-on-Windows tolerance explicitly (most git-managed repos normalize via `.gitattributes`; the criterion should not implicitly depend on autocrlf).",
-            "Timezone-sensitive criteria (timestamps, retention windows) must pin UTC or note the source of truth — clocks differ across CI runners (GitHub macOS vs Linux image vs Windows image)."
-        ]
-    },
-    artifactRules: {
-        artifactFile: "04-spec.md",
-        completionStatus: ["DONE", "DONE_WITH_CONCERNS", "BLOCKED"],
-        crossStageTrace: {
-            readsFrom: [".cclaw/artifacts/03-design-<slug>.md", ".cclaw/artifacts/02-scope-<slug>.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: "Upstream Handoff", required: false, validationRule: "Summarizes scope/design decisions, constraints, open questions, and explicit drift before acceptance criteria." },
-            { section: "Acceptance Criteria", required: true, validationRule: "Each criterion is observable, measurable, and falsifiable. Standard track should include Requirement Ref and Design Decision Ref columns; quick track may instead link each AC to the reproduction contract or bug slice. AC IDs (AC-1, AC-2…) are stable across revisions — dropped ACs stay with Priority `DROPPED`. each AC declares `parallelSafe` (true|false) and `touchSurface` (paths/modules) for parallel slice planning." },
-            { section: "Quick Reproduction Contract", required: false, validationRule: "Quick bug-fix specs own the reproduction contract: symptom, repro steps, expected RED test behavior, and acceptance criterion." },
-            { section: "Edge Cases", required: true, validationRule: "At least one boundary and one error condition per criterion." },
-            { section: "Constraints and Assumptions", required: false, validationRule: "Constraints are CARRIED FORWARD from scope's `## Scope Contract > Constraints` (cite with `See scope: <ref>` or copy with attribution). New spec-stage constraints (rare) get a citation to the spec-stage Q&A row that surfaced them. Assumptions are owned by `## Assumptions Before Finalization` — do NOT duplicate them here. Section may be `- See scope: 02-scope.md#constraints.` for the common case." },
-            { section: "Assumptions Before Finalization", required: true, validationRule: "Each assumption has source/confidence, validation path, and accepted/rejected/open disposition before the Approval section is finalized." },
-            { section: "Acceptance Mapping", required: true, validationRule: "Each criterion maps to upstream design decision, observable evidence, verification method, likely test level (unit/integration/e2e/manual), and command or manual steps when known." },
-            { 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: "Synthesis Sources", required: false, validationRule: "If present: cite at least one upstream/context source with what it supplied and confidence." },
-            { section: "Behavior Contract", required: false, validationRule: "If present: list >=3 behaviors in user-story or Given/When/Then shape (or `- None.` for single-step specs)." },
-            { section: "Architecture Modules", required: false, validationRule: "If present: module responsibilities only (no code fences or function/class signatures); keep module count within a single coherent subsystem." },
-            { section: "Spec Self-Review", required: true, validationRule: "Must explicitly cover placeholder, consistency, scope, and ambiguity checks plus applied patches/remaining concerns." },
-            { section: "Approval", required: true, validationRule: "Explicit user approval marker present." }
-        ]
-    },
-    reviewLens: {
-        outputs: [
-            "measurable specification",
-            "acceptance-to-testability map",
-            "approved spec artifact"
-        ],
-        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 row in Acceptance Mapping?",
-                    "Does every test specify a verification approach (unit, integration, e2e, manual)?",
-                    "Does every verification method include a runnable command or concrete manual steps when known?",
-                    "Were assumptions surfaced before finalization with source/confidence, validation path, and disposition?",
-                    "Are edge cases (boundary + error) defined for every criterion?",
-                    "Are commands specific enough to run later (not vague `run tests` wording)?"
-                ],
-                stopGate: true
-            }
-        ]
-    },
-    next: "plan",
-};

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

@@ -1,4 +0,0 @@
-import type { StageSchemaInput, StageSchemaV2Input } from "./schema-types.js";
-import type { FlowTrack } from "../../types.js";
-export declare const TDD: StageSchemaV2Input;
-export declare function tddStageForTrack(track: FlowTrack): StageSchemaInput;