@kontourai/flow-agents 1.4.0 → 2.0.0

package/kits/knowledge/flows/glossary-sync.flow.json

@@ -0,0 +1,61 @@
+{
+  "id": "knowledge.glossary-sync",
+  "version": "1.0",
+  "steps": [
+    { "id": "collect", "next": "extract" },
+    { "id": "extract", "next": "diff-gate" },
+    { "id": "diff-gate", "next": "propose-gate" },
+    { "id": "propose-gate", "next": "done" },
+    { "id": "done", "next": null }
+  ],
+  "gates": {
+    "collect-gate": {
+      "step": "collect",
+      "expects": [
+        {
+          "id": "glossary-sources-resolved",
+          "kind": "trust.bundle",
+          "required": true,
+          "description": "The configurable glossary source list has been resolved to concrete canonical docs. Each source is a record id or a { category, prefix } selector; a source id that does not exist fails the gate (the source list is evidence — a typo must not pass silently). Auditing is opt-in: an empty source list resolves to nothing and the flow does nothing.",
+          "bundle_claim": {
+            "claimType": "knowledge.glossary-sync.collect",
+            "subjectType": "artifact",
+            "accepted_statuses": ["trusted", "accepted"]
+          }
+        }
+      ]
+    },
+    "diff-gate": {
+      "step": "diff-gate",
+      "expects": [
+        {
+          "id": "entries-classified-cite-source",
+          "kind": "trust.bundle",
+          "required": true,
+          "description": "Every term→definition entry extracted from a canonical doc (via the pluggable term extractor) is classified against the existing concept records and cites its evidence: the canonical source doc id + title, the extracted term and definition, and (for an outdated entry) the existing concept's drifted body. An entry is classified 'gap' when no concept captures the term, 'outdated' when a concept exists but its body has drifted from the canonical definition (whitespace-insensitive), or 'current' when they match. No entry is emitted without the source doc it came from. This step NEVER mutates a record — it only classifies.",
+          "bundle_claim": {
+            "claimType": "knowledge.glossary-sync.diff",
+            "subjectType": "artifact",
+            "accepted_statuses": ["trusted", "accepted"]
+          }
+        }
+      ]
+    },
+    "propose-gate": {
+      "step": "propose-gate",
+      "expects": [
+        {
+          "id": "gaps-and-drift-routed-through-existing-ops",
+          "kind": "trust.bundle",
+          "required": true,
+          "description": "Read-only by default: the flow returns the classification plan (gaps / outdated / current) and mutates nothing. When apply mode is enabled, every gap and outdated entry is enacted through the EXISTING concept-record ops with the canonical source doc as the proposer (it is the evidence for the definition): a gap is store.create(concept) then propose+apply; an outdated concept is store.propose + store.apply with the canonical definition as new_body. No new mutation path is forked — the operator's adopt/refresh decision rides the same gated propose→apply lineage every other concept mutation uses.",
+          "bundle_claim": {
+            "claimType": "knowledge.glossary-sync.propose",
+            "subjectType": "artifact",
+            "accepted_statuses": ["trusted", "accepted"]
+          }
+        }
+      ]
+    }
+  }
+}

package/kits/knowledge/flows/hygiene-review.flow.json

@@ -0,0 +1,43 @@
+{
+  "id": "knowledge.hygiene-review",
+  "version": "1.0",
+  "steps": [
+    { "id": "orchestrate", "next": "review-gate" },
+    { "id": "review-gate", "next": "done" },
+    { "id": "done", "next": null }
+  ],
+  "gates": {
+    "orchestrate-gate": {
+      "step": "orchestrate",
+      "expects": [
+        {
+          "id": "sub-flows-run-via-existing-methods",
+          "kind": "trust.bundle",
+          "required": true,
+          "description": "Each opted-in hygiene audit was run through its EXISTING flow-runner method and EXISTING gates — knowledge.audit-freshness, knowledge.detect-contradictions, knowledge.glossary-sync, knowledge.canonicalize-category — and its findings collected. This orchestrator reimplements NO detection logic and forks NO new gate: the freshness/contradiction/canonicalize flags arrive already vouched by their own flag-/propose-gates, and glossary entries arrive already classified by glossary-sync's diff-gate. Each audit is opt-in (mirroring the flows): an audit whose config block is omitted is skipped and surfaced as skipped, so an empty review does nothing. This step is read-only by default — like the flows it runs, it mutates no record of its own.",
+          "bundle_claim": {
+            "claimType": "knowledge.hygiene-review.orchestrate",
+            "subjectType": "artifact",
+            "accepted_statuses": ["trusted", "accepted"]
+          }
+        }
+      ]
+    },
+    "review-gate": {
+      "step": "review-gate",
+      "expects": [
+        {
+          "id": "proposals-route-through-existing-gates",
+          "kind": "trust.bundle",
+          "required": true,
+          "description": "The unified review presents every collected proposal as one of three operator decisions — adopt / retire / merge — and each proposal cites its sourceFlow plus the underlying evidence the originating flow's gate already guaranteed (no proposal is synthesized here). hygiene-review forks NO propose→approve gate of its own: the operator enacts each decision by routing it back through the source flow's EXISTING gated op — retire via knowledge.retire; adopt via a fresh capture/compile (audit-freshness refresh) or via glossary-sync apply (store.create→propose→apply for a gap, store.propose→apply for drift, canonical doc as proposer); merge via an update/recategorize. The ONLY mutation path this orchestrator can trigger is glossary apply, which it delegates verbatim to knowledge.glossary-sync's own propose→apply lineage — it never writes the store directly. Read-only by default (consume-never-fork).",
+          "bundle_claim": {
+            "claimType": "knowledge.hygiene-review.review",
+            "subjectType": "artifact",
+            "accepted_statuses": ["trusted", "accepted"]
+          }
+        }
+      ]
+    }
+  }
+}

