@kontourai/flow-agents 3.6.0 → 3.8.0

package/kits/builder/skills/idea-to-backlog/SKILL.md

@@ -1,277 +1,96 @@
 ---
 name: "idea-to-backlog"
-description: "Turn raw product or technical ideas into shaped, prioritized, executable GitHub issue backlog. Use for idea intake, ideation, product shaping, spike/prototype decisions, PRD-like feature briefs, prioritization, and backlog creation before implementation starts."
+description: "Turn raw product or technical ideas into a shaped, prioritized, provider-neutral executable backlog before implementation starts."
 ---
 
 # Idea To Backlog
 
-Convert raw ideas into shaped, prioritized, executable backlog without starting production implementation.
+Convert raw ideas into shaped, prioritized, executable work without starting implementation.
 
-## Contract
-
-- Produce durable reasoning artifacts before creating execution issues.
-- Own the human-readable backlog issue contract; downstream delivery workflows inherit and refine it rather than inventing a new shape.
-- Create GitHub issues only for committed or near-committed work.
-- Do not write production code or edit implementation files.
-- Do not invoke downstream delivery skills while shaping upstream work.
-- After the backlog gate, hand off to `pull-work` only if the user explicitly asks to continue.
-- Never invoke `plan-work`, `execute-plan`, `review-work`, `verify-work`, `evidence-gate`, or release skills from this workflow.
-- Stop at gates unless the user explicitly asks to continue.
-- Treat GitHub issues as executable backlog, not the whole reasoning store.
-- Keep separate ideas separate until a shared outcome, hard dependency, or sequencing reason justifies bundling them.
-- Push back when the user blends unrelated ideas, and ask them to justify why the ideas belong together before shaping bundled work.
-
-## Model Routing
-
-When this skill delegates its shaping work (opportunity review, option
-exploration, slicing), resolve the `delegate-design` role from
-`.datum/config.json` (`npx @kontourai/datum resolve delegate-design --json`) and
-pass the resolved model explicitly — shaping a raw idea into a backlog 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.
-
-## Artifact Contract
-
-Create or update `.kontourai/flow-agents/<slug>/<slug>--idea-to-backlog.md` with:
-
-- `source_ideas`: raw inputs and dedupe links
-- `idea_inventory`: one record per distinct idea, classification, outcome, and reason
-- `slice_candidates`: thinnest meaningful slice for each buildable idea, success signal, and non-goals
-- `bundle_justification`: why grouped ideas belong together, or explicit decision to split
-- `dependency_map`: blocks / blocked-by / related-only relationships between ideas or slices
-- `phase`: intake, opportunity, explore, shape, prioritize, backlog, blocked, complete
-- `decisions`: decision, rationale, decision maker, date
-- `opportunity_briefs`: problem, stakeholder, outcome, confidence, size
-- `shaped_work`: scope, non-goals, requirements, acceptance criteria
-- `risk_release_notes`: risk class, rollout, rollback, observability
-- `backlog_links`: GitHub issue URLs and status
-- `parked_or_rejected`: reason and revisit trigger
-- `open_questions`: owner and needed evidence
-- `next_gate`: gate name and pass/fail/block status
-
-## Workflow
-
-### 1. Intake
-
-Normalize and deduplicate raw ideas.
-
-Classify each item as:
-
-- feature
-- bug
-- research question
-- spike
-- prototype
-- chore
-- cleanup
-- parked thought
-
-Outcome: `discard`, `park`, `merge`, `research`, `shape`, or `commit`.
-
-Gate: every idea has exactly one outcome and a recorded reason.
-
-### 2. Separate Ideas And Slice
-
-Create an idea inventory before shaping. Treat each distinct user problem, workflow, stakeholder, risk, or success metric as a separate idea unless proven otherwise.
-
-When multiple ideas arrive together:
-
-- name each idea separately
-- identify the thinnest meaningful slice for each buildable idea
-- challenge accidental bundles
-- require a bundle justification before shaping grouped work
-- distinguish hard dependencies from "related-only" context
-
-A thinnest meaningful slice is the smallest independently valuable and testable unit that can reach evidence/release gates without leaving dependent half-work behind.
-
-Bundled work is allowed only when at least one is true:
+## Role And Binding
 
