@kontourai/flow-agents 2.3.0 → 2.4.0

package/kits/veritas-governance/flows/readiness-check.flow.json

@@ -0,0 +1,35 @@
+{
+  "id": "veritas-governance.readiness-check",
+  "version": "1.0",
+  "steps": [
+    { "id": "readiness", "next": "gate-check" },
+    { "id": "gate-check", "next": null }
+  ],
+  "gates": {
+    "gate-check-gate": {
+      "step": "gate-check",
+      "expects": [
+        {
+          "id": "readiness-verdict",
+          "kind": "trust.bundle",
+          "required": true,
+          "description": "A `veritas readiness --check evidence --working-tree` run, projected by the kit adapter (adapter/readiness-to-trust-bundle.mjs) into a Hachure trust.bundle, produced a verified software-readiness-verdict claim for this change.",
+          "explore_hint": "Run `veritas readiness --check evidence --working-tree`, project its evidence report with adapter/readiness-to-trust-bundle.mjs, then `flow attach-evidence <run> --gate gate-check-gate --file <bundle> --bundle`.",
+          "bundle_claim": {
+            "claimType": "software-readiness-verdict",
+            "subjectType": "repository-change",
+            "accepted_statuses": ["verified"]
+          }
+        }
+      ],
+      "on_route_back": {
+        "missing_evidence": "gate-check",
+        "default": "gate-check"
+      },
+      "route_back_policy": {
+        "max_attempts": 3,
+        "on_exceeded": "block"
+      }
+    }
+  }
+}

package/kits/veritas-governance/kit.json

@@ -0,0 +1,16 @@
+{
+  "schema_version": "1.0",
+  "id": "veritas-governance",
+  "name": "Veritas Governance Kit",
+  "description": "Turns a repo's Veritas-governed Repo Standards into deterministic, agentless gate evidence: a single flow gates a real `veritas readiness` run as a trust.bundle software-readiness-verdict claim. Wraps @kontourai/veritas via CLI invocation and a kit-local trust.bundle adapter; does not fork or reimplement standards evaluation.",
+  "flows": [
+    {
+      "id": "veritas-governance.readiness-check",
+      "path": "flows/readiness-check.flow.json",
+      "description": "Single-gate agentless flow: requires a verified software-readiness-verdict trust.bundle claim (projected from `veritas readiness --check evidence --working-tree`) before the gate-check step can pass. CI-callable, K0."
+    }
+  ],
+  "docs": [
+    { "id": "veritas-governance.readme", "path": "docs/README.md" }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontourai/flow-agents",
-  "version": "2.3.0",
+  "version": "2.4.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",
@@ -91,6 +91,7 @@
     "!evals/results/",
     "!**/.DS_Store",
     "!**/.flow-agents/",
+    "!**/.kontourai/",
     "!**/.surface/",
     "!**/.telemetry/",
     "!**/.veritas/",
@@ -126,6 +127,7 @@
     "eval:static": "bash evals/run.sh static",
     "eval:integration": "bash evals/run.sh integration",
     "trust-reconcile-verify": "npm run build && npm run eval:static",
+    "trust-reconcile-manifest": "bash evals/ci/run-baseline.sh --manifest-json",
     "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",
@@ -133,6 +135,8 @@
     "promptfoo": "PROMPTFOO_CONFIG_DIR=.promptfoo PROMPTFOO_DISABLE_WAL_MODE=true PROMPTFOO_DISABLE_TELEMETRY=true promptfoo",
     "promptfoo:view": "PROMPTFOO_CONFIG_DIR=.promptfoo PROMPTFOO_DISABLE_WAL_MODE=true PROMPTFOO_DISABLE_TELEMETRY=true promptfoo view",
     "check:content-boundary": "node scripts/check-content-boundary.cjs",
+    "check:decisions": "node scripts/check-decisions.cjs check",
+    "gen:decisions-index": "node scripts/check-decisions.cjs gen-index",
     "prepack": "npm run build --silent && npm run validate:source --",
     "kit": "npm run build --silent && node build/src/cli.js kit"
   },
@@ -142,10 +146,10 @@
     "typescript": "^6.0.3"
   },
   "dependencies": {
-    "@kontourai/flow": "~1.4.1"
+    "@kontourai/flow": "^2.0.0"
   },
   "optionalDependencies": {
-    "hachure": "^0.5.1",
-    "@kontourai/surface": "^1.2.0"
+    "@kontourai/surface": "^2.0.0",
+    "hachure": "^0.9.0"
   }
 }