package/kits/knowledge/kit.json

@@ -34,6 +34,31 @@
       "id": "knowledge.retire",
       "path": "flows/retire.flow.json",
       "description": "Retire implemented or obsolete records from the working set via gated lifecycle: identify → propose-retirement → evidence-gate → apply-or-reject. Evidence required: retirement rationale + implementedByRef (when targeting 'implemented' status) or supersededByRef (optional, for 'retired'). Rejection leaves record status byte-identical. Retired records remain fully queryable with provenance via includeRetired flag."
+    },
+    {
+      "id": "knowledge.audit-freshness",
+      "path": "flows/audit-freshness.flow.json",
+      "description": "Hygiene audit (optional, configurable): flag records past per-category staleness thresholds and propose archive/refresh for each. Read-only: collect → measure → flag-gate. Thresholds are per-category (dot-hierarchy longest-prefix, with optional default); a category with no threshold is skipped (opt-in). Each flag cites last-mutation (max of updated_at and latest mutation_log entry) + the threshold that fired + computed age. Forks no mutation path — the operator routes each flag through knowledge.retire (archive) or a fresh capture/compile (refresh)."
+    },
+    {
+      "id": "knowledge.canonicalize-category",
+      "path": "flows/canonicalize-category.flow.json",
+      "description": "Hygiene audit (optional, configurable): audit category sprawl and propose flattening/retirement. Read-only: survey → assess → propose-gate. Flags three sprawl kinds (each independently toggleable): orphan-prefix (an intermediate prefix node holding no record directly, or a deep path carrying a single record → flatten), too-many-leaves (a parent fanning out past the configured leaf budget → regroup), implemented-active (a still-active record carrying an operator-supplied implemented-marker tag → retire). Every finding cites its evidence (the metric that fired + offending category/record ids). Forks no mutation path — the operator routes each finding through knowledge.retire (retire) or an update/recategorize (flatten/regroup)."
+    },
+    {
+      "id": "knowledge.glossary-sync",
+      "path": "flows/glossary-sync.flow.json",
+      "description": "Hygiene sync (optional, configurable): keep the glossary (concept records) in sync with the canonical docs that define those terms. Read-only by default: collect → extract → diff-gate → propose-gate. Surveys a configurable glossary source list (record ids and/or category selectors — opt-in), extracts term→definition entries via a pluggable extractor, and classifies each against existing concepts: gap (no concept) → propose a canonical definition; outdated (concept body drifted from the canonical, whitespace-insensitive) → propose the update; current → no-op. Each entry cites its source doc. With apply=true it enacts the plan through the existing concept-record ops (create → propose → apply for gaps; propose → apply for drift) with the canonical doc as proposer — forks no mutation path."
+    },
+    {
+      "id": "knowledge.detect-contradictions",
+      "path": "flows/detect-contradictions.flow.json",
+      "description": "Hygiene audit (optional, configurable): compare compiled records within a category and flag conflicting assertions with BOTH record ids. Read-only: collect → compare → flag-gate. Reuses the similarity adapter to scope comparisons to records about the same thing, then a pluggable contradiction fn (default: opposing-polarity heuristic) judges each similar pair. Auditing is opt-in per category. Each flag cites both record ids + shared category + the reason that fired. Forks no mutation path — the operator routes each flag through knowledge.retire (drop the stale assertion) or a fresh capture/compile/consolidate (reconcile)."
+    },
+    {
+      "id": "knowledge.hygiene-review",
+      "path": "flows/hygiene-review.flow.json",
+      "description": "Hygiene orchestrator (#106 #5, closes the issue): a THIN, opt-in orchestrator over the four hygiene flows (audit-freshness, detect-contradictions, glossary-sync, canonicalize-category). orchestrate → review-gate. Runs each opted-in audit via its EXISTING flow-runner method + gates (reimplements no detection), folds their findings into one operator-facing review of proposed actions normalized to adopt / retire / merge, each citing its sourceFlow + the evidence its origin flow's gate already vouched. Read-only by default; forks NO propose→approve gate — the operator enacts each decision through the source flow's existing gated op (retire via knowledge.retire; adopt via capture/compile or glossary-sync apply; merge via update/recategorize). The only mutation it can trigger is glossary apply, delegated verbatim to knowledge.glossary-sync's propose→apply lineage (consume-never-fork)."
     }
   ],
   "docs": [
@@ -55,7 +80,7 @@
     {
       "id": "knowledge.flow-runner",
       "path": "adapters/flow-runner/index.js",
-      "description": "Executable flow logic: capture(rawText, meta) → classified raw record; compile(rawIds[]) → compiled record with provenance links; synthesize(conceptId | topicSelector, options) → concept summary proposal with mutation gate; consolidate(snapshotId | topicSelector, options) → decision snapshot consolidation with supersede-not-delete; retire(recordId, options) → gated status lifecycle transition (active→implemented→retired) with working-set exclusion. Emits canonical telemetry events at gate points."
+      "description": "Executable flow logic: capture(rawText, meta) → classified raw record; compile(rawIds[]) → compiled record with provenance links; synthesize(conceptId | topicSelector, options) → concept summary proposal with mutation gate; consolidate(snapshotId | topicSelector, options) → decision snapshot consolidation with supersede-not-delete; retire(recordId, options) → gated status lifecycle transition (active→implemented→retired) with working-set exclusion; auditFreshness(options) → read-only hygiene audit returning flags (last-mutation + threshold cited) proposing archive/refresh for records past per-category staleness thresholds; canonicalizeCategory(options) → read-only hygiene audit returning category-sprawl findings (orphan-prefix/too-many-leaves/implemented-active, each citing its metric + offending ids) proposing flatten/regroup/retire; glossarySync(options) → read-only-by-default glossary hygiene that extracts term→definition entries from a configurable list of canonical docs and classifies each against existing concepts (gap/outdated/current), optionally enacting gaps+drift through the existing concept-record create→propose→apply ops; detectContradictions(options) → read-only hygiene audit comparing compiled records within a category (similarity adapter scopes the comparison; pluggable contradiction fn judges each similar pair) returning flags that cite BOTH conflicting record ids + reason. Emits canonical telemetry events at gate points."
     },
     {
       "id": "knowledge.similarity-vector",
@@ -103,6 +128,31 @@
       "id": "knowledge.entity-cards-suite",
       "path": "evals/entities/suite.test.js",
       "description": "Eval cases for person/entity cards (issue #48): AC1-AC4 — entity extraction from Attendees lines, exact-match resolution, possible-duplicate detection, merge via propose/apply/reject (union aliases+backlinks, supersede duplicate), Obsidian people/ folder rendering, and extended contract suite (person type validity) on both adapters."
+    },
+    {
+      "id": "knowledge.audit-freshness-suite",
+      "path": "evals/audit-freshness/suite.test.js",
+      "description": "Eval cases for audit-freshness (#106 hygiene #1): per-category threshold resolution (dot-hierarchy longest-prefix + default + opt-in skip); each flag cites last-mutation + threshold + age; boundary (age == threshold not flagged, age > threshold flagged); last-mutation derived from max(updated_at, latest mutation_log entry); retired records excluded; read-only invariant (no record mutated, no flag without evidence); proposed-action resolution; gate telemetry."
+    },
+    {
+      "id": "knowledge.canonicalize-category-suite",
+      "path": "evals/canonicalize-category/suite.test.js",
+      "description": "Eval cases for canonicalize-category (#106 hygiene #4): orphan-prefix detection (empty intermediate node + single-record deep path → flatten); too-many-leaves fan-out budget (boundary: count == budget not flagged, > budget flagged → regroup, lists the leaves); implemented-active (status:active + implemented-marker tag → retire, case-insensitive markers); every finding cites its metric + evidence + offending ids; each check is independently toggleable + opt-in (disabled check / empty markers → no findings); retired records excluded; read-only invariant (no record mutated); gate telemetry (survey-gate + propose-gate); module-level export."
+    },
+    {
+      "id": "knowledge.glossary-sync-suite",
+      "path": "evals/glossary-sync/suite.test.js",
+      "description": "Eval cases for glossary-sync (#106 hygiene #3): default term extraction from canonical docs (bold/colon glossary lines); classification — gap (no concept), outdated (concept body drifted, whitespace-insensitive), current (matches); case/space-insensitive term matching within the resolved concept category; configurable source list (record id + category selector, opt-in empty list, unknown source rejected); pluggable term extractor; read-only-by-default invariant (no record mutated without apply); apply mode enacts gaps via create→propose→apply and drift via propose→apply with the canonical doc as proposer (consume-never-fork, proposes-link + mutation-log evidence); gate telemetry."
+    },
+    {
+      "id": "knowledge.detect-contradictions-suite",
+      "path": "evals/detect-contradictions/suite.test.js",
+      "description": "Eval cases for detect-contradictions (#106 hygiene #2): default opposing-polarity heuristic flags affirm-vs-negate over a shared subject; agreeing records not flagged; every flag cites BOTH record ids + category + reason; similarity scoping (an empty similarity detector yields no flags); pluggable contradiction fn overrides the default verdict; opt-in category scoping; cross-category pairs never formed; each unordered pair compared at most once; retired compiled records excluded; read-only invariant; gate telemetry; module-level export."
+    },
+    {
+      "id": "knowledge.hygiene-review-suite",
+      "path": "evals/hygiene-review/suite.test.js",
+      "description": "Eval cases for hygiene-review (#106 hygiene #5, closes the issue): opt-in orchestration (omitted audit block is skipped; empty review does nothing); each opted-in audit runs via its existing flow-runner method and its findings are collected verbatim (no detection reimplemented); proposals are normalized to adopt/retire/merge and each cites its sourceFlow + evidence; thin-orchestrator/consume-never-fork invariants — read-only by default mutates no record, no new gate is forked, the only mutation (glossary apply:true) is delegated to glossarySync's own gated propose→apply (verified via proposes-link + mutation-log on the resulting concept); sub-flow telemetry is folded in plus hygiene-review's own orchestrate-gate + review-gate; module-level export delegates to the runner."
     }
   ],
   "skills": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontourai/flow-agents",