-- one slice cannot deliver value without the other
-- the same user outcome and acceptance signal require both
-- the dependency order is explicit and the first slice unlocks the second
-- grouping reduces delivery risk more than it increases scope risk
+- **Role:** canonical Builder shape-step producer.
+- **Binding:** `builder.shape` steps `shape`, `breakdown`, and `file-issues`.
+- **Produces:** the `trust.bundle` shaping slices for an active matching run: `shaped-problem`, `shaped-outcome`, `shaped-constraints`, `shaped-non-goals`, `shaped-success`, `shaped-risk`, optional `open-decisions`, `slices-defined`, and `work-items-filed`.
+- **Standalone no-run behavior:** create a local shaping artifact or return the shaped backlog to the caller. Do not start a Builder run, record Builder evidence, or imply that any Builder gate passed.
 
-If the user is blending ideas without justification, push back directly and stop shaping the bundle until the relationship is clear.
-
-Gate: every shaped candidate has one outcome, one thinnest meaningful slice, and either a split decision or a recorded bundle justification and dependency map.
-
-### 3. Opportunity Review
-
-For ideas worth shaping, capture:
-
-- product/theme goal
-- user or stakeholder
-- problem / opportunity
-- expected outcome
-- confidence
-- rough investment size
-- tradeoffs and what this displaces
-
-Gate: the opportunity is worth shaping, or it is parked/rejected.
-
-### 4. Explore Options
-
-Use `search-first` or `explore` when context is missing.
-
-Decide the path:
-
-- `shape-work`: enough is known to define the feature.
-- `spike-research`: unknowns need investigation, no production code.
-- `prototype-mvp`: visual or interaction proof is needed in an isolated worktree.
-- `reject/park`: not worth current backlog.
-
-For spikes and prototypes, define the learning question, timebox, artifact, and cleanup expectation. Prototype work must be isolated and must not silently become production implementation.
-
-### 5. Shape Work
-
-Create a brief with:
+## Contract
 
-- story / user outcome: `As a <user/persona>, I want <capability>, so that <outcome>` when a user-facing story fits; otherwise use a concise system/operator outcome
-- problem statement
-- users / stakeholders
-- scope
-- non-goals
-- requirements with stable ids, such as `R1`, `R2`
-- UX/API implications
-- acceptance criteria with stable ids, such as `AC1`, `AC2`; criteria must be testable and map back to requirements
-- verification expectations that preserve AC ids and name expected command/test evidence plus source evidence/permalink expectations when implementation behavior is claimed
-- risk class
-- rollout / rollback notes
-- observability or release concerns
-- open questions
+- Produce durable reasoning before creating executable work items.
+- Do not write production code or invoke downstream build, review, verification, or release skills.
+- Keep distinct ideas separate unless a shared outcome, hard dependency, or sequencing reason justifies a bundle.
+- Stop after shaping unless the user explicitly asks to continue with another workflow.
+- Treat provider work items as an execution queue, not as the sole reasoning store.
 
-Gate: acceptance criteria are testable and scope/non-goals are stable enough for planning.
+## Provider Boundaries
 
-The backlog issue shape should optimize for human readability first, then workflow traceability:
+Use configured capabilities rather than provider-specific commands or data shapes:
 
-- `Story / Outcome`
-- `Problem`
-- `Scope`
-- `Non-goals`
-- `Requirements` with stable `R*` ids
-- `Acceptance Criteria` with stable `AC*` ids
-- `Verification Expectation`
-- `Acceptance Evidence` expectation: closure/provider comments must map AC ids to status, command/test evidence, source evidence/permalinks, and gaps
-- `Milestone / Delivery Outcome`
-- `Dependencies / Blockers`
-- `Source Artifact`
+- `BoardProvider` supplies candidate queue, priority, milestone, and board state.
+- `WorkItemProvider` creates or updates executable work items and records their references.
+- `RepositoryAdapter` supplies repository identity, target revision, and source context.
+- `AssignmentProvider` may provide ownership context; shaping does not claim work.
 
