@khoavu882/doflow 0.0.0-stage → 2.0.0-beta.3

package/core/shared/skills/do-implement/SKILL.md

@@ -0,0 +1,222 @@
+---
+name: do-implement
+description: "Direct, standalone code implementation from a description, /do-code-review findings, or an existing task — no DoFlow chain artifacts required. Use when the user names /do-implement, says 'now implement that', 'fix what the review found' or 'address these comments', or /do routed a bug, refactor, dependency change or small edit here. A plain change request that names no /do-* skill goes to /do first, which classifies it and routes it back here when it fits. Skip it for questions, reviews, and new features that need the full chain."
+argument-hint: "[description of the change] [--from-review]"
+effort: medium
+---
+
+# do-implement
+
+A standalone extension skill, not a numbered phase of the DoFlow chain (`do-brainstorm → do-design
+→ do-plan → do-execute-plan → do-test → do-code-review`). Implements directly from whatever
+context is fed to it — a plain-language description, `/do-code-review`'s findings, or a pointer to
+an existing `requirement.md` / `design.md` / `plan.md` — without requiring any of those artifacts
+to exist first. `/do-execute-plan` is the chain's own implementation phase, built for orchestrating
+a full `plan.md` task checklist through specialist subagents with prerequisite gates; reach for
+this skill instead when there is no task checklist to orchestrate — a one-off fix, a described
+feature, or a batch of review comments to work through right now.
+
+## Invocation
+```text
+/do-implement [description of the change] [--from-review]
+```
+
+- With no arguments, and a `/do-code-review` (or `/code-review`) run earlier in the conversation:
+  `--from-review` is implied — work through that review's findings.
+- With a description: implement exactly what is described.
+- Either form may also name an existing artifact (`requirement.md`, `design.md`, a linked issue, a
+  specific `plan.md` task) as extra context. Reading it is welcome; it is never required.
+
+## Behavioral Flow
+
+Every DoFlow runtime call in this skill goes through the runtime seam. Resolve it **once** here and
+reuse `$DOFLOW` for every later call in this skill:
+
+```bash
+# Resolve the DoFlow runtime: nearest project install wins, then the global one.
+D=$PWD; while [ "$D" != / ] && [ ! -x "$D/.doflow/scripts/doflow/bin/doflow-run" ]; do D=$(dirname "$D"); done
+DOFLOW="$D/.doflow/scripts/doflow/bin/doflow-run"
+[ -x "$DOFLOW" ] || DOFLOW="$HOME/.doflow/scripts/doflow/bin/doflow-run"
+[ -x "$DOFLOW" ] || { echo "doflow: no runtime found in any .doflow/ above $PWD, nor at $HOME/.doflow. Run: npx @khoavu882/doflow install -t <harness>" >&2; exit 2; }
+```
+Run every command below from the project root — the walk-up starts at `$PWD`. On exit 2, print the message verbatim and stop; it names every path searched.
+
+1. **Gather context — don't demand it**:
+   - Invoked after `/do-code-review` or `/code-review` in this conversation, or with
+     `--from-review`: treat that review's findings as the work list, most-severe first, in the
+     order the review itself ranked them.
+   - Invoked with a description: treat that as the work list directly.
+   - If the current branch has an active DoFlow feature (`"$DOFLOW" paths --json` resolves a
+     `feature_dir`) and its `plan.md` already has a task matching the request, say so and offer
+     `/do-execute-plan` instead — that machinery exists for exactly this case, and duplicating it
+     here would just be a second, worse orchestrator. Proceed directly only if the user confirms
+     the lighter path, or if no such plan or matching task exists.
+   - Never block on a missing `requirement.md` / `design.md` / `plan.md`. Those artifacts are the
+     chain's business, not a precondition of this skill.
+
+**Stop when** every work-list finding the contract names has an answer or a stated gap, **and** the last round produced no new work-list finding. A round that only restates what you already have is the last round. Report the remaining gaps rather than continuing.
+
+2. **Resolve the task id, then evaluate readiness — skip only when standalone**:
+   - `<task id>` is the same unit every recording stage keys on: the plan task id when one exists,
+     otherwise the feature slug that step 1's `"$DOFLOW" paths --json` resolved, or the issue id you
+     were given. When none of those exist, there is nothing to look up — treat this run as standalone
+     and go straight to the exemption below.
+   - Check what is recorded against that id before touching anything:
+     ```bash
+     "$DOFLOW" evidence --task-id "<task id>" --json
+     ```
+   - **`evidenceCount` is 0 — standalone.** Nothing is recorded for this id, which is exactly the
+     no-chain-artifacts case this skill exists to serve (FR-002). Proceed to step 3 without
+     evaluating readiness and without compiling a context pack. State the exemption in step 6's
+     report as prominently as a block would be stated — a skipped gate the report never mentions
+     reads as a passed gate, and that silence is the failure this exemption must not become
+     (NFR-004).
+   - **`evidenceCount` is nonzero — not standalone.** An earlier stage already recorded work against
+     this task, so resolve its class the same way every classifying stage does — proposing whichever
+     of `bug`, `refactor`, `dependency-change` or `trivial-edit` the recorded work already fits.
+     `do-implement` never serves `feature`; that class's implementation stage is `/do-execute-plan`.
+     ```bash
+     "$DOFLOW" classify --task-class "<proposed>" --calling-skill do-implement --json
+     ```
+     Branch on the returned `outcome`, not the exit code. `ACCEPTED` — the returned `workflow` names
+     the validated class to evaluate readiness against. `REJECTED` — stop, print `message` verbatim
+     (it names `validClasses`), ask the user to choose from that set, then re-validate; never
+     substitute `feature` for the class that was rejected.
+   - Evaluate readiness before modifying anything. `do-implement` is the declared one-off path, so
+     it states that mode explicitly — the exemption is a flag, never an inference:
+     ```bash
+     "$DOFLOW" readiness --task-class "<validated class>" --task-id "<task id>" --mode standalone \
+       --verification-plan "<one line: how this change is verified>" --scope "<comma-separated paths this change touches>" --json
+     ```
+     Every call records its evaluation; `verify` bounds the change by a `--scope` path list, so a
+     change with no plan states its paths here. Both are inputs you state, reported back as
+     `Caller-stated`. Add `--slug=<feature slug>` when the task id is not the feature's slug.
+     Both `--task-class` and `--task-id` are required — omitting either exits 2 and names the valid
+     set. Branch on the returned `stageEntry.decision`, never the exit code or your own reading of
+     `state`: the entry policy is owned by the runtime, and this verb exits 0 for every state it
+     computes, so a zero exit is not a green light.
+     - **`STOP`** — refuse to modify source. Report which claim is conflicted and what evidence
+       disagrees, then stop. Do not edit anyway.
+     - **`ASK_USER`** — a decision is owed by the user. Ask it through the `RULE_04_QUESTIONS.md`
+       mechanism and wait; editing first would decide it silently on their behalf.
+     - **`ENTER`** — proceed to the context-pack call below. In standalone mode this includes
+       `NEEDS_EVIDENCE`: the unmet contract is reported, not enforced — relay the missing
+       requirements in step 6's report rather than presenting the edit as fully evidenced. When a
+       run for this task has its implementation stage pending, `NEEDS_EVIDENCE` is not enough:
+       gather what the report lists and call `readiness` again until it reports `READY`, before
+       the first source edit.
+     (`GATHER_FIRST` is the workflow-mode answer and does not arise under `--mode standalone`.)
+   - Once readiness has cleared (or been confirmed non-blocking), compile the prior context:
+     ```bash
+     "$DOFLOW" context-pack --task-id "<task id>" --json
+     ```
+     This verb exits 1 on an empty pack by design — nothing recorded is not the same as nothing
+     needed — and that non-zero exit is never read as success. Because this call only runs after the
+     evidence check above already found something recorded for this task id, an exit 1 here means
+     the compiled pack still held nothing usable (evidence with no linked claims, most likely):
+     treat that as a mismatch worth naming in step 6's report, not as license to proceed as though
+     there were no prior context to look for. On a normal, non-empty pack, carry its evidence and
+     claims into step 4's change set instead of re-deriving what an earlier stage already
+     established.
+   - The repository's `pre-implement-gate` hook checks file existence (`requirement.md` /
+     `design.md` / `plan.md`) on every `Edit`/`Write` call regardless of which skill is editing. On
+     a harness with an edit hook it also denies the edit of a task held to a readiness record that
+     is not `READY`; this step writes that record, and is not a way around the hook.
+
+3. **Understand before writing**:
+   - Read the files the change touches and their immediate neighbors — naming conventions, error
+     handling style, test structure — before writing anything. Evidence over assumption applies
+     here exactly as everywhere else in DoFlow: match what the codebase already does rather than
+     importing an unrelated house style.
+
+4. **Name the change set, then continue**:
+   - Before touching anything, write the change set out file by file: each file to be edited, the
+     change it takes, and what that change is for. Name what you are deliberately leaving alone.
+     The pass that decides what to change is still not the pass that makes it — deciding and
+     typing in one move is how the first plausible shape becomes the design — but the separation
+     is an ORDERING inside this run, not a turn boundary.
+   - The user asking to implement IS the authorization to implement: proceed to step 5 in the same
+     run. Ending the turn here to await approval the user already gave costs a round-trip and
+     duplicates the host's own edit-approval mechanisms.
+   - Stop after the change set only when one of two things is true: the user asked for the plan
+     rather than the change ("show me what you'd change first"), or naming the change set surfaced
+     a genuine user-owned decision — then ask it per `RULE_04_QUESTIONS.md` and wait, because
+     editing first would decide it silently.
+
+5. **Implement**:
+   - Make the complete change end-to-end. Never leave placeholder stubs (e.g. `// TODO: implement`),
+     unimplemented mock functions, or `throw new Error('Not implemented')` placeholders in the
+     produced change. Every changed component must be fully wired and functional.
+   - Before the first source edit, a run for this task needs step 2's recorded readiness to be
+     `READY`: the hook denies the edit otherwise where there is one, and elsewhere step 7's handoff
+     is refused after the edits are made. A standalone `NEEDS_EVIDENCE` does not pass it.
+   - Keep it scoped to what was asked — no bonus refactors, no speculative abstractions (the same
+     scope-discipline rule the chain's own artifacts would otherwise remind you of; here, hold
+     yourself to it directly).
+   - Add or update tests when the codebase already has a test convention to extend; skip it when
+     there is not one, rather than inventing a test harness the project doesn't otherwise use.
+   - When `paths --json` reports `has_decisions: true`, follow steps 1-4 of the decision step in
+     the guidance tree's `references/WORKFLOW_HANDOFF.md` once the change is made, whether or not
+     step 7 records a handoff, and before any handoff call.
+
+6. **Verify — name the check set before running it**:
+   - First, list the build/test/lint commands you found and where each came from (`package.json`
+     scripts, a `Makefile`, an obvious test runner config). That list is the contract for this
+     step; state it before running anything.
+   - Then run each one and report its result against that list. A command the list named and the
+     run did not reach is reported as not run, and a command the project does not have is reported
+     as absent — neither is dropped from the report. Never mark something done against a failing
+     suite.
+
+7. **Record the handoff — skip only when step 2 took the standalone exemption**:
+   - Step 2's standalone exemption (`evidenceCount` 0) means there was never a task id to begin
+     with — skip this step entirely; there is nothing to record against.
+   - Otherwise, `<task id>` and the validated class are the same ones step 2 already resolved.
+     Record this skill's completion of the implementation stage:
+     ```bash
+     "$DOFLOW" orchestrate --action handoff --task-id "<task id>" --calling-skill do-implement --note "<one line: what was implemented>" --result <passed|failed> --json
+     ```
+     Name the `DEC-###` ids step 5 registered in `--note`.
+     A handoff on a run whose implementation stage has a readiness template is refused unless
+     step 2's recorded readiness is `READY`.
+     Use step 6's verification outcome for `--result`: `passed` when every check in the named set
+     passed, `failed` when one did not — never omit it to imply a pass step 6 did not establish.
+     The runtime selects this class's implementation stage — the only mutating stage a caller may
+     complete — and returns `disposition`. `deferred` means a gate, an unfinished mutating stage
+     elsewhere, or a rejected run prevented it; report `reason` and stop, this skill resolves no
+     gate. Render the trail after a recorded completion:
+     ```bash
+     "$DOFLOW" render-audit --slug="<task id>" --json
+     ```
+   - Without this call, the orchestrator's cursor never advances past `implementation` for any
+     class that routes here — `bug`, `refactor`, `dependency-change`, `trivial-edit` all do — and
+     every later stage's own handoff call is refused with `blocked-on-mutating-stage:implementation`
+     until this one runs.
+
+8. **Report and hand off**:
+   - Summarize what changed, file by file, and why — not a restatement of the diff.
+   - If step 2 took the standalone exemption, state that plainly here — as visible as a block would
+     be, per NFR-004 — rather than only mentioning it in passing back in step 2. If step 2 evaluated
+     readiness instead, name the state it returned, whether the context pack held usable prior
+     context or came back mismatched-empty, and the handoff `disposition` step 7 recorded (or that
+     step 7 was skipped as standalone).
+   - Suggest `/do-code-review` as the natural next step, mirroring the pointer that skill's own
+     "Next Step" section already sends back here. If a chain feature's `plan.md` task happened to
+     get addressed along the way, say so explicitly rather than silently — `plan.md` bookkeeping
+     itself stays `/do-execute-plan`'s responsibility, not this skill's.
+
+## Boundaries
+
+**Will:** Implement directly from a description, review findings, or a named task; read and match
+existing repo conventions before writing; run whatever test/lint suite the project already has;
+work in any repo, whether or not it uses the DoFlow chain at all; record the stage handoff through
+`orchestrate`/`render-audit` when this run is not standalone, so the orchestrator's cursor can
+advance past the mutating stage only this skill may complete.
+
+**Will Not:** Require or generate `requirement.md` / `design.md` / `plan.md`; orchestrate a
+multi-task checklist through specialist subagents — that is `/do-execute-plan`'s job once a real
+plan exists; silently override the repository's own `pre-implement-gate` hook. That hook triggers
+on any `Edit`/`Write` call, not on which skill made it — a branch mid-chain with a started feature
+but no `design.md` still gets blocked here exactly as it would anywhere else, and that is by
+design, not a gap this skill works around. Resolve a workflow gate, or start a workflow run for a
+standalone implementation.