-  "version": "1.4.0",
+  "version": "2.0.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",
@@ -44,7 +44,6 @@
     "flow-agents-console-learning-projection": "build/src/cli.js",
     "flow-agents-context-map": "build/src/cli.js",
     "flow-agents-effective-backlog-settings": "build/src/cli.js",
-    "flow-agents-filter-installed-packs": "build/src/cli.js",
     "flow-agents-fixture-retirement-audit": "build/src/cli.js",
     "flow-agents-promote-workflow-artifact": "build/src/cli.js",
     "flow-agents-publish-change": "build/src/cli.js",
@@ -105,7 +104,6 @@
     "context-map": "npm run build --silent && node build/src/cli.js context-map",
     "context-map:check": "npm run build --silent && node build/src/cli.js context-map --check",
     "build:bundles": "npm run build --silent && node build/src/cli.js build-bundles",
-    "filter:packs": "npm run build --silent && node build/src/cli.js filter-installed-packs",
     "validate:package": "npm run build --silent && node build/src/cli.js validate-package",
     "workflow:sidecar": "npm run build --silent && node build/src/cli/workflow-sidecar.js",
     "workflow:validate-artifacts": "npm run build --silent && node build/src/cli/validate-workflow-artifacts.js",
@@ -126,6 +124,7 @@
     "eval": "bash evals/run.sh",
     "eval:static": "bash evals/run.sh static",
     "eval:integration": "bash evals/run.sh integration",
