@kontourai/flow-agents 2.4.0 → 3.0.0

package/context/contracts/artifact-contract.md

@@ -1,5 +1,7 @@
 # Workflow Artifact Contract
 
+> Read [`context/contracts/standing-directives.md`](standing-directives.md) — ratified owner directives that override default engineering conservatism.
+
 Workflow artifacts are the resumable local handoff surface between orchestrators, workers, verifiers, hooks, evals, and future sessions.
 
 ## Artifact Root

package/context/contracts/assignment-provider-contract.md

@@ -0,0 +1,239 @@
+# Assignment Provider Contract
+
+This contract defines the provider-neutral vocabulary for durable work-item ownership: who has
+claimed a subject, how that claim is represented, and how it is read back safely. It formalizes
+[ADR 0021: Assignment Leases and Stale-Claim Takeover](../../docs/adr/0021-assignment-leases-and-stale-claim-takeover.md)
+as the third provider leg beside `WorkItemProvider` and `BoardProvider`
+(`context/contracts/work-item-contract.md`) and `ChangeProvider`. GitHub is the first concrete
+mapping for this contract, not the generic vocabulary — Linear, Jira, GitLab, and a local-file
+provider for tracker-less repos and evals all map the same operations.
+
+## Terminology: three distinct "claim" concepts
+
+This repository uses the word "claim" for three unrelated things. Always qualify in prose; never
+write bare "claim" where the meaning is not obvious from surrounding context:
+
+| Term | Layer | Meaning | Where it lives |
+| --- | --- | --- | --- |
+| **assignment claim** | this contract | Durable, provider-recorded ownership of a work item | `AssignmentProvider.claim()`, this doc |
+| **liveness claim** | ADR 0012 | Ephemeral, TTL-reaped presence/heartbeat event | `liveness claim` (`workflow-sidecar.ts`), `freshHolders` (`liveness-read.js`) |
+| **trust claim** | ADR 0010 / ADR 0017 | A Hachure `trust.bundle` evidence claim (kit-typed, verification status) | `workflow-sidecar.ts claim <id> <dir>` (`claimLookup`) |
+
+An assignment claim's *effective state* is never computed from the assignment layer alone — it is
+always joined against a liveness claim's freshness (see the join table below).
+
+## AssignmentProvider Operations
+
+Provider-neutral interface, verbatim from ADR 0021 §2:
+
+```
+AssignmentProvider:
+  claim(subjectId, actor, meta)         # assign + attach machine-readable claim record
+  release(subjectId, actor, meta)       # unassign + handoff note
+  supersede(subjectId, from, to, meta)  # reassign with audit trail
+  status(subjectId) -> {assignee?, actor?, claimedAt?, meta?}
+  list(actor?) -> [subjectId]
+```
+
+| Operation | Arguments | Effect | Returns |
+| --- | --- | --- | --- |
+| `claim` | `subjectId`, `actor`, `meta` | Records durable ownership: assignee (or local-file record), a claim marker, and a versioned claim record carrying the full actor struct. | void (caller re-reads via `status` to confirm) |
+| `release` | `subjectId`, `actor`, `meta` | Clears durable ownership and leaves a handoff note. Normally invoked by the incumbent actor at clean session end. | void |
+| `supersede` | `subjectId`, `from`, `to`, `meta` | Reassigns ownership from a lapsed actor to a successor, with an audit-trail note explaining why (staleness, explicit human confirmation). | void |
+| `status` | `subjectId` | Reads current assignment state without joining liveness. | `{ assignee?, actor?, claimedAt?, meta? }` — the raw assignment-layer read |
+| `list` | `actor?` (optional filter) | Enumerates subject ids currently claimed, optionally filtered to one actor. | `[subjectId]` |
+
+`status()` alone is **assignment-layer truth only** — it does not tell a caller whether the claim
+is fresh. Callers that need to decide "is this work available" must compute the join described
+next, not call `status()` in isolation.
+
+**Actor identity is runtime-agnostic**: `{ runtime, session_id, host, human? }`. Claude Code,
+codex, opencode, and pi sessions, and humans, are all actors. Reuse the exact struct
+`scripts/hooks/lib/actor-identity.js`'s `resolveActor`/`serializeActor` already define — do not
+fork a second actor concept. `subject_id` reuses `workItemSlug`'s `owner/repo#id` convention
+(the same string the deterministic session slug derives from) rather than inventing a second
+identifier scheme.
+
+## The assignment ⋈ liveness join
+
+Effective claim state is always a **join** of two layers with distinct jobs. Neither layer is
+trusted alone:
+
+| Layer | Records | Lifetime | Medium |
+| --- | --- | --- | --- |
+| **Assignment** | intent / ownership | durable, survives crashes | provider (issue assignee/label/comment, or local-file record) |
+| **Liveness** | presence / freshness | ephemeral, TTL-reaped | ADR 0012 claim stream (`freshHolders`) |
+
+Readers compute the join from `{ assignment: AssignmentStatus, freshHolders: FreshHolder[] }` to
+one of five effective states:
+
+| Assignment | Liveness | Effective state | `pull-work` treatment |
+| --- | --- | --- | --- |
+| assigned | fresh heartbeat | **held** | excluded |
+| assigned | stale / absent | **reclaimable** | offered, via takeover protocol (ADR 0021 §5, out of this contract's scope) |
+| assigned (human) | n/a (humans don't heartbeat) | **human-held** | surfaced, never auto-taken (see below) |
+| unassigned | fresh (claim only) | **held** (assignment lagging) | excluded |
+| unassigned | absent | **free** | offered |
+
+This join rule is what makes lost locks structurally impossible: staleness — not assignment — is
+what excludes, so an orphaned assignee/label/record from a dead session can never gate work.
+
+The join is a pure function; reuse `scripts/hooks/lib/liveness-read.js`'s exported
+`freshHolders(events, slug, selfActor, nowMs)` for the liveness half rather than re-implementing
+TTL/staleness arithmetic. The join table itself (assignment status × liveness freshness →
+effective state) is the only new logic — it has no other implementation in this repository.
+
+## Lazy-correction transition table
+
+Nothing updates the provider on a timer; every mutation has a responsible actor, invoked at a
+specific lifecycle moment (ADR 0021 §4). This table names every transition for completeness; it
+also records which issue implements each row so a future reader does not assume any single issue
+delivers all four:
+
+| Transition | Mutator | When | Owning issue |
+| --- | --- | --- | --- |
+| `claim` | the claiming session | at selection | **#290 (this issue)** |
+| `clean_release` | the incumbent (Stop hook / terminal `advance-state`) | session end — unassign + handoff comment | #292 |
+| `supersede` | the successor, inside the takeover protocol | after the grace beat | #294 |
+| `crash_no_successor` | nobody, initially; corrected by the next actor to want the subject, or the janitor | lazily, or on a janitor sweep | out of scope — the Console relay's first cross-machine duty (ADR 0021 §4/§7) |
+
+Lazy correction is *safe* by the join rule above (stale assignment excludes nothing), but leaves
+the human-visible board stale in the crash case until the next claim attempt or a janitor sweep
+corrects it.
+
+## Human-assignee ask-first policy
+
+Humans do not heartbeat, so `assigned-to-human + no-liveness` is **normal, not stale** — it must
+never be treated as `reclaimable`. Agents surface idle human assignments ("assigned to `brian` 3
+days ago, no linked activity — reclaim?") and act only on explicit confirmation.
+
+- Default behavior: `ask_first`.
+- The threshold (`idle_threshold_days`, default `3`, matching ADR 0021 §6's own illustrative
+  example) and behavior (`ask_first` | `never_reclaim`) are a policy knob in
+  `assignment-provider-settings.schema.json` (`policy.human_assignee_policy`), not a hardcoded
+  constant.
+- **Non-goal:** never auto-supersede a human. The join function must gate on the actor struct's
+  `human` field being present (not absent/null) — never on a heuristic over the GitHub login name
+  — so a human assignee is always classified `human-held`, regardless of idle duration, and is
+  never silently reclaimed by any automated path.
+- This contract and its settings schema define the policy knob and the read-side data a caller
+  needs to surface the question (assignee identity, idle duration). The actual "ask the user"
+  interaction belongs to whichever skill consumes the join result (`pull-work`), which records it
+  as an alignment question rather than a new UI surface.
+
+## Versioned claim-record format
+
+The durable claim record is a single JSON object, versioned via `schema_version` so a reader can
+detect an incompatible future shape before parsing fields it does not understand:
+
+```json
+{
+  "schema_version": "1.0",
+  "role": "AssignmentClaimRecord",
+  "subject_id": "kontourai/flow-agents#290",
+  "actor": { "runtime": "claude-code", "session_id": "...", "host": "...", "human": null },
+  "claimed_at": "2026-07-02T00:00:00Z",
+  "ttl_seconds": 1800,
+  "branch": "agent/<actor>/<slug>",
+  "artifact_dir": ".kontourai/flow-agents/<slug>",
+  "status": "claimed"
+}
+```
+
+| Field | Required | Description |
+| --- | --- | --- |
+| `schema_version` | yes | Version of this record shape, `"1.0"`. |
+| `role` | yes | Constant `"AssignmentClaimRecord"`, for readers scanning mixed content (e.g. a GitHub comment thread) for this record type. |
+| `subject_id` | yes | The claimed work item, in `owner/repo#id` form — the same string `workItemSlug` derives the deterministic session slug from. |
+| `actor` | yes | `{ runtime, session_id, host, human? }` — the exact struct `actor-identity.js` defines. `human` is set (non-null) only for a human assignee; its presence, not a username heuristic, gates the human-held join state. |
+| `claimed_at` | yes | ISO-8601 timestamp the claim was recorded. Mirrors the liveness stream's own claim-event field so a reader compares freshness with one mental model across both layers, even though the two are stored in different media. |
+| `ttl_seconds` | yes | Same field name/semantics as the liveness stream's `ttlSeconds` (default `1800`). |
+| `branch` | yes | The branch this actor is working on, per the `agent/<actor>/<slug>` convention. |
+| `artifact_dir` | yes | The deterministic workflow artifact directory for this subject, so a successor inherits the same session. |
+| `status` | yes | `"claimed"` today; future transitions may add `"released"` / `"superseded"` values as the corresponding mutator (see the transition table) is implemented. |
+
+**Versioning rule:** bump `schema_version` only on an incompatible change (matching
+`artifact-contract.md`'s existing sidecar rule: "Keep `schema_version` at `1.0` until the schema
+changes incompatibly"). Additive, optional fields do not require a bump.
+
+### GitHub mapping
+
+The GitHub implementation represents the record as:
+
+- **assignee**: the notification/board hook.
+- **a single `agent:claimed` label** (default name, configurable via
+  `policy.label_name`): the board filter.
+- **a machine-readable claim comment**: human-readable prose above a fenced JSON block containing
+  the record above, located via a fixed marker (default
+  `<!-- flow-agents:assignment-claim -->`, configurable via `policy.claim_comment_marker`) so the
+  board stays legible to a human without tooling, while remaining machine-parseable.
+
+The comment carries identity because the assignee field cannot: N agent sessions typically share
+one GitHub account, so per-session identity lives in the attached record. Each provider decides
+what it can natively represent versus what goes in the record.
+
+### local-file mapping
+
+For tracker-less repos and evals, the same record is written to a JSON file under the artifact
+root (`<artifact-root>/assignment/<sanitized-subject-id>.json`), full read-modify-write, no
+external process involved. This path is the one that does real I/O inside the CLI, since there is
+no external mutation to defer to a skill.
+
+**`--actor-json` asymmetry (fix-plan iteration 1, F5, intentional):** local-file `claim`/`release`
+falls back to auto-resolving the actor from the live environment (`resolveActor(process.env)`) when
+`--actor-json` is omitted; `render-claim`/`render-supersede` (GitHub) always require `--actor-json`
+explicitly and fail loud without it. This is intentional, not a footgun to fix later — the
+currently-wired `pull-work` skill always passes `--actor-json` for both provider kinds, so the
+asymmetry has no effect on the shipped path today, but a future direct-CLI caller relying on
+local-file `claim` to fail the same way `render-claim` does when the actor can't be determined
+should pass `--actor-json` explicitly rather than relying on the auto-resolve fallback.
+
+## Implementation Note
+
+`schemas/assignment-provider-settings.schema.json` is the settings schema companion to this
+contract — it configures `provider.kind` (`github` | `local-file`), the label name, the claim
+comment marker, and the human-assignee policy knob described above.
+
+The GitHub write path follows this repository's `publish-change-helper.ts` precedent — **render,
+don't execute**: the CLI emits the exact, deterministic `gh` argv and comment body for a mutation
+as a pure function; the calling skill runs that exact argv via its Bash tool (never freehand `gh`
+text), then re-fetches and feeds the result back into the CLI's `status` parser to close the round
+trip. This is a deliberate divergence from a literal "CLI shells out to `gh` itself" design: it
+matches the one existing same-shaped precedent in this repository, keeps operational concerns
+(auth, rate limiting, retries, partial-failure sequencing across separate `gh` calls) at the skill
+layer where Bash-tool error handling already lives, and avoids introducing this repository's first
+`execFileSync`-to-`gh` code path inside compiled code without a dedicated decision. A future
+implementer of the GitHub mutation path should read this note, not re-derive the reasoning from
+scratch — see the `#290` plan artifact's Design Decision 1 for the full evidence trail if more
+detail is needed.
+
+**`gh_commands` execution contract (fix-plan iteration 1, F4):** every `render-*` subcommand's
+`gh_commands` field is a JSON array of **argv arrays** (one element per `gh` argument), not a
+shell-command string. The calling skill MUST execute each entry as argv — every element passed as
+its own separate Bash-tool argument — and MUST NOT concatenate the elements into a single shell
+string or run them via `bash -c`/shell re-interpretation. This matters specifically because
+`claim_comment_body` (and, for `render-supersede`, `previous_record`) can carry attacker-influenced
+text: any GitHub user who can comment on the issue can post a forged claim-marker comment (see the
+sanitization note below), and reconstructing a shell string from that content would reintroduce a
+shell-injection surface the render/execute split is designed to avoid. This is stated explicitly in
+`kits/builder/skills/pull-work/SKILL.md`'s "Assignment Claim On Selection" section as well — this
+paragraph is the contract-side mirror of that instruction, not a duplicate source of truth to drift
+from it.
+
+**Untrusted claim-record fields (fix-plan iteration 1, F2):** `extractClaimRecord()` parses the
+fenced JSON claim record out of *any* issue comment matching the claim marker — posting a comment
+requires no elevated access, unlike the assignee/label mutations this contract otherwise gates. Its
+returned record's string fields (`subject_id`, `branch`, `artifact_dir`, `actor.*`, including
+`actor.human`, and each `audit_trail` entry's actor/`reason`) are therefore treated as untrusted
+display input and are run through a control-character-strip + length-cap sanitizer (mirroring
+`workflow-sidecar.ts`'s `stripControlCharsForDisplay`, the established #287/#320 mitigation for
+this input class) before they leave the module in `status`/`list` output. This is display-only — it
+never changes the assignment ⋈ liveness join's classification logic, only the surfaced string
+content.
+
+No part of this system writes to the provider on a timer or heartbeats to it (ADR 0021 §4/§7).
+Every write is triggered by a specific lifecycle moment named in the transition table above. The
+one optional exception is a comment-body refresh at an explicit phase transition
+(`policy.comment_refresh_on_phase_transition`, default `false`) — cheap because it reuses the same
+render path already built for `claim`, just called again with an updated `status`/`claimed_at`
+field.

package/context/contracts/builder-kit-workflow-state-contract.md

@@ -1,5 +1,7 @@
 # Builder Kit Workflow State Contract
 
+> Read [`context/contracts/standing-directives.md`](standing-directives.md) — ratified owner directives that override default engineering conservatism.
+
 This contract defines the durable routing state for Builder Kit build-flow pickup and resume. It keeps `state.json` limited to canonical Flow Agents workflow routing and stores rich pickup decisions in a documented Probe record sidecar referenced by `state.json`, `handoff.json`, and the session artifact.
 
 Builder Kit owns product-level build-flow coordination. Flow Agents owns the workflow harness, artifact conventions, primitive execution, and evidence gates. Flow remains the owner of Flow gate semantics. Builder Kit contracts may route to Flow Agents primitives, but must not redefine pass, fail, approval, or release authority semantics.

package/context/contracts/decision-registry-contract.md

@@ -1,5 +1,7 @@
 # Decision Registry Contract
 
+> Read [`context/contracts/standing-directives.md`](standing-directives.md) — ratified owner directives that override default engineering conservatism.
+
 Normative contract for the topic-keyed decision registry. This is the source of
 truth for how NEW decisions are recorded in a Kontour repository. Numbered ADRs
 under `docs/adr/` are frozen history and are never written for new decisions

package/context/contracts/delivery-contract.md

@@ -1,5 +1,7 @@
 # Delivery Contract
 
+> Read [`context/contracts/standing-directives.md`](standing-directives.md) — ratified owner directives that override default engineering conservatism.
+
 Delivery chains planning, execution, review, verification, Goal Fit, and final acceptance until the user-facing goal is genuinely handled.
 
 ## Workflow

package/context/contracts/execution-contract.md

@@ -1,5 +1,7 @@
 # Execution Contract
 
+> Read [`context/contracts/standing-directives.md`](standing-directives.md) — ratified owner directives that override default engineering conservatism.
+
 Execution turns an approved plan artifact into code and local evidence while preserving parallel safety.
 
 ## Required Inputs
@@ -42,6 +44,29 @@ Execution may upgrade to a stronger mode when risk increases. Downgrades require
 - Worker delegation must name the exact worker role (`tool-worker`) rather than spawning an unnamed/default implementation agent.
 - After each wave, collect results, check conflicts, and update the session artifact before starting the next wave.
 
+## Delegation: Model Routing
+
+Model-routing policy is data, not code: `.datum/config.json` (schema:
+`@kontourai/datum`, provider/role registry) is the source of truth for which
+model backs which delegate role. This contract only says where to read it.
+
+- When spawning a delegate, resolve its role via `npx @kontourai/datum resolve <role> --json`
+  (or the `@kontourai/datum` library's `resolve()`) and pass the resolved
+  `model` explicitly to the delegate invocation. Do not hardcode a model name
+  in a skill, agent definition, or generated file — the role name is the
+  stable reference; the model it resolves to can change without touching
+  delegation call sites.
+- Role selection follows task shape, not delegate identity: fully-specified
+  mechanical tasks resolve `delegate-mechanical`; precisely-planned
+  implementation tasks resolve `delegate-implementation`; tasks needing design
+  latitude resolve `delegate-design`. The orchestrator's own model (planning,
+  gates, adversarial verification) resolves `orchestrator`, typically inherited
+  rather than overridden.
+- When `datum` (the CLI/library) or `.datum/config.json` is absent or a role
+  fails to resolve, fall back to the runtime's inherited model and note the
+  fallback in the session/task artifact — do not block delegation on datum
+  being present.
+
 ## Completion Rules
 
 Execution is complete only when:

package/context/contracts/governance-adapter-contract.md

@@ -1,5 +1,7 @@
 # Governance Adapter Contract
 
+> Read [`context/contracts/standing-directives.md`](standing-directives.md) — ratified owner directives that override default engineering conservatism.
+
 Governance adapters let Flow Agents ask an external tool for policy, proof, or trust evidence without baking repo-specific policy into Flow Agents core.
 
 ## Boundary

package/context/contracts/knowledge-store-contract.md

@@ -0,0 +1,197 @@
+# Knowledge Store Provider Contract
+
+Normative contract for the Knowledge Kit's typed graph MODEL and its pluggable
+storage/sync PROVIDERS. The model (nodes, edges, provenance) is owned by the Kit;
+storage and synchronisation are provider concerns. The same ingest/link/health
+verbs run over every provider, so backlog hygiene is a knowledge-health pass over
+the work-item provider rather than a bespoke tool.
+
+Machine-checkable structure lives in `schemas/knowledge/*.schema.json`
+(`node`, `edge`, `proposal`, `health-report`). Reference implementations live in
+`kits/knowledge/providers/` (markdown-vault, git-repo, work-item) with health
+verbs in `kits/knowledge/providers/health/` and the conformance suite in
+`kits/knowledge/providers/conformance/`.
+
+This contract applies the portfolio provider pattern (hachure format/adapters;
+Builder Kit work-item contract/providers) to knowledge, which until now was fused
+to one storage shape (the markdown vault).
+
+## 1. Graph model
+
+### 1.1 Node
+
+A node is a typed, identified unit of knowledge. Validated by
+`schemas/knowledge/node.schema.json`.
+
+| Field | Required | Meaning |
+| --- | --- | --- |
+| `id` | yes | Provider-scoped stable id, unique within a single `readGraph` result. |
+| `type` | yes | Node type (see §1.3). EXTENSIBLE. |
+| `title` | yes | Human-readable title; the basis for duplicate detection. |
+| `body` | no | Primary content; format is provider/type-specific. |
+| `attributes` | no | Provider-specific structured fields (issue state/labels, decision status, note category/tags). |
+| `provenance` | yes | Where this node was read from (§1.4). |
+
+### 1.2 Edge
+
+An edge is a typed, directed relationship. Validated by
+`schemas/knowledge/edge.schema.json`.
+
+| Field | Required | Meaning |
+| --- | --- | --- |
+| `id` | yes | Provider-scoped stable edge id. |
+| `type` | yes | One of the CLOSED edge vocabulary (§1.3). |
+| `from` | yes | Source node id. |
+| `to` | yes | Target node id. |
+| `resolved` | no | `true` (default) means `to` is expected to resolve to a node in the same graph (an internal dependency link); `false` marks a deliberate external reference (e.g. `evidence-of` a PR outside the store). |
+| `attributes` | no | Provider-specific structured fields. |
+| `provenance` | yes | Where this edge was derived from (§1.4). |
+
+### 1.3 Vocabularies
+
+**Node types are EXTENSIBLE.** The recommended core vocabulary is `note`,
+`decision`, `issue`, `session`, `person`. Providers MAY emit additional types;
+consumers MUST NOT reject unknown node types.
+
+**Edge types are CLOSED** (schema-enforced enum):
+
+| Edge type | Direction | Meaning |
+| --- | --- | --- |
+| `supersedes` | from → to | `from` replaces `to`. |
+| `merged-into` | from → to | `from` was folded into `to`. |
+| `blocks` | from → to | `from` must complete before `to`. |
+| `evidence-of` | from → to | `from` is provenance/evidence for `to`. |
+| `mentions` | from → to | `from` references `to` in prose. |
+| `relates` | from → to | General association. |
+
+Adding an edge type is a contract change (schema + this table), because health
+verbs reason over the closed vocabulary (e.g. `blocks` is the dependency-link
+relation).
+
+### 1.4 Provenance
+
+Provenance appears on BOTH nodes and edges. Every assertion in the graph is
+traceable back to the store it came from — no orphan facts.
+
+| Field | Required | Meaning |
+| --- | --- | --- |
+| `provider` | yes | Provider id that produced the element. |
+| `source` | yes | Concrete origin: a file path, an issue ref, or a URL. |
+| `locator` | no | Finer locator (line, anchor, frontmatter field, link kind). |
+| `retrieved_at` | yes | ISO-8601 read timestamp. |
+| `agent` | no | Agent/process id that performed the read. |
+
+## 2. Provider interface
+
+A provider is an ESM module exporting a default class constructed with a
+provider-specific options object. Every provider implements the READ interface
+and the PROPOSALS-ONLY write interface.
+
+### 2.1 Read
+
+| Method | Signature | Behaviour |
+| --- | --- | --- |
+| `capabilities()` | `() => Capabilities` | Static description (§2.3). Synchronous. |
+| `readNodes(options?)` | `(o?) => Promise<Node[]>` | All nodes; `options.type` filters by node type. Every node schema-valid. |
+| `readEdges()` | `() => Promise<Edge[]>` | All edges; every edge schema-valid and in the closed vocabulary. |
+| `queryByType(type)` | `(t) => Promise<Node[]>` | Convenience: the nodes of one type (a consistent subset of `readNodes`). |
+| `readGraph()` | `() => Promise<{nodes, edges}>` | The full graph. |
+
+### 2.2 Write — proposals only
+
+Knowledge stores are HUMAN-CURATED. No provider auto-writes to a store. The only
+write surface is:
+
+| Method | Signature | Behaviour |
+| --- | --- | --- |
+| `proposeWrite(intent)` | `(i) => Promise<Proposal>` | Returns a `Proposal` (§2.4) describing an intended change. MUST NOT mutate the store, disk, or the remote board. |
+
+**How proposals-only is expressed structurally:** the `Proposal` schema fixes
+`status` to the const `"proposed"`. A provider can never return an applied
+proposal, and the conformance suite asserts that `readNodes()` is byte-stable
+across a `proposeWrite` call. Enactment happens DOWNSTREAM of the provider:
+
+- **git-repo** renders a decision-registry topic file (frontmatter compatible
+  with `schemas/decision-record.schema.json`) shaped for the **promote sub-flow**
+  (`docs/decisions/promotion-gate.md`). The promote step is the enactor.
+- **work-item** renders a draft `gh issue comment` / `gh issue edit --add-label`
+  the operator files. The provider never runs a mutating `gh` command.
+- **markdown-vault** renders a note in native frontmatter + `[[wikilink]]` form
+  for the Knowledge Kit ingest/compile flow to file.
+
+This is the same proposals-only discipline as the store contract's
+`propose → apply/reject` gate and the ADR-0003-style "proposals, never silent
+writes to a curated store" precedent. A provider is the propose half; a human or
+a gated flow is the apply half.
+
+### 2.3 Capabilities
+
+`capabilities()` returns `{ id, node_types, edge_types, writable, write_mode,
+proposal_targets, source_of_truth }`. `writable` is always `false` and
+`write_mode` is always `"proposals-only"` in this version — a graph-database
+provider that owns its store is a separate, gated spike (issue #318), not a
+loophole here.
+
+### 2.4 Proposal
+
+Validated by `schemas/knowledge/proposal.schema.json`.
+
+| Field | Required | Meaning |
+| --- | --- | --- |
+| `schema_version` | yes | `"1.0"`. |
+| `provider` | yes | Emitting provider id. |
+| `kind` | yes | `create-node` \| `update-node` \| `add-edge` \| `comment` \| `label` \| `decision-topic`. |
+| `target` | yes | Where the change would land (descriptive only). |
+| `payload` | no | The structured node/edge/field proposed. |
+| `rendered` | no | The provider-native form an enactor would apply. |
+| `status` | yes | The const `"proposed"`. |
+| `rationale` | no | Why the change is proposed. |
+| `provenance` | yes | §1.4. |
+
+## 3. Health verbs
+
+Health verbs are PROVIDER-AGNOSTIC pure functions over a graph
+(`{ nodes, edges }`) — they never inspect provider internals, which is what lets
+one health command run identically over any provider (R4). Each returns a
+schema-valid Knowledge Health Report
+(`schemas/knowledge/health-report.schema.json`). Reference verbs live in
+`kits/knowledge/providers/health/`.
+
+| Verb | Report `check` | Behaviour |
+| --- | --- | --- |
+| `detectDuplicates(graph, o?)` | `duplicate-detection` | Flags node pairs whose titles match / are highly similar (token Jaccard ≥ `threshold`, default 0.7; same-type by default). |
+| `checkDependencyLinkIntegrity(graph, o?)` | `dependency-link-integrity` | Flags dependency edges (default type `blocks`) whose endpoints are missing from the graph, unless the edge is `resolved:false` (deliberate external ref). |
+
+Every finding cites its evidence (the compared titles + similarity, or the edge
++ which endpoint is missing). A report's `summary.finding_count` MUST equal
+`findings.length`.
+
+## 4. Reference providers
+
+| Provider | Reads | Node types | Write proposal |
+| --- | --- | --- | --- |
+| `markdown-vault` | The existing Knowledge Kit store (markdown + frontmatter + `[[wikilinks]]` + graph index) via an existing store adapter — thin wrapper, existing skills unaffected. | `note`, `person` | `create-node` rendered as a native vault note. |
+| `git-repo` | `docs/decisions/*` (tombstones → `supersedes`/`merged-into`; `evidence[]` → `evidence-of`), CONTEXT.md glossary, `docs/learnings/*`. | `decision`, `note` | `decision-topic` shaped for the promote sub-flow. |
+| `work-item` | GitHub issues via an INJECTABLE runner (default `gh`), `flow-agents:work-item-metadata` blockers + prose refs → `blocks`/`relates`. | `issue` | `comment` / `label` draft. |
+
+## 5. Conformance
+
+`kits/knowledge/providers/conformance/suite.test.js` is the parameterized
+conformance suite EVERY provider must pass (issue #317, AC3). It asserts:
+capabilities declare proposals-only/non-writable; `readNodes` returns unique,
+schema-valid nodes with provider provenance; `readEdges` returns schema-valid
+edges in the closed vocabulary; `queryByType` is a consistent subset of
+`readNodes`; `readGraph` returns `{nodes, edges}`; and `proposeWrite` returns a
+schema-valid `"proposed"` proposal that mutates nothing.
+
+`kits/knowledge/providers/health/health-pass.test.js` covers AC1 (the same
+health command over vault + git-repo yields schema-valid reports) and AC2 (a
+backlog pass over the work-item adapter, driven by a SEEDED fixture, flags a
+duplicate and a broken blocker link — never the real board).
+
+## 6. Non-goals
+
+Graph-database provider (issue #318 spike; adoption gated on a real query failing
+over files); embeddings; auto-writes to any human-curated store; personal-vault
+feature changes. This contract adds a model + read/propose interface over stores
+operated today; it does not change how those stores are curated.

package/context/contracts/planning-contract.md

@@ -1,5 +1,7 @@
 # Planning Contract
 
+> Read [`context/contracts/standing-directives.md`](standing-directives.md) — ratified owner directives that override default engineering conservatism.
+
 Planning turns a user goal into an executable implementation plan without writing production code.
 
 ## Required Inputs

package/context/contracts/review-contract.md

@@ -1,5 +1,7 @@
 # Review Contract
 
+> Read [`context/contracts/standing-directives.md`](standing-directives.md) — ratified owner directives that override default engineering conservatism.
+
 Review is report-only critique. It asks whether the changed code is maintainable, secure, consistent with project standards, and structurally sound before verification proves behavior.
 
 ## Purpose

package/context/contracts/sandbox-policy.md

@@ -1,5 +1,7 @@
 # Sandbox Policy Contract
 
+> Read [`context/contracts/standing-directives.md`](standing-directives.md) — ratified owner directives that override default engineering conservatism.
+
 Workflow artifacts must name the execution boundary required for the work. The sandbox mode is a planning and delegation contract, not a substitute for the runtime permission model.
 
 ## Canonical Modes

package/context/contracts/standing-directives.md

@@ -0,0 +1,13 @@
+# Standing Directives Contract
+
+Ratified owner directives are corrections and policies the owner has explicitly settled across sessions. They override default engineering conservatism (e.g. "keep the old path working just in case") wherever they apply. Each directive below is a durable, quotable statement — cite the number, not a paraphrase from memory. This file exists so a delegated agent that only sees one task in a plan still receives the same standing policy the orchestrator ratified; correction that lives only in one session's ephemeral context does not reach the agents who need it.
+
+Read this file alongside the phase contract for the work you are doing. When a standing directive and a phase contract's default guidance conflict, the standing directive wins; if you believe a directive does not fit the situation, stop and report the conflict rather than silently picking a side.
+
+## Directives
+
+1. **No legacy fallbacks: migrate hard.** A compatibility path that keeps defective or superseded behavior reachable is prohibited regardless of how short-lived or self-healing it is; the remedy for old artifacts is a loud typed error naming the regeneration command. (Ratified July 2026. Evidence: [datum#3](https://github.com/kontourai/datum/pull/3) hard cutover to `.datum/config.json`; the fallback-removal follow-up to [flow-agents#344](https://github.com/kontourai/flow-agents/pull/344), tracked as [flow-agents#347](https://github.com/kontourai/flow-agents/issues/347).)
+2. **Durable vs runtime paths: never invert them.** `.kontourai/` is gitignored runtime state; `.<product>/` (e.g. `.veritas/`, `.datum/`) is a product's durable, committed directory in consuming repos. (Ratified July 2026. Evidence: `.veritas/` precedent and the `.kontourai/` vs `.veritas/` distinction in [docs/repository-structure.md](../../docs/repository-structure.md); [datum#3](https://github.com/kontourai/datum/pull/3) `.datum/config.json`; [surface#110](https://github.com/kontourai/surface/issues/110), [surface#113](https://github.com/kontourai/surface/pull/113).)
+3. **Evidence must be executable.** Check summaries/excerpts are runnable-from-repo-root commands (`true # ...` for prose that has no command); probe scripts live inside the session dir; reconcilable claims use manifest-exact bare labels. (Ratified July 2026.)
+4. **Standalone-first, then integrate.** Build pieces to provide value alone, then push them through a real product integration to pressure-test the abstractions; file upstream issues for friction found during integration rather than working around it. (Ratified July 2026.)
+5. **Regression rule for cutovers.** Proper before/after tests are required for any cutover; large regressions (e.g. more than 40% record loss, or a whole field-class disappearing) are surfaced as an explicit owner decision with data, never papered over — but a large regression does not block the cutover by default. (Ratified July 2026.)

package/context/contracts/verification-contract.md

@@ -1,5 +1,7 @@
 # Verification Contract
 
+> Read [`context/contracts/standing-directives.md`](standing-directives.md) — ratified owner directives that override default engineering conservatism.
+
 Verification is report-only. It proves whether the implementation satisfies the plan, the Definition Of Done, and the original user outcome.
 
 ## Required Inputs

package/context/contracts/work-item-contract.md

@@ -1,5 +1,7 @@
 # Work Item Contract
 
+> Read [`context/contracts/standing-directives.md`](standing-directives.md) — ratified owner directives that override default engineering conservatism.
+
 This contract defines the provider-neutral vocabulary for selecting, planning, and handing off backlog work. It is the source shape for provider-backed workflows such as `pull-work`; provider-specific adapters map into this model without making GitHub, Jira, Linear, or any other provider the generic language.
 
 ## Provider Roles

package/context/settings/assignment-provider-settings.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "../../schemas/assignment-provider-settings.schema.json",
+  "schema_version": "1.0",
+  "projects": [
+    {
+      "project": {
+        "repo": {
+          "owner": "kontourai",
+          "name": "flow-agents",
+          "url": "https://github.com/kontourai/flow-agents"
+        }
+      },
+      "provider": {
+        "kind": "github",
+        "repo": {
+          "owner": "kontourai",
+          "name": "flow-agents",
+          "url": "https://github.com/kontourai/flow-agents"
+        },
+        "capabilities": ["assignees", "labels", "comments"]
+      },
+      "policy": {
+        "label_name": "agent:claimed",
+        "claim_comment_marker": "<!-- flow-agents:assignment-claim -->",
+        "human_assignee_policy": {
+          "behavior": "ask_first",
+          "idle_threshold_days": 3
+        },
+        "comment_refresh_on_phase_transition": false
+      }
+    }
+  ]
+}