@kontourai/flow-agents 3.6.0 → 3.8.0

package/context/scripts/hooks/stop-goal-fit.js

@@ -1759,6 +1759,37 @@ function hasSidecarPresence(artifactDir) {
   return fs.existsSync(path.join(artifactDir, 'state.json')) || fs.existsSync(path.join(artifactDir, 'trust.bundle'));
 }
 
+function canonicalFlowState(root, artifactDir) {
+  if (!artifactDir) return { state: null, error: null };
+  const slug = path.basename(artifactDir);
+  if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(slug)) return { state: null, error: 'canonical Flow run slug is malformed' };
+  const runDir = path.join(root, '.kontourai', 'flow', 'runs', slug);
+  const components = [
+    path.join(root, '.kontourai'),
+    path.join(root, '.kontourai', 'flow'),
+    path.join(root, '.kontourai', 'flow', 'runs'),
+    runDir,
+  ];
+  try {
+    for (const component of components) {
+      const stat = fs.lstatSync(component);
+      if (stat.isSymbolicLink() || !stat.isDirectory()) return { state: null, error: `canonical Flow run has an unsafe parent component: ${component}` };
+    }
+    const file = path.join(runDir, 'state.json');
+    const stat = fs.lstatSync(file);
+    if (stat.isSymbolicLink() || !stat.isFile()) return { state: null, error: 'canonical Flow state must be a non-symlink regular file' };
+    const state = JSON.parse(fs.readFileSync(file, 'utf8'));
+    if (!state || typeof state !== 'object' || Array.isArray(state)
+      || typeof state.status !== 'string' || !state.status.trim()
+      || typeof state.current_step !== 'string' || !state.current_step.trim()) {
+      return { state: null, error: 'canonical Flow state is malformed' };
+    }
+    return { state, error: null };
+  } catch (error) {
+    return { state: null, error: `canonical Flow state is unavailable or malformed: ${safeOneLine(error && error.message || error, 120)}` };
+  }
+}
+
 // WS8 (AC10a): when current.json names a slug whose session directory does NOT exist,
 // return that slug so analyze() can log the staleness rather than silently falling back to
 // a global mtime scan that could resurface an abandoned/never-real session as active.
