@kontourai/flow-agents 1.3.0 → 2.0.0

package/kits/builder/kit.json

@@ -17,20 +17,90 @@
     }
   ],
   "skills": [
-    { "id": "builder.builder-shape", "path": "skills/builder-shape/SKILL.md", "description": "Invoke Builder Kit shape from a raw idea or the current conversation context." },
-    { "id": "builder.deliver", "path": "skills/deliver/SKILL.md", "description": "Delivery workflow — selected work to delivered code." },
-    { "id": "builder.design-probe", "path": "skills/design-probe/SKILL.md", "description": "One-question-at-a-time design probing interview." },
-    { "id": "builder.evidence-gate", "path": "skills/evidence-gate/SKILL.md", "description": "Evaluate whether completed work is trustworthy enough for human review, merge, or release." },
-    { "id": "builder.execute-plan", "path": "skills/execute-plan/SKILL.md", "description": "Parallel execution primitive — plan artifact path to implemented code." },
-    { "id": "builder.fix-bug", "path": "skills/fix-bug/SKILL.md", "description": "Bug fix orchestrator — diagnose, plan, execute, review, verify, loop." },
-    { "id": "builder.idea-to-backlog", "path": "skills/idea-to-backlog/SKILL.md", "description": "Turn raw ideas into shaped, prioritized, executable GitHub issue backlog." },
-    { "id": "builder.learning-review", "path": "skills/learning-review/SKILL.md", "description": "Capture post-merge learnings and feed them back into backlog, skills, tests, or knowledge." },
-    { "id": "builder.pickup-probe", "path": "skills/pickup-probe/SKILL.md", "description": "Builder Kit work-item/docs/provider-grounded Probe specialization before plan-work." },
-    { "id": "builder.plan-work", "path": "skills/plan-work/SKILL.md", "description": "Code planning primitive — goal + directory to structured execution plan." },
-    { "id": "builder.pull-work", "path": "skills/pull-work/SKILL.md", "description": "Select ready GitHub issues from the executable backlog for implementation." },
-    { "id": "builder.release-readiness", "path": "skills/release-readiness/SKILL.md", "description": "Decide whether evidence-backed work is ready to merge, release, deploy, or hold." },
-    { "id": "builder.review-work", "path": "skills/review-work/SKILL.md", "description": "Review primitive — code, security, dependency, architecture critique before verification." },
-    { "id": "builder.tdd-workflow", "path": "skills/tdd-workflow/SKILL.md", "description": "Test-driven development — RED, GREEN, REFACTOR with git checkpoints." },
-    { "id": "builder.verify-work", "path": "skills/verify-work/SKILL.md", "description": "Verification primitive — session file path to structured evidence verdict." }
+    {
+      "id": "builder.builder-shape",
+      "path": "skills/builder-shape/SKILL.md",
+      "description": "Invoke Builder Kit shape from a raw idea or the current conversation context."
+    },
+    {
+      "id": "builder.continue-work",
+      "path": "skills/continue-work/SKILL.md",
+      "description": "Advance a multi-slice work item to its next increment via a fresh-context handoff, routing the next slice through pull-work + pickup-probe."
+    },
+    {
+      "id": "builder.deliver",
+      "path": "skills/deliver/SKILL.md",
+      "description": "Delivery workflow — selected work to delivered code."
+    },
+    {
+      "id": "builder.design-probe",
+      "path": "skills/design-probe/SKILL.md",
+      "description": "One-question-at-a-time design probing interview."
+    },
+    {
+      "id": "builder.evidence-gate",
+      "path": "skills/evidence-gate/SKILL.md",
+      "description": "Evaluate whether completed work is trustworthy enough for human review, merge, or release."
+    },
+    {
+      "id": "builder.gate-review",
+      "path": "skills/gate-review/SKILL.md",
+      "description": "Enumerate gate fires and suspected misses from the session trust.bundle; classify as correct/false_block/missed_block; route findings to learning-review; propose advisory fixes."
+    },
+    {
+      "id": "builder.execute-plan",
+      "path": "skills/execute-plan/SKILL.md",
+      "description": "Parallel execution primitive — plan artifact path to implemented code."
+    },
+    {
+      "id": "builder.fix-bug",
+      "path": "skills/fix-bug/SKILL.md",
+      "description": "Bug fix orchestrator — diagnose, plan, execute, review, verify, loop."
+    },
+    {
+      "id": "builder.idea-to-backlog",
+      "path": "skills/idea-to-backlog/SKILL.md",
+      "description": "Turn raw ideas into shaped, prioritized, executable GitHub issue backlog."
+    },
+    {
+      "id": "builder.learning-review",
+      "path": "skills/learning-review/SKILL.md",
+      "description": "Capture post-merge learnings and feed them back into backlog, skills, tests, or knowledge."
+    },
+    {
+      "id": "builder.pickup-probe",
+      "path": "skills/pickup-probe/SKILL.md",
+      "description": "Builder Kit work-item/docs/provider-grounded Probe specialization before plan-work."
+    },
+    {
+      "id": "builder.plan-work",
+      "path": "skills/plan-work/SKILL.md",
+      "description": "Code planning primitive — goal + directory to structured execution plan."
+    },
+    {
+      "id": "builder.pull-work",
+      "path": "skills/pull-work/SKILL.md",
+      "description": "Select ready GitHub issues from the executable backlog for implementation."
+    },
+    {
+      "id": "builder.release-readiness",
+      "path": "skills/release-readiness/SKILL.md",
+      "description": "Decide whether evidence-backed work is ready to merge, release, deploy, or hold."
+    },
+    {
+      "id": "builder.review-work",
+      "path": "skills/review-work/SKILL.md",
+      "description": "Review primitive — code, security, dependency, architecture critique before verification."
+    },
+    {
+      "id": "builder.tdd-workflow",
+      "path": "skills/tdd-workflow/SKILL.md",
+      "description": "Test-driven development — RED, GREEN, REFACTOR with git checkpoints."
+    },
+    {
+      "id": "builder.verify-work",
+      "path": "skills/verify-work/SKILL.md",
+      "description": "Verification primitive — session file path to structured evidence verdict."
+    }
   ]
 }

