jaw-dev-pabcd

Structured 5-phase development. Advance with the required user approval or, in authorized goal mode, an evidence-backed checkpoint. > **C0/C1 work:** see `jaw-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. > **`jaw-dev` is canonical:** `jaw-dev` §0.2 Rule Classes, §3 Verification Gate, and §5 Safety Rules apply to all work governed by this skill. ## §1. Interview Trigger (MUST) Use Interview behavior for an interview request; read [Interview evidence and closeout](references/interview.md). Enter persisted I only when the user explicitly requests stateful orchestration or an active authorized PABCD workflow requires it. Read `jaw orchestrate status` first. An interview-only, read-only, or plan-only request does not itself authorize a state transition. Jaw's I→P readiness gate is soft; keep textual evidence and contradiction checks. - **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: **Before P settle three things** (DEFAULT, INTERVIEW-CLASSIFY-01): the work class (jaw-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). Apply this in HITL Interview when authorized, or in goal-mode planning without inventing an Interview round. An archetype discovered after candidates were burned indicates inadequate initial classification. **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): 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) 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 `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. ``` jaw orchestrate A --attest '{"from":"P","to":"A","did":"<the concrete plan you wrote: files/surfaces + approved plan path>"}' jaw orchestrate B --attest '{"from":"A","to":"B","did":"<audit and disposition>","auditOutput":"<review tail>","auditVerdict":"pass"}' jaw orchestrate C --attest '{"from":"B","to":"C","did":"<what you built + who verified it>"}' jaw orchestrate D --attest '{"from":"C","to":"D","did":"<what you checked>","checkOutput":"<paste the real tsc/test tail>","exitCode":0}' ``` The gate validates form and declared audit outcomes: a specific `did` is required; declared `auditVerdict:"fail"` blocks A→B, and `near-pass` requires `auditResidual`. C→D 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: approved plan path, changed-file list, verifier command, exit code, and relevant `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 enforces attestation shape and some declared outcomes; artifact truth and cycle ownership remain agent duties. **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 outside an authorized cycle does not become a recorded phase by narration. Read actual server state and document the real artifact before advancing; never fabricate a prior transition. **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 relevant check output — non-empty `checkOutput`, zero `exitCode` when supplied | | 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 supplied `--attest` object carries exact `from`, `to`, and a specific `did` for the transition. P→A may carry `planUnit` at the repository-approved plan location; its absence is advisory. A→B carries actual `auditOutput`, boss `auditVerdict`, and residual dispositions. The parser preserves `planUnit`, `workPhaseId`, `auditOutput`, `auditVerdict`, and `auditResidual`; declared `fail` blocks A→B and `near-pass` requires `auditResidual`. `testReceiptPath` is unsupported. See [phase control](references/phase-control.md) for real edge requirements and CLI limits. **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. See [phase control](references/phase-control.md). ## §3. Phases ### P — Plan Read [Plan phase](references/phase-plan.md) for the loop-spec, consultation when authorized, verifier/field-chain/bypass checks, and the reader summary. **PHASE-SPLIT-01:** order work-phases by dependency and give each a verifiable outcome. Name activation scenarios for conditional paths (C-ACTIVATION-GROUNDING-01). Plan-only scope does not authorize execution. Present the plan and obtain any required approval before P→A. ### §3.1 Implementation-Unit Documents For C2+ planning or any multi-cycle roadmap, read [Implementation units](references/implementation-units.md) (DIFFLEVEL-ROADMAP-01, LEXICO-SPLIT-01, UNIT-RESIDENCE-01). Use the repository-approved plan location; never create private records in a public checkout. C0 creates no numbered record; C1 records only inside an already-existing unit. C2+ follows the approved unit convention. For projects allowing in-tree records, `devlog/_plan/YYMMDD_slug/` remains the default placeholder; repositories forbidding them use an approved external location. Documents use decade-range numbering (000-009 research/spec/MOC, 010-019 phase 1, ...); never bare `PLAN.md`, `DIFF_PLAN.md`, `PHASES.md` or `RCA.md` (LEXICO-SPLIT-01). ### A — Plan Audit Read [Audit phase](references/phase-audit.md) for actual path, verifier and evidence review, then synthesize blockers and re-audit (AUDIT-LOOP-01). A declared `fail` cannot advance; near-pass records each residual disposition. The main agent judges the verdict and carries `auditOutput`, `auditVerdict` and, when applicable, `auditResidual` into A→B. Independent review is conditional on authorized delegation and an available employee. ### B — Build Implement the plan. You write code by default and own every verdict; a worker may write when its slice passes DISPATCH-ECONOMY-01 ([dispatch](references/dispatch.md)) and the dispatch is explicitly write-capable with a bounded scope (see Pitfalls). Workers without that grant are read-only verifiers. Do not create new source-of-truth folders unless approved in P; keep private records only in the repository-approved location. After implementing, output worker JSON for verification (code exists, integrates cleanly): NEEDS_FIX → fix and re-verify (repair thresholds §11.3); DONE → report to the user. ⛔ Wait for user approval. When approved, advance with the canonical B→C attestation form in §2.1. ### C — Check Read [Check phase](references/phase-check.md) for fresh target-specific verification, SoT sync (SOT-SYNC-01), rendered and paged artifacts (C-RENDER-GROUNDING-01), reachable conditional paths (C-ACTIVATION-GROUNDING-01), and the reader check (C-READER-01). C→D carries real nonempty `checkOutput`; an `exitCode`, if supplied, must be zero. Register and verify a `jaw bgtask` wake before yielding on a long external gate. ### D — Done Summarize the entire flow: what was planned (P), audited (A), built (B), checked (C); the list of files changed; any follow-up items. **Pessimistic close-out (DEFAULT, LOOP-PESSIMIST-01):** for loop/multi-pass work, D also records the negative delta: what did NOT improve, which hypothesis died this cycle, and one sentence answering "what evidence would show the current direction is wrong?" The next P quotes this (§10 LOOP-CONTINUITY-01). D→IDLE→P is a context/bias-flush boundary: the next cycle resumes from disk artifacts, not the transcript's accumulated assumptions. State returns to IDLE automatically. Project root configuration is persistent: D resets PABCD state but not `projectDirs`; `jaw project clear` only on explicit user request. ## §4. Rules 1. One phase per response (the gate-and-wait turn boundary; canonical approval rule in §2.1). Goal-mode exception: with an active goal, do not end the turn before D while PABCD-phases remain — keep going P→D, close D, re-enter P for the next work-phase. 2. Sequence: P → A → B → C → D. Use `jaw orchestrate reset` to restart. 3. Workers verify (read-only) by default; write-capable dispatch follows [dispatch](references/dispatch.md) DISPATCH-ECONOMY-01. Verdicts stay with the boss in B. 4. Goal-mode precedence: when a jaw goal is active (jaw-dev §0.4), use §2.1 with evidence-backed checkpoints (`jaw goal update`) instead of user approval; phase order, audit conditions, and verification intensity are unchanged. Gate quick-reference (strict vs goal mode): | Gate | Strict PABCD | Goal mode | |------|--------------|-----------| | P→A, A→B, B→C | user approval + `--attest` | evidence-backed checkpoint + `--attest` | | C→D | auto + `--attest` w/ `checkOutput`/`exitCode` | same | | Turn boundary | one phase per response | continue P→D within the cycle | ## §5. Terminology: work-phase vs PABCD-phase **work-phase** = one outcome slice of a larger goal (e.g. "Phase 3: Management API"); **PABCD-phase** = one letter P/A/B/C/D inside a single orchestration cycle. Work-phases need not be slices of one feature: successive cycles in the SAME session may target completely different features or plans under the same goal (LOOP-UNIT-CHAIN-01). "This needs its own PABCD" is a plan statement — append the unit to the slice map and run it as the next cycle, never a reason to end the goal or defer to a new session. **Invariant: one work-phase = one full PABCD cycle.** Run P→A→B→C→D, close D (→ IDLE), then `jaw orchestrate P` for the next work-phase. Never run B for several work-phases back-to-back or commit out of B without passing C and D. Depth scales per class (§9); the P→D **sequence** is never skipped. **Loop / multi-pass tasks** run one complete P→A→B→C→D cycle per work-phase. A two-or-more-cycle loop starts with a docs-only roadmap cycle (LOOP-DOCS-FIRST-01, DIFFLEVEL-ROADMAP-01); later P cycles revalidate their prewritten unit against the live tree. See [Implementation units](references/implementation-units.md) and [Goal and loop continuation](references/loop-continuation.md) (LOOP-READS-PABCD-01). With remaining authorized work, D→IDLE is followed by the next P (GOAL-IDLE-CONTINUE-01). ## §6. Repository Root Contract Before writing a PABCD plan or dispatching an employee, determine the actual working repository root with `pwd -P` from the target repo. If `Project root` is injected at the top of the system prompt, use it directly; if not, recommend the user configure it (Manager UI → Project settings, or `jaw project set /path/to/repo`) to avoid JAW_HOME/codebase confusion. Every A/B phase `jaw dispatch` task body MUST begin with `Project root: /absolute/path/to/current/repo`. Rules: `Project root` is the current working repository, never `JAW_HOME`; workers never infer the root from `~/.cli-jaw*`, `process.cwd()`, or a temp dir; all relative repo paths resolve against `Project root`; if it is unknown, STOP and ask before dispatching. ## §7. Shared plan and bounded dispatch