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

package/core/shared/skills/do-execute-plan/references/readiness_gate.md

@@ -0,0 +1,155 @@
+# Task Readiness Gate
+
+Pre-implementation contract gate. The contract is versioned and lives inside the runtime, not on
+this page and not in your repository: **query it through the verb, don't recall it.** The class
+names and requirement ids below are reproduced for orientation only — when this page and the
+command disagree, the command is right.
+
+```bash
+"$DOFLOW" readiness --task-class <class> --task-id <id>          # human-readable report
+"$DOFLOW" readiness --task-class <class> --task-id <id> --json
+"$DOFLOW" evidence  --task-id <id>                               # what has been recorded so far
+"$DOFLOW" evidence  --task-id <id> --action add --batch <file>   # record this stage's batch
+"$DOFLOW" claim     --task-id <id> --action list                 # and what has been concluded
+```
+
+`$DOFLOW` is the handle `SKILL.md` step 1 resolves; run these from the project the task belongs to,
+because evidence and claims are per-project state under that repo's `.doflow/state/evidence/`, not
+global.
+
+Every `readiness` call records its evaluation under `.doflow/state/readiness/`, replacing the
+task's earlier one. The implementation handoff and `complete-stage` read that record and refuse
+without a `READY` one made before the call; they evaluate nothing themselves, and the refusal names
+the `readiness` command to run. A `verify` report that would be `PASS` on a task whose implementation
+stage is still pending is `INCONCLUSIVE` while that record is missing or not `READY`.
+
+**Both `--task-class` and `--task-id` are required on `readiness`.** Omitting either exits 2 with
+the valid set named — the verb refuses rather than grading the wrong class or the wrong task.
+`readiness` then exits **0 for every state it can compute**, so branch on the `state` field; a zero
+exit says the contract was evaluated, not that it was met.
+
+## Task classes
+
+Pass the **key**, not the display name — `--task-class feature`, not `"New Feature"`.
+
+| Key | Contract | Requirements |
+| :--- | :--- | :--- |
+| `bug` | Bug Fix Readiness | `reproduction`, `affected_code`, `root_cause`, `blast_radius`, `regression_verification` |
+| `feature` | Feature Implementation Readiness | `scope_clear`, `affected_components`, `verification_plan` |
+| `refactor` | Refactoring Readiness | `architecture_mapped`, `invariants_captured`, `baseline_tests`, `blast_radius` |
+| `trivial-edit` | Trivial Edit Readiness | `target_identified`, `scope_verified` |
+| `dependency-change` | Dependency Change Readiness | `compatibility_checked`, `usage_impact`, `verification_command` |
+
+These five are the only templates that exist. Every other declared task class has **no** readiness
+template, by design: those workflows author no source, so there is nothing for an implementation
+contract to gate. Which classes those are is a property of the resolved workflow —
+`requiresImplementationReadiness: false` — not a list to carry here. The verb exits 1 on them and lists the valid
+keys — that is the right answer, not a gap. Any other unknown class fails the same way, so a typo
+is loud rather than silently evaluating the wrong contract.
+
+## Reading the report
+
+Each unmet requirement carries a `recommendedAction` naming the **intent** and **capability** that
+would satisfy it — `blast_radius`, for example, recommends `estimate-blast-radius` /
+`code.impact-analysis`. Resolve it against this machine with
+`"$DOFLOW" route --intent <intent> --json`, which reports the provider that actually answers here
+and its fallback chain, then go gather that evidence. The gate tells you what is missing *and* how
+to go get it.
+
+| State | Meaning |
+| :--- | :--- |
+| `READY` | Every mandatory prerequisite is verified by fresh evidence |
+| `NEEDS_EVIDENCE` | Contract understood, prerequisites not yet established |
+| `NEEDS_USER_DECISION` | A design or architectural decision is owed by the user |
+| `BLOCKED` | A claim on this task is `conflicted` — evidence disagrees with itself |
+
+These four are the whole vocabulary. There is no fifth state, no partial state, and no numeric or
+percentage rendering of any of them — a gate that emits a number invites the reader to round it up.
+All four are reachable through the seam; the next section says exactly which input produces each.
+
+**What to do about a state is not this page's call, and not yours** — the runtime owns the one
+stage-entry policy and every report carries its answer as `stageEntry: {decision, reason}`
+(`Stage Entry:` in the human report), computed from the state and the execution mode you declare
+with `--mode`:
+
+| | `--mode workflow` (default) | `--mode standalone` |
+| :--- | :--- | :--- |
+| `READY` | `ENTER` | `ENTER` |
+| `NEEDS_EVIDENCE` | `GATHER_FIRST` — gather the named requirements before entering the stage | `ENTER` — the unmet contract is reported, not enforced; relay it in the result |
+| `NEEDS_USER_DECISION` | `ASK_USER` — ask through `RULE_04_QUESTIONS.md` and wait | `ASK_USER` — same; a small edit does not cure an owed decision |
+| `BLOCKED` | `STOP` — never modify source; surface which claim and which evidence | `STOP` — same |
+
+`workflow` is an orchestrated run (`do-flow`, `do-execute-plan`); `standalone` is a declared
+one-off edit (`do-implement`, `do-diagnose --fix`). The mode is a flag, never an inference — an
+absent evidence record is not a statement of intent, so the default fails closed to `workflow`.
+Act on `decision`; do not re-derive the answer from `state`, because a policy re-derived in prose
+is exactly how three skills came to disagree about the same state.
+
+The engine fails closed: a requirement it cannot evaluate reads as unmet, not satisfied. A gate that
+guesses in its own favour is worse than no gate, because it reports a verdict it never earned.
+
+## What produces each state
+
+`readiness` grades three inputs. Knowing which one moved a verdict is the difference between a
+contract that was met and one that was described as met.
+
+| Input | Written by | What it can satisfy |
+| :--- | :--- | :--- |
+| Evidence | `evidence --task-id <id> --action add` — one item from `--kind/--provenance/--provider/--capability/--locator/--content`, plus `--establishes <req-id[,req-id]>` and (for executions) `--observed-command`/`--observed-exit`; or a whole stage from `--batch <file>` | every requirement declaring evidence kinds: `reproduction`, `affected_code`, `blast_radius`, `affected_components`, `architecture_mapped`, `baseline_tests`, `target_identified`, `compatibility_checked`, `usage_impact` |
+| Claims | `claim --action add` (with `--role root-cause` where the contract names a role), promoted by `claim --action link` | `root_cause`, the one requirement that demands a `supported` claim **in the `root-cause` role**. A `conflicted` claim additionally forces `BLOCKED` for the whole task |
+| Caller-stated profile | stated on `readiness`, not on `handoff`: `readiness --verification-plan <text>` · `--scope <text>` · `--invariants <text>` · `--user-decision-pending` | `verification_plan`, `verification_command`, `regression_verification` (from `--verification-plan`); `scope_clear`, `scope_verified`, `invariants_captured` (from `--scope` or `--invariants`) |
+
+So each state arrives as follows.
+
+- **`NEEDS_EVIDENCE`** — the default answer for a task with nothing recorded. Every required
+  entry the batch has not covered and no stated input satisfies is listed with its
+  `recommendedAction`. This is the checklist, not a malfunction.
+
+  An item counts toward a requirement only when it is `extracted` **and** names that requirement
+  in `establishes` — kind alone is a category, and an inferred item is analysis, not measurement.
+  Where the contract expects an execution (`reproduction`, `baseline_tests`), the item must carry
+  the observation `{command, exitCode}` it records, and `baseline_tests` additionally requires
+  exit 0: a run that failed is reported as the failure it was. A bug reproduction succeeds by
+  observing the expected failure, so a non-zero exit there is the evidence, not a defect in it.
+- **`READY`** — recorded evidence plus stated inputs cover every required entry. Each satisfied
+  requirement names the evidence ids that satisfied it in `evidenceIds`; a requirement satisfied
+  by a *stated* input carries an empty `evidenceIds`, because nothing backs it but the statement.
+- **`BLOCKED`** — a claim on the task is `conflicted`: it carries both fresh supporting and fresh
+  contradicting evidence. Blocking is checked before requirements, so `BLOCKED` outranks
+  `NEEDS_EVIDENCE` — a blocked task is not "also missing things", it is stopped.
+- **`NEEDS_USER_DECISION`** — you passed `--user-decision-pending`. It returns before any
+  requirement is examined, so that report carries no requirements breakdown. It records that a
+  decision is owed; it is not a way to skip the gate.
+
+**Measured and stated are reported apart, and must stay apart when you repeat the verdict.** The
+JSON report lists every stated input under `callerAsserted`; the human report prints
+`Caller-stated: … (asserted on the command line, not established by evidence)`. Pass those flags
+when they are true — that is what they are for — but a `READY` that rests partly on them is only as
+good as the statement, and saying so is the difference between reporting a verdict and laundering
+one.
+
+Three limits still hold, and none of them is a reason to work around the gate:
+
+- Only evidence whose `freshness.status` is `FRESH` counts. The write measures freshness itself —
+  HEAD commit, sha256 of the located file, `observedAt` — and records `null` for anything it cannot
+  establish, rather than a value that happens to parse. Every `readiness` read and every gated
+  stage completion re-checks those stamps against the tree as it stands — the same evaluation at
+  both boundaries — so an item whose file has changed since it was read reports `STALE` and stops
+  counting toward the requirement it named, and the report names it. Recording fresh replacement
+  evidence alone does not clear this: a stale item stays in the ledger and keeps forcing
+  `NEEDS_EVIDENCE` at the task level until it is explicitly retired. Once the fresh replacement is
+  recorded, supersede the stale item: `evidence --action supersede --evidence-id <stale-id>
+  --replaced-by <fresh-id>`. Do not argue with the verdict by any other route — not by re-adding the
+  same fact under a new id and hoping the old one stops mattering, and never by editing the local
+  ledger file directly.
+- `claim --action link` refuses an evidence id the ledger does not hold (exit 2). Record the batch
+  first, then link; a link is not a way to reference evidence you have not written.
+- The gate grades this task's ledger only. A different `--task-id` reads a different record, and
+  the verdict will look confident either way.
+
+What the gate delivers is worth running for its own sake: the exact per-class contract, which
+requirements are unmet, and the intent and capability that would satisfy each one. Act on it as the
+checklist it is. Do not halt indefinitely on a persistent `NEEDS_EVIDENCE` — record what you
+actually established, state which requirements it covers, and say what remains. And do not write
+`READY` yourself. The gate did not say it, and saying it on the gate's behalf is precisely the
+failure this page exists to prevent.

