@kontourai/flow-agents 3.6.0 → 3.8.0

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

@@ -1,144 +1,87 @@
 ---
 name: "pickup-probe"
-description: "Builder Kit work-item/docs/provider-grounded Probe specialization used at the design-probe flow step before plan-work."
+description: "Provider-grounded pickup probe used at the Builder design-probe step before planning."
 ---
 
 # Pickup Probe
 
-Probe selected backlog work before Builder Kit planning starts.
+Verify that selected work is understood well enough to plan without implementing it.
 
-## Contract
-
-`pickup-probe` is the Builder Kit pickup specialization of the `design-probe` flow step. It runs after `pull-work` selects work and before `plan-work` creates an execution plan.
-
-Direct `pull-work` and direct `plan-work` remain valid standalone primitives. This skill is required when the productized Builder Kit `build` flow has selected work, when a user asks to pick up work and continue into build/delivery, or when `deliver` needs to prove selected-work readiness before planning.
-
-This skill is modeled after Matt Pocock's `grill-with-docs`: challenge the selected work against the existing domain model, sharpen terminology, cross-check docs and code, ask one recommended question at a time, update durable glossary terms inline when they crystallize, and offer ADRs only for hard-to-reverse, surprising, trade-off decisions.
-
-## Required Inputs
-
-- Selected work item or coherent work item group.
-- Pull-work artifact with board snapshot, WIP assessment, selection rationale, scope, non-goals, pickup gate, and handoff.
-- Provider state, including WorkItemProvider and BoardProvider refs, issue status, labels, milestone/project fields, blockers, PR links, and source artifact refs when available.
-- WIP and conflict scan covering active sessions, open PRs, verification/review/CI remediation queues, expected shared files, and worktree or sandbox mode.
-- Existing acceptance criteria, done criteria, stop-short risks, and known non-goals.
-- Source issue and artifact refs, including issue URLs, source planning or idea artifacts, flow definition refs, and missing-source notes.
-- Repository reality: `CONTEXT.md` when present, relevant docs, ADRs, contracts, skills, schemas, fixtures, and code paths named by the selected work.
-- Domain documentation: root `CONTEXT.md`, `CONTEXT-MAP.md` when present, and relevant `docs/adr/` records. If no durable context file exists, create one lazily only when a resolved project-specific term needs a home.
-- Planned-base drift context: `planned_base_ref`, `planned_base_sha`, current target ref/SHA, `planning_scope_refs`, and a diff summary from the planned/pulled work SHA to current HEAD when available.
-
-If a required input is missing, first try to recover it from local artifacts and provider snapshots. Ask one alignment question only when the missing input creates a real decision gap that cannot be resolved from local evidence.
-
-If `planned_base_sha` is missing, record that as a `NOT_VERIFIED` drift baseline gap and use current target plus provider history as the best available baseline. Do not invent a planned SHA.
+## Role And Binding
 
-For Builder Kit baseline freshness gaps where `planned_base_sha` is missing or inconclusive, record `resolution_hints` in the Builder Kit Probe record when that record shape is available. Use `gap_id: revision_freshness_not_verified`, `claim_id: planning.baseline.current`, and a reason code such as `missing_planned_base_sha`. The hint should name the blocked refs, the required evidence needed to resolve the gap, `resolve_at` pointing back to `pickup-probe`, and any explicit accepted fallback baseline that allows planning to continue.
+- **Role:** canonical Builder build-step producer and specialized pickup primitive.
+- **Binding:** `builder.build` step `design-probe`.
+- **Produces:** the pickup-probe section in `<slug>--pull-work.md`, plus `pickup-probe-readiness` and `probe-decisions-or-accepted-gaps` for an active matching run.
+- **Standalone no-run behavior:** produce a probe record or conversation summary only. Do not start a Builder run, record Builder evidence, or claim readiness for a non-Builder invocation.
 
