@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
package/README.md CHANGED
@@ -1,3 +1,368 @@
1
- # Temporary Holding Version
1
+ # Kandev Workflow Config — Agentic SDLC
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Configuration-as-code for a five-stage agentic software lifecycle with a human approval lane on
4
+ [Kandev](https://kandev.ai). Agent gateways → Spec Kit planning and document review →
5
+ clean-context implementation → independent review → end-to-end verification, with a
6
+ hard fail-fast gate at every step.
7
+
8
+ - **Kandev core is untouched.** Only `config.yaml`, portable workflow YAML, agent
9
+ profiles, and the external MCP/HTTP surfaces are used.
10
+ - **npm-distributed agents only.** All stages run the `@openai/codex` runtime brought by `codex-acp`;
11
+ the gateway adapters and `$speckit-*` skills are deterministic setup/planning
12
+ surfaces, not local review agents. E2E adds `@playwright/mcp` and
13
+ `@playwright/test`.
14
+ - **Git is the source of truth.** `npm run sync` reconciles a live instance to the
15
+ committed definition and is idempotent; UI edits are drift.
16
+
17
+ ## npm bundle
18
+
19
+ ```bash
20
+ npm install -g @koreanhole/kandev
21
+ kandev
22
+ ```
23
+
24
+ On the first server start, the `kandev` wrapper waits for the loopback endpoint and runs
25
+ the bundled workflow sync automatically. Set `KANDEV_AUTO_SYNC=0` to disable it. If the
26
+ automatic sync fails because `codex-acp` is not ready yet, run `kandev-config sync`
27
+ manually after Kandev is up.
28
+
29
+ `@koreanhole/kandev` installs Kandev 0.98.0, this repository's runtime config, the
30
+ three sub-agent packages, and `@agentclientprotocol/codex-acp@2.5.0`. `codex-acp` brings
31
+ its compatible `@openai/codex` transitively. The bundle exposes `codex-acp`. The postinstall installs
32
+ `specify-cli==1.2.0` with `uv` or `pipx` when `specify` is missing. If it cannot install
33
+ or verify `specify`, the npm install fails. Set `KANDEV_SKIP_PREREQ_INSTALL=1` only when
34
+ you intentionally manage `specify` yourself. Codex authentication remains a manual
35
+ prerequisite. `kandev` forwards to the original CLI; `kandev-config` applies and verifies
36
+ the bundled config. Gate and baseline state live under the
37
+ installed package's `.cache`; after upgrading the package, rerun
38
+ `kandev-config baseline`.
39
+
40
+ ## Requirements
41
+
42
+ - Kandev 0.98.x running on the same host, bound to loopback.
43
+ - Node.js 22+.
44
+ - Codex CLI authenticated as the Kandev service user (`codex exec "ok"` succeeds).
45
+ Authentication is not automated by the package.
46
+ - `specify` CLI on PATH for the Stage 1 gateway. The npm postinstall installs
47
+ `specify-cli==1.2.0` with `uv` or `pipx` when it is missing and fails the install if it
48
+ still cannot verify `specify`. Install `uv`, `pipx`, or `specify-cli==1.2.0` before the
49
+ npm install, or set `KANDEV_SKIP_PREREQ_INSTALL=1` if you manage it yourself.
50
+ - `@agentclientprotocol/codex-acp@2.5.0` is installed by the bundle and exposed as
51
+ `codex-acp`. Kandev's `codex-acp` agent must still be configured and ready;
52
+ `kandev-config sync` checks it.
53
+ - `gh` authenticated for the one-time repository setup.
54
+
55
+ ## Source checkout
56
+
57
+ ```bash
58
+ git clone git@github.com:koreanhole/kandev-workflow-config.git
59
+ cd kandev-workflow-config
60
+ npm ci
61
+ cp .env.example .env # optional overrides; no secret is required to sync
62
+ ```
63
+
64
+ ## Apply
65
+
66
+ ```bash
67
+ npm run sync # create/update profiles + workflow, bind steps
68
+ npm run sync # must print only "unchanged"
69
+ npm run baseline # record the immutable Kandev install (once per install/upgrade)
70
+ npm run gate # keep running in another terminal (completion gate)
71
+ npm run verify # all checks must be OK
72
+ npm run measure # read-only token usage from the local Kandev database
73
+ ```
74
+
75
+ `kandev` already runs the sync automatically for `run`/`start` and no-subcommand
76
+ launches. Use `kandev-config sync` to reapply after config changes. The installed
77
+ equivalents are `kandev-config sync`, `kandev-config sync --dry-run`,
78
+ `kandev-config baseline`, `kandev-config gate`, `kandev-config verify`, and
79
+ `kandev-config measure`. Automatic sync does not run for `dev`, `service`, `--help`, or
80
+ `--version`.
81
+
82
+ `sync` never deletes profiles or a workflow. Extra steps are reported as a conflict and
83
+ left untouched; `--prune` is refused while any task exists and only removes extra steps
84
+ after the workflow is empty. Steps are updated in place so existing tasks keep their
85
+ position. `baseline` is required before `verify`; rerun it after every Kandev upgrade.
86
+ Exit codes: `0` converged, `1` live failure, `2` validation failure.
87
+
88
+ `npm run e2e:contract` runs a token-free agent-stage contract test: the real gate,
89
+ artifact validators, stage boundaries, and `verify-change.mjs` are exercised against a
90
+ temporary fixture with no model calls.
91
+
92
+ An existing four-stage workflow must be migrated once before the first five-stage sync:
93
+
94
+ ```bash
95
+ npm run migrate:legacy
96
+ npm run sync
97
+ ```
98
+
99
+ The migration reuses the legacy step IDs, inserts Agent Gateway, and refuses while any
100
+ task is active.
101
+
102
+ An existing five-stage workflow must then run the approval migration once:
103
+
104
+ ```bash
105
+ npm run migrate:approval
106
+ npm run sync
107
+ ```
108
+
109
+ It renames `6. Done` to `7. Done`, inserts `6. Human Approval`, and reorders the steps.
110
+
111
+ ## npm release
112
+
113
+ The package is published from this repository. Publish the Android sub-agent first when
114
+ its pin changes, then refresh the lockfile and publish the bundle:
115
+
116
+ ```bash
117
+ npm login
118
+ (cd agents/android-testing-superpowers && npm run release)
119
+ npm install --package-lock-only
120
+ npm test
121
+ npm publish --access public
122
+ ```
123
+
124
+ The tarball contains only `bin/`, the runtime config, `scripts/`, and this README. It
125
+ excludes `agents/`, `specs/`, `test/`, and `.cache/`.
126
+
127
+ ## Pipeline
128
+
129
+ | Step | Profile | Artifact |
130
+ | --- | --- | --- |
131
+ | 1. Agent Gateway | `SDLC 1 · Gateway` | `.agentic/gateway.json` |
132
+ | 2. Planning | `SDLC 2 · Planning` | `.agentic/spec.json`, `.agentic/spec-review.json`, `.agentic/speckit-analyze.md`, optional `.agentic/bugfix.json` |
133
+ | 3. Implementation | `SDLC 3 · Implement` | `.agentic/implementation.json`, `.agentic/bugfix-runs/` for bugfixes |
134
+ | 4. Code Review | `SDLC 4 · Review` | `.agentic/review.json` |
135
+ | 5. E2E | `SDLC 5 · E2E` | `.agentic/e2e.json` |
136
+ | 6. Human Approval | — | manual lane; a person reviews the verified worktree/PR |
137
+ | 7. Done | — | terminal lane; `complete_task_on_enter` |
138
+
139
+ Stages 1-5 set `auto_advance_requires_signal: true`, but the workflow itself has no
140
+ transition actions. `scripts/gate.mjs` watches tasks whose turn ended, validates the stage
141
+ artifact (`verdict: PASS`, AC coverage, scenario status, build/lint codes) and only then
142
+ moves the task. Missing or invalid artifacts leave it in place. A valid `review.json` or
143
+ `e2e.json` with `verdict: FAIL` is a rework signal: when `config/pipeline.json` sets
144
+ `rework.max_attempts` to a positive number, the gate moves the task back to Implementation
145
+ and logs the attempt. After the cap it blocks for human review. Omit the policy or set it
146
+ to `0` for fail-fast-only behavior. The gate keeps the Planning pins (`spec.json`,
147
+ `bugfix.json`, and reproduction files) across every later transition. Agent stages 1-5
148
+ disable manual moves; the gate owns those transitions. Human Approval is the only manual
149
+ lane: a person reviews the verified worktree and moves the task to Done. No agent can
150
+ signal directly into Done.
151
+
152
+ All five stages and the default workspace profile (`DeepSeek V4.1 Flash`) run on `combo/deepseek-v4.1-flash-auto`
153
+ with `reasoning_effort: "xhigh"`, including Stage 5 E2E. The same stage model is injected
154
+ into the child agents through each profile's `agent-tools` environment, so the requirement
155
+ agent, code review roles, and Android E2E agent do not fall back to their package
156
+ defaults. The resume policy below bounds stalled-turn recovery.
157
+
158
+ Live E2E runs (`docs/token-free-e2e.md` layer 4) lower that model's reasoning effort to
159
+ `low`, its lowest supported value. The token-free contract and no-agent probe never call
160
+ a model, so the setting does not apply there.
161
+
162
+ The gate also resumes a stage that ends without its artifact. It sends a self-contained
163
+ `[Kandev resume]` prompt to the same session through `message_task_kandev`, or creates a
164
+ replacement session with `spawn_session_kandev` when every session is terminal. It never
165
+ moves a task; the artifact validators remain the only transition authority. The policy in
166
+ `config/pipeline.json` allows three attempts per task and stage boundary, with a
167
+ two-minute cooldown. A `RUNNING`/`STARTING` session is left alone while its last message
168
+ is within the stage idle window (15 minutes; 30 minutes for Code Review and E2E). A truly
169
+ hung session is settled by Kandev's stall sweep, so `config/config.yaml` sets
170
+ `tasks.stallDetectionThreshold: "10m"`; apply the same value to the live service and
171
+ restart Kandev once when no task is mid-turn. The current headless launch does not inject
172
+ `config/config.yaml` into the backend automatically, so set
173
+ `KANDEV_TASK_STALL_DETECTION_THRESHOLD=10m` in the launch environment as well. After the
174
+ third failed attempt the gate blocks for human review. The gate discovers the advertised
175
+ MCP tools first; if the connected Kandev build does not expose the message/spawn tool,
176
+ resume is treated as unavailable and no resume failure is recorded.
177
+
178
+ `rework.max_attempts` lives in `config/pipeline.json` because rework is an external gate
179
+ policy, not a Kandev transition action. The gate counts `decision: "rework"` entries in
180
+ `.cache/gate-log.jsonl`; the cap is per task. A FAIL artifact older than the current stage
181
+ boundary is treated as stale and never starts a new rework. When the gate routes back, it
182
+ archives the prior `implementation.json` (and the prior `review.json` after an E2E failure)
183
+ under `.agentic/rework/` and removes the live copy, so a rework turn that stops without
184
+ writing fresh evidence cannot advance on the old PASS artifact.
185
+
186
+ The gateway stage is generic. `config/gateways.json` lists enabled adapters; the current
187
+ `speckit` adapter installs Codex Spec Kit skills when `.specify` or `.agents/skills` is
188
+ missing and preserves an existing default integration. Future gateways add a module and a
189
+ config entry without changing the workflow prompt.
190
+
191
+ Implementation starts in a new session with no task prompt. It reads `.agentic/spec.json`
192
+ only for the reviewed `documents` list, runs `$speckit-implement`, runs
193
+ `$speckit-converge` once, and runs one follow-up `$speckit-implement` only when
194
+ convergence appended unchecked tasks. The code review stage sees the application diff,
195
+ not `specs/` planning evidence.
196
+
197
+ Stage 3 follows `$speckit-implement`'s normal implementation and verification. A feature
198
+ that changes source files must add or update a permanent test file; the temporary
199
+ `.agentic/e2e-driver.mjs` is not a permanent test. After
200
+ that, `scripts/verify-change.mjs` writes the deterministic `implementation.json`
201
+ artifact and leaves the full output in `.agentic/verify.log`. The agent reads only the
202
+ last 60 lines of that log when the verifier fails.
203
+
204
+ ### Bugfix path
205
+
206
+ Planning writes `change_type` (`feature` or `bugfix`) and a classification reason in
207
+ `spec.json`. A bugfix also writes `.agentic/bugfix.json` with the symptom, the canonical
208
+ E2E driver, pinned file hashes, a `path:line` root cause, and the permanent regression
209
+ test. It must run `.agentic/bugfix-repro.mjs` and record a failed `planning-before` run
210
+ before `$speckit-plan`. Stage 3 replays the same driver before any edit, adds the native
211
+ regression test, replays after the fix, and records both results. Stage 5 replays the
212
+ same driver and the permanent test. The gate pins `spec.json`, `bugfix.json`, and every
213
+ reproduction file at the Planning transition; a changed canonical file blocks the task.
214
+
215
+ Feature classification is checked twice. First, the gate rejects a `feature` task whose
216
+ text carries an explicit bug marker (`[bug]`, `bug:`, an issue reference, or a Korean
217
+ bug/error word). Second, Stage 4 independently classifies the change and the gate fails
218
+ the review when that classification differs from `spec.json`.
219
+
220
+ The bugfix path does not add a workflow stage or change the pinned npm agents. It uses
221
+ the existing execution profile, `$speckit-*` skills, code reviewer, and Android test
222
+ package.
223
+
224
+ Each stage is write-isolated by the external gate. Gateway may only create `.specify/`,
225
+ `.agents/`, and its own artifact. Planning may only create `specs/` and
226
+ `.specify/feature.json`. Implementation may change application files and `tasks.md`
227
+ checkboxes. Code Review and E2E are read-only for the application and planning documents;
228
+ their reports live under `.agentic/`. The gate snapshots the worktree after each successful
229
+ transition and rejects out-of-stage paths.
230
+
231
+ ## Token controls
232
+
233
+ All five agent-stage prompts share one bounded-output rule: build/test logs end in
234
+ `2>&1 | tail -60`, file reads end in `| head -c 4000`, and any command that may
235
+ exceed 8 KB writes to `.agentic/logs/` first. A tool result larger than 8 KB is a
236
+ pipeline defect and must be rerun bounded.
237
+
238
+ Stage 2 uses `$speckit-specify`, `$speckit-clarify`, `$speckit-plan`, and
239
+ `$speckit-tasks`, then reviews the feature directory with the pinned requirement agent
240
+ (ambiguity, testability, consistency) and one `$speckit-analyze` pass. Three successful
241
+ rounds are the maximum. The planning gate verifies reviewed-document hashes, checklist
242
+ completion, `feature.json`, and the analyze report before implementation. Stage 2 and
243
+ Stage 4 wait with `scripts/wait-status.mjs` instead of polling every 20 seconds.
244
+ The requirement agent receives `--model` from `KANDEV_STAGE_MODEL`; a missing or invalid
245
+ model stops the wrapper before it spawns the package. After two completed review rounds,
246
+ the `FR-*`/`AC-*`/`SC-*` id set from the latest completed round is frozen and each reviewed
247
+ document has a bounded remediation growth budget. New behavior requires a replan instead
248
+ of expanding the documents inside the review loop. The finalizer records hashes from the
249
+ latest review run's immutable `snapshot.json`, not from the current files, and binds
250
+ `rounds`, `major_history`, counts, and major finding stable ids to the completed run artifacts.
251
+ The requirement agent merges cross-role findings at shared citation loci and emits a
252
+ `stableId`; the gate prefers it over the renumbered `F-*` display id. A major count may rise
253
+ between rounds when the reviewer reviews revised text; PASS requires zero blockers and a
254
+ reason for every remaining major, not a decreasing count. Every listed
255
+ document, including `analysis.md`, must be final before the final review run; any edit
256
+ after it invalidates the snapshot and requires another round.
257
+
258
+ Stage 3 runs `scripts/verify-change.mjs` once after the skill's normal verification. It
259
+ runs configured npm build/lint/test scripts for Node and Web, or `./gradlew assembleDebug` plus
260
+ `./gradlew testDebugUnitTest` for Android, and writes `implementation.json` plus
261
+ `.agentic/verify.log`. Stage 5's Node branch still uses
262
+ `scripts/verify-node.mjs --mode e2e` for its final acceptance run and writes
263
+ `node-result.json` plus `node-test.log`.
264
+
265
+ Stage 4 runs the code reviewer through the repository-owned `scripts/codex-medium`
266
+ shim. The shim injects `model_reasoning_effort="medium"` while preserving argv and
267
+ exit status. Every selected role is launched as `codex:<KANDEV_STAGE_MODEL>`, so the
268
+ reviewer package cannot use its own default model. The wrapper disables Codex ACP for
269
+ that invocation, logs the selected CLI transport, model, and effort before spawning, and
270
+ fails if the shim or stage model is missing. Before review,
271
+ it writes `.agentic/review-excludes.txt` and injects it through
272
+ `GIT_CONFIG_*` so logs and derived artifacts never enter the application diff;
273
+ `.agentic/spec.json` remains the authoritative contract. After review,
274
+ `scripts/review-digest.mjs` produces a compact JSON digest; the stage must not read
275
+ `aggregateMarkdown` or the full log. Package install failures are infrastructure
276
+ failures and must not be debugged through the npm registry.
277
+
278
+ The review wrapper selects roles from `spec.json`: a feature uses spec-compliance,
279
+ adversarial, and regression; a bugfix uses adversarial and regression; Android adds the
280
+ ANR/FC risk role. The selected roles are logged with the run.
281
+
282
+ Stage 5's Android branch runs through `scripts/run-android-e2e.mjs`, which sets the
283
+ stage model as `SUPERPOWER_LLM_MODEL` and points the package at `scripts/codex-stage`.
284
+ That shim translates the Android agent's `-p` prompt into `codex exec -m
285
+ <KANDEV_STAGE_MODEL>`, so the Android planner and evaluator use the Kandev model.
286
+
287
+ Stage 5's web branch runs `.agentic/e2e-driver.mjs` first: one real Playwright
288
+ scenario per acceptance criterion, bounded output, and `.agentic/e2e-result.json`
289
+ with per-AC evidence. Interactive Playwright MCP inspection is limited to five calls
290
+ after a driver start failure or an ambiguous assertion. Screenshots are failure-only.
291
+
292
+ ## Layout
293
+
294
+ ```text
295
+ config/config.yaml startup configuration (loopback, port, home)
296
+ config/pipeline.json stage -> profile/model/MCP mapping
297
+ config/workflows/sdlc.yaml portable kandev_workflow definition
298
+ config/gateways.json enabled gateway adapters in execution order
299
+ scripts/sync.mjs idempotent reconciler
300
+ scripts/gate.mjs external completion gate (validates artifacts, moves tasks)
301
+ scripts/verify.mjs live verification (health, bindings, immutability, secrets)
302
+ scripts/measure-tokens.mjs read-only task/profile token report
303
+ scripts/wait-status.mjs blocking stage-status wait
304
+ scripts/run-gateways.mjs gateway adapter runner and gateway.json writer
305
+ scripts/gateways/speckit.mjs Spec Kit Codex-skill adapter
306
+ scripts/planning-tools.mjs planning hashes and handoff validation
307
+ scripts/run-doc-review.mjs pinned requirement-agent wrapper
308
+ scripts/run-android-e2e.mjs pinned Android E2E wrapper with stage-model injection
309
+ scripts/verify-change.mjs deterministic Stage 3 build/test verifier
310
+ scripts/lib/bugfix.mjs bugfix contract, run evidence, and hash pins
311
+ scripts/verify-node.mjs deterministic Node build/lint/test verification
312
+ scripts/review-digest.mjs compact code-review summary
313
+ scripts/codex-medium code-review executor shim (medium reasoning effort)
314
+ scripts/codex-stage Android executor shim (stage model injection)
315
+ scripts/lib/stage-model.mjs KANDEV_STAGE_MODEL validation
316
+ scripts/lib/ MCP client, Kandev helpers, validation, checksum
317
+ test/ unit tests for pure logic
318
+ ```
319
+
320
+ ## Change workflow
321
+
322
+ 1. Edit `config/workflows/sdlc.yaml` or `config/pipeline.json`.
323
+ 2. `npm test && npm run sync && npm run verify`.
324
+ 3. Commit and push. Kandev never owns the definition; the repository does.
325
+
326
+ Native Workflow Sync is intentionally not enabled in the MVP: portable descriptors match
327
+ profiles by agent display name + model, and every agent stage shares the Codex vendor. The
328
+ reconciler binds profiles by exact name instead, which is deterministic. See
329
+ `specs/001-agentic-sdlc-pipeline/` for the full design and verification evidence.
330
+
331
+ ## Self-improvement loop
332
+
333
+ The read-only reviewer in `improver/` reviews completed and gate-blocked tasks,
334
+ writes task reports and agent scorecards under `.state/improver/`, and turns
335
+ repeated failures into candidate Kandev tasks. It never edits a worktree or the
336
+ Kandev database. See [docs/improver.md](docs/improver.md) for the report fields,
337
+ ticket rules, and guardrails.
338
+
339
+ ```bash
340
+ npm run improve:status
341
+ npm run improve # one tick
342
+ npm run improve:review -- <task-id>
343
+ npm run improve:tickets
344
+ npm run improve:convert -- <ticket-id> [--start-agent] [--yes]
345
+ npm run measure # task and per-profile token totals
346
+ mkdir -p .state/improver && touch .state/improver/FREEZE # stop actions; remove to resume
347
+ ```
348
+
349
+ A frozen tick, review, or conversion exits `2` and appends a `skipped` audit
350
+ record without writing a report or calling MCP. Conversion runs under the
351
+ controller lock. The lock is an atomic directory at `.state/improver/lock/`
352
+ with a heartbeat; only a changed hostname, dead PID, or heartbeat older than 24
353
+ hours makes it stale.
354
+
355
+ Planning also accepts `platform: "node"`. Stage 5's Node branch runs the
356
+ deterministic `verify-node.mjs --mode e2e` helper, which runs `npm test` and
357
+ a non-mutating `npm run sync:dry` when defined, otherwise records
358
+ `not-configured` at exit 127. Both results go in the required `commands` array,
359
+ and `report_path` plus scenario evidence must be non-empty `.log` files under
360
+ `.agentic/`. Improvement tasks are limited to a candidate commit plus rollback
361
+ notes; sync, publish, gate restart, and live `~/.kandev` edits are forbidden.
362
+
363
+ ## Security
364
+
365
+ `.env`, artifacts, caches, and Playwright output are gitignored. `verify` scans every
366
+ tracked file for token patterns and refuses non-empty `.env.example` values. The External
367
+ MCP endpoint is loopback-only and unauthenticated, so never expose the Kandev port
368
+ publicly without an authenticated proxy.
@@ -0,0 +1,16 @@
1
+ #!/usr/bin/env node
2
+ import { spawn } from "node:child_process";
3
+ import { createRequire } from "node:module";
4
+
5
+ const require = createRequire(import.meta.url);
6
+ const entry = require.resolve("@agentclientprotocol/codex-acp/dist/index.js");
7
+ const child = spawn(process.execPath, [entry, ...process.argv.slice(2)], {
8
+ stdio: "inherit",
9
+ });
10
+ child.on("error", (error) => {
11
+ console.error(`[codex-acp] ${error.message}`);
12
+ process.exit(1);
13
+ });
14
+ child.on("exit", (code, signal) => {
15
+ process.exit(code ?? (signal ? 1 : 0));
16
+ });
@@ -0,0 +1,101 @@
1
+ import path from "node:path";
2
+ import { spawnSync as nodeSpawnSync } from "node:child_process";
3
+
4
+ const SERVER_COMMANDS = new Set(["run", "start"]);
5
+ const VALUE_FLAGS = new Set(["--port", "--backend-port", "--web-internal-port"]);
6
+ const INFORMATIONAL_FLAGS = new Set(["--help", "-h", "--version", "-V", "--dev"]);
7
+
8
+ export function shouldAutoSync(argv, env = process.env) {
9
+ if (env.KANDEV_AUTO_SYNC === "0") return false;
10
+ if (argv.some((arg) => INFORMATIONAL_FLAGS.has(arg))) return false;
11
+ let command = null;
12
+ for (let index = 0; index < argv.length; index += 1) {
13
+ const arg = argv[index];
14
+ if (VALUE_FLAGS.has(arg)) {
15
+ index += 1;
16
+ continue;
17
+ }
18
+ if (arg.startsWith("-")) continue;
19
+ command = arg;
20
+ break;
21
+ }
22
+ return command === null || SERVER_COMMANDS.has(command);
23
+ }
24
+
25
+ export function targetUrl(argv, env = process.env) {
26
+ if (env.KANDEV_URL) return env.KANDEV_URL.replace(/\/$/, "");
27
+ let port = "38429";
28
+ for (let index = 0; index < argv.length; index += 1) {
29
+ const arg = argv[index];
30
+ if (arg === "--port" || arg === "--backend-port") {
31
+ if (argv[index + 1]) {
32
+ port = argv[index + 1];
33
+ index += 1;
34
+ }
35
+ continue;
36
+ }
37
+ if (arg.startsWith("--port=")) port = arg.slice("--port=".length);
38
+ else if (arg.startsWith("--backend-port=")) port = arg.slice("--backend-port=".length);
39
+ }
40
+ return `http://127.0.0.1:${port}`;
41
+ }
42
+
43
+ function sleep(milliseconds, signal) {
44
+ return new Promise((resolve) => {
45
+ const timer = setTimeout(resolve, milliseconds);
46
+ signal?.addEventListener(
47
+ "abort",
48
+ () => {
49
+ clearTimeout(timer);
50
+ resolve();
51
+ },
52
+ { once: true },
53
+ );
54
+ });
55
+ }
56
+
57
+ export async function autoSync({
58
+ argv,
59
+ env = process.env,
60
+ root,
61
+ fetchImpl = fetch,
62
+ spawnSyncImpl = nodeSpawnSync,
63
+ log = console.log,
64
+ warn = console.warn,
65
+ timeoutMs = 120000,
66
+ intervalMs = 1000,
67
+ signal,
68
+ } = {}) {
69
+ if (!shouldAutoSync(argv, env)) return { synced: false, reason: "disabled" };
70
+ const url = targetUrl(argv, env);
71
+ const deadline = Date.now() + timeoutMs;
72
+ while (Date.now() < deadline) {
73
+ if (signal?.aborted) return { synced: false, reason: "aborted", url };
74
+ try {
75
+ const response = await fetchImpl(`${url}/api/v1/workspaces`, {
76
+ signal: AbortSignal.timeout(Math.max(100, Math.min(2000, intervalMs * 2))),
77
+ });
78
+ if (response.ok) {
79
+ log(`[kandev] workflow config: syncing ${url}`);
80
+ let result;
81
+ try {
82
+ result = spawnSyncImpl(process.execPath, [path.join(root, "scripts", "sync.mjs")], {
83
+ stdio: "inherit",
84
+ env: { ...env, KANDEV_URL: url },
85
+ });
86
+ } catch (error) {
87
+ warn(`[kandev] workflow config sync failed: ${error.message}`);
88
+ return { synced: false, reason: "sync-failed", url };
89
+ }
90
+ if (result?.status === 0) return { synced: true, url };
91
+ warn("[kandev] workflow config sync failed; run `kandev-config sync` after Kandev is ready");
92
+ return { synced: false, reason: "sync-failed", url };
93
+ }
94
+ } catch {
95
+ // The server is still starting.
96
+ }
97
+ await sleep(intervalMs, signal);
98
+ }
99
+ warn("[kandev] workflow config auto-sync skipped: server did not become ready");
100
+ return { synced: false, reason: "timeout", url };
101
+ }
@@ -0,0 +1,53 @@
1
+ #!/usr/bin/env node
2
+ import { spawnSync } from "node:child_process";
3
+ import path from "node:path";
4
+ import { fileURLToPath } from "node:url";
5
+
6
+ const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
7
+ const COMMANDS = {
8
+ sync: "scripts/sync.mjs",
9
+ verify: "scripts/verify.mjs",
10
+ gate: "scripts/gate.mjs",
11
+ baseline: "scripts/baseline.mjs",
12
+ measure: "scripts/measure-tokens.mjs",
13
+ replan: "scripts/replan-planning.mjs",
14
+ };
15
+
16
+ function usage() {
17
+ console.log(`Usage: kandev-config <command> [options]
18
+
19
+ Commands:
20
+ sync Reconcile the bundled config with the running Kandev instance
21
+ verify Verify the live Kandev bindings, gate, and install
22
+ gate Run the completion gate daemon
23
+ baseline Record the Kandev install fingerprint
24
+ measure Measure token usage from the local Kandev database
25
+ replan Archive a blocked Planning attempt and re-enter the gateway
26
+
27
+ Examples:
28
+ kandev-config sync
29
+ kandev-config sync --dry-run
30
+ kandev-config gate
31
+ kandev-config verify`);
32
+ }
33
+
34
+ const [command, ...args] = process.argv.slice(2);
35
+ if (!command || command === "help" || command === "-h" || command === "--help") {
36
+ usage();
37
+ process.exit(0);
38
+ }
39
+ const script = COMMANDS[command];
40
+ if (!script) {
41
+ console.error(`kandev-config: unknown command "${command}"`);
42
+ usage();
43
+ process.exit(2);
44
+ }
45
+ const result = spawnSync(process.execPath, [path.join(ROOT, script), ...args], {
46
+ stdio: "inherit",
47
+ env: process.env,
48
+ });
49
+ if (result.error) {
50
+ console.error(`kandev-config: ${result.error.message}`);
51
+ process.exit(1);
52
+ }
53
+ process.exit(result.status ?? 1);
package/bin/kandev.js ADDED
@@ -0,0 +1,35 @@
1
+ #!/usr/bin/env node
2
+ import { spawn } from "node:child_process";
3
+ import { createRequire } from "node:module";
4
+ import path from "node:path";
5
+ import { fileURLToPath } from "node:url";
6
+ import { autoSync } from "./kandev-auto-sync.mjs";
7
+
8
+ const require = createRequire(import.meta.url);
9
+ const cli = require.resolve("kandev/bin/cli.js");
10
+ const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
11
+ const argv = process.argv.slice(2);
12
+ const env = {
13
+ ...process.env,
14
+ KANDEV_TASK_STALL_DETECTION_THRESHOLD:
15
+ process.env.KANDEV_TASK_STALL_DETECTION_THRESHOLD || "10m",
16
+ };
17
+ const controller = new AbortController();
18
+ const child = spawn(process.execPath, [cli, ...argv], {
19
+ stdio: "inherit",
20
+ env,
21
+ });
22
+
23
+ autoSync({ argv, env, root: ROOT, signal: controller.signal }).catch((error) => {
24
+ console.warn(`[kandev] workflow config auto-sync failed: ${error.message}`);
25
+ });
26
+
27
+ child.on("error", (error) => {
28
+ controller.abort();
29
+ console.error(`[kandev] ${error.message}`);
30
+ process.exit(1);
31
+ });
32
+ child.on("exit", (code, signal) => {
33
+ controller.abort();
34
+ process.exit(code ?? (signal ? 1 : 0));
35
+ });
@@ -0,0 +1,6 @@
1
+ homeDir: ~/.kandev
2
+ server:
3
+ host: 127.0.0.1
4
+ port: 38429
5
+ tasks:
6
+ stallDetectionThreshold: "10m"
@@ -0,0 +1,79 @@
1
+ {
2
+ "project": "opencodex-cli",
3
+ "match": {
4
+ "repo_names": ["opencodex-cli"],
5
+ "package_names": ["@koreanhole/opencodex"],
6
+ "files": ["package.json", "bun.lock", "bunfig.toml"]
7
+ },
8
+ "image": "kandev-task-opencodex-cli:bookworm",
9
+ "dockerfile": "docker/Dockerfile.opencodex-cli",
10
+ "platform": "linux/arm64",
11
+ "container_prefix": "kandev-task-ocx",
12
+ "env": {
13
+ "BUN_INSTALL_CACHE_DIR": "/root/.bun/install/cache",
14
+ "NPM_CONFIG_CACHE": "/opt/npm-cache"
15
+ },
16
+ "volumes": [
17
+ "kandev-bun-cache:/root/.bun/install/cache"
18
+ ],
19
+ "dependencies": {
20
+ "apt": [
21
+ "bash",
22
+ "ca-certificates",
23
+ "curl",
24
+ "git",
25
+ "gnupg",
26
+ "jq",
27
+ "procps",
28
+ "python3",
29
+ "python3-pip",
30
+ "python3-venv",
31
+ "ripgrep",
32
+ "unzip",
33
+ "wget"
34
+ ],
35
+ "cli_tools": [
36
+ { "name": "node", "verify": ["node", "--version"] },
37
+ { "name": "npm", "verify": ["npm", "--version"] },
38
+ { "name": "bun", "verify": ["bun", "--version"] },
39
+ { "name": "git", "verify": ["git", "--version"] },
40
+ { "name": "rg", "verify": ["rg", "--version"] },
41
+ { "name": "uv", "verify": ["uv", "--version"] },
42
+ { "name": "specify", "verify": ["specify", "--help"] },
43
+ { "name": "codex", "verify": ["codex", "--version"] }
44
+ ],
45
+ "npm_global": [
46
+ "bun@1.4.4",
47
+ "@openai/codex@0.164.0"
48
+ ],
49
+ "npm_cache": [
50
+ "mcp-server-commands@0.8.2",
51
+ "@koreanhole/requirement-agent@0.1.7",
52
+ "@koreanhole/code-review-agent@0.5.0",
53
+ "@playwright/mcp@0.0.84"
54
+ ],
55
+ "uv_tools": [
56
+ "specify-cli==1.2.0"
57
+ ],
58
+ "bun": {
59
+ "version": "1.4.4",
60
+ "lockfile": "bun.lock",
61
+ "packages": [
62
+ "@agentclientprotocol/sdk@1.9.0",
63
+ "@bitkyc08/opencodex@2.94.0",
64
+ "@modelcontextprotocol/sdk@^1.32.1",
65
+ "bun@1.4.4",
66
+ "@types/bun@1.4.4",
67
+ "typescript@7.0.2"
68
+ ],
69
+ "provision_commands": [
70
+ ["bun", "install", "--frozen-lockfile"]
71
+ ],
72
+ "verify_commands": [
73
+ ["bun", "run", "verify:upstream"],
74
+ ["bun", "run", "typecheck"],
75
+ ["bun", "test", "tests/repository-surface.test.ts"]
76
+ ]
77
+ }
78
+ }
79
+ }