@kontourai/flow-agents 2.3.0 → 2.4.0

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

@@ -0,0 +1,263 @@
+# Decision Registry Contract
+
+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

@@ -59,7 +59,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/planning-contract.md

@@ -23,7 +23,7 @@ Also create or update structured sidecars beside the Markdown artifacts:
 Use the sidecar writer when available:
 
 ```bash
-npm run workflow:sidecar -- init-plan .flow-agents/<slug>/<slug>--deliver.md \
+npm run workflow:sidecar -- init-plan .kontourai/flow-agents/<slug>/<slug>--deliver.md \
   --source-request "<original request>" \
   --summary "<planning summary>" \
   --next-action "<next execution step>"
@@ -79,6 +79,7 @@ The plan body must include:
 - Preserve stable requirement and acceptance ids from upstream backlog issues when they exist; otherwise create stable ids in the plan before execution.
 - Every implementation task must map back to the acceptance criteria it supports.
 - Acceptance criteria for implementation behavior must name expected command/test evidence and expected source evidence. Source evidence means structured refs with `kind`, `url`, `file`, `line_start`, `line_end`, and `excerpt` where applicable; use immutable GitHub blob permalinks pinned to a commit SHA when provider URLs are available, and local file/line refs only as pre-publish fallback.
+- A `kind: "command"` evidence ref's `excerpt`/`command` field must be a **literally runnable shell command** (for example `npm test`, `bash evals/run.sh static`, `./scripts/check.sh`), not a prose description of a manual verification step. The goal-fit backstop and the CI reconciler treat this text as a command: a prose "excerpt" is classified `malformed-evidence` (it is never spawned as `bash -lc "<a sentence>"`, and it is not conflated with a caught false-completion — see `scripts/hooks/stop-goal-fit.js`). When a verification is not automatable — a manual review, a provider/CI observation, a document citation — use `kind: "artifact"`/`"external"` (or record the criterion as `not_verified`/`accepted_gap`) instead of fabricating a `kind: "command"` ref. This keeps the contract and the enforcing code in agreement (ADR 0020).
 - Plans should state that provider, PR, issue, closure, and final acceptance comments need an `Acceptance Evidence` table with columns `AC id`, `Status`, `Command/Test Evidence`, `Source Evidence / Permalinks`, and `Gaps`.
 - The Definition Of Done is the stop condition, not a decorative section.
 - If the goal is exploratory or uncertain, define what the user should be able to take away from the work.

package/context/contracts/review-contract.md

@@ -78,10 +78,12 @@ If a perspective is required but cannot be reviewed, record it as `not_verified`
 
 When review runs as part of a workflow, write or update the configured critique artifact/sink. For the current local sidecar materialization, write or update `critique.json` beside the workflow artifacts using `schemas/workflow-critique.schema.json`.
 
+Reviewers write critique **through** `record-critique` (or `import-critique` for a Markdown report), directly or via the orchestrating skill — never by hand-authoring `critique.json`, `evidence.json`, or `acceptance.json`. Those bespoke sidecars were retired as the source of truth by ADR 0010 Phase 4c; `trust.bundle` is the sole verification artifact and only the sidecar writer performs the evidence classification the CI trust anchor depends on (ADR 0020). `config-protection.js` blocks direct tool writes to these gate files by design.
+
 Prefer the sidecar writer when available:
 
 ```bash
-npm run workflow:sidecar -- record-critique .flow-agents/<slug> \
+npm run workflow:sidecar -- record-critique .kontourai/flow-agents/<slug> \
   --id code-review \
   --reviewer tool-code-reviewer \
   --verdict pass \
@@ -91,8 +93,8 @@ npm run workflow:sidecar -- record-critique .flow-agents/<slug> \
 For Markdown reviewer reports, import them when possible:
 
 ```bash
-npm run workflow:sidecar -- import-critique .flow-agents/<slug> \
-  .flow-agents/<slug>/<slug>--code-review.md \
+npm run workflow:sidecar -- import-critique .kontourai/flow-agents/<slug> \
+  .kontourai/flow-agents/<slug>/<slug>--code-review.md \
   --reviewer tool-code-reviewer
 ```
 

package/context/contracts/verification-contract.md

@@ -14,6 +14,14 @@ Verification is report-only. It proves whether the implementation satisfies the
 
 Verifiers and reviewers do not modify source code. They may run commands, inspect files, take screenshots, and write verification artifacts. They must not apply fixes, formatting, lint autofixes, or patches.
 