-## Behavior
-
-Challenge the selected work against the repository before planning:
-
-- Fetch latest for the target ref when available, then compare the current target SHA to `planned_base_sha`. Record current target ref/SHA, planned base ref/SHA, `commits-since`, planned age, changed files reviewed, and changed-file intersections with `planning_scope_refs`.
-- Classify revision freshness as `fresh`, `drifted`, or `stale`. `fresh` may proceed through normal pickup gates. `drifted` prompts alignment and may proceed only when the Probe records accepted decisions or an explicit accepted gap. `stale` routes back to `idea-to-backlog` before implementation planning.
-- If `planned_base_sha` is missing, mark the freshness check `NOT_VERIFIED` and record the concrete fallback baseline, such as current target ref/SHA plus provider history. Treat that as an accepted gap only when the artifact names why planning may continue; do not invent a planned SHA. When using a Builder Kit Probe JSON record, include `resolution_hints` for `revision_freshness_not_verified` so the next planning attempt can see the accepted fallback baseline or route back to `pickup-probe` for missing evidence.
-- Research drift before asking questions: compare the selected work's `planned_base_sha` or pulled-work SHA to current HEAD before running the alignment interview. Inspect changed files, docs, ADRs, contracts, schemas, dependency state, and expected execution areas that overlap `planning_scope_refs` or likely modified files.
-- Classify the diff from planned base to current HEAD as `no_material_drift`, `scope_drift`, `dependency_drift`, `contract_drift`, or `conflict_risk`. Treat material drift as pickup Probe context and ask an alignment question before planning when it changes scope, acceptance criteria, dependency assumptions, terminology, contract expectations, or execution risk.
-- Compare the selected work to `CONTEXT.md`, docs, ADRs, contracts, existing skills, schemas, fixtures, and nearby code.
-- Verify that the acceptance criteria describe an executable outcome rather than only implementation tasks.
-- Sharpen fuzzy domain and workflow terms until the artifact names, scope, gate names, and next step mean one thing.
-- Surface contradictions between issue text, pull-work handoff, provider state, docs, ADRs, contracts, and code reality.
-- Challenge glossary conflicts immediately: if a user or issue uses a term differently than `CONTEXT.md`, ask which meaning is authoritative before planning.
-- Discuss concrete scenarios when boundaries are fuzzy, especially around ownership, provider state, workflow gates, and stop-short behavior.
-- Check whether the selected work is still ready after WIP, conflicts, blockers, dependency freshness, and expected modified files are considered.
-- If the pull-work artifact flags the selected item `reclaimable`, treat the recorded opt-in as a decision to re-confirm (not silently accept) when material drift or time has passed since pull-work's preflight ran.
-- Keep downstream issues and non-goals out of scope unless they are explicit contract consumers for the selected work.
-- Ask one question at a time when a decision is needed, include a recommended answer, and record the answer immediately.
-- Record unresolved questions as blockers unless the user or orchestrator explicitly accepts proceeding with the gap.
-- Update the active workflow artifact immediately when a decision crystallizes; do not rely on chat memory.
+## Contract
 
-For Builder Kit build-flow recovery, a missing or incomplete pickup Probe record routes `decision_gap` back to the `design-probe` step. For pickup/planning gaps, returning to `design-probe` means completing this pickup Probe record before retrying `plan-work`.
+- Probe one selected work item or one justified group after `pull-work` and before `plan-work`.
+- Reuse the generic `design-probe` interview behavior for unresolved decisions, but own the Builder pickup record and Builder evidence when the matching flow is active.
+- Do not implement code, revise the backlog, or turn unknowns into assumed requirements.
+- Stop planning when a blocker, contradiction, stale baseline, or material unanswered question lacks an explicit accepted gap.
 
-## Output
+## Provider Boundaries
 
-Record the pickup Probe result in the pull-work artifact, handoff artifact, or documented Builder Kit Probe record referenced by `state.json` or `handoff.json`. The record must include:
+Use `WorkItemProvider` for item detail and acceptance criteria, `BoardProvider` for current queue and dependency context, `RepositoryAdapter` for revision and source-scope context, and `AssignmentProvider` for durable ownership. A GitHub adapter is optional; provider-specific URLs, labels, Projects, pull requests, and commands are not required.
 
-- Probe status: `pass`, `needs_decision`, `blocked`, or `accepted_gap`.
-- Decisions made during the Probe, with source refs when relevant.
-- Unresolved questions, each with owner, impact, and whether it blocks planning.
-- Accepted gaps, including who accepted the gap and why planning may continue.
-- Drift research: planned base ref/SHA, current target ref/SHA, command or provider evidence used, changed files reviewed, drift classification, and whether the drift is material.
-- Builder Kit `resolution_hints` when available for baseline freshness `NOT_VERIFIED` gaps, including `planning.baseline.current`, required baseline evidence, and the accepted fallback baseline behavior.
-- Planning readiness: ready/not ready, required handoff target, and readiness evidence.
-- Expected modified files or file areas, including generated/runtime artifact expectations when relevant.
-- Conflict risks with active work, shared files, provider state, or downstream contract consumers.
-- Route reason and next action, such as `continue -> plan-work`, `decision_gap -> design-probe`, `blocked -> pull-work`, or `split_scope -> pull-work`.
+## Required Inputs
 
-## Planning Gate
+- selected work-item identifier and `pull-work` artifact
+- scope, non-goals, requirements, acceptance criteria, dependencies, and blockers
+- provider state, assignment/liveness result, target revision, and baseline freshness
+- expected modified files, conflict risks, worktree mode, and sandbox constraints
+- existing decisions, unresolved questions, and caller constraints
 
-Planning is ready only when:
+## Probe Method
 
