@kontourai/flow-agents 3.5.0 → 3.7.0

package/context/contracts/artifact-contract.md

@@ -137,7 +137,7 @@ Canonical vocabulary:
 
 | Field | Values |
 | --- | --- |
-| `state.status` | `new`, `planning`, `planned`, `in_progress`, `blocked`, `verifying`, `verified`, `needs_decision`, `not_verified`, `failed`, `delivered`, `accepted`, `archived` |
+| `state.status` | `new`, `planning`, `planned`, `in_progress`, `blocked`, `verifying`, `verified`, `needs_decision`, `not_verified`, `failed`, `delivered`, `canceled`, `accepted`, `archived` |
 | `state.phase` | `idea`, `backlog`, `pickup`, `planning`, `execution`, `verification`, `goal_fit`, `evidence`, `release`, `learning`, `done` |
 | `next_action.status` | `continue`, `needs_user`, `blocked`, `done` |
 | `acceptance.criteria[].status` | `pending`, `pass`, `fail`, `not_verified`, `accepted_gap` |

package/context/scripts/hooks/config-protection.js

@@ -120,6 +120,13 @@ function checkProtectedPathPattern(filePath) {
     };
   }
 
+  if (/(?:^|\/)\.flow-agents\/lifecycle-authority-keys\.json$/.test(norm)) {
+    return {
+      name: '.flow-agents/lifecycle-authority-keys.json',
+      reason: 'an agent could replace the pinned lifecycle authority key and forge cancellation authority',
+    };
+  }
+
   // .kontourai/flow-agents/current.json — an agent could forge active_flow_id / active_step_id
   // to route the gate to a permissive or empty-expects FlowDefinition.
   // SAFE: the workflow CLI writes current.json via fs (writeJson → fs.writeFileSync),
