@kontourai/flow-agents 2.3.0 → 3.0.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
@@ -23,7 +25,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 +81,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

@@ -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
@@ -78,10 +80,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 +95,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/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
@@ -14,6 +16,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 +87,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

@@ -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
@@ -176,7 +178,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