-- Selected work and source refs are clear enough for `plan-work`.
-- Acceptance criteria and done criteria are present or explicit accepted gaps exist.
-- Planned-base drift research is recorded, or the missing baseline is explicitly marked `NOT_VERIFIED` with a best-available fallback.
-- Provider state and WIP/conflict scan have been checked or marked `NOT_VERIFIED` with a reason.
-- Scope, non-goals, expected modified files, and conflict risks are recorded.
-- Contradictions are resolved, blocked, or explicitly accepted as gaps.
-- The route reason and next action are recorded in an artifact that can be recovered without chat memory.
+1. Re-read the selected item and its upstream artifact. Check that selected identifiers, scope, acceptance criteria, grouping rationale, and next action agree.
+2. Confirm goal fit, user or operator outcome, scope, non-goals, acceptance-criteria quality, dependencies, blockers, provider state, assignment, WIP, and conflict context. When drift now makes a selected item `reclaimable`, re-confirm the recorded takeover opt-in and consequence; do not silently carry an earlier opt-in across changed holder or freshness evidence.
+3. Check target revision against the recorded base and planning scope. Record whether it is fresh, stale, or `NOT_VERIFIED`; identify changed intersections and acceptance-criteria drift.
+4. Identify expected files, sandbox/worktree mode, stop-short risks, and the evidence needed for planning and later verification.
+5. Resolve contradictions through the generic one-question-at-a-time probe. Record each decision, unresolved question, accepted gap with consequence, route reason, and next action.
+6. Set readiness to `ready`, `needs_more_probe`, or `accepted_gap_ready`. Only the first and explicitly accepted third outcome may hand off to `plan-work`.
 
-If the gate fails, stop before `plan-work` and update the artifact with the blocker or decision gap.
-## Gate Claims: Record Pickup Probe Results
+## Probe Record
 
-When the Planning Gate passes, record the two gate claims for the Builder Kit `design-probe` step before handing off to `plan-work`. These satisfy the `builder.design-probe.pickup-readiness` and `builder.design-probe.decisions` gate expectations.
+Record:
 
-**Claim 1 — Pickup readiness** (probe passed, goal fit and scope confirmed):
+- selected IDs and grouping decision
+- goal fit, scope, non-goals, acceptance-criteria assessment, and provider state
+- dependency and revision freshness, baseline, drift, assignment, WIP, and conflict findings
+- expected modified files, sandbox/worktree mode, risk, and stop-short risks
+- decisions, unresolved questions, accepted gaps, readiness, route reason, and next action
 
-```bash
-npm run workflow:sidecar -- record-gate-claim .kontourai/flow-agents/<slug> \
-  --expectation pickup-probe-readiness \
-  --status pass \
-  --summary "Pickup probe passed: goal fit confirmed, blockers checked, dependencies reviewed, acceptance criteria verified." \
-  --evidence-ref-json '{"kind":"artifact","file":".kontourai/flow-agents/<slug>/<slug>--pull-work.md","summary":"Pull-work artifact recording probe status, scope, and planning readiness."}'
-```
+## Active Builder Evidence
 
-**Claim 2 — Probe decisions captured** (decisions, accepted gaps, and planning readiness are recorded):
+Only for the active `builder.build` `design-probe` step, confirm the run and then record both expectations through the public interface:
 
 ```bash
-npm run workflow:sidecar -- record-gate-claim .kontourai/flow-agents/<slug> \
-  --expectation probe-decisions-or-accepted-gaps \
-  --status pass \
-  --summary "Probe decisions recorded: <decision-count> decisions, <gap-count> accepted gaps. Planning readiness: <ready|accepted_gap_ready>." \
-  --evidence-ref-json '{"kind":"artifact","file":".kontourai/flow-agents/<slug>/<slug>--pull-work.md","summary":"Pull-work artifact with decisions, accepted gaps, and planning handoff."}'
+flow-agents workflow status --session-dir <session-dir>
+flow-agents workflow evidence --session-dir <session-dir> \
+  --expectation pickup-probe-readiness --status pass \
+  --summary "Pickup probe records goal fit, scope, dependencies, risks, and planning readiness." \
+  --evidence-ref-json '{"kind":"artifact","file":"<session-dir>/<slug>--pull-work.md","summary":"Pickup readiness, scope, dependencies, risks, and planning decision."}'
+flow-agents workflow evidence --session-dir <session-dir> \
+  --expectation probe-decisions-or-accepted-gaps --status pass \
+  --summary "Probe decisions and accepted gaps are explicit in the handoff." \
+  --evidence-ref-json '{"kind":"artifact","file":"<session-dir>/<slug>--pull-work.md","summary":"Probe decisions, unresolved questions, accepted gaps, route reason, and next action."}'
 ```
 
