@kontourai/flow-agents 3.6.0 → 3.7.0

package/kits/builder/skills/tdd-workflow/SKILL.md

@@ -1,159 +1,65 @@
 ---
 name: "tdd-workflow"
-description: "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."
+description: "Test-first profile for builder.build. Requires observable RED, GREEN, and appropriate REFACTOR evidence through the standard build primitives."
 ---
 
 # TDD Workflow
 
-Test-driven development orchestrator. Wraps the standard plan → execute → verify chain with test-first constraints.
+## Role and Boundary
 
-## When to Activate
+**Role:** test-first `builder.build` profile.
 
-- User says "use TDD", "test-driven", "write tests first", "TDD"
-- User asks to build something and mentions test coverage requirements
+Select this profile only when the user requests test-driven development or when
+the selected Work Item explicitly requires a test-first approach. It constrains
+the standard build primitives; it is not a separate flow and does not replace
+`deliver` as the build entrypoint.
 
-## Agents
-
-Same as deliver (inherited from primitives):
-
-| Agent | Used by |
-|---|---|
-| tool-planner | plan-work (with TDD constraints) |
-| tool-worker (x4) | execute-plan (tests first, then implementation) |
-| tool-code-reviewer | review-work |
-| tool-security-reviewer | review-work (conditional) |
-| tool-verifier | verify-work (with coverage check) |
-| tool-playwright | verify-work (if UI) |
+The profile owns **no step-gate evidence**. The plan, execution, review, and
+verification primitives own the artifacts and evidence for their respective
+steps.
 
 ## Model Routing
 