@@ -426,7 +433,7 @@ function checkCommandForBypass(command) {
  */
 // #379: the delivery/ arms carry an optional (?:[^/]+\/)? segment so redirects/tee to the
 // per-session path delivery/<slug>/trust.bundle (+ checkpoint) are caught, not just the flat path.
-const REDIRECT_PROTECTED_RE = /(?:^|\/|~\/)(\.bash_profile|\.bashrc|\.profile|\.zprofile|\.zshrc)$|(?:^|\/)\.claude\/settings(?:\.local)?\.json$|(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/current\.json$|(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/current\/[^/]+\.json$|(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/\.goal-fit-block-streak\.json$|(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/[^/]+\/state\.json$|(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/[^/]+\/trust\.bundle$|(?:^|\/)delivery\/(?:[^/]+\/)?trust\.bundle$|(?:^|\/)delivery\/(?:[^/]+\/)?trust\.checkpoint\.json$/;
+const REDIRECT_PROTECTED_RE = /(?:^|\/|~\/)(\.bash_profile|\.bashrc|\.profile|\.zprofile|\.zshrc)$|(?:^|\/)\.claude\/settings(?:\.local)?\.json$|(?:^|\/)\.flow-agents\/lifecycle-authority-keys\.json$|(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/current\.json$|(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/current\/[^/]+\.json$|(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/\.goal-fit-block-streak\.json$|(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/[^/]+\/state\.json$|(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/[^/]+\/trust\.bundle$|(?:^|\/)delivery\/(?:[^/]+\/)?trust\.bundle$|(?:^|\/)delivery\/(?:[^/]+\/)?trust\.checkpoint\.json$/;
 
 /**
  * Return true when a token (an unquoted redirect target or tee argument) matches

package/context/scripts/hooks/lib/config-protection-remedies.js

@@ -20,6 +20,8 @@ const SANCTIONED_REMEDIES = {
     'There is no sanctioned automated writer for this file. Ask a human maintainer to edit it directly. Never disable this hook to make the write.',
   '.claude/settings.local.json':
     'There is no sanctioned automated writer for this file. Ask a human maintainer to edit it directly. Never disable this hook to make the write.',
+  '.flow-agents/lifecycle-authority-keys.json':
+    'Only the trusted harness installer or a human maintainer may rotate lifecycle authority keys. Never let an agent replace this trust root.',
   '.kontourai/flow-agents/current.json':
     'Use `npm run workflow:sidecar -- ensure-session` (or `advance-state`), which writes this file for you. Never disable this hook to make the write.',
   '.kontourai/flow-agents/current/<actor>.json':
@@ -58,6 +60,7 @@ function remedyFor(name) {
  * basename 'trust.bundle') -- first match wins, deterministically.
  */
 const REMEDY_COMMAND_CANDIDATES = [
+  { name: '.flow-agents/lifecycle-authority-keys.json', needles: ['lifecycle-authority-keys.json'] },
   { name: 'delivery/trust.checkpoint.json', needles: ['delivery/trust.checkpoint.json', 'trust.checkpoint.json'] },
   { name: 'delivery/trust.bundle', needles: ['delivery/trust.bundle'] },
   { name: '.kontourai/flow-agents/<slug>/trust.bundle', needles: ['trust.bundle'] },

package/context/scripts/hooks/lib/kit-catalog.js

@@ -137,7 +137,7 @@ function renderKitSteering(trigger) {
     else lines.push(`Activate \`${defaultSkill}\`.`);
   }
   if (targetFlowId) {
-    lines.push(`Keep the session on \`${targetFlowId}\` and use \`npm run workflow:sidecar -- ensure-session --flow-id ${targetFlowId} ...\` when the repo provides the sidecar writer.`);
+    lines.push(`Keep the session on \`${targetFlowId}\`. Use the public \`flow-agents workflow\` interface only when it supports that Flow and its Work Item binding; otherwise report an unsupported-runtime blocker. Never call the package-internal writer from skill guidance.`);
   }
   if (requiredSequence.length) {
     lines.push(`Do not bypass ${requiredSequence.join(' -> ')} for matching work.`);

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

@@ -77,7 +77,7 @@ const PRE_EXECUTION_PHASES = new Set(['idea', 'backlog', 'pickup', 'planning']);
 // Terminal tasks are complete — they must never gate a stop or count as "active".
 // A stale current.json pointing at one, or a graveyard of finished states, must
 // not block an unrelated session.
-const TERMINAL_STATUSES = new Set(['done', 'delivered', 'accepted', 'archived', 'complete', 'completed']);
+const TERMINAL_STATUSES = new Set(['done', 'delivered', 'canceled', 'accepted', 'archived', 'complete', 'completed']);
 
 function isTerminalDeliveredState(state) {
   if (!state || typeof state !== 'object') return false;
@@ -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 |
@@ -54,8 +56,10 @@ Machine-readable workflow state lives beside Markdown artifacts in `.kontourai/f
 | --- | --- | --- |
 | assignment-provider-settings.schema.json | Flow Agents Assignment Provider Settings | https://flow-agents.dev/schemas/assignment-provider-settings.schema.json |
 | backlog-provider-settings.schema.json | Flow Agents Backlog Provider Settings | https://flow-agents.dev/schemas/backlog-provider-settings.schema.json |
+| builder-lifecycle-authorization.schema.json | Builder Lifecycle Authorization | https://kontourai.dev/schemas/builder-lifecycle-authorization.schema.json |
 | decision-record.schema.json | Flow Agents Decision Record | https://flow-agents.dev/schemas/decision-record.schema.json |
 | flow-agents-settings.schema.json | Flow Agents Settings | https://flow-agents.dev/schemas/flow-agents-settings.schema.json |
+| lifecycle-authority-keys.schema.json | Lifecycle Authority Key Registry | https://kontourai.dev/schemas/lifecycle-authority-keys.schema.json |
 | workflow-acceptance.schema.json | Flow Agents Workflow Acceptance | https://flow-agents.dev/schemas/workflow-acceptance.schema.json |
 | workflow-critique.schema.json | Flow Agents Workflow Critique | https://flow-agents.dev/schemas/workflow-critique.schema.json |
 | workflow-evidence.schema.json | Flow Agents Workflow Evidence | https://flow-agents.dev/schemas/workflow-evidence.schema.json |
@@ -64,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
 
@@ -91,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/public-workflow-cli.md

@@ -0,0 +1,132 @@
+# Public Workflow CLI
+
+Flow Agents exposes its supported consumer workflow surface through the primary package binary.
+Consumer repositories do not need a `package.json`, a local dependency, or a repository-owned
+writer script.
+
+Use an exact package version from an isolated npm prefix. This prevents a repository-local
+dependency with the same version from intercepting the command. Generated workflow actions and
+doctor remediation include this isolation automatically:
+
+```bash
+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.6.0 -- flow-agents "$@"
+)
+
+flow_agents workflow start \
+  --flow builder.build \
+  --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-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. `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"
+flow_agents workflow resume --reason "Decision received"
+flow_agents workflow release --reason "Handing work back"
+flow_agents workflow cancel --authorization-file cancel.json
+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. Its `next_action` is freshly
+derived from the canonical run, so a stale sidecar projection cannot misdirect recovery.
+
+## Compatibility Doctor
+
+Run doctor through the exact isolated package helper defined above:
+
+```bash
+flow_agents workflow doctor --json
+```
+
+The report distinguishes the executing CLI from a repository-local dependency and reports the
+workflow/writer contract, installed hook and writer package, active Kits, Builder Kit content,
+Flow runtime and definition, workflow-state schema, and trust-bundle schema. Incompatible or
+missing installed components produce a nonzero exit and an exact, version-pinned `init` command
+that preserves the recorded runtime and active Kits.
+
+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.