-Record both claims together immediately when the gate passes. Use `--status fail` when the gate fails (unresolved blocker or decision gap). Use `--status not_verified` only when the session has no active flow step.
-
-When the gate fails, record `--status fail` with `--expectation pickup-probe-readiness` naming the blocker, and omit or defer the decisions claim until the blocker is resolved.
-
+Use `fail` for an unresolved planning blocker and `not_verified` when the record cannot prove an expectation. Do not record either claim outside the active matching step.
 
+## Durable Decision Notes
 
-## Docs-Write Policy: Two-Delta Emission
+When probing resolves a reusable domain decision, follow `context/contracts/probe-docs-write-contract.md`: update the existing vocabulary home when necessary, revise or create the topic-keyed decision record, and retain the probe record as provenance. Keep transient provider snapshots, implementation notes, and open questions in the pickup artifact.
 
-`pickup-probe` may identify durable terminology and decision gaps, but it must keep documentation changes narrow. Per `context/contracts/probe-docs-write-contract.md`, a **decision subject** crystallizing during pickup probing (a durable, reusable answer to a named domain question — not an implementation detail or transient planning choice) gets both deltas in the same motion:
+## Handoff
 
-- Update `CONTEXT.md` inline only for glossary-style durable terminology decisions, using tight one- or two-sentence definitions and `_Avoid_` terms when useful. Keep implementation details out of `CONTEXT.md`. Coin the subject term first if it is not already a glossary entry — vocabulary is the decision registry's topic namespace (`context/contracts/decision-registry-contract.md` § Slug rules) — or refine the existing entry when a decision changes what it says.
-- If a `CONTEXT-MAP.md` exists, update the relevant context instead of assuming the root glossary owns the term.
-- Create a lazy context file only when a resolved term or workflow concept has no existing home.
-- Do not create context files for transient planning notes, open questions, or provider snapshots.
-- Record a decision delta at `docs/decisions/<slug>.md`: consult `docs/decisions/index.md` first and propose revise-vs-create (an existing topic file, including a `needs-decision` stub, is revised in place; only an uncovered subject gets a new file), then run `npm run gen:decisions-index && npm run check:decisions`. Link this Probe's own session artifact as a `session-archive` evidence ref (transcript provenance). Never propose or create a numbered ADR — `docs/adr/` is frozen history; decisions go into the topic-keyed registry.
-- Prefer workflow artifacts for pickup decisions, unresolved questions, accepted gaps, and route reasons until the work is accepted.
+Hand `plan-work` the selected references, probe record, provider and baseline summary, decisions, unresolved questions, accepted gaps, expected modified files, conflict risks, sandbox/worktree mode, route reason, and next action. If the record is absent, contradictory, stale without an accepted gap, or not ready, route back to this probe instead of planning.
 
-## Handoff To Plan Work
+## Drift And Decision Safeguards
 
-When the Probe passes, hand off to `plan-work` with:
+Research drift before asking alignment questions. Record `planned_base_ref`, `planned_base_sha`, current target ref/SHA, commits-since, planned age, changed files, and intersections with `planning_scope_refs`. Classify revision freshness as `fresh`, `drifted`, or `stale`, and material drift as `no_material_drift`, `scope_drift`, `dependency_drift`, `contract_drift`, or `conflict_risk`.
 
-- selected work item refs
-- pull-work artifact path
-- pickup Probe record path or section
-- provider state summary
-- planned-base drift summary and drift classification
-- accepted gaps
-- expected modified files
-- conflict risks
-- sandbox/worktree mode
-- route reason and next action
+`drifted` may proceed only with a recorded decision or accepted gap. `stale` routes to `idea-to-backlog`. Missing `planned_base_sha` is `NOT_VERIFIED`, never implicitly fresh; an accepted fallback must name the current target ref/SHA plus provider history. When the Builder Probe shape supports resolution hints, record `gap_id: revision_freshness_not_verified`, `claim_id: planning.baseline.current`, the required evidence, and `resolve_at: pickup-probe`.
 
-`plan-work` must consume this record for Builder Kit build-flow planning. If the record is absent, contradictory, or lacks an accepted gap for a known decision gap, planning stops and routes back to `design-probe`.
+Challenge existing domain vocabulary before creating terms. A durable decision follows the probe docs-write contract and topic-keyed decision registry; never propose a numbered ADR. Link the probe artifact as provenance. Create a context file only when a resolved reusable term has no existing home.

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

@@ -1,216 +1,82 @@
 ---
 name: "plan-work"
-description: "Code planning primitive — goal + directory to structured execution plan. Delegates to tool-planner. No resume, no ideation."
+description: "Code planning primitive that turns a goal and directory into a structured implementation plan."
 ---
 
-# Plan
+# Plan Work
 
-Goal + directory in, structured plan artifact out. Pure planning primitive.
+Turn a bounded goal into an execution-ready plan. This skill plans; it does not implement or resume a Builder run.
 