-Downstream `pull-work`, `plan-work`, `execute-plan`, `review-work`, `verify-work`, and `evidence-gate` must preserve the `R*` and `AC*` ids and add readiness, execution, modified-file scope, critique, and evidence mappings.
+GitHub is only an optional adapter example. Do not require GitHub issues, Projects, labels, milestones, URLs, or `gh` for this skill to work.
 
-### 6. Prioritize
+## Model Routing
 
-Produce a priority brief:
+For delegated opportunity review, option exploration, or slicing, resolve `delegate-design` from `.datum/config.json`. If that mapping is unavailable, inherit the session model and record the fallback in the artifact.
+Apply the routing and escalation contract in `context/contracts/execution-contract.md`.
 
-- recommendation: do / defer / reject
-- why now
-- expected outcome
-- confidence
-- cost / size
-- risks
-- dependencies
-- alternatives
-- human decision
+## Artifact
 
-Gate: tradeoff, priority, and decision maker are explicit.
+Create or update `<slug>--idea-to-backlog.md` with:
 
-### 7. Sync Executable Backlog
+- source ideas, deduplication decisions, and an inventory of distinct ideas
+- the thinnest meaningful slice, outcome, non-goals, and bundle justification for each buildable idea
+- dependency map, opportunity briefs, options considered, and priority recommendation
+- requirements and acceptance criteria with stable `R*` and `AC*` identifiers
+- risk, rollout, rollback, observability, open-question, parked, and rejected-work records
+- created work-item references and the selected provider/adapter capability gaps
+- source revision assumptions: target ref/SHA when available, shaping time, and relevant scope references
 
-Use `github-cli` / `gh` for issues when available.
+## Shape
 
-Create GitHub issues only for committed or near-committed execution units. Each issue should include:
+1. Normalize and deduplicate the inputs. Classify each as a feature, bug, research question, spike, prototype, chore, cleanup, or parked thought. Give every idea one outcome: discard, park, merge, research, shape, or commit.
+2. Separate ideas before slicing. Name the user problem, stakeholder, risk, and success signal for each idea. Require a recorded split decision or bundle justification.
+3. Review opportunity: product goal, affected user or operator, expected outcome, confidence, investment, tradeoffs, and what the work displaces.
+4. Choose the path: shape work, time-boxed research, isolated prototype, or park/reject. A spike or prototype must state its learning question, artifact, cleanup expectation, and why it is not production implementation.
+5. Shape the work with a problem statement, scope, non-goals, requirements, testable acceptance criteria, UX/API implications, verification expectations, risks, rollout and rollback notes, observability, and open questions.
+6. Prioritize explicitly: do, defer, or reject; why now; expected outcome; confidence; size; risk; dependencies; alternatives; and decision owner.
+7. File only committed or near-committed slices through `WorkItemProvider`. Preserve the readable brief and provider-neutral metadata needed for later selection: dependencies, blockers, source revisions, planning scope references, and the shaping artifact reference.
 
-- story / outcome
-- problem
-- scope
-- non-goals
-- requirements with stable `R*` ids
-- acceptance criteria
-- links to source brief / session artifact
-- priority rationale
-- milestone or milestone decision: assign a milestone when the work contributes to a named delivery outcome, or record why no milestone is appropriate
-- expected size
-- thinnest meaningful slice
-- dependencies / blockers
-- bundle justification if grouped with other issues
-- verification expectation
-- release/evidence expectation
-- acceptance evidence expectation, including source evidence refs for behavior claims and immutable GitHub blob permalinks pinned to commit SHA when a provider change is available
-- owner or assignee when known
+A thinnest meaningful slice is independently valuable and testable. Bundle only when the same outcome requires all included work, a hard dependency makes sequencing necessary, or grouping demonstrably reduces delivery risk.
 
-Each synced issue body must preserve the human-readable `Dependencies / Blockers` prose for people and also include a provider-neutral structured metadata marker for adapters. The marker is workflow metadata embedded in the body, not a requirement to use provider-native dependency, sub-issue, project, or custom-field APIs. Native dependency surfaces are adapter-specific enhancements and are outside the generic skill contract.
+## Work Item Contract
 
