@koreanhole/kandev 0.0.0-stage → 0.1.0

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.
Files changed (51) hide show
  1. package/README.md +367 -2
  2. package/bin/codex-acp.js +16 -0
  3. package/bin/kandev-auto-sync.mjs +101 -0
  4. package/bin/kandev-config.js +53 -0
  5. package/bin/kandev.js +35 -0
  6. package/config/config.yaml +6 -0
  7. package/config/docker/projects/opencodex-cli.json +79 -0
  8. package/config/docker/projects/samsung-bus-tracker.json +91 -0
  9. package/config/gateways.json +14 -0
  10. package/config/pipeline.json +150 -0
  11. package/config/workflows/sdlc.yaml +1019 -0
  12. package/docker/Dockerfile +68 -0
  13. package/docker/Dockerfile.opencodex-cli +44 -0
  14. package/docker/Dockerfile.samsung-bus-tracker +75 -0
  15. package/package.json +61 -4
  16. package/scripts/agent-tools-docker.mjs +223 -0
  17. package/scripts/baseline.mjs +20 -0
  18. package/scripts/codex-medium +2 -0
  19. package/scripts/codex-stage +22 -0
  20. package/scripts/gate.mjs +909 -0
  21. package/scripts/gateways/docker.mjs +64 -0
  22. package/scripts/gateways/speckit.mjs +78 -0
  23. package/scripts/install-prerequisites.mjs +48 -0
  24. package/scripts/lib/artifacts.mjs +990 -0
  25. package/scripts/lib/bugfix.mjs +325 -0
  26. package/scripts/lib/checksum.mjs +166 -0
  27. package/scripts/lib/docker-workspace.mjs +1209 -0
  28. package/scripts/lib/gateways.mjs +79 -0
  29. package/scripts/lib/kandev.mjs +273 -0
  30. package/scripts/lib/mcp.mjs +111 -0
  31. package/scripts/lib/pipeline.mjs +548 -0
  32. package/scripts/lib/planning-replan.mjs +103 -0
  33. package/scripts/lib/resume.mjs +207 -0
  34. package/scripts/lib/review-history.mjs +260 -0
  35. package/scripts/lib/stage-boundary.mjs +146 -0
  36. package/scripts/lib/stage-model.mjs +23 -0
  37. package/scripts/lib/task-worktree.mjs +40 -0
  38. package/scripts/measure-tokens.mjs +121 -0
  39. package/scripts/planning-tools.mjs +166 -0
  40. package/scripts/replan-planning.mjs +82 -0
  41. package/scripts/review-digest.mjs +240 -0
  42. package/scripts/run-android-e2e.mjs +116 -0
  43. package/scripts/run-code-review.mjs +281 -0
  44. package/scripts/run-detached.mjs +163 -0
  45. package/scripts/run-doc-review.mjs +155 -0
  46. package/scripts/run-gateways.mjs +138 -0
  47. package/scripts/sync.mjs +588 -0
  48. package/scripts/verify-change.mjs +252 -0
  49. package/scripts/verify-node.mjs +288 -0
  50. package/scripts/verify.mjs +442 -0
  51. package/scripts/wait-status.mjs +88 -0