+    "trust-reconcile-verify": "npm run build && npm run eval:static",
     "eval:acceptance": "bash evals/run.sh acceptance",
     "eval:llm": "bash evals/run.sh llm",
     "eval:llm:codex": "bash evals/run.sh llm dev --runtime codex",
@@ -145,6 +144,7 @@
     "@kontourai/flow": "~1.3.0"
   },
   "optionalDependencies": {
-    "hachure": "^0.4.0"
+    "hachure": "^0.4.0",
+    "@kontourai/surface": "^1.2.0"
   }
 }

package/packaging/conformance/README.md

@@ -84,12 +84,20 @@ Full payload/decision schema is documented in `docs/spec/runtime-hook-surface.md
 | `stop-goal-fit--allow-clean-cwd.json` | stop-goal-fit | stop | L1 | No warnings in clean workspace |
 | `stop-goal-fit--warn-active-delivery.json` | stop-goal-fit | stop | L1 | Warnings for active delivery without DOD/GoalFit |
 | `stop-goal-fit--block-strict-mode.json` | stop-goal-fit | stop | L2 | Exit 2 with FLOW_AGENTS_GOAL_FIT_STRICT=true |
+| `stop-goal-fit--block-mode.json` | stop-goal-fit | stop | L2 | Exit 2 with FLOW_AGENTS_GOAL_FIT_MODE=block |
+| `stop-goal-fit--off-mode.json` | stop-goal-fit | stop | L1 | Silent (exit 0, no stderr) with FLOW_AGENTS_GOAL_FIT_MODE=off |
 | `workflow-steering--allow-no-state.json` | workflow-steering | userPromptSubmit | L1 | Pass-through when no active workflow state |
 | `workflow-steering--inject-active-state.json` | workflow-steering | userPromptSubmit | L1 | Injects STATE hint for blocked task |
 | `workflow-steering--inject-subagent-steering.json` | workflow-steering | postToolUse | L1 | Injects EXECUTION COMPLETE hint after tool-worker |
+| `workflow-steering--reground-active-prompt.json` | workflow-steering | userPromptSubmit | L1 | Re-grounds an ordinary in_progress task (not just flagged states) |
+| `workflow-steering--reground-session-start.json` | workflow-steering | sessionStart | L1 | Re-grounds the active goal on SessionStart (survives compaction/resume) |
 
 Fixtures with `workspace_setup` create a temporary directory with the listed files before invoking the adapter, and clean it up afterward. The `cwd` field in those payloads is replaced with the temp directory path at runtime.
 
+### Goal-fit enforcement mode
+
+`stop-goal-fit` enforcement is controlled by `FLOW_AGENTS_GOAL_FIT_MODE` (`block` | `warn` | `off`); the legacy `FLOW_AGENTS_GOAL_FIT_STRICT=true` is honored as an alias for `block`. The canonical engine default is `warn`, so the conformance contract stays warning-by-default. Shipped L2 runtime configs (Claude Code, Codex) set `block` by default — overridable per-operator via the env var — so the installed product enforces while the engine default and these fixtures remain warn. In `block` mode the same goal-fit gap is refused up to `FLOW_AGENTS_GOAL_FIT_MAX_BLOCKS` (default 3) consecutive times, then released to avoid trapping the agent on an unsatisfiable goal.
+
 ---
 
 ## How to declare conformance
@@ -102,8 +110,8 @@ engine_contract_version: "1.0"
 runner_version: "run-conformance.js"
 test_date: 2026-06-11
 verdict: PASS
-fixture_count: 12
-fixtures_passed: 12
+fixture_count: 18
+fixtures_passed: 18
 gaps: []                       # List any declared gaps here
 ```
 