-At sync time, capture the source revision assumptions that shaped the issue:
+Each filed work item should include:
 
-- `planned_base_ref`: target branch or ref used during shaping
-- `planned_base_sha`: exact commit SHA for that ref at shaping time
-- `planned_at`: timestamp when the issue scope was shaped or last materially refreshed
-- `planning_artifact_ref`: idea-to-backlog artifact, brief, design, ADR, or other source artifact that produced the issue
-- `planning_scope_refs`: key docs, contracts, schemas, files, packages, or provider records considered while shaping
+- story or operator outcome, problem, scope, and non-goals
+- stable `R*` requirements and `AC*` acceptance criteria
+- verification expectation and a future acceptance-evidence table: `AC id`, `Status`, `Command/Test Evidence`, `Source Evidence`, and `Gaps`
+- priority rationale, expected size, dependencies/blockers, milestone or delivery outcome decision, and source artifact reference
+- source revision groups with `planned_base_ref`, `planned_base_sha`, `planned_at`, and `planning_scope_refs` when the `RepositoryAdapter` can supply them
 
-Represent source revision per relevant repository. Single-repo work may use one source revision group; cross-repo work should use an array of scoped groups so downstream consumers can compare each repository against its own planned base.
+Use an adapter-neutral structured metadata attachment or field when supported. Native dependency, project, milestone, assignee, and custom-field features remain optional adapter enhancements.
 
-Emit structured `blockers[]` in the marker in addition to the prose `Dependencies / Blockers` section. Use structured entries for provider refs, artifact refs, decisions, external dependencies, and text blockers. Keep the prose section concise and readable; the structured marker carries normalized fields for `pull-work`, pickup Probe, and provider adapters.
+## Active Builder Evidence
 
-Provider-neutral marker example:
+Only when an active `builder.shape` run is already bound to this work, inspect
+its current state with the public workflow status command. Record each completed
+expectation with the public workflow evidence command; use reviewable shaping
+references and never an internal writer:
 
