@kontourai/flow-agents 2.3.0 → 3.0.0

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.
@@ -25,6 +27,7 @@ Every Builder Kit build-flow pause, resume, or step transition must make the fol
 | Field | Durable location | Required meaning |
 | --- | --- | --- |
 | current step | `state.phase`, `state.status`, and Probe record `current_step` | The current Builder Kit step or direct Flow Agents primitive. |
+| branch | `state.json.branch`; seeded in the session Markdown's `branch:` line | The `agent/<actor>/<slug>` routing branch `ensure-session` derives for a new session (optional field for migration honesty — see `schemas/workflow-state.schema.json`); an explicit `--branch` overrides; an existing session's already-recorded branch is never re-derived (see [ADR 0021](../../docs/adr/0021-assignment-leases-and-stale-claim-takeover.md) §3 and §5). |
 | next step | `state.next_action` and Probe record `next_step` | The next step to run after resume or after the current primitive exits. |
 | route reason | Probe record `route_reason`; summarized in `state.next_action.summary` | Why this route was selected, including missing state, evidence, decisions, or blockers. |
 | selected work item refs | Probe record `selected_work_items`; optionally linked in `handoff.json` | Neutral work item references from the work-item contract. |
@@ -44,7 +47,7 @@ Every Builder Kit build-flow pause, resume, or step transition must make the fol
 
 ## Probe Record
 
-A Builder Kit Probe record is a JSON sidecar beside the other workflow artifacts, for example `.flow-agents/<slug>/builder-kit-probe.json`. It is the durable location for pickup/design context that would otherwise make `state.json` too broad.
+A Builder Kit Probe record is a JSON sidecar beside the other workflow artifacts, for example `.kontourai/flow-agents/<slug>/builder-kit-probe.json`. It is the durable location for pickup/design context that would otherwise make `state.json` too broad.
 
 Required shape:
 
@@ -168,7 +171,7 @@ Baseline freshness example for missing historical `planned_base_sha`:
         {
           "id": "source_artifact",
           "description": "Source shaped artifact or pickup artifact used to accept the fallback baseline.",
-          "source": ".flow-agents/<slug>/<slug>--idea-to-backlog.md",
+          "source": ".kontourai/flow-agents/<slug>/<slug>--idea-to-backlog.md",
           "example_value": ".flow-agents/builder-kit-not-verified-resolution-hints/builder-kit-not-verified-resolution-hints--idea-to-backlog.md"
         }
       ],

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