package/core/shared/skills/do-execute-plan/references/run_position.md

@@ -0,0 +1,63 @@
+# Step 3 — positioning the run and dispatching on gate state
+
+The gate-state dispatch behind `/do-execute-plan`'s step 3. The step's own purpose — which gate
+stands before this stage, and why this skill is where it gets answered — stays in `SKILL.md`; what
+follows is the call that positions the run and every branch off its response.
+
+- `<slug>` is step 1's `feature_slug`; `<class>` is the class step 2's `classify` call accepted;
+  `<stage id>` is the id of the entry in that call's `workflow.stages[]` whose `skill` is
+  `do-execute-plan` (`implementation` in the `feature` workflow) — read it off that response,
+  never hardcode a guess. One call positions the run: it starts one when none exists yet (an
+  old-layout feature, or a chain that skipped straight here), backfills any earlier non-mutating
+  stage as a routine handoff (marked `backfilled` in the trail, distinct from a stage its own
+  skill actually completed), and stops on the node this skill must act on — or on any gate in the
+  way, `clarification`-kind included, since only a human or that gate's own owning skill may
+  decide it.
+  ```bash
+  "$DOFLOW" orchestrate --action catch-up --task-id "<slug>" --task-class "<class>" --stage "<stage id>" --note "entering implementation" --json
+  ```
+- Branch on the response's `caughtUpTo` / `reason`, not on the exit code:
+- **`reason` is `awaiting-gate:<gate id>`** — **first check `<gate id>` against step 2's
+  `<expected gate id>`.** They match in the ordinary case (`gate-a`, standing immediately before
+  this stage) — present `awaitingGate.prompt` to the user through `AskUserQuestion` as a plain
+  go/no-go, the same way step 1's prerequisite gate stops and asks rather than assuming. On yes:
+  ```bash
+  "$DOFLOW" orchestrate --action decide-gate --task-id "<slug>" --gate "<awaitingGate.gateId>" --decision approve --note "<the user's own answer, one line>" --json
+  ```
+  Then re-run the same `catch-up` call to land on this stage. If that re-run itself stops on
+  *another* `awaiting-gate:`, re-apply this same check from the top — do not assume one approval
+  clears the path; walk it exactly as far as it goes. On no: **stop the whole run here.** The gate
+  is terminal in the same sense step 1's prerequisite gate is — report that the gate was not
+  approved and dispatch nothing.
+  **They do not match** — this is a gate belonging to an earlier stage, not this one. `gate-0`,
+  left open by an aborted `/do-brainstorm` session, is exactly this case: it now surfaces here
+  (catch-up stops on every gate, `clarification`-kind included) instead of being silently
+  resolved on the way past. Report the gate id plainly and stop, the same way `do-design`,
+  `do-plan`, `do-test` and `do-brainstorm` already handle a gate that isn't theirs. Never approve
+  a gate this stage did not expect regardless of what the user answers — a "yes" given in an
+  implementation context is not an answer to a different stage's clarification prompt, and
+  `reject`'s "terminate the run outright" semantics are the wrong shape for a gate this stage has
+  no standing to decide either way.
+- **`caughtUpTo` is this stage id** (`reason: reached-candidate`) — the run is positioned exactly
+  here and there is no gate to ask. That covers three cases at once and needs no special-casing
+  between them: `/do-flow` already recorded the user's answer to that gate while driving the
+  chain, this skill just recorded it in the branch above, or the accepted class declares no gate
+  at all — `feature` is the only shipped class that declares any. Never ask a gate the run does
+  not report as open; that is exactly the double-prompt this branch exists to prevent. Carry this
+  `caughtUpTo` value to step 10; it is the stage id that call completes.
+- **`reason` is `blocked-on-mutating-stage:<id>`** — a *different* source-mutating stage sits
+  ahead of this one and its own skill has not executed it. Name `<id>`, report the block plainly,
+  and dispatch nothing.
+- **`reason` starts with `already-completed:`** — this stage was already recorded on an earlier
+  run of this skill (a `--scope resume` after an interrupted run, say). Use `annotate` instead of
+  `complete-stage`:
+  ```bash
+  "$DOFLOW" orchestrate --action annotate --task-id "<slug>" --node "<stage id>" --note "<what changed on this re-run>" --json
+  ```
+- **`reason` is `run-completed` or `run-rejected`** — the run is finished and takes no further
+  stage. Report it and stop.
+- Positioning the run is advisory to the trail, not to the work: if the `catch-up` call itself
+  fails for a reason outside this flow's control (an unwritable local state directory, say),
+  report the failure plainly and continue — the hard prerequisite gate step 1 already enforced is
+  what governs whether this run may proceed. A user's explicit "no" above is not that case; it
+  stops the run.