-```markdown
-<!-- flow-agents:work-item-metadata
-{
-  "schema_version": "1.0",
-  "source_revisions": [
-    {
-      "repo": "owner/repo",
-      "planned_base_ref": "main",
-      "planned_base_sha": "0123456789abcdef0123456789abcdef01234567",
-      "planned_at": "2026-06-03T03:23:14Z",
-      "planning_artifact_ref": ".flow-agents/example/example--idea-to-backlog.md",
-      "planning_scope_refs": [
-        "kits/builder/skills/idea-to-backlog/SKILL.md",
-        "context/contracts/work-item-contract.md"
-      ]
-    }
-  ],
-  "blockers": [
-    {
-      "type": "work_item",
-      "ref": "provider://work-items/123",
-      "status": "blocked",
-      "summary": "Needs the upstream contract issue to land first."
-    },
-    {
-      "type": "text",
-      "status": "blocked",
-      "summary": "Needs product decision on rollout scope."
-    }
-  ]
-}
--->
+```bash
+flow-agents workflow status --session-dir <session-dir>
+flow-agents workflow evidence --session-dir <session-dir> \
+  --expectation <expectation-id> --status pass \
+  --summary "Shaped work and filed Work Item evidence are recorded." \
+  --evidence-ref-json '{"kind":"artifact","file":"<session-dir>/<slug>--idea-to-backlog.md","summary":"Reviewable shaping report with slices and filed Work Item links."}'
 ```
 
-For one-repo issues, adapters may normalize the first source revision group to top-level `planned_base_ref`, `planned_base_sha`, `planned_at`, `planning_artifact_ref`, and `planning_scope_refs` while preserving `source_revisions` when present.
-
-Avoid creating tiny implementation tasks too early; `plan-work` can decompose inside an execution artifact later.
-
-Gate: every created issue is ready for `pull-work` or explicitly marked blocked/needs shaping.
-
-Backlog issue bodies should not require live provider calls to create permalinks during shaping. They should require downstream closure comments to include an `Acceptance Evidence` table with columns `AC id`, `Status`, `Command/Test Evidence`, `Source Evidence / Permalinks`, and `Gaps`; source evidence can start as local file/line refs during verification and should be upgraded to immutable provider permalinks before closure when available.
-
-When a GitHub Project is used, decide whether milestones are represented as repo milestones, project fields, issue labels, or intentionally omitted. Record the chosen milestone strategy in the artifact and apply it consistently to created issues/project items when the provider supports it.
-
-## Gates
-
-- Idea Gate: deduped, classified, and either discarded, parked, merged, researched, shaped, or committed.
-- Slice Gate: every candidate has one outcome, one thinnest meaningful slice, and explicit split/bundle/dependency reasoning.
-- Shape Gate: brief is coherent and acceptance criteria are stable enough.
-- Priority Gate: priority and tradeoff are explicit.
-- Backlog Gate: GitHub issues are ready for `pull-work`.
-
-If a gate fails, update the artifact with the missing evidence or decision and stop.
+At `shape`, record the six required shape expectations and `open-decisions` when applicable. At `breakdown`, record `slices-defined`. At `file-issues`, record `work-items-filed`. Use `fail` or `not_verified` when the artifact cannot support the expectation; never convert an accepted uncertainty into a passing claim.
 
-## Backlog Hygiene
+## Stop
 
-- Do not let every qualified idea become an issue.
-- Use an inbox, opportunity store, shaped queue, executable backlog, and archive.
-- Parked ideas need a reason and revisit trigger.
-- Stale issues should be closed, archived, or returned to discovery.
+Stop when the selected path is shaped and either filed as executable work, intentionally parked, or explicitly rejected. Hand off to `pull-work` only when the user asks to select work for delivery.

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

@@ -1,196 +1,89 @@
 ---
 name: "learning-review"
-description: "Capture post-merge, post-deploy, or post-incident learnings and feed them back into backlog, workflow skills, tests, docs, or knowledge. Use after release readiness, post-deploy checks, retrospectives, failed gates, or repeated workflow friction."
+description: "Capture delivery decisions, outcomes, and routed follow-up. Records Builder publish-learn learning evidence in trust.bundle."
 ---
 
 # Learning Review
 
-Turn delivery outcomes into durable learning and follow-up work.
+## Role
 
-## Contract
+This is a Builder step skill.
 
-- Do not rewrite history or mark failed work as successful.
-- Do not implement fixes during the review.
-- Capture facts, decisions, and follow-up issues separately.
-- Feed actionable changes back to `idea-to-backlog`, GitHub issues, tests, docs, or knowledge.
-- Use `knowledge-capture` or `observe` when the learning should persist beyond the repo.
-- Compare long-lived docs against the local `.kontourai/flow-agents/<slug>/` plan and the final acceptance artifact so implementation intent is not lost after merge.
-- Treat `learning-review` as the terminal closeout decision point for correction telemetry. Compare intended behavior to observed behavior before writing `learning.json`, then record either `correction.needed: false` for a clean run or `correction.needed: true` for a mismatch.
+Learning Review records what the delivery outcome taught us and where any
+correction belongs. It does not rewrite history, implement fixes, or declare a
+failed outcome successful.
 
-## Inputs
-
-- Release-readiness artifact, evidence-gate artifact, PR/issue links, deploy notes, incidents, telemetry, user feedback, and reviewer/verifier notes.
-- **Delegation routing telemetry** — the per-run economics records (`.kontourai/telemetry/economics.jsonl`) carry `delegations[]` with each sub-agent's `(role, resolved_model, outcome)`. Feed them to the routing-efficiency review (step 2a) to judge whether the model each role routes to is actually efficient.
-- **Kit/gate economics proposal ledger** — the same economics records, turned into a durable, idempotent per-kit/per-gate proposal ledger (`.kontourai/telemetry/learning-review-proposals.jsonl`) by `scripts/telemetry/learning-review-proposals.sh`. Feed it to the kit/gate economics review (step 2b).
-
-## Artifact Contract
-
-Create or update `.kontourai/flow-agents/<slug>/<slug>--learning-review.md` with:
-
-- `scope`: delivered work, issue/PR/release links, dates
-- `outcomes`: expected vs observed behavior and signals
-- `evidence`: telemetry, support notes, incidents, CI/review patterns
-- `decisions`: what changed, why, and who decided
-- `gaps`: process, tests, docs, skill, tooling, product, or ownership gaps
-- `followups`: GitHub issues, idea-to-backlog items, docs/tests/eval work
-- `knowledge_updates`: notes captured or observations proposed
-- `docs_promotion`: durable docs updated, source artifacts archived/linked, and gaps routed
-- `runtime_artifact_cleanup`: `.flow-agents/` runtime artifacts remain untracked or a blocker is recorded
-- `verdict`: LEARNED, FOLLOWUP_REQUIRED, or BLOCKED
-
-When the repository provides `npm run workflow:sidecar --`, also write `learning.json` with:
-
-```bash
-npm run workflow:sidecar -- record-learning .kontourai/flow-agents/<slug> \
-  --status learned \
-  --record-json '{"id":"...","source_refs":["release.json"],"outcome":"success","facts":["..."],"interpretation":"...","routing":[{"target":"none","action":"No follow-up required after intended-vs-observed closeout.","status":"completed"}],"correction":{"needed":false,"evidence":"Acceptance, release, docs promotion, and learning closeout behaved as intended."}}' \
-  --summary "..."
-```
-
-Use `followup_required` or `blocked` when facts are captured but follow-up routing is still open.
-
-Clean terminal runs must record a lightweight no-correction-needed record, not an invented lesson. Use `correction.needed: false`, a brief `correction.evidence` summary, and closed routing such as `target: "none"` with `status: "completed"`.
-
-Mismatch terminal runs must record `correction.needed: true` with:
-
-- `correction.type`: one of `workflow`, `skill`, `agent`, `tooling`, `test`, `doc`, `process`, `product`, `provider`, or `none`
-- `correction.recurrence_key`: a stable free-form key for grouping repeated failures
-- `correction.intended_behavior`: what the workflow, artifact, skill, agent, or provider was supposed to do
-- `correction.observed_behavior`: what actually happened
-- `correction.gap`: the difference between intended behavior and observed behavior
-- `correction.prevention`: a routed prevention action, or `correction.no_change_rationale` when no change is intentionally made
-
-If a correction-needed prevention route is still open, use `learning.status: followup_required` unless the route is already represented by a durable provider issue, deferred with a trigger, accepted, or rejected with a rationale.
+## Binding
 
-After writing `learning.json`, run artifact validation when available. If `record-learning` is unavailable or blocked, keep the learning verdict at `FOLLOWUP_REQUIRED` or `BLOCKED` in the Markdown artifact and record the sidecar-write gap explicitly.
+| Context | Binding | Flow expectations |
+| --- | --- | --- |
+| Active Builder run | Parent `builder.build` projection at composed `builder.publish-learn` step `learn` | `decision-evidence` and `learning-evidence` |
+| Standalone invocation | No Flow binding | No workflow mutation. |
 
-For Flow Agents repo changes, prefer the combined self-validation command when evidence and critique are part of the same pass:
+For an active run, inspect the binding first:
 
 ```bash