package/packaging/conformance/fixtures/evidence-capture--allow-records-command.json

@@ -0,0 +1,29 @@
+{
+  "description": "evidence-capture records a command execution to the append-only log and passes through (exit 0, echoes input) — it is non-blocking by contract",
+  "policy_class": "evidence-capture",
+  "canonical_event": "postToolUse",
+  "conformance_level": "L2",
+  "hook_id": "evidence-capture",
+  "hook_script": "evidence-capture.js",
+  "payload": {
+    "hook_event_name": "PostToolUse",
+    "tool_name": "Bash",
+    "cwd": "__TEMP_WORKSPACE__",
+    "tool_input": {
+      "command": "npm test"
+    },
+    "tool_response": {
+      "exitCode": 0,
+      "stdout": "ok"
+    }
+  },
+  "workspace_setup": {
+    "AGENTS.md": "# Test Repo\n",
+    ".flow-agents/cap-task/state.json": "{\"schema_version\":\"1.0\",\"task_slug\":\"cap-task\",\"status\":\"in_progress\",\"phase\":\"verification\",\"updated_at\":\"2026-06-23T00:00:00Z\"}"
+  },
+  "expected": {
+    "exit_code": 0,
+    "stdout_echoes_input": true,
+    "stderr_is_empty": true
+  }
+}

package/packaging/conformance/fixtures/stop-goal-fit--block-bundle-disputed-claim.json

@@ -0,0 +1,29 @@
+{
+  "description": "stop-goal-fit blocks (exit 2) when the canonical Hachure trust.bundle carries a high-impact claim Surface marked `disputed` \u2014 even on a terminal/delivered task; trust.bundle is the sole verification artifact (4c bundle-only). ADR 0010 Phase 2: the gate enforces on the bundle the producers emit, not only bespoke sidecars.",
+  "policy_class": "stop-goal-fit",
+  "canonical_event": "stop",
+  "conformance_level": "L2",
+  "hook_id": "stop-goal-fit",
+  "hook_script": "stop-goal-fit.js",
+  "payload": {
+    "hook_event_name": "Stop",
+    "cwd": "__TEMP_WORKSPACE__"
+  },
+  "workspace_setup": {
+    "AGENTS.md": "# Test Repo\n",
+    ".flow-agents/false-bundle/false-bundle--deliver.md": "# False Bundle\n\nbranch: main\nstatus: delivered\ntype: deliver\n\n## Definition Of Done\n- [x] tests pass\n\n## Goal Fit Gate\n- [x] acceptance verified\n\n### Verdict: PASS\n",
+    ".flow-agents/false-bundle/state.json": "{\"schema_version\":\"1.0\",\"task_slug\":\"false-bundle\",\"status\":\"delivered\",\"phase\":\"done\",\"updated_at\":\"2026-06-23T00:00:00Z\",\"next_action\":{\"status\":\"done\",\"summary\":\"done\"}}",
+    ".flow-agents/false-bundle/trust.bundle": "{\"schemaVersion\":3,\"source\":\"flow-agents/workflow-sidecar\",\"claims\":[{\"id\":\"c1\",\"subjectId\":\"false-bundle/unit-tests\",\"claimType\":\"workflow.check.command\",\"fieldOrBehavior\":\"unit tests\",\"value\":\"fail\",\"impactLevel\":\"high\",\"status\":\"disputed\",\"createdAt\":\"2026-06-23T00:00:00Z\",\"updatedAt\":\"2026-06-23T00:00:00Z\"}],\"evidence\":[],\"policies\":[],\"events\":[]}"
+  },
+  "env": {
+    "FLOW_AGENTS_GOAL_FIT_MODE": "block",
+    "FLOW_AGENTS_GOAL_FIT_BACKSTOP": "skip"
+  },
+  "expected": {
+    "exit_code": 2,
+    "stderr_contains": [
+      "trust.bundle claim disputed",
+      "caught false-completion"
+    ]
+  }
+}