-Delegates are spawned with an explicit model override resolved from
-`.datum/config.json` via `npx @kontourai/datum resolve <role> --json` — see
-`context/contracts/execution-contract.md` § Delegation: Model Routing:
-
-| Delegate | Role |
-|---|---|
-| tool-worker | `delegate-mechanical` for fully-specified mechanical slices, `delegate-implementation` for precisely-planned implementation (RED/GREEN/REFACTOR), `delegate-design` when a slice needs design latitude |
-| tool-planner | `delegate-design` |
-| tool-code-reviewer / tool-security-reviewer | `delegate-implementation` by default, raised to the worker's tier when higher — never below the tier of the checked work (Goodhart guard) |
-| tool-verifier / tool-playwright | `delegate-implementation` by default, raised to the worker's tier when higher — never below the tier of the checked work (Goodhart guard) |
-
-On a review/verify gate failure, re-dispatch the fix one tier higher and record
-the escalation (contract § Escalation on gate failure). Fallback: inherit the
-session model when datum/config is absent, noted in the artifact.
-
-## Orchestrator Rule
-
-Same as deliver: you never touch source files. You coordinate the primitives with TDD-specific context.
-
-## Workflow
-
-### 1. Create session file
-
-Filename: `<branch>--tdd-<slug>.md`
-Set `status: planning`, `type: tdd`, `iteration: 0`
-
-### 2. Plan (plan-work with TDD constraint)
-
-Invoke plan-work with additional constraint:
-```
-Constraint: TEST-FIRST DEVELOPMENT
-- Plan MUST include test files as separate tasks in Wave 1
-- Each feature task must have a corresponding test task that precedes it
-- Test tasks specify: test file path, test cases to write, expected failures
-- Implementation tasks specify: which tests they make pass
-- Include a final "coverage check" task
-```
-
-Present plan to user. Get approval.
-
-### 3. Execute RED phase
-
-Invoke execute-plan for Wave 1 only (test tasks):
-- tool-worker writes test files
-- After Wave 1 completes, run the tests — they MUST fail (RED)
-- If tests pass (no RED state), the tests are wrong — flag to user
-- Git checkpoint: `test: add failing tests for <feature>`
-
-### 4. Execute GREEN phase
-
-Invoke execute-plan for Wave 2 (implementation tasks):
-- tool-worker writes minimal code to make tests pass
-- After Wave 2 completes, run the tests — they MUST pass (GREEN)
-- If tests still fail, loop: re-invoke execute-plan with failure context
-- Git checkpoint: `feat: implement <feature> (tests passing)`
-
-### 5. Execute REFACTOR phase
-
-Invoke execute-plan for Wave 3 (refactor tasks, if any):
-- tool-worker improves code quality while keeping tests green
-- After Wave 3, run tests again — must still pass
-- Git checkpoint: `refactor: clean up <feature>`
-
-### 6. Review (review-work)
-
-Invoke `review-work` after GREEN/REFACTOR and before verification. Review findings must be fixed, accepted, deferred, or marked false positive before delivery.
-
-### 7. Verify (verify-work with coverage gate)
-
-Invoke verify-work with additional context:
-```
-Additional verification: Check test coverage.
-Run coverage command and verify >= 80% on changed files.
-Include coverage % in the verification report.
-If coverage < 80%, verdict is FAIL with coverage gap details.
-```
-
-### 8. Route on verdict
-
-Same as deliver:
-- **Clean review + all PASS + coverage >= 80%** → deliver
-- **Any FAIL or coverage < 80%** → loop (re-plan failing items)
-- **NOT_VERIFIED** → surface to user
-
-### 9. Deliver
-
-Same as deliver, plus:
-- Report TDD cycle summary: RED → GREEN → REFACTOR with checkpoint SHAs
-- Report final coverage %
-
-## Session File Format
-
-```markdown
-# TDD: <Goal one-liner>
-
-branch: <branch>
-created: <date>
-status: planning | red | green | refactor | verifying | delivered
-type: tdd
-iteration: 0
-coverage_target: 80
-
-## Plan
-(from plan-work)
-
-## RED Phase
-- Tests written: <list>
-- All failing: YES/NO
-- Checkpoint: <SHA>
-
-## GREEN Phase
-- Implementation: <list>
-- All passing: YES/NO
-- Checkpoint: <SHA>
-
-## REFACTOR Phase
-- Changes: <list>
-- Tests still passing: YES/NO
-- Checkpoint: <SHA>
-
-## Verification Report
-(from verify-work)
-
-## History
-- iteration 1: RED ✓, GREEN ✓, REFACTOR ✓, coverage 85%
-```
-
-`<branch>` is the branch recorded in `state.json`'s `branch` field (`ensure-session` derives `agent/<actor>/<slug>`; an explicit `--branch` flag overrides on a new session). `ensure-session` only records the name — creating and checking out the actual git branch/worktree remains this skill's responsibility.
-
-{context?}
+Use `delegate-mechanical` for test and check bookkeeping, `delegate-design` for
+acceptance and test design, and `delegate-implementation` for the red-green-
+refactor implementation and its review. Resolve roles from `.datum/config.json`
+under `context/contracts/execution-contract.md` and record fallbacks or
+escalations.
+
+## Inputs and Provider Adapters
+
+Use the selected Work Item's acceptance criteria, Repository adapter test
+conventions and commands, and Change-adapter risk context. A remote issue or
+pull request may supply these inputs, but no particular provider is required.
+
+## Profile Behavior
+
+1. Select `builder.build` through `deliver`, recording the `tdd-workflow`
+   profile in planning context.
+2. Have `plan-work` identify test scenarios before the implementation tasks,
+   including what behavior each test should demonstrate and why it should fail
+   against the pre-change behavior.
+3. Have `execute-plan` make the tests demonstrably fail for the intended
+   reason before implementation, then make them pass with the smallest adequate
+   change.
+4. Refactor only while the relevant tests remain passing. Use checkpoints when
+   the Repository adapter's practice calls for them; do not impose a commit
+   pattern.
+5. Have review and verification evaluate the test quality, changed behavior,
+   relevant regression coverage, and any project-defined coverage requirement.
+
+Do not require an arbitrary numeric coverage percentage. Coverage targets come
+from the Work Item, repository policy, or an explicit user decision.
+
+## Output Responsibility
+
+This profile creates no independent artifact or evidence. Its output is the
+test-first constraints and RED/GREEN/REFACTOR observations carried by the
+standard primitive artifacts and final delivery report.
+
+## Standalone and No-Active-Run Behavior
+
+`tdd-workflow` does not start or resume a run itself. With no active run,
+route to `deliver` to select and start `builder.build` with this profile. With
+an active run, apply it only when doing so is compatible with the current Work
+Item and canonical next action; otherwise surface the conflict.

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

@@ -1,127 +1,115 @@
 ---
 name: "verify-work"
