@kontourai/flow-agents 2.3.0 → 3.0.0

package/docs/standards-register.md

@@ -50,13 +50,13 @@ Flow Agents may need local schemas for reliability glue that existing standards
 
 | Format | Purpose | Target Location | Status |
 | --- | --- | --- | --- |
-| Workflow state | Current phase, owner, next action, status, and resumability data | `.flow-agents/<slug>/state.json` | Draft schema: `schemas/workflow-state.schema.json` |
-| Acceptance criteria | Criteria, source request, evidence requirements, and goal-fit status | `.flow-agents/<slug>/acceptance.json` | Draft schema: `schemas/workflow-acceptance.schema.json` |
-| Evidence summary | Proof commands, standard refs, skipped checks, not-verified gaps, and external evidence links | `.flow-agents/<slug>/evidence.json` | Draft schema: `schemas/workflow-evidence.schema.json` |
-| Handoff | What another agent or future session needs to continue safely | `.flow-agents/<slug>/handoff.json` | Draft schema: `schemas/workflow-handoff.schema.json` |
-| Critique record | Reviewer passes, findings, severity, and resolution state for critique loops | `.flow-agents/<slug>/critique.json` | Draft schema: `schemas/workflow-critique.schema.json` |
-| Release readiness | Merge, release, deploy, hold, rollback, docs, and operational readiness decisions | `.flow-agents/<slug>/release.json` | Draft schema: `schemas/workflow-release.schema.json` |
-| Learning record | Repeated failure, correction, pattern, and recommended system update | `.flow-agents/<slug>/learning.json` or `.telemetry/outcomes.jsonl` | Draft schema: `schemas/workflow-learning.schema.json` |
+| Workflow state | Current phase, owner, next action, status, and resumability data | `.kontourai/flow-agents/<slug>/state.json` | Draft schema: `schemas/workflow-state.schema.json` |
+| Acceptance criteria | Criteria, source request, evidence requirements, and goal-fit status | `.kontourai/flow-agents/<slug>/acceptance.json` | Draft schema: `schemas/workflow-acceptance.schema.json` |
+| Evidence summary | Proof commands, standard refs, skipped checks, not-verified gaps, and external evidence links | `.kontourai/flow-agents/<slug>/evidence.json` | Draft schema: `schemas/workflow-evidence.schema.json` |
+| Handoff | What another agent or future session needs to continue safely | `.kontourai/flow-agents/<slug>/handoff.json` | Draft schema: `schemas/workflow-handoff.schema.json` |
+| Critique record | Reviewer passes, findings, severity, and resolution state for critique loops | `.kontourai/flow-agents/<slug>/critique.json` | Draft schema: `schemas/workflow-critique.schema.json` |
+| Release readiness | Merge, release, deploy, hold, rollback, docs, and operational readiness decisions | `.kontourai/flow-agents/<slug>/release.json` | Draft schema: `schemas/workflow-release.schema.json` |
+| Learning record | Repeated failure, correction, pattern, and recommended system update | `.kontourai/flow-agents/<slug>/learning.json` or `.telemetry/outcomes.jsonl` | Draft schema: `schemas/workflow-learning.schema.json` |
 | Context map | Compact project map: structure, commands, conventions, test strategy, Kits, and recent state | Generated under `.flow-agents/` or configurable cache | Planned |
 | Kit Catalog | Product-facing catalog of Flow Kits and their activation, layered over the always-installed standalone base | `kits/catalog.json` plus generated export catalog metadata | Catalog: `kits/catalog.json` |
 | Governance adapter | Optional bridge from Flow Agents evidence gates to tools such as Veritas | `context/contracts/governance-adapter-contract.md` | Draft contract |

package/docs/trust-anchor-adoption.md

@@ -106,12 +106,91 @@ for the files that declare what CI runs:
 
 ```
 # Trust anchor config — requires owner review.
-# An agent cannot weaken verify-command without a human approving the change.
+# An agent cannot weaken verify-command or the reconcile manifest without a human
+# approving the change.
 .github/workflows/trust-verify.yml  @your-org/owners
 package.json                         @your-org/owners
+evals/ci/run-baseline.sh             @your-org/owners
 ```
 