package/kits/builder/skills/continue-work/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: "continue-work"
+description: "Advance a multi-slice work item to its next increment via a fresh-context handoff. Use when one or more slices of a multi-slice issue have landed and the next undone slice should be built. Routes the next slice through pull-work + pickup-probe (never around the gate), restores prior slices from the durable record as precedent, and hands off in a fresh context per ADR 0013."
+---
+
+# Continue Work
+
+Advance a multi-slice work item to its **next increment**, in a fresh context, with the already-landed slices as precedent.
+
+This skill is **orchestration, not new machinery.** It composes existing pieces and must never reimplement them:
+
+- `pull-work` already owns *selection* plus the `pickup-probe` gate, and already handles "continue / keep going / pick up the next" intents. continue-work routes the chosen slice **through** `pull-work` / `pickup-probe`, never around it.
+- The **resume surface** (#153) owns restoring an item's durable record (`state.json` lifecycle + `handoff.json` next-steps/blockers + plan artifact + `trust.bundle` trust summary) into context. continue-work consumes that surface; it does not re-derive the record.
+- **ADR 0013** establishes `pull-work` as the clean *context-reset* seam: a fresh window per increment, selective compaction, status-gated reuse. continue-work spawns the next increment as a fresh-context workflow seamed at `pull-work`.
+- The **fresh-handoff** pattern (spawn a new context for the next increment) is the delivery mechanism.
+
+continue-work ties these together for **one job**: take a multi-slice work item that has at least one slice landed and more remaining, determine the next undone slice, route it through the gate, and hand it off fresh with the prior slices as the model.
+
+## When To Use / When Not
+
+**Use** when:
+
+- A multi-slice issue has **at least one slice landed and more remaining** (for example #106), and the request is "continue", "pick up the next slice", "keep going on this issue", or "do the next increment".
+
+**Do not use** when:
+
+- The request is **brand-new work** with nothing landed yet — that is selection from the backlog. Route to `pull-work`.
+- The request is to **resume the *same* interrupted slice** after a restart (same in-flight slice, mid-execution, picking up new hooks/logic) — that is the resume surface (#153), which reconstructs `state.json` + `handoff.json` + plan + `trust.bundle` for the *same* increment. continue-work advances to the *next* increment; it does not re-enter an unfinished one.
+
+If the boundary is ambiguous (is this the next slice or the same one?), stop and ask one question before routing. Do not silently assume.
+
+## Boundary (ADR 0014)
+
+Home is the **Builder Kit** — developer orchestration over issues, slices, and PRs — alongside `pull-work` and `deliver`. The underlying *fresh-handoff primitive* is generic. If a non-developer kit later needs continuation, **graduate the primitive** per ADR 0014; do not fork continue-work into each kit.
+
+## Inputs
+
+- The multi-slice work item (an issue ref) with at least one slice landed and more remaining.
+- Repository or working directory and the owning kit/kit-dir.
+- The durable record for the item when one exists, restored via the resume surface (#153): `state.json`, `handoff.json` next-steps/blockers, the plan artifact, and a one-line `trust.bundle` summary of what is already verified.
+- The merged PRs and commits that reference the issue (the landed slices), available as `git show <sha>` precedent.
+- `AGENTS.md` "Operating discipline (working agreements)" — the operating agreements that travel with every increment.
+
+## Workflow
+
+### 1. Restore the durable record (resume surface, #153)
+
+Before doing anything else, restore the item's durable record into context through the resume surface (#153) rather than re-deriving it from chat memory: `state.json` lifecycle, `handoff.json` next-steps and blockers, the plan artifact, and a one-line `trust.bundle` summary of what is already verified. This is *restore for context*, not *resume the slice* — continue-work is advancing to the next increment, so already-verified prior slices stay verified and are not re-proven.
+
+If no durable record exists for the item, record that gap and rely on the issue body plus merged PRs/commits as the authoritative history.
+
+### 2. Determine the next undone slice
+
+From the issue body plus the merged PRs and commits referencing the issue, determine which slices have **landed** and which is the **next undone slice**.
+
+- Read the issue body for the slice list / acceptance breakdown.
+- List merged PRs and commits referencing the issue (`gh pr list --search <issue>`, `git log --grep`) to see which slices are done.
+- The next undone slice is the thinnest remaining meaningful increment. If the remaining work is ambiguous or no longer matches the issue, route back to `idea-to-backlog` instead of inventing scope.
+
+### 3. Route the slice THROUGH pull-work + pickup-probe (the gate, never around it)
+
+Hand the chosen next slice to `pull-work`, then `pickup-probe`. **Never bypass this gate.** A continuation instruction ("continue", "pick up the next") may justify inspecting the queue, but it must not skip per-item pickup Probe evidence — see pull-work's Pickup Gate ("A stale broad continuation instruction … may allow queue inspection but must not bypass per-item pickup Probe evidence") and its post-merge rule ("automatic continuation … cannot enter planning or execution for the next work item until a fresh pickup Probe record exists for that newly selected item").
+
+- `pull-work` enforces board selection, WIP/shepherding, dependency, grouping, freshness (planned-base drift), and worktree logic for the selected slice, and writes the pull-work artifact.
+- `pickup-probe` then challenges the slice against the repository — scope, acceptance quality, provider state, drift, conflict risks — and records the pickup Probe outcome, planning readiness, decisions, unresolved questions, and accepted gaps.
+- continue-work does **not** reimplement either step's logic. It supplies them the next slice and the precedent (prior slices) and consumes their artifacts. The evidence that the gate ran lives in the pull-work / pickup-probe artifact referenced by the handoff (`probe_status`, `probe_artifact_ref`).
+
+Do not enter planning or execution until a fresh pickup Probe record exists for this slice.
+
+### 4. Assemble the minimal handoff
+
+Once the slice passes the gate, assemble the **minimal handoff** — the smallest durable context a fresh agent needs:
+
+- the **slice's spec**: `gh issue view <issue>` (the issue is the spec);
+- the **operating agreements**: `AGENTS.md` "Operating discipline";
+- the **precedent**: the prior slices' merged PRs as the model (`git show` them);
+- the **gate evidence**: the pull-work / pickup-probe artifact ref proving the slice passed the gate.
+
+The minimal template it encodes:
+
+```
+Implement [slice N of #ISSUE] in <repo> — the <kit>.
+Read first: AGENTS.md 'Operating discipline'; gh issue view ISSUE (your slice's spec);
+the prior slices as your model (PRs … — git show them).
+Then: scope → minimal impl reusing existing ops (consume-never-fork) → tests stay green +
+cover new code → PR referencing #ISSUE, <kit-dir> only. Don't merge; get CI green and report.
+```
+
+### 5. Execute in a fresh context (ADR 0013)
+
+Hand the minimal template off into a **fresh context** — either spawn a sub-agent for the next increment, or hand the prompt to the operator for a fresh session. Per ADR 0013, the new increment rebuilds its context from durable artifacts (the issue, AGENTS.md, prior PRs, the gate artifact), not from this conversation's history. The fresh-handoff is the delivery seam: a sharp window for the new slice, continuity carried by the durable system.
+
+The fresh-context agent runs the standard Builder Kit build for its slice (`plan-work` → `execute-plan` → `review-work` → `verify-work`), which it may reach via `deliver`. continue-work does not re-run those primitives in-line; it sets up the handoff and lets the fresh context execute.
+
+### 6. Verify and report — do not merge
+
+After the slice is built:
+
+- Confirm the **boundary held** (only `<kit-dir>` changed) and the **suites are green** (the slice's tests cover the new code and nothing regressed).
+- Report: which slice advanced, the gate evidence (pull-work / pickup-probe artifact), the precedent PRs used, the verification result, and the PR.
+- **Do not merge without authorization.** Get CI green and report back.
+
+## Composition Gate
+
+continue-work has correctly composed the pieces only when:
+
+- the durable record was restored via the resume surface (#153), or a missing-record gap is recorded;
+- the next undone slice was derived from the issue body plus merged PRs/commits, not invented;
+- the slice was routed **through** `pull-work` + `pickup-probe`, with a fresh pickup Probe record (`probe_status`, `probe_artifact_ref`) referenced by the handoff — the gate was not bypassed;
+- the minimal handoff carries the issue spec, `AGENTS.md` operating agreements, and the precedent PRs;
+- the next increment runs in a **fresh context** per ADR 0013;
+- the boundary held, suites are green, and the change is reported without merging.
+
+If any item fails, stop and surface the gap rather than proceeding.
+
+Refs: #106 (proving ground), #153 (resume surface), #168 / ADR 0013 (context lifecycle), #164 (operating agreements), ADR 0014 (core vs domain-kit boundary).

package/kits/builder/skills/deliver/SKILL.md

@@ -145,9 +145,12 @@ Create the session file with `status: planning`, `iteration: 0`. Use the sidecar
 npm run workflow:sidecar -- ensure-session \
   --source-request "<original request>" \
   --summary "<current delivery goal>" \
-  --criterion "<acceptance criterion>"
+  --criterion "<acceptance criterion>" \
+  --flow-id builder.build
 ```
 
+`--flow-id builder.build` activates the FlowDefinition-driven path for this session. Producers fire, gates enforce on builder.* claims, and `advance-state` sets `active_step_id` automatically via the `builder.build` phase_map. Keep this flag on all `deliver`-initiated sessions; do not remove it for direct ad-hoc requests that are not builder-flow pickup.
+
 ### 2. Plan (plan-work)
 
 Invoke plan-work with the goal, directory, session file path, and any pull-work / pickup-probe artifact refs. The plan must include `## Definition Of Done`. Present the plan to the user when a user decision is actually needed; otherwise record the plan artifact and continue automatically to execution.
@@ -212,10 +215,36 @@ Record the final local state with `advance-state`. Use `status: verified` only w
 After review, verification, evidence, and Goal Fit are clean for the same diff:
 
 1. Confirm the working tree contains only verified scope.
-2. Commit the verified diff.
-3. Push the branch.
-4. Open or update the provider change record with issue links, closing refs, evidence links, and verification summary, or record an explicit no-provider-change reason.
-5. Wait for provider checks/CI or record missing checks as `NOT_VERIFIED`.
+2. Publish the session trust bundle to `delivery/` so the CI trust-reconcile job can verify what the agent claimed. `record-release` (via the sidecar writer) does this automatically (best-effort). To publish or re-publish explicitly:
+
+   ```bash
+   npm run workflow:sidecar -- publish-delivery .flow-agents/<slug>
+   ```
+
+   Then force-stage the trust artifacts for the delivery commit. They are gitignored
+   by default (they are runtime artifacts written on every local delivery) — `-f`
+   commits them deliberately into THIS delivery PR so CI's trust-reconcile job can
+   reconcile the session's claims against fresh CI results:
+
+   ```bash
+   git add -f delivery/trust.bundle delivery/trust.checkpoint.json
+   ```
+
+3. Commit the verified diff, including the force-added `delivery/trust.bundle` and `delivery/trust.checkpoint.json`.
+4. Push the branch.
+5. Open or update the provider change record with issue links, closing refs, evidence links, and verification summary, or record an explicit no-provider-change reason.
+6. Wait for provider checks/CI or record missing checks as `NOT_VERIFIED`.
+7. Record the gate claim for the Builder Kit `pr-open` step immediately after the PR is opened or updated:
+
+```bash
+npm run workflow:sidecar -- record-gate-claim .flow-agents/<slug> \
+  --expectation pull-request-opened \
+  --status pass \
+  --summary "PR opened: <pr-url>. Linked to <work-item-ref>, implementation summary and verification evidence attached." \
+  --evidence-ref-json '{"kind":"provider","url":"<pr-url>"}'
+```
+
+Use `--status fail` when the PR cannot be opened or when no provider change record is created and the reason is not an accepted no-provider-change path. Use `--status not_verified` when provider access is unavailable and the PR creation cannot be confirmed.
 
 Do not invoke `release-readiness` before this gate unless the user explicitly accepts a no-provider-change/no-push path and the reason is recorded in the session artifact. For GitHub, the first `ChangeProvider` adapter example is a PR with PR checks.
 
@@ -229,7 +258,8 @@ After CI passes and the work is merged or otherwise accepted:
 4. Promote the relevant plan, decision, evidence, and usage notes into long-lived docs such as `docs/`, `README.md`, or a project decision record.
 5. Link the long-lived doc back to the provider record, archived plan artifact, or accepted evidence when useful so future readers can see why and how the feature was built.
 6. Confirm `.flow-agents/` runtime artifacts remain untracked before merge to `main`.
-7. Hand off to `learning-review` when the delivery exposed workflow, testing, documentation, or product follow-up.
+7. **Clean up the workspace once the merge is confirmed.** First verify the merge actually happened from the provider's own record (a merge commit / `mergedAt`) — not a green check or a watcher's exit code. Then honor the `worktree_lifecycle` recorded by `pull-work` (`retain_until: pr_merged`): remove the isolated worktree (`git worktree remove <path>`) and delete the now-merged branch locally and on the remote. Never delete a branch or worktree before the merge is confirmed — a closed-but-unmerged PR or a prematurely deleted branch loses work. The task is not done while it leaves a stale worktree or merged branch behind.
+8. Hand off to `learning-review` when the delivery exposed workflow, testing, documentation, or product follow-up.
 
 ### 11. Deliver
 

package/kits/builder/skills/design-probe/SKILL.md

@@ -98,6 +98,34 @@ Before stopping, summarize:
 - Planning readiness.
 - Recommended next action.
 
+## Gate Claims: Builder Kit Design-Probe Step
+
+When `design-probe` runs at the Builder Kit `design-probe` flow step and the probe reaches a stop condition with shared understanding or accepted gaps, record the gate claims before handing off to `plan-work`.
+
+This applies whether the probe is run directly (generic) or as part of a Builder Kit productized flow. The `pickup-probe` specialization owns the same two claims when it runs instead.
+
+**Claim 1 — Pickup readiness** (probe passed, goal fit and scope confirmed):
+
+```bash
+npm run workflow:sidecar -- record-gate-claim .flow-agents/<slug> \
+  --expectation pickup-probe-readiness \
+  --status pass \
+  --summary "Design probe passed: goal fit confirmed, scope aligned, planning readiness verified." \
+  --evidence-ref-json '{"kind":"artifact","file":".flow-agents/<slug>/<slug>--<artifact>.md","summary":"Design-probe artifact with decisions, accepted gaps, and planning readiness."}'
+```
+
+**Claim 2 — Probe decisions captured**:
+
+```bash
+npm run workflow:sidecar -- record-gate-claim .flow-agents/<slug> \
+  --expectation probe-decisions-or-accepted-gaps \
+  --status pass \
+  --summary "Probe decisions recorded: decisions made, unresolved questions explicit, planning readiness confirmed." \
+  --evidence-ref-json '{"kind":"artifact","file":".flow-agents/<slug>/<slug>--<artifact>.md","summary":"Design-probe artifact with decisions and accepted gaps."}'
+```
+
+Record both claims when shared understanding exists and the next action is `plan-work` or equivalent. Use `--status fail` when stopping due to an unresolved blocker. Skip these claims entirely when `design-probe` is used outside a Builder Kit flow (no active `builder.build` flow step in `current.json`).
+
 ## Boundaries
 
 - Do not ask multiple questions in one turn.

package/kits/builder/skills/execute-plan/SKILL.md

@@ -45,7 +45,7 @@ This skill owns orchestration between waves. The contracts own artifact continui
    - if traceability is missing, update the session file and/or send the plan back for refinement before delegation
 5. Set session file `status: executing` and use `npm run workflow:sidecar -- advance-state <artifact-dir> --status in_progress --phase execution --summary ... --next-action ...` when the repository provides it
 6. **Frontend design check:** If any tasks involve UI, CSS, layouts, components, or visual design, read the `frontend-design` skill and include its aesthetics guidelines in the tool-worker prompts for those tasks
-7. Fan out each wave to tool-worker subagents (up to 4 parallel):
+7. **Before fan-out, run the [Pre-Fan-Out Freshness Re-Check](#pre-fan-out-freshness-re-check) and re-ground if the plan is stale.** Then fan out each wave to tool-worker subagents (up to 4 parallel):
    - Delegate to the exact `tool-worker` role for every implementation worker. Do not spawn unnamed/default implementation agents.
    ```
    Each tool-worker gets:
@@ -69,6 +69,14 @@ This skill owns orchestration between waves. The contracts own artifact continui
 
 The orchestrator owns root `state.json` updates. Workers should receive the workflow artifact root explicitly and append agent events under that root instead of inferring the slug or rewriting shared sidecars.
 
+## Pre-Fan-Out Freshness Re-Check
+
+A plan can go stale between planning and execution — upstream may have advanced, or the plan may simply be old. `plan-work` and `pull-work` stamp and check `planned_base_sha` / `revision_freshness` at planning and pickup; this is the same check at the **execution boundary**, where stale plans actually cause wasted work (parallel workers building what already landed upstream). Run it before any worker starts.
+
+- **Always — cheap SHA tripwire.** Re-fetch the target ref and compare the current target SHA to the plan's `planned_base_sha` (per `context/contracts/planning-contract.md`). If the base moved **and** the newer commits/files intersect `planning_scope_refs`, the plan is stale: do not fan out. Route back to `plan-work` (or `pickup-probe` for provider-backed work) to re-ground against the current base — the same `revision_freshness: stale` rule plan-work and pull-work already enforce. Missing `planned_base_sha` is not fresh; record a `NOT_VERIFIED` gap and confirm the base before fan-out.
+- **On plan age — deeper re-survey.** If the plan is older than the staleness window (default ~1h; shorter for fast-moving scope), do the costlier relook the SHA diff cannot: re-survey what now exists in the target area (recently merged PRs, new modules, sibling work) for anything that already does what this plan proposes. If it already shipped upstream, stop and route back to `plan-work` rather than building a duplicate. The SHA tripwire is the precise signal; plan age is the backstop for landscape drift the diff can't see.
+- Record the re-check result (`fresh`, or re-grounded with the compared SHAs and route-back) in the session file before continuing. Worktree/isolation needs stay owned by `pull-work`'s file-overlap decision — don't re-derive them here.
+
 ## Session File Updates
 
 Between each wave, append to the session file:

package/kits/builder/skills/gate-review/SKILL.md

@@ -0,0 +1,234 @@
+---
+name: "gate-review"
+description: "Enumerate gate fires and suspected misses from the session's Hachure trust.bundle, classify each as correct/false_block/missed_block using Surface's resolveInquiry to produce canonical InquiryRecords, route findings to learning-review, and propose advisory-only gate/flow fixes. Use mid-session after a goal-fit block or at closeout. Requires ADR 0010 Phase 1 (trust.bundle dual-write) to be present."
+---
+
+# Gate Review
+
+Classify gate fires and suspected misses from the session's `trust.bundle` by calling Surface's `resolveInquiry` to produce canonical `InquiryRecord` outputs. Every finding is advisory — proposes a fix, never applies one.
+
+## Contract
+
+- **Advisory-only**: proposes fixes, never applies them. No finding may instruct auto-application of any fix.
+- Never writes to `scripts/hooks/` or any flow file.
+- Reads the local `trust.bundle` file only. Does NOT fall back to `command-log.jsonl`, `.goal-fit-block-streak.json`, or `evidence.json` direct reads as primary inputs.
+- If no `trust.bundle` is present at `.flow-agents/<slug>/trust.bundle`, reports `NOT_VERIFIED` and stops. Does not silently degrade to bespoke sidecar reads.
+- Routes all telemetry, `learning.json` writes, and correction routing through `learning-review`. Gate-review never calls `record-learning` directly.
+- Reads `state.json` for lifecycle context only (phase, status). `state.json` is NOT a trust claim per ADR 0010.
+- Reads `context/gate-awareness.md` for vocabulary alignment when available.
+- Classification vocabulary (`correct`, `false_block`, `missed_block`) aligns with `context/gate-awareness.md` sections "Judge Gate Correctness" and "Missed-Block Diagnostic".
+- Uses `@kontourai/surface`'s `resolveInquiry(bundle, inquiry)` to produce canonical `InquiryRecord` outputs per ADR 0003.
+- If `@kontourai/surface` is unavailable, logs a warning and skips output. No bespoke fork fallback.
+- **Builder Kit build flow**: gate-review operates on sessions created by `deliver` or `plan-work` with `--flow-id builder.build`. The session's trust.bundle contains both declared builder.* claims (e.g. `builder.verify.tests`) and legacy workflow.* shadow claims. Gate-review classifies all claims present in the bundle regardless of claimType prefix.
+
+## Inputs
+
+- `trust.bundle` at `.flow-agents/<slug>/trust.bundle` (produced by ADR 0010 Phase 1 dual-write in `workflow-sidecar`).
+
+  **Dependency**: this file is NOT present at `origin/main @ a9b8fd6`; it requires ADR 0010 Phase 1 to be built and merged (owned by `arch/goal-fit-gate-trust-bundle`). Do not begin execution until Phase 1 has landed or a fixture is agreed with that owner.
+
+  The bundle shape produced by `workflow-sidecar` (schemaVersion 3, source `"flow-agents/workflow-sidecar;statusFunctionVersion=1"`):
+  ```json
+  {
+    "schemaVersion": 3,
+    "source": "flow-agents/workflow-sidecar;statusFunctionVersion=1",
+    "claims": [
+      {
+        "id": "<slug>-<checkId>.<surface>.<fieldOrBehavior>",
+        "subjectType": "workflow-check",
+        "subjectId": "<slug>/<checkId>",
+        "surface": "flow-agents.workflow",
+        "claimType": "workflow.check.test",
+        "fieldOrBehavior": "<check summary>",
+        "value": "pass|fail|skip",
+        "createdAt": "<ISO-8601>",
+        "updatedAt": "<ISO-8601>",
+        "status": "verified|disputed|assumed|proposed|rejected|stale|unknown"
+      }
+    ],
+    "evidence": [...],
+    "events": [...],
+    "policies": []
+  }
+  ```
+
+  The claim `status` field is the canonically derived status (computed by `@kontourai/surface.deriveClaimStatus`). Status values and their meaning for gate-review:
+
+  | `status` | Meaning |
+  | --- | --- |
+  | `verified` | Claim confirmed by matching evidence; a pass. |
+  | `disputed` | Claim contradicted by evidence; a genuine failure. |
+  | `assumed` | Claim accepted without direct evidence (e.g. `accepted_gap` criterion, `skip` check). |
+  | `proposed` | Claim written but not yet evaluated. |
+  | `rejected` | Claim explicitly rejected. |
+  | `stale` | Claim data is outdated; gate had stale input. |
+  | `unknown` | No event found; claim was never evaluated. |
+
+- `state.json` at `.flow-agents/<slug>/state.json` (lifecycle context; not a trust input).
+- Optional: seeded fixture `trust.bundle` path for testing before Phase 1 produces real bundles.
+
+## Artifact Contract
+
+Write the following artifacts under `.flow-agents/<slug>/`:
+
+### `<slug>--gate-review.md`
+
+Human-readable summary. Sections:
+
+- `## Session` — slug, state.json phase/status at review time, trust.bundle schemaVersion
+- `## Gate Fires` — one entry per classified InquiryRecord
+- `## Suspected Misses` — missed_block InquiryRecords; expected criteria absent from the bundle
+- `## Advisory Fixes` — proposed (NOT applied) fixes per InquiryRecord (from `answer.value.advisoryFix`)
+- `## NOT_VERIFIED Gaps` — any classification that could not be completed (e.g. trust.bundle absent, Surface unavailable)
+- `## Routed To` — `learning-review` invocation record
+
+### `gate-review.inquiries.json`
+
+Machine-readable array of canonical `InquiryRecord` objects validated against the hachure schema at `node_modules/hachure/schemas/inquiry-record.schema.json` (canonical `$id`: `https://kontourai.io/schemas/surface/inquiry-record.schema.json`).
+
+Required fields per schema: `id`, `inquiry`, `outcome`, `resolutionPath`, `inputSnapshot`, `statusFunctionVersion`, `resolvedAt`.
+
+The `outcome` field is the canonical Surface value: `"matched"` (claim found and resolved), `"derived"` (rule-based resolution), or `"unsupported"` (no matching claim — absent criterion).
+
+The `answer` field carries gate-review's value-add:
+- `answer.status` — canonical `TrustStatus` of the resolved claim (`"unknown"` when absent).
+- `answer.value` — gate-review advisory object:
+  ```json
+  {
+    "calibration": "correct | false_block | missed_block",
+    "advisoryFix": "<non-empty advisory string>",
+    "gateFired": true,
+    "sessionSlug": "<slug>"
+  }
+  ```
+
+The `calibration` field in `answer.value` is derived from `(outcome, answer.status, blockSignal.blocked)`:
+- `"matched"` + `"disputed"|"rejected"` + `blocked=true` → `"correct"`
+- `"matched"` + `"verified"|"assumed"` + `blocked=true` → `"false_block"`
+- `"matched"` + `"stale"|"unknown"|"proposed"` + `blocked=false` → `"missed_block"`
+- `"unsupported"` (absent claim) → `"missed_block"`
+
+The `advisoryFix` in `answer.value` must be non-empty for every record. No record may have `auto_applied: true` or instruct automatic changes.
+
+Example record:
+```json
+{
+  "id": "my-session-gr-1",
+  "inquiry": {
+    "id": "my-session-gr-1",
+    "question": "Was gate action on claim my-session/unit-tests... (status: verified) justified?",
+    "askedBy": "gate-review",
+    "askedAt": "2026-06-24T00:00:00Z",
+    "target": { "subjectType": "workflow-check", "subjectId": "my-session/unit-tests", "fieldOrBehavior": "unit tests pass" }
+  },
+  "outcome": "matched",
+  "resolutionPath": { "claimIds": ["my-session/unit-tests.flow-agents.workflow.unit tests pass"] },
+  "answer": {
+    "status": "verified",
+    "value": {
+      "calibration": "false_block",
+      "advisoryFix": "Investigate why the gate blocked when claim ... has status verified ...",
+      "gateFired": true,
+      "sessionSlug": "my-session"
+    }
+  },
+  "inputSnapshot": [{ "claimId": "my-session/unit-tests.flow-agents.workflow.unit tests pass", "status": "verified" }],
+  "statusFunctionVersion": "1",
+  "resolvedAt": "2026-06-24T00:00:00Z"
+}
+```
+
+Invariants:
+- Every record must have a non-empty `answer.value.advisoryFix`.
+- No record may have `auto_applied: true`.
+- `answer.value.calibration` must be one of `"correct"`, `"false_block"`, or `"missed_block"`.
+
+After writing `gate-review.inquiries.json`, invoke `learning-review` passing the inquiries artifact path as an additional reviewer-notes input. Learning-review writes `learning.json` via `npm run workflow:sidecar -- record-learning`. Do NOT call `record-learning` from gate-review directly.
+
+## Bundle-Claim to InquiryRecord Mapping
+
+| Bundle claim condition | outcome | calibration | Rationale |
+| --- | --- | --- | --- |
+| Gate blocked AND claim has `status: "disputed"` or `"rejected"` | `matched` | `correct` | Gate saw a genuine failure; block was warranted. |
+| Gate blocked AND claim has `status: "verified"` or `"assumed"` | `matched` | `false_block` | Gate blocked despite passing claims — acted on stale or incorrect data. |
+| An expected claim is absent from the bundle entirely | `unsupported` | `missed_block` | Gate had no claim to evaluate. |
+| A claim has `status: "stale"` and the gate did NOT block | `matched` | `missed_block` | Stale claim was present but gate did not fire on it. |
+| A claim has `status: "unknown"` with no evidence trace | `matched` | `missed_block` | Claim was never evaluated; gate had no resolved evidence. |
+
+Cross-reference with `state.json` phase at the time of the block to confirm the block was in an active workflow phase (not planning or archived).
+
+## Workflow
+
+### Step 1 — Locate trust.bundle
+
+Resolve `.flow-agents/<slug>/trust.bundle`. The slug is the most recent active session (by `current.json` or `state.json` newest-mtime). If absent, surface the blocker:
+
+```
+[gate-review] trust.bundle absent — NOT_VERIFIED. Build ADR 0010 Phase 1 first.
+```
+
+Stop and surface the blocker to the user.
+
+### Step 2 — Load Surface and resolve inquiries
+
+Run `npm run workflow:sidecar -- gate-review <dir>`.
+
+The sidecar writer:
+1. Loads `@kontourai/surface` (ESM, fail-open dynamic import).
+2. For each claim in the bundle: builds a `SurfaceInquiry` with a canonical `target` and calls `resolveInquiry(bundle, inquiry)`.
+3. For each absent expected criterion (from `acceptance.json`): builds a `SurfaceInquiry` targeting the missing claim; `resolveInquiry` returns `"unsupported"`.
+4. Derives `calibration` from `(outcome, answer.status, blockSignal.blocked)` using `deriveGateCalibration`.
+5. Composes advisory `advisoryFix` string using `gateAdvisoryFix`.
+6. Sets `answer.value = { calibration, advisoryFix, gateFired, sessionSlug }`.
+7. Strips Surface-internal fields (`identityLinkIds`, `transitiveRuleIds`) to conform to the hachure schema.
+8. Validates each record against `inquiry-record.schema.json` (fail-open).
+9. Writes `gate-review.inquiries.json`.
+
+### Step 3 — Classify each InquiryRecord
+
+Apply the InquiryRecord calibration mapping:
+
+**`correct`** — `outcome: "matched"`, claim `status: "disputed"` or `"rejected"`, `blocked=true`:
+> Gate saw a genuine failure. Block was warranted. Advisory fix: close the gap and re-run.
+
+**`false_block`** — `outcome: "matched"`, claim `status: "verified"` or `"assumed"`, `blocked=true`:
+> Gate blocked despite passing claims. Advisory fix: investigate the block trigger; add freshness check.
+
+**`missed_block`** — `outcome: "unsupported"` (absent) OR `status: "stale"|"unknown"|"proposed"`, `blocked=false`:
+> Gate had no claim to evaluate or claim was unresolved. Advisory fix: ensure record-evidence writes the claim.
+
+### Step 4 — Write human-readable summary
+
+Write `<slug>--gate-review.md` with sections for Session, Gate Fires, Suspected Misses, Advisory Fixes, NOT_VERIFIED Gaps, and Routed To.
+
+Optionally use `buildTrustReport(bundle)` + `formatTrustReportSummary(report)` from `@kontourai/surface` for the trust-state summary section.
+
+### Step 5 — Invoke learning-review
+
+Pass the `gate-review.inquiries.json` path as additional reviewer notes to `learning-review`. Do not call `record-learning` directly. Learning-review owns the `learning.json` write and correction routing.
+
+Example invocation note:
+```
+gate-review InquiryRecords at .flow-agents/<slug>/gate-review.inquiries.json:
+- <N> record(s): calibration counts
+- gate fired: <true/false>
+- calibration: correct=<n>, false_block=<n>, missed_block=<n>
+Use these as reviewer notes for the learning-review correction record.
+```
+
+## Gates
+
+- **Advisory gate**: every InquiryRecord must have a non-empty `answer.value.advisoryFix`. Gate-review must not complete without one per record.
+- **No-auto-apply gate**: no record's advisory fix may instruct auto-application of any fix. Any proposed fix that starts with "Apply" or "Change" must be rephrased as "Propose" or "Investigate".
+- **Phase-1 dependency gate**: if `trust.bundle` is absent, surface the blocker to the user rather than degrading silently to bespoke sidecars.
+- **Surface gate**: if `@kontourai/surface` is unavailable, log and skip (no fork fallback).
+
+## NOT_VERIFIED Gaps
+
+| Gap | Description | Resolution trigger |
+| --- | --- | --- |
+| NV1 | trust.bundle absent at `origin/main @ a9b8fd6` — ADR 0010 Phase 1 not yet built | Phase 1 merged to main by `arch/goal-fit-gate-trust-bundle` owner |
+| NV2 | AC1 seeded-session test fixture cannot be validated against real bundle shape | Phase 1 lands; coordinate with Phase 1 owner on exact bundle file path and claim array shape |
+| NV3 | AC2 false_block / missed_block fixture depends on exact Phase 1 bundle structure | Same as NV2 |
+
+AC1 and AC2 are `not_verified` pending ADR 0010 Phase 1. The classification logic is spec-complete against the real bundle shape (confirmed by `workflow-sidecar ensure-session` + `record-evidence` probe). Re-run seeded-session tests after Phase 1 lands.

package/kits/builder/skills/learning-review/SKILL.md

@@ -105,6 +105,36 @@ Check whether accepted delivery artifacts were promoted into long-lived document
 
 Record which follow-ups were created, which were intentionally deferred, and what trigger should revisit deferred work.
 
+## Gate Claims: Record Learning Outcomes
+
+After `learning.json` is written and the learning verdict is `LEARNED` or `FOLLOWUP_REQUIRED`, record the two gate claims for the Builder Kit `learn` step. These satisfy the `builder.learn.decisions` and `builder.learn.evidence` gate expectations.
+
+**Claim 1 — Decision evidence** (durable decisions from the build are recorded):
+
+```bash
+npm run workflow:sidecar -- record-gate-claim .flow-agents/<slug> \
+  --expectation decision-evidence \
+  --status pass \
+  --summary "Build decisions recorded: <decision-count> decisions captured, correction.<needed> recorded." \
+  --evidence-ref-json '{"kind":"artifact","file":".flow-agents/<slug>/learning.json","summary":"learning.json with decisions and correction state."}'
+```
+
+**Claim 2 — Learning evidence** (learnings from delivery are recorded for future work):
+
+```bash
+npm run workflow:sidecar -- record-gate-claim .flow-agents/<slug> \
+  --expectation learning-evidence \
+  --status pass \
+  --summary "Learning evidence captured: <outcome> outcome, facts recorded, routing complete." \
+  --evidence-ref-json '{"kind":"artifact","file":".flow-agents/<slug>/learning.json","summary":"learning.json with outcomes, facts, and routing."}'
+```
+
+Record both claims immediately after `record-learning` succeeds and artifact validation passes. Use `--status fail` when `record-learning` fails or when learning cannot be captured (verdict `BLOCKED`). Use `--status not_verified` only when the session has no active Builder Kit flow step.
+
+When the learning verdict is `FOLLOWUP_REQUIRED`, record both claims with `--status pass` and name the open routing in the summary; the follow-up route is separate from gate satisfaction.
+
+
+
 ## Gates
 
 - Learning Gate: observed outcome is recorded with evidence.