+## Writing Evidence Through The Sidecar Writer
+
+Verifiers write evidence and acceptance status **through** `record-evidence` (directly, or via the orchestrating skill), never by hand-authoring `evidence.json`, `acceptance.json`, or `trust.bundle`. Those bespoke sidecars were retired as the source of truth by ADR 0010 Phase 4c; the `trust.bundle` is the sole verification artifact, and only the sidecar writer performs the evidence classification (`evidenceType`/`method` derivation and manifest reconciliation) the CI trust anchor depends on (ADR 0020). `config-protection.js` blocks direct tool writes to these gate files by design. If the sidecar writer is unavailable, record the exact gap instead of writing the files by hand.
+
+## Mutation Testing Runs In A Scratch Copy
+
+Mutation-testing tools (Stryker or equivalent) **must** run against a scratch/throwaway copy of the working tree, never the live working tree. They deliberately introduce defects to measure test-suite sensitivity; running them in place risks leaving mutated source, corrupting the checkout, or tripping the gate/anchor on injected failures. Copy the tree to a temporary directory (or a git worktree/clone) and run the mutation tool there; discard it afterward.
+
 ## Verification Phases
 
 Attempt relevant phases and record evidence:
@@ -77,7 +85,7 @@ When verification runs as part of a workflow, write or update `evidence.json` be
 Use the sidecar writer when available:
 
 ```bash
-npm run workflow:sidecar -- record-evidence .flow-agents/<slug> \
+npm run workflow:sidecar -- record-evidence .kontourai/flow-agents/<slug> \
   --verdict pass \
   --check-json '{"id":"tests","kind":"test","status":"pass","summary":"Relevant checks passed."}'
 ```

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

@@ -176,7 +176,7 @@ GitHub is the first concrete mapping for this contract, not the generic vocabula
 | `related_links` | Issue links, closing references, discussions, docs, and cross-references. |
 | `source_provider` | `github`, repository owner/name, issue number, node id, and issue URL. |
 | `pr_links` | Linked pull requests, closing PRs, branches, or manually referenced PR URLs. |
-| `artifact_refs` | `.flow-agents/<slug>/` artifacts, plan/review/evidence links, and promoted docs referenced from the issue or workflow. |
+| `artifact_refs` | `.kontourai/flow-agents/<slug>/` artifacts, plan/review/evidence links, and promoted docs referenced from the issue or workflow. |
 
 ### GitHub Projects as `BoardProvider`
 

package/context/deferred/parallelization.md

@@ -26,7 +26,7 @@ Every worker delegation must target the exact `tool-worker` role. Omitting the r
 3. **Context** — relevant code patterns, conventions, types/interfaces it needs to follow
 4. **Working directory** — if different from current
 
-tool-worker manages its own TODO files in `.flow-agents/<slug>/` and tracks `modified_files` to detect conflicts with other parallel workers. It will end its turn immediately if instructions are insufficient rather than guessing.
+tool-worker manages its own TODO files in `.kontourai/flow-agents/<slug>/` and tracks `modified_files` to detect conflicts with other parallel workers. It will end its turn immediately if instructions are insufficient rather than guessing.
 
 ## Conflict Avoidance
 

package/context/gate-awareness.md

@@ -6,7 +6,7 @@ This repo runs three active gates implemented as Claude Code hook scripts. Every
 
 **goal-fit/Stop** (`scripts/hooks/stop-goal-fit.js`): fires on the agent Stop event (before the agent final-answers as complete). The gate reads `.flow-agents/` to find the most recent active workflow artifact and checks for: an incomplete Definition Of Done section, an incomplete or absent Goal Fit Gate section, open items in Final Acceptance when status is delivered, failing or NOT_VERIFIED checks in `evidence.json`, open sidecar issues (state.json showing non-done status, critique.json with open findings), and evidence cross-reference failures (the capture log in `command-log.jsonl` contradicting a claimed-pass command check in `evidence.json`). In `block` mode the gate exits 2, which prevents the Stop. The canonical engine default is `warn` (exit 0 with guidance on stderr); shipped runtime configs such as Claude Code at L2 set `block` so the installed product enforces. The gate releases automatically after a configurable number of consecutive identical blocks (default 3) to surface the situation to the human rather than looping forever.
 
