cclaw-cli 0.48.28 → 0.48.30
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/artifact-linter.js +16 -5
- package/dist/artifact-paths.d.ts +28 -0
- package/dist/artifact-paths.js +261 -0
- package/dist/content/stage-schema.js +26 -11
- package/dist/content/stages/brainstorm.js +5 -5
- package/dist/content/stages/design.js +5 -5
- package/dist/content/stages/plan.js +153 -143
- package/dist/content/stages/review.js +212 -202
- package/dist/content/stages/scope.js +4 -4
- package/dist/content/stages/ship.js +132 -122
- package/dist/content/stages/spec.js +131 -121
- package/dist/content/stages/tdd.d.ts +2 -2
- package/dist/content/stages/tdd.js +237 -214
- package/dist/gate-evidence.js +7 -17
- package/dist/internal/advance-stage.js +9 -3
- package/package.json +1 -1
|
@@ -2,133 +2,143 @@
|
|
|
2
2
|
// SHIP — reference: superpowers finishing-a-development-branch + gstack /ship
|
|
3
3
|
// ---------------------------------------------------------------------------
|
|
4
4
|
export const SHIP = {
|
|
5
|
+
schemaShape: "v2",
|
|
5
6
|
stage: "ship",
|
|
7
|
+
complexityTier: "standard",
|
|
6
8
|
skillFolder: "shipping-and-handoff",
|
|
7
9
|
skillName: "shipping-and-handoff",
|
|
8
10
|
skillDescription: "Release handoff stage with preflight checks, rollback readiness, and explicit finalization mode for both git and non-git workflows.",
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
"
|
|
82
|
-
"
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
11
|
+
philosophy: {
|
|
12
|
+
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.",
|
|
13
|
+
ironLaw: "NO MERGE WITHOUT GREEN CI, A WRITTEN ROLLBACK, AND EXACTLY ONE SELECTED FINALIZATION MODE.",
|
|
14
|
+
purpose: "Prepare a safe release handoff with clear rollback and branch finalization decision.",
|
|
15
|
+
whenToUse: [
|
|
16
|
+
"After review passes with APPROVED or APPROVED_WITH_CONCERNS verdict",
|
|
17
|
+
"Before creating PR/merge/final branch action",
|
|
18
|
+
"When release notes and rollback plan are required",
|
|
19
|
+
"When shipping from non-git environments (docs bundles, script drops, detached artifacts)"
|
|
20
|
+
],
|
|
21
|
+
whenNotToUse: [
|
|
22
|
+
"Review verdict is BLOCKED or unresolved critical findings remain",
|
|
23
|
+
"Preflight checks cannot run and no approved exception exists",
|
|
24
|
+
"The request is still design/spec/implementation work, not release handoff"
|
|
25
|
+
],
|
|
26
|
+
commonRationalizations: [
|
|
27
|
+
"Shipping without rollback strategy",
|
|
28
|
+
"Implicit finalization decision",
|
|
29
|
+
"Bypassing preflight due to urgency",
|
|
30
|
+
"Selecting multiple finalization modes",
|
|
31
|
+
"Shipping with BLOCKED review verdict",
|
|
32
|
+
"No rollback trigger/steps",
|
|
33
|
+
"More than one finalization mode implied",
|
|
34
|
+
"No explicit preflight result",
|
|
35
|
+
"Review verdict not referenced",
|
|
36
|
+
"Finalization not executed, only planned",
|
|
37
|
+
"Selecting git-dependent finalization mode when `.git` is unavailable"
|
|
38
|
+
]
|
|
39
|
+
},
|
|
40
|
+
executionModel: {
|
|
41
|
+
checklist: [
|
|
42
|
+
"Validate upstream gates — verify review verdict is APPROVED or APPROVED_WITH_CONCERNS. If BLOCKED, stop immediately.",
|
|
43
|
+
"Run preflight checks — tests pass, build succeeds, linter clean, type-check clean, no uncommitted changes. Every check must produce fresh output in this message.",
|
|
44
|
+
"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.",
|
|
45
|
+
"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.",
|
|
46
|
+
"Generate release notes — summarize what changed, why, and what it affects. Reference spec criteria. Include: breaking changes, new dependencies, migration steps if any.",
|
|
47
|
+
"Write rollback plan — trigger conditions (what tells you it is broken), rollback steps (exact commands/git operations), and verification (how to confirm rollback worked).",
|
|
48
|
+
"Load utility skills — `verification-before-completion` for fresh evidence and `finishing-a-development-branch` for finalization workflow.",
|
|
49
|
+
"Monitoring checklist — what should be watched after deploy? Error rates, latency, key business metrics. If no monitoring exists, flag it as a risk.",
|
|
50
|
+
"Detect repository mode — if `.git/` is absent or inaccessible, lock finalization choices to FINALIZE_NO_VCS only and document manual handoff + rollback.",
|
|
51
|
+
"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.",
|
|
52
|
+
"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.",
|
|
53
|
+
"Worktree cleanup — if using git worktrees, clean up the worktree after merge/discard. Keep it only for 'keep branch' mode. Skip for FINALIZE_NO_VCS."
|
|
54
|
+
],
|
|
55
|
+
interactionProtocol: [
|
|
56
|
+
"Run preflight checks before any release action.",
|
|
57
|
+
"Document release notes and rollback plan explicitly.",
|
|
58
|
+
"For finalization mode: use the Decision Protocol — present modes as labeled options (A/B/C/D/E) with consequences, and mark one as (recommended). Do NOT use a numeric Completeness rubric; recommend the mode that best addresses release blast-radius, rollback readiness, observability, and stakeholder communication — ties go to the most reversible option. If the harness's native structured-ask tool is available (`AskUserQuestion` / `AskQuestion` / `question` / `request_user_input`), send exactly ONE question per call, validate fields against the runtime schema, and on schema error immediately fall back to a plain-text lettered list instead of retrying guessed payloads.",
|
|
59
|
+
"Do not proceed if critical blockers remain from review.",
|
|
60
|
+
"**STOP.** Present finalization options and wait for user selection before executing any finalization action."
|
|
61
|
+
],
|
|
62
|
+
process: [
|
|
63
|
+
"Validate review and test gates.",
|
|
64
|
+
"Run preflight: build, test, lint, uncommitted-changes check.",
|
|
65
|
+
"Generate release notes and rollback procedure.",
|
|
66
|
+
"Choose one finalization enum: FINALIZE_MERGE_LOCAL, FINALIZE_OPEN_PR, FINALIZE_KEEP_BRANCH, FINALIZE_DISCARD_BRANCH, or FINALIZE_NO_VCS.",
|
|
67
|
+
"Execute finalization action.",
|
|
68
|
+
"Write ship artifact with decision, rationale, and execution result."
|
|
69
|
+
],
|
|
70
|
+
requiredGates: [
|
|
71
|
+
{ id: "ship_review_verdict_valid", description: "Review verdict is APPROVED or APPROVED_WITH_CONCERNS." },
|
|
72
|
+
{ id: "ship_preflight_passed", description: "Preflight checks passed or exceptions documented and approved." },
|
|
73
|
+
{ id: "ship_rollback_plan_ready", description: "Rollback trigger, steps, and verification are documented." },
|
|
74
|
+
{ id: "ship_finalization_executed", description: "Selected finalization action was executed and verified." }
|
|
75
|
+
],
|
|
76
|
+
requiredEvidence: [
|
|
77
|
+
"Artifact written to `.cclaw/artifacts/08-ship.md`.",
|
|
78
|
+
"Release notes section is complete.",
|
|
79
|
+
"Rollback section includes trigger conditions, steps, and verification.",
|
|
80
|
+
"Finalization section shows exactly one selected enum token.",
|
|
81
|
+
"Execution result documented."
|
|
82
|
+
],
|
|
83
|
+
inputs: ["review verdict", "test/build outputs", "release context"],
|
|
84
|
+
requiredContext: ["review artifact", "changelog scope", "deployment constraints"],
|
|
85
|
+
blockers: [
|
|
86
|
+
"review verdict is BLOCKED",
|
|
87
|
+
"critical review blockers remain",
|
|
88
|
+
"rollback plan missing",
|
|
89
|
+
"finalization mode not selected"
|
|
90
|
+
],
|
|
91
|
+
exitCriteria: [
|
|
92
|
+
"preflight completed",
|
|
93
|
+
"rollback and release notes complete",
|
|
94
|
+
"finalization action explicitly chosen and executed"
|
|
95
|
+
]
|
|
96
|
+
},
|
|
97
|
+
artifactRules: {
|
|
98
|
+
artifactFile: "08-ship.md",
|
|
99
|
+
completionStatus: ["SHIPPED", "SHIPPED_WITH_EXCEPTIONS", "BLOCKED"],
|
|
100
|
+
crossStageTrace: {
|
|
101
|
+
readsFrom: [".cclaw/artifacts/07-review.md", ".cclaw/artifacts/06-tdd.md", ".cclaw/artifacts/05-plan.md", ".cclaw/artifacts/04-spec.md"],
|
|
102
|
+
writesTo: [".cclaw/artifacts/08-ship.md"],
|
|
103
|
+
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."
|
|
104
|
+
},
|
|
105
|
+
artifactValidation: [
|
|
106
|
+
{ section: "Preflight Results", required: true, validationRule: "Build, test, lint, type-check results captured with fresh output. Exceptions documented if any." },
|
|
107
|
+
{ section: "Release Notes", required: true, validationRule: "What changed, why, impact. References spec criteria. Breaking changes flagged." },
|
|
108
|
+
{ section: "Rollback Plan", required: true, validationRule: "Trigger conditions, rollback steps (exact commands), verification steps." },
|
|
109
|
+
{ section: "Monitoring", required: false, validationRule: "If applicable: what metrics/logs to watch post-deploy. Risk note if no monitoring." },
|
|
110
|
+
{ 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." },
|
|
111
|
+
{ section: "Completion Status", required: false, validationRule: "If present: exactly one of SHIPPED, SHIPPED_WITH_EXCEPTIONS, BLOCKED. Exceptions documented when applicable." },
|
|
112
|
+
{ section: "Compound Step", required: false, validationRule: "Optional retrospective: at least one bullet of the form 'Insight: ... | Action: append [compound] entry to .cclaw/knowledge.jsonl', or an explicit 'No compound insight this run.' line." }
|
|
113
|
+
]
|
|
114
|
+
},
|
|
115
|
+
reviewLens: {
|
|
116
|
+
outputs: ["release package handoff", "rollback plan", "final branch decision"],
|
|
117
|
+
reviewSections: [
|
|
118
|
+
{
|
|
119
|
+
title: "Preflight Verification",
|
|
120
|
+
evaluationPoints: [
|
|
121
|
+
"Test suite: full run, all pass, output captured",
|
|
122
|
+
"Build: clean build, exit code 0",
|
|
123
|
+
"Lint/format: no violations",
|
|
124
|
+
"Type-check: no errors",
|
|
125
|
+
"Working tree: no uncommitted changes"
|
|
126
|
+
],
|
|
127
|
+
stopGate: true
|
|
128
|
+
},
|
|
129
|
+
{
|
|
130
|
+
title: "Release Readiness",
|
|
131
|
+
evaluationPoints: [
|
|
132
|
+
"Release notes are accurate and reference spec criteria",
|
|
133
|
+
"Breaking changes are documented with migration steps",
|
|
134
|
+
"Rollback plan has trigger, steps, and verification",
|
|
135
|
+
"If applicable: monitoring/alerting is in place for the change"
|
|
136
|
+
],
|
|
137
|
+
stopGate: true
|
|
138
|
+
}
|
|
139
|
+
]
|
|
140
|
+
},
|
|
93
141
|
// `done` exits the stage pipeline. Archive semantics are handled by the
|
|
94
142
|
// closeout substate machine (`idle` -> ... -> `archived`) in flow-state.
|
|
95
143
|
next: "done",
|
|
96
|
-
reviewSections: [
|
|
97
|
-
{
|
|
98
|
-
title: "Preflight Verification",
|
|
99
|
-
evaluationPoints: [
|
|
100
|
-
"Test suite: full run, all pass, output captured",
|
|
101
|
-
"Build: clean build, exit code 0",
|
|
102
|
-
"Lint/format: no violations",
|
|
103
|
-
"Type-check: no errors",
|
|
104
|
-
"Working tree: no uncommitted changes"
|
|
105
|
-
],
|
|
106
|
-
stopGate: true
|
|
107
|
-
},
|
|
108
|
-
{
|
|
109
|
-
title: "Release Readiness",
|
|
110
|
-
evaluationPoints: [
|
|
111
|
-
"Release notes are accurate and reference spec criteria",
|
|
112
|
-
"Breaking changes are documented with migration steps",
|
|
113
|
-
"Rollback plan has trigger, steps, and verification",
|
|
114
|
-
"If applicable: monitoring/alerting is in place for the change"
|
|
115
|
-
],
|
|
116
|
-
stopGate: true
|
|
117
|
-
}
|
|
118
|
-
],
|
|
119
|
-
completionStatus: ["SHIPPED", "SHIPPED_WITH_EXCEPTIONS", "BLOCKED"],
|
|
120
|
-
crossStageTrace: {
|
|
121
|
-
readsFrom: [".cclaw/artifacts/07-review.md", ".cclaw/artifacts/06-tdd.md", ".cclaw/artifacts/05-plan.md", ".cclaw/artifacts/04-spec.md"],
|
|
122
|
-
writesTo: [".cclaw/artifacts/08-ship.md"],
|
|
123
|
-
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."
|
|
124
|
-
},
|
|
125
|
-
artifactValidation: [
|
|
126
|
-
{ section: "Preflight Results", required: true, validationRule: "Build, test, lint, type-check results captured with fresh output. Exceptions documented if any." },
|
|
127
|
-
{ section: "Release Notes", required: true, validationRule: "What changed, why, impact. References spec criteria. Breaking changes flagged." },
|
|
128
|
-
{ section: "Rollback Plan", required: true, validationRule: "Trigger conditions, rollback steps (exact commands), verification steps." },
|
|
129
|
-
{ section: "Monitoring", required: false, validationRule: "If applicable: what metrics/logs to watch post-deploy. Risk note if no monitoring." },
|
|
130
|
-
{ 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." },
|
|
131
|
-
{ section: "Completion Status", required: false, validationRule: "If present: exactly one of SHIPPED, SHIPPED_WITH_EXCEPTIONS, BLOCKED. Exceptions documented when applicable." },
|
|
132
|
-
{ section: "Compound Step", required: false, validationRule: "Optional retrospective: at least one bullet of the form 'Insight: ... | Action: append [compound] entry to .cclaw/knowledge.jsonl', or an explicit 'No compound insight this run.' line." }
|
|
133
|
-
]
|
|
134
144
|
};
|
|
@@ -2,131 +2,141 @@
|
|
|
2
2
|
// SPEC
|
|
3
3
|
// ---------------------------------------------------------------------------
|
|
4
4
|
export const SPEC = {
|
|
5
|
+
schemaShape: "v2",
|
|
5
6
|
stage: "spec",
|
|
7
|
+
complexityTier: "standard",
|
|
6
8
|
skillFolder: "specification-authoring",
|
|
7
9
|
skillName: "specification-authoring",
|
|
8
10
|
skillDescription: "Specification stage. Produce measurable, testable requirements without ambiguity.",
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
"constraints
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
"Is every criterion observable (can you point to evidence of pass/fail)?",
|
|
97
|
-
"Is every criterion measurable (numeric threshold or boolean outcome)?",
|
|
98
|
-
"Is every criterion falsifiable (can you describe what failure looks like)?",
|
|
99
|
-
"Does every criterion trace to a design decision (Design Decision Ref)?",
|
|
100
|
-
"Are there any vague adjectives (fast, intuitive, robust) without thresholds?"
|
|
101
|
-
],
|
|
102
|
-
stopGate: true
|
|
11
|
+
philosophy: {
|
|
12
|
+
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.",
|
|
13
|
+
ironLaw: "EVERY ACCEPTANCE CRITERION MUST BE OBSERVABLE AND TESTABLE — OR IT DOES NOT EXIST.",
|
|
14
|
+
purpose: "Create a testable specification aligned with approved design and constraints.",
|
|
15
|
+
whenToUse: [
|
|
16
|
+
"After design lock",
|
|
17
|
+
"Before planning and implementation",
|
|
18
|
+
"When acceptance criteria must be measurable"
|
|
19
|
+
],
|
|
20
|
+
whenNotToUse: [
|
|
21
|
+
"Design decisions are still unresolved or disputed",
|
|
22
|
+
"The task is implementation-only cleanup with unchanged behavior",
|
|
23
|
+
"You still need to challenge scope rather than author requirements"
|
|
24
|
+
],
|
|
25
|
+
commonRationalizations: [
|
|
26
|
+
"High-level goals without measurable outcomes",
|
|
27
|
+
"Implicit assumptions",
|
|
28
|
+
"Proceeding to plan before approval",
|
|
29
|
+
"Using vague adjectives (fast, intuitive, robust) without thresholds",
|
|
30
|
+
"No explicit assumptions section",
|
|
31
|
+
"No approval record",
|
|
32
|
+
"No testability mapping",
|
|
33
|
+
"Edge cases missing or deferred"
|
|
34
|
+
]
|
|
35
|
+
},
|
|
36
|
+
executionModel: {
|
|
37
|
+
checklist: [
|
|
38
|
+
"Read upstream — load design artifact and scope contract. Cross-reference architecture decisions.",
|
|
39
|
+
"Define measurable acceptance criteria — each criterion must be observable and falsifiable. No vague adjectives.",
|
|
40
|
+
"Capture edge cases — for each criterion, define at least one boundary condition and one error condition.",
|
|
41
|
+
"Document constraints and assumptions — regulatory, system, integration, and performance boundaries. Surface implicit assumptions explicitly.",
|
|
42
|
+
"Confirm testability — for each acceptance criterion, describe the test that would prove it. If untestable, rewrite the criterion.",
|
|
43
|
+
"Write spec artifact and request user approval — wait for explicit confirmation before proceeding."
|
|
44
|
+
],
|
|
45
|
+
interactionProtocol: [
|
|
46
|
+
"Express each requirement in observable terms.",
|
|
47
|
+
"Resolve ambiguity before moving to plan. Challenge vague language.",
|
|
48
|
+
"Capture assumptions explicitly, not implicitly.",
|
|
49
|
+
"**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.",
|
|
50
|
+
"Require user confirmation on the written spec. **STOP.** Do NOT proceed to plan until user approves.",
|
|
51
|
+
"For each criterion, ask: how would you test this? If the answer is unclear, rewrite.",
|
|
52
|
+
"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."
|
|
53
|
+
],
|
|
54
|
+
process: [
|
|
55
|
+
"Define measurable acceptance criteria.",
|
|
56
|
+
"Capture constraints, assumptions, and edge cases.",
|
|
57
|
+
"Build testability map: criterion -> test description.",
|
|
58
|
+
"Confirm testability for each criterion.",
|
|
59
|
+
"Present acceptance criteria to the user in 3-5-item batches, pausing for explicit ACK between batches (see Interaction Protocol).",
|
|
60
|
+
"Write spec artifact and request approval."
|
|
61
|
+
],
|
|
62
|
+
requiredGates: [
|
|
63
|
+
{ id: "spec_acceptance_measurable", description: "Acceptance criteria are measurable and observable." },
|
|
64
|
+
{ id: "spec_testability_confirmed", description: "Each criterion has a described test method." },
|
|
65
|
+
{ id: "spec_user_approved", description: "User approved the final written spec." }
|
|
66
|
+
],
|
|
67
|
+
requiredEvidence: [
|
|
68
|
+
"Artifact written to `.cclaw/artifacts/04-spec.md`.",
|
|
69
|
+
"Each acceptance criterion maps to a testable outcome.",
|
|
70
|
+
"Edge cases documented per criterion.",
|
|
71
|
+
"Approval marker captured in artifact."
|
|
72
|
+
],
|
|
73
|
+
inputs: ["design artifact", "business constraints", "quality requirements"],
|
|
74
|
+
requiredContext: [
|
|
75
|
+
"design lock baseline",
|
|
76
|
+
"regulatory or system boundaries",
|
|
77
|
+
"integration constraints"
|
|
78
|
+
],
|
|
79
|
+
blockers: [
|
|
80
|
+
"non-measurable criteria",
|
|
81
|
+
"constraints missing",
|
|
82
|
+
"open ambiguities remain"
|
|
83
|
+
],
|
|
84
|
+
exitCriteria: [
|
|
85
|
+
"spec approved by user",
|
|
86
|
+
"required gates marked satisfied",
|
|
87
|
+
"plan-ready acceptance mapping exists",
|
|
88
|
+
"testability confirmed for all criteria"
|
|
89
|
+
]
|
|
90
|
+
},
|
|
91
|
+
artifactRules: {
|
|
92
|
+
artifactFile: "04-spec.md",
|
|
93
|
+
completionStatus: ["DONE", "DONE_WITH_CONCERNS", "BLOCKED"],
|
|
94
|
+
crossStageTrace: {
|
|
95
|
+
readsFrom: [".cclaw/artifacts/03-design-<slug>.md", ".cclaw/artifacts/02-scope-<slug>.md"],
|
|
96
|
+
writesTo: [".cclaw/artifacts/04-spec.md"],
|
|
97
|
+
traceabilityRule: "Every acceptance criterion must trace to a design decision. Every downstream plan task must trace to a spec criterion."
|
|
103
98
|
},
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
}
|
|
115
|
-
],
|
|
116
|
-
completionStatus: ["DONE", "DONE_WITH_CONCERNS", "BLOCKED"],
|
|
117
|
-
crossStageTrace: {
|
|
118
|
-
readsFrom: [".cclaw/artifacts/03-design.md", ".cclaw/artifacts/02-scope.md"],
|
|
119
|
-
writesTo: [".cclaw/artifacts/04-spec.md"],
|
|
120
|
-
traceabilityRule: "Every acceptance criterion must trace to a design decision. Every downstream plan task must trace to a spec criterion."
|
|
99
|
+
artifactValidation: [
|
|
100
|
+
{ 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-<slug>.md (legacy 02-scope.md is accepted during migration) 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`." },
|
|
101
|
+
{ section: "Edge Cases", required: true, validationRule: "At least one boundary and one error condition per criterion." },
|
|
102
|
+
{ section: "Constraints and Assumptions", required: false, validationRule: "All implicit assumptions surfaced. Constraints have sources." },
|
|
103
|
+
{ 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." },
|
|
104
|
+
{ section: "Vague to Fixed", required: false, validationRule: "If present: table with original vague wording and rewritten observable/testable version for each ambiguous requirement." },
|
|
105
|
+
{ section: "Non-Functional Requirements", required: false, validationRule: "If present: performance thresholds, security constraints, scalability limits, reliability targets with measurable values." },
|
|
106
|
+
{ section: "Interface Contracts", required: false, validationRule: "If present: for each module boundary list produces (outputs) and consumes (inputs) with data types." },
|
|
107
|
+
{ section: "Approval", required: true, validationRule: "Explicit user approval marker present." }
|
|
108
|
+
]
|
|
121
109
|
},
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
110
|
+
reviewLens: {
|
|
111
|
+
outputs: [
|
|
112
|
+
"measurable specification",
|
|
113
|
+
"acceptance-to-testability map",
|
|
114
|
+
"approved spec artifact"
|
|
115
|
+
],
|
|
116
|
+
reviewSections: [
|
|
117
|
+
{
|
|
118
|
+
title: "Acceptance Criteria Audit",
|
|
119
|
+
evaluationPoints: [
|
|
120
|
+
"Is every criterion observable (can you point to evidence of pass/fail)?",
|
|
121
|
+
"Is every criterion measurable (numeric threshold or boolean outcome)?",
|
|
122
|
+
"Is every criterion falsifiable (can you describe what failure looks like)?",
|
|
123
|
+
"Does every criterion trace to a design decision (Design Decision Ref)?",
|
|
124
|
+
"Are there any vague adjectives (fast, intuitive, robust) without thresholds?"
|
|
125
|
+
],
|
|
126
|
+
stopGate: true
|
|
127
|
+
},
|
|
128
|
+
{
|
|
129
|
+
title: "Testability Audit",
|
|
130
|
+
evaluationPoints: [
|
|
131
|
+
"Does every criterion have a concrete test description in the Testability Map?",
|
|
132
|
+
"Does every test specify a verification approach (unit, integration, e2e, manual)?",
|
|
133
|
+
"Does every test include a runnable command or manual steps?",
|
|
134
|
+
"Are edge cases (boundary + error) defined for every criterion?",
|
|
135
|
+
"Can you run every verification command right now and get a meaningful result?"
|
|
136
|
+
],
|
|
137
|
+
stopGate: true
|
|
138
|
+
}
|
|
139
|
+
]
|
|
140
|
+
},
|
|
141
|
+
next: "plan",
|
|
132
142
|
};
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import type { StageSchemaInput,
|
|
1
|
+
import type { StageSchemaInput, StageSchemaV2Input } from "./schema-types.js";
|
|
2
2
|
import type { FlowTrack } from "../../types.js";
|
|
3
|
-
export declare const TDD:
|
|
3
|
+
export declare const TDD: StageSchemaV2Input;
|
|
4
4
|
export declare function tddStageForTrack(track: FlowTrack): StageSchemaInput;
|