package/packaging/README.md

@@ -19,7 +19,7 @@ For the full source/generated/runtime inventory, see [Repository Structure](../d
 
 - `dist/kiro/` keeps native Kiro JSON agents and rewrites path-bound config through the install token.
 - `dist/claude-code/` exports `.claude/agents/*.md` and `.claude/skills/*/SKILL.md`.
-- `dist/codex/` exports `.codex/agents/*.toml`, `.codex/skills/*/SKILL.md`, and profile config for `kdev` and its Bedrock variant.
+- `dist/codex/` exports `.codex/agents/*.toml`, `.codex/skills/*/SKILL.md`, and generated profile config for operating intents such as `builder` and `personal`.
 
 All targets also receive shared canonical directories where supported: `context/`, `powers/`, `prompts/`, `scripts/`, and `evals/`.
 
@@ -29,7 +29,7 @@ All targets also receive shared canonical directories where supported: `context/
 
 `dist/` is a generated export surface, not the source of truth. Installed runtime directories such as `.codex/` and `.claude/` are also not source. They are created from the generated target bundle and installer scripts. If generated or installed hook config is wrong, fix the canonical source, rebuild `dist/`, and reinstall the runtime config.
 
-Runtime workflow state under `.flow-agents/<slug>/` is local working memory. Packaging should copy canonical workflow contracts and skills, but it should not publish local task artifacts as product source. Durable outcomes must be promoted into docs, source, schemas, or provider records before merge.
+Runtime workflow state under `.kontourai/flow-agents/<slug>/` is local working memory. Packaging should copy canonical workflow contracts and skills, but it should not publish local task artifacts as product source. Durable outcomes must be promoted into docs, source, schemas, or provider records before merge.
 
 ## Validation And Build
 

package/packaging/conformance/fixtures/config-protection--allow-read-state-json.json

@@ -0,0 +1,20 @@
+{
+  "description": "config-protection allows a read-only tool (Read) on a sidecar state.json — path protection must not block reads",
+  "policy_class": "config-protection",
+  "canonical_event": "preToolUse",
+  "conformance_level": "L2",
+  "hook_id": "config-protection",
+  "hook_script": "config-protection.js",
+  "payload": {
+    "hook_event_name": "PreToolUse",
+    "tool_name": "Read",
+    "tool_input": {
+      "path": "/repo/.kontourai/flow-agents/my-slug/state.json"
+    }
+  },
+  "expected": {
+    "exit_code": 0,
+    "stderr_is_empty": true,
+    "stdout_echoes_input": true
+  }
+}

package/packaging/conformance/fixtures/config-protection--block-write-state-json.json

@@ -0,0 +1,20 @@
+{
+  "description": "config-protection blocks a Write to a sidecar state.json and routes to the sanctioned sidecar writer (never advising the hook be disabled)",
+  "policy_class": "config-protection",
+  "canonical_event": "preToolUse",
+  "conformance_level": "L2",
+  "hook_id": "config-protection",
+  "hook_script": "config-protection.js",
+  "payload": {
+    "hook_event_name": "PreToolUse",
+    "tool_name": "Write",
+    "tool_input": {
+      "path": "/repo/.kontourai/flow-agents/my-slug/state.json"
+    }
+  },
+  "expected": {
+    "exit_code": 2,
+    "stderr_contains": ["BLOCKED", "advance-state", "Never disable this hook"],
+    "stdout_is_empty": true
+  }
+}

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

@@ -13,7 +13,7 @@
     "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\":[]}"
+    ".flow-agents/false-bundle/trust.bundle": "{\"schemaVersion\":5,\"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",

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

@@ -14,7 +14,7 @@
     ".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\"}]}"
+    ".flow-agents/false-pass/trust.bundle": "{\"schemaVersion\": 5, \"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",

package/packaging/manifest.json

@@ -25,14 +25,14 @@
     "install_default": "~/.flow-agents"
   },
   "claude_code": {
-    "task_dir": ".flow-agents",
+    "task_dir": ".kontourai/flow-agents",
     "permissions": {
       "defaultMode": "auto"
     },
     "skipDangerousModePermissionPrompt": true
   },
   "codex": {
-    "task_dir": ".flow-agents",
+    "task_dir": ".kontourai/flow-agents",
     "settings": {
       "approvals_reviewer": "auto_review"
     },
@@ -57,22 +57,21 @@
       "dev"
     ],
     "profiles": {
-      "kdev": {
+      "builder": {
         "model": "gpt-5.5",
         "model_reasoning_effort": "medium",
         "approval_policy": "on-request",
         "sandbox_mode": "workspace-write",
         "web_search": "cached",
-        "developer_instructions": "You are operating in Flow Agents dev mode. You write and modify code, validate it works, and deliver clean results. You own the code; specialist tool-* subagents provide bounded context, review, verification, or parallel implementation support. Use deliver for feature work, fix-bug for bug fixes, plan-work for planning, execute-plan for approved plans, review-work for critique, verify-work for evidence collection, search-first for unfamiliar external APIs, and context-budget when context grows. When a workflow skill or shared contract names a delegate, that delegate is a required gate, not an optional optimization: plan-work must delegate to tool-planner, execute-plan to tool-worker, review-work to tool-code-reviewer and conditionally tool-security-reviewer, verify-work to tool-verifier, and browser/UI verification to tool-playwright when those agents are available. Attempt required delegation even in read-only or partially blocked environments; if blocked, report the blocked gate as NOT_VERIFIED or incomplete with evidence instead of replacing it with a local summary. In progress and final reports, name exact delegate ids such as tool-planner, tool-worker, tool-code-reviewer, tool-security-reviewer, tool-verifier, and tool-playwright so text-only evals remain auditable when telemetry is unavailable. In Codex, required specialist delegation must pass the role through the spawn tool, for example agent_type=tool-worker; do not spawn unnamed/default subagents for Flow Agents worker, planner, reviewer, verifier, or Playwright gates."
+        "developer_instructions": "You are operating in Flow Agents Builder mode. You write and modify code, validate it works, and deliver clean results. You own the code; specialist tool-* subagents provide bounded context, review, verification, or parallel implementation support. Use deliver for feature work, fix-bug for bug fixes, plan-work for planning, execute-plan for approved plans, review-work for critique, verify-work for evidence collection, search-first for unfamiliar external APIs, and context-budget when context grows. When a workflow skill or shared contract names a delegate, that delegate is a required gate, not an optional optimization: plan-work must delegate to tool-planner, execute-plan to tool-worker, review-work to tool-code-reviewer and conditionally tool-security-reviewer, verify-work to tool-verifier, and browser/UI verification to tool-playwright when those agents are available. Attempt required delegation even in read-only or partially blocked environments; if blocked, report the blocked gate as NOT_VERIFIED or incomplete with evidence instead of replacing it with a local summary. In progress and final reports, name exact delegate ids such as tool-planner, tool-worker, tool-code-reviewer, tool-security-reviewer, tool-verifier, and tool-playwright so text-only evals remain auditable when telemetry is unavailable. In Codex, required specialist delegation must pass the role through the spawn tool, for example agent_type=tool-worker; do not spawn unnamed/default subagents for Flow Agents worker, planner, reviewer, verifier, or Playwright gates."
       },
-      "kdev-br": {
-        "model_provider": "amazon-bedrock",
-        "model": "amazon.nova-pro-v1:0",
+      "personal": {
+        "model": "gpt-5.4-mini",
         "model_reasoning_effort": "medium",
         "approval_policy": "on-request",
         "sandbox_mode": "workspace-write",
         "web_search": "cached",
-        "developer_instructions": "You are operating in Flow Agents dev mode on Amazon Bedrock. You write and modify code, validate it works, and deliver clean results. You own the code; specialist tool-* subagents provide bounded context, review, verification, or parallel implementation support. Use deliver for feature work, fix-bug for bug fixes, plan-work for planning, execute-plan for approved plans, review-work for critique, verify-work for evidence collection, search-first for unfamiliar external APIs, and context-budget when context grows. When a workflow skill or shared contract names a delegate, that delegate is a required gate, not an optional optimization: plan-work must delegate to tool-planner, execute-plan to tool-worker, review-work to tool-code-reviewer and conditionally tool-security-reviewer, verify-work to tool-verifier, and browser/UI verification to tool-playwright when those agents are available. Attempt required delegation even in read-only or partially blocked environments; if blocked, report the blocked gate as NOT_VERIFIED or incomplete with evidence instead of replacing it with a local summary. In progress and final reports, name exact delegate ids such as tool-planner, tool-worker, tool-code-reviewer, tool-security-reviewer, tool-verifier, and tool-playwright so text-only evals remain auditable when telemetry is unavailable. In Codex, required specialist delegation must pass the role through the spawn tool, for example agent_type=tool-worker; do not spawn unnamed/default subagents for Flow Agents worker, planner, reviewer, verifier, or Playwright gates."
+        "developer_instructions": "You are operating in Flow Agents Personal mode for email, knowledge work, research, writing, and lightweight automation. Keep durable notes and decisions easy to recover across sessions. Use knowledge-capture when the user asks you to remember, save, capture, file, or bookmark context, or when a source, decision, relationship detail, or reusable lesson should be indexed. Prefer concise synthesis, explicit source attribution when web research is used, and reversible changes to local files. For software work, switch back to Builder mode or explicitly use the Builder workflow skills so planning, review, and verification gates remain intact."
       }
     },
     "model_providers": {
@@ -223,10 +222,10 @@
     ]
   },
   "opencode": {
-    "task_dir": ".flow-agents",
+    "task_dir": ".kontourai/flow-agents",
     "default_agent_mode": "subagent"
   },
   "pi": {
-    "task_dir": ".flow-agents"
+    "task_dir": ".kontourai/flow-agents"
   }
 }

package/schemas/decision-record.schema.json

@@ -0,0 +1,109 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://flow-agents.dev/schemas/decision-record.schema.json",
+  "title": "Flow Agents Decision Record",
+  "description": "YAML frontmatter for a topic-keyed living decision record at docs/decisions/<topic-slug>.md. One file per decision SUBJECT. Supersession is an edit to this file; tombstones (superseded_by / merged_into) point at the slug that carries the current answer. Numbered ADRs under docs/adr are frozen history and are NOT validated by this schema.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["status", "subject", "decided", "evidence"],
+  "properties": {
+    "status": {
+      "type": "string",
+      "enum": ["current", "superseded", "merged", "needs-decision"],
+      "description": "current: this file holds the live answer for its subject. superseded: the subject moved to another topic slug (see superseded_by); this file is a tombstone. merged: the subject was folded into another topic slug (see merged_into); this file is a tombstone. needs-decision: a stub topic that names an open subject with no ratified answer yet (used by ADR freeze tooling, issue #314, to record that a frozen ADR's subject still needs a living decision). A needs-decision stub carries provenance evidence but no live decision body."
+    },
+    "subject": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The decision SUBJECT, a noun phrase drawn from the repository's CONTEXT.md domain vocabulary. The subject is the topic namespace; if the term is absent from CONTEXT.md, add it there first."
+    },
+    "decided": {
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+      "description": "ISO date (YYYY-MM-DD) the current decision was ratified. For needs-decision stubs, the date the stub was recorded."
+    },
+    "evidence": {
+      "type": "array",
+      "minItems": 1,
+      "description": "Derivation context is LINKED here, never inlined. Each ref points at durable provenance: an issue, a PR, an archived session artifact, or a frozen ADR. Secret-shaped literals are refused.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["kind", "ref"],
+        "properties": {
+          "kind": {
+            "type": "string",
+            "enum": ["issue", "pr", "commit", "session-archive", "adr", "doc", "url"],
+            "description": "issue/pr/commit: a GitHub reference (number, URL, or SHA). session-archive: a path to an archived session artifact under .kontourai/ that was promoted at retirement. adr: a frozen numbered ADR under docs/adr that is provenance for this decision. doc: a repository document path. url: an external permalink."
+          },
+          "ref": {
+            "type": "string",
+            "minLength": 1,
+            "description": "The reference literal. Must not contain secret-shaped material (access keys, tokens, private keys, JWTs).",
+            "not": {
+              "pattern": "(AKIA[A-Z0-9]{16}|ASIA[A-Z0-9]{16}|gh[pousr]_[A-Za-z0-9_]{36,}|BEGIN[A-Z ]*PRIVATE KEY|eyJ[A-Za-z0-9_-]{10,}\\.eyJ[A-Za-z0-9_-]{10,}\\.[A-Za-z0-9_-]{10,})"
+            }
+          }
+        }
+      }
+    },
+    "supersedes": {
+      "type": "array",
+      "description": "Optional. Topic slugs whose subjects this file absorbed (e.g. the surviving file of a merge lists the slugs it merged in). Each item must be a valid topic slug.",
+      "items": { "$ref": "#/$defs/slug" }
+    },
+    "superseded_by": {
+      "allOf": [{ "$ref": "#/$defs/slug" }],
+      "description": "Present only when status is superseded. The topic slug that now carries the current answer for this subject (the subject was renamed or split to a different topic)."
+    },
+    "merged_into": {
+      "allOf": [{ "$ref": "#/$defs/slug" }],
+      "description": "Present only when status is merged. The topic slug this subject was folded into."
+    }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "status": { "const": "current" } } },
+      "then": {
+        "not": {
+          "anyOf": [
+            { "required": ["superseded_by"] },
+            { "required": ["merged_into"] }
+          ]
+        }
+      }
+    },
+    {
+      "if": { "properties": { "status": { "const": "superseded" } } },
+      "then": {
+        "required": ["superseded_by"],
+        "not": { "required": ["merged_into"] }
+      }
+    },
+    {
+      "if": { "properties": { "status": { "const": "merged" } } },
+      "then": {
+        "required": ["merged_into"],
+        "not": { "required": ["superseded_by"] }
+      }
+    },
+    {
+      "if": { "properties": { "status": { "const": "needs-decision" } } },
+      "then": {
+        "not": {
+          "anyOf": [
+            { "required": ["superseded_by"] },
+            { "required": ["merged_into"] }
+          ]
+        }
+      }
+    }
+  ],
+  "$defs": {
+    "slug": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$",
+      "description": "A topic slug: lowercase kebab-case nouns from CONTEXT.md vocabulary. Resolves to docs/decisions/<slug>.md."
+    }
+  }
+}

package/schemas/workflow-evidence.schema.json

@@ -174,7 +174,7 @@
           },
           "kind": {
             "type": "string",
-            "enum": ["build", "types", "lint", "test", "security", "diff", "browser", "runtime", "policy", "external"]
+            "enum": ["build", "types", "lint", "test", "command", "security", "diff", "browser", "runtime", "policy", "external"]
           },
           "status": {
             "type": "string",

package/schemas/workflow-state.schema.json

@@ -36,6 +36,11 @@
     "owner": {
       "type": "string"
     },
+    "branch": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Routing branch for this session, e.g. agent/<actor>/<slug> (ADR 0021 \u00a73/\u00a75, issue #289). Optional for migration honesty: legacy/in-flight sessions predate this field. ensure-session always writes it for newly created sessions; validate-workflow-artifacts warns (does not fail) when it is absent."
+    },
     "created_at": {
       "type": "string",
       "format": "date-time"

package/scripts/README.md

@@ -52,7 +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). |
+| `evidence-capture.js` | policy hook | `evals/integration/test_evidence_capture_hook.sh` | Deterministically captures command executions to `.kontourai/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. |
@@ -67,10 +67,15 @@ renamed, or changes category, update the table and the validator together.
 | `workflow-steering.js` | policy hook | `evals/integration/test_workflow_steering_hook.sh` | Provides workflow guidance from current artifact state. |
 | `pre-commit-quality.js` | repo guardrail hook | `evals/integration/test_hook_category_behaviors.sh` | Supports repository Git hook checks, not installed runtime hooks. |
 | `desktop-notify.sh` | local notification helper | `evals/integration/test_hook_category_behaviors.sh` | Optional local desktop notification helper. |
+| `lib/actor-identity.js` | shared hook library | `evals/integration/test_actor_identity.sh` | Shared runtime-agnostic actor identity resolver (`resolveActor`) consumed by `workflow-steering.js` and `workflow-sidecar.js` to retire the shared `"local"` liveness-actor default (issue #287). |
 | `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/config-protection-remedies.js` | shared hook library | `evals/integration/test_hook_category_behaviors.sh` | Sanctioned-remedy table for `config-protection.js` (WS8/ADR 0020 extraction). |
 | `lib/hook-flags.js` | shared hook library | `evals/integration/test_hook_category_behaviors.sh` | Shared profile/disable flag parsing. |
+| `lib/liveness-heartbeat.js` | shared hook library | `evals/integration/test_liveness_heartbeat.sh` | Shared tool-activity liveness heartbeat (`maybeEmitHeartbeat`); rides `postToolUse` across all four telemetry hook wrappers, throttled and fail-open (issue #288). |
+| `lib/liveness-policy.js` | shared hook library | `evals/integration/test_workflow_sidecar_writer.sh`, `evals/integration/test_liveness_heartbeat.sh` | Shared liveness on/off predicate (`isLivenessEnabled`, default-on/opt-out) and TTL/heartbeat-throttle default resolution (issue #288). |
 | `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/local-artifact-paths.js` | shared hook library | `evals/integration/test_migrate_local_artifacts.sh`, `evals/integration/test_workflow_sidecar_writer.sh` | Shared `.kontourai/flow-agents` artifact-root helpers with legacy `.flow-agents` read compatibility for CJS hooks. |
+| `lib/liveness-write.js` | shared hook library | `evals/integration/test_workflow_sidecar_writer.sh`, `evals/integration/test_liveness_heartbeat.sh` | Shared liveness event stream writer (`livenessStreamFile`, `appendLivenessEvent`), lifted from `workflow-sidecar.ts` so the CLI and hook wrappers share one writer (issue #288). |
+| `lib/local-artifact-paths.js` | shared hook library | `evals/integration/test_migrate_local_artifacts.sh`, `evals/integration/test_workflow_sidecar_writer.sh` | Shared `.kontourai/flow-agents` artifact-root helpers for CJS hooks. |
 | `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. |
 
@@ -103,7 +108,7 @@ prompting. Add `--allow-network` to probe a non-local HTTPS Console endpoint.
 
 ## Install And Repo Utilities
 
-- `install-codex-home.sh`: installs the isolated generated Codex home.
+- `install-codex-home.sh`: installs the generated Codex bundle into `CODEX_HOME`, or `~/.codex` when `CODEX_HOME` is unset. A positional destination argument is the explicit override for isolated homes and tests.
 - `setup-repo-hooks.sh`: configures this clone's Git hook path.
 - `check-content-boundary.cjs`, `detect-tools.sh`, `discover-agents.sh`, `git-status.sh`: repo-local helper commands.
 - `context-budget/` and `statusline/`: specialized support tooling copied into bundles where needed.

package/scripts/check-content-boundary.cjs

@@ -42,7 +42,7 @@ function isIgnoredPath(filePath) {
 }
 
 function isWorkflowRuntimeArtifact(filePath) {
-  return filePath.startsWith(".flow-agents/");
+  return filePath.startsWith(".kontourai/flow-agents/") || filePath.startsWith(".flow-agents/");
 }
 
 function lineNumberFor(content, index) {