-Adjust paths and team names for your repo structure.
+`package.json` covers both `trust-reconcile-verify` and the `trust-reconcile-manifest`
+declaration (see below); `evals/ci/run-baseline.sh` covers the manifest registry when you
+source the manifest from a `run-baseline.sh`-shaped registry. Adjust paths and team names
+for your repo structure.
+
+## Declaring a Manifest (Multiple Commands)
+
+The single `trust-reconcile-verify` command above is the anchor's standalone fresh-verify
+(and the legacy reconcile path — a manifest of size 1). To reconcile **granular,
+per-acceptance-criterion** evidence — some commands, some session-local/manual/provider
+evidence — declare a **reconcile manifest**: a set of named, individually-re-runnable
+commands, each of which must actually run in a required CI lane (see ADR 0020).
+
+Resolution priority (first match wins):
+
+1. CLI `--manifest '<json>'`
+2. `TRUST_RECONCILE_MANIFEST` environment variable (JSON)
+3. `package.json` `"trust-reconcile-manifest"` — either an inline array, or a string
+   command that emits the JSON:
+
+   ```json
+   {
+     "trust-reconcile-manifest": [
+       { "id": "unit",  "command": "npm test" },
+       { "id": "lint",  "command": "npm run lint" },
+       { "id": "types", "command": "npm run typecheck" }
+     ]
+   }
+   ```
+
+   Every `id`/`command` here must be a command your required CI actually runs. If your repo
+   already has a lane registry that CI invokes, point the key at its machine-readable emit
+   instead of duplicating it (this is what Flow Agents does — see the mirror section):
+
+   ```json
+   { "scripts": { "trust-reconcile-manifest": "bash evals/ci/run-baseline.sh --manifest-json" } }
+   ```
+4. `evals/ci/run-baseline.sh --manifest-json` (auto-detected, if present).
+
+**How classification works.** A claim reconciles per-command against fresh CI results only
+when its evidence is `evidenceType: "test_output"` **and** its command matches a manifest
+entry. Honest session-local evidence (`human_attestation`, `crawl_observation`,
+`document_citation`, `policy_rule`, `source_excerpt`, `attestation`) is never flagged
+"not-run" for lacking a command — it is accepted on its Surface-derived `verified`/`assumed`
+status. A `test_output` claim whose command is not in the manifest is still a divergence
+(you cannot self-label an arbitrary command `test_output` to dodge the manifest).
+
+**Session-local passes are loudly, not quietly, marked.** A non-command-backed claim that
+re-derives `verified` (and carries no waiver) is NOT independently re-runnable by CI — the
+anchor can only confirm the bundle is internally self-consistent, not that the underlying
+attestation is true. It prints a distinct line for every such claim:
+
+```
+[trust-reconcile] ATTESTED (not independently verifiable at L0): '<claimId>' (<claimType>) evidenceType=<type> — accepted on bundle-internal consistency only; see ADR 0020 Residuals
+```
+
+plus a summary count (`N attested claim(s) accepted without independent verification`). This
+does not change the exit code — attestations are not blocked, only disclosed — so review the
+`ATTESTED` lines and count in any bundle before trusting it. See the **Residuals** section of
+[ADR 0020](adr/0020-trust-reconcile-manifest-and-claim-classification.md) for the full
+disclosure (fabricated self-consistent attestations, unauthenticated `approved_by`, and the
+evidenceType-laundering route).
+
+**Waiving an accepted gap.** For an honestly-accepted gap, record it with both flags:
+
+```bash
+npm run workflow:sidecar -- record-evidence <artifact-dir> --verdict pass \
+  --check-json '{"id":"load-test","kind":"external","status":"skip","summary":"sustained-load perf test"}' \
+  --accepted-gap-reason "load-test env not provisioned this cycle; tracked for the perf milestone" \
+  --waived-by "your-name"
+```
+
+Both `--accepted-gap-reason` and `--waived-by` are required together — an accepted gap
+with no justification or approver is refused (no silent waiver). Reuse a **separate**
+`record-evidence` invocation for waived checks: the flags apply to every check in the
+invocation. The anchor prints each waived claim on a distinct, un-suppressible
+`[trust-reconcile] WAIVED: ...` line in the required job's own log — reviewed and visible,
+never silent.
 
 ## Configuring the Verify Command
 
@@ -164,9 +243,14 @@ Flow Agents uses the same pattern in its own repository:
 
 - **`scripts/ci/trust-reconcile.js`** — the anchor script (runs in
   `.github/workflows/trust-reconcile.yml`).