-## Agents
+## Role And Binding
 
-| Agent | Role |
-|---|---|
-| tool-planner | Codebase analysis, structured execution plan, writes plan artifact |
+- **Role:** canonical Builder build-step producer and standalone planning primitive.
+- **Binding:** `builder.build` step `plan`.
+- **Produces:** `<slug>--plan-work.md`, `acceptance.json`, `handoff.json`, and `implementation-plan` for an active matching run.
+- **Standalone no-run behavior:** return a plan artifact without starting a Builder run, recording Builder evidence, or claiming the Builder prefix completed.
 
 ## Model Routing
 
-Planning delegation (`tool-planner`) resolves the `delegate-design` role from
-`.datum/config.json` (`npx @kontourai/datum resolve delegate-design --json`) and
-passes the resolved model explicitly — turning a goal into a plan needs design
-latitude, so it routes to the design tier. See
-`context/contracts/execution-contract.md` § Delegation: Model Routing. Fallback:
-inherit the session model when datum/config is absent, noted in the artifact.
+Delegate codebase analysis and plan writing to `tool-planner`. Resolve `delegate-design` from `.datum/config.json`; when unavailable, inherit the session model and record the fallback.
+Apply the routing and escalation contract in `context/contracts/execution-contract.md`.
 
-## Orchestrator Rule
+## Provider Boundaries
 
-You do not read source files. You delegate to tool-planner and read the artifact it produces.
+For provider-backed planning, consume context supplied by `WorkItemProvider`, `BoardProvider`, `RepositoryAdapter`, and `AssignmentProvider`. Do not assume a GitHub issue, pull request, branch convention, or provider-specific API. GitHub may be an optional adapter example only.
 
-## Shared Contracts
+## Inputs
 
-Follow:
-- `context/contracts/artifact-contract.md`
-- `context/contracts/planning-contract.md`
-- `context/contracts/sandbox-policy.md`
-
-This skill owns orchestration. The contracts own the required artifact shape, Definition Of Done, acceptance criteria, sandbox mode, evidence expectations, and stop-short risk rules.
-
-## Pre-Planning: Research
-
-Before delegating to tool-planner, check if the goal can be solved with existing tools or libraries:
-1. Search the current codebase for similar functionality
-2. If the goal involves adding new capabilities, invoke the search-first skill
-3. Pass research findings to tool-planner as additional context
-
-**Survey existing concepts before designing new ones.** Before the plan introduces a new
-artifact, schema, type, data shape, status, or derivation/algorithm, check what the project's
-**dependencies and contracts already define** — not just the local codebase. Inspect exported
-types, schemas, and builders from dependencies (e.g. `@kontourai/*` packages and vendored
-schemas) and the resource/data contracts under `context/contracts/`. Prefer **consuming the
-canonical concept over inventing a parallel one**: follow existing patterns, understand the
-dependency surface, and leverage existing concepts. If a planned shape resembles a dependency's
-existing concept, consume theirs and record which one. This operationalizes the consume-never-fork
-guardrail of ADR 0008 and ADR 0010 at planning time — the cheapest place to catch a fork.
-
-Skip the codebase-similarity search for pure bug-fix/refactor goals, but still apply the
-survey-existing-concepts check whenever the plan would add a new shape or algorithm.
-
-## Input
-
-The orchestrator (or user) provides:
-- **Goal**: what to build or change
-- **Directory**: working directory for the codebase
-- **Constraints**: from AGENTS.md, user preferences, conversation context
-- **Session file path** (optional): if part of a larger workflow, the orchestrator passes this
-
-Direct `plan-work` remains a standalone planning primitive. Do not require Builder Kit pickup Probe state for ordinary direct planning prompts unless the user is trying to pick up provider-backed backlog work or continue a productized build/delivery workflow.
+- goal, working directory, and user or repository constraints
+- optional selected-work and pickup-probe records for provider-backed work
+- source revision, dependency, acceptance-criteria, sandbox, worktree, and conflict context when available
 
-When `plan-work` is invoked from the Builder Kit `build` flow, from `deliver`, or from a pick-up-and-build request after `pull-work`, first read the recorded pickup Probe decisions, unresolved questions, accepted gaps, sandbox/worktree mode, expected modified files, and conflict risks from the pull-work or handoff artifact. If the handoff lacks required Probe decisions or explicitly accepted gaps, stop planning and route `decision_gap` back to `design-probe`; for pickup/planning gaps, that means returning to the pickup Probe before retrying planning.
+## Research And Readiness
 
