feat: leaner contract, test-first bug fixes, generic intake (v0.14.0)

README.ko.md

@@ -212,7 +212,7 @@ abandoned나 dead-end는 교훈이 없으면 닫히지 않습니다(lazymode 3 
 
 ### 장애 진단은 싼 프로브부터
 
-6단계는 에이전트를 대량으로 풀지 않습니다. 배포된 소스를 먼저 확인합니다. `refcheck.sh`는 작업 트리의 내용을 스테이징·비스테이징·미추적까지 모두 대상 리비전과 비교하고, 릴리스 시스템이 알려주는 실제 배포 SHA가 있으면 `--deployed-sha`로 받고, ref나 fetch가 실패하면 추측 대신 UNKNOWN을 보고합니다. 그다음 어떤 통제가 뚫렸는지 묻고, 요청한 재현 증거를 추적하고, `skills/6-maintain/probes.md`의 짧은 프로브를 돌립니다.
+6단계는 에이전트를 대량으로 풀지 않습니다. 배포된 소스를 먼저 확인합니다. `refcheck.sh`는 작업 트리의 내용을 스테이징·비스테이징·미추적까지 모두 대상 리비전과 비교하고, 릴리스 시스템이 알려주는 실제 배포 SHA가 있으면 `--deployed-sha`로 받고, ref나 fetch가 실패하면 추측 대신 UNKNOWN을 보고합니다. 그다음 무엇을 어떤 입력으로 했는지, 대신 무슨 일이 일어났는지, 어디서, 누구로, 어떤 흔적이 남았는지 묻고(UI·API·배치 작업·CLI 모두 같은 다섯 질문), 요청한 재현 증거를 추적하고, `skills/6-maintain/probes.md`의 짧은 프로브를 돌립니다.
 
 프로브는 수정 계획에 도달하기 전에 흔한 진단 실수 네 가지를 잡습니다.
 
@@ -221,6 +221,8 @@ abandoned나 dead-end는 교훈이 없으면 닫히지 않습니다(lazymode 3 
 - 아래 계층이 이미 삼키는 에러에 `try/catch`를 덧대는 실수
 - 데이터 없는 정상 상태를 확인하지 않고 "리스크 제로"라고 말하는 실수
 
+버그 수정은 수정 전 코드에서 보고된 이유로 실패하는 회귀 테스트부터 만듭니다. 같은 테스트가 수정 후 통과하고 테스트 스위트에 남습니다. 테스트로 결함에 닿을 수 없을 때만 수동 절차나 로그로 대신하고, 그 이유를 증거에 적습니다.
+
 재현이 안 되는 장애는 새 컨텍스트 adversary들이 범위를 다시 세고, 주장된 에러 전파를 증명하고, 모든 "절대 안 그래" 주장을 공격하고, 경쟁 원인을 제시합니다. 받지 못한 콘솔, 네트워크, 스크린샷 증거는 사람이 받거나 면제할 때까지 `status.sh`에 계속 보입니다.
 
 ## 조종석

README.md

@@ -212,7 +212,7 @@ An abandoned or dead-end run cannot close until a lesson exists (at lazymode ≥
 
 ### Incident diagnosis starts with cheap probes
 
-Stage 6 does not begin with a broad agent fan-out. It first checks the deployed source — `refcheck.sh` compares the working tree's content (staged, unstaged, and untracked alike) against the target revision, takes the real deployment SHA with `--deployed-sha` when the release system reports one, and reports UNKNOWN rather than guessing when a ref or fetch fails — asks which control failed, tracks requested reproduction evidence, and runs the short probes in `skills/6-maintain/probes.md`.
+Stage 6 does not begin with a broad agent fan-out. It first checks the deployed source — `refcheck.sh` compares the working tree's content (staged, unstaged, and untracked alike) against the target revision, takes the real deployment SHA with `--deployed-sha` when the release system reports one, and reports UNKNOWN rather than guessing when a ref or fetch fails — asks what was done with what input, what happened instead, where, as whom, and what trace exists (the same five questions for a UI, an API, a job, or a CLI), tracks requested reproduction evidence, and runs the short probes in `skills/6-maintain/probes.md`.
 
 The probes catch four common diagnosis mistakes before they reach a fix plan:
 
@@ -221,6 +221,8 @@ The probes catch four common diagnosis mistakes before they reach a fix plan:
 - adding a `try/catch` where the lower layer already swallows the error;
 - calling a change "zero risk" without checking normal missing-data states.
 
+A bug fix starts with a regression test that fails on the pre-fix code for the reported reason; the same test passes after and stays in the suite. Manual steps or logs stand in only when no test can reach the defect, and the evidence says why.
+
 When the incident cannot be reproduced, fresh-context adversaries recount the scope, prove the claimed error propagation, attack every "never" claim, and propose a rival cause. Outstanding console, network, or screenshot evidence stays visible in `status.sh` until it is received or the human waives it.
 
 ## Cockpit

SKILL.md

@@ -8,8 +8,9 @@ description: "Gated SDLC loop with human approvals, for building features and fi
 One loop, six stages, one artifact per stage, and a gate between stages:
 human at intent, spec, and ship; tiered at plan; `lazymode:` in
 `.sdlc/config.md` can waive human gates (AGENTS.md rule 3).
-This file routes requests. `AGENTS.md` in this directory is the full contract.
-Read it completely on first contact with a project, then return here.
+This file routes requests. `AGENTS.md` in this directory is the full contract
+— gates, authority, memory, fresh-context review, proof. Read it completely
+before the first stage of a session, then return here.
 
 ## When this skill runs
 
@@ -35,30 +36,10 @@ they do it under this contract (gates, artifacts, memory), not beside it.
 | ticket too big or foggy for one intent pass | `map.md` in the same slug dir first (skills/1-intent "Chart a map first"); one Unknown per session, six sessions max. |
 | "continue <slug>" / "what's next" | Run `gates/status.sh <slug>` from the project root. Its `next →` line names the stage skill or gate command. |
 | "where are we" / "sdlc status" | `gates/status.sh` (open features; `--all` adds the newest 20 archived) + `gates/stats.sh` (open + recent closed). Full-archive sweeps: `ls`/`grep .sdlc/archive/`, never the whole listing into context. |
-| "has this been done before" / "why is X like this" / debugging an old area | `tools/kb.sh search "<text>"` then `tools/kb.sh show <slug>` — a digest (goal, summary.md, delivery, unmerged harvest candidates, lesson titles, then the paths) over open and closed features plus durable memory, bounded output (`--area <folder>` covers every store, even one whose checkout is gone). Exit 0 found · 1 nothing · 2 usage/refusal. |
-| "what did we learn that is not in memory yet" / many open features, few closes | `tools/kb.sh harvest [--stale <days>]` — open features whose harvest.md no close has merged, with idle time; a STALE one may be merged without closing (AGENTS.md rule 4). The contents page (`tools/kb.sh index`; `index_style: obsidian` in config.md for a vault) shows the same candidates and an overview table by state, date and tags. |
-| a host/scheduler drives the loop, or you need machine state | `gates/status.sh --json` (= `tools/auto.sh status --json`) and `tools/auto.sh next <slug>` (exit 0 ready · 10 needs-human · 20 blocked · 30 complete). Verification receipts: `tools/verify.sh`; review handoff: `tools/handoff.sh`. Contract: `docs/automation.md`. These report and record — they run no stage. |
+| "has this been done before" / "why is X like this" / debugging an old area | `tools/kb.sh search "<text>"` then `tools/kb.sh show <slug>` (AGENTS.md rule 7). |
+| "what did we learn that is not in memory yet" / many open features, few closes | `tools/kb.sh harvest [--stale <days>]`; a stale one may be merged without closing (AGENTS.md rule 4). Contents page: `tools/kb.sh index` (`index_style: obsidian` in config.md for a vault). |
+| a host/scheduler drives the loop, or you need machine state | `gates/status.sh --json`, `tools/auto.sh next <slug>`; contract: `docs/automation.md`. |
 | gate request answered "approve" in chat | `gates/approve.sh <stage> <artifact> --delegated` per AGENTS.md rule 3. |
 | incident / bug / alert on a shipped feature | Read `skills/6-maintain/SKILL.md`. |
-| "we're done / drop this / dead end" for a feature | `gates/close.sh <slug> <shipped\|abandoned\|dead-end\|handed-off> "reason"`. `shipped` needs a confirmed `delivery.md` (templates/delivery.md) and an unchanged ship approval; dead-end/abandoned need a lesson (lazymode ≥3: the reason line suffices); handed-off needs an external ticket/PR reference. close.sh archives the feature to `.sdlc/archive/<slug>/`. |
+| "we're done / drop this / dead end" for a feature | `gates/close.sh <slug> <shipped\|abandoned\|dead-end\|handed-off> "reason"` — what each needs: AGENTS.md "Every feature ends in a terminal state". |
 | project has no `.sdlc/` yet | Run `<kit>/init.sh` from the project root (records are gitignored; `--area <folder>` keeps them in a folder the human names instead); ask the human which lazymode level they want (0–4, default 1; AGENTS.md rule 3) and set it in `.sdlc/config.md`; fill the config commands; then stage 1. |
-
-## Coexistence (full text in AGENTS.md)
-
-Project rules control implementation details such as commands, branches, and
-style. The kit controls stages, gates, and memory. Quote conflicts to the human
-instead of resolving them silently. DOMAIN.md points at existing
-glossaries/ADRs instead of copying. Kit roles dispatch onto existing specialist agents when one fits.
-Monorepos: one `.sdlc/` per shipping unit.
-
-## Invariants (full text in AGENTS.md)
-
-Before stages 2–4, check the gate. One delegate carries the loop; verification
-and adversarial review always run in a fresh context, and a harness that cannot
-provide one gets an explicit gap line in the artifact (AGENTS.md rule 5).
-Read `.sdlc/memory/POLICY.md`,
-`.sdlc/memory/INDEX.md`, and `.sdlc/memory/DOMAIN.md` at every stage start;
-mid-loop memory candidates go to the feature's `harvest.md`, merged only at
-close (rule 4). Speak plainly to the human. Keep artifacts in the record
-store, which is gitignored in full and is the human's to back up (rule 7).
-Store large evidence in scratch/ and cite only the deciding lines.

VERSION

@@ -1 +1 @@
-v0.13.1
+v0.14.0

init.sh

@@ -354,6 +354,12 @@ qa:
 # then finds the project's own e2e entry point, and records NOT VERIFIED when
 # there is no runnable environment (roles/verifier.md). Never a new dependency.
 e2e:
+# Optional: the project's own agent or skill to dispatch for each kit role
+# (AGENTS.md "Running beside…" rule 3) — e.g. a debugging skill as researcher,
+# a QA agent as verifier. Empty = the best local fit, else a generic worker.
+researcher:
+verifier:
+adversary:
 EOF
 
 # projects seeded before lazymode existed keep their config; append the block

log/changelog-v0.14.0.md

@@ -0,0 +1,64 @@
+# v0.14.0 — a leaner contract, test-first bug fixes, generic intake
+
+Real stores showed where the kit's words went. The agent-facing prose had
+grown to about 128 KB. `AGENTS.md` restated what the scripts already enforce,
+each stage skill repeated the heartbeat and memory paragraphs, and bug fixes
+could "prove" themselves with reproduction steps that nothing re-runs. The
+kit is used for any software (web, API, batch, CLI), but stage 6 intake still
+asked only UI questions. This release cuts the duplication and makes the bug
+proof durable. Gates, scripts, the `--json` schema, and lazymode are
+unchanged; `init.sh` gains three optional config lines.
+
+## Changes
+
+- **`AGENTS.md` keeps what an agent must decide** (453 → 324 lines, −31%).
+  Mechanics a script enforces and prints a reason for (digest binding,
+  ship-snapshot rules, C-quoted paths, handoff refusals, store ownership) are
+  now one line each. Text that `docs/automation.md` already holds (full-auto
+  intent contract §3, verify receipt §4) is now a pointer. Rule numbers and
+  section names are unchanged. The stale "rule 3a" citations in
+  `gates/_auto.sh` and `gates/status.sh` now resolve: 3a labels the full-auto
+  intent contract.
+- **Defined once.** Heartbeat (rule 9, now listing the stage names and
+  build's n/m) and memory reading (rule 4) are no longer repeated in six stage
+  skills; each skill carries a one-line pointer. The harvest/close-writer
+  rule, the `kb.sh` digest description, and tripwire caveats are referenced,
+  not restated. `SKILL.md` drops its Coexistence and Invariants summaries,
+  which repeated `AGENTS.md`. `roles/researcher.md` points at `probes.md`
+  instead of copying three probes.
+- **Bug fixes start with a failing test** (AGENTS.md rule 6). By default the
+  reproduction is an automated test at the lowest level that reaches the
+  defect. It fails on the pre-fix code for the reported reason, passes after,
+  and stays in the suite. Manual steps or logs stand in only when no test can
+  reach the defect, and the evidence says why. Stage 6 drafts the test outside
+  the source tree, build adds it before the fix, and the verifier runs it
+  against the pre-fix commit and must see it fail. `templates/evidence.md`
+  gains a `Regression test:` line, and the plan's Proof and the compact
+  route's Proof line name it.
+- **Generic stage 6 intake.** The five questions now fit a UI, an API, a job,
+  or a CLI: what was done with what input, what happened versus what was
+  expected, where and when, as whom, and what trace exists (request or trace
+  id, log line, affected record keys). A symptom class (nothing happened /
+  wrong result / looks wrong / intermittent) replaces the UI-only
+  "does not react vs looks disabled" split. Probe 2 is no longer a MyBatis
+  `awk` over `mapper.xml`: it diffs the filters of every query on one entity
+  (SQL, ORM, API params, cache keys).
+- **Projects name their own helpers.** New optional `researcher:`,
+  `verifier:`, `adversary:` keys in `.sdlc/config.md`: the named agent or
+  skill is dispatched with the kit's role file as its contract ("Running
+  beside…" rule 3). Empty or absent means the old behavior. Existing configs
+  are not rewritten.
+
+Agent-facing prose (SKILL.md, AGENTS.md, stage skills, roles): 104,136 →
+~89,700 bytes.
+
+## Validation
+
+- `bash gates/knowledge-test.sh` → `KNOWLEDGE-TEST PASS`, 144
+- `bash gates/selftest.sh` → `SELFTEST PASS`
+- `bash gates/e2e.sh` → `E2E PASS`, 152 · `bash gates/autotest.sh` → `AUTOTEST PASS`, 195
+- Three fresh-context verifier lenses over the diff: E2E (init.sh in a
+  disposable repo, plus a backend-bug compact walk and a UI full-route walk),
+  Side effects (removed instructions and cross-references), and Intent match
+  (against the approved recommendation). Their minor findings in the changed
+  text were fixed before release.

roles/researcher.md

@@ -18,14 +18,10 @@ Do:
    suspicious duplication, version constraints, and feature flags.
 3. Verify claims you were given ("the bug is in module Y", "the API does X"):
    confirm or refute with file:line evidence.
-4. Class sweep: if you find a defect that is an instance of a pattern
-   (missing filter/guard/timeout/lock), grep the same file or module for the
-   whole class and report a count table, not just the one instance.
-5. Shared-symbol audit: before reporting that a shared query/function should
-   change, list every call site and whether each guards the result
-   (null/empty check). The call-site × guard table goes in your report.
-6. Gate check: when verifying a constant or flag ("logging is on"), read the
-   condition AROUND it. A true constant inside a dead branch is false.
+4. Run the probes in `skills/6-maintain/probes.md` (kit-relative) that fit
+   the question — above all the class sweep (5), the call-site × guard table
+   before calling a shared symbol wrong (4), and the gate check on
+   "impossible" claims (6). Their tables go in your report.
 
 Report format (target: 60 lines or fewer):
 
@@ -42,8 +38,7 @@ Report format (target: 60 lines or fewer):
 ```
 
 The dispatcher appends Domain candidates to the feature's
-`.sdlc/work/<slug>/harvest.md`; INDEX.md, DOMAIN.md, and lessons/ are
-written only at close (AGENTS.md rule 4). A candidate that contradicts an
+`.sdlc/work/<slug>/harvest.md` (AGENTS.md rule 4). A candidate that contradicts an
 existing DOMAIN.md entry supersedes it — mark it `supersedes: <old entry>`
 so the close merge replaces the old line instead of keeping both.
 

roles/verifier.md

@@ -16,16 +16,20 @@ spec.md and plan.md (compact route: intent.md only), the changed-file list,
    `tools/verify.sh run <slug>`: the receipt records what ran, your report is
    still the judgement.
 2. Exercise the change for real, scoped to it — the flows it touches, not the
-   product's whole suite; the project's own commands and fixtures, never a
-   parallel harness:
+   product's whole suite; the project's own commands and fixtures (config.md
+   `e2e:` when set), never a parallel harness:
    - **UI** → drive the actual screen (`qa:` tool, else any browser tool in
      the harness): load it, do the user's steps, read the rendered result.
    - **API / CLI / job** → the real request or command against a running
      instance (`run:`); read the response, exit status, and resulting state.
-   - **Bug fix** → the proof chain (AGENTS.md rule 6): reproduce the ORIGINAL
-     failure against the pre-fix state (`git show <base>:<file>` into scratch
-     or a disposable checkout — never `git stash` or anything that mutates the
-     human's tree), confirm the mechanism, run the SAME reproduction after.
+   - **Bug fix** → the proof chain (AGENTS.md rule 6): run the regression
+     test (or, where none can reach the defect, the recorded reproduction)
+     against the pre-fix code — a disposable worktree of the commit before
+     the fix (HEAD while the fix is uncommitted) with only the new test
+     copied in; never `git stash` or anything that mutates the human's
+     tree — and
+     confirm it FAILS for the reported reason; confirm the mechanism; run the
+     SAME test after. A test that passes on the pre-fix code proves nothing.
      A chain you cannot complete is a FAIL, or a stated limitation for an
      intermittent defect — never a pass by assumption.
 3. Check each plan.md **Proof** item (compact route: intent.md's Proof line).