Skip to content

Commit 1e81e7f

Browse files
thundermiraclethundermiracle
authored
feat: add MVP acceptance checklist and explicit non-goals contract (issue #13)
* feat: add MVP acceptance contract schema (issue #13) * feat: add canonical MVP acceptance checklist and non-goals contract * docs: add MVP acceptance checklist and non-goals narrative * test: add unit tests for MVP acceptance and non-goal contract
1 parent 11713ed commit 1e81e7f

File tree

4 files changed

+556
-0
lines changed

4 files changed

+556
-0
lines changed

‎docs/spec/mvp-acceptance-contract.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# MVP Acceptance Checklist and Non-goals v1
2+
3+
This document defines the release gate checklist, done definitions, and explicit non-goals for issue `#13`.
4+
5+
## Major Flows in MVP Scope
6+
7+
The MVP decision is based on exactly four major flows:
8+
9+
1. `detection`
10+
2. `list`
11+
3. `add`
12+
4. `remove`
13+
14+
## Release Decision Rule
15+
16+
- Rule: `all_blocking_items_pass`
17+
- Meaning: any blocking checklist item failing means `no_go`
18+
- Required evidence classes:
19+
- `automated_test`
20+
- `manual_qa`
21+
- `spec_review`
22+
23+
This contract is designed to support a release/no-release decision without interpretation ambiguity.
24+
25+
## Must-have Checklist
26+
27+
- The checklist defines blocking requirements for each major flow.
28+
- Every item has:
29+
- stable ID
30+
- verification method
31+
- concrete evidence expectation
32+
- The checklist is intentionally strict to prevent scope creep and hidden quality debt.
33+
34+
## Done Definition per Flow
35+
36+
Each major flow has:
37+
38+
- required checklist item references
39+
- explicit `doneWhen` statements
40+
- explicit `notDoneWhen` failure triggers
41+
42+
This allows the team to evaluate completion consistently across contributors and reviews.
43+
44+
## Explicit Non-goals
45+
46+
MVP non-goals are documented and tied to later issues to keep deferred scope explicit:
47+
48+
- Parser extensibility hardening (`#21`, `#31`)
49+
- Secret redaction hardening (`#30`, `#32`)
50+
- Full GUI polish scope (`#27`, `#28`, `#29`)
51+
- Packaging and release automation (`#33`, `#34`, `#35`)
52+
53+
## Files
54+
55+
- Schema:
56+
- `schemas/mvp-acceptance-contract.schema.json`
57+
- Canonical sample:
58+
- `docs/spec/mvp-acceptance-contract.v1.json`
59+
- Unit tests:
60+
- `tests/mvp-acceptance-contract.test.mjs`

‎docs/spec/mvp-acceptance-contract.v1.json‎

Lines changed: 193 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,193 @@
1+
{
2+
"version": "1.0.0",
3+
"updatedAt": "2026-02-26",
4+
"flows": [
5+
"detection",
6+
"list",
7+
"add",
8+
"remove"
9+
],
10+
"releaseDecisionPolicy": {
11+
"rule": "all_blocking_items_pass",
12+
"blockingDefinition": "Any checklist item marked as blocking must pass with required evidence.",
13+
"goState": "go",
14+
"noGoState": "no_go",
15+
"requiredEvidence": [
16+
"automated_test",
17+
"manual_qa",
18+
"spec_review"
19+
]
20+
},
21+
"mustHaveChecklist": [
22+
{
23+
"id": "CHK_DETECTION_001",
24+
"flow": "detection",
25+
"title": "Detect all four target clients with deterministic status",
26+
"description": "Detection returns deterministic detected/partial/absent/error status for Claude Code, Codex CLI, Cursor, and Codex App.",
27+
"verification": "automated_test",
28+
"evidence": "Fixture-based detector tests with stable expected outputs.",
29+
"blocking": true
30+
},
31+
{
32+
"id": "CHK_DETECTION_002",
33+
"flow": "detection",
34+
"title": "Detection evidence is traceable",
35+
"description": "Detection result includes concrete evidence such as binary path or config path without ambiguous generic output.",
36+
"verification": "manual_qa",
37+
"evidence": "Manual run screenshots or logs showing evidence fields for each client.",
38+
"blocking": true
39+
},
40+
{
41+
"id": "CHK_LIST_001",
42+
"flow": "list",
43+
"title": "Unified MCP and Skill listing works across detected clients",
44+
"description": "Read pipeline returns normalized MCP and Skill entities without UI-level client branching.",
45+
"verification": "automated_test",
46+
"evidence": "Integration tests across fixtures for all supported clients.",
47+
"blocking": true
48+
},
49+
{
50+
"id": "CHK_LIST_002",
51+
"flow": "list",
52+
"title": "Parse failures remain actionable",
53+
"description": "Malformed entries do not crash full listing and produce categorized actionable errors.",
54+
"verification": "automated_test",
55+
"evidence": "Negative fixtures proving partial success plus categorized error output.",
56+
"blocking": true
57+
},
58+
{
59+
"id": "CHK_ADD_001",
60+
"flow": "add",
61+
"title": "Add operation is safe and reversible",
62+
"description": "Adding MCP/Skill creates backup and applies atomic write semantics.",
63+
"verification": "automated_test",
64+
"evidence": "Mutation tests demonstrating backup creation and rollback on failure.",
65+
"blocking": true
66+
},
67+
{
68+
"id": "CHK_ADD_002",
69+
"flow": "add",
70+
"title": "Validation blocks invalid additions",
71+
"description": "Duplicate names, malformed transport, and invalid metadata are rejected before write.",
72+
"verification": "automated_test",
73+
"evidence": "Validation unit tests with explicit categorized errors.",
74+
"blocking": true
75+
},
76+
{
77+
"id": "CHK_REMOVE_001",
78+
"flow": "remove",
79+
"title": "Remove operation updates target config only",
80+
"description": "Removal mutates only intended entries and preserves unrelated configuration blocks.",
81+
"verification": "automated_test",
82+
"evidence": "Before/after fixture comparison tests for remove operations.",
83+
"blocking": true
84+
},
85+
{
86+
"id": "CHK_REMOVE_002",
87+
"flow": "remove",
88+
"title": "Remove operation exposes explicit user feedback",
89+
"description": "UI and command boundary return clear success/error states with suggested recovery actions.",
90+
"verification": "manual_qa",
91+
"evidence": "Manual QA checklist signed for remove happy-path and failure-path scenarios.",
92+
"blocking": true
93+
}
94+
],
95+
"doneDefinitions": [
96+
{
97+
"flow": "detection",
98+
"requiredChecklistItemIds": [
99+
"CHK_DETECTION_001",
100+
"CHK_DETECTION_002"
101+
],
102+
"doneWhen": [
103+
"All target clients return deterministic status and evidence.",
104+
"No detection output uses ambiguous generic error text."
105+
],
106+
"notDoneWhen": [
107+
"Any target client lacks reproducible detection evidence."
108+
]
109+
},
110+
{
111+
"flow": "list",
112+
"requiredChecklistItemIds": [
113+
"CHK_LIST_001",
114+
"CHK_LIST_002"
115+
],
116+
"doneWhen": [
117+
"Unified normalized list contract is stable across client fixtures.",
118+
"Malformed inputs degrade gracefully with actionable categorized errors."
119+
],
120+
"notDoneWhen": [
121+
"One malformed file can crash whole-list retrieval."
122+
]
123+
},
124+
{
125+
"flow": "add",
126+
"requiredChecklistItemIds": [
127+
"CHK_ADD_001",
128+
"CHK_ADD_002"
129+
],
130+
"doneWhen": [
131+
"Every add path creates backup and applies atomic write semantics.",
132+
"Invalid inputs are rejected before persistence."
133+
],
134+
"notDoneWhen": [
135+
"Add can overwrite existing configuration without conflict checks."
136+
]
137+
},
138+
{
139+
"flow": "remove",
140+
"requiredChecklistItemIds": [
141+
"CHK_REMOVE_001",
142+
"CHK_REMOVE_002"
143+
],
144+
"doneWhen": [
145+
"Remove mutates only targeted entries and leaves unrelated content untouched.",
146+
"Remove flow returns clear outcome and recovery guidance."
147+
],
148+
"notDoneWhen": [
149+
"Successful remove cannot be verified by deterministic before/after evidence."
150+
]
151+
}
152+
],
153+
"nonGoals": [
154+
{
155+
"id": "NG_001",
156+
"title": "Advanced parser extensibility and fixture DSL",
157+
"description": "Extensible parser plugin mechanisms and advanced fixture DSL are deferred to parser hardening phase.",
158+
"deferredToIssues": [
159+
21,
160+
31
161+
]
162+
},
163+
{
164+
"id": "NG_002",
165+
"title": "Full secret redaction policy across every diagnostic surface",
166+
"description": "Comprehensive secret masking in all logs/UI contexts is deferred to security hardening milestones.",
167+
"deferredToIssues": [
168+
30,
169+
32
170+
]
171+
},
172+
{
173+
"id": "NG_003",
174+
"title": "Polished multi-tab GUI and advanced interaction patterns",
175+
"description": "Full dashboard polish and detailed tab UX are deferred to dedicated GUI milestones.",
176+
"deferredToIssues": [
177+
27,
178+
28,
179+
29
180+
]
181+
},
182+
{
183+
"id": "NG_004",
184+
"title": "Distribution packaging and release automation",
185+
"description": "DMG packaging, release policy, and operator docs are deferred to release phase.",
186+
"deferredToIssues": [
187+
33,
188+
34,
189+
35
190+
]
191+
}
192+
]
193+
}

0 commit comments

Comments
 (0)