-- **`package.json` `trust-reconcile-verify`** — `npm run build && npm run eval:static`.
+- **`package.json` `trust-reconcile-verify`** — `npm run build && npm run eval:static`
+  (the standalone fresh-verify / legacy single-command reconcile path).
+- **`package.json` `trust-reconcile-manifest`** — `bash evals/ci/run-baseline.sh
+  --manifest-json` (the reconcile manifest *is* the live `run-baseline.sh` `LANE_*`
+  registry — every entry runs in a required `ci.yml` lane by construction).
 - **`evals/ci/antigaming-suite.sh`** — the regression suite that proves the gate and
-  anchor work; runs in the required `ci.yml` lane.
+  anchor work (including `test_trust_reconcile_manifest.sh` and the end-to-end
+  `test_trust_reconcile_mixed_bundle.sh`); runs in the required `ci.yml` lane.
 - **Branch protection** on `main` — `Trust Reconcile` required, `enforce_admins` on.
 
 ## Adoption Checklist
@@ -192,6 +276,23 @@ the mismatch. Fix the underlying test failure.
 **"trust divergence: command contains exit-code-laundering operator"**: A claimed
 command used `||`, `; true`, or `; exit 0`. These mask real exit codes. Remove them.
 
+**"command is not in the reconcile manifest"**: A `test_output` claim named a command that
+is not a manifest entry. Either declare the command in your `trust-reconcile-manifest` (and
+ensure it runs in a required CI lane), or, if the evidence is genuinely session-local
+(manual/provider/observation), record it with a non-`test_output` `evidenceType` so it is
+classified session-local instead of expected to be CI-re-runnable.
+
+**"session-local claim ... asserts pass ... but has no waiver and no Surface-derived
+verified/assumed status"**: An honest session-local claim must either resolve a real
+`verified`/`assumed` Surface status from its own evidence, or be explicitly waived with
+`--accepted-gap-reason` + `--waived-by`. Classification is not a pass bypass.
+
 **"checkpoint-only bundle cannot be reconciled per-command"**: A `delivery/trust.bundle`
 was expected but only `delivery/trust.checkpoint.json` was found. The deliver skill
 publishes the full bundle; ensure it ran correctly.