@@ -0,0 +1,265 @@
+# 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
+(see [Relationship to ADRs](#relationship-to-adrs-and-grill-with-docs)).
+
+Machine-checkable structure lives in `schemas/decision-record.schema.json`; the
+validator/generator is `scripts/check-decisions.cjs`, exposed as
+`npm run check:decisions` and `npm run gen:decisions-index` and wired into the
+required `source-and-static` CI lane.
+
+## Why topic-keyed living records
+
+Numbered ADRs accumulate three failure modes at multi-contributor, multi-repo
+scale: contradictions (a new ADR appends a conflicting decision instead of
+replacing the old one), bloat (derivation context is inlined alongside the
+decision), and numbering collisions (two contributors both grab `0021-`). The
+registry removes all three by construction:
+
+- **One file per decision subject**, keyed by a vocabulary noun, not a number.
+- **Supersession is an edit**, so the current answer is always the only answer.
+- **Derivation context is linked, not inlined**, so files stay lean.
+
+## File location and shape
+
+- Each decision lives at `docs/decisions/<topic-slug>.md`.
+- Exactly **one file per decision SUBJECT**. If two questions have the same
+  subject, they share a file; if a file is answering two subjects, split it.
+- A generated index lives at `docs/decisions/index.md` (see [Index](#index)).
+- The file holds ONLY the current decision plus lean rationale. It does not
+  inline transcripts, exploration, meeting notes, or superseded prose.
+
+A topic file is YAML frontmatter followed by a short Markdown body:
+
+```markdown
+---
+status: current
+subject: Decision records
+decided: 2026-07-03
+evidence:
+  - kind: issue
+    ref: https://github.com/kontourai/flow-agents/issues/310
+  - kind: session-archive
+    ref: .kontourai/flow-agents/decision-registry-shape/decision-registry-shape--idea-to-backlog.md
+---
+
+# Decision records
+
+The current answer, plus lean rationale. Derivation context is linked via
+`evidence[]`, never pasted here.
+```
+
+## Slug rules: vocabulary is the namespace
+
+- Slugs are **nouns from the repository's CONTEXT.md domain vocabulary**. The
+  ubiquitous language is the topic namespace; topic identity is downstream of it.
+- Slugs are lowercase kebab-case: `^[a-z0-9]+(-[a-z0-9]+)*$`, matching a
+  glossary term (e.g. the glossary term "Decision Records" ->
+  `decision-records.md`).
+- **If the subject term is absent from CONTEXT.md, add it to CONTEXT.md first**,
+  then create the topic file. This keeps slugs stable and collision-free: two
+  contributors deciding the same subject land on the same slug rather than
+  competing for the next number.
+
+## Frontmatter fields
+
+Validated by `schemas/decision-record.schema.json`:
+
+| Field | Required | Meaning |
+| --- | --- | --- |
+| `status` | yes | `current` \| `superseded` \| `merged` \| `needs-decision` (see [Status](#status-values)). |
+| `subject` | yes | The decision subject, a CONTEXT.md vocabulary noun phrase. |
+| `decided` | yes | ISO date `YYYY-MM-DD` the current decision was ratified. |
+| `evidence[]` | yes | `{kind, ref}` links to durable provenance. Never a secret. |
+| `supersedes[]` | no | Topic slugs whose subjects this file absorbed. |
+| `superseded_by` | when superseded | The slug that now carries the answer. |
+| `merged_into` | when merged | The slug this subject was folded into. |
+
+### Status values
+
+- **`current`** — this file holds the live answer for its subject. Must not
+  carry `superseded_by` or `merged_into`.
+- **`superseded`** — a tombstone: the subject moved to a different topic slug
+  (renamed or split). Requires `superseded_by`.
+- **`merged`** — a tombstone: the subject was folded into another topic. Requires
+  `merged_into`.
+- **`needs-decision`** — a stub that names an open subject with no ratified answer
+  yet. It carries provenance `evidence[]` (e.g. the frozen ADR whose subject is
+  still open) but no live decision body. This value exists so ADR freeze tooling
+  (issue #314) can record that a frozen ADR's subject still needs a living
+  decision without inventing an answer. A `needs-decision` stub is not a
+  tombstone and must not carry `superseded_by`/`merged_into`.
+
+### Evidence refs
+
+Derivation context is LINKED, never inlined. Each `evidence[]` entry is
+`{kind, ref}` where `kind` is one of `issue`, `pr`, `commit`, `session-archive`,
+`adr`, `doc`, `url`:
+
+- **`session-archive`** — a path to an archived session artifact (under
+  `.kontourai/`) promoted at retirement. Grilling/probe transcripts retire into
+  the session archive and are linked here as decision provenance.
+- **`adr`** — a frozen numbered ADR under `docs/adr/` that is provenance for this
+  decision.
+- **`issue`/`pr`/`commit`** — GitHub references (number, URL, or SHA).
+- **`doc`/`url`** — a repository document path or external permalink.
+
+`ref` values must never contain secret-shaped material (AWS access keys, GitHub
+tokens, private-key blocks, JWTs, or `secret:`/`token:`-style literals). The
+validator refuses them; link durable provenance, never a credential.
+
+## Supersession by edit
+
+The normal way a decision changes is: **edit the topic file in place.** Update
+the body to the new decision, bump `decided`, and add an `evidence[]` ref to the
+PR/issue that changed it. There is no second file, no appendix, and no
+contradiction — the file always states exactly one current answer.
+
+Example — the pre-edit file:
+
+```markdown
+---
+status: current
+subject: Artifact retention window
+decided: 2026-04-01
+evidence:
+  - kind: pr
+    ref: https://github.com/kontourai/flow-agents/pull/120
+---
+
+# Artifact retention window
+
+Runtime artifacts are retained for 30 days, then archived.
+```
+
+After a later decision to shorten the window, the SAME file becomes:
+
+```markdown
+---
+status: current
+subject: Artifact retention window
+decided: 2026-07-01
+evidence:
+  - kind: pr
+    ref: https://github.com/kontourai/flow-agents/pull/120
+  - kind: pr
+    ref: https://github.com/kontourai/flow-agents/pull/305
+---
+
+# Artifact retention window
+
+Runtime artifacts are retained for 14 days, then archived.
+```
+
+The old answer is gone from the head; its provenance survives in the linked PRs.
+
+## Tombstones: when a topic moves or merges
+
+Editing covers a decision changing. The rarer case is a SUBJECT moving to a
+different slug. Then the old file becomes a tombstone so inbound links and
+retrieval still resolve.
+
+### `superseded_by` — the subject moved to another slug
+
+Use when a subject is renamed or split and its answer now lives under a different
+slug. The old file:
+
+```markdown
+---
+status: superseded
+subject: Artifact retention window
+decided: 2026-07-02
+superseded_by: artifact-lifecycle
+evidence:
+  - kind: pr
+    ref: https://github.com/kontourai/flow-agents/pull/330
+---
+
+# Artifact retention window
+
+Superseded. The current decision for this subject lives in
+[artifact-lifecycle](./artifact-lifecycle.md).
+```
+
+### `merged_into` — the subject folded into an existing topic
+
+Use when a subject is absorbed by another existing topic. The absorbed file:
+
+```markdown
+---
+status: merged
+subject: Artifact retention window
+decided: 2026-07-02
+merged_into: artifact-lifecycle
+evidence:
+  - kind: pr
+    ref: https://github.com/kontourai/flow-agents/pull/330
+---
+
+# Artifact retention window
+
+Merged into [artifact-lifecycle](./artifact-lifecycle.md).
+```
+
+The surviving file may record what it absorbed with `supersedes: [artifact-retention-window]`.
+
+Both tombstone forms require the target slug to exist (a validator error
+otherwise) and must not point at their own slug.
+
+## Retrieval-at-write
+
+Before recording a decision, **consult `docs/decisions/index.md`** (the
+always-loaded slug + one-liner index) and decide **revise-vs-create**:
+
+1. If an existing topic covers the subject, **revise that file** (edit in place,
+   or tombstone + move if the subject itself is changing identity).
+2. If no topic covers it, confirm the subject noun exists in CONTEXT.md (add it
+   if absent), then **create** `docs/decisions/<slug>.md`.
+
+This retrieval-at-write step, plus a health check at rest (the validator + index
+freshness in CI), is sufficient at this cardinality; no embeddings or semantic
+topic matching are required.
+
+## Index
+
+`docs/decisions/index.md` is generated by `npm run gen:decisions-index`
+(`scripts/check-decisions.cjs gen-index`). It is deterministic and idempotent: a
+second run with no topic change is diff-clean. It lists each topic slug, its
+status, and a one-line summary (the `subject`, falling back to the first body
+line). Do not edit it by hand. `npm run check:decisions` fails if the index is
+missing or stale, so CI catches an out-of-date index.
+
+The index is referenced from `CONTEXT.md` so retrieval-at-write always has a
+cheap, loaded pointer into the registry.
+
+## Validation
+
+`npm run check:decisions` (wired into the required `source-and-static` CI lane)
+exits nonzero on any of:
+
+- invalid frontmatter (missing `status`/`subject`/`decided`/`evidence`);
+- unknown `status`;
+- a secret-shaped `evidence[].ref`;
+- a `superseded_by`/`merged_into`/`supersedes` slug that points at a missing
+  topic file;
+- a status/relationship mismatch (e.g. `current` carrying a tombstone field, or
+  `superseded` without `superseded_by`);
+- a stale or missing `docs/decisions/index.md`.
+
+## Relationship to ADRs and grill-with-docs
+
+- **CONTEXT.md is the only external compatibility surface.** Grill-with-docs
+  interop reads the domain vocabulary from CONTEXT.md; the registry keys its
+  slugs off that same vocabulary. We inherit the grill-with-docs behavior, not
+  the numbered-ADR file format.
+- **Numbered ADRs (`docs/adr/NNNN-*.md`) are frozen history.** They are never
+  written for new decisions and are never converted into topic files. Existing
+  ADRs are frozen-and-indexed by separate tooling (issue #314); a topic file may
+  cite a frozen ADR via an `adr` evidence ref as provenance.
+
+The pilot record self-hosting this contract is
+[docs/decisions/decision-records.md](../../docs/decisions/decision-records.md).

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
@@ -59,7 +61,7 @@ After CI passes and the work is merged, released, or otherwise accepted:
 - [ ] working artifacts archived or linked
 - [ ] long-lived docs updated with why and how the feature was built
 - [ ] durable docs link back to the provider record, archived plan, or session artifact when useful
-- [ ] local `.flow-agents/` runtime artifacts remain untracked, and durable outcomes are promoted before merge to `main`
+- [ ] local `.kontourai/flow-agents/` runtime artifacts remain untracked, and durable outcomes are promoted before merge to `main`
 - [ ] follow-up issues or learning-review items created for deferred work
 - [ ] **workspace cleaned up after a confirmed merge**: the merge is verified from the provider's own merge record (a merge commit / `mergedAt`), not a green check or a command exit code; then the isolated worktree is removed and the now-merged branch is deleted locally and on the remote, honoring the `worktree_lifecycle` (`retain_until: pr_merged`) recorded at selection. Never delete a branch or worktree before the merge is confirmed. A delivery is not complete while it leaves a stale worktree or merged branch behind.
 

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