-npm run workflow:sidecar -- dogfood-pass \
-  --check-json '{"id":"...","kind":"test","status":"pass","summary":"..."}' \
-  --require-critique \
-  --critique-id "..." \
-  --critique-summary "..." \
-  --learning-record-json '{"id":"...","source_refs":["evidence.json","critique.json"],"outcome":"success","facts":["..."],"interpretation":"...","routing":[{"target":"none","action":"No correction required.","status":"completed"}],"correction":{"needed":false,"evidence":"Evidence and critique matched the intended closeout behavior."}}'
+flow-agents workflow status --session-dir <session-dir> --json
 ```
 
-Use `dogfood-pass` only when it can preserve the real evidence state. It must not turn `NOT_VERIFIED` or missing critique into a clean learning outcome.
-
-## Workflow
-
-### 1. Reconstruct Outcome
-
-Compare the original intent, acceptance criteria, release decision, and post-deploy signals. Distinguish facts from interpretation.
-
-### 1a. Decide Correction State
-
-Before identifying durable learnings, write down the intended behavior, observed behavior, and any gap. If there is no gap, record `correction.needed: false`. If there is a gap, record `correction.needed: true` with typed `correction.type`, stable `correction.recurrence_key`, intended behavior, observed behavior, gap, and either a prevention route or an explicit no-change rationale.
-
-### 2. Identify Learning
-
-Classify learnings as product, technical, operational, workflow, test, documentation, eval, or agent-behavior learning.
-
-### 2a. Review Delegation Routing Efficiency
-
-Run the routing-efficiency analyzer over the run's economics records and review its proposals — the
-internal mirror of the #409 small-model value proof, applied to our own agent fan-out:
-
-```bash
-bash scripts/telemetry/routing-efficiency.sh .kontourai/telemetry/economics.jsonl
-```
-
-It emits ADVISORY per-`(role, model)` proposals (`escalate-minimum-tier`, `keep-tier`, `monitor`,
-`insufficient-signal`) with rationales, computed only from **measurable** outcomes — `unavailable`
-outcomes are excluded (a missing verdict is neither success nor failure; see
-`docs/specs/harness-capability-matrix.md`). Fold any actionable proposal into `learning.json`:
-
-- an `escalate-minimum-tier` / demote proposal → a `routing` entry (`target: "rule"`, naming the
-  `.datum/config.json` role→model change to consider) or `correction` with `type: "agent"`.
-- **These are proposals, never auto-applied.** A human ratifies the `.datum/config.json` change, which
-  then travels the normal deliver loop (ADR 0003 call 5). `insufficient-signal` proposals are recorded
-  as coverage notes, not routing changes.
+Public status reports the parent definition as `builder.build`. Only that parent
+run at `learn`, whose Flow Definition composes the step from
+`builder.publish-learn`, may publish workflow evidence. A standalone review
+produces its local record only.
 
-### 2b. Review Kit/Gate Economics Proposals
-
-Run the kit/gate economics analyzer over a window of economics records whenever enough new
-records have piled up since the last ledger entry — cadenced during a learning-review pass, not
-on a scheduler (see `--help` for the full flag set):
-
-```bash
-bash scripts/telemetry/learning-review-proposals.sh --since <last-run-until> --until <now>
-```
-
-It emits ADVISORY per-kit (`kit-review-cost-inflation`) and per-gate (`gate-false-block-review`,
-`gate-well-calibrated`) proposals, each citing paired `evidence.cost` + `evidence.defect` — never
-cost alone. `insufficient-data` is a valid, reportable outcome, not a bar to lower; never propose
-from noise. Surface every new (non-`already_proposed`) proposal to the human with its evidence,
-then record the ratify/reject/defer decision BEFORE any follow-on work exists:
-
-```bash
-bash scripts/telemetry/learning-review-decide.sh <ledger> <proposal-id> \
-  --ratify|--reject|--defer --decided-by <name> --rationale "<why>"
-```
-
-- **These are proposals, never auto-applied.** Nothing here writes to `kits/**`,
-  `.datum/config.json`, or any gate/flow config file.
-- Only on `--ratify`, create the ordinary follow-on backlog item and record it back onto the
-  proposal with `--follow-on-ref <ref>` — a follow-on may never cite an unratified proposal. A
-  later pass's effect-fill shows whether the ratified change actually moved the numbers.
-
-See `docs/specs/learning-review-proposals-contract.md` for the full contract.
-
-### 3. Route Follow-Up
-
-Route raw ideas or ambiguous improvements to `idea-to-backlog`. Create GitHub issues only for executable follow-up. Use `evidence-gate` again when unresolved trust questions remain.
-
-### 4. Capture Durable Knowledge
-
-Use `knowledge-capture` for durable project or relationship knowledge and `observe` for repeated agent workflow patterns or corrections.
-
-### 5. Confirm Docs Promotion
-
-Check whether accepted delivery artifacts were promoted into long-lived documentation and whether `.flow-agents/` runtime artifacts remained untracked before merge to `main`. If not, route the missing doc or cleanup work as an owned follow-up or explicitly record why the delivery was self-explanatory.
-
-### 6. Close The Loop
-
-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.
+## Inputs
 
-**Claim 1 — Decision evidence** (durable decisions from the build are recorded):
+- Original intent, acceptance evidence, confidence report, and release decision.
+- Observed outcomes from `RepositoryAdapter`, `CheckProvider`, `ReleaseProvider`,
+  and `DeployProvider` when those providers exist.
+- Incidents, user feedback, review findings, operational observations, and
+  durable documentation decisions.
+
+## Learning Work
+
+1. Compare intended and observed outcomes. Separate observed facts from
+   interpretation.
+2. Record delivery decisions and whether a correction is needed. A clean result
+   may record that no correction is needed; do not invent a lesson.
+3. When a correction is needed, name the gap, the affected workflow or product
+   area, and a durable follow-up, deferral condition, accepted decision, or
+   explicit rationale for no change.
+4. Give each correction a stable identifier, owner or ownership gap, target
+   destination, evidence, disposition, and follow-up state. Route product work
+   to the backlog, workflow defects to the owning workflow, regression risks to
+   tests, durable operating knowledge to the knowledge system, and binding
+   decisions or changed contracts to documentation or an ADR.
+5. Record follow-up creation or linkage as observed evidence. A recommendation
+   without a durable destination remains open; do not report it as captured.
+6. Preserve `NOT_VERIFIED` for outcomes that could not be observed. Do not infer
+   deployment, release, provider, or user outcomes from local completion alone.
+7. Give `decision-evidence` and `learning-evidence` independent verdicts. A
+   complete decision record can pass while learning follow-up remains failed or
+   `NOT_VERIFIED`.
+8. On a matching active run, publish both expectations through the public CLI:
 
 ```bash
-npm run workflow:sidecar -- record-gate-claim .kontourai/flow-agents/<slug> \
+flow-agents workflow evidence --session-dir <session-dir> \
   --expectation decision-evidence \
-  --status pass \
-  --summary "Build decisions recorded: <decision-count> decisions captured, correction.<needed> recorded." \
-  --evidence-ref-json '{"kind":"artifact","file":".kontourai/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):
+  --status <pass|fail|not_verified> \
+  --summary "Delivery decisions and unresolved gaps are recorded." \
+  --evidence-ref-json '{"kind":"artifact","file":"<session-dir>/learning.json","summary":"Recorded delivery decisions, correction state, and routing."}'
 
-```bash
-npm run workflow:sidecar -- record-gate-claim .kontourai/flow-agents/<slug> \
+flow-agents workflow evidence --session-dir <session-dir> \
   --expectation learning-evidence \
-  --status pass \
-  --summary "Learning evidence captured: <outcome> outcome, facts recorded, routing complete." \
-  --evidence-ref-json '{"kind":"artifact","file":".kontourai/flow-agents/<slug>/learning.json","summary":"learning.json with outcomes, facts, and routing."}'
+  --status <pass|fail|not_verified> \
+  --summary "Observed outcomes and learning follow-up are recorded." \
+  --evidence-ref-json '{"kind":"artifact","file":"<session-dir>/learning.json","summary":"Observed outcomes, follow-up routing, and unresolved gaps."}'
 ```
 
-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.
-
-
+## Output
 
-## Gates
+Record scope, intended and observed outcomes, decisions, facts, interpretation,
+correction state, `NOT_VERIFIED` gaps, and follow-up routing as the
+`decision-evidence` and `learning-evidence` slices in `trust.bundle`.
+Corrections include their identifier, owner, destination, evidence, disposition,
+and durable link when one was created.
 
-- Learning Gate: observed outcome is recorded with evidence.
-- Follow-Up Gate: every actionable gap is routed, owned, or intentionally deferred.
-- Knowledge Gate: durable learning is captured in the right store.
-- Docs Gate: accepted planning and final acceptance artifacts are archived and linked from durable docs when useful.
-- Closure Gate: the artifact says what is done, what remains, and why.
-- Correction Gate: every terminal learning review records whether correction was needed; clean runs do not invent lessons, and mismatch runs have a recurrence key plus prevention route or no-change rationale.
+For a matching active run, publish both `decision-evidence` and
+`learning-evidence` from those slices. These claims record closeout evidence;
+they do not erase open follow-up work or authorize an external operation.