-description: "Verification primitive — session file path to structured evidence verdict via tool-verifier + tool-playwright. Reads acceptance criteria from plan artifact."
+description: "Report-only acceptance verification. Records command-backed Builder verification evidence in trust.bundle when bound to an active run."
 ---
 
-# Verify
+# Verify Work
 
-Session file in, structured evidence verdict out. Delegates to tool-verifier and tool-playwright.
+## Role
 
-Verification is not critique. Run `review-work` first when the task needs maintainability, security, architecture, or standards review. Verification should start only after the required critique gate has been recorded or explicitly marked `not_verified`. `verify-work` records proof in `evidence.json`; `review-work` records critique through the critique artifact/sink, currently `critique.json` locally.
+This is a Builder step skill.
 
-## Agents
+Verify Work proves acceptance criteria with reproducible evidence. It is
+report-only: verifiers may inspect, test, and write evidence artifacts, but do
+not patch source files or apply autofixes.
 
-| Agent | Role |
-|---|---|
-| tool-verifier | Code verification, acceptance criteria checking, structured verdicts |
-| tool-playwright | Visual verification, screenshots, accessibility checks |
+Critique belongs to `review-work`; behavior proof belongs here.
+
+## Binding
+
+| Context | Binding | Flow expectations |
+| --- | --- | --- |
+| Active Builder run | `builder.build` at `verify` | `acceptance-criteria` and `tests-evidence`; `policy-compliance` only when applicable. `review-work` separately produces `clean-critique`. |
+| Standalone invocation | No Flow binding | No workflow mutation. |
+
+For an active run, verify the binding first:
+
+```bash
+flow-agents workflow status --session-dir <session-dir> --json
+```
+
+Only a matching active `builder.build` run at `verify` may receive workflow
+evidence. Otherwise, return the verification report and unresolved gaps without
+calling `workflow evidence`.
 
 ## Model Routing
 
