@kontourai/flow-agents 3.0.0 → 3.2.0

package/docs/decisions/trust-reconcile.md

@@ -0,0 +1,20 @@
+---
+status: needs-decision
+subject: Trust-reconcile and delivery reconciliation
+decided: 2026-07-03
+evidence:
+  - kind: adr
+    ref: docs/adr/0020-trust-reconcile-manifest-and-claim-classification.md
+  - kind: adr
+    ref: docs/adr/0022-fail-closed-delivery-reconciliation-with-governed-exemptions.md
+---
+# Trust-reconcile and delivery reconciliation
+
+This subject has provenance in frozen ADR history ([0020-trust-reconcile-manifest-and-claim-classification.md](../adr/0020-trust-reconcile-manifest-and-claim-classification.md), [0022-fail-closed-delivery-reconciliation-with-governed-exemptions.md](../adr/0022-fail-closed-delivery-reconciliation-with-governed-exemptions.md)) but no living
+decision has been ratified yet under the topic-keyed decision registry
+(`context/contracts/decision-registry-contract.md`). This stub records that the
+subject is open and links the frozen ADR(s) as provenance; it is not a decision.
+
+When a living decision is ratified for Trust-reconcile and delivery reconciliation, update this
+file's `status` to `current`, add rationale, and keep the `adr` evidence
+links as provenance for the history that led here.

package/docs/decisions/typescript-source-policy.md

@@ -0,0 +1,48 @@
+---
+status: current
+subject: TypeScript-first source policy
+decided: 2026-07-04
+evidence:
+  - kind: adr
+    ref: docs/adr/0006-typescript-first-source-policy.md
+  - kind: session-archive
+    ref: .kontourai/flow-agents/kontourai-flow-agents-311/kontourai-flow-agents-311--deliver.md
+  - kind: issue
+    ref: https://github.com/kontourai/flow-agents/issues/311
+---
+
+# TypeScript-first source policy
+
+Kontour product and runtime source defaults to TypeScript across Flow, Flow
+Agents, Surface, Veritas, and `kontourai.io`. New durable product code, runtime
+adapters, package APIs, CLI behavior, workflow orchestration, hooks, provider
+bridges, and shared contracts are authored in TypeScript by default in
+repositories that are TypeScript-enabled or migrating toward TypeScript.
+
+## Decision
+
+- TypeScript-enabled repositories expose a typecheck or build validation that
+  proves the authored TypeScript surface compiles, and CI runs that validation
+  before code is treated as releasable.
+- Narrow JavaScript/MJS/CJS exceptions remain acceptable: package/tool
+  configuration that expects JS/MJS, generated docs/site assets, thin
+  shell-adjacent launchers, fixtures/examples/tests following existing local
+  convention, and historical archived/vendored/generated artifacts that are not
+  edited as active source. Exceptions stay narrow — expanding product/runtime
+  behavior in JS/MJS is a deliberate exception or routed into a migration plan.
+- Repositories with nontrivial non-TypeScript runtime source track staged
+  migration through repo-specific issues rather than being grandfathered as
+  permanent direction (see the original inventory and linked migration issues
+  in the frozen ADR below).
+
+## Rationale
+
+Cross-repo shared source, contracts, adapters, and workflow tooling need a
+consistent default language, or new work deepens fragmentation and turns every
+existing non-TypeScript file into an implicit permanent exception. This is a
+purely technical, already-settled call: the frozen ADR below made the decision
+on 2026-05-31 and it has not changed. This entry upgrades the ADR-freeze
+cutover's `needs-decision` stub for this subject (issue #314) to a living
+decision — nothing new is decided here beyond recording that the frozen ADR's
+call still stands, per the Probe docs-write contract's worked example
+(`context/contracts/probe-docs-write-contract.md`).

package/docs/decisions/workflow-enforcement.md