package/packaging/conformance/fixtures/stop-goal-fit--block-capture-contradicts-claimed-pass.json

@@ -0,0 +1,30 @@
+{
+  "description": "stop-goal-fit blocks (exit 2) when the trust.bundle claims a command check passed but the deterministic capture log (command-log.jsonl) recorded that same command as FAIL \u2014 a caught false-completion (bundle-only; 4c)",
+  "policy_class": "stop-goal-fit",
+  "canonical_event": "stop",
+  "conformance_level": "L2",
+  "hook_id": "stop-goal-fit",
+  "hook_script": "stop-goal-fit.js",
+  "payload": {
+    "hook_event_name": "Stop",
+    "cwd": "__TEMP_WORKSPACE__"
+  },
+  "workspace_setup": {
+    "AGENTS.md": "# Test Repo\n",
+    ".flow-agents/false-pass/false-pass--deliver.md": "# False Pass\n\nbranch: main\nstatus: delivered\ntype: deliver\n\n## Definition Of Done\n- [x] tests pass\n\n## Goal Fit Gate\n- [x] acceptance verified\n\n### Verdict: PASS\n",
+    ".flow-agents/false-pass/state.json": "{\"schema_version\":\"1.0\",\"task_slug\":\"false-pass\",\"status\":\"delivered\",\"phase\":\"done\",\"updated_at\":\"2026-06-23T00:00:00Z\",\"next_action\":{\"status\":\"done\",\"summary\":\"done\"}}",
+    ".flow-agents/false-pass/command-log.jsonl": "{\"command\":\"npm test\",\"observedResult\":\"fail\",\"exitCode\":1,\"capturedAt\":\"2026-06-23T00:00:00Z\",\"source\":\"postToolUse-capture\"}\n",
+    ".flow-agents/false-pass/trust.bundle": "{\"schemaVersion\": 3, \"source\": \"flow-agents/workflow-sidecar\", \"claims\": [{\"id\": \"c1\", \"subjectId\": \"false-pass/unit-tests\", \"claimType\": \"workflow.check.command\", \"fieldOrBehavior\": \"unit tests\", \"value\": \"pass\", \"impactLevel\": \"high\", \"status\": \"verified\", \"createdAt\": \"2026-06-23T00:00:00Z\", \"updatedAt\": \"2026-06-23T00:00:00Z\"}], \"evidence\": [{\"id\": \"ev:c1\", \"claimId\": \"c1\", \"evidenceType\": \"test_output\", \"method\": \"validation\", \"sourceRef\": \"false-pass/command-log.jsonl\", \"excerptOrSummary\": \"unit tests\", \"observedAt\": \"2026-06-23T00:00:00Z\", \"collectedBy\": \"flow-agents/workflow-sidecar\", \"passing\": true, \"execution\": {\"runner\": \"bash\", \"label\": \"npm test\", \"isError\": false}}], \"policies\": [], \"events\": [{\"id\": \"evt:c1\", \"claimId\": \"c1\", \"status\": \"verified\", \"actor\": \"flow-agents/workflow-sidecar\", \"method\": \"validation\", \"evidenceIds\": [\"ev:c1\"], \"createdAt\": \"2026-06-23T00:00:00Z\", \"verifiedAt\": \"2026-06-23T00:00:00Z\"}]}"
+  },
+  "env": {
+    "FLOW_AGENTS_GOAL_FIT_MODE": "block",
+    "FLOW_AGENTS_GOAL_FIT_BACKSTOP": "skip"
+  },
+  "expected": {
+    "exit_code": 2,
+    "stderr_contains": [
+      "caught false-completion",
+      "npm test"
+    ]
+  }
+}

package/packaging/conformance/fixtures/stop-goal-fit--block-mode.json

@@ -0,0 +1,23 @@
+{
+  "description": "stop-goal-fit blocks (exit 2) when FLOW_AGENTS_GOAL_FIT_MODE=block for an active delivery artifact missing DOD and Goal Fit Gate",
+  "policy_class": "stop-goal-fit",
+  "canonical_event": "stop",
+  "conformance_level": "L2",
+  "hook_id": "stop-goal-fit",
+  "hook_script": "stop-goal-fit.js",
+  "payload": {
+    "hook_event_name": "Stop",
+    "cwd": "__TEMP_WORKSPACE__"
+  },
+  "workspace_setup": {
+    "AGENTS.md": "# Test Repo\n",
+    ".flow-agents/my-task/my-task--deliver.md": "# My Task\n\nbranch: main\nstatus: executing\ntype: deliver\n\n## Plan\n\nWork TBD.\n"
+  },
+  "env": {
+    "FLOW_AGENTS_GOAL_FIT_MODE": "block"
+  },
+  "expected": {
+    "exit_code": 2,
+    "stderr_contains": ["status:executing"]
+  }
+}

package/packaging/conformance/fixtures/stop-goal-fit--off-mode.json