-Verify roles never resolve **below** the tier of the work they check (Goodhart
-guard): default `delegate-implementation`, raised to match or exceed the tier
-that produced the work under verification — a verifier of `delegate-design` work
-resolves `delegate-design` or `orchestrator`, never a cheaper tier. Resolve the
-role from `.datum/config.json` (`npx @kontourai/datum resolve <role> --json`) and
-pass the model explicitly. See `context/contracts/execution-contract.md`
-§ Delegation: Model Routing and § Goodhart guard. Fallback: inherit the session
-model when datum/config is absent, noted in the artifact.
-
-## Orchestrator Rule
-
-You do not review source files. You delegate to tool-verifier and tool-playwright, then read the verdict artifact.
-
-## Shared Contracts
-
-Follow:
-- `context/contracts/artifact-contract.md`
-- `context/contracts/verification-contract.md`
-- `context/contracts/planning-contract.md` for acceptance criteria and Definition Of Done
-
-This skill owns orchestration and routing. The verification contract owns phases, report-only behavior, verdict rules, report shape, Goal Fit checks, and `NOT_VERIFIED` handling.
-
-## Read-Only Rule (STRICT)
-
-**Verifiers NEVER modify source code.** tool-verifier and tool-playwright are read-only reporters:
-- They may run commands (build, test, lint) but NEVER apply fixes
-- No format fixes, no lint auto-fixes, no "1 format fix applied"
-- No code patches, no "found and fixed" — report findings only
-- If a fix is needed, report it as a finding. The orchestrator routes it back to execute-plan.
-
-## Input
-
-- **Session file path**: the session file in `.kontourai/flow-agents/<slug>/` (preferred)
-- The session file references the plan artifact (which has acceptance criteria) and execution progress (which has modified files)
-- If NO session file exists, delegate to tool-verifier directly (see Standalone Verification below)
-
-## Standalone Verification (no session file)
-
-When invoked without a session file (e.g., user says "verify this project" or "run verification"):
-
-1. Delegate to tool-verifier with:
-   - The user's verification request
-   - The current working directory
-   - Modified files from `git diff --name-only` (if available)
-2. Delegate to tool-playwright in parallel if UI changes are mentioned
-3. Read the verdict and report to the user
-
-Skip session file lookup — go straight to delegation.
-
-## Workflow (with session file)
-
-1. Read the session file to find the plan artifact path and modified files
-2. Confirm the review-before-verify gate: the critique artifact/sink should show the required review pass, blocking findings, or an explicit `not_verified` gap. If the critique gate is missing for work that requires review, stop and route to `review-work` instead of treating verification as a substitute critique.
-3. Set session file `status: verifying` and update `state.json` phase/status. Use `npm run workflow:sidecar -- advance-state <artifact-dir> --status verifying --phase verification --summary ... --next-action ...` when the repository provides it.
-4. Delegate in parallel:
-   ```
-   tool-verifier:
-   - Acceptance criteria from plan artifact
-   - Acceptance criteria from acceptance.json when present
-   - Definition Of Done and stop-short risks from plan artifact
-   - Modified files from execution progress
-   - Requirement to preserve each AC id and map it to command/test evidence plus structured source evidence refs when implementation behavior is claimed
-   - Evidence ref schema: objects with `kind`, `url`, `file`, `line_start`, `line_end`, and `excerpt` where applicable; source refs require local file/line/excerpt and should use immutable GitHub blob permalinks pinned to a commit SHA when provider URLs are available
-   - Build/test commands from AGENTS.md or plan
-   - todo_file path for writing verdict artifact
-   - Workflow artifact root path; append verifier progress with record-agent-event
-
-   tool-playwright (if UI changes exist):
-   - Pages/components to check
-   - Expected visual state
-   - Workflow artifact root path; append browser evidence or blockers with record-agent-event
-   ```
-5. Read the verdict artifact: `<session-basename>-review.md`
-6. Update session file: paste verdict summary into `## Verification Report`
-7. Write or update `evidence.json` with verification checks, top-level verdict, and `not_verified_gaps`
-   - use `npm run workflow:sidecar -- record-evidence <artifact-dir> --verdict ... --check-json ...` when the repository provides it
-   - `checks[].artifact_refs` must use structured evidence ref objects, not legacy strings
-   - for multi-repo or cross-product work, preserve a coverage matrix in the
-     evidence report or check summaries that lists each affected root and its
-     build/test, dependency/security, provider/CI, and accepted-gap status
-   - if external dependency audit or provider checks are blocked by approval,
-     privacy, credentials, network, or missing change-provider state, record the
-     affected roots as `not_verified` instead of collapsing the lane into a
-     generic pass/fail
-8. Update `acceptance.json` with criterion statuses and structured evidence refs
-   - `criteria[].evidence_refs` must use structured evidence refs and map each AC id to command/test proof plus source refs for behavior claims
-   - when source refs are missing for a behavior claim, mark the criterion `not_verified` or record an accepted gap instead of using broad prose-only evidence
-9. Route on verdicts:
-   - **All PASS** → set `status: verified`
-   - **Any FAIL** → set `status: failed`, list failures
-   - **Any NOT_VERIFIED** → set Markdown status `needs-decision`, set `state.json` status `needs_decision`, and surface to user
-
-## Verification Contract
-
-tool-verifier writes the verdict artifact using `context/contracts/verification-contract.md`.
-
-You do not override verdicts. FAIL is FAIL until re-verified. `NOT_VERIFIED` items are surfaced to the user so they can decide whether to accept, fix, or skip. A technically green build is not enough for PASS when the `Definition Of Done` says the user still cannot run, understand, inspect, or act on the result.
+Resolve `delegate-implementation` from `.datum/config.json` and follow
+`context/contracts/execution-contract.md`. The Goodhart guard applies:
+verification must never resolve below the reasoning tier of the checked work.
+Record any fallback or escalation in the verification report.
+
+## Inputs
+
+- Acceptance criteria, Definition Of Done, and stop-short risks.
+- Changed-file scope from the session, plan, or `RepositoryAdapter`.
+- Local checks and runtime evidence selected for the change.
+- Relevant `CheckProvider` and `ChangeProvider` evidence when it exists.
+- The `trust.bundle` critique slice when review is required; critique findings
+  remain separate from verification evidence.
+
+## Verification Work
+
+1. Re-check Goal Fit before testing: compare the delivered artifacts and actual
+   changed scope with the selected Work Item, Definition Of Done, acceptance
+   criteria, and stop-short risks. Missing requested behavior or unexplained
+   scope routes back even when the implementation plan was completed.
+2. Map each acceptance criterion to an observable check, source inspection, or
+   runtime observation. Delegate to `tool-verifier`; include `tool-playwright`
+   for browser-facing behavior.
+3. Run relevant build, type, lint, test, security, diff, browser, runtime, and
+   provider checks. `CheckProvider` evidence is provider-neutral; a provider
+   check is not assumed to exist for every repository.
+4. Record every criterion as `PASS`, `FAIL`, `NOT_VERIFIED`, or an explicitly
+   accepted gap. Missing, inaccessible, or inconclusive evidence is
+   `NOT_VERIFIED`, never `PASS`.
+   Reject prose-only claims and non-resolving references. Evidence references
+   must identify a command result, source location, provider record, runtime
+   observation, or artifact that a reviewer can inspect. A passing
+   `tests-evidence` claim needs every declared criterion exactly once, and every
+   passing criterion needs a `kind:"command"` reference whose command text
+   exactly matches one of the substantive `--command` values that ran
+   successfully. External-only attestations cannot satisfy it.
+5. Publish the relevant active-run expectation through the public CLI with one
+   or more exact commands that produced the test results. Repeat `--command`
+   when criteria require different checks, and include a matching top-level
+   `--evidence-ref-json` for every recorded command. A prose summary or an
+   artifact reference alone cannot satisfy `tests-evidence`:
+
+```bash
+flow-agents workflow evidence --session-dir <session-dir> \
+  --expectation tests-evidence \
+  --status <pass|fail|not_verified> \
+  --command "npm test" \
+  --summary "The recorded test command supports the accepted behavior." \
+  --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":"<session-dir>/<slug>--plan-work.md","summary":"Accepted criterion and planned verification mapping."}'
+```
+
+When a policy check applies, publish `policy-compliance` in the same way. Do
+not publish that optional expectation when no policy check applies.
 
 ## Output
 
