@kontourai/flow-agents 2.4.0 → 3.1.0

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/probe-docs-write-contract.md

@@ -0,0 +1,187 @@
+# Probe Docs-Write Contract
+
+> Read [`context/contracts/standing-directives.md`](standing-directives.md) — ratified owner directives that override default engineering conservatism.
+
+Normative contract for how a Probe (`design-probe`, and its Builder Kit
+`pickup-probe` specialization) writes durable documentation as understanding
+crystallizes during probing. This is the docs-write half of the grill-with-docs
+pattern: a Probe already interviews and aligns; this contract says what a Probe
+must leave behind in durable docs, not just in the session artifact.
+
+## Why
+
+Probe outcomes previously landed only in session artifacts (`.kontourai/flow-agents/<slug>/`):
+vocabulary and decisions crystallized while probing had to be re-extracted later,
+or were lost when the session archived. Grill-with-docs' whole point is that the
+interview leaves living documentation behind, not session-local notes. This
+contract makes that the default behavior for every Probe, not an occasional
+manual follow-up.
+
+## Scope
+
+Applies to `design-probe` (generic) and `pickup-probe` (the Builder Kit
+pickup specialization) — see
+[`kits/builder/skills/design-probe/SKILL.md`](../../kits/builder/skills/design-probe/SKILL.md)
+and
+[`kits/builder/skills/pickup-probe/SKILL.md`](../../kits/builder/skills/pickup-probe/SKILL.md).
+It does not create a new skill; both existing Probe skills already own the
+grill/grill-with-docs behavior (R1 in
+[flow-agents#311](https://github.com/kontourai/flow-agents/issues/311)) — this
+contract only normalizes what they write and where.
+
+Out of scope: enforcement gating on Probe docs-writes (a separate issue),
+`CONTEXT.md` restructuring beyond vocabulary sections, and repositories with no
+`CONTEXT.md` (an open question the owner has not settled; non-blocking for
+flow-agents, which always has one).
+
+## The Two-Delta Rule
+
+**Per crystallized understanding** — a question the Probe asked and the user (or
+discoverable local evidence) definitively answered, not a still-open question or
+an accepted gap — the Probe emits, in the same motion:
+
+1. **A vocabulary delta** into `CONTEXT.md` (or the owning `CONTEXT-MAP.md`
+   context when one exists) — see [Vocabulary Delta](#1-vocabulary-delta-coin-first).
+2. **A decision delta** into `docs/decisions/<slug>.md` — see
+   [Decision Delta](#2-decision-delta-retrieval-at-write).
+3. **Transcript provenance** — the decision delta's `evidence[]` links the
+   session artifact that produced it — see
+   [Transcript Provenance](#3-transcript-provenance).
+
+Not every Probe question needs both deltas. A question resolved by reading
+existing docs/code needs neither (nothing crystallized — it was already
+decided). A question about implementation detail, sequencing, or a transient
+planning choice needs neither (it belongs in the workflow artifact, per
+`context/contracts/artifact-contract.md`, not durable docs). The two-delta rule
+applies specifically to a **decision subject** crystallizing: a durable,
+reusable answer to a named domain question that other work will need to look up
+later. If in doubt, ask: "will a future session need to know this answer without
+re-deriving it?" — if yes, it is a decision subject and both deltas apply.
+
+### 1. Vocabulary delta (coin-first)
+
+**A decision subject may only use subject terms present in (or added to)
+`CONTEXT.md` in the same session** (R2). Vocabulary is the topic namespace the
+decision registry's slugs are drawn from
+(`context/contracts/decision-registry-contract.md` § Slug rules), so the term
+must exist before the topic file can be named.
+
+- If the crystallized understanding's subject noun is **already** a `CONTEXT.md`
+  glossary term, the vocabulary delta may be a **refinement** of that entry
+  rather than a new one — e.g. removing "subject open" language once a decision
+  ratifies it, tightening a definition, or adding an `_Avoid_` term. This still
+  counts as a vocabulary delta: the glossary is a living document, not
+  write-once.
+- If the subject noun is **absent**, **coin it first**: add a tight one- or
+  two-sentence `### <Term>` entry to `CONTEXT.md`'s Glossary section, in the
+  same style as existing entries (definition, optional `_Avoid_` line). Do this
+  before creating the decision file — the term is the slug's namespace, not an
+  afterthought.
+- Keep the vocabulary delta to glossary-style terminology. Implementation
+  detail, rationale, and derivation stay out of `CONTEXT.md` (unchanged from the
+  Probe skills' existing docs discipline).
+- If a `CONTEXT-MAP.md` exists and a more specific context owns the term, update
+  that context instead of assuming the root glossary owns every term.
+
+### 2. Decision delta (retrieval-at-write)
+
+Once the vocabulary exists, record the decision per
+`context/contracts/decision-registry-contract.md` in full — this contract does
+not repeat the frontmatter/slug/tombstone rules, only the Probe-specific
+sequencing:
+
+1. **Consult `docs/decisions/index.md`** (the always-loaded slug + one-liner
+   index) before writing anything, and propose **revise-vs-create**:
+   - An existing topic slug already covers the subject (including a
+     `needs-decision` stub seeded by ADR-freeze tooling, issue #314) → **revise
+     that file in place.** Flip `needs-decision` → `current` (or edit a `current`
+     file's body/`decided` date for a superseding decision), add the new
+     `evidence[]` refs, do not create a second file for the same subject.
+   - No topic covers the subject → confirm the vocabulary delta above landed,
+     then **create** `docs/decisions/<slug>.md` with the frontmatter shape
+     `context/contracts/decision-registry-contract.md` defines.
+2. Run `npm run gen:decisions-index && npm run check:decisions` after every
+   decision-delta write. A Probe session is not done touching the registry until
+   both exit 0.
+3. Never propose a numbered ADR. `docs/adr/` is frozen history
+   (`docs/adr/README.md`); a Probe's decision delta always targets the
+   topic-keyed registry, never a new `docs/adr/NNNN-*.md` file.
+
+### 3. Transcript provenance
+
+Every decision file a Probe creates or edits carries an `evidence[]` entry of
+`kind: session-archive` pointing at the Probe's own session artifact (R3) — the
+Markdown file recording the interview, decisions, and accepted gaps
+(`.kontourai/flow-agents/<slug>/<slug>--design-probe.md`,
+`<slug>--pull-work.md`, or the equivalent Probe record the active workflow
+artifact uses).
+
+- Record the **live session path** at write time, even though the topic file
+  and the decision-registry contract describe `session-archive` as pointing at
+  an *archived* artifact "promoted at retirement" — the Probe runs at shaping
+  time, before the session archives. This is a deliberate, documented seam: the
+  promote-then-archive gate (issue #312) is the retirement-time mechanism that
+  moves the session directory to `<artifact-root>/archive/<slug>/` and is
+  responsible for keeping already-written evidence refs accurate across that
+  move. The Probe's job is emitting the initial link, not the later archival
+  move; do not block a decision delta on the session having archived first.
+- When the Probe is also citing a frozen ADR as prior provenance (e.g. upgrading
+  a `needs-decision` stub whose `evidence[]` already names one), keep that `adr`
+  evidence entry and add the `session-archive` entry alongside it — provenance
+  accumulates, it does not replace.
+- Also add a `pr`/`issue` evidence entry once a PR or issue number exists for the
+  work, following the same pattern every other decision file in the registry
+  uses.
+
+## Worked Example: Upgrading a Needs-Decision Stub
+
+The ADR-freeze cutover (issue #314, landed in #368) seeded 17 `needs-decision`
+stubs, each naming a subject with provenance in a frozen ADR but no ratified
+living decision. These are the natural first targets for this contract: a Probe
+that settles one of these subjects from existing evidence (the frozen ADR
+already states a decision that remains true — nothing new needs deciding, only
+recording) does the following:
+
+1. **Read the stub** (`docs/decisions/<slug>.md`, `status: needs-decision`) and
+   its `evidence[]`-linked frozen ADR(s).
+2. **Vocabulary delta**: the subject noun is already a `CONTEXT.md` term (seeded
+   alongside the stub during the freeze cutover) — refine its definition to
+   state the decision is now living rather than "subject open in the Decision
+   Registry," and keep the link to `docs/decisions/<slug>.md`.
+3. **Decision delta**: consult `docs/decisions/index.md` — the slug already
+   exists (revise, not create). Edit `docs/decisions/<slug>.md`:
+   `status: needs-decision` → `current`, set `decided` to today, keep the
+   existing `adr` evidence ref(s), append a `session-archive` ref (this Probe's
+   session artifact) and a `pr` ref once the PR exists, and write the `# <Title>`
+   body stating the decision (drawn from the ADR) plus lean rationale.
+4. Run `npm run gen:decisions-index && npm run check:decisions`; both must exit
+   0 before the Probe records the gate claim.
+5. **Transcript provenance**: the session-archive evidence ref from step 3 is the
+   provenance link (R3).
+
+This exercises all three rules end-to-end without inventing a new decision —
+the frozen ADR already made the call; the Probe's job is only recording that it
+is still true and giving it a living home.
+
+## Relationship To Other Contracts
+
+- **`context/contracts/decision-registry-contract.md`** is the normative
+  frontmatter/slug/tombstone/validation contract for every `docs/decisions/`
+  file, Probe-written or not. This contract only adds *when* and *in what
+  sequence* a Probe writes to that registry.
+- **`context/contracts/artifact-contract.md`** governs the Probe's session
+  artifact itself (the thing this contract's transcript-provenance rule links
+  to) and the promote/archive lifecycle referenced above.
+- **`docs/adr/README.md`** is where this contract is announced as the mechanism
+  that supersedes the prior "propose ADRs sparingly" Probe guidance — Probes
+  never write numbered ADRs; they write decision-registry deltas.
+
+## Validation
+
+- `npm run check:decisions` / `npm run gen:decisions-index` — the decision
+  delta must pass the registry validator and keep the index current (wired into
+  the required `source-and-static` CI lane).
+- `evals/static/test_workflow_skills.sh` — asserts `design-probe` and
+  `pickup-probe` reference this contract and describe the two-delta behavior.
+- `evals/static/test_decisions.sh` — regression coverage for the validator and
+  generator this contract's decision deltas depend on.

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/scripts/hooks/config-protection.js

@@ -131,6 +131,18 @@ function checkProtectedPathPattern(filePath) {
     };
   }
 
+  // .kontourai/flow-agents/current/<actor>.json (#291) — the per-actor projection of the same
+  // pointer above. An agent could forge active_flow_id/active_step_id here exactly as it could
+  // via the legacy global file, so this is protected identically (same reason text).
+  // SAFE: the workflow CLI writes this via writePerActorCurrent → fs.writeFileSync,
+  // NOT via the Write/Edit tool — blocking the tool path does not break legit sidecar.
+  if (/(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/current\/[^/]+\.json$/.test(norm)) {
+    return {
+      name: '.kontourai/flow-agents/current/<actor>.json',
+      reason: 'an agent could forge active_flow_id/active_step_id to route the gate to a permissive FlowDefinition',
+    };
+  }
+
   // .kontourai/flow-agents/.goal-fit-block-streak.json controls soft-block
   // release counting. An agent could force early advisory-gate release by
   // writing a high count.
@@ -403,12 +415,13 @@ function checkCommandForBypass(command) {
  * Regex that matches a normalized (forward-slash) path ending with a protected
  * kill-switch file: shell profiles, .claude/settings*.json,
  * .kontourai/flow-agents/current.json,
+ * .kontourai/flow-agents/current/<actor>.json (#291 per-actor projection),
  * .kontourai/flow-agents/.goal-fit-block-streak.json,
  * .kontourai/flow-agents/<slug>/state.json,
  * .kontourai/flow-agents/<slug>/trust.bundle, and deprecated runtime-shaped
  * .flow-agents equivalents.
  */
-const REDIRECT_PROTECTED_RE = /(?:^|\/|~\/)(\.bash_profile|\.bashrc|\.profile|\.zprofile|\.zshrc)$|(?:^|\/)\.claude\/settings(?:\.local)?\.json$|(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/current\.json$|(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/\.goal-fit-block-streak\.json$|(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/[^/]+\/state\.json$|(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/[^/]+\/trust\.bundle$|(?:^|\/)delivery\/trust\.bundle$|(?:^|\/)delivery\/trust\.checkpoint\.json$/;
+const REDIRECT_PROTECTED_RE = /(?:^|\/|~\/)(\.bash_profile|\.bashrc|\.profile|\.zprofile|\.zshrc)$|(?:^|\/)\.claude\/settings(?:\.local)?\.json$|(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/current\.json$|(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/current\/[^/]+\.json$|(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/\.goal-fit-block-streak\.json$|(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/[^/]+\/state\.json$|(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/[^/]+\/trust\.bundle$|(?:^|\/)delivery\/trust\.bundle$|(?:^|\/)delivery\/trust\.checkpoint\.json$/;
 
 /**
  * Return true when a token (an unquoted redirect target or tee argument) matches

package/context/scripts/hooks/lib/config-protection-remedies.js

@@ -22,6 +22,8 @@ const SANCTIONED_REMEDIES = {
     'There is no sanctioned automated writer for this file. Ask a human maintainer to edit it directly. Never disable this hook to make the write.',
   '.kontourai/flow-agents/current.json':
     'Use `npm run workflow:sidecar -- ensure-session` (or `advance-state`), which writes this file for you. Never disable this hook to make the write.',
+  '.kontourai/flow-agents/current/<actor>.json':
+    'Use `npm run workflow:sidecar -- ensure-session` (or `advance-state`), which writes this file for you. Never disable this hook to make the write.',
   '.kontourai/flow-agents/.goal-fit-block-streak.json':
     'This file is only mutated internally by the goal-fit Stop hook; there is no sanctioned agent writer. Never disable this hook to make the write.',
   '.kontourai/flow-agents/<slug>/state.json':
@@ -61,6 +63,13 @@ const REMEDY_COMMAND_CANDIDATES = [
   { name: '.kontourai/flow-agents/<slug>/trust.bundle', needles: ['trust.bundle'] },
   { name: '.kontourai/flow-agents/<slug>/state.json', needles: ['state.json'] },
   { name: '.kontourai/flow-agents/.goal-fit-block-streak.json', needles: ['.goal-fit-block-streak.json'] },
+  // #291: the per-actor projection (current/<actor>.json) is checked BEFORE the legacy
+  // current.json needle below — its needle is a directory-scoped substring
+  // ('flow-agents/current/') that never overlaps with the bare 'current.json' basename, so
+  // ordering between these two entries has no effect on real inputs, but keeping the more
+  // specific per-actor entry first mirrors this table's existing "specific before generic"
+  // convention.
+  { name: '.kontourai/flow-agents/current/<actor>.json', needles: ['flow-agents/current/', '.flow-agents/current/'] },
   { name: '.kontourai/flow-agents/current.json', needles: ['current.json'] },
   { name: '.claude/settings.local.json', needles: ['settings.local.json'] },
   { name: '.claude/settings.json', needles: ['.claude/settings.json'] },

package/context/scripts/hooks/stop-goal-fit.js

@@ -42,6 +42,8 @@ const {
   flowAgentsArtifactRoot,
   flowAgentsArtifactRootsForRead,
 } = require('./lib/local-artifact-paths');
+const { resolveActor } = require('./lib/actor-identity.js');
+const { readCurrentPointer } = require('./lib/current-pointer.js');
 
 const MAX_STDIN = 1024 * 1024;
 const ACTIVE_STATUSES = new Set([
@@ -1531,7 +1533,7 @@ async function bundleEnforcement(artifactDir, activeFlowStep) {
  * to scanning all of .kontourai/flow-agents (newest-mtime).
  */
 function preferredArtifactDir(flowAgentsDir) {
-  const current = readJsonFile(path.join(flowAgentsDir, 'current.json'));
+  const { payload: current } = readCurrentPointer(flowAgentsDir, resolveActor(process.env).actor);
   if (!current) return null;
   const slug = current.artifact_dir || current.active_slug;
   if (typeof slug !== 'string' || !slug.trim()) return null;
@@ -1549,7 +1551,7 @@ function hasSidecarPresence(artifactDir) {
 // return that slug so analyze() can log the staleness rather than silently falling back to
 // a global mtime scan that could resurface an abandoned/never-real session as active.
 function staleCurrentSlug(flowAgentsDir) {
-  const current = readJsonFile(path.join(flowAgentsDir, 'current.json'));
+  const { payload: current } = readCurrentPointer(flowAgentsDir, resolveActor(process.env).actor);
   if (!current) return null;
   const slug = current.artifact_dir || current.active_slug;
   if (typeof slug !== 'string' || !slug.trim()) return null;

package/context/scripts/hooks/workflow-steering.js

@@ -19,6 +19,7 @@ const path = require('path');
 const { readLivenessEvents, freshHolders } = require('./lib/liveness-read');
 const { resolveActor } = require('./lib/actor-identity');
 const { flowAgentsArtifactRootsForRead } = require('./lib/local-artifact-paths');
+const { readCurrentPointer } = require('./lib/current-pointer');
 
 const STEERING = {
   'tool-planner': [
@@ -102,7 +103,48 @@ function readJson(file) {
   }
 }
 
+/**
+ * #291 (Conflict #2, Wave 2 Task 2.4): actor-scoped preference consulted BEFORE the global
+ * newest-mtime scan below. For each read-root, resolve the "current" pointer via
+ * `readCurrentPointer` (per-actor `current/<actor>.json` preferred, legacy global
+ * `current.json` fallback — the same single choke point every other Wave 2 consumer uses) and,
+ * if it names a session dir whose `state.json` is still in an ACTIVE_STATE_STATUSES status,
+ * return that state immediately — so actor A's own ambient steering hint always prefers A's own
+ * current task over a globally-newer-mtime `state.json` some other actor (B) happened to touch
+ * more recently. Returns null (never throws) when no root yields an actor-scoped resolution,
+ * so the caller falls through to the unchanged global scan below — this is the compat-shim
+ * guarantee: when `actorKey` is empty/unresolved and/or no per-actor file exists yet, this
+ * degrades to the SAME legacy-`current.json`-or-nothing lookup the compat shim already performs
+ * for every other Wave 2 reader, so a single-session/CI/legacy-only fixture cannot fail to
+ * resolve here in a way it wouldn't already have resolved via the global scan.
+ *
+ * @param {string} root
+ * @param {string} actorKey
+ * @returns {{file: string, payload: object, mtimeMs: number}|null}
+ */
+function actorScopedWorkflowState(root, actorKey) {
+  for (const flowAgentsDir of flowAgentsArtifactRootsForRead(root)) {
+    const { payload: current } = readCurrentPointer(flowAgentsDir, actorKey);
+    if (!current) continue;
+    const slug = current.artifact_dir || current.active_slug;
+    if (typeof slug !== 'string' || !slug.trim()) continue;
+    const safe = slug.replace(/\.\.+/g, '').replace(/^[/\\]+/, '');
+    const dir = path.join(flowAgentsDir, safe);
+    if (!dir.startsWith(flowAgentsDir + path.sep) || !fs.existsSync(dir)) continue;
+    const file = path.join(dir, 'state.json');
+    let stat;
+    try { stat = fs.statSync(file); } catch { continue; }
+    const payload = readJson(file);
+    if (!payload || !ACTIVE_STATE_STATUSES.has(payload.status)) continue;
+    return { file, payload, mtimeMs: stat.mtimeMs };
+  }
+  return null;
+}
+
 function latestWorkflowState(root) {
+  const preferred = actorScopedWorkflowState(root, resolveActor(process.env).actor);
+  if (preferred) return preferred;
+
   const states = flowAgentsArtifactRootsForRead(root)
     .flatMap(artifactRoot => walkStateFiles(artifactRoot))
     .map(file => {

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
+      }
+    }
+  ]
+}

package/docs/adr/0001-flow-agents-consumes-flow.md

@@ -2,6 +2,8 @@
 title: ADR 0001: Flow Agents Consumes Flow For Workflow Enforcement
 ---
 
+> **FROZEN — immutable history.** Superseding/current decisions live in [`docs/decisions/`](../decisions/index.md). Do not edit.
+
 # ADR 0001: Flow Agents Consumes Flow For Workflow Enforcement
 
 Date: 2026-05-24

package/docs/adr/0002-flow-kits-as-extension-unit.md

@@ -2,6 +2,8 @@
 title: ADR 0002: Flow Kits As The Extension Unit
 ---
 
+> **FROZEN — immutable history.** Superseding/current decisions live in [`docs/decisions/`](../decisions/index.md). Do not edit.
+
 # ADR 0002: Flow Kits As The Extension Unit
 
 Flow Agents will use **Flow Kit** as the product and implementation term for installable workflow bundles, replacing the older "pack" vocabulary. A Flow Kit may contain Flow Definitions, skills, adapters, provider contracts, docs, and evals; the Kit Catalog lists available kits and installable assets, but the workflow semantics live in kit-owned Flow Definition files. This avoids overloading packaging metadata with process semantics and gives custom workflow authoring a clearer product language.