@@ -1871,7 +1902,7 @@ function missingBundleOrStateSignal(artifactDir, activeFlowStep) {
 //
 // Both are used in analyze() for blocking decisions AND in run() for the AC2
 // MAX_BLOCKS hard-block guard (preventing auto-release of hard blocks).
-const HARD_BLOCK = /contradicts evidence\.json|caught false-completion|evidence verdict:|evidence check .+ status:|critique status|critique open|required sidecar is missing|command-log integrity check FAILED|gate misconfiguration:|exit-code-laundered|NOT_VERIFIED \(ambiguous\)/;
+const HARD_BLOCK = /contradicts evidence\.json|caught false-completion|evidence verdict:|evidence check .+ status:|critique status|critique open|required sidecar is missing|command-log integrity check FAILED|gate misconfiguration:|exit-code-laundered|NOT_VERIFIED \(ambiguous\)|canonical Flow (?:run remains active|state is unsafe or malformed)/;
 // FULL_BLOCK adds: workflow-state hygiene, surface-unavailable fail-closed, missing log.
 const FULL_BLOCK = /status:|Definition Of Done|Goal Fit|sidecar validation:|contradicts evidence\.json|workflow state|evidence verdict|evidence check|NOT_VERIFIED gap|critique status|critique open|next action|caught false-completion|NOT_VERIFIED —|command-log integrity check FAILED|gate misconfiguration:|surface unavailable —|expected capture log is missing|exit-code-laundered|malformed-evidence|NOT_VERIFIED \(ambiguous\)/;
 
@@ -1897,7 +1928,31 @@ async function analyze(root, now = Date.now()) {
     artifacts = artifacts.filter(a => a && hasSidecarPresence(path.dirname(a.file)));
   }
 
-  if (artifacts.length === 0) return { warnings: [], blocking: false, latestArtifactDir: null };
+  const scopedCanonicalFlow = canonicalFlowState(root, scoped);
+  const scopedState = scoped ? readJsonFile(path.join(scoped, 'state.json')) : null;
+  const scopedProjectedActive = Boolean(scopedState && scopedState.flow_run && normalizedStatus(scopedState.flow_run.status) === 'active');
+  if (scopedProjectedActive && scopedCanonicalFlow.error) {
+    return {
+      warnings: [`workflow state: canonical Flow state is unsafe or malformed for the active scoped session: ${scopedCanonicalFlow.error}. Resolve the canonical run before stopping.`],
+      blocking: true,
+      activeFlowRun: true,
+      latestArtifactDir: scoped,
+      gatePrefix: '[stop-gate]',
+    };
+  }
+  if (artifacts.length === 0) {
+    if (normalizedStatus(scopedCanonicalFlow.state?.status) === 'active') {
+      const activeStep = safeOneLine(scopedCanonicalFlow.state.current_step || 'unknown', 80);
+      return {
+        warnings: [`workflow state: canonical Flow run remains active at step ${activeStep}; complete or explicitly cancel the run before stopping.`],
+        blocking: true,
+        activeFlowRun: true,
+        latestArtifactDir: scoped,
+        gatePrefix: '[stop-gate]',
+      };
+    }
+    return { warnings: [], blocking: false, activeFlowRun: false, latestArtifactDir: null };
+  }
 
   const latest = artifacts[0];
   const latestArtifactDir = path.dirname(latest.file);
@@ -1965,14 +2020,25 @@ async function analyze(root, now = Date.now()) {
   // Use module-scope HARD_BLOCK / FULL_BLOCK (defined above analyze()).
   // pre-execution/terminal tasks: only HARD_BLOCK signals cause a block.
   // execution-onward tasks: FULL_BLOCK signals cause a block.
-  const activeFlowRun = gateState && gateState.flow_run && normalizedStatus(gateState.flow_run.status) === 'active';
+  const canonicalFlow = canonicalFlowState(root, latestArtifactDir);
+  const activeProjectedFlow = gateState && gateState.flow_run && normalizedStatus(gateState.flow_run.status) === 'active';
+  const unsafeActiveCanonical = Boolean(activeProjectedFlow && canonicalFlow.error);
+  if (unsafeActiveCanonical) {
+    warnings.push(`workflow state: canonical Flow state is unsafe or malformed for the active scoped session: ${canonicalFlow.error}. Resolve the canonical run before stopping.`);
+  }
+  const activeFlowRun = normalizedStatus(canonicalFlow.state?.status) === 'active'
+    || (gateState && gateState.flow_run && normalizedStatus(gateState.flow_run.status) === 'active');
+  if (activeFlowRun && !warnings.some(w => /canonical Flow run remains active/.test(w))) {
+    const activeStep = safeOneLine(canonicalFlow.state?.current_step || gateState?.flow_run?.current_step || 'unknown', 80);
+    warnings.push(`workflow state: canonical Flow run remains active at step ${activeStep}; complete or explicitly cancel the run before stopping.`);
+  }
   const blockRe = ((preExecution && !activeFlowRun) || terminal) ? HARD_BLOCK : FULL_BLOCK;
-  const blocking = warnings.some(w => {
+  const blocking = activeFlowRun || warnings.some(w => {
     // Capture cross-reference warn-mode notes never block (operator opted out).
     if (/\[backstop in warn mode — not blocking\]/.test(w)) return false;
     return blockRe.test(w);
   });
-  return { warnings, blocking, preExecution, gatePrefix: gateLabel(activeFlowStep), latestArtifactDir };
+  return { warnings, blocking, activeFlowRun, preExecution, gatePrefix: gateLabel(activeFlowStep), latestArtifactDir };
 }
 
 /**
@@ -2220,8 +2286,9 @@ function releaseOnNonTerminalStop(root, artifactDir) {
 
     const state = readJsonFile(path.join(artifactDir, 'state.json'));
     if (!state) return; // AC5: no state.json — nothing to gate a release decision on.
-    if (state.flow_run && normalizedStatus(state.flow_run.status) === 'active') {
-      process.stderr.write(`[Hook] Goal Fit: stop-hook release skipped for active Flow run "${safeOneLine(state.flow_run.run_id || state.task_slug || 'unknown', 80)}"; continuation remains governed by Flow state.\n`);
+    const canonicalFlow = canonicalFlowState(root, artifactDir);
+    if (normalizedStatus(canonicalFlow.state?.status) === 'active' || (state.flow_run && normalizedStatus(state.flow_run.status) === 'active')) {
+      process.stderr.write(`[Hook] Goal Fit: stop-hook release skipped for active Flow run "${safeOneLine(state.flow_run?.run_id || state.task_slug || path.basename(artifactDir), 80)}"; continuation remains governed by Flow state.\n`);
       return;
     }
 
@@ -2367,7 +2434,7 @@ async function run(rawInput) {
     // with runtime-constructed paths or by modifying the warning
     // text so the hash changes. The real anchor is external (signed checkpoints + human
     // review). This raises the cost of the burn-through-the-counter escape vector.
-    const isHardBlock = result.warnings.some(w => {
+    const isHardBlock = result.activeFlowRun || result.warnings.some(w => {
       if (/\[backstop in warn mode — not blocking\]/.test(w)) return false;
       return HARD_BLOCK.test(w);
     });
@@ -2375,7 +2442,9 @@ async function run(rawInput) {
       // Do NOT clear the streak — keep accumulating so the same hard block stays visible.
       return {
         stdout: rawInput,
-        stderr: `${message}\n${gatePrefix} max-blocks reached but the block is a caught false-completion / integrity failure — not auto-releasing; requires a real fix or operator override.`,
+        stderr: result.activeFlowRun
+          ? `${message}\n${gatePrefix} max-blocks reached but canonical Flow remains active — not auto-releasing; complete or explicitly cancel the run.`
+          : `${message}\n${gatePrefix} max-blocks reached but the block is a caught false-completion / integrity failure — not auto-releasing; requires a real fix or operator override.`,
         exitCode: 2,
       };
     }

package/docs/context-map.md

@@ -40,8 +40,10 @@ Generated by `npm run context-map`. Regenerate after changing agents, skills, sc
 | Static suite | bash evals/run.sh static |
 | Integration suite | bash evals/run.sh integration |
 | Workflow artifacts | npm run workflow:validate-artifacts -- --require-sidecars --require-critique .kontourai/flow-agents/<slug> |
-| Workflow sidecars | npm run workflow:sidecar -- --help |
-| Claim lookup | npm run workflow:sidecar -- claim <id> <dir> |
+| Workflow control | flow-agents workflow --help |
+| Workflow status | flow-agents workflow status --session-dir .kontourai/flow-agents/<slug> --json |
+| Workflow critique | flow-agents workflow critique --session-dir .kontourai/flow-agents/<slug> --verdict <pass|fail|not_verified> --summary <text> |
+| Workflow verification | flow-agents workflow evidence --session-dir .kontourai/flow-agents/<slug> --expectation tests-evidence --status <pass|fail|not_verified> --command "bash evals/static/test_builder_skill_coherence.sh" --criterion-json '{"id":"AC-1","status":"pass","evidence_refs":[{"kind":"command","excerpt":"bash evals/static/test_builder_skill_coherence.sh","summary":"Exact substantive command run for AC-1."}]}' --evidence-ref-json '{"kind":"artifact","file":".kontourai/flow-agents/<slug>/<slug>--plan-work.md","summary":"Reviewable criterion mapping."}' |
 | Context map drift | npm run context-map:check |
 | Bundle build | npm run build:bundles |
 | Skill drift check | flow-agents skill-drift-check |
@@ -66,26 +68,26 @@ Machine-readable workflow state lives beside Markdown artifacts in `.kontourai/f
 | workflow-release.schema.json | Flow Agents Workflow Release Readiness | https://flow-agents.dev/schemas/workflow-release.schema.json |
 | workflow-state.schema.json | Flow Agents Workflow State | https://flow-agents.dev/schemas/workflow-state.schema.json |
 
-Primary tools: `npm run workflow:sidecar`, `npm run workflow:validate-artifacts`, `scripts/hooks/stop-goal-fit.js`, and `scripts/hooks/workflow-steering.js`.
+Primary tools: public `flow-agents workflow`, `trust.bundle`, artifact validation, `scripts/hooks/stop-goal-fit.js`, and `scripts/hooks/workflow-steering.js`. The package-internal writer is not an agent or consumer interface.
 
 ## Workflow Skills
 
 | Skill | Source | When To Load |
 | --- | --- | --- |
-| continue-work | kits/builder/skills/continue-work/SKILL.md | 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... |
-| deliver | kits/builder/skills/deliver/SKILL.md | Delivery workflow — selected work to delivered code. Ensures pull-work + pickup-probe preflight, then chains plan-work → execute-plan → review-work → verify-work → loop on failure without requiring user interaction between cleanly determ... |
-| evidence-gate | kits/builder/skills/evidence-gate/SKILL.md | Evaluate whether completed work is trustworthy enough for human review, merge, or release. Use after implementation, verify-work, provider checks, CI, or remediation to map acceptance criteria to evidence, inspect scope integrity, classi... |
-| execute-plan | kits/builder/skills/execute-plan/SKILL.md | Parallel execution primitive — plan artifact path to implemented code via tool-worker (x4). Reads plan directly. Updates session file between waves. |
-| fix-bug | kits/builder/skills/fix-bug/SKILL.md | Bug fix orchestrator — diagnose → plan-work → execute-plan → review-work → verify-work → loop. Diagnosis phase is unique to bugs, then chains the same primitives. |
-| gate-review | kits/builder/skills/gate-review/SKILL.md | 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, a... |
-| idea-to-backlog | kits/builder/skills/idea-to-backlog/SKILL.md | 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 befor... |
-| learning-review | kits/builder/skills/learning-review/SKILL.md | 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... |
-| plan-work | kits/builder/skills/plan-work/SKILL.md | Code planning primitive — goal + directory to structured execution plan. Delegates to tool-planner. No resume, no ideation. |
-| pull-work | kits/builder/skills/pull-work/SKILL.md | Select ready GitHub issues from the executable backlog and prepare them for implementation. Use when choosing what to work on next, reviewing a kanban-style issue board, enforcing WIP limits, grouping issues, deciding worktree isolation,... |
-| release-readiness | kits/builder/skills/release-readiness/SKILL.md | Decide whether evidence-backed work is ready to merge, release, deploy, or hold. Use after evidence-gate PASS, before merge/release/deploy, and for post-deploy verification planning. |
-| review-work | kits/builder/skills/review-work/SKILL.md | Review primitive - run report-only code, security, dependency, architecture/standards, and IaC/policy critique before verification; records findings through the critique artifact/sink, currently critique.json locally. |
-| tdd-workflow | kits/builder/skills/tdd-workflow/SKILL.md | Test-driven development — RED → GREEN → REFACTOR with git checkpoints. Wraps plan-work → execute-plan → review-work → verify-work with test-first constraints and coverage gates. |
-| verify-work | kits/builder/skills/verify-work/SKILL.md | Verification primitive — session file path to structured evidence verdict via tool-verifier + tool-playwright. Reads acceptance criteria from plan artifact. |
+| continue-work | kits/builder/skills/continue-work/SKILL.md | Explicit Builder Kit continuation extension. Prepares a fresh-context handoff for the next unfinished increment of a multi-slice Work Item. |
+| deliver | kits/builder/skills/deliver/SKILL.md | Builder Kit build entrypoint. Starts or continues a selected Work Item through builder.build by composing the build primitives without owning their step evidence. |
+| evidence-gate | kits/builder/skills/evidence-gate/SKILL.md | Assess whether verification evidence and scope integrity support merge review. Produces a confidence report and Builder merge-readiness evidence. |
+| execute-plan | kits/builder/skills/execute-plan/SKILL.md | Execution primitive that turns a structured plan into implemented scope through tool-worker delegation. |
+| fix-bug | kits/builder/skills/fix-bug/SKILL.md | Bug-fix profile for builder.build. Adds disciplined diagnosis and regression-focused verification without replacing the build primitives. |
+| gate-review | kits/builder/skills/gate-review/SKILL.md | Explicit advisory extension for reviewing apparent workflow gate blocks or misses from a completed trust bundle. |
+| idea-to-backlog | kits/builder/skills/idea-to-backlog/SKILL.md | Turn raw product or technical ideas into a shaped, prioritized, provider-neutral executable backlog before implementation starts. |
+| learning-review | kits/builder/skills/learning-review/SKILL.md | Capture delivery decisions, outcomes, and routed follow-up. Records Builder publish-learn learning evidence in trust.bundle. |
+| plan-work | kits/builder/skills/plan-work/SKILL.md | Code planning primitive that turns a goal and directory into a structured implementation plan. |
+| pull-work | kits/builder/skills/pull-work/SKILL.md | Select ready provider-backed work and prepare a bounded implementation handoff. |
+| release-readiness | kits/builder/skills/release-readiness/SKILL.md | Make a provider-neutral merge, release, deploy, or hold decision. Records Builder publish-learn CI merge-readiness in trust.bundle. |
+| review-work | kits/builder/skills/review-work/SKILL.md | Report-only critique before Builder verification. Records a critique slice through the public workflow interface without claiming Flow completion. |
+| tdd-workflow | kits/builder/skills/tdd-workflow/SKILL.md | Test-first profile for builder.build. Requires observable RED, GREEN, and appropriate REFACTOR evidence through the standard build primitives. |
+| verify-work | kits/builder/skills/verify-work/SKILL.md | Report-only acceptance verification. Records command-backed Builder verification evidence in trust.bundle when bound to an active run. |
 
 ## Support Skills
 
@@ -93,14 +95,14 @@ Primary tools: `npm run workflow:sidecar`, `npm run workflow:validate-artifacts`
 | --- | --- | --- |
 | agentic-engineering | skills/agentic-engineering/SKILL.md | Eval-first execution, task decomposition, and cost-aware model routing for AI-driven development workflows. |
 | browser-test | skills/browser-test/SKILL.md | Headless browser automation via Playwright — screenshots, accessibility checks, form filling, UI testing, DOM inspection. |
-| builder-shape | kits/builder/skills/builder-shape/SKILL.md | Invoke Builder Kit shape from a raw idea or the current conversation context without requiring the user to name idea-to-backlog. Delegates shaping to idea-to-backlog, records the Builder Kit Flow Definition link, and stops at the backlog... |
+| builder-shape | kits/builder/skills/builder-shape/SKILL.md | Builder Kit shaping entrypoint. Turns a raw idea into a provider-neutral, reviewable backlog proposal and stops before build selection unless the user explicitly continues. |
 | dependency-update | skills/dependency-update/SKILL.md | Analyze and upgrade project dependencies — latest versions, security vulnerabilities, actionable update plan across all package managers. |
-| design-probe | kits/builder/skills/design-probe/SKILL.md | Generic one-question-at-a-time design probing interview for turning unclear goals, designs, or workflow states into shared understanding before planning or execution. |
+| design-probe | kits/builder/skills/design-probe/SKILL.md | Generic one-question-at-a-time design probe for turning unclear goals, designs, and handoffs into shared understanding. |
 | eval-rebuild | skills/eval-rebuild/SKILL.md | Project-specific build and install commands for the eval feedback loop. Injected into eval-builder agent. Replace this skill for different build systems. |
 | exemption-usage-review | kits/veritas-governance/skills/exemption-usage-review/SKILL.md | Periodic audit of standing delivery/DECLARED no-agent-delivery exemptions (ADR 0022 §3): lists every current exemption's scope, reason, approver, and age since declared_at, flags entries overdue for owner re-confirmation against a config... |
 | github-cli | skills/github-cli/SKILL.md | Interact with GitHub via gh CLI — PRs, issues, repos, releases, workflows, gists. |
 | knowledge-capture | kits/knowledge/skills/knowledge-capture/SKILL.md | Save durable knowledge, lightweight pointers, user corrections, decisions, lessons, relationship context, or source references into the knowledge base. Use when the user says save, remember, capture, file this, bookmark context, or when... |
-| pickup-probe | kits/builder/skills/pickup-probe/SKILL.md | Builder Kit work-item/docs/provider-grounded Probe specialization used at the design-probe flow step before plan-work. |
+| pickup-probe | kits/builder/skills/pickup-probe/SKILL.md | Provider-grounded pickup probe used at the Builder design-probe step before planning. |
 | search-first | skills/search-first/SKILL.md | Research-before-coding workflow. Search for existing tools, libraries, and patterns before writing custom code. |
 
 ## Agents

package/docs/developer-architecture.md

@@ -108,7 +108,7 @@ flowchart TB
 
 **Current state:** The durable handoff surface is a pair of human-readable Markdown artifacts and machine-readable JSON sidecars under `.kontourai/flow-agents/<slug>/`. Verification, critique, release, and learning records are explicit artifacts rather than hidden chat memory.
 
-**Programmatic API (for native hosts):** The canonical sidecar writer/validator is importable as a library, not only via the `flow-agents-workflow-sidecar` CLI. A host that records workflow evidence natively should import the package root rather than reimplement validated read / merge / write:
+**Programmatic API (for native hosts):** The canonical Builder runtime and sidecar writer/validator remain importable from the package root so a native host does not reimplement validated workflow mutation. Agent-facing Kit guidance uses the public `flow-agents workflow` command so gate ownership, assignment checks, command observation, and projection happen through one portable interface:
 
 ```js
 import {

package/docs/getting-started.md

@@ -30,7 +30,15 @@ For a normal Codex global install, target the Codex home instead of a project wo
 npx @kontourai/flow-agents init --runtime codex --global --activate-kits --yes
 ```
 
-That installs into `CODEX_HOME` when it is set, otherwise `~/.codex`. Use `--dest /path/to/codex-home` only when you need an explicit override for an isolated install, CI fixture, or test.
+That splits installation by ownership: Codex-only runtime assets go into `CODEX_HOME` when set (otherwise `~/.codex`), while portable skills go into Codex's documented user catalog at `$HOME/.agents/skills`. A repository bundle install similarly exposes skills at `<repo>/.agents/skills`.
+
+Pass a positional runtime destination and `--skills-dir PATH` when both roots must be isolated, or set `FLOW_AGENTS_SKILLS_DIR` for headless environments:
+
+```bash
+bash scripts/install-codex-home.sh /tmp/codex-home --skills-dir /tmp/agents/skills
+```
+
+Installer output reports both destinations. Reinstall preserves unknown user skills and migrates only unchanged Flow Agents-owned files from the former `CODEX_HOME/skills` layout; modified legacy content is retained. Flow Agents intentionally does not create a compatibility symlink because the Codex runtime home must not own or mask a universal user catalog, and the installer refuses to write through symlinked destinations.
 
 Keep generated Codex base config lean. Put profile-specific model, provider, and approval settings in separate `<profile>.config.toml` files and select them with `codex --profile <name>`.
 

package/docs/public-workflow-cli.md

@@ -13,26 +13,93 @@ flow_agents() (
   root=$(mktemp -d) || exit 1
   trap 'rm -rf "$root"' EXIT HUP INT TERM
   npm exec --yes --prefix "$root" \
-    --package=@kontourai/flow-agents@3.5.0 -- flow-agents "$@"
+    --package=@kontourai/flow-agents@3.6.0 -- flow-agents "$@"
 )
 
 flow_agents workflow start \
   --flow builder.build \
-  --work-item owner/repository#123
+  --work-item provider:work-item-123 \
+  --assignment-provider example-provider \
+  --effective-state-json .kontourai/flow-agents/provider-assignment.json
 
 flow_agents workflow status --json
 
 flow_agents workflow evidence \
+  --session-dir .kontourai/flow-agents/example \
   --expectation implementation-plan \
   --status pass \
   --summary "Implementation plan recorded." \
-  --evidence-ref-json '{"kind":"artifact","file":".kontourai/flow-agents/example/example--plan.md"}'
+  --evidence-ref-json '{"kind":"artifact","file":".kontourai/flow-agents/example/example--plan-work.md","summary":"Reviewed implementation plan with Definition Of Done and task-to-criterion mapping."}' \
+  --evidence-ref-json '{"kind":"artifact","file":".kontourai/flow-agents/example/acceptance.json","summary":"Stable acceptance criteria and required evidence."}' \
+  --evidence-ref-json '{"kind":"artifact","file":".kontourai/flow-agents/example/handoff.json","summary":"Execution handoff and next action."}'
+
+flow_agents workflow critique \
+  --session-dir .kontourai/flow-agents/example \
+  --verdict pass \
+  --summary "Report-only review found no blocking findings." \
+  --artifact-ref ".kontourai/flow-agents/example/example--deliver.md" \
+  --lane-json '{"id":"code-review","status":"pass","summary":"The delivered implementation was reviewed.","evidence_refs":[{"kind":"artifact","file":".kontourai/flow-agents/example/example--deliver.md","summary":"Reviewed delivery report and changed scope."}]}'
+```
+
+`builder.build` accepts the stable, human-readable Work Item reference emitted by the selected
+provider adapter. Flow Agents persists that exact reference as the run subject; it does not infer
+provider identity from a GitHub-shaped string. Pass the resolved `--assignment-provider`; non-local
+providers also pass their standard assignment status result through `--effective-state-json`.
+Flow Agents verifies that the current actor is the confirmed holder, retains that provider result
+as selected-work evidence, and creates a local runtime lease mirror for atomic session mutation.
+A direct local request can resume an existing bound session, but the public CLI does not invent a
+provider or create an unresolvable local binding.
+
+`builder.shape` uses a caller-supplied, safe slug. Derive it from a selected
+title using lowercase ASCII words separated by single hyphens. Never inject raw
+request text into a shell command or use it as a slug:
+
+```bash
+flow_agents workflow start --flow builder.shape \
+  --task-slug onboarding-alerts \
+  --summary "Shape onboarding alerts into independently actionable slices."
+flow_agents workflow status --session-dir .kontourai/flow-agents/onboarding-alerts --json
+```
+
+For `tests-evidence`, supply one criterion object for every accepted criterion
+and one or more substantive commands that were actually run. Repeat `--command`
+when criteria require different checks. Every command needs a matching
+top-level command reference, and every passing criterion must cite at least one
+of those exact commands. A passing observation must also report a positive executed-test or
+assertion count; a successful zero-test run is rejected. Do not use placeholders such as `true`
+or a version command as behavior proof:
+
+```bash
+flow_agents workflow evidence \
+  --session-dir .kontourai/flow-agents/example \
+  --expectation tests-evidence \
+  --status pass \
+  --command "npm test" \
+  --summary "The project test command passed for the implemented criterion." \
+  --evidence-ref-json '{"kind":"command","excerpt":"npm test","summary":"Exact substantive project test command recorded for this verification result."}' \
+  --criterion-json '{"id":"<criterion-id>","status":"pass","evidence_refs":[{"kind":"command","excerpt":"npm test","summary":"Exact substantive project test command run for this criterion."}]}' \
+  --evidence-ref-json '{"kind":"artifact","file":".kontourai/flow-agents/example/example--plan-work.md","summary":"Accepted criterion and verification mapping."}'
 ```
 
 The public lifecycle verbs are `pause`, `resume`, `release`, `cancel`, and `archive`. Pause,
-resume, and release require the current assignment actor and an explicit reason. Cancel and
+resume, and release require the current assignment actor and an explicit reason. `critique`
+records the `clean-critique` claim but does not independently attach it to Flow or advance a gate. Cancel and
 archive require a signed user/operator authorization file. Flow owns the canonical run
 transition; Flow Agents validates assignment and request binding and projects the resulting run.
+Critique derives reviewer identity from the calling runtime actor. An active
+implementation assignment is required, and its actor cannot review its own
+work; the delegated reviewer invokes the command directly under a distinct
+identity. The public interface does not accept a caller-selected reviewer
+label. Every critique includes an explicit verdict, at least one substantive
+`--lane-json`, and local reviewed `--artifact-ref` values. Passing critiques
+require every lane to pass; reviewed files and the workspace snapshot are
+hashed into the stored review target so later implementation changes invalidate
+stale clean critiques.
+
+Current local runtime actor IDs provide coordination-level separation, not a
+cryptographic identity guarantee. A policy that requires externally attested
+reviewer identity must keep that assurance `NOT_VERIFIED` until the runtime
+supplies a trusted delegation credential.
 
 ```bash
 flow_agents workflow pause --reason "Waiting for a decision"
@@ -43,7 +110,8 @@ flow_agents workflow archive --authorization-file archive.json
 ```
 
 `workflow status` is read-only. It reads the actor-scoped current-session pointer, the projected
-state, and the canonical Flow run without rewriting either store.
+state, and the canonical Flow run without rewriting either store. Its `next_action` is freshly
+derived from the canonical run, so a stale sidecar projection cannot misdirect recovery.
 
 ## Compatibility Doctor
 
@@ -59,5 +127,6 @@ Flow runtime and definition, workflow-state schema, and trust-bundle schema. Inc
 missing installed components produce a nonzero exit and an exact, version-pinned `init` command
 that preserves the recorded runtime and active Kits.
 
-The `flow-agents-workflow-sidecar` binary is deprecated and retained only while package-internal
-callers migrate. New consumer guidance must use `flow-agents workflow`.
+The package may use lower-level writer modules internally. They are not a
+supported consumer or skill surface. Consumer guidance and Builder skills use
+`flow-agents workflow` exclusively.

package/docs/skills-map.md

@@ -8,13 +8,39 @@ This map groups the current skills by the user journey they support. The Builder
 
 For practical operator instructions and copy/paste prompts, see https://github.com/kontourai/flow-agents/blob/main/docs/workflow-usage-guide.md. For the shared cross-distribution contracts behind the workflow artifacts and gates, see https://github.com/kontourai/flow-agents/blob/main/docs/workflow-shared-contracts.md.
 
+## Builder Skill Roles
+
+`kits/builder/kit.json` is the machine-readable source for skill activation.
+Flow Definitions own step order, gates, route-backs, and trust expectations;
+the role matrix only maps each skill to that Flow-owned behavior.
+
+| Role | Skills | Activation |
+| --- | --- | --- |
+| Entrypoint | `builder-shape`, `deliver` | User selects the Builder product workflow; the skill coordinates but owns no step evidence. |
+| Profile | `fix-bug`, `tdd-workflow` | Explicit workflow variant; never selected as an automatic step action. |
+| Step producer | `idea-to-backlog`, `pull-work`, `pickup-probe`, `plan-work`, `execute-plan`, `review-work`, `verify-work`, `evidence-gate`, `release-readiness`, `learning-review` | Activated only for its declared Flow step; publishes only its declared expectations. |
+| Shared primitive | `design-probe` | Reused interview behavior with no Builder expectation ownership. |
+| Extension | `continue-work`, `gate-review` | Explicit continuation or retrospective operation outside automatic step actions. |
+
+Within the active `verify` step, `review-work` owns `clean-critique`: it records
+a report-only critique slice in `trust.bundle`. `verify-work` owns
+`acceptance-criteria`, `tests-evidence`, and applicable `policy-compliance`
+through command-backed behavior evidence. Use the public `flow-agents workflow`
+CLI for run status, evidence, and critique; skills must not call the
+package-internal writer directly.
+
+`builder.build` accepts exactly two public Work Item reference forms:
+`provider:id` and `owner/repo#numeric-id`. The latter is the GitHub-compatible
+adapter form; GitHub remains an optional adapter example. Do not invent
+arbitrary reference formats.
+
 - `builder-shape`: product-level Builder Kit shape invocation that guides `idea-to-backlog` without requiring the user to name the primitive, links `kits/builder/flows/shape.flow.json`, and stops at the backlog gate unless issue sync is explicit.
-- `idea-to-backlog`: discovery, idea separation, thinnest meaningful slice, shaping, prioritization, and executable GitHub issue creation.
+- `idea-to-backlog`: discovery, idea separation, thinnest meaningful slice, shaping, prioritization, and executable provider-backed work items; GitHub is an optional adapter.
 - `pull-work`: dynamic backlog selection, grouping/dependency checks, WIP awareness, worktree decision, and execution handoff; in Builder Kit build, every selected item or justified group needs fresh pickup Probe evidence before planning.
 - `design-probe`: generic one-question-at-a-time probing interview; Builder Kit uses this step before planning when the build flow needs shared understanding or a pickup decision.
 - `pickup-probe`: Builder Kit specialization of `design-probe` for selected work items; records scope, provider state, WIP/conflict scans, risks, decisions, unresolved questions, accepted gaps, and planning readiness.
 - `plan-work` / `execute-plan` / `deliver`: Definition Of Done, execution orchestration, and local delivery closure.
-- `continue-work`: advance a multi-slice work item to its next increment via a fresh-context handoff; restores the durable record (resume surface), derives the next undone slice from the issue plus merged PRs, and routes that slice **through** `pull-work` + `pickup-probe` (never around the gate) before handing off fresh per ADR 0013.
+- `continue-work`: advance a multi-slice work item to its next increment via an ephemeral fresh-context handoff; derives the next undone slice from the Work Item plus completed changes, then routes it **through** `pull-work` + `pickup-probe` before handing off fresh per ADR 0013.
 - `review-work`: report-only critique for quality, security triggers, architecture fit, and standards findings.
 - `verify-work`: behavior evidence mapped to acceptance criteria and Goal Fit.
 - `evidence-gate`: trust assessment for completed work: acceptance evidence, integrity checks, CI confidence, and next step.
@@ -35,7 +61,7 @@ flowchart LR
   Publish[publish-change<br/>commit / push / PR / CI]
   Release[release-readiness<br/>merge / release / deploy / docs decision]
   Learn[learning-review<br/>route follow-ups]
-  Backlog[(GitHub issues)]
+  Backlog[(Provider-backed work items)]
 
   Idea --> Shape --> Backlog --> Pickup --> Probe --> Build --> Review --> Verify --> GoalFit --> Trust --> Publish --> Release --> Learn
   Probe -->|not needed| Build
@@ -58,8 +84,8 @@ The operating model now has first-class coverage from idea intake through truste
 - Design probing is a generic skill named `design-probe`; in the Builder Kit build flow the step is still named `design-probe`, and the `pickup-probe` specialization records selected-work readiness before planning. `decision_gap` route-backs return there for missing pickup/planning decisions.
 - Product-level Builder Kit build may guide `pull-work -> design-probe / pickup-probe -> plan-work`; direct primitives still stop at their own gates and report the expected next step.
 - Broad continuation language does not carry across newly selected work after merge. Queue inspection is allowed, but planning the next item requires a fresh pickup Probe record.
-- Critique is owned by `review-work` and persisted in `critique.json`.
-- Verification is owned by `verify-work` and persisted in `evidence.json`.
+- Critique is owned by `review-work` as `clean-critique`, recorded directly by a delegated reviewer whose runtime identity differs from the active implementation actor, and stored through public `workflow critique` in its `trust.bundle` slice before verification.
+- Verification is owned by `verify-work` as `acceptance-criteria`, `tests-evidence`, and applicable `policy-compliance`, recorded as command-backed `trust.bundle` evidence with one criterion JSON record for every accepted criterion.
 - Trust evidence is assessed by `evidence-gate`; it decides whether completed work has enough proof and integrity to publish or continue fixing.
 - Publishing verified changes is the bridge between evidence and release readiness: commit the verified diff, push the branch, open or update the PR, and collect PR/CI evidence.
 - Merge/release/deploy decisioning is owned by `release-readiness` after the publish-change gate.
@@ -80,18 +106,18 @@ This view shows how each phase is composed. The left rail is the durable phase s
     <div class="phase-step"><span>01</span><strong>Discovery & shaping</strong></div>
     <div class="phase-lanes">
       <section class="phase-lane phase-lane--primary"><h3>Primary</h3><p><code>builder-shape</code> <code>idea-to-backlog</code></p></section>
-      <section class="phase-lane"><h3>Support</h3><p><code>search-first</code> <code>explore</code> <code>frontend-design</code> <code>github-cli</code> <code>knowledge-capture</code></p></section>
+      <section class="phase-lane"><h3>Support</h3><p><code>search-first</code> <code>explore</code> <code>frontend-design</code> optional <code>github-cli</code> adapter <code>knowledge-capture</code></p></section>
       <section class="phase-lane"><h3>Nested sections / future primitives</h3><p>intake/dedupe, separate ideas, thinnest meaningful slice, opportunity review, explore options, <code>shape-work</code>, prioritize work, sync executable backlog</p></section>
-      <section class="phase-lane phase-lane--gate"><h3>Gate & artifact</h3><p>Idea, slice, shape, and backlog gates. Writes shaped briefs and GitHub issue links in <code>.kontourai/flow-agents/&lt;slug&gt;/</code>.</p></section>
+      <section class="phase-lane phase-lane--gate"><h3>Gate & artifact</h3><p>Idea, slice, shape, and backlog gates. Writes shaped briefs and provider work-item refs in <code>.kontourai/flow-agents/&lt;slug&gt;/</code>.</p></section>
     </div>
   </article>
   <article class="phase-row">
     <div class="phase-step"><span>02</span><strong>Backlog pickup</strong></div>
     <div class="phase-lanes">
       <section class="phase-lane phase-lane--primary"><h3>Primary</h3><p><code>pull-work</code></p></section>
-      <section class="phase-lane"><h3>Support</h3><p><code>github-cli</code></p></section>
+      <section class="phase-lane"><h3>Support</h3><p>optional <code>github-cli</code> adapter</p></section>
       <section class="phase-lane"><h3>Nested sections / future primitives</h3><p>board snapshot, WIP check, grouping/dependency check, pickup Probe decision, worktree decision, <code>plan-work</code> handoff</p></section>
-      <section class="phase-lane phase-lane--gate"><h3>Gate & artifact</h3><p>Pickup gate and pickup Probe handoff. Writes selected issues, blockers, bundle justification, provider state, accepted gaps, worktree policy, expected modified files, conflict risks, and handoff notes.</p></section>
+      <section class="phase-lane phase-lane--gate"><h3>Gate & artifact</h3><p>Pickup gate and pickup Probe handoff. Writes selected work items, blockers, bundle justification, provider state, accepted gaps, worktree policy, expected modified files, conflict risks, and handoff notes.</p></section>
     </div>
   </article>
   <article class="phase-row">
@@ -107,9 +133,9 @@ This view shows how each phase is composed. The left rail is the durable phase s
     <div class="phase-step"><span>04</span><strong>Evidence & release</strong></div>
     <div class="phase-lanes">
       <section class="phase-lane phase-lane--primary"><h3>Primary</h3><p><code>evidence-gate</code> <code>release-readiness</code></p></section>
-      <section class="phase-lane"><h3>Support</h3><p><code>github-cli</code> <code>eval-rebuild</code></p></section>
+      <section class="phase-lane"><h3>Support</h3><p>optional <code>github-cli</code> adapter <code>eval-rebuild</code></p></section>
       <section class="phase-lane"><h3>Nested sections / future primitives</h3><p>criteria-to-evidence map, CI confidence, <code>scope-and-integrity-check</code>, publish-change, rollback review, observability review, post-deploy plan, final acceptance docs, remediate-ci</p></section>
-      <section class="phase-lane phase-lane--gate"><h3>Gate & artifact</h3><p>Evidence, publish-change, release, and docs gates. Writes confidence, integrity, commit/branch/PR/CI links, release scope, risk, rollback, deploy-readiness decisions, and durable documentation links.</p></section>
+      <section class="phase-lane phase-lane--gate"><h3>Gate & artifact</h3><p>Evidence, publish-change, release, and docs gates. Writes confidence, integrity, commit/branch/provider-change/CI links, release scope, risk, rollback, deploy-readiness decisions, and durable documentation links.</p></section>
     </div>
   </article>
   <article class="phase-row">
@@ -125,10 +151,10 @@ This view shows how each phase is composed. The left rail is the durable phase s
 
 | Phase | Primary workflow skill | Supporting skills | Nested sections / future primitive candidates |
 | --- | --- | --- | --- |
-| Idea discovery and shaping | `builder-shape`, `idea-to-backlog` | `search-first`, `explore`, `frontend-design`, `github-cli`, `knowledge-capture` | intake/dedupe, separate ideas, thinnest meaningful slice, opportunity review, explore options, shape work, prioritize work, sync executable backlog |
-| Backlog pickup | `pull-work` | `github-cli` | board snapshot, WIP check, grouping/dependency check, Probe decision, worktree decision, handoff |
+| Idea discovery and shaping | `builder-shape`, `idea-to-backlog` | `search-first`, `explore`, `frontend-design`, optional `github-cli` adapter, `knowledge-capture` | intake/dedupe, separate ideas, thinnest meaningful slice, opportunity review, explore options, shape work, prioritize work, sync executable backlog |
+| Backlog pickup | `pull-work` | optional `github-cli` adapter | board snapshot, WIP check, grouping/dependency check, Probe decision, worktree decision, handoff |
 | Execution planning and build | `design-probe`, `pickup-probe`, `plan-work`, `execute-plan`, `review-work`, `verify-work` | `feedback-loop`, `browser-test`, `deliver`, `fix-bug`, `tdd-workflow` | Probe notes, Builder Kit Probe record, Definition Of Done, execution plan, parallel waves, implementation session state, critique report, verification report, Goal Fit Gate |
-| Evidence and release confidence | `evidence-gate`, `release-readiness` | `github-cli`, `eval-rebuild` | criteria-to-evidence map, CI confidence, scope/integrity check, publish-change, rollback review, observability review, final acceptance docs, post-deploy plan |
+| Evidence and release confidence | `evidence-gate`, `release-readiness` | optional `github-cli` adapter, `eval-rebuild` | criteria-to-evidence map, CI confidence, scope/integrity check, publish-change, rollback review, observability review, final acceptance docs, post-deploy plan |
 | Learning and improvement | `learning-review` | `knowledge-capture`, `idea-to-backlog`, `eval-rebuild` | facts vs interpretation, docs promotion review, follow-up routing, knowledge updates, eval/skill/backlog improvements |
 
 The highest-leverage future extractions are likely `shape-work`, `test-map`, `scope-and-integrity-check`, and `remediate-ci`. They are still nested because their behavior is present, but not yet large enough to need separate activation contracts.
@@ -137,28 +163,26 @@ The highest-leverage future extractions are likely `shape-work`, `test-map`, `sc
 
 Each workflow phase ends with an explicit gate and durable artifact:
 
-- `builder-shape` invokes Builder Kit shape, delegates to `idea-to-backlog`, links `kits/builder/flows/shape.flow.json`, and writes the standard `.kontourai/flow-agents/<slug>/<slug>--idea-to-backlog.md` artifact.
-- `idea-to-backlog` writes `.kontourai/flow-agents/<slug>/<slug>--idea-to-backlog.md` and produces shaped briefs plus GitHub issue links.
-- `pull-work` writes `.kontourai/flow-agents/<slug>/<slug>--pull-work.md` with selected issues, WIP notes, blockers, pickup Probe decisions or accepted gaps, worktree decision, expected modified files, conflict risks, and a `plan-work` handoff.
-- `plan-work` and `deliver` write `.kontourai/flow-agents/<slug>/<slug>--*.md` artifacts with `Definition Of Done`, `Goal Fit Gate`, and `Final Acceptance` sections.
-- `review-work` writes reviewer artifacts when available and updates `critique.json` with quality, security, architecture, standards, and resolution state.
-- `verify-work` writes verification artifacts and updates `evidence.json` with behavior evidence mapped to acceptance criteria.
-- `evidence-gate` writes `.kontourai/flow-agents/<slug>/<slug>--evidence-gate.md` with acceptance evidence, CI summary, integrity report, verdict, and next step.
-- `release-readiness` writes `.kontourai/flow-agents/<slug>/<slug>--release-readiness.md` with release scope, evidence reference, risk review, operational plan, rollback plan, observability plan, post-deploy checks, and decision.
-- `learning-review` writes `.kontourai/flow-agents/<slug>/<slug>--learning-review.md` with outcomes, evidence, decisions, gaps, follow-ups, knowledge updates, and verdict.
+- `builder-shape` selects a safe-slugged public shape run and delegates to `idea-to-backlog`.
+- `idea-to-backlog` owns `<slug>--idea-to-backlog.md` and the `builder.shape` slices in `trust.bundle`.
+- `pull-work` and `pickup-probe` own the selected-work and Probe sections of `<slug>--pull-work.md` plus their `trust.bundle` slices.
+- `plan-work` owns `<slug>--plan-work.md`, `acceptance.json`, `handoff.json`, and its `trust.bundle` plan slice; `execute-plan` owns the session execution report, `state.json`, and its scope slice.
+- `review-work` records report-only critique through public `workflow critique` and owns `clean-critique`.
+- `verify-work` records command-backed `acceptance-criteria`, `tests-evidence`, and applicable `policy-compliance` evidence in `trust.bundle`.
+- `evidence-gate` owns `<slug>--evidence-gate.md`; `release-readiness` owns `release.json`; `learning-review` owns `learning.json`; each also records its declared `trust.bundle` slice.
 
 Core gates:
 
 - Idea Gate: raw input is deduped, classified, and routed.
 - Slice Gate: each candidate has one outcome, one thinnest meaningful slice, and explicit split/bundle/dependency reasoning.
 - Shape Gate: scope, non-goals, risk, rollout notes, and acceptance criteria are stable enough.
-- Backlog Gate: GitHub issues represent executable or near-executable work.
+- Backlog Gate: provider-backed work items represent executable or near-executable work; GitHub issues are an optional adapter example.
 - Pickup Gate: selected work is ready, WIP is acceptable, and worktree policy is recorded.
 - Review Gate: report-only reviewers have no open blocking findings, or findings are explicitly accepted/deferred/false positive.
 - Verification Gate: implementation evidence exists from local, automated, browser, or runtime checks.
 - Goal Fit Gate: the original user outcome is satisfied, gaps are explicit, and local/project/global scope is clear.
 - Evidence Gate: acceptance criteria are mapped to falsifiable evidence and scope integrity is checked.
-- Publish Change Gate: verified changes are committed, pushed, represented by a PR or explicit no-PR decision, and PR checks/CI are linked.
+- Publish Change Gate: verified changes are committed, pushed, represented by a provider change record or explicit no-provider-change decision, and available provider checks/CI are linked.
 - Release Gate: CI, docs, rollout, rollback, observability, and owner concerns are addressed for the risk class.
 - Docs Gate: accepted planning artifacts are archived and promoted into durable docs when useful.
 - Learning Gate: failures and recurring patterns are routed to tests, evals, skills, backlog, or knowledge capture.
@@ -169,7 +193,7 @@ Core gates:
 flowchart LR
   Idea[Idea / vague goal]
   BacklogSkill[idea-to-backlog]
-  Issue[Executable GitHub issue]
+  Issue[Executable provider-backed work item]
   Pull[pull-work]
   Probe[design-probe]
   Worktree[worktree decision]
@@ -203,7 +227,7 @@ Workflow evals are layered to match this map:
 
 - Static contract evals guard non-negotiable skill boundaries.
 - Behavioral activation evals check that agents choose the right workflow and stop at gates.
-- Artifact quality evals inspect durable session artifacts and GitHub issue drafts.
+- Artifact quality evals inspect durable session artifacts and provider work-item drafts; GitHub is an optional adapter example.
 - Adversarial evals exercise premature coding, vague issues, missing CI, weakened tests, and prototype promotion risks.
 - End-to-end evals cover `idea-to-backlog -> pull-work -> design-probe -> plan-work -> execute-plan -> review-work -> verify-work -> goal-fit -> evidence-gate` selectively.