-**evidence-capture** (`scripts/hooks/evidence-capture.js`): fires as a postToolUse hook on every shell or command tool execution. It deterministically records the actual command result — not the model's narration about it — to `.flow-agents/<slug>/command-log.jsonl` as an append-only JSONL log. Each record captures the command string, observed result (pass/fail), exit code when available, and a timestamp. Non-blocking; always exits 0. Fail-open: a capture failure never blocks the agent or corrupts the log.
+**evidence-capture** (`scripts/hooks/evidence-capture.js`): fires as a postToolUse hook on every shell or command tool execution. It deterministically records the actual command result — not the model's narration about it — to `.kontourai/flow-agents/<slug>/command-log.jsonl` as an append-only JSONL log. Each record captures the command string, observed result (pass/fail), exit code when available, and a timestamp. Non-blocking; always exits 0. Fail-open: a capture failure never blocks the agent or corrupts the log.
 
 **reground** (`scripts/hooks/workflow-steering.js`): fires on `SessionStart` and `UserPromptSubmit` to re-inject the active workflow phase, goal, and next-step from `state.json` into the agent turn. This is what keeps an in-flight goal alive through context compaction and session resume without requiring the agent to voluntarily re-read sidecars. The hook also fires after subagent calls (use_subagent) to inject phase-transition reminders tailored to the completing subagent (planner, worker, reviewer, verifier). Non-blocking; always exits 0.
 
@@ -28,12 +28,12 @@ Do not conflate "inconvenient" with "false-block." If the gap named by the gate
 
 ## Missed-Block Diagnostic
 
-When a gate does not fire and you suspect it should have, the gate is almost never defective. The goal-fit/Stop gate only knows what the flow recorded in `.flow-agents/<slug>/`. It cross-references `evidence.json` command checks against `command-log.jsonl`. A suspected missed block nearly always means the flow did not record the evidence, not that the gate failed to evaluate it.
+When a gate does not fire and you suspect it should have, the gate is almost never defective. The goal-fit/Stop gate only knows what the flow recorded in `.kontourai/flow-agents/<slug>/`. It cross-references `evidence.json` command checks against `command-log.jsonl`. A suspected missed block nearly always means the flow did not record the evidence, not that the gate failed to evaluate it.
 
 Start diagnosis here:
 
-1. Check `.flow-agents/<slug>/command-log.jsonl` — was the relevant command captured? If the evidence-capture hook was not active when the command ran (for example, the session predated the hook or the artifact directory was not yet resolved), the log will have no entry for that command and the Stop gate will see no contradiction to raise.
-2. Check `.flow-agents/<slug>/evidence.json` — does the relevant check exist with kind `command` and status `pass`? The gate only cross-references checks that are explicitly recorded in `evidence.json` as command-kind claimed passes. If the check was never written there, the gate has nothing to cross-reference.
+1. Check `.kontourai/flow-agents/<slug>/command-log.jsonl` — was the relevant command captured? If the evidence-capture hook was not active when the command ran (for example, the session predated the hook or the artifact directory was not yet resolved), the log will have no entry for that command and the Stop gate will see no contradiction to raise.
+2. Check `.kontourai/flow-agents/<slug>/evidence.json` — does the relevant check exist with kind `command` and status `pass`? The gate only cross-references checks that are explicitly recorded in `evidence.json` as command-kind claimed passes. If the check was never written there, the gate has nothing to cross-reference.
 3. If both files are present and consistent but the block still did not fire, verify that the artifact directory the gate found is the one you expect (`state.json` newest-mtime resolution) and that the workflow artifact has the correct type and status to be treated as active.
 
 A gate defect is a last resort diagnosis, not a first assumption.

package/context/scripts/git-status.sh

@@ -32,11 +32,11 @@ if [ "$WORKTREE_COUNT" -gt 1 ]; then
   echo "=== Active Worktrees ($WORKTREE_COUNT) ==="
   git worktree list
   echo ""
-  echo "⚠️  Multiple worktrees active — check .flow-agents/ for in-progress tasks before modifying shared files"
+  echo "⚠️  Multiple worktrees active — check .kontourai/flow-agents/ for in-progress tasks before modifying shared files"
 fi
 
 # List existing TODOs for awareness
-TODO_DIR=".flow-agents"
+TODO_DIR=".kontourai/flow-agents"
 if [ -d "$TODO_DIR" ]; then
   TODO_COUNT=$(find "$TODO_DIR" -name "*.md" 2>/dev/null | wc -l | tr -d ' ')
   if [ "$TODO_COUNT" -gt 0 ]; then