@@ -0,0 +1,1019 @@
1
+ version: 2
2
+ type: kandev_workflow
3
+ workflows:
4
+ - name: Agentic SDLC
5
+ description: >-
6
+ Five gated agent stages plus a human approval lane: generic agent gateways,
7
+ Spec Kit planning and document review, clean-context implementation,
8
+ independent code review, and browser end-to-end verification. Every agent
9
+ transition requires a machine-readable artifact and an explicit completion
10
+ signal; a person reviews the verified worktree and moves the task to Done.
11
+ steps:
12
+ - name: 1. Agent Gateway
13
+ position: 0
14
+ color: bg-slate-500
15
+ profile_ref: SDLC 1 · Gateway
16
+ is_start_step: true
17
+ show_in_command_panel: true
18
+ allow_manual_move: false
19
+ auto_advance_requires_signal: true
20
+ cancel_triggers_turn_complete: false
21
+ complete_task_on_enter: false
22
+ events:
23
+ on_enter:
24
+ - type: auto_start_agent
25
+ prompt: |
26
+ You are Stage 1, the agent gateway. Work only in the task's repository
27
+ worktree. Do not write application code.
28
+
29
+ Stage boundary: only `.specify/`, `.agents/`, and
30
+ `.agentic/gateway.json` may change. The gate snapshots the worktree and
31
+ rejects any application, specification, or other out-of-scope path.
32
+
33
+ The task description belongs to Planning and is intentionally not
34
+ provided here. The gateway runner executes every gateway enabled in
35
+ the workflow configuration. Do not hard-code a vendor or assume the
36
+ current gateway list cannot grow.
37
+
38
+ Tool-output discipline:
39
+ Bound every command. Build/test logs: `2>&1 | tail -60`.
40
+ File/report reads: `| head -c 4000`. Never run unbounded `cat`,
41
+ `rg` over HTML/base64/minified assets or reports, `ls -R` of
42
+ `node_modules`, or `find` over caches. If output may exceed ~8KB,
43
+ redirect to `.agentic/logs/<name>.log`, then inspect with
44
+ `rg -n -m 20` or `sed -n 'a,bp'`. A tool result larger than ~8KB is
45
+ a pipeline defect: rerun bounded before reasoning about it.
46
+
47
+ Tool-calling discipline:
48
+ Every turn MUST execute a tool call until the stage is complete. Never
49
+ output conversational commentary, plans, explanations, or text-only
50
+ messages without calling a tool in the same turn. Do not stop to explain
51
+ what you will do.
52
+ Use the `agent-tools` MCP server's `run_process` tool with `argv` only;
53
+ in tool declarations it may appear as `run_process`, `agent-tools/run_process`,
54
+ `agent-tools.run_process`, or `mcp__agent_tools__run_process`.
55
+ Wait for agent-tools to be ready before running any stage command. If it is
56
+ absent, use the host's tool discovery and a non-shell wait, then refresh the
57
+ tool catalog and retry for up to 60 seconds. Never use a host shell as a
58
+ substitute. If still unavailable, stop without signaling success; the gate
59
+ will block or resume this stage.
60
+
61
+ As your first bridge call, execute the gateway runner in one shot using `sh`:
62
+ argv: ["sh", "-c", "node \"$KANDEV_WORKFLOW_ROOT/scripts/run-gateways.mjs\" --cwd \"$PWD\" --task \"agent gateway\" --json"]
63
+
64
+ Do not run shell commands, list files, read files, or edit anything before
65
+ or after the runner. Never create or edit `.agentic/gateway.json` yourself;
66
+ only `run-gateways.mjs` may write `.agentic/gateway.json`.
67
+
68
+ Completion rule: signal only when the runner exits 0,
69
+ `.agentic/gateway.json` has verdict PASS, every enabled gateway in it
70
+ has status PASS, and `application_files_changed` is empty. Call
71
+ `step_complete_kandev` to complete this step. On FAIL, leave the
72
+ artifact in place and call `step_complete_kandev` so the gate records
73
+ the failure; the gate decides the transition.
74
+
75
+ Resume contract: a message beginning with `[Kandev resume` is a
76
+ continuation of the current stage, not a new task. Do not restart
77
+ completed work, change scope, or move the step. Produce or signal the
78
+ named `.agentic` artifact and call `step_complete_kandev`. If this
79
+ stage ends in FAIL, write the FAIL artifact and signal it; do not stop
80
+ silently.
81
+
82
+ - name: 2. Planning
83
+ position: 1
84
+ color: bg-blue-500
85
+ profile_ref: SDLC 2 · Planning
86
+ is_start_step: false
87
+ show_in_command_panel: true
88
+ allow_manual_move: false
89
+ auto_advance_requires_signal: true
90
+ cancel_triggers_turn_complete: false
91
+ complete_task_on_enter: false
92
+ events:
93
+ on_enter:
94
+ - type: auto_start_agent
95
+ prompt: |
96
+ You are Stage 2, Spec Kit planning and document review. Work only in
97
+ the task's repository worktree. Do not write application code.
98
+
99
+ Your first bridge action MUST be `agent-tools.run_process` with
100
+ `["printenv","KANDEV_WORKFLOW_ROOT"]`; your second MUST be `["pwd"]`;
101
+ wait for both string outputs before calling any script or reading
102
+ files (never call scripts in the same parallel turn as printenv/pwd);
103
+ your third MUST read `<worktree>/.agents/skills/speckit-specify/SKILL.md`.
104
+ Follow that skill file. Do not use the shell tool. Do not inspect
105
+ `node_modules`, `~/.npm`, `~/.kandev`, `scripts/lib`, the implementation
106
+ of `run-doc-review.mjs` or `planning-tools.mjs`, or package sources.
107
+ Invoke helper scripts as commands only; their contracts are in this
108
+ prompt. Read the other `speckit-*` SKILL.md files in order before using
109
+ them.
110
+
111
+ {{task_prompt}}
112
+
113
+ Tool-output discipline:
114
+ Bound every command. Build/test logs: `2>&1 | tail -60`.
115
+ File/report reads: `| head -c 4000`. Never run unbounded `cat`,
116
+ `rg` over HTML/base64/minified assets or reports, `ls -R` of
117
+ `node_modules`, or `find` over caches. If output may exceed ~8KB,
118
+ redirect to `.agentic/logs/<name>.log`, then inspect with
119
+ `rg -n -m 20` or `sed -n 'a,bp'`. A tool result larger than ~8KB is
120
+ a pipeline defect: rerun bounded before reasoning about it.
121
+
122
+ Tool-calling discipline:
123
+ Every turn MUST execute a tool call until the stage is complete. Never
124
+ output conversational commentary, plans, explanations, or text-only
125
+ messages without calling a tool in the same turn. Do not stop to explain
126
+ what you will do.
127
+ Use the `agent-tools` MCP server's `run_process` tool with `argv` only;
128
+ in tool declarations it may appear as `run_process`, `agent-tools/run_process`,
129
+ `agent-tools.run_process`, or `mcp__agent_tools__run_process`.
130
+ Wait for agent-tools to be ready before running any stage command. If it is
131
+ absent, use the host's tool discovery and a non-shell wait, then refresh the
132
+ tool catalog and retry for up to 60 seconds. Never use a host shell as a
133
+ substitute. If still unavailable, stop without signaling success; the gate
134
+ will block or resume this stage.
135
+ As your first bridge call, execute `run_process` with `argv: ["printenv", "KANDEV_WORKFLOW_ROOT"]`.
136
+ As your second bridge call, execute `run_process` with `argv: ["pwd"]`.
137
+ Once both paths are obtained, immediately proceed to execute the stage
138
+ actions without stopping to talk.
139
+
140
+ Use the project's Spec Kit skills in this order:
141
+ $speckit-specify -> $speckit-clarify -> $speckit-plan -> $speckit-tasks
142
+ Do not run `$speckit-implement`; implementation belongs to the next
143
+ stage. `$speckit-clarify` must not wait for a human: resolve each
144
+ question from repository evidence and the task description, and record
145
+ every assumption in `spec.md`. Use `.specify/feature.json` to locate
146
+ the feature directory created by `$speckit-specify`.
147
+
148
+ Classify the task before writing the plan. Write `change_type` and
149
+ `classification_reason` in `.agentic/spec.json`. Use `bugfix` when the
150
+ task describes an existing defect, regression, crash, or broken
151
+ behavior. Do not call a defect a feature to skip reproduction.
152
+ A `feature` classification must name the new behavior and explain why
153
+ no existing behavior is being fixed. If the task contains `[bug]`,
154
+ `bug:`, `bugfix:`, `hotfix:`, `regression:`, an issue reference, or a
155
+ Korean bug/error/outage word, use `bugfix`; the gate rejects a feature
156
+ classification for any bug marker.
157
+
158
+ Bugfix branch (required when `change_type` is `bugfix`):
159
+ 1. After `$speckit-specify` and `$speckit-clarify`, write
160
+ `.agentic/bugfix.json` with the issue symptom, the original and
161
+ expected behavior, the canonical reproduction command, the pinned
162
+ reproduction files, the root-cause evidence, and the planned
163
+ regression test path. The driver must be
164
+ `.agentic/bugfix-repro.mjs`; pin its sha256 together with every
165
+ other `.agentic` file it imports. Use this contract:
166
+ {
167
+ "stage": "bugfix",
168
+ "task": "<exact task string>",
169
+ "timestamp": "<ISO-8601>",
170
+ "verdict": "PASS",
171
+ "issue": {"summary": "...", "source": "...", "observed": "...", "expected": "..."},
172
+ "reproduction": {
173
+ "driver": ".agentic/bugfix-repro.mjs",
174
+ "command": ["node", ".agentic/bugfix-repro.mjs"],
175
+ "files": [{"path": ".agentic/bugfix-repro.mjs", "sha256": "..."}],
176
+ "scenario_id": "BUG-1",
177
+ "result_path": ".agentic/bugfix-result.json",
178
+ "expected_before": "failed",
179
+ "expected_after": "passed"
180
+ },
181
+ "root_cause": {
182
+ "summary": "...",
183
+ "evidence": [{"path": "src/file.ts", "line": 1, "note": "..."}],
184
+ "causal_chain": ["trigger", "fault", "visible result"]
185
+ },
186
+ "fix_scope": ["src/file.ts"],
187
+ "regression_test": {
188
+ "path": "tests/bugfix/example.test.ts",
189
+ "command": ["npm", "test", "--", "tests/bugfix/example.test.ts"],
190
+ "framework": "node-test" | "junit" | "playwright" | "other"
191
+ }
192
+ }
193
+ 2. Write `.agentic/bugfix-repro.mjs` as a real E2E driver for the
194
+ current platform. It must drive the actual UI, CLI, or Android
195
+ device, write `.agentic/bugfix-result.json` with
196
+ `{"scenario":"BUG-1","status":"failed|passed","evidence":"..."}`,
197
+ and exit non-zero while the bug exists.
198
+ The driver `.agentic/bugfix-repro.mjs` MUST ONLY write to
199
+ `.agentic/bugfix-result.json`. It MUST NOT write to or reference
200
+ any file under `.agentic/bugfix-runs/` (such as
201
+ `planning-before.result.json` or `implementation-before.result.json`).
202
+ Hardcoding writes to `.agentic/bugfix-runs/` inside the driver will
203
+ corrupt historical failure evidence during Stage 3 and Stage 5
204
+ replays and will be rejected by the planning finalizer and the gate.
205
+ 3. Run the driver before `$speckit-plan` with `agent-tools.run_process`
206
+ and `argv` only. Save bounded output to
207
+ `.agentic/bugfix-runs/planning-before.log`, copy the driver result to
208
+ `.agentic/bugfix-runs/planning-before.result.json`, and write
209
+ `.agentic/bugfix-runs/planning-before.json` with `phase`,
210
+ `scenario_id`, `status: "failed"`, `exit_code`, `evidence`, `log`,
211
+ `result_path`, and `timestamp`. If the driver exits 0 or reports
212
+ `passed`, stop; do not reclassify the task as a feature.
213
+ 4. Analyze the root cause from the running code, not from the symptom.
214
+ Record at least one `path:line` evidence entry outside `.agentic/`,
215
+ `specs/`, and `.specify/`, a causal chain with at least two steps,
216
+ and the fix scope.
217
+ 5. Only after the failing reproduction and root-cause evidence exist,
218
+ run `$speckit-plan` and `$speckit-tasks`. Name the reproduced
219
+ behavior `BUG-1`, add a matching `AC-BUG-1` acceptance criterion,
220
+ and plan the regression test at the exact path in
221
+ `bugfix.json.regression_test.path`.
222
+
223
+ The planning finalizer validates `.agentic/bugfix.json` and the
224
+ `planning-before` evidence. A missing or passing pre-fix run is a
225
+ blocker; never downgrade it to `feature` to advance.
226
+
227
+ If a `$speckit-*` skill is not exposed in your skill list, read the
228
+ corresponding `.agents/skills/speckit-<name>/SKILL.md` file and follow
229
+ it directly. The project skill files are authoritative. Do not search
230
+ Kandev internals, `~/.kandev`, `node_modules`, or the host installation
231
+ for them. Use `agent-tools.run_process` for every command; the shell
232
+ tool does not inherit `KANDEV_WORKFLOW_ROOT`. Obtain that value with
233
+ `["printenv","KANDEV_WORKFLOW_ROOT"]` and pass absolute paths.
234
+
235
+ Stage boundary: only `specs/` and `.specify/feature.json` may change.
236
+ Do not modify application files, `.agents`, any other `.specify` file,
237
+ or implementation artifacts. The gate rejects out-of-scope paths.
238
+
239
+ Keep spec.md self-consistent across FR-*, AC-*, and SC-*: use one
240
+ explicit start anchor and pass/fail condition per timing/freshness
241
+ rule, state explicit precedence when two ACs cover fallback/empty
242
+ states, and leave architecture, data-model fields, and adb/clock-jump
243
+ driver steps in plan.md, data-model.md, and quickstart.md.
244
+ Follow these self-consistency rules:
245
+ - Refresh ordering rule: Define latest refresh by monotonic request sequence or snapshot version; late-completing older refreshes are dropped.
246
+ - Measurable outcomes timing rule: Measurable Outcomes (`SC-*`) sample times must always be at or after the maximum allowed display deadline (e.g. if FR allows up to 20 seconds after 17:00:00 for the widget to render, SC must sample at 17:00:25 or 17:00:30, never at 17:00:10).
247
+ - Inactive / fallback state rule: Clarify RON active window vs inactive fallback in a concise single state definition.
248
+
249
+ After the documents exist, run a bounded review loop. The requirement
250
+ review run is the snapshot of record: every listed document, including
251
+ `analysis.md`, must be final before that run starts, and must not change
252
+ until the next round starts. Each round runs both reviewers on the same
253
+ final documents:
254
+ 1. Finish every listed document first. Invoke the `$speckit-analyze`
255
+ skill on the feature directory and write its complete report to
256
+ `.agentic/speckit-analyze.md`. The report must state a PASS/FAIL
257
+ verdict and count CRITICAL, major, and minor findings. Fold every
258
+ CRITICAL or major analyze finding into the feature documents and
259
+ `analysis.md` before the requirement review starts. `analysis.md`
260
+ must contain the final cross-artifact review and no unresolved
261
+ CRITICAL finding.
262
+ 2. Start the requirement review as a detached process with the
263
+ `agent-tools` MCP server and `run_process` with `argv` only;
264
+ `command_line` is forbidden. Resolve `KANDEV_WORKFLOW_ROOT` and the
265
+ absolute worktree path first:
266
+ ["node","<printed root>/scripts/run-doc-review.mjs","--cwd","<printed worktree>","--input","<feature directory>","--log",".agentic/doc-review.log","--status",".agentic/doc-review.status.json"]
267
+ It returns immediately with a monitorPid. Wait with:
268
+ ["node","<printed root>/scripts/wait-status.mjs","--status",".agentic/doc-review.status.json","--timeout-ms","280000"]
269
+ using `timeout_ms` 300000. Repeat that wait once if still running,
270
+ then poll every 60 seconds until completed, failed, or 30 minutes
271
+ pass. On failure, record the error and retry at most once. Do not
272
+ inspect the npm registry or debug package resolution.
273
+ 3. Parse the latest RunSummary JSON from `.agentic/doc-review.log`.
274
+ Record its run id, finding stable ids, and blocker/major/minor counts. The
275
+ wrapper runs the pinned `@koreanhole/requirement-agent@0.1.7` with
276
+ the ambiguity, testability, and consistency roles. The run's
277
+ `run.json`, `findings.json`, and `snapshot.json` are authoritative.
278
+ 4. In Round 1, every blocker must be remediated in `spec.md` followed
279
+ by Round 2. Fix requirement-agent majors only when they
280
+ change the implementation or test contract. Record every remaining
281
+ testability or consistency major in `accepted_majors` with a
282
+ concrete reason and the exact `stableId` from `findings.json`; do
283
+ not rewrite the contract just to make the count fall. A later round
284
+ may legitimately have more majors than the previous round because
285
+ the reviewer reviews revised text; display ids may renumber, so use
286
+ `stableId` when carrying a major across rounds. Do not treat an
287
+ increase as a failure. Keep observation windows, fixture
288
+ ids, clock jumps, and timing procedures in `quickstart.md` or the
289
+ bugfix driver, not in `spec.md`. Once two completed review rounds
290
+ exist, the `FR-*`, `AC-*`, and `SC-*` id set from the latest
291
+ completed round is frozen. Do not add, renumber, or split ids
292
+ during remediation; the wrapper and finalizer reject new ids. A
293
+ finding that needs genuinely new behavior is a planning blocker:
294
+ write the FAIL/blocked report and stop for replan. Edit only the
295
+ passages cited by the findings. A failed wrapper run may be retried
296
+ once as infrastructure recovery.
297
+ 5. Stop reviewing when the latest completed round has zero blockers,
298
+ or once at least two completed review rounds exist (`rounds >= 2`,
299
+ including after Round 2 or Round 3), if a remaining blocker finding
300
+ in `findings.json` is already satisfied by existing `spec.md`
301
+ clauses (a disputed or single-role interpretation that does not
302
+ require new `FR-*`/`AC-*` scope), do NOT fail the stage or start
303
+ another round: write `verdict: "PASS"`, record the exact counts from
304
+ `run.json`, list every remaining blocker's `stableId` in
305
+ `blocker_ids: ["<final blocker stableId>"]`, and justify each in
306
+ `accepted_blockers: [{"id": "<final blocker stableId>", "reason": "<concrete citation in spec.md showing why the requirement is already unambiguous and testable>"}]`
307
+ (when `blockers` is 0, set `blocker_ids: []` and `accepted_blockers: []`
308
+ or omit them). At Round 3 (the final allowed round), if findings
309
+ remain regarding edge case timings, sampling intervals, or
310
+ interpretations that do not alter the core user scenario, the agent
311
+ MUST NOT fail the stage: it must set `verdict: "PASS"`, populate
312
+ `blocker_ids`, and provide concrete citations in `accepted_blockers`
313
+ showing why the requirement is unambiguous and testable, so that
314
+ Stage 2 successfully advances to Stage 3. Write the PASS envelope
315
+ with every remaining major in `accepted_majors`; do not run another
316
+ round just to lower the count.
317
+ If you edited any listed document after that run, its snapshot is
318
+ stale: run another review round when the budget allows, otherwise
319
+ stop and write the FAIL/blocked report. If the wrapper refuses a new
320
+ round because three completed rounds already exist, stop. If it
321
+ refuses because the requirement id set grew or a reviewed document
322
+ expanded past the remediation budget, remove the added ids or text
323
+ and address the finding by clarifying the existing requirements; if
324
+ that is impossible, stop and write the FAIL/blocked report. Do not
325
+ delete ids or edit the wrapper to bypass the guard. Run the
326
+ finalizer first even on FAIL so the snapshot hashes are recorded,
327
+ then write the FAIL/blocked report. Do not start a fourth round. The
328
+ wrapper writes `.agentic/planning-blocked.json` with the reason and
329
+ review history; report it and call `step_complete_kandev` so the
330
+ gate records the blocked state.
331
+
332
+ After the final clean round, write `.agentic/spec.json` with:
333
+ {
334
+ "stage": "planning",
335
+ "task": "<copy the exact task string>",
336
+ "timestamp": "<ISO-8601>",
337
+ "change_type": "feature" | "bugfix",
338
+ "classification_reason": "<why this is a feature or bugfix>",
339
+ "platform": "web" | "android" | "node",
340
+ "feature_dir": "<relative feature directory>",
341
+ "documents": ["spec.md", "plan.md", "tasks.md", "analysis.md", "checklists/requirements.md", ...],
342
+ "functional_requirements": [{"id": "FR-001", "text": "..."}],
343
+ "acceptance_criteria": [{"id": "AC-1", "given": "...", "when": "...", "then": "..."}],
344
+ "out_of_scope": ["..."],
345
+ "risks": ["..."],
346
+ "assumptions": ["..."],
347
+ "application_files_changed": []
348
+ }
349
+ Include every functional requirement and acceptance criterion from the
350
+ final `spec.md`. Label the acceptance scenarios with their AC ids in
351
+ `spec.md` so the contract and the document agree. Every listed document
352
+ must exist under `feature_dir`; include `spec.md`, `plan.md`,
353
+ `tasks.md`, `analysis.md`, and `checklists/requirements.md` at minimum.
354
+ `analysis.md` must already be final and included in the latest review
355
+ snapshot; a document created or edited after that run is rejected.
356
+
357
+ Then write `.agentic/spec-review.json` with the standard review
358
+ envelope plus both reviewer records:
359
+ {
360
+ "stage": "planning-review",
361
+ "task": "<copy the exact task string>",
362
+ "timestamp": "<ISO-8601>",
363
+ "verdict": "PASS",
364
+ "rounds": <number of completed review runs>,
365
+ "blockers": 0,
366
+ "majors": <final requirement-agent major count>,
367
+ "minors": <count>,
368
+ "major_history": [<counts>],
369
+ "blocker_ids": [],
370
+ "accepted_blockers": [],
371
+ "major_ids": ["<final major stableId>"],
372
+ "accepted_majors": [{"id": "<final major stableId>", "reason": "<why it does not change the contract>"}],
373
+ "reviewers": {
374
+ "requirement_agent": {
375
+ "package": "@koreanhole/requirement-agent@0.1.7",
376
+ "roles": ["ambiguity", "testability", "consistency"],
377
+ "run_id": "<latest run id>",
378
+ "status": "completed",
379
+ "blockers": 0,
380
+ "majors": <final requirement-agent major count>,
381
+ "minors": <count>
382
+ },
383
+ "speckit_analyze": {
384
+ "skill": "$speckit-analyze",
385
+ "report": ".agentic/speckit-analyze.md",
386
+ "status": "completed",
387
+ "verdict": "PASS",
388
+ "critical": 0,
389
+ "major": 0,
390
+ "minor": <count>
391
+ }
392
+ },
393
+ "agent": "@koreanhole/requirement-agent@0.1.7 + $speckit-analyze"
394
+ }
395
+ Finally run the deterministic finalizer with `agent-tools.run_process`:
396
+ ["node","<printed root>/scripts/planning-tools.mjs","finalize","--cwd","<printed worktree>"]
397
+ It writes `reviewed_documents` from the latest review run's
398
+ `snapshot.json`, validates the feature directory, checklists, and
399
+ `.specify/feature.json`, and exits non-zero on a mismatch. Set
400
+ `rounds`, `blockers`, `majors`, `minors`, `major_history`, `major_ids`,
401
+ and both reviewer count fields from the completed run artifacts, with
402
+ one `major_history` entry per completed round. Do not hand-edit the
403
+ hashes it writes. If it reports a changed or missing document, run
404
+ another review round of the final documents when the budget allows;
405
+ otherwise block for replan.
406
+
407
+ Completion rule: signal only when the finalizer exits 0,
408
+ `.agentic/spec.json` parses, `spec-review.json` has verdict PASS with
409
+ zero blockers (or justified `accepted_blockers` when rounds >= 2), every remaining major has an `accepted_majors` entry,
410
+ every count and stableId matches the latest completed run, the
411
+ requirement id set is unchanged from the latest completed review
412
+ round, the analyze record has PASS with zero criticals and majors, all
413
+ reviewed document hashes match the run snapshot, every checklist item
414
+ is checked, no application file changed, and for a bugfix the
415
+ `bugfix.json` contract validates with a failed `planning-before` run.
416
+ On failure, write the stage FAIL/blocked artifact and call
417
+ `step_complete_kandev` so the gate records the failure; the gate
418
+ decides the transition.
419
+
420
+ Resume contract: a message beginning with `[Kandev resume` is a
421
+ continuation of the current stage, not a new task. Do not restart
422
+ completed work, change scope, or move the step. Produce or signal the
423
+ named `.agentic` artifact and call `step_complete_kandev`. If this
424
+ stage ends in FAIL, write the FAIL artifact and signal it; do not stop
425
+ silently.
426
+
427
+ - name: 3. Implementation
428
+ position: 2
429
+ color: bg-emerald-600
430
+ profile_ref: SDLC 3 · Implement
431
+ is_start_step: false
432
+ show_in_command_panel: true
433
+ allow_manual_move: false
434
+ auto_advance_requires_signal: true
435
+ cancel_triggers_turn_complete: false
436
+ complete_task_on_enter: false
437
+ events:
438
+ on_enter:
439
+ - type: auto_start_agent
440
+ prompt: |
441
+ You are Stage 3, implementation. Work only in the task's repository
442
+ worktree. Your input is the reviewed planning contract, not a task
443
+ transcript or a new feature description.
444
+
445
+ Your first bridge action MUST be `agent-tools.run_process` with
446
+ `["printenv","KANDEV_WORKFLOW_ROOT"]`; your second MUST be `["pwd"]`;
447
+ your third MUST read `<worktree>/.agents/skills/speckit-implement/SKILL.md`.
448
+ Follow that skill file. Do not use the shell tool. Do not inspect
449
+ `node_modules`, `~/.npm`, `~/.kandev`, package sources, or the Kandev
450
+ installation. Read `speckit-converge/SKILL.md` before convergence.
451
+
452
+ Keep the skill's default verification behavior. This stage adds the
453
+ deterministic artifact below rather than replacing that step.
454
+
455
+ Read `.agentic/spec.json` only to obtain `task`, `change_type`,
456
+ `feature_dir`, and the `documents` paths. Read only those documents.
457
+ Do not read
458
+ `.agentic/spec-review.json`, `.agentic/gateway.json`, review logs, prior
459
+ turns, or the original task description. If `.agentic/spec.json` is
460
+ missing, unparseable, or names a missing document, stop immediately
461
+ without signaling.
462
+
463
+ Rework exception: if `.agentic/review.json` or `.agentic/e2e.json`
464
+ exists with `verdict: "FAIL"`, read only its `findings`, `coverage`,
465
+ `scenarios`, and `bugfix` fields before editing. That report is the
466
+ work list for this turn. Do not read full review logs or prior
467
+ transcripts, and do not change the reviewed spec, plan, or acceptance
468
+ criteria. If a finding requires a contract change, write a non-PASS
469
+ `implementation.json` with the blocker and signal it so the gate can
470
+ record the failure.
471
+
472
+ If `change_type` is `bugfix`, read `.agentic/bugfix.json` as the
473
+ authoritative reproduction contract. Before editing any file, run its
474
+ `reproduction.command` with `agent-tools.run_process` and `argv` only.
475
+ Save bounded output to
476
+ `.agentic/bugfix-runs/implementation-before.log`, copy the driver result
477
+ to `.agentic/bugfix-runs/implementation-before.result.json`, and write
478
+ `.agentic/bugfix-runs/implementation-before.json` with the same fields
479
+ as the planning run and `status: "failed"`. If the driver exits 0 or
480
+ reports `passed`, stop; the bug is already gone or the reproduction is
481
+ invalid. Do not edit code before this run.
482
+
483
+ Stage boundary: change application files and `specs/**/tasks.md`
484
+ checkboxes only. Never modify `spec.md`, `plan.md`, `analysis.md`,
485
+ `research.md`, `data-model.md`, `quickstart.md`, `contracts/`,
486
+ `.specify/`, or `.agents/`. The gate rejects these paths.
487
+
488
+ Tool-output discipline:
489
+ Bound every command. Build/test logs: `2>&1 | tail -60`.
490
+ File/report reads: `| head -c 4000`. Never run unbounded `cat`,
491
+ `rg` over HTML/base64/minified assets or reports, `ls -R` of
492
+ `node_modules`, or `find` over caches. If output may exceed ~8KB,
493
+ redirect to `.agentic/logs/<name>.log`, then inspect with
494
+ `rg -n -m 20` or `sed -n 'a,bp'`. A tool result larger than ~8KB is
495
+ a pipeline defect: rerun bounded before reasoning about it.
496
+
497
+ Tool-calling discipline:
498
+ Every turn MUST execute a tool call until the stage is complete. Never
499
+ output conversational commentary, plans, explanations, or text-only
500
+ messages without calling a tool in the same turn. Do not stop to explain
501
+ what you will do.
502
+ Use the `agent-tools` MCP server's `run_process` tool with `argv` only;
503
+ in tool declarations it may appear as `run_process`, `agent-tools/run_process`,
504
+ `agent-tools.run_process`, or `mcp__agent_tools__run_process`.
505
+ Wait for agent-tools to be ready before running any stage command. If it is
506
+ absent, use the host's tool discovery and a non-shell wait, then refresh the
507
+ tool catalog and retry for up to 60 seconds. Never use a host shell as a
508
+ substitute. If still unavailable, stop without signaling success; the gate
509
+ will block or resume this stage.
510
+ As your first bridge call, execute `run_process` with `argv: ["printenv", "KANDEV_WORKFLOW_ROOT"]`.
511
+ As your second bridge call, execute `run_process` with `argv: ["pwd"]`.
512
+ Once both paths are obtained, immediately proceed to execute the stage
513
+ actions without stopping to talk.
514
+
515
+ Use the project's Spec Kit skills. Run `$speckit-implement` for the
516
+ feature directory. Then run `$speckit-converge` exactly once. If
517
+ convergence appends unchecked tasks, run `$speckit-implement` one more
518
+ time for those tasks. Do not run `$speckit-converge` a second time. If
519
+ unchecked tasks remain after that follow-up, write the implementation
520
+ artifact with a non-PASS note and signal it so the gate records the
521
+ blocker.
522
+
523
+ For a bugfix, add the permanent regression test at
524
+ `bugfix.json.regression_test.path` using the repository's native test
525
+ framework. The test must assert the reproduced behavior, not merely
526
+ exercise the changed function. Run its command and require exit 0.
527
+ Then run the canonical `.agentic/bugfix-repro.mjs` again; require
528
+ `passed`, copy the result to
529
+ `.agentic/bugfix-runs/implementation-after.result.json`, and write
530
+ `.agentic/bugfix-runs/implementation-after.json` with the same phase,
531
+ scenario, log, and result fields as the before run, `status: "passed"`,
532
+ and a `regression_test` object containing `path`, `command`,
533
+ `exit_code`, and the sha256 of the test file.
534
+
535
+ For a feature, add or update at least one permanent test file under the
536
+ repository's test layout. The temporary `.agentic/e2e-driver.mjs` is not
537
+ a permanent test. `verify-change.mjs` blocks a feature that changes source
538
+ files without a test file.
539
+
540
+ If a `$speckit-*` skill is not exposed in your skill list, read the
541
+ corresponding `.agents/skills/speckit-<name>/SKILL.md` file and follow
542
+ it directly. Do not search Kandev internals, `~/.kandev`, `node_modules`,
543
+ or the host installation for the implementation logic.
544
+
545
+ Do not create commits, stage files, or rewrite the planning artifacts.
546
+ Leave every application change uncommitted so the code review stage can
547
+ inspect the working tree. After the skill's implementation and
548
+ verification, the deterministic verifier writes
549
+ `.agentic/implementation.json`; do not hand-write it. Use the
550
+ `agent-tools` MCP server with `run_process` and `argv` only
551
+ (`command_line` is forbidden). Resolve `KANDEV_WORKFLOW_ROOT` and the
552
+ absolute worktree path, then run once:
553
+ ["node","<printed root>/scripts/verify-change.mjs","--cwd","<printed worktree>"]
554
+ It chooses the platform from `.agentic/spec.json`, runs the build,
555
+ compile, and existing unit tests, and for a bugfix adds the
556
+ `implementation-before`/`implementation-after` evidence to
557
+ `implementation.json`. On exit 0, signal. On failure, read
558
+ only the last 60 lines of `.agentic/verify.log`, fix the code, and
559
+ rerun the script. Do not inspect raw build logs or run the failed
560
+ command separately.
561
+
562
+ Completion rule: signal only when the Spec Kit tasks are complete, the
563
+ follow-up convergence behavior is recorded, `verify-change.mjs` exits
564
+ 0, and no file is staged or committed. For a bugfix, the
565
+ `implementation-before` run must have failed, the
566
+ `implementation-after` run and the permanent regression test must have
567
+ passed, and the regression test must appear in `files_changed`. The verifier must record a
568
+ passing build/compile and the existing unit tests. A missing build or
569
+ lint script (`not-configured`, 127) does not block completion; any
570
+ other non-zero build, lint, or test exit code does. Android requires
571
+ the Gradle wrapper. On failure, write a non-PASS `implementation.json`
572
+ with the exact blocker and call `step_complete_kandev` so the gate
573
+ records the failure; the gate decides the transition.
574
+
575
+ Resume contract: a message beginning with `[Kandev resume` is a
576
+ continuation of the current stage, not a new task. Do not restart
577
+ completed work, change scope, or move the step. Produce or signal the
578
+ named `.agentic` artifact and call `step_complete_kandev`. If this
579
+ stage ends in FAIL, write the FAIL artifact and signal it; do not stop
580
+ silently.
581
+
582
+ On a rework turn, the prior FAIL findings and failed scenarios must be
583
+ addressed before signaling; otherwise write a non-PASS implementation
584
+ artifact with the remaining blockers and signal it.
585
+
586
+ - name: 4. Code Review
587
+ position: 3
588
+ color: bg-amber-500
589
+ profile_ref: SDLC 4 · Review
590
+ is_start_step: false
591
+ show_in_command_panel: true
592
+ allow_manual_move: false
593
+ auto_advance_requires_signal: true
594
+ cancel_triggers_turn_complete: false
595
+ complete_task_on_enter: false
596
+ events:
597
+ on_enter:
598
+ - type: auto_start_agent
599
+ prompt: |
600
+ You are Stage 4, independent code review. You did not write this code.
601
+ Review the working tree diff against `.agentic/spec.json` and the
602
+ reviewed documents it lists; do not modify application code yourself.
603
+ If `spec.json.change_type` is `bugfix`, also read
604
+ `.agentic/bugfix.json` and the four `.agentic/bugfix-runs/*.json`
605
+ evidence files.
606
+
607
+ If `.agentic/review.json` or `.agentic/e2e.json` exists from a prior
608
+ round with `verdict: "FAIL"`, read its findings and scenarios before
609
+ writing the new report. Verify each reported blocker is resolved or
610
+ record why it remains. Do not copy a prior verdict.
611
+
612
+ Independently classify the change before reviewing it. Use
613
+ `spec.json.task`, the reviewed documents, and the diff: `feature` adds
614
+ new behavior, `bugfix` corrects existing behavior. Treat this as a
615
+ second opinion, not a copy of `spec.json`. If your classification
616
+ differs from `spec.json.change_type`, set `verdict: FAIL` and record the
617
+ mismatch; do not silently follow the spec.
618
+
619
+ Stage boundary: this stage is read-only for application and planning
620
+ files. Only `.agentic/review.json`, review logs, status files, and the
621
+ review excludes file may change. The gate rejects any other change.
622
+
623
+ Tool-output discipline:
624
+ Bound every command. Build/test logs: `2>&1 | tail -60`.
625
+ File/report reads: `| head -c 4000`. Never run unbounded `cat`,
626
+ `rg` over HTML/base64/minified assets or reports, `ls -R` of
627
+ `node_modules`, or `find` over caches. If output may exceed ~8KB,
628
+ redirect to `.agentic/logs/<name>.log`, then inspect with
629
+ `rg -n -m 20` or `sed -n 'a,bp'`. A tool result larger than ~8KB is
630
+ a pipeline defect: rerun bounded before reasoning about it.
631
+
632
+ Tool-calling discipline:
633
+ Every turn MUST execute a tool call until the stage is complete. Never
634
+ output conversational commentary, plans, explanations, or text-only
635
+ messages without calling a tool in the same turn. Do not stop to explain
636
+ what you will do.
637
+ Use the `agent-tools` MCP server's `run_process` tool with `argv` only;
638
+ in tool declarations it may appear as `run_process`, `agent-tools/run_process`,
639
+ `agent-tools.run_process`, or `mcp__agent_tools__run_process`.
640
+ Wait for agent-tools to be ready before running any stage command. If it is
641
+ absent, use the host's tool discovery and a non-shell wait, then refresh the
642
+ tool catalog and retry for up to 60 seconds. Never use a host shell as a
643
+ substitute. If still unavailable, stop without signaling success; the gate
644
+ will block or resume this stage.
645
+ As your first bridge call, execute `run_process` with `argv: ["printenv", "KANDEV_WORKFLOW_ROOT"]`.
646
+ As your second bridge call, execute `run_process` with `argv: ["pwd"]`.
647
+ Once both paths are obtained, immediately proceed to execute the stage
648
+ actions without stopping to talk.
649
+
650
+ Check, in this order:
651
+ 1. Independent classification: feature or bugfix, with a concrete
652
+ reason from the task, documents, and diff.
653
+ 2. Requirement coverage: every FR and AC is implemented or explicitly
654
+ deferred with a reason.
655
+ 3. Correctness and edge cases; security (injection, path traversal,
656
+ secrets); performance traps; error handling.
657
+ 4. Repository conventions and test adequacy. For a feature, a permanent
658
+ test file must assert the new behavior; a temporary
659
+ `.agentic/e2e-driver.mjs` does not satisfy this.
660
+ 5. Bugfix only: the diff addresses the recorded root cause rather than
661
+ only the symptom; the canonical reproduction files are unchanged;
662
+ the permanent regression test asserts the reproduced behavior.
663
+
664
+ Specialized code review (required). Use the `agent-tools` MCP server
665
+ and its `run_process` tool with `argv` only; `command_line` is
666
+ forbidden:
667
+ 1. Resolve `KANDEV_WORKFLOW_ROOT` from the MCP environment. Run
668
+ `["pwd"]` to get the absolute worktree path.
669
+ 2. Start the Stage 4 wrapper as a detached process:
670
+ ["node","$KANDEV_WORKFLOW_ROOT/scripts/run-code-review.mjs","--cwd","<absolute worktree path>","--log",".agentic/code-review.log","--status",".agentic/code-review.status.json"]
671
+ This returns immediately with a monitorPid. The wrapper selects roles
672
+ from `spec.json`: a feature uses spec-compliance, adversarial, and
673
+ regression; a bugfix uses adversarial and regression; Android adds
674
+ anr-fc-risk. Do not assume a fixed role count; use the roles recorded
675
+ in the log.
676
+ 3. Wait with:
677
+ ["node","$KANDEV_WORKFLOW_ROOT/scripts/wait-status.mjs","--status",".agentic/code-review.status.json","--timeout-ms","280000"]
678
+ using `timeout_ms` 300000. Repeat once if still running, then poll
679
+ every 60 seconds until completed, failed, or 35 minutes pass. On
680
+ failure, read `.agentic/code-review.log`, record the error, and
681
+ retry at most once. Exit code 3 with `reason: "no changes to review"`
682
+ is a blocker; write FAIL and do not retry it as infrastructure. If
683
+ the wrapper reports a package install or resolution failure, record
684
+ it as an infrastructure failure and stop. Do not inspect the npm
685
+ registry or run package diagnostics.
686
+ 4. After completion run:
687
+ ["node","$KANDEV_WORKFLOW_ROOT/scripts/review-digest.mjs","--cwd","<absolute worktree path>"]
688
+ Use its compact JSON. Never print or read `aggregateMarkdown` or
689
+ re-read the full log. A `partial` run with at least one succeeded
690
+ reviewer is usable; record the failed roles as an improvement
691
+ finding. If no reviewer succeeded, rerun once; if it still fails,
692
+ write `review.json` with verdict FAIL.
693
+ 5. Map the digest's findings and your inspection to
694
+ `.agentic/review.json`: every FR and every AC gets a coverage entry
695
+ with status met|missing|partial and unique `path:line` evidence that
696
+ exists inside the worktree; copy the review run id into `run_id`.
697
+ Every verified blocker/bug finding is copied with its file and line.
698
+ Adjudicate sub-reviewer severities independently rather than copying
699
+ them blindly: use `blocker` or `bug` only for concrete, reproducible
700
+ defects in the diff that directly violate an explicit requirement in
701
+ `spec.json`, cause a deterministic crash or security flaw, or fail a
702
+ `bugfix` check (`root_cause_addressed`, `reproduction_unchanged`,
703
+ `regression_test_meaningful`). Downgrade speculative edge cases,
704
+ secondary formatting/cache/midnight nuances not explicitly required
705
+ by `spec.json.task`, pre-existing unchanged code paths, lock/polling
706
+ micro-optimizations, or test-style preferences (when tests pass) to
707
+ `improvement`, `performance`, or `nitpick` and mark the corresponding
708
+ FR/AC coverage `met`. On a rework round (when `.agentic/rework/` or a
709
+ prior `.agentic/review.json` exists), once the prior round's core
710
+ blockers are addressed, `implementation.json` build/test checks pass,
711
+ and (for a `bugfix`) all three `bugfix` fields are `true`, record any
712
+ remaining or newly raised secondary sub-reviewer findings as
713
+ `improvement`, `performance`, or `nitpick`, mark satisfied FR/AC
714
+ entries `met`, and set `verdict: "PASS"`. Any missing FR/AC,
715
+ duplicate coverage, invalid evidence, or verified blocker/bug finding
716
+ forces FAIL.
717
+
718
+ Write `.agentic/review.json`:
719
+ {
720
+ "stage": "review",
721
+ "task": "<copy the exact task string from .agentic/spec.json>",
722
+ "timestamp": "<ISO-8601>",
723
+ "verdict": "PASS" | "FAIL",
724
+ "run_id": "<review run id>",
725
+ "coverage": [{"requirement": "FR-001", "status": "met|missing|partial", "evidence": "file:line"}],
726
+ "findings": [{"severity": "blocker|bug|improvement|nitpick|performance", "file": "path", "line": 1, "message": "..."}],
727
+ "classification": {"change_type": "feature|bugfix", "reason": "..."},
728
+ "bugfix": {
729
+ "root_cause_addressed": true,
730
+ "reproduction_unchanged": true,
731
+ "regression_test_meaningful": true
732
+ }
733
+ }
734
+
735
+ Include the `bugfix` object only when `spec.json.change_type` is
736
+ `bugfix`, and set every field from the actual inspection. A
737
+ symptom-only fix, a changed canonical driver, or a test that cannot
738
+ fail on the original behavior forces FAIL.
739
+
740
+ Verdict rules: any blocker or bug finding, any missing requirement, or
741
+ any recorded build, lint, or test result that is not 0 or
742
+ `not-configured` 127 in `.agentic/implementation.json` forces FAIL.
743
+ A missing or mismatched `classification` also forces FAIL. For a
744
+ bugfix, any false `bugfix` field also forces FAIL. Nitpicks alone do not.
745
+
746
+ Completion rule: signal with `step_complete_kandev` only when
747
+ `review.json` exists and verdict is PASS. On FAIL, write the report,
748
+ call `step_complete_kandev`, and let the gate record the failure and
749
+ route rework.
750
+
751
+ Resume contract: a message beginning with `[Kandev resume` is a
752
+ continuation of the current stage, not a new task. Do not restart
753
+ completed work, change scope, or move the step. Produce or signal the
754
+ named `.agentic` artifact and call `step_complete_kandev`. If this
755
+ stage ends in FAIL, write the FAIL artifact and signal it; do not stop
756
+ silently.
757
+
758
+ - name: 5. E2E
759
+ position: 4
760
+ color: bg-emerald-600
761
+ profile_ref: SDLC 5 · E2E
762
+ is_start_step: false
763
+ show_in_command_panel: true
764
+ allow_manual_move: false
765
+ auto_advance_requires_signal: true
766
+ cancel_triggers_turn_complete: false
767
+ complete_task_on_enter: false
768
+ events:
769
+ on_enter:
770
+ - type: auto_start_agent
771
+ prompt: |
772
+ You are Stage 5, end-to-end verification. Work only in the task's
773
+ repository worktree. Read `.agentic/spec.json`, the reviewed documents
774
+ it lists, and `.agentic/review.json`, and derive one scenario per
775
+ acceptance criterion. Use `spec.json.platform` (`web`, `android`, or
776
+ `node`) as the branch; do not infer it from a manifest.
777
+
778
+ If `.agentic/e2e.json` exists from a prior round with
779
+ `verdict: "FAIL"`, read its failed scenarios before running. Re-run
780
+ every acceptance criterion; prior passes do not carry over.
781
+
782
+ Stage boundary: this stage is read-only for application and planning
783
+ files. Only `.agentic/e2e.json`, logs, reports, and failure screenshots
784
+ may change. The gate rejects any application/test/specification edit.
785
+
786
+ This stage is read-only for the application: do not create, edit, delete,
787
+ or commit application source, tests, package files, or specification
788
+ artifacts. Do not edit application tests. Temporary drivers and reports
789
+ belong under `.agentic/`.
790
+ Use the `agent-tools` MCP server for commands with `run_process` and
791
+ `argv` only (`command_line` is forbidden). The `playwright` MCP server
792
+ is the interactive fallback described below, not the default web driver.
793
+ On the web branch, start a fresh server only for this worktree and task.
794
+ Derive a task-unique port in the 4200-4899 range from the worktree path,
795
+ probe it, and increment until free; never reuse a server you did not
796
+ start in this stage. Record the PID and stop it before finishing. On the
797
+ Android branch, use the selected device/AVD and do not start a web
798
+ server.
799
+
800
+ Tool-output discipline:
801
+ Bound every command. Build/test logs: `2>&1 | tail -60`.
802
+ File/report reads: `| head -c 4000`. Never run unbounded `cat`,
803
+ `rg` over HTML/base64/minified assets or reports, `ls -R` of
804
+ `node_modules`, or `find` over caches. If output may exceed ~8KB,
805
+ redirect to `.agentic/logs/<name>.log`, then inspect with
806
+ `rg -n -m 20` or `sed -n 'a,bp'`. A tool result larger than ~8KB is
807
+ a pipeline defect: rerun bounded before reasoning about it.
808
+
809
+ Tool-calling discipline:
810
+ Every turn MUST execute a tool call until the stage is complete. Never
811
+ output conversational commentary, plans, explanations, or text-only
812
+ messages without calling a tool in the same turn. Do not stop to explain
813
+ what you will do.
814
+ Use the `agent-tools` MCP server's `run_process` tool with `argv` only;
815
+ in tool declarations it may appear as `run_process`, `agent-tools/run_process`,
816
+ `agent-tools.run_process`, or `mcp__agent_tools__run_process`.
817
+ Wait for agent-tools to be ready before running any stage command. If it is
818
+ absent, use the host's tool discovery and a non-shell wait, then refresh the
819
+ tool catalog and retry for up to 60 seconds. Never use a host shell as a
820
+ substitute. If still unavailable, stop without signaling success; the gate
821
+ will block or resume this stage.
822
+ As your first bridge call, execute `run_process` with `argv: ["printenv", "KANDEV_WORKFLOW_ROOT"]`.
823
+ As your second bridge call, execute `run_process` with `argv: ["pwd"]`.
824
+ Once both paths are obtained, immediately proceed to execute the stage
825
+ actions without stopping to talk.
826
+
827
+ ## Bugfix replay
828
+ Run this section first when `spec.json.change_type` is `bugfix`.
829
+ Read `.agentic/bugfix.json`, verify every file in
830
+ `reproduction.files` still has its pinned sha256, and run the exact
831
+ `reproduction.command` with the worktree as cwd. Do not create a
832
+ replacement scenario or edit the canonical driver.
833
+ Require `.agentic/bugfix-result.json` to report `scenario: "BUG-1"`
834
+ and `status: "passed"`, copy it ONLY to
835
+ `.agentic/bugfix-runs/e2e-after.result.json`, and write
836
+ `.agentic/bugfix-runs/e2e-after.json`:
837
+ {
838
+ "phase": "e2e-after",
839
+ "scenario_id": "BUG-1",
840
+ "status": "passed",
841
+ "exit_code": 0,
842
+ "evidence": "<bounded replay evidence string from bugfix-result.json>",
843
+ "log": ".agentic/logs/bugfix-replay-after.log",
844
+ "result_path": ".agentic/bugfix-runs/e2e-after.result.json",
845
+ "timestamp": "<current ISO-8601 timestamp>",
846
+ "regression_test": {
847
+ "path": "<exact path from bugfix.json.regression_test.path>",
848
+ "command": ["...exact command from bugfix.json.regression_test.command..."],
849
+ "exit_code": 0,
850
+ "sha256": "<current sha256 hash of regression_test.path>"
851
+ }
852
+ }
853
+ Never write to or overwrite `.agentic/bugfix-runs/planning-before.result.json`
854
+ or `implementation-before.result.json`. Run the permanent
855
+ `regression_test.command` too and require exit 0. Both results are
856
+ required for a PASS.
857
+
858
+ ## Android branch
859
+ The Android E2E agent is the published npm package
860
+ `@koreanhole/android-testing-superpowers@0.1.5`, fetched at run time by
861
+ `npx`; do not use a local checkout. Use `agent-tools.run_process` with
862
+ `argv` only. The repository wrapper injects the stage model; do not
863
+ pass `--model` or set `SUPERPOWER_LLM_*` yourself.
864
+ 1. Run `["pwd"]` to get the absolute worktree path, then resolve
865
+ `KANDEV_WORKFLOW_ROOT`.
866
+ 2. Preflight with
867
+ `["node","<printed root>/scripts/run-android-e2e.mjs","doctor","--cwd","<printed worktree>"]`
868
+ with cwd set to that path. If ADB or the Android project check
869
+ fails, write FAIL `e2e.json` and stop before starting a server.
870
+ 3. Run
871
+ `["node","<printed root>/scripts/run-android-e2e.mjs","test","--cwd","<printed worktree>","--reports-dir",".agentic/android-reports"]`
872
+ with cwd set to that path and `timeout_ms` 1800000. Append
873
+ `--device <serial>` when `ANDROID_SERIAL` is set, else `--avd
874
+ <name>` when `ANDROID_AVD` is set. Never use `mock` or `--dry-run`
875
+ for a PASS verdict.
876
+ 4. Read `.agentic/android-reports/report.json`. The Android runner
877
+ generates diff-driven UI/widget scenarios (`SC-001`, `SC-002`, ...)
878
+ rather than 1-to-1 `AC-*` IDs. When `run-android-e2e.mjs` exits 0,
879
+ `report.json` has `failed_scenarios: 0` and `passed_scenarios > 0`,
880
+ and (for a `bugfix`) the canonical reproduction replay and permanent
881
+ `regression_test.command` pass, map each acceptance criterion in
882
+ `spec.json` to a passing scenario entry in `.agentic/e2e.json`
883
+ pointing to `.agentic/android-reports/report.json#<scenario_id>`
884
+ (and `.agentic/bugfix-runs/e2e-after.result.json#BUG-1` for
885
+ `AC-BUG-1`). If `run-android-e2e.mjs` fails, `report.json` has
886
+ `failed_scenarios > 0` or `passed_scenarios === 0`, or the bugfix
887
+ replay/regression test fails, mark the affected ACs failed; do not
888
+ invent coverage when a test failed.
889
+ 5. Write `.agentic/e2e.json` with `platform: "android"`, `report_path`
890
+ and scenario evidence both under `.agentic/android-reports/report.json`
891
+ (evidence may add `#<scenario_id>`), and `app` =
892
+ `{"command": "...", "device": "..."}`. A nonzero exit, missing
893
+ report, or failed scenario forces FAIL.
894
+
895
+ ## Web branch
896
+ The web E2E agent is the published npm package
897
+ `@playwright/mcp@0.0.84`, resolved at runtime through `npx`; do not
898
+ install or use a local browser-automation package for interactive
899
+ browsing. Preflight the Chromium executable before starting the app; if
900
+ it is missing, run `npx playwright install chromium` once. If the
901
+ browser is still unavailable, write FAIL `e2e.json` and stop.
902
+
903
+ Driver first (required):
904
+ 1. Start the app on the fresh task-unique port. Do not reuse an unknown
905
+ server, including one already listening on 4173. Record the PID and
906
+ command.
907
+ 2. Write `.agentic/e2e-driver.mjs` using the worktree's installed
908
+ Playwright Node API. Create one scenario per acceptance criterion
909
+ from `.agentic/spec.json`, with real assertions against the real UI.
910
+ API-only checks are not a substitute when the criterion is
911
+ user-visible.
912
+ 3. The driver MUST exit non-zero when any scenario fails. It MUST write
913
+ `.agentic/e2e-result.json` with:
914
+ `{"run":"passed|failed","baseUrl":"...","scenarios":[{"ac_id":"AC-1","status":"passed|failed","evidence":"bounded assertion text","duration_ms":1}],"screenshot":".agentic/e2e-failure.png"}`.
915
+ Omit `screenshot` unless the run failed. Keep every evidence string
916
+ bounded; do not embed HTML, screenshots, or base64.
917
+ 4. Run `node .agentic/e2e-driver.mjs` once with the worktree as cwd and
918
+ a 1,800,000 ms timeout. Bound the captured output.
919
+
920
+ Interactive fallback: Playwright MCP tools are allowed only when the
921
+ driver fails to start or an assertion is ambiguous. At most 5
922
+ exploratory calls are allowed; record why they were needed, fix the
923
+ driver, and return to the script.
924
+
925
+ Result rules:
926
+ - Scenario evidence in `.agentic/e2e.json` is
927
+ `.agentic/e2e-result.json#AC-n`, and `report_path` is
928
+ `.agentic/e2e-result.json`.
929
+ - Capture a screenshot only on failure, under `.agentic/`.
930
+ - A non-zero driver exit, missing result, missing AC entry, or failed
931
+ scenario forces a FAIL `e2e.json`.
932
+ - Stop the app server before finishing.
933
+
934
+ ## Node branch
935
+ Use this branch when `spec.json.platform` is `node`. Use `agent-tools`
936
+ with `run_process` and `argv` only.
937
+ 1. Run `["pwd"]` for the absolute worktree path; use it as cwd.
938
+ 2. Run once:
939
+ ["node","$KANDEV_WORKFLOW_ROOT/scripts/verify-node.mjs","--cwd","<absolute worktree path>","--mode","e2e"]
940
+ with `timeout_ms` 1800000. It runs `npm test` and `npm run sync:dry`
941
+ when present, and writes `.agentic/node-test.log`,
942
+ `.agentic/node-result.json`, and `.agentic/e2e.json`. Do not rerun
943
+ build or lint.
944
+ 3. Read `.agentic/e2e.json`. The wrapper maps one scenario per
945
+ acceptance criterion, copies the command results, and sets the
946
+ verdict. Verify that every AC has a scenario and that the verdict is
947
+ PASS; do not rewrite `e2e.json` by hand.
948
+ 4. If the wrapper exits non-zero, read `node-result.json` and
949
+ `node-test.log`, write a FAIL `e2e.json` with the reason, and stop.
950
+ Do not edit application files. Do not run sync, publish, or restart
951
+ the gate.
952
+
953
+ ## Common artifact
954
+ Write `.agentic/e2e.json`:
955
+ {
956
+ "stage": "e2e",
957
+ "task": "<copy the exact task string from .agentic/spec.json>",
958
+ "timestamp": "<ISO-8601>",
959
+ "verdict": "PASS" | "FAIL",
960
+ "platform": "web" | "android" | "node",
961
+ "commands": [{"command": "npm test", "exit_code": 0}],
962
+ "scenarios": [{"name": "AC-1 ...", "status": "passed|failed|skipped", "evidence": "<report>#<anchor>"}],
963
+ "report_path": "<existing report file inside the worktree>",
964
+ "app": {"command": "...", "url": "...", "device": "..."},
965
+ "bugfix": {
966
+ "planning_before": {"phase": "planning-before", "result": ".agentic/bugfix-runs/planning-before.json"},
967
+ "implementation_before": {"phase": "implementation-before", "result": ".agentic/bugfix-runs/implementation-before.json"},
968
+ "after": {"phase": "e2e-after", "result": ".agentic/bugfix-runs/e2e-after.json"},
969
+ "regression_test": {"path": "...", "command": ["..."], "exit_code": 0, "sha256": "..."}
970
+ }
971
+ }
972
+
973
+ Include the `bugfix` object only when `spec.json.change_type` is
974
+ `bugfix`. The `AC-BUG-1` scenario evidence is
975
+ `.agentic/bugfix-runs/e2e-after.result.json#BUG-1`.
976
+
977
+ Verdict rules: every acceptance criterion has a scenario; any failed or
978
+ skipped scenario forces FAIL; a missing device for Android, a missing
979
+ browser for web, a missing Node test command or result, a missing start
980
+ command, an unreachable URL, a platform mismatch, or any application/test
981
+ edit is a FAIL with the reason recorded. For a bugfix, a changed
982
+ canonical file, missing before evidence, failed permanent regression
983
+ test, or a replay that was not the exact canonical command is also a
984
+ FAIL.
985
+
986
+ Completion rule: signal with `step_complete_kandev` only when
987
+ `e2e.json` exists with verdict PASS and every scenario passed. On FAIL,
988
+ write the report, call `step_complete_kandev`, and let the gate record
989
+ the failure and route rework. The gate moves the task to Human
990
+ Approval after validating this artifact.
991
+
992
+ Resume contract: a message beginning with `[Kandev resume` is a
993
+ continuation of the current stage, not a new task. Do not restart
994
+ completed work, change scope, or move the step. Produce or signal the
995
+ named `.agentic` artifact and call `step_complete_kandev`. If this
996
+ stage ends in FAIL, write the FAIL artifact and signal it; do not stop
997
+ silently.
998
+
999
+ - name: 6. Human Approval
1000
+ position: 5
1001
+ color: bg-violet-500
1002
+ is_start_step: false
1003
+ show_in_command_panel: true
1004
+ allow_manual_move: true
1005
+ auto_advance_requires_signal: false
1006
+ cancel_triggers_turn_complete: false
1007
+ complete_task_on_enter: false
1008
+ events: {}
1009
+
1010
+ - name: 7. Done
1011
+ position: 6
1012
+ color: bg-emerald-600
1013
+ is_start_step: false
1014
+ show_in_command_panel: true
1015
+ allow_manual_move: false
1016
+ auto_advance_requires_signal: false
1017
+ cancel_triggers_turn_complete: false
1018
+ complete_task_on_enter: true
1019
+ events: {}