@kontourai/flow-agents 2.3.0 → 3.0.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": "3.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",
@@ -91,6 +91,7 @@
     "!evals/results/",
     "!**/.DS_Store",
     "!**/.flow-agents/",
+    "!**/.kontourai/",
     "!**/.surface/",
     "!**/.telemetry/",
     "!**/.veritas/",
@@ -109,6 +110,8 @@
     "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",
     "effective-backlog-settings": "npm run build --silent && node build/src/cli.js effective-backlog-settings",
+    "assignment-provider": "npm run build --silent && node build/src/cli.js assignment-provider",
+    "effective-assignment-provider-settings": "npm run build --silent && node build/src/cli.js effective-assignment-provider-settings",
     "pull-work-provider": "npm run build --silent && node build/src/cli.js pull-work-provider",
     "publish-change": "npm run build --silent && node build/src/cli.js publish-change",
     "promote-workflow-artifact": "npm run build --silent && node build/src/cli.js promote-workflow-artifact",
@@ -126,6 +129,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,19 +137,21 @@
     "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"
   },
   "devDependencies": {
-    "@types/node": "^26.0.1",
+    "@types/node": "^26.1.0",
     "promptfoo": "^0.121.17",
     "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/assignment-provider-settings.schema.json

@@ -0,0 +1,125 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://flow-agents.dev/schemas/assignment-provider-settings.schema.json",
+  "title": "Flow Agents Assignment Provider Settings",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version"],
+  "properties": {
+    "$schema": { "type": "string" },
+    "schema_version": { "const": "1.0" },
+    "defaults": { "$ref": "#/$defs/assignment_settings" },
+    "projects": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/project_assignment_settings" }
+    }
+  },
+  "anyOf": [{ "required": ["defaults"] }, { "required": ["projects"] }],
+  "$defs": {
+    "project_assignment_settings": {
+      "allOf": [
+        { "$ref": "#/$defs/assignment_settings" },
+        { "type": "object", "required": ["project"] }
+      ]
+    },
+    "assignment_settings": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["provider", "policy"],
+      "properties": {
+        "project": { "$ref": "#/$defs/project_match" },
+        "provider": { "$ref": "#/$defs/provider" },
+        "policy": { "$ref": "#/$defs/policy" }
+      }
+    },
+    "project_match": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["repo"],
+      "properties": {
+        "repo": { "$ref": "#/$defs/repo" },
+        "paths": { "type": "array", "items": { "type": "string", "minLength": 1 } }
+      }
+    },
+    "provider": {
+      "oneOf": [
+        { "$ref": "#/$defs/github_provider" },
+        { "$ref": "#/$defs/local_file_provider" }
+      ]
+    },
+    "github_provider": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "repo", "capabilities"],
+      "properties": {
+        "kind": { "const": "github" },
+        "repo": { "$ref": "#/$defs/repo" },
+        "capabilities": { "$ref": "#/$defs/capabilities" }
+      }
+    },
+    "local_file_provider": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "capabilities"],
+      "properties": {
+        "kind": { "const": "local-file" },
+        "capabilities": { "$ref": "#/$defs/capabilities" }
+      }
+    },
+    "policy": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["label_name", "claim_comment_marker", "human_assignee_policy"],
+      "properties": {
+        "label_name": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Label attached to a claimed subject on providers that support labels. Default: \"agent:claimed\"."
+        },
+        "claim_comment_marker": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Fixed marker used to locate the machine-readable claim comment among human comments. Default: \"<!-- flow-agents:assignment-claim -->\"."
+        },
+        "human_assignee_policy": { "$ref": "#/$defs/human_assignee_policy" },
+        "comment_refresh_on_phase_transition": {
+          "type": "boolean",
+          "description": "Whether an explicit render-claim/render-supersede call at a phase transition also refreshes the claim comment body. Default: false. No new mechanism; this reuses the same render path already built for claim."
+        }
+      }
+    },
+    "human_assignee_policy": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["behavior", "idle_threshold_days"],
+      "properties": {
+        "behavior": {
+          "enum": ["ask_first", "never_reclaim"],
+          "description": "Default: \"ask_first\". A human assignee is never auto-superseded regardless of this value; this knob only governs whether idle human assignments are ever surfaced for possible reclaim confirmation (ask_first) or left untouched (never_reclaim)."
+        },
+        "idle_threshold_days": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Days of no linked activity before an idle human assignment is surfaced for confirmation. Default: 3."
+        }
+      }
+    },
+    "capabilities": {
+      "type": "array",
+      "items": {
+        "enum": ["assignees", "labels", "comments"]
+      },
+      "uniqueItems": true
+    },
+    "repo": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["owner", "name"],
+      "properties": {
+        "owner": { "type": "string", "minLength": 1 },
+        "name": { "type": "string", "minLength": 1 },
+        "url": { "type": "string" }
+      }
+    }
+  }
+}

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/knowledge/edge.schema.json