+
+**"ATTESTED (not independently verifiable at L0): ..."**: Not an error — the job still
+passes. This is the anchor telling you a claim was accepted on bundle-internal consistency
+only (no CI command to re-run and no independent, cryptographically-verified attestation).
+Review each `ATTESTED` line and the summary count before trusting the bundle; see
+[ADR 0020's Residuals section](adr/0020-trust-reconcile-manifest-and-claim-classification.md).

package/docs/work-item-adapters.md

@@ -69,4 +69,4 @@ Do not treat missing CI, missing required review, missing branch protection data
 
 ## Artifact Lifecycle
 
-Local workflow artifacts under `.flow-agents/<slug>/` or a distribution-specific artifact root are runtime/session state by default. Provider records may link to those artifacts, but long-lived decisions should be promoted into durable docs, release notes, changelogs, ADRs, or provider comments/descriptions that are intended to persist.
+Local workflow artifacts under `.kontourai/flow-agents/<slug>/` or a distribution-specific artifact root are runtime/session state by default. Provider records may link to those artifacts, but long-lived decisions should be promoted into durable docs, release notes, changelogs, ADRs, or provider comments/descriptions that are intended to persist.

package/docs/workflow-artifact-lifecycle.md

@@ -4,7 +4,7 @@ title: Workflow Artifact Lifecycle
 
 # Workflow Artifact Lifecycle
 
-Flow Agents treats task artifacts as useful working memory, not permanent product documentation. Feature branches should promote durable planning, decisions, evidence pointers, and acceptance notes into normal project docs, source, schemas, or provider records instead of carrying `.flow-agents/` runtime files.
+Flow Agents treats task artifacts as useful working memory, not permanent product documentation. Feature branches should promote durable planning, decisions, evidence pointers, and acceptance notes into normal project docs, source, schemas, or provider records instead of carrying `.kontourai/flow-agents/` runtime files.
 
 The local artifact root is a current-state dashboard first and a short-lived recovery cache second. It should answer "what needs attention now?" without forcing agents to sift through old successful deliveries.
 
@@ -17,17 +17,19 @@ npm run workflow-artifact-cleanup-audit -- --artifact-root .flow-agents
 npm run workflow-artifact-cleanup-audit -- --artifact-root .flow-agents --json
 ```
 
+The default root for local runtime artifacts is `.kontourai/flow-agents`. `.flow-agents` may hold explicit durable Flow Agents config/install state, but it is not a runtime fallback. Move old local sessions with the migration script instead of relying on automatic fallback reads.
+
 The command scans immediate workflow directories, skips non-workflow lanes such as `archive/`, and reports active WIP separately from cleanup candidates, terminal done records, active learning follow-ups, and invalid sidecars. This first slice is dry-run classification only: it does not delete, archive, move, or rewrite runtime artifacts by default, and it has no apply mode.
 
 Use the Current-State Semantics and Local Retention Policy sections below to interpret each bucket. In particular, learning records with `learning.status: followup_required` or any `routing[].status: open` remain active learning follow-ups until every route is completed, opened elsewhere, deferred with a trigger, accepted, or rejected.
 
 ## Artifact Lanes
 
-Use one local lane under `.flow-agents/`:
+Use one local non-durable lane under `.kontourai/flow-agents/`:
 
 | Lane | Path | Commit Policy | Purpose |
 | --- | --- | --- | --- |
-| Runtime workspace | `.flow-agents/<slug>/` | Do not commit | Local session state, sidecars, delegate events, scratch evidence, and recovery notes. |
+| Runtime workspace | `.kontourai/flow-agents/<slug>/` | Do not commit | Local session state, sidecars, delegate events, scratch evidence, and recovery notes. |
 
 The runtime workspace stays local because it may contain stale session state, machine-specific paths, or noisy intermediate artifacts. When a branch needs cross-session or cross-person traceability, promote the durable summary, decisions, evidence pointers, and acceptance notes into docs, source, schemas, or provider records instead of committing runtime artifacts.
 
@@ -41,10 +43,71 @@ Treat `state.json` as the active-work signal for local users and `pull-work`.
 | `verified` with `next_action.status: continue` | Local evidence passed, but release, final acceptance, or learning is not closed. | Active shepherding candidate. |
 | `verified` with `next_action.status: done` | Evidence passed and the next phase was completed outside the state machine or by a provider record. | Cleanup candidate; should be advanced to a terminal state during final acceptance. |
 | `accepted` with `phase: learning` and `learning.status: followup_required` | Learning was captured but at least one routed follow-up is still open or undecided. | Active learning follow-up until routed to backlog, docs, evals, skills, knowledge, or an explicit deferred trigger. |
-| `delivered`, `accepted`, or `archived` with `phase: done`, or `accepted`/`archived` with closed learning routing | Completed local workflow. | Not active WIP; retain only while useful for recovery or audit. |
+| `delivered`, `accepted`, or `archived` with `phase: done`, or `accepted`/`archived` with closed learning routing | Completed local workflow. | Terminal only once a promotion claim is recorded (see [Promote-Then-Archive Gate](#promote-then-archive-gate)); a delivered/accepted session with no promotion claim is a cleanup candidate, not terminal. Retain only while useful for recovery or audit. |
 
 `verified` is not a terminal state. It means the verifier supplied evidence. Final acceptance must still record the provider change, CI/release result, docs promotion decision, and any learning route before the workflow stops being active.
 
+## Promote-Then-Archive Gate
+
+Archiving a delivered session is not a parallel chore to promoting its durable
+residue — it is **gated on** it. The sequence is:
+
+```
+final acceptance  ->  promote  ->  archive
+```
+
+Durable-residue extraction is the archival act. A delivered session's decisions,
+vocabulary, learnings, and doc updates must be promoted into durable living docs
+(`docs/decisions/<slug>.md`, `CONTEXT.md`, `docs/learnings/*`, `README.md`,
+`context/contracts/`, schemas, provider records) before the session is retired,
+so no delivered work is retired without its knowledge extracted.
+
+### The promotion claim
+
+The `promote` step records **what was promoted where** and writes a **promotion
+claim** into the session `trust.bundle`:
+
+```bash
+# Real durable residue: each --evidence-path must exist on disk at record time.
+flow-agents workflow-sidecar promote <session-dir> \
+  --evidence-path docs/decisions/<slug>.md \
+  --evidence-path CONTEXT.md
+```
+
+The claim is **session-local by construction** (check kind `policy` ->
+`policy_rule` evidence, no command / `execution.label`). It therefore needs **no
+new reconcile-manifest entry** and can **never** become a `[not-run]` /
+unbacked-command divergence at CI `trust-reconcile`: the reconciler classifies it
+session-local and accepts it as an ATTESTED claim. The durable doc paths are the
+claim's evidence refs; each is verified to exist on disk when the claim is
+recorded (a missing path fails loud), and they are mirrored into an auditable
+`promotion.json` in the session directory. The claim is detectable by the archive
+gate and validators via `claim.metadata.promotion` without any manifest change.
+
+### Empty-promotion path
+
+When a delivered session genuinely produced **no durable residue** (e.g. a pure
+refactor with no decision, vocabulary, or doc change), record an explicit,
+auditable no-residue promotion rather than skipping the gate:
+
+```bash
+flow-agents workflow-sidecar promote <session-dir> \
+  --none --reason "<why nothing durable was promoted>"
+```
+
+This still produces a promotion claim (with `none: true` and the reason), so the
+decision that nothing needed promoting is recorded, not silently assumed.
+
+### Archive enforcement
+
+`workflow-artifact-cleanup-audit` classifies a **delivered or accepted** session
+that reached a terminal shape **without** a promotion claim as a
+`cleanup_candidate` (blocked from archive) with a reason naming the `promote`
+remedy — not `terminal_done`. With the claim (real residue **or** `--none`) it
+classifies `terminal_done` and may be archived. Already-`archived` sessions are
+past the gate and are never re-flagged; this gate is not a backfill of historical
+archives.
+
 ## Learning Closeout
 
 Learning records are a routing surface, not a permanent parking lot.
@@ -75,13 +138,13 @@ Durable learning should be promoted by target:
 
 ## Local Retention Policy
 
-For local-only users, keep enough local state to recover recent work, but do not use `.flow-agents/<slug>/` as the long-term system of record.
+For local-only users, keep enough local state to recover recent work, but do not use `.kontourai/flow-agents/<slug>/` as the long-term system of record.
 
 Recommended defaults:
 
 | Artifact class | Retain locally | Durable destination |
 | --- | --- | --- |
-| Active WIP, blockers, and unresolved decisions | Until resolved | Current `.flow-agents/<slug>/` state and handoff. |
+| Active WIP, blockers, and unresolved decisions | Until resolved | Current `.kontourai/flow-agents/<slug>/` state and handoff. |
 | Recently merged or accepted deliveries | 14-30 days, or until the next queue audit | PR body, issue comments, release records, promoted docs, or archived evidence refs. |
 | Security, migration, release, or provider-governance evidence | 30-90 days when useful for audit | Provider record, release note, durable doc, or external evidence store. |
 | Routine successful local runtime artifacts | Delete or archive after durable promotion and recovery window | Usually none beyond provider record and docs. |
@@ -117,10 +180,10 @@ Before merge to `main`:
 
 1. Promote durable behavior, contracts, decisions, operations notes, and usage guidance into long-lived docs such as `README.md`, `docs/`, `docs/adr/`, schema docs, runbooks, changelogs, or provider records.
 2. Make sure the durable record names the promotion targets and any accepted gaps.
-3. Confirm `.flow-agents/` runtime artifacts remain untracked.
+3. Confirm `.kontourai/flow-agents/` runtime artifacts remain untracked.
 4. Keep links to provider records, durable docs, or archived external evidence instead of relying on temporary local files.
 
-`main` must not contain tracked files under `.flow-agents/`. If runtime artifacts still seem necessary after merge, their durable content has not been promoted yet.
+`main` must not contain tracked files under `.kontourai/flow-agents/`. If runtime artifacts still seem necessary after merge, their durable content has not been promoted yet.
 
 ## Promotion Targets
 
@@ -138,4 +201,4 @@ Do not promote raw intermediate thinking wholesale. Promote the resulting decisi
 
 ## Enforcement
 
-Runtime state remains ignored under `.flow-agents/`. Static package validation fails if runtime artifacts are tracked. Reviewers should reject PRs that omit durable docs, source, schema, provider, or evidence updates needed to understand shipped behavior.
+Runtime state remains ignored under `.kontourai/flow-agents/`. Static package validation fails if runtime artifacts are tracked. Reviewers should reject PRs that omit durable docs, source, schema, provider, or evidence updates needed to understand shipped behavior.

package/docs/workflow-eval-strategy.md

@@ -49,7 +49,7 @@ These check that skill contracts preserve non-negotiable guardrails:
 
 Static evals prove documented contracts did not drift. They do not prove the agent follows them in conversation.
 
-Activation-only behavioral evals may assert no write tools when the goal is trigger and boundary testing. Artifact-quality evals must allow controlled writes to `.flow-agents/<slug>/*.md` and inspect the resulting artifact contracts.
+Activation-only behavioral evals may assert no write tools when the goal is trigger and boundary testing. Artifact-quality evals must allow controlled writes to `.kontourai/flow-agents/<slug>/*.md` and inspect the resulting artifact contracts.
 
 ### 2. Behavioral Activation Evals
 
@@ -79,7 +79,7 @@ These should verify:
 
 ### 3. Artifact Quality Evals
 
-Inspect generated `.flow-agents/<slug>/*.md` files and provider-backed work item drafts for required structure.
+Inspect generated `.kontourai/flow-agents/<slug>/*.md` files and provider-backed work item drafts for required structure.
 
 The local artifact-quality gate is:
 
@@ -117,7 +117,7 @@ These cases check that the gates resist pressure and ambiguity:
 - CI passes only after unexplained reruns; `evidence-gate` should degrade confidence.
 - Prototype code exists; workflow should require learning review before production promotion.
 - Release notes, rollback, or observability are missing for production-impacting work; `release-readiness` should return `HOLD`, optionally routing missing evidence back to `evidence-gate`.
-- Agent tries to stop with an active `.flow-agents/<slug>/` delivery artifact; `stop-goal-fit` should warn and strict mode should block.
+- Agent tries to stop with an active `.kontourai/flow-agents/<slug>/` delivery artifact; `stop-goal-fit` should warn and strict mode should block.
 - CI/merge acceptance happens but docs are not promoted; release readiness or learning review should record a docs follow-up or explain why durable docs are not needed.
 - Temporary verifier-local sidecar mismatch notes remain in the history; terminal artifacts must show final sidecar reconciliation before reporting clean delivery.
 - Deep-context delivery contains stale shortcuts; agent should ignore stale context and still preserve Definition Of Done, explicit `NOT_VERIFIED`, Goal Fit, and Final Acceptance.

package/docs/workflow-shared-contracts.md

@@ -10,6 +10,7 @@ The workflow system now separates durable process contracts from role-specific i
 
 Shared contracts live in `context/contracts/`:
 
+- `standing-directives.md`
 - `artifact-contract.md`
 - `planning-contract.md`
 - `execution-contract.md`
@@ -17,7 +18,7 @@ Shared contracts live in `context/contracts/`:
 - `verification-contract.md`
 - `delivery-contract.md`
 
-These files define the stable rules for artifacts, planning, execution, review, verification, delivery loops, Goal Fit, and final acceptance.
+These files define the stable rules for artifacts, planning, execution, review, verification, delivery loops, Goal Fit, and final acceptance. `standing-directives.md` is cross-cutting: it holds ratified owner directives that override default engineering conservatism, pointed to from the header of every other contract file so delegated agents receive it regardless of which phase contract they load.
 
 The durable resource shape for selected scope, workflow runs, run plans, status conditions, provider-backed Work Items, and sidecar compatibility direction is documented in the Kontour Resource Contract:
 https://github.com/kontourai/flow-agents/blob/main/docs/kontour-resource-contract.md
@@ -27,7 +28,7 @@ That reference is docs-only guidance for new resource-shaped contracts and does
 The lifecycle for in-progress and completed workflow artifacts is documented in the Workflow Artifact Lifecycle:
 https://github.com/kontourai/flow-agents/blob/main/docs/workflow-artifact-lifecycle.md
 
-Runtime workflow artifacts under `.flow-agents/` remain local and ignored. Completed work must promote durable behavior, decisions, contracts, and evidence into long-lived docs, source, schemas, or provider records before merge to `main`.
+Runtime workflow artifacts under `.kontourai/flow-agents/` remain local and ignored. Explicit durable Flow Agents config/install state may live under `.flow-agents/` when documented, but runtime readers do not fall back there. Completed work must promote durable behavior, decisions, contracts, and evidence into long-lived docs, source, schemas, or provider records before merge to `main`.
 
 ## How Skills And Agents Use Them