-Only consume Builder Kit Probe `resolution_hints` in those Builder Kit build/deliver/pickup contexts. Direct primitive `plan-work` remains valid without Builder Kit-specific `resolution_hints`; do not require or synthesize them for ordinary planning requests.
+1. Search the codebase for existing behavior and patterns. Use `search-first` when the work adds a capability that may already exist elsewhere.
+2. Before adding a type, schema, artifact, status, or algorithm, inspect existing contracts and dependency exports. Consume canonical concepts instead of creating parallel ones.
+3. For Builder-backed work, require a fresh pickup record with selected IDs, readiness, grouping decision, decisions or accepted gaps, expected modified files, conflict risks, route reason, and next action. Route a missing or contradictory record to `pickup-probe`.
+4. Carry forward revision freshness, target ref/SHA, planned base, source-scope intersections, dependency state, acceptance-criteria drift, and accepted fallback baseline. A stale or unaccepted unknown baseline stops planning.
 
-Required Builder Kit handoff fields before planning:
+## Plan Contract
 
-- `probe_status` is `passed` or `accepted_gap`
-- `probe_artifact_ref` points to the pickup Probe record
-- selected item ids are present
-- grouping decision is `single-item`, `independent-items`, or `justified-bundle`
-- accepted gaps, expected modified files, conflict risks, route reason, and next action are recorded
+Ask `tool-planner` to produce an implementation plan containing:
 
-If the handoff came from stale broad continuation language after a previous merge, treat it as missing Probe evidence and route back to `design-probe` / `pickup-probe`. Do not infer permission to plan the next item from a previous continuation instruction.
+- goal, constraints, repository context, source revision, and accepted gaps
+- files or surfaces to change, sequence of work, dependencies, and rollback boundaries
+- `## Definition Of Done`, including stop-short risks and durable documentation target
+- stable acceptance criteria and a mapping from every task or wave to the criteria it supports
+- expected command/test evidence and structured source evidence for behavior changes
+- sandbox mode, escalation conditions, expected modified files, and conflict handling
+- execution handoff and next action
 
-## Provider-Backed Baseline Preflight
+Require evidence that is proportionate to the change and named by the accepted criteria.
 
-For provider-backed backlog work, `plan-work` consumes freshness context; it does not classify revision freshness itself. Before delegating to `tool-planner`, read the pull-work or pickup Probe artifact and carry forward:
+## Procedure
 
-- `revision_freshness` from the upstream artifact
-- current target ref/SHA confirmed from the latest provider or repository state available to pull-work/pickup Probe
-- `planned_base_ref` and `planned_base_sha` when present
-- accepted gaps, including any accepted-gap baseline for missing historical `planned_base_sha`
-- Builder Kit Probe `resolution_hints` for `revision_freshness_not_verified` when the invocation came through Builder Kit build/deliver/pickup, especially hints for `planning.baseline.current`
-- changed scope intersections with `planning_scope_refs`, contracts, dependencies, expected files, or execution areas
-- dependency freshness and provider state, including blockers, PR links, board/project membership, and any `NOT_VERIFIED` checks
+1. Resolve the artifact location through the host contract when one exists. In an active Builder run, write `<slug>--plan-work.md`, update `acceptance.json` with the stable criteria and evidence plan, and update `handoff.json` with the execution target and next action.
+2. Delegate the goal, directory, constraints, research findings, pickup context, and evidence requirements to `tool-planner`.
+3. Read the returned plan. Send it back for refinement when task-to-criterion traceability, scope, stop-short risks, or evidence expectations are missing.
+4. Present the plan when a user decision is needed; otherwise hand the plan to `execute-plan` only when the caller requests execution.
 
-If `revision_freshness` is `stale`, unresolved, missing without an accepted gap, or contradicted by dependency/provider state, stop planning. Route pickup/planning gaps back to `pickup-probe`; when `revision_freshness` is `stale`, route stale shaped work back to `idea-to-backlog` instead of handing the item to `tool-planner`.
+## Active Builder Evidence
 
-An explicit accepted-gap fallback baseline may allow planning to proceed, but it must name the fallback baseline used. Missing `planned_base_sha` is never fresh by itself. If baseline freshness is missing or `NOT_VERIFIED`, record the gap and stop planning unless it has been explicitly accepted as a fallback baseline naming the current target ref/SHA plus provider history or equivalent.
+This skill does not create or restamp a Builder run. For an already active `builder.build` `plan` step, confirm the run and record the completed plan through the public interface:
 