@@ -0,0 +1,54 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://flow-agents.dev/schemas/knowledge/edge.schema.json",
+  "title": "Knowledge Graph Edge",
+  "description": "A typed, directed edge between two nodes. The edge-type vocabulary is CLOSED (unlike node types): supersedes, merged-into, blocks, evidence-of, mentions, relates. Every edge carries provenance. The `to` endpoint MAY reference a node that is not present in the graph (an external or dangling reference); `resolved` records whether the provider expects the target to resolve, which the dependency-link-integrity health verb uses to separate deliberate external refs from broken links.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["id", "type", "from", "to", "provenance"],
+  "properties": {
+    "id": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Provider-scoped stable identifier for the edge."
+    },
+    "type": {
+      "type": "string",
+      "enum": ["supersedes", "merged-into", "blocks", "evidence-of", "mentions", "relates"],
+      "description": "supersedes: from replaces to. merged-into: from was folded into to. blocks: from must complete before to. evidence-of: from is provenance/evidence for to. mentions: from references to in prose. relates: general undirected-ish association."
+    },
+    "from": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Source node id."
+    },
+    "to": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Target node id. MAY be a node id not present in the graph when `resolved` is false (external ref)."
+    },
+    "resolved": {
+      "type": "boolean",
+      "description": "true (default when omitted) means the provider expects `to` to resolve to a node in the same graph; a missing target is then a broken link. false means `to` is a deliberate external reference (e.g. evidence-of a PR outside the store) and MUST NOT be flagged as broken."
+    },
+    "attributes": {
+      "type": "object",
+      "description": "Provider-specific structured fields for the edge."
+    },
+    "provenance": { "$ref": "#/$defs/provenance" }
+  },
+  "$defs": {
+    "provenance": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["provider", "source", "retrieved_at"],
+      "properties": {
+        "provider": { "type": "string", "minLength": 1 },
+        "source": { "type": "string", "minLength": 1 },
+        "locator": { "type": "string" },
+        "retrieved_at": { "type": "string", "minLength": 1 },
+        "agent": { "type": "string" }
+      }
+    }
+  }
+}

package/schemas/knowledge/health-report.schema.json

@@ -0,0 +1,45 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://flow-agents.dev/schemas/knowledge/health-report.schema.json",
+  "title": "Knowledge Health Report",
+  "description": "The schema-valid output of a provider-agnostic health verb (duplicate detection, dependency-link integrity). The same report shape is produced regardless of which provider supplied the graph, which is what lets one health command run identically over vault, git-repo, and work-item.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "check", "provider", "generated_at", "summary", "findings"],
+  "properties": {
+    "schema_version": { "const": "1.0" },
+    "check": {
+      "type": "string",
+      "enum": ["duplicate-detection", "dependency-link-integrity"],
+      "description": "Which health verb produced the report."
+    },
+    "provider": { "type": "string", "minLength": 1, "description": "Provider id the graph was read from." },
+    "generated_at": { "type": "string", "minLength": 1 },
+    "summary": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["nodes_examined", "edges_examined", "finding_count"],
+      "properties": {
+        "nodes_examined": { "type": "integer" },
+        "edges_examined": { "type": "integer" },
+        "finding_count": { "type": "integer" }
+      }
+    },
+    "findings": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["kind", "severity", "message", "evidence"],
+        "properties": {
+          "kind": { "type": "string", "minLength": 1 },
+          "severity": { "type": "string", "enum": ["info", "warning", "error"] },
+          "node_ids": { "type": "array", "items": { "type": "string" } },
+          "edge_ids": { "type": "array", "items": { "type": "string" } },
+          "message": { "type": "string", "minLength": 1 },
+          "evidence": { "type": "object" }
+        }
+      }
+    }
+  }
+}