@@ -0,0 +1,24 @@
+{
+  "description": "stop-goal-fit stays silent (exit 0, no stderr) when FLOW_AGENTS_GOAL_FIT_MODE=off even for an active incomplete delivery artifact",
+  "policy_class": "stop-goal-fit",
+  "canonical_event": "stop",
+  "conformance_level": "L1",
+  "hook_id": "stop-goal-fit",
+  "hook_script": "stop-goal-fit.js",
+  "payload": {
+    "hook_event_name": "Stop",
+    "cwd": "__TEMP_WORKSPACE__"
+  },
+  "workspace_setup": {
+    "AGENTS.md": "# Test Repo\n",
+    ".flow-agents/my-task/my-task--deliver.md": "# My Task\n\nbranch: main\nstatus: executing\ntype: deliver\n\n## Plan\n\nWork TBD.\n"
+  },
+  "env": {
+    "FLOW_AGENTS_GOAL_FIT_MODE": "off"
+  },
+  "expected": {
+    "exit_code": 0,
+    "stdout_echoes_input": true,
+    "stderr_is_empty": true
+  }
+}

package/packaging/conformance/fixtures/stop-goal-fit--warn-active-delivery.json

@@ -1,5 +1,5 @@
 {
-  "description": "stop-goal-fit warns (exit 0, stderr has warnings) for an active delivery artifact missing DOD and Goal Fit Gate",
+  "description": "stop-goal-fit warns (exit 0, stderr has warnings) for an active delivery artifact; validates the warn mode status signal fires without Builder heading checks",
   "policy_class": "stop-goal-fit",
   "canonical_event": "stop",
   "conformance_level": "L1",
@@ -13,9 +13,12 @@
     "AGENTS.md": "# Test Repo\n",
     ".flow-agents/my-task/my-task--deliver.md": "# My Task\n\nbranch: main\nstatus: executing\ntype: deliver\n\n## Plan\n\nWork TBD.\n"
   },
+  "env": {
+    "FLOW_AGENTS_GOAL_FIT_MODE": "warn"
+  },
   "expected": {
     "exit_code": 0,
     "stdout_echoes_input": true,
-    "stderr_contains": ["status:executing", "Definition Of Done", "Goal Fit Gate"]
+    "stderr_contains": ["status:executing"]
   }
 }

package/packaging/conformance/fixtures/stop-goal-fit--warn-no-bundle.json

@@ -0,0 +1,23 @@
+{
+  "description": "stop-goal-fit emits NOT_VERIFIED — warning (exit 2 in block mode) when a delivery session has neither trust.bundle nor state.json",
+  "policy_class": "stop-goal-fit",
+  "canonical_event": "stop",
+  "conformance_level": "L2",
+  "hook_id": "stop-goal-fit",
+  "hook_script": "stop-goal-fit.js",
+  "payload": {
+    "hook_event_name": "Stop",
+    "cwd": "__TEMP_WORKSPACE__"
+  },
+  "workspace_setup": {
+    "AGENTS.md": "# Test Repo\n",
+    ".flow-agents/my-task/my-task--deliver.md": "# My Task\n\nbranch: main\nstatus: executing\ntype: deliver\n\n## Plan\n\nWork in progress — no sidecars yet.\n"
+  },
+  "env": {
+    "FLOW_AGENTS_GOAL_FIT_MODE": "block"
+  },
+  "expected": {
+    "exit_code": 2,
+    "stderr_contains": ["NOT_VERIFIED —", "trust.bundle"]
+  }
+}

package/packaging/conformance/fixtures/workflow-steering--reground-active-prompt.json

@@ -0,0 +1,30 @@
+{
+  "description": "workflow-steering re-grounds an ordinary in_progress task (not just flagged states) at UserPromptSubmit so an in-flight goal survives long gaps and compaction",
+  "policy_class": "workflow-steering",
+  "canonical_event": "userPromptSubmit",
+  "conformance_level": "L1",
+  "hook_id": "workflow-steering",
+  "hook_script": "workflow-steering.js",
+  "payload": {
+    "hook_event_name": "UserPromptSubmit",
+    "cwd": "__TEMP_WORKSPACE__",
+    "prompt": "continue"
+  },
+  "workspace_setup": {
+    "AGENTS.md": "# Test Repo\n",
+    ".flow-agents/build-feature/state.json": {
+      "task_slug": "build-feature",
+      "status": "in_progress",
+      "phase": "execution",
+      "next_action": {
+        "summary": "Wire the auth middleware and add tests.",
+        "status": "in_progress",
+        "target_phase": "verification"
+      }
+    }
+  },
+  "expected": {
+    "exit_code": 0,
+    "stdout_contains": ["WORKFLOW STATE:", "STATE:", "build-feature", "in_progress"]
+  }
+}

package/packaging/conformance/fixtures/workflow-steering--reground-session-start.json