@@ -0,0 +1,18 @@
+---
+status: needs-decision
+subject: Workflow Enforcement
+decided: 2026-07-03
+evidence:
+  - kind: adr
+    ref: docs/adr/0001-flow-agents-consumes-flow.md
+---
+# Workflow Enforcement
+
+This subject has provenance in frozen ADR history ([0001-flow-agents-consumes-flow.md](../adr/0001-flow-agents-consumes-flow.md)) but no living
+decision has been ratified yet under the topic-keyed decision registry
+(`context/contracts/decision-registry-contract.md`). This stub records that the
+subject is open and links the frozen ADR(s) as provenance; it is not a decision.
+
+When a living decision is ratified for workflow enforcement, update this
+file's `status` to `current`, add rationale, and keep the `adr` evidence
+links as provenance for the history that led here.

package/docs/decisions/workflow-trust-state.md

@@ -0,0 +1,20 @@
+---
+status: needs-decision
+subject: Workflow trust state
+decided: 2026-07-03
+evidence:
+  - kind: adr
+    ref: docs/adr/0004-gates-expect-surface-claims.md
+  - kind: adr
+    ref: docs/adr/0010-workflow-trust-state-as-hachure-bundle.md
+---
+# Workflow trust state
+
+This subject has provenance in frozen ADR history ([0004-gates-expect-surface-claims.md](../adr/0004-gates-expect-surface-claims.md), [0010-workflow-trust-state-as-hachure-bundle.md](../adr/0010-workflow-trust-state-as-hachure-bundle.md)) but no living
+decision has been ratified yet under the topic-keyed decision registry
+(`context/contracts/decision-registry-contract.md`). This stub records that the
+subject is open and links the frozen ADR(s) as provenance; it is not a decision.
+
+When a living decision is ratified for workflow trust state, update this
+file's `status` to `current`, add rationale, and keep the `adr` evidence
+links as provenance for the history that led here.

package/docs/fixture-ownership.md

@@ -13,7 +13,7 @@ run `npm run validate:source --` and `npm run fixture:retirement-audit --`.
 
 | Fixture directory | Classification | Owners | Cleanup rule |
 | --- | --- | --- | --- |