package/core/shared/skills/do-plan/SKILL.md

@@ -0,0 +1,219 @@
+---
+name: do-plan
+description: "Generate the implementation plan (HOW) and dependency-ordered task checklist from requirement.md + design.md (plus design/specs.md's IC-### interface contracts when the feature has one), with a Constitution Check gate, as Phase 3 of the doflow chain. Use whenever requirement.md and design.md exist and the next step is creating an actionable, owner-and-file-scoped task breakdown before implementation, or when the user says 'create an implementation plan', 'break this down into tasks', 'plan the work', or 'plan Phase 3'. Always activate this skill before executing feature implementation."
+argument-hint: "[--depth shallow|normal|deep]"
+effort: high
+---
+
+# do-plan
+
+Phase 3 of the doflow chain. Turns `requirement.md` (WHAT/WHY) + `design.md` (system shape) — and
+`design/specs.md`'s `IC-###` interface contracts when `/do-design` wrote one — into `plan.md` (HOW to
+implement, plus the dependency-ordered task checklist).
+
+## Invocation
+```text
+/do-plan [--depth shallow|normal|deep]
+```
+
+## Behavioral Flow
+
+1. **Resolve** — run the resolver, parse JSON. Every DoFlow runtime call in this skill goes through
+   the runtime seam. Resolve it **once** here and reuse `$DOFLOW` for every later call in this skill:
+
+```bash
+# Resolve the DoFlow runtime: nearest project install wins, then the global one.
+D=$PWD; while [ "$D" != / ] && [ ! -x "$D/.doflow/scripts/doflow/bin/doflow-run" ]; do D=$(dirname "$D"); done
+DOFLOW="$D/.doflow/scripts/doflow/bin/doflow-run"
+[ -x "$DOFLOW" ] || DOFLOW="$HOME/.doflow/scripts/doflow/bin/doflow-run"
+[ -x "$DOFLOW" ] || { echo "doflow: no runtime found in any .doflow/ above $PWD, nor at $HOME/.doflow. Run: npx @khoavu882/doflow install -t <harness>" >&2; exit 2; }
+```
+
+Run every command below from the project root — the walk-up starts at `$PWD`. On exit 2, print the message verbatim and stop; it names every path searched.
+
+```bash
+"$DOFLOW" paths --json
+```
+
+`feature_slug` `null` with a non-empty `candidate_slugs` is an unresolved choice, not "no active feature": ask one option per entry, re-resolve with `"$DOFLOW" paths --json --slug="<chosen>"`, and use that slug for the rest of this flow. `/do-flow` passing `--slug` already resolves it — no prompt then.
+
+2. **Propose one task class; the runtime validates it** — name exactly one class id for the work
+   being planned. `/do-flow` passes one when it invoked this skill; a user who named one settles it;
+   otherwise derive it from `requirement.md` and `design.md`, not from their mere existence.
+   ```bash
+   "$DOFLOW" classify --task-class "<proposed>" --calling-skill do-plan --json
+   ```
+Branch on the returned `outcome` field, not the exit code.
+- **`ACCEPTED`** — the returned `workflow` is this run's plan of record; read `stages`, `gates` and `handoff` off it rather than from memory.
+- **`REJECTED`** — **stop.** Print `message` verbatim (it already names `validClasses` and any `suggestions`), ask the user to choose from `validClasses`, then re-validate. Never substitute `feature`.
+  A rejection may be about **you** rather than the class (`reason: caller-not-a-stage`). Then the fix is to propose one of the classes in `fit.hostingClasses`, or to hand the work to the skill this class names for the stage you meant — not to re-propose the same class.
+- **Exit 2** — surface the message verbatim and stop.
+
+This skill is the accepted workflow's `planning` stage: state the class and the signal it rests on
+in one line. Its `stageIds` are also what §8's phases must decompose toward, and its implementation
+stage's `readinessTemplate` names the contract `/do-execute-plan` will be graded against — read them
+off the returned object rather than assuming the six-stage feature chain. If the accepted `stageIds`
+contain no `planning` stage, say so and hand off to the first stage they do name. Only `feature`
+plans; `bug`, `refactor`, `dependency-change` and `trivial-edit` go straight from their analysis
+stages to implementation, and writing them a `plan.md` adds a gate their workflow deliberately does
+not have.
+
+3. **Precondition (advisory)** — if `has_requirement` or `has_design` is false, warn and offer to
+   run `/do-brainstorm` / `/do-design` first. This gate is **advisory** (skippable), not the hard
+   hook gate.
+4. **Read inputs** — compile the recorded prior context first, using the same task id rule step 10
+   uses below (the plan task id for anything already scoped to a single `- [ ]` task, otherwise the
+   feature slug):
+   ```bash
+   "$DOFLOW" context-pack --task-id "<task id>" --json
+   ```
+   **Exit 1 means the pack came back empty.** By this point `do-design` should already have batched
+   its own stage-boundary evidence and claims (its step 8), so an empty pack here carries more
+   weight than it does at design time: either that batch never ran, or this task id doesn't match
+   the one design used. Treat it as advisory rather than blocking — plan's hard gate is artifact
+   existence only — but say so plainly in this stage's report, and in `plan.md`'s own §3 "Research &
+   Decisions": a decision written straight from `requirement.md`/`design.md` prose, with no compiled
+   pack behind it, must not be recorded as if it traced to prior evidence it doesn't have. When the
+   pack is non-empty, read it alongside `requirement.md`, `design.md`, and the constitution.
+   **Also read `specs.md` when step 1's `has_specs` is true** — use that flag, never a filesystem
+   check of your own, and read the `specs` path the resolver returned. `/do-design` moves the
+   interface and data-model contracts out of `design.md` into `specs.md` §1 as numbered `IC-###`
+   entries, so on a feature that has one, `design.md`'s §4/§5 are a pointer and the contracts this
+   plan must decompose toward live only in `specs.md`. Planning from `design.md` alone on such a
+   feature plans against a pointer. When `has_specs` is false (an old-layout feature dir, which never
+   had a `specs.md`), the contracts are still in `design.md` §4/§5 and there is nothing extra to
+   read. Read
+   `constitution_base`,
+   then read `constitution_local` **only when `has_constitution_local` is true** — use that flag,
+   never a filesystem check of your own (path math belongs to the resolver). You then reconcile the
+   two tiers yourself, tier-2 taking precedence: nothing hands you a merged set. See
+   the guidance tree's `references/DOFLOW_CHAIN.md` → "Two-tier constitution" for what is computed
+   and what is convention.
+5. **Write `plan.md`, sections 1–7** — copy the plan template to the `plan` path step 1 resolved
+   (`<feature_dir>/plan.md`, the same flat location under both the structured and legacy layouts),
+   `mkdir -p`-ing its parent directory first.
+The template is `templates/doflow/plan-template.md` in the install step 1 resolved: take `constitution_base` from that JSON and swap its trailing `guidance/references/CONSTITUTION_BASE.md` for that path.
+   Fill `[REQUIREMENT_PATH]`/`[DESIGN_PATH]` with that same step 1 resolution's `requirement`/`design`
+   fields, verbatim (repo-root-relative, exactly as the resolver returns them) — never hand-written
+   `./` links, which assume the artifact sits next to `plan.md`; under `layout: structured` it
+   instead sits in a sibling subdirectory, and only the resolver's own field says which.
+   Fill it: approach, research/decisions that resolve every `[NEEDS CLARIFICATION]` from the
+   requirement, components, data/contracts, risks, validation strategy.
+   §5 "Data / Contracts" cites contracts by id, not by pointer: when step 4 read a `specs.md`, name
+   the `IC-###` ids that this plan's tasks implement or consume, one per contract, so a task can be
+   traced to the contract it satisfies. Pointing §5 at `design.md` is only correct when `has_specs`
+   is false and the contracts genuinely still live there.
+   When the feature has a `data-model.md` (check the resolver's `has_data_model` flag, the same way
+   `has_specs` is already checked), also name any entities/tables from its schema catalog that this
+   plan's tasks touch, citing them by the name the schema catalog already gives them — never
+   inventing a new id scheme, since `data-model.md` carries no `ID`-bearing index the way `specs.md`
+   does.
+**Stop when** every `[NEEDS CLARIFICATION]` marker / open decision the contract names has an answer or a stated gap, **and** the last round produced no new `[NEEDS CLARIFICATION]` marker / open decision. A round that only restates what you already have is the last round. Report the remaining gaps rather than continuing.
+Structure the artifact per the guidance tree's `references/ARTIFACT_FORMAT.md` — read it before filling the template; it names which of this artifact's sections take an index-then-detail table.
+Filling §8's task dependency graph, read the guidance tree's `references/DIAGRAM_GUIDE.md` first — §4 above names the slot, that file governs what goes in it: the `flowchart` node and edge ceilings, the direction convention, and the rule for splitting a graph that outgrows them.
+   Its §5 governs §8's `### Task Summary` rollup — the per-task `- [ ]` checklist stays the single
+   source of truth and is never mirrored into a per-task index.
+   Read `references/ARTIFACT_VOICE.md` at the same point: it carries the prose rules the artifact's sentences follow, and the carve-outs where one of those rules meets a construct the checker parses.
+   This stage fills the plan from requirement + design + constitution rather than by eliciting, so
+   it writes no dialogue log — its sibling stages' `intention/`/`design/` question files have no
+   counterpart here. Should a future revision of this skill add an `AskUserQuestion` clarification
+   loop, each of its rounds logs to `plan-<NN>-question.md` at the feature root exactly as
+   `/do-brainstorm` and `/do-design` log theirs to their own subdirectories, numbered from step 1's
+   `plan_next_round`.
+6. **Constitution Check (advisory gate)** — evaluate the plan against both tiers as reconciled in
+   step 4. On a violation, STOP and revise the approach before continuing, then record PASS/FAIL in
+   the plan. The verdict is **advisory**: it is recorded in `plan.md` §2 "Constitution Check" and nothing downstream
+   blocks on it — the chain's one hard gate covers artifact existence only. Stopping on a violation
+   is a discipline this skill observes, not something a hook enforces.
+7. **Decompose into Tasks (section 8)** — dependency-ordered, `[US#]`-traced to the requirement's
+   user stories, owner+files named per task, with checkpoints and completion criteria.
+   Read the guidance tree's `references/ORCHESTRATION.md` and
+   `references/MODEL_SELECTION.md` before assigning agent owners and write sets.
+   `--depth shallow|normal|deep` is the single granularity knob: it sets how finely a phase is
+   split into tasks and how much detail each task carries. Default `normal`.
+   **Why explicit task scoping and `[P]` markers**: Specifying concrete file paths (`files: [...]`)
+   and named specialist owners (`system-architect`, `core-implementer`, `quality-guardian`) per task
+   enables `/do-execute-plan` to compute write-set isolation (`parallel-check`). Tasks with disjoint
+   file sets run concurrently without merge conflicts, while overlapping tasks are safely serialized.
+   **Mark `[P]` by default:** parallel execution is the framework default, so apply `[P]` to every
+   task whose `files:` set is disjoint from its phase siblings' and leave it off only where a real
+   dependency forces the order — an unmarked task is the exception that owes a reason, not the norm.
+   Siblings that write any path in common are not parallel-safe however independent they otherwise
+   look, so compare the actual `files:` sets rather than judging by description. Do not change the
+   marker's syntax or meaning: unmarked still means sequential, which is what keeps plans written
+   before this rule behaving as they always did.
+   Set `depends-on:` on a task when it references a service (via its
+   `files:` or description) that has no owning task in this plan and is external to what the plan
+   builds. When such a dependency has no local repo at all (a vendor API, a SaaS integration) but
+   *does* have a documented contract, also set `external-contract:` pointing to a doc built from
+   `templates/doflow/external-contract-template.md` — `/do-execute-plan --scaffold` generates a real
+   frame from it instead of silently skipping the dependency (its default when `external-contract:` is
+   absent). The `- [ ]` checkboxes are the execution contract `/do-execute-plan`
+   parses — keep the marker syntax intact, don't reflow it into prose.
+8. **Derive branch plan** — read `requirement.md`'s `**Ticket:**` field (absent/`none` → no
+   ticket). Branch name: `feat/<TICKET>-<slug-description>` (ticket present, slug's leading
+   `NNN-` stripped) or `feat/<slug>` (no ticket). Resolve a repo for each task's `files:` path
+   *and* each task's `depends-on:` value the same way — walk up to the nearest `.git`; if a
+   `depends-on:` value doesn't resolve to a `.git` (not a real local path), skip that row rather
+   than guessing. `external-contract:` never participates in this derivation — it names a doc in this
+   same repo, not an external service repo. Write one row per repo to `plan.md`'s Repo Branch Plan
+   table: `primary` if it owns a task via `files:`, `dependency-only` if it's only ever reached via
+   `depends-on:`. A single-repo result → `N/A: single-repo feature`. Derivation only — no branch is
+   created here (`/do-execute-plan`'s job, lazily, per repo).
+9. **Validate** — run the advisory consistency check and surface any findings verbatim:
+   ```bash
+   "$DOFLOW" validate "<plan path>"
+   ```
+   This also verifies each `### Task Summary` rollup row against the `- [ ]` lines under its
+   `### Phase <X>` heading. Surface findings verbatim; a non-zero exit is advisory and does not halt
+   the chain.
+10. **Batch this stage's evidence** — one pass here at the stage boundary, never one call per fact.
+    `<task id>` is the unit these stores key on: the plan task id for anything scoped to a single
+    `- [ ]` task, otherwise the feature slug. Use the same id for every `evidence`, `claim` and
+    `readiness` call that concerns it — a different id reads a different task's record.
+    ```bash
+    "$DOFLOW" evidence --task-id "<task id>" --action add --batch <batch>.json --json
+    "$DOFLOW" claim --task-id "<task id>" --action add --statement "<one conclusion>"
+    ```
+Item schema, provenance rules, and the refused-field list: the guidance tree's `references/EVIDENCE_LEDGER.md`. Read it before writing the batch.
+    This stage's items are §3 "Research & Decisions" of the `plan.md` you just wrote: per decision,
+    what was found, where it came from, and its locator. Add each §3 decision as a claim in the same pass: by `D#`, or, with a register, new
+    planning decisions by statement (their `DEC-###` IDs are written back at the handoff step).
+11. **Record the handoff** — read the guidance tree's `references/WORKFLOW_HANDOFF.md`.
+   Use the feature slug as `<task id>`; if no feature is active, this is standalone and there is
+   no workflow handoff. After completing this skill's work:
+   ```bash
+   "$DOFLOW" orchestrate --action handoff --task-id "<task id>" --calling-skill do-plan --task-class "<validated class>" --note "<work completed and verification result>" --json
+   ```
+   The runtime selects this skill's stage, records completion or a rerun annotation, and returns
+   `disposition`. Report `deferred` with its `reason`; resolve no gate in this skill.
+   `standalone` means no run was created. Render the trail after a recorded handoff:
+   ```bash
+   "$DOFLOW" render-audit --slug="<task id>" --json
+   ```
+   Leave any returned approval gate for `/do-flow` or `/do-execute-plan` to present.
+
+12. **Stop** — report the plan path, Constitution Check result, the task count (`[P]`/sequential),
+   and the derived branch name/repo count when the Repo Branch Plan is populated.
+
+## Embedded feature research
+
+For an external fact gap or explicit request, follow the conditional protocol in `../do-document/references/embedded-research.md` before stage completion.
+
+## Boundaries
+**Will:** propose a task class and have the runtime validate it, read requirement + design + specs
+(when `has_specs`) + constitution, cite `specs.md`'s `IC-###` contracts in §5, write `plan.md`
+including its embedded task checklist and Repo Branch Plan, run the
+Constitution Check, resolve clarifications, batch the stage's evidence and claims at the boundary,
+and record the stage handoff through `orchestrate`/`render-audit`.
+**Will Not:** write `design.md` or `specs.md` (that's `/do-design`) — it cites their contracts, it
+does not author or amend them — write code, execute the plan, decide the
+approval gate its own handoff opens, create any
+git branch (derivation only), plan under a class the runtime rejected or replaced with `feature`,
+call `readiness` for a stage that declares no template; or express evidence, an estimate or readiness as a number, a percentage or a confidence.
+
+## CRITICAL BOUNDARIES
+**STOP AFTER PLAN CREATION.** Output: `agent-docs/doflow/<slug>/plan.md` (HOW + tasks).
+
+**Next Step:** `/do-execute-plan` to execute the tasks. The implement phase is gated: it requires
+`requirement.md`, `design.md`, and `plan.md` to all exist.

package/core/shared/skills/do-test/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: do-test
+description: "Execute project builds, automated test suites, and coverage verification with intelligent error reporting across whatever toolchain the repo already uses. Use whenever the user wants to run existing tests, execute test suites, verify builds, check test coverage, or check compile status (e.g., 'run the tests', 'execute test suite', 'check coverage', 'verify build', 'does this still build'). Always activate this skill when verifying test suites or running builds without writing new application code."
+argument-hint: "[target] [--clean] [--watch]"
+effort: medium
+---
+
+# do-test
+
+Unified build verification and test runner for DoFlow projects.
+
+## Invocation
+```text
+/do-test [target] [--clean] [--watch]
+```
+
+## Behavioral Flow
+
+1. **Resolve the runtime** — every DoFlow runtime call in this skill goes through the runtime seam.
+   Resolve it **once** here and reuse `$DOFLOW` for every later call in this skill:
+
+```bash
+# Resolve the DoFlow runtime: nearest project install wins, then the global one.
+D=$PWD; while [ "$D" != / ] && [ ! -x "$D/.doflow/scripts/doflow/bin/doflow-run" ]; do D=$(dirname "$D"); done
+DOFLOW="$D/.doflow/scripts/doflow/bin/doflow-run"
+[ -x "$DOFLOW" ] || DOFLOW="$HOME/.doflow/scripts/doflow/bin/doflow-run"
+[ -x "$DOFLOW" ] || { echo "doflow: no runtime found in any .doflow/ above $PWD, nor at $HOME/.doflow. Run: npx @khoavu882/doflow install -t <harness>" >&2; exit 2; }
+```
+
+Run every command below from the project root — the walk-up starts at `$PWD`. On exit 2, print the message verbatim and stop; it names every path searched.
+
+2. **State the contract before running anything** — compile it, do not recall it:
+
+   `<task id>` is the plan task id when the run is scoped to one task, otherwise the feature slug —
+   the same id every other stage used for it. `--risk` is an input the caller supplies: omitted, the
+   contract compiles at the registry's default; a change touching security, auth, payments or data
+   migration is what `HIGH` is for, and the level also sets `maxRecoveryIterations`.
+
+   Optionally ask for a decision-model second opinion before compiling the contract:
+
+```bash
+"$DOFLOW" advise --kind verify-risk --state "<what the change touches, one paragraph>" --static "<the level you chose>" --task-id "<task id>" --json
+```
+
+   When `status` is `answered` and `agrees` is `false`, say so in one line and keep or change the level
+   by your own judgement. Record the level used with `"$DOFLOW" advise --action outcome --pick-id
+   "<pickId>" --actual "<level>"`. Skip both calls when `status` is not `answered`.
+
+```bash
+"$DOFLOW" verify --task-id "<task id>" --risk "<LOW|MEDIUM|HIGH|CRITICAL>" --action contract --json
+```
+
+   Report, before a single tier runs:
+   - the compiled `tiers[]` in the order returned — that list, and nothing else, is what will run;
+   - the `riskLevel` it compiled at and the `maxRecoveryIterations` it carries;
+   - `detection.absent` — the command roles the runtime could not find in this repo's manifests
+     (`detection.manifests` names what it read). Those are the tiers most likely to come back
+     unresolved, and naming them up front is the difference between a gap and a surprise.
+
+   Detection belongs to the verb. Do not re-derive the toolchain by hand, and do not substitute a
+   runner the contract did not compile.
+
+3. **Run the contract and report against it**:
+
+```bash
+"$DOFLOW" verify --task-id "<task id>" --risk "<the same level>" --action report --json
+```
+
+   When an explicit manifest and pinned ancestor baseline are provided, pass `--verification-input <file> --verification-phase postimplementation --baseline-ref <ref>`; the verdict proves current checks under postimplementation chronology without claiming preimplementation compilation.
+
+   Every tier step 2 listed gets a status in the report — `PASS`, `FAIL`, `UNRESOLVED`, `SUBSUMED`,
+   `NOT_APPLICABLE`, `SKIPPED` or `NOT_RUN`. Report all of them. A tier the contract named and the
+   run did not reach is reported as unreached, never omitted.
+**Stop when** every required tier the contract names has an answer or a stated gap, **and** the last round produced no new required tier. A round that only restates what you already have is the last round. Report the remaining gaps rather than continuing.
+
+4. **Read the verdict as it stands**:
+   - A tier whose command cannot be detected is `UNRESOLVED`, and one unresolved required tier makes
+     the whole run `INCONCLUSIVE`. The verb computes that and returns it in `status` with a `reason`
+     naming the tiers — report it as it stands. Never call a check passed that was not run, and
+     never narrow the set to make the report green.
+   - Coverage comes with the test tiers and with what the detected runner already emits, not from a
+     separate request: report line and branch numbers when the runner produces them, and say
+     plainly that it does not when it does not.
+   - `--clean` forces a clean compile before the deterministic tiers run.
+   - `--watch` launches interactive watcher mode when the detected runner supports it. It is an
+     interactive session, not a verification run: it produces no contract verdict.
+
+5. **Diagnostics & Reporting**:
+   - Report pass/fail summaries, exact failure traces, and affected requirements.
+   - Never skip or delete failing tests to force passing status.
+
+6. **Record the handoff** — read the guidance tree's `references/WORKFLOW_HANDOFF.md`.
+   Use the feature slug as `<task id>`; if no feature is active, this is standalone and there is
+   no workflow handoff. After completing this skill's work:
+   ```bash
+   "$DOFLOW" orchestrate --action handoff --task-id "<task id>" --calling-skill do-test --note "<work completed and verification result>" --result <passed|failed> --json
+   ```
+   The runtime selects this skill's stage, records completion or a rerun annotation, and returns
+   `disposition`. Report `deferred` with its `reason`; resolve no gate in this skill.
+   `standalone` means no run was created. Render the trail after a recorded handoff:
+   ```bash
+   "$DOFLOW" render-audit --slug="<task id>" --json
+   ```
+   `passed` means the contract was met, including an expected failure in a reproduction stage.
+   Use `failed` when it was not met; missing verification is `unverified`, never an implied pass.
+
+## Embedded feature research
+
+For an external fact gap or explicit request, follow the conditional protocol in `../do-document/references/embedded-research.md` before stage completion.
+
+## Boundaries
+**Will:** Run the compiled tiers, report every status (including unreached), coverage, and failure traces; hand off the current stage in a chain.
+**Will Not:** Write tests or build config, narrow tiers, invent a verdict, resolve gates, or start a standalone run.

package/core/shared/templates/doflow/constitution-template.md

@@ -0,0 +1,28 @@
+# [PROJECT NAME] Constitution
+
+**Version:** 0.1.0 · **Ratified:** [DATE] · **Last amended:** [DATE]
+
+<!-- SYNC IMPACT REPORT (filled by /do-constitution on each change):
+     version: [old] → [new] · changed: [...] · propagated to: [...] -->
+
+> Persistent, cross-feature rules every phase and agent inherits. This is the **tier-2**
+> per-repo overlay on top of `CONSTITUTION_BASE.md`; these rules take precedence on conflict.
+> The overlay is performed by the chain skill reading both files — see `DOFLOW_CHAIN.md` →
+> "Two-tier constitution" for what is computed and what is convention. Bump the version (semver)
+> on any change and fill the Sync Impact Report above.
+
+## Principles
+
+### [PRINCIPLE_1_NAME]
+[PRINCIPLE_1_STATEMENT — testable and non-negotiable.]
+
+### [PRINCIPLE_2_NAME]
+[PRINCIPLE_2_STATEMENT.]
+
+## Constraints
+- [stack / tooling / process constraint specific to this repo].
+
+## Governance
+- Amendments: bump semver, fill the Sync Impact Report, re-run dependent gates.
+- `/do-plan`'s Constitution Check MUST evaluate against both tiers together (these rules taking
+  precedence). Its verdict is advisory — recorded, not blocking.