jaw-dev-pabcd

Structured 5-phase development. Advance only with user approval. > **C0/C1 work:** see `dev` §0.0 Work Classifier and §0.1 Patch Fast-Path first — full > PABCD is mandatory for C4 and conditional for C3, not the baseline for every task. > **`dev` is canonical:** `dev` §0.2 Rule Classes, §3 Verification Gate, and §5 Safety Rules apply to all work governed by this skill. ## §1. Interview Trigger (MUST) When the user asks for an interview in any form — "인터뷰하자", "인터뷰 모드", "interview", "요구사항 정리", "스펙 정리해줘", "뭘 만들어야 하는지 정리", or any variation — you MUST immediately run: cli-jaw orchestrate I Do NOT ask clarifying questions in IDLE instead of entering Interview, skip Interview for unclear requests, or merely narrate — actually execute the command in Bash. `/interview` is the user-facing shortcut; the Boss agent always runs the command directly. - **Teach the decision space, don't only narrow it** (DEFAULT, INTERVIEW-TEACH-01): intent transfer is bidirectional — a user cannot choose among options they have never seen. Questions that merely confirm details the user already stated are the weak form; the strong form maps the option landscape (research it first when needed) with a trade-off explanation per option, at every load-bearing altitude: stack, architecture, **algorithm/strategy**, data structure, evaluation method. - Recommend one with project-specific reasoning - Confirm once, then proceed For broad changes or unfamiliar repositories, P phase MUST include: - Compact tree of the current repository shape - Detected repo conventions: docs, plans, architecture notes, source-of-truth logs, naming, tests - Whether existing `structure/`, `devlog/`, `docs/`, `plans/`, or equivalent logs were read and will be reused - Whether `structure/` or `devlog/` is proposed - The SoT sync target (SOT-SYNC-01): which general source-of-truth doc (`structure/`, architecture/INDEX docs) this unit will patch in C — or, if the repo has none, the plan recommends creating one (jaw-dev-scaffolding §2.1) Do not create new project-level source-of-truth folders during B unless approved in P or explicitly requested by the user. For every planned conditional path (error handler, fallback, retry, cache, guard, feature-gated branch, threshold behavior), the plan's accept criteria name its **activation scenario**: how C will trigger the condition and what observable effect proves the path ran (C-ACTIVATION-GROUNDING-01, §3 C). Design phases before mapping them to PABCD. **Slice and order phases by dependency/architecture structure (STRICT, PHASE-SPLIT-01)** — the orthodox unlimited-time build order: foundations (schema, contracts, core data flow) → core capabilities → integration → hardening/polish — so each phase consumes the verified output of the previous one. DB/API/UI/test work inside a phase are subtasks, not top-level phases by default, and every phase must still close with something independently verifiable (build, tests, or a demonstrable surface). Effort-based bucketing is FORBIDDEN: never split or order phases by estimated effort or payoff speed — no "quick win vs heavy" buckets, no impact/effort matrices, no time-boxed slices. Phase boundaries encode the system's build order, not the schedule. A simple task can finish in one PABCD with several small phases; larger work splits into multiple PABCD passes — one full P→A→B→C→D per work-phase, closed by D and re-entered at P for the next work-phase (see Terminology / Rule 4). Read project docs and jaw-dev skills first. Write the complete plan internally, then report it simply — like a developer reporting to the CEO. Write a plan with two parts: **Interview MUST settle three things before P** (DEFAULT, INTERVIEW-CLASSIFY-01): the work class (dev §0.0), the **loop archetype** (§11.4) — ask "does a verifier define *done* for this work, or only *better*?" — and the **unit residence** (UNIT-RESIDENCE-01, §3.1). Applies in HITL and goal mode alike; an archetype discovered mid-loop, after candidates were burned, is an Interview failure. **Interview may widen, not only narrow** (DEFAULT, INTERVIEW-DIVERGE-01): sometimes the truest transfer of intent is "we don't know yet — test both." When a load-bearing choice is genuinely uncertain and a spike is cheap, present options as `A · B · BOTH (parallel spike, select by evidence)` instead of forcing one pick. Generate the option list against typicality bias: the 2-3 options a model volunteers are usually one attractor family — deliberately include at least one atypical (low-probability) approach. A `BOTH` answer becomes an explore-and-select work-phase (§11.4) with the comparison verifier declared in the loop-spec. Divergence seeded at Interview is far cheaper than divergence discovered at a plateau. **Interview sub-modes** (DEFAULT, INTERVIEW-CATALOG-01): pick by the user's knowledge level. *Clarification* (existing) — the user already knows roughly what they want; questions structure goals, constraints, success criteria. *Catalog Discovery* — the user names a vague domain but no features ("사주 앱 만들고 싶어", "뭘 만들지 모르겠어"); see below. *Configurator* — compile the selections into a spec. Heuristic: concrete feature/goal → Clarification; vague domain, no tech specifics → Catalog Discovery; explicit user request → honor it. **Catalog Discovery — design/UX LEADS** (DEFAULT, CATALOG-DESIGN-FIRST-01): the user cannot choose from options they have never seen (the strong form of INTERVIEW-TEACH-01). Present the option ontology in `references/catalog-discovery.yaml`. *Hard barrier:* iterate `axis_order` by ascending `stage`; do NOT present a stage until every `required` entry of all earlier stages is answered. Stage 1 is design, so all six design dials (mood, lightness, density, shape, typography, motion), each `required: true`, MUST be answered before any Stage 2 (domain) or Stage 3 (feature/data/ security/ops/cost) question appears. This is the load-bearing invariant — backend is asked on top of design, never before it. - *Design methodology — Product-Personality Selection first* (`design_methodology.primary`, from jaw-dev-uiux-design §1): for each design dial show its `question_options` (labels + trade-offs) anchored on familiar products, then ask (present-then-ask, not confirm-what-they-said); refine via the declared `followups` — Korean Request Translation (§3), Reference Discovery (§1 Step 6), Design Read (§2). - *Deriving backend questions* — two paths populate Stage 3 from earlier answers, never a flat list: **structural** — a chosen Stage-2 domain entry's `implies[]` plus each Stage-3 entry's `derived_from` (resolve `implies[]` transitively); **keyword** — scan the user's INITIAL free-text request against Stage-3 `auto_activate_rules` (e.g. "사주"/"생년월일" pre-activates `security.pii_protection`). Confirm high-impact activations. - The catalog is a DATA STRUCTURE — do not invent entries not in it. The YAML encodes derivation INPUTS + dependency metadata; this prose is the agent procedure that reads it. Automated runtime filtering is out of scope (it would escalate to code). **Configurator**: once selections are complete, compile them (with resolved `implies[]` chains) into a spec — PRD sections, an MVP cut ordered by `cost_class`, a risk register of every `risk_class: high` entry, and a PABCD plan seed carrying the work class + loop archetype from INTERVIEW-CLASSIFY-01. ## §2. How It Works ``` IDLE ──→ P ──→ A ──→ B ──→ C ──→ D ──→ IDLE │ │ │ │ │ STOP STOP STOP auto auto wait wait wait └──────┴──── I (Interview) — reachable from any phase, context preserved Transitions (each phase accepts only its predecessor): cli-jaw orchestrate I|P|A|B|C|D → I from any state (context preserved); P from IDLE/I; A←P, B←A, C←B, D←C (D returns to IDLE) cli-jaw orchestrate reset → IDLE from any state (context cleared); re-enter with P ``` ### §2.1 Evidence gate (forward transitions) The four forward transitions (P→A, A→B, B→C, C→D) require an **evidence attestation** — a real `cli-jaw orchestrate` command with an `--attest` JSON, not narration. The server gates the agent (identified by its boss token); a human's `/orchestrate X` keeps the free pass. P, A, and B also require user approval; C and D proceed automatically once their work is done. In goal mode, §4 rule 4 replaces user approval with evidence-backed checkpoints. ``` cli-jaw orchestrate A --attest '{"from":"P","to":"A","did":"<the concrete plan you wrote: files/surfaces + devlog path>"}' cli-jaw orchestrate B --attest '{"from":"A","to":"B","did":"<who audited the plan + the verdict>"}' cli-jaw orchestrate C --attest '{"from":"B","to":"C","did":"<what you built + who verified it>"}' cli-jaw orchestrate D --attest '{"from":"C","to":"D","did":"<what you checked>","checkOutput":"<paste the real tsc/test tail>","exitCode":0}' ``` The gate is **form-only**: well-formed block, real `did` narrative (booleans/placeholders rejected); C→D additionally requires non-empty `checkOutput` and, if present, `exitCode:0`. It does NOT cross-check the narrative against runtime state — it forces a deliberate, specific claim, not malice-proofing. **Evidence pointers (DEFAULT, ATTEST-EVIDENCE-01):** even though the gate checks form only, write `did` with artifact pointers: plan/devlog path, changed-file list, verifier command, exit code, and relevant `cli-jaw goal update` checkpoint when goal mode is active, so a later reader can re-check the claim. Narration without running the command does nothing: the state moves only on the command. Threat model = laziness, not malice. Accepted residuals (NOT bugs): fabricated `did`, the hidden `--force` hatch, a prior-turn `pendingAttestation`, and boss-token stripping (closing it would break the legitimate human-via-CLI free pass). ### 2.2 Orchestration invariants Four rules govern what a transition means. The gate above enforces none of them — they are what makes the recorded cycle worth reading. **ORCH-MANDATE-01 (STRICT) — a narrated phase did not happen.** A phase claim without a persisted transition is invalid. Narrating phases — "now I'm in B", "the audit passed" — without issuing them is the failure this rule exists to stop: nothing gated anything, the log is empty, and the cycle is one ordinary turn wearing a PABCD costume. §2.1 already says it for one edge; this generalizes it to entry and re-entry. 1. **Read the real state before claiming one.** Query the current phase, or read the last recorded transition. Do not resume from memory. 2. **Arm the mode explicitly** — enter at `orchestrate I` or `orchestrate P`. 3. **Advance every forward edge with an evidence-bearing attestation**, carrying that phase's real artifact (ORCH-ARTIFACT-01 below). 4. **After D closes, read durable state** — the plan record and the transition log — to confirm what remains, then re-enter P for the next work-phase (LOOP-UNIT-CHAIN-01). Work performed outside the state machine does not count as progress: re-enter and attest it before building on it. Per the Runtime adapter note at the top of this file, "persisted" scales with the host — a runtime with an FSM persists the transition itself; a runtime without one persists it as the announced transition plus the attestation JSON appended to the worklog. What is never acceptable is a transition that exists only in the reply text. **ORCH-ARTIFACT-01 (DEFAULT) — advancing a phase is not doing it.** Each forward edge must carry its real artifact, not just an attestation string: | Edge | Required artifact | |---|---| | P→A | the actual diff-level plan document | | A→B | an audit verdict that names its blockers | | B→C | the implementation delta | | C→D | fresh typecheck/test/gate output — non-empty `checkOutput`, `exitCode: 0` | | D | a cycle summary with evidence and the next-phase decision | A phase whose artifact is absent is not done, regardless of adjacency. The gate is form-only and cannot tell a real artifact from a plausible sentence; this rule is the discipline the gate cannot enforce. **ATTEST-SHAPE-01 (STRICT) — name the edge.** Every attestation carries `from` and `to` naming the edge it advances, on every edge including ungated entry edges, and it matters before `did` does: an attestation that does not say which transition it belongs to is not an attestation, it is a sentence. A later reader reconstructing the cycle from the log has only those two keys to order it by. P→A additionally names its plan unit — a real `devlog/_plan/YYMMDD_slug/` holding numbered docs (UNIT-RESIDENCE-01) — **inside `did`**, not as a separate key. That placement is not a style choice. cli-jaw's attest parser accepts exactly `from`, `to`, `did`, `checkOutput`, and `exitCode`; every other key is **silently dropped**, with no error and no warning. A `planUnit`, `workPhaseId`, `auditOutput`, `auditVerdict`, or `testReceiptPath` field written into the JSON simply vanishes, so a rule demanding them would document a gate that does not exist. Carry them in the `did` narrative, where they survive and stay readable, and treat the shape as what makes the log re-readable rather than what makes the gate pass. **SESSION-IDENTITY-01 (STRICT) — do not attest for a state you do not own.** cli-jaw keeps one FSM per server rather than one per session, and `jaw orchestrate` takes no `--session` flag, so there is no id to get wrong here. What remains is the failure the rule exists to prevent: advancing a phase that another conversation is mid-cycle on. Read the current phase before claiming one, and when several conversations share the server, confirm the in-flight cycle is yours before advancing it. Two cycles writing one record is not a mistake that reports itself: the other conversation's phase moves without it acting, and neither side can tell from inside. That is why this is STRICT rather than hygiene. ## §3. Phases ### P — Plan If the request has unclear scope or unspecified technology, return to Interview (`cli-jaw orchestrate I`): present 2–3 options as `<TechName> — <plain explanation>`, recommend one with project-specific reasoning, confirm once, then proceed. For broad changes or unfamiliar repositories, P phase MUST include: - Compact tree of the current repository shape - Detected repo conventions (docs, plans, architecture notes, naming, tests) - Whether existing SoT logs (`structure/`, `devlog/`, `docs/`, `plans/`) were read and will be reused, and whether new ones are proposed - The SoT sync target (SOT-SYNC-01): which general source-of-truth doc this unit will patch in C — or, if the repo has none, the plan recommends creating one (dev-scaffolding §2.1) Do not create new project-level source-of-truth folders during B unless approved in P or explicitly requested. Design phases before mapping them to PABCD. **Slice and order phases by dependency/architecture structure (STRICT, PHASE-SPLIT-01)** — the orthodox unlimited-time build order: foundations (schema, contracts, core data flow) → core capabilities → integration → hardening/polish — so each phase consumes the verified output of the previous one. DB/API/UI/test work inside a phase are subtasks, and every phase closes with something independently verifiable (build, tests, or a demonstrable surface). Effort-based bucketing is FORBIDDEN (no "quick win vs heavy" buckets, impact/effort matrices, or time-boxed slices): phase boundaries encode build order, not the schedule. Larger work splits into multiple PABCD passes (§5). Read project docs and dev skills first. Write the complete plan internally, then report it simply — like a developer reporting to the CEO. Write a plan with two parts: **Part 1** — easy explanation of what will be built, in non-developer terms; **Part 2** — diff-level precision: exact file paths (NEW/MODIFY/DELETE), before/after diffs for MODIFY, complete content for NEW. For every planned conditional path, the accept criteria name its activation scenario (C-ACTIVATION-GROUNDING-01 — owner: C phase below). **Loop-spec header (DEFAULT, C2+):** open the plan with a compact loop-spec: Loop archetype (§11.4, carried from Interview) · Trigger · Goal (user-visible outcome) · Non-goals · Verifier (the command/gate and what it measures, not only pass/fail) · Stop condition · Memory artifact (worklog/devlog/checkpoint path) · Expected terminal states (§11.2) · Escalation condition. Goal mode also states the §11.5 resource scope. **Instrumentation before candidates:** when the archetype is open-ended optimization, the loop-spec MUST include a divergence plan: descriptor axes, cell/archetype assignments, candidate count, deterministic selection rule, and telemetry schema. With a score-only verifier, B's first work item is the telemetry, not a candidate — a scalar-only verifier plus discarded candidates is the §10 plateau signature by design. If anything is unclear, return to Interview (`cli-jaw orchestrate I`) — do NOT ask questions in P. ### §3.1 Implementation-Unit Documents Full documentation routine (P concretizes the docs, A audits them as a hard gate, D archives to `_fin/`, plus the mainstream design-doc/RFC translation table): `dev-scaffolding/references/implementation-log.md`. **Difflevel roadmap plan (STRICT, DIFFLEVEL-ROADMAP-01):** for any multi-phase unit (2+ work-phases), the FIRST P — or the dedicated design-only Phase-0 pass (§5) — must deliver the entire roadmap concretized: `000_plan.md` (objective, constraints, dependency-ordered work-phase map) PLUS every phase's decade doc written to full diff-level precision — each a copy-paste-executable PRD, not an outline or empty scaffold. Each later cycle's P re-verifies its pre-written doc against the current codebase (stale check), amends it, then executes. LOOP-CONTINUITY-01 (§10) applies. **Lexicographic separation (STRICT, LEXICO-SPLIT-01):** every document in a unit carries a numeric lexicographic prefix — bare semantic filenames (`PLAN.md`, `DIFF_PLAN.md`, `PHASES.md`, `RCA.md`, unnumbered folders) are an A-phase FAIL, not a style nit. Research/spec material (00-range) and implementation phase designs (decade ranges) are SEPARATE documents; mixing both in one doc fails the audit. **Unit residence (STRICT, UNIT-RESIDENCE-01):** every piece of development work belongs to an implementation unit (`devlog/_plan/YYMMDD_slug/`). Ceremony scales with class (§9); residence does not. C0-C1 fast-path work skips the PABCD ceremony but MUST leave a numbered record doc in its owning unit — next free index in the matching decade — stating what changed, why the fast path applied, and the verification evidence; no owning unit → create a minimal unit folder for it. Interview settles residence before P (§1). Devlog plan artifacts use decade-range numbering to separate concerns. **Prefixes are three digits** (`000_`, `010_`, `020_`); do not mix two-digit and three-digit prefixes. | Range | Purpose | |-------|---------| | 000–009 | Research, specs, MOC (`000_plan.md`, `001_api-survey.md`) | | 010–019, 020–029, ... | Phase 1, Phase 2, ... (`010_phase1-auth-module.md`) | Rules: - 000-range durable research is **mandatory for C4**, and for C3 only when state must persist across turns/agents, public contract or architecture decisions need durable audit, or the user/repo already uses devlog planning; optional for C0-C2 and low-persistence C3 (the work still leaves its numbered record in a unit, UNIT-RESIDENCE-01). - Sequential within decade; overflow (>10 docs) uses sub-index (`000_0_name.md`). - NEVER use bare filenames like `PLAN.md`, `DIFF_PLAN.md`, `PHASES.md`, `RCA.md`. Three digits rather than two because the range carries the meaning, and two digits make the tens column do double duty: `10` reads as both "decade 1" and "tenth document". With three, `010` is unambiguously phase 1's first doc and `001` is research's first. This rule was previously written as two-digit while current practice is three. Measured in `devlog/_plan/`: 492 three-digit documents against 107 two-digit ones, and the two-digit files are concentrated in units from 2026-06 (`260610_*`, `260618_*`, `260621_*`) while every unit from 2026-08 onward is three-digit. So the repository migrated and the rule text did not follow. Historical units keep their prefixes. Renaming them would break every inbound reference for no gain, so this rule governs new units. #### §3.2 Plan-quality rules Three authoring rules for P. Each is also an A blocker (§3 A, "Plan-rule checks"),