-| `evals/fixtures/assignment-provider` | AssignmentProvider local-file and GitHub render/status fixtures (#290) | `evals/integration/test_assignment_provider_local_file.sh`, `evals/integration/test_assignment_provider_github.sh`, `evals/integration/test_pull_work_assignment_join.sh` | Keep while the assignment provider contract's claim/release/supersede/status/list operations and the assignment ⋈ liveness join are tested against local-file and GitHub fixture inputs. |
+| `evals/fixtures/assignment-provider` | AssignmentProvider local-file and GitHub render/status fixtures (#290); hostile-effective-state.json is the #291 ensure-session ownership guard's AC9 sanitization fixture | `evals/integration/test_assignment_provider_local_file.sh`, `evals/integration/test_assignment_provider_github.sh`, `evals/integration/test_pull_work_assignment_join.sh`, `evals/integration/test_ensure_session_ownership_guard.sh` | Keep while the assignment provider contract's claim/release/supersede/status/list operations and the assignment ⋈ liveness join are tested against local-file and GitHub fixture inputs. |
 | `evals/fixtures/backlog-provider-settings` | settings precedence fixtures | `evals/integration/test_effective_backlog_settings.sh` | Keep while backlog provider settings resolution supports global defaults and project overrides. |
 | `evals/fixtures/builder-kit-workflow-state` | Builder Kit workflow-state fixtures | `evals/static/test_workflow_skills.sh` | Keep while Builder Kit state contract and resume behavior are documented in workflow skill contracts. |
 | `evals/fixtures/console-learning-projection` | console learning projection fixtures | `evals/integration/test_console_learning_projection.sh` | Keep while learning projection supports correction and open-route examples. |

package/docs/workflow-usage-guide.md

@@ -255,7 +255,7 @@ When verification or evidence gates route work backward, the handoff must name b
 
 For pickup or planning alignment gaps, `decision_gap -> design-probe` means returning to the pickup Probe record, resolving the missing decision or recording an accepted gap, and only then retrying `plan-work`.
 
-Pickup Probe may update durable docs only when the decision is no longer a transient planning note. Use `CONTEXT.md` for glossary-style terminology decisions, create context files lazily only when a resolved term has no existing home, and create ADRs only for hard-to-reverse, surprising decisions that came from a real trade-off. Keep selected-work details, provider snapshots, unresolved questions, and accepted gaps in workflow artifacts until the work is accepted.
+Pickup Probe may update durable docs only when the decision is no longer a transient planning note. Use `CONTEXT.md` for glossary-style terminology decisions, create context files lazily only when a resolved term has no existing home, and record decision subjects as decision-registry deltas (`docs/decisions/<slug>.md`, revise-vs-create against `docs/decisions/index.md`) rather than numbered ADRs — see `context/contracts/probe-docs-write-contract.md`. Keep selected-work details, provider snapshots, unresolved questions, and accepted gaps in workflow artifacts until the work is accepted.
 
 ## 7. Check Goal Fit Before Stopping
 

package/evals/ci/run-baseline.sh

@@ -24,7 +24,10 @@ CHECKS=(
   "Actor identity resolver integration|bash evals/integration/test_actor_identity.sh"
   "Assignment provider local-file integration|bash evals/integration/test_assignment_provider_local_file.sh"
   "Assignment provider github integration|bash evals/integration/test_assignment_provider_github.sh"
+  "Stop hook release-with-handoff integration|bash evals/integration/test_stop_hook_release.sh"
   "Pull work assignment join integration|bash evals/integration/test_pull_work_assignment_join.sh"
+  "Ensure-session ownership guard integration|bash evals/integration/test_ensure_session_ownership_guard.sh"
+  "Current.json per-actor integration|bash evals/integration/test_current_json_per_actor.sh"
   "Goal Fit hook integration|bash evals/integration/test_goal_fit_hook.sh"
   "Hook category behavior integration|bash evals/integration/test_hook_category_behaviors.sh"
   "Workflow steering hook integration|bash evals/integration/test_workflow_steering_hook.sh"
@@ -77,7 +80,10 @@ LANE_WORKFLOW_CONTRACTS=(
   "Actor identity resolver integration"
   "Assignment provider local-file integration"
   "Assignment provider github integration"
+  "Stop hook release-with-handoff integration"
   "Pull work assignment join integration"
+  "Ensure-session ownership guard integration"
+  "Current.json per-actor integration"
 )
 
 LANE_RUNTIME_AND_KIT=(

package/evals/fixtures/assignment-provider/hostile-effective-state.json

@@ -0,0 +1,11 @@
+{
+  "_comment": "Hostile-string fixture for #291 AC9 (ensure-session ownership guard sanitization). Simulates the precomputed .effective JSON a GitHub-provider caller would pass via --effective-state-json, where the .assignee field originates from an attacker-postable GitHub login/comment. The assignee value below embeds a real ESC (ANSI CSI lead-in) and a real BEL control byte -- both must be stripped (never echoed raw) by ensure-session's guard before this value is interpolated into any die() remediation message.",
+  "effective": {
+    "effective_state": "human-held",
+    "reason": "assignee_is_human",
+    "holder": {
+      "assignee": "hostile-assignee\u001b[31;1mFAKE-ADMIN\u0007-login",
+      "idle_days": 3
+    }
+  }
+}

package/evals/integration/test_checkpoint_signing.sh

@@ -298,10 +298,11 @@ else
   _fail "advance-state --status delivered exited $SEAL_EXIT (signing must not break the seal)"
 fi
 
-if [[ -f "$REPO_ROOT2/delivery/trust.bundle" ]]; then
-  _pass "publish-delivery published into the explicit scratch --repo-root ($REPO_ROOT2/delivery/trust.bundle), not process.cwd()"
+# #379: publishDelivery writes to the per-session path delivery/<slug>/trust.bundle.
+if [[ -f "$REPO_ROOT2/delivery/$SLUG2/trust.bundle" ]]; then
+  _pass "publish-delivery published into the explicit scratch --repo-root ($REPO_ROOT2/delivery/$SLUG2/trust.bundle, #379 per-session), not process.cwd()"
 else
-  _fail "publish-delivery did not write to the explicit scratch --repo-root ($REPO_ROOT2/delivery/trust.bundle) — check the --repo-root plumbing in advanceState"
+  _fail "publish-delivery did not write to the explicit scratch --repo-root ($REPO_ROOT2/delivery/$SLUG2/trust.bundle) — check the --repo-root plumbing in advanceState"
 fi
 
 if [[ -f "$SESSION_DIR2/trust.checkpoint.json" ]]; then