-- Verdict artifact: `<session-basename>-review.md`
-- Session file updated with verification report and status
-- Structured sidecars updated: `state.json`, `acceptance.json`, and `evidence.json`
-- Acceptance evidence preserves AC ids and uses structured evidence refs; prose-only behavior claims are not clean verification evidence
-- Verdict follows `context/contracts/verification-contract.md`
-
-If `record-evidence` or artifact validation is unavailable or blocked, keep the verdict explicit and record the sidecar-write gap as `NOT_VERIFIED`. Do not convert verifier output into `PASS` without structured evidence when sidecars are required.
+Record completed criteria as the required `acceptance-criteria` slice and the
+verification result as the `tests-evidence` slice in `trust.bundle`.
+It must preserve criterion identifiers and include a readable `Acceptance
+Evidence` table in its summary or linked reviewable report:
+
+| AC id | Status | Command/Test Evidence | Source Evidence | Gaps |
+| --- | --- | --- | --- | --- |
+| `<id>` | `PASS`, `FAIL`, or `NOT_VERIFIED` | Command, result, or observation | File, test, provider, or runtime reference | Missing or accepted evidence |
+
+The result states the overall verification verdict and every unresolved gap.
+For an active matching run, publish one `--criterion-json` object for every
+accepted criterion, each with its own status and reviewable evidence refs, plus
+a substantive literal `--command` for every distinct check that was run. Every
+top-level and criterion command reference must exactly match one of those
+commands. The public evidence calls
+publish `acceptance-criteria`, `tests-evidence`, and applicable
+`policy-compliance`; no retired
+verification sidecar is a store. Never publish a placeholder, `true`,
+`bash -c true`, or `node --version` as behavior evidence. In a packed or
+temporary consumer repository, use a real project-local test/check/verify
+script rather than a command that exists only in the Flow Agents source repo.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontourai/flow-agents",
-  "version": "3.6.0",
+  "version": "3.7.0",
   "description": "Flow Agents — a Kontour product that applies Flow and Veritas discipline as a portable process layer inside the agent tools you already use: Claude Code, Codex, Kiro, opencode, pi, and GitHub Actions — with framework adapters (AWS Strands preview) on the same policy-engine contract.",
   "keywords": [
     "agents",
@@ -149,7 +149,7 @@
     "typescript": "^6.0.3"
   },
   "dependencies": {
-    "@kontourai/flow": "^3.1.0"
+    "@kontourai/flow": "^3.1.4"
   },
   "optionalDependencies": {
     "@kontourai/surface": "^2.0.0",

package/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/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,
       };
     }