@@ -0,0 +1,30 @@
+{
+  "description": "workflow-steering re-grounds the active goal on SessionStart (which fires after context compaction and on resume), so the goal/phase/next-step survive context loss",
+  "policy_class": "workflow-steering",
+  "canonical_event": "sessionStart",
+  "conformance_level": "L1",
+  "hook_id": "workflow-steering",
+  "hook_script": "workflow-steering.js",
+  "payload": {
+    "hook_event_name": "SessionStart",
+    "cwd": "__TEMP_WORKSPACE__",
+    "source": "compact"
+  },
+  "workspace_setup": {
+    "AGENTS.md": "# Test Repo\n",
+    ".flow-agents/build-feature/state.json": {
+      "task_slug": "build-feature",
+      "status": "in_progress",
+      "phase": "execution",
+      "next_action": {
+        "summary": "Wire the auth middleware and add tests.",
+        "status": "in_progress",
+        "target_phase": "verification"
+      }
+    }
+  },
+  "expected": {
+    "exit_code": 0,
+    "stdout_contains": ["WORKFLOW STATE:", "STATE:", "build-feature"]
+  }
+}

package/packaging/conformance/run-conformance.js

@@ -35,7 +35,7 @@ const LEVEL_ORDER = ['L0', 'L1', 'L2'];
 const LEVEL_POLICY_CLASSES = {
   L0: new Set([]),               // L0: telemetry only — no policy fixtures required
   L1: new Set(['workflow-steering', 'stop-goal-fit']),
-  L2: new Set(['workflow-steering', 'stop-goal-fit', 'quality-gate', 'config-protection']),
+  L2: new Set(['workflow-steering', 'stop-goal-fit', 'quality-gate', 'config-protection', 'evidence-capture']),
 };
 
 // -----------------------------------------------------------------------

package/scripts/README.md

@@ -9,7 +9,6 @@ These files are stable launchers for TypeScript code compiled under `build/src/`
 | Wrapper | Compiled implementation |
 | --- | --- |
 | `build-universal-bundles.js` | `build/src/tools/build-universal-bundles.js` |
-| `filter-installed-packs.js` | `build/src/tools/filter-installed-packs.js` |
 | `generate-context-map.js` | `build/src/tools/generate-context-map.js` |
 | `kit.js` | `build/src/cli/kit.js` |
 | `pull-work-provider.js` | `build/src/cli/pull-work-provider.js` |
@@ -53,6 +52,7 @@ renamed, or changes category, update the table and the validator together.
 | `codex-telemetry-hook.js` | telemetry shim | `evals/integration/test_hook_category_behaviors.sh`, `evals/integration/test_telemetry.sh` | Captures Codex hook telemetry and fails open. |
 | `run-hook.js` | hook runner | `evals/integration/test_hook_category_behaviors.sh`, `evals/integration/test_goal_fit_hook.sh`, `evals/integration/test_workflow_steering_hook.sh` | Applies profile/disable flags, traversal checks, and hook execution. |
 | `config-protection.js` | policy hook | `evals/integration/test_hook_category_behaviors.sh` | Blocks unsafe runtime config edits. |
+| `evidence-capture.js` | policy hook | `evals/integration/test_evidence_capture_hook.sh` | Deterministically captures command executions to `.flow-agents/<slug>/command-log.jsonl` so evidence is machine-recorded, not model-claimed (cross-referenced by stop-goal-fit). |
 | `governance-audit.sh` | policy hook | `evals/integration/test_hook_category_behaviors.sh`, `evals/integration/test_telemetry.sh` | Emits governance/Veritas audit context when configured. |
 | `opencode-hook-adapter.js` | runtime adapter | `evals/integration/test_bundle_install.sh` | Translates opencode plugin events into the shared hook runner contract. |
 | `opencode-telemetry-hook.js` | telemetry shim | `evals/integration/test_bundle_install.sh` | Captures opencode plugin telemetry and fails open. |
@@ -69,6 +69,7 @@ renamed, or changes category, update the table and the validator together.
 | `desktop-notify.sh` | local notification helper | `evals/integration/test_hook_category_behaviors.sh` | Optional local desktop notification helper. |
 | `lib/audit-transport.sh` | shared hook library | `evals/integration/test_hook_category_behaviors.sh`, `evals/integration/test_telemetry.sh` | Shared audit event transport functions. |
 | `lib/hook-flags.js` | shared hook library | `evals/integration/test_hook_category_behaviors.sh` | Shared profile/disable flag parsing. |
+| `lib/liveness-read.js` | shared hook library | `evals/integration/test_session_resume_roundtrip.sh` | Shared liveness event reader + freshness check (`readLivenessEvents`, `freshHolders`); consumed by the reground hook and `workflow-sidecar liveness status`. |
 | `lib/patterns.sh` | shared hook library | `evals/integration/test_hook_category_behaviors.sh`, `evals/integration/test_telemetry.sh` | Shared shell pattern constants. |
 | `lib/resolve-formatter.js` | shared hook library | `evals/integration/test_hook_category_behaviors.sh` | Shared formatter resolution helper. |
 

package/scripts/build-universal-bundles.js

@@ -1,3 +1,2 @@
 #!/usr/bin/env node
-// Supports FLOW_AGENTS_PACKS through the TypeScript bundle builder.
 import("../build/src/tools/build-universal-bundles.js").then(({ main }) => process.exit(main()));