-For Builder Kit `resolution_hints` with `gap_id: revision_freshness_not_verified` and `claim_id: planning.baseline.current`, carry the accepted fallback baseline into the plan's baseline section exactly enough for execution and verification to recover it. If the missing baseline evidence does not include an explicit accepted fallback baseline, do not pass the item to `tool-planner`; route back to `pickup-probe` so the Probe can collect evidence or record the accepted gap.
-
-The `tool-planner` prompt context must include the latest-base confirmation and acceptance-criteria drift findings:
-
-- the current target ref/SHA that planning is based on
-- the source freshness state or accepted-gap baseline
-- each upstream AC id revalidated against drift
-- stale assumptions found during revalidation
-- any route-back decision already taken or still required
-
-## Workflow
-
-1. Create session file in `.kontourai/flow-agents/<slug>/` if one wasn't provided:
-   - Filename: `<slug>--plan-work.md`
-   - `status: planning`, `type: plan-work`
-   - Create or update `state.json` (phase `planning`) via `npm run workflow:sidecar -- init-plan`/`ensure-session` — never through a direct Write/Edit tool call (`config-protection.js` blocks that by design)
-   - use `npm run workflow:sidecar -- ensure-session --source-request ... --summary ... --criterion ...` when the repository provides it; this also writes `.kontourai/flow-agents/current.json`
-   - **Builder Kit build flow**: add `--flow-id builder.build` to the `ensure-session` call when `plan-work` is invoked from `deliver`, from the Builder Kit `build` flow, or from a pick-up-and-build request after `pull-work`. This activates the FlowDefinition-driven path so producers fire and gates enforce on builder.* claims. Do NOT add `--flow-id` for direct/ad-hoc primitive `plan-work` invocations that are not part of a builder-flow.
-2. Delegate to `tool-planner`:
-   ```
-   Goal: <goal>
-   Directory: <working directory>
-   Constraints: <constraints>
-   todo_file: <session file path>
-   Workflow artifact root: <path from npm run workflow:sidecar -- current --format path>
-   Latest-base confirmation: <current target ref/SHA, revision_freshness, planned base or accepted-gap baseline>
-   AC drift findings: <per-AC revalidation, stale assumptions, route-back decisions>
-   Evidence expectations: preserve AC ids; require command/test evidence and structured source refs for implementation behavior; require provider/closure `Acceptance Evidence` tables when comments claim behavior
-   ```
-3. tool-planner explores the codebase and writes the plan to the artifact file:
-   - `<session-basename>-plan.md`
-   - `acceptance.json` with pending criteria from Definition Of Done
-   - `handoff.json` with the execution/user-approval next steps
-   - use `npm run workflow:sidecar -- init-plan <artifact> --source-request ... --summary ... --next-action ...` when the repository provides it
-   - every acceptance criterion should have a stable id, either in Markdown or mirrored in `acceptance.json`
-   - every implementation task/wave should list which acceptance criterion ids it supports
-   - acceptance criteria for behavior changes should name expected command/test proof and expected source evidence refs or permalink upgrade expectations
-   - `acceptance.json` evidence refs must be structured objects, not legacy strings
-   - if task-to-acceptance mapping is unclear, send the planner feedback before presenting the plan as ready
-4. Read the plan artifact
-5. Update session file: paste plan summary into `## Plan`, set `status: planned`
-6. Update `state.json` (`status: planned`, phase `planning`, next action) via `npm run workflow:sidecar -- advance-state` — never through a direct Write/Edit tool call (`config-protection.js` blocks that by design)
-7. For an active Builder Flow run, record the `implementation-plan` gate claim after the plan and structured sidecars are complete:
-   ```bash
-   npm run workflow:sidecar -- record-gate-claim .kontourai/flow-agents/<slug> \
-     --expectation implementation-plan \
-     --status pass \
-     --summary "Implementation plan records files, sequencing, acceptance criteria, and required evidence." \
-     --evidence-ref-json '{"kind":"artifact","file":".kontourai/flow-agents/<slug>/<session-basename>-plan.md","summary":"Structured implementation plan with acceptance and evidence traceability."}'
-   ```
-   Use `fail` or `not_verified` instead of `pass` when the plan contract is not satisfied. The sidecar writer synchronizes Flow; Flow, not this skill, decides whether execution is now active.
-8. Present the plan to the user
-9. If the user wants changes, re-delegate to tool-planner with feedback
-
-Never rely on conversational memory for the slug. Resolve the active artifact with `npm run workflow:sidecar -- current --format path` and pass that path to delegated agents.
-
-## Definition Of Done Contract
-
-Every plan artifact must include the `## Definition Of Done` defined in `context/contracts/planning-contract.md`, including `Stop-short risks` and `Durable docs target`. If the goal is exploratory or uncertain, the plan must still name what the user should be able to take away from the work. Do not let acceptance criteria stop at implementation tasks.
-
-Every non-trivial implementation plan must include traceability from requirements to acceptance criteria to execution tasks. At minimum, acceptance criteria need stable ids and each wave/task needs a `Supports:` line referencing those ids. Loose wave names without criterion references are not execution-ready.
-
-Every behavior-changing plan must also include evidence traceability expectations. The Definition Of Done should tell workers and verifiers which command/test evidence is expected and which source evidence refs should support claimed behavior. Source refs use the structured evidence ref object from `context/contracts/artifact-contract.md`; before publication they may be local file/line/excerpt refs, and provider-facing comments should upgrade them to immutable GitHub blob permalinks pinned to a commit SHA when available. Plans that expect provider, PR, issue, closure, or final acceptance comments must require an `Acceptance Evidence` table with columns `AC id`, `Status`, `Command/Test Evidence`, `Source Evidence / Permalinks`, and `Gaps`.
-
-Every plan artifact must also record `Sandbox mode` using `context/contracts/sandbox-policy.md`. If the needed mode is unclear, choose the smallest safe mode for the plan and list the escalation condition that would require a stronger boundary.
-
-## Structured Sidecars
-
-Follow `context/contracts/artifact-contract.md` and `context/contracts/planning-contract.md`.
-
-When `npm run workflow:sidecar --` exists, structured sidecars are not optional ceremony. Use the writer commands above, then validate the artifact directory when local validation is available. If the writer is unavailable or blocked, preserve the exact blocker in the Markdown artifact as a `NOT_VERIFIED` gap.
-
-Planning owns:
-
-- `state.json`: current phase/status and next action
-- `acceptance.json`: criteria from the Definition Of Done, initially `pending`
-- `handoff.json`: summary and execution/user-approval next steps
-
-If a target harness cannot write sidecars, record `NOT_VERIFIED` or an explicit gap in the session file instead of pretending the structured state exists.
-
-## Session File Format
-
-```markdown
-# <Goal one-liner>
-
-branch: <branch>
-worktree: <worktree>
-created: <date>
-status: planning | planned
-type: plan-work
-
-## Plan
-
-Structured plan from tool-planner (pasted from artifact).
-
-## Definition Of Done
-
-Copied from the plan artifact. This is the stop condition for delivery.
+```bash
+flow-agents workflow status --session-dir <session-dir>
+flow-agents workflow evidence --session-dir <session-dir> \
+  --expectation implementation-plan --status pass \
+  --summary "Implementation plan records scope, sequencing, acceptance criteria, and required evidence." \
+  --evidence-ref-json '{"kind":"artifact","file":"<session-dir>/<slug>--plan-work.md","summary":"Execution-ready plan with Definition Of Done and task-to-criterion mapping."}' \
+  --evidence-ref-json '{"kind":"artifact","file":"<session-dir>/acceptance.json","summary":"Stable acceptance criteria and evidence requirements."}' \
+  --evidence-ref-json '{"kind":"artifact","file":"<session-dir>/handoff.json","summary":"Execution handoff, route reason, and next action."}'
 ```
 
-`<branch>` is the branch recorded in `state.json`'s `branch` field (`ensure-session` derives `agent/<actor>/<slug>`; an explicit `--branch` flag overrides on a new session). `ensure-session` only records the name — creating and checking out the actual git branch/worktree remains this skill's responsibility.
-
-## Output
+Use `fail` or `not_verified` when the plan is incomplete or cannot be evidenced. Do not enter `builder.build` at this step directly and do not use private writer commands.
 
-- Session file in `.kontourai/flow-agents/<slug>/` with status `planned`
-- Plan artifact: `<session-basename>-plan.md`
-- Structured sidecars: `state.json`, `acceptance.json`, and `handoff.json`
-- The plan artifact is the source of truth — tool-worker agents read it directly
-- Plan artifact follows `context/contracts/planning-contract.md`
+## Baseline And Evidence Safeguards
 
-{context?}
+Follow `context/contracts/planning-contract.md`, `context/contracts/artifact-contract.md`, and `context/contracts/sandbox-policy.md`. In an active Builder run, consume the recorded pickup Probe decisions, accepted gaps, expected modified files, conflict risks, grouping decision, route reason, and `revision_freshness`; direct standalone planning does not require Builder-specific Probe state.
 
-## Workflow Entry
+For provider-backed work, require the current target ref/SHA and revalidate each upstream AC id against drift. Record stale assumptions. Missing `planned_base_sha` is never fresh. If baseline freshness is missing or `NOT_VERIFIED`, stop unless an accepted fallback baseline names the current target ref/SHA plus provider history. `stale` shaped work routes to `idea-to-backlog`; missing pickup decisions route to `pickup-probe`.
 
-Do not create or restamp a `builder.build` run from this planning primitive. A Builder
-run enters through `pull-work`, then `design-probe`; Flow advances it to `plan` only after
-the declared upstream gates pass. When `plan-work` is invoked directly outside that
-product workflow, run it as a standalone primitive without `--flow-id builder.build` and
-do not report the omitted Builder prefix as complete.
+Behavior-changing plans require structured evidence ref objects and an `Acceptance Evidence` table mapping AC ids to command/test evidence, source evidence, and gaps. A plan must not be handed to execution when Definition Of Done, Stop-short risks, Durable docs target, sandbox mode, or task-to-AC traceability is missing.