agentflow-runtime 1.5.0__tar.gz → 1.6.0__tar.gz

{agentflow_runtime-1.5.0 → agentflow_runtime-1.6.0}/.gitignore

@@ -72,7 +72,7 @@ node_modules/
 # Mutation testing output
 mutants/
 
-# Session notes (root-level temp .md created during Codex/Claude sessions).
+# Local working notes (root-level temp .md created during dev sessions).
 # NOTE: BCG_audit.md was removed from this list on 2026-04-19 -
 # it was a release artifact, not a session note.
 /codex_res.md
@@ -93,12 +93,14 @@ integrations/agentflow_integrations/**/*.py[cod]
 agentflow_bench_debug*.duckdb*
 agentflow_demo_api.duckdb*
 
-# Local autopilot runtime state.
+# Local autopilot tooling + runtime state (kept locally, not published).
 .autopilot/
+/scripts/autopilot.ps1
+/scripts/install-autopilot-task.ps1
+/tests/unit/test_autopilot_runner.py
 
-# Operator scratch notes at the repo root (user-owned audit prompts/results;
-# codex audit F-6). Ignored so the autopilot clean-tree gate and git status
-# stay quiet without touching the files themselves.
+# Local scratch notes at the repo root (audit prompts/results). Ignored so
+# the clean-tree gate and git status stay quiet without touching the files.
 /p[0-9].md
 /p[0-9]_res*.md
 /p_res*.md
@@ -106,3 +108,46 @@ agentflow_demo_api.duckdb*
 
 # Security scan workdir (generated by .github/workflows/security.yml safety job)
 .tmp-security/
+
+# Internal working notes / autonomous-session artifacts — kept locally, not published.
+# These are process/handoff/scratch docs, not product or engineering documentation.
+/AGENT_STATE.md
+/AUTOPILOT.md
+/BACKLOG.md
+/help.md
+/res.md
+/all-open-questions-closure-plan.md
+/close-gaps-plan.md
+/road-to-9.8.md
+/desc_for_julia.md
+/fable_*.md
+/next-session-*.md
+/second-opinion-*.md
+/.pi/
+/.workflow/
+/res/
+docs/dv2-multi-branch/kimi_*.md
+docs/dv2-multi-branch/RECORDING_DAY.md
+docs/dv2-multi-branch/pitch.md
+docs/dv2-multi-branch/brief.md
+docs/operations/local-verification-matrix.md
+docs/release-readiness-archive/
+docs/codex-tasks/
+docs/plans/codex-archive/
+docs/lessons/
+docs/audits/
+docs/exploration/
+docs/audit-history.md
+docs/SESSION_HANDOFF.md
+docs/dv2-multi-branch/SESSION_HANDOFF*.md
+docs/customer-discovery-*.md
+docs/pricing-validation-plan.md
+docs/v1-1-interview-prep.md
+docs/v1-1-research.md
+docs/operations/autonomous-compact-safe-process.md
+docs/operations/external-gate-evidence-intake.md
+docs/operations/external-pen-test-attestation-handoff.md
+docs/operations/generated-external-gate-pack-*.md
+docs/operations/guarded-autopilot-*.md
+docs/operations/immutable-retention-evidence-handoff.md
+docs/operations/security-evidence-template.md

{agentflow_runtime-1.5.0 → agentflow_runtime-1.6.0}/CHANGELOG.md

@@ -4,6 +4,236 @@ All notable changes to AgentFlow are documented in this file.
 
 ## [Unreleased]
 
+## [1.6.0] - 2026-07-02
+
+### Added — vault-side PII governance on the engine (ADR 0006 Phase 2, executed 2026-07-02)
+
+- **New `warehouse/agentflow/dv2/governance/`** — ClickHouse RBAC as the PII
+  boundary for the DV2 vault, replacing the removed app-level string-parse
+  gate with access control on resolved columns: `dv2_analyst` (cross-branch
+  analytics, fail-closed allow-list, contact-PII columns never granted) and
+  per-jurisdiction `dv2_pii_officer__<branch>` roles (own branch's
+  `bv_customer_mdm` view + personal satellite only), plus row policies
+  scoping the shared `rv.hub_customer` to the officer's jurisdiction (with
+  the mandatory catch-all keeping non-officer visibility independent of
+  `users_without_row_policies_can_read_rows`).
+- **`bv_customer_mdm__*` views run `SQL SECURITY DEFINER`** so column-limited
+  grants on the views work without exposing the underlying
+  `sat_customer_personal__1c__*` satellites to readers.
+- **`marts.customer_360` is PII-free by contract** — the cross-branch
+  materialized mart no longer selects `first_name`/`last_name`/`email`
+  (copying jurisdiction-bound PII past the column grants at build time);
+  `pii_source` metadata stays.
+- **Verified live** against ClickHouse 26.7 (32/32 adversarial probes): every
+  PII shape denied for `dv2_analyst` — including the three historical
+  bypass forms of the removed app gate, two of which are not even expressible
+  on this engine — officers bounded to their jurisdiction, admin unaffected,
+  re-apply idempotent. Includes a root-caused ergonomic limitation of filter
+  pushdown over column-limited DEFINER views and its PII-safe subquery
+  workaround. Evidence: `docs/perf/vault-pii-governance-verify-2026-07-02.md`.
+- `infrastructure/dv2/clickhouse-sts.yaml` sets
+  `CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT: "1"` so the stand admin can apply
+  RBAC DDL; `tests/unit/test_dv2_governance_ddl.py` pins the boundary
+  structure (PII columns never granted, every satellite classified, catch-all
+  in sync with officer roles, DEFINER on the views, mart stays PII-free).
+
+### Changed — ClickHouse is the shipped serving engine (ADR 0006 Phase 1, executed 2026-07-02)
+
+- **`config/serving.yaml` defaults to `backend: clickhouse`.** `make demo`,
+  `docker-compose.yml`, and `docker-compose.prod.yml` bring the ClickHouse
+  service up by default (the `--profile clickhouse` gate is removed; the API
+  container `depends_on` its healthcheck). Rollback is config-only
+  (`SERVING_BACKEND=duckdb`). Tests stay pinned to DuckDB
+  (`tests/conftest.py`), and DuckDB remains the local-dev / test store.
+- **The local pipeline writes the serving store** — new
+  `src/processing/clickhouse_sink.py`: when the configured backend is
+  ClickHouse, every validated event mirrors its serving-table writes and its
+  `pipeline_events` journal row there (dead-letter rows included), after the
+  DuckDB commit. A configured-but-unreachable ClickHouse fails loudly instead
+  of letting the demo serve a frozen seed.
+- **Upserts are ReplacingMergeTree row versions.** The four mutable serving
+  tables move from `MergeTree` to `ReplacingMergeTree` versioned by a
+  `MATERIALIZED af_updated_at` column (invisible to `SELECT *`, inserts, and
+  `table_columns`); every backend read carries the `final=1` setting so
+  queries always see the latest version. **Existing demo ClickHouse volumes
+  must be dropped and re-seeded** (engine changes don't apply to existing
+  tables; the demo store is disposable by design).
+- **The freshness-critical event scan goes through the serving backend.** New
+  `QueryEngine.fetch_pipeline_events()`; the webhook dispatcher (which also
+  drives metric-cache invalidation) and the `/v1/stream/events` SSE scan
+  delegate to it instead of reaching into the embedded DuckDB connection — so
+  event-driven freshness works when the writer is out-of-process and the
+  engine is external. Verified live against a real ClickHouse 26.7 server:
+  cross-process burst moved the served revenue metric, SSE streamed
+  ClickHouse-only events, upsert dedup read back one latest-version row
+  (`docs/perf/clickhouse-serving-verify-2026-07-02.md`).
+- **Transpile safety net:** `ClickHouseBackend._translate_sql` now fails
+  closed if any table reference — including the tenant schema qualifier
+  applied by `_scope_sql` *before* the rewrite — does not survive the
+  duckdb→clickhouse transpile or does not re-parse. Guards the
+  rewrite-after-guard seam that produced the historical PII bypasses, now for
+  tenant isolation.
+- **Fixed (found by the live verification):** the ClickHouse backend sent the
+  session-database URL parameter on the `CREATE DATABASE` bootstrap statement,
+  which fails with `UNKNOWN_DATABASE` on a bare server (Docker's
+  `CLICKHOUSE_DB` pre-creation masked it).
+- **Helm:** new `serving.*` values wire `SERVING_BACKEND` /
+  `CLICKHOUSE_*` env (password via `existingSecret`); the chart default stays
+  the safe single-node DuckDB profile because the chart ships no ClickHouse
+  service. **ADR 0009** records the honest scaling gate: the control plane
+  (webhook queue, alert history, outbox, usage) is an embedded per-pod DuckDB
+  store, so `replicaCount`/`autoscaling` stay pinned even on the ClickHouse
+  profile until it is externalized.
+
+### Removed
+
+- **The serving-layer PII protection is removed — it guarded columns that do not
+  exist.** The demo serving warehouse holds no PII: `users_enriched` and
+  `orders_v2` (and every other serving table) carry only analytics columns
+  (aggregates, ids, timestamps) — none of the fields declared in the former
+  `config/pii_fields.yaml` (`email`, `phone`, `full_name`, `ip_address`,
+  `shipping_address`) exist in the catalog entity contracts or the physical DDL.
+  So the interim NL→SQL `assert_no_pii_access` deny-gate and the entity-path
+  `redact_entity` masker were operating on a surface that is never present in the
+  demo — defense-in-depth over an empty set. Both are deleted, along with
+  `src/serving/pii_policy.py`, `config/pii_fields.yaml`, their CI coverage /
+  mutation gates, the helm `piiFields` config, and the `X-PII-Masked` emission
+  (the versioned header stays reserved; the generic version-transform that would
+  strip it for older clients is unchanged). This also un-breaks the rule-based
+  `SELECT *` user/order lookups the deny-gate had been rejecting. The earlier
+  SQL-lineage masker (`src/serving/masking.py`, removed in the same cycle) is
+  likewise gone. **Real contact PII lives only in the DV2 business vault**
+  (`warehouse/agentflow/dv2/business_vault/bv_customer_mdm__*.sql`), and its
+  governance belongs engine-side there — ClickHouse row/column policies, tracked
+  as ADR 0006 Phase 2 — not in a dialect-pinned string parse in the serving tier.
+
+### Changed
+
+- **NL→SQL LLM path now routes through the GraceKelly orchestration API**
+  (`nl_engine._llm_translate`), not a direct provider SDK. It POSTs to
+  `${GRACEKELLY_URL}/api/v1/orchestrate` with the target model
+  (`GRACEKELLY_NL_SQL_MODEL`, default `claude-sonnet-5`); GraceKelly owns model
+  execution (browser-backed). LLM mode is gated on `GRACEKELLY_URL` (was
+  `ANTHROPIC_API_KEY`); engine detection across the query package, analytics, and
+  agent-query telemetry was realigned to match. The previous direct
+  `claude-sonnet-4-20250514` call is removed. The shipped demo still runs the
+  **rule-based** translator (GraceKelly is opt-in, unset in deploy configs);
+  when configured, GraceKelly serves `claude-sonnet-5`.
+- **Serving engine decision: fixed on ClickHouse** (ADR 0006 + 0007). The demo
+  serving default moves DuckDB → ClickHouse, with DuckDB demoted to the
+  local-dev / test and compatibility store. This unblocks engine-native bounded
+  PII (ClickHouse row/column policies) and real Kubernetes horizontal API
+  scaling. Recorded as a decision and staged in `docs/clickhouse-cutover-plan.md`;
+  the config/compose/Helm cutover itself is **not yet executed**.
+
+### Added
+
+- **DV2 raw vault migrated from ClickHouse to PostgreSQL** with a cloud
+  supplier / product reference (`warehouse/agentflow/dv2/`). Hubs, links, and
+  satellites are emitted in a PostgreSQL dialect (`argMax` → `DISTINCT ON`,
+  `splitByString` → `split_part`); both ingestion feeds (the X5 loader and the
+  reference loader) repoint to a shared, parameterized `pg_vault_writer`; and
+  OLTP → vault promotion runs as an in-database `INSERT … SELECT` now that OLTP
+  and the vault share one engine. The ClickHouse dialect regenerates
+  byte-for-byte and is retained for optional mart-serving. Each generated
+  `INSERT` is parsed by `sqlglot` in `tests/unit/test_dv2_postgres_ingestion.py`
+  to assert every interpolated column exists in the committed DDL. (#91)
+- **PyIceberg sink backed by a real MinIO object store** — the REST catalog
+  now writes through `S3FileIO` to `s3://agentflow-lake/warehouse` (the same
+  bucket the Flink path uses) instead of an ephemeral `/tmp/warehouse`
+  `HadoopFileIO`. A self-contained `docker-compose.iceberg.yml` (MinIO +
+  bucket-init + REST catalog) and env-overridable credentials in
+  `config/iceberg.yaml` make the local catalog object-store-backed; a no-Docker
+  guard asserts an `s3://` warehouse never triggers a local `mkdir`. (#92)
+- **Event-driven OLTP → vault freshness via PostgreSQL `LISTEN`/`NOTIFY`** —
+  `AFTER INSERT/UPDATE` triggers on each `ops_<branch>` table emit
+  `pg_notify('dv2_vault_refresh', …)`, and a guarded listener runs an
+  idempotent promote on each event (push, not polling), the PostgreSQL
+  equivalent of the ClickHouse `MaterializedPostgreSQL` CDC path. Lag is
+  observed on the server clock (`db_now`) to stay free of host/container
+  clock skew. The driver-agnostic core is covered no-Docker by
+  `tests/unit/test_dv2_freshness_listen_notify.py`. (#93)
+- OpenSSF Scorecard $0 supply-chain security posture channel:
+  `.github/workflows/scorecard.yml` (`ossf/scorecard-action@v2.4.3`) runs on
+  push to `main`, weekly, and on branch-protection changes with top-level
+  `read-all` permissions and a least-privilege analysis job
+  (`security-events`/`id-token` writes only), publishes the public Scorecard
+  result, and uploads SARIF to Code scanning. Shape-pinned by
+  `tests/unit/test_scorecard_workflow.py`. A companion
+  `docs/operations/openssf-security-posture.md` documents the channel and
+  carries a prepared OpenSSF Best Practices self-assessment for operator
+  submission. These are posture signals only — explicitly NOT a third-party
+  penetration-test attestation; backlog item 22 stays N/A and unclaimed.
+- Backlog item 19 reopened with a real evidence channel: the production
+  source is the operator-owned Neon Postgres backing VacancyRadar
+  (`public.vacancies`), recorded with an honest solo-org decision record in
+  `docs/operations/cdc-production-onboarding.md`. New dispatch-only
+  `.github/workflows/cdc-production-capture.yml` builds the repo's Debezium
+  Kafka Connect image, reads connection material only from Actions secrets
+  via FileConfigProvider, snapshots the approved table scope over TLS, writes
+  an evidence artifact, and always tears down the connector, publication, and
+  replication slot (shape tests pin dispatch-only, secret sourcing, sslmode,
+  the teardown trap, and always-upload). The first run waits on the operator
+  enabling Logical Replication on the Neon project (irreversible
+  `wal_level` flip).
+- Backlog item 21 closed with real evidence under an operator-amended
+  hardware class: `.github/workflows/benchmark-arm.yml` (dispatch-only) runs
+  the canonical benchmark on the free GitHub-hosted arm64 runner for public
+  repositories (`ubuntu-24.04-arm`, Neoverse-N2, 4 vCPU). First real run
+  (27012731848) recorded 554 requests / 0 failures, aggregate p50 6 ms /
+  p99 150 ms — every entity gate passed. Evidence in
+  `docs/perf/arm-server-benchmark-2026-06-05.md` plus raw artifacts; shape
+  tests pin dispatch-only/runner-label/artifact upload, and the job carries
+  an A06 dependency-profile target (`perf`). No `c8g.4xlarge` claim is made.
+
+### Changed
+
+- Dependency maintenance batch (consolidated from eight Dependabot PRs): the
+  Docker `python` base digest, `cp-kafka-connect-base` 7.9.7 → 7.9.8,
+  `apache-flink` 2.2.1 → 2.3.0 (validated by the Flink smoke job), and the SDK
+  `vitest` / `schemathesis` bumps, plus the GitHub Pages action major bumps
+  (`checkout` v7, `configure-pages` v6, `upload-pages-artifact` v5,
+  `deploy-pages` v5) — all SHA-pinned and validated on `main` by the Deploy
+  Pages and Flink Smoke runs. (#94)
+- Production CDC onboarding, PMF/pricing evidence, a production-hardware
+  benchmark, and an external pen-test attestation are documented as out of
+  scope for the current plan. Their acceptance criteria require external
+  counterparties (production source owners, real customers, production-grade
+  hardware, a third-party tester) that are deliberate non-goals for this
+  reference project. The gated claims remain explicitly unmade: production CDC
+  is not enabled, PMF/pricing is not validated, no production-hardware results
+  exist, and no third-party attestation exists. Status is summarized in
+  `docs/release-readiness.md`.
+
+### Security
+
+- First OpenSSF Scorecard cycle acted on — published score **5.8 → 7.0**,
+  open Code-scanning findings **163 → 53**, every remainder classified
+  accepted-open (see `docs/operations/openssf-security-posture.md` §4 for the
+  fixed/accepted-open split):
+  - Every `uses:` in all 19 workflows (99 references, 20 unique actions) is
+    pinned to a full commit SHA with a trailing `# <version>` comment that
+    Dependabot's `github-actions` ecosystem keeps updating. The convention is
+    enforced by the new `tests/unit/test_workflow_action_pinning.py`;
+    per-workflow shape tests now assert action identity (prefix) instead of
+    mutable tags.
+  - Top-level `permissions: contents: read` added to the five workflows that
+    ran on the default token (`staging-deploy`, `e2e`, `contract`,
+    `cdc-production-capture`, `benchmark-arm`), and
+    `container-attestation.yml` no longer grants
+    `packages`/`id-token`/`attestations` writes at the top level — they moved
+    to the two operator-dispatched signing jobs, so the every-PR `build-smoke`
+    job runs read-only (pinned by a new shape test).
+  - All four Dockerfile `FROM` lines are digest-pinned to their current
+    manifest-list digests, and the Dependabot `docker` ecosystem now covers
+    every Dockerfile directory (`directories:` list) so the pins keep moving
+    with upstream tags.
+  - `warehouse/agentflow/dv2/loaders/x5_retail_hero/requirements.txt` floors
+    raised: `pydantic>=2.9` (GHSA-mr82-8j83-vxmv ReDoS range started at the
+    old 2.0 floor) and `tqdm>=4.66.3` (PYSEC-2017-74 and the 2024 CLI
+    injection both fall below it). Resolution-floor fixes only; runtime code
+    is unchanged.
+
 ## [1.5.0] - 2026-06-05
 
 ### Added
@@ -37,7 +267,7 @@ All notable changes to AgentFlow are documented in this file.
   observe the `hashed_key_count_exceeds_guidance` warning (the warning still
   emits; only the capture goes blind). An autouse fixture now re-points the
   package logger at a fresh uncached proxy per test, making the file
-  order-independent. Found while reproducing the 2026-06-03 codex audit F-1
+  order-independent. Found while reproducing the 2026-06-03 audit F-1
   claim that the broad no-Docker full-repo pytest run is unreliable on this
   host: on the canonical `.venv` the run completes with a normal summary and
   leaves no orphan uvicorn child (the audit ran the shadow system Python),
@@ -111,7 +341,7 @@ All notable changes to AgentFlow are documented in this file.
 
 ### Changed
 
-- `scripts/` is now part of the CI Ruff gate (2026-06-03 codex audit F-2:
+- `scripts/` is now part of the CI Ruff gate (2026-06-03 audit F-2:
   release/benchmark/backup/security tooling had drifted to 20 lint errors and
   12 unformatted files that CI never checked). The 12 drifted scripts were
   reformatted (no semantic changes), import order and `datetime.UTC` usages
@@ -163,7 +393,7 @@ All notable changes to AgentFlow are documented in this file.
   spec are unchanged (`export_openapi.py --check` green).
 - The ClickHouse serving backend now translates DuckDB-flavored
   semantic-layer SQL through a sqlglot parse → AST rewrite → generate
-  pipeline instead of the former regex chain (PR #41; closes audit_kimi
+  pipeline instead of the former regex chain (PR #41; closes audit finding
   H-C2 in full — the earlier literal-masking commit was the narrow fix).
   String literals are preserved structurally by the parser, and
   unparseable or multi-statement SQL now fails loudly as
@@ -416,7 +646,7 @@ All notable changes to AgentFlow are documented in this file.
 - New module `src/serving/api/auth/usage_table.py` holds
   `ensure_usage_table` / `record_usage` / `usage_by_tenant`, which used
   to live alongside the ASGI middleware in
-  `src/serving/api/auth/middleware.py`. Closes Kimi audit L-C4
+  `src/serving/api/auth/middleware.py`. Closes audit L-C4
   ("DB utilities don't belong in a middleware file"). Public callers
   go through `AuthManager.*` shim methods unchanged; the only direct
   importer was `tests/unit/test_audit_publisher.py`, repointed to the
@@ -425,7 +655,7 @@ All notable changes to AgentFlow are documented in this file.
 
 ### Performance
 
-- The two Flink hot-path findings from `audit_kimi_25_05_26.md` are closed
+- The two Flink hot-path findings from the 2026-05 internal audit are closed
   now that the runtime is on 2.2.1 (they were gated on the PR #23 upstream
   wait). M-C3: `ValidateAndEnrich` emits `(event_id, payload)` pairs and the
   dedup `key_by` reads the key from the tuple, dropping the second
@@ -443,7 +673,7 @@ All notable changes to AgentFlow are documented in this file.
   events to two enriched outputs. The JSON-in-MapState layout is
   deliberately unchanged (checkpoint compatible).
 - `scripts/perf/auth_bench.py` + `docs/perf/auth-bench-2026-05-26.md`
-  — perf-baseline microbench closing two deferred Kimi audit findings.
+  — perf-baseline microbench closing two deferred audit findings.
   Measured `authenticate()` worst-case at production `bcrypt_rounds=12`:
   N=5 hit-last p95 = 1.9 s, N=20 hit-last p95 = 8.1 s (exceeds the
   1100 ms POST load gate). M-C4 stays partial-deferred — steady-state
@@ -502,7 +732,7 @@ All notable changes to AgentFlow are documented in this file.
     counter branch and the `/metrics` exposure round trip.
 - 6 new unit tests in `tests/unit/test_cdc_connector_configs.py`
   exercise `src.ingestion.connectors.{mysql_cdc,postgres_cdc}`
-  pure-Python config builders. Closes Kimi audit R4: both files
+  pure-Python config builders. Closes audit R4: both files
   went from 0% to 100% combined (line+branch) unit coverage; total
   `src.ingestion` rose 82% → ~85%. Tests pin the operational knobs
   the `cdc-lag` runbook depends on (snapshot mode, heartbeat
@@ -514,7 +744,7 @@ All notable changes to AgentFlow are documented in this file.
 - `.github/workflows/contract.yml` now triggers on
   `infrastructure/terraform/**`, `sdk-ts/**`, and `Dockerfile*`
   paths in addition to the existing src/sdk/pyproject/workflows
-  set. Closes Kimi audit R2 and removes the last remaining
+  set. Closes audit R2 and removes the last remaining
   `--admin merge` workaround from session 18 for changes outside
   the Python tree.
 - `.github/workflows/ci.yml` main coverage gate
@@ -534,7 +764,7 @@ All notable changes to AgentFlow are documented in this file.
   `build-push-sign-attest` + `attest-and-sign` jobs are gated
   behind `github.event_name == 'workflow_dispatch'` so a PR can
   never accidentally fire the ghcr.io push / cosign sign path.
-  Closes Kimi audit R6. A new
+  Closes audit R6. A new
   `test_container_attestation_workflow_runs_smoke_on_pull_request`
   unit test asserts the trigger paths, the PR-event gate, and
   push/load shape. Local Docker Desktop 29.4.0 smoke verified the
@@ -548,7 +778,7 @@ All notable changes to AgentFlow are documented in this file.
   `int()` / `float()`) fixed with `cast()` at the JSON boundary.
   mypy is now clean on all 98 source files including
   `checkpointing`, `session_aggregation`, `session_aggregator`,
-  `stream_processor`. Closes Kimi audit R7.
+  `stream_processor`. Closes audit R7.
 
 ### Fixed
 
@@ -563,7 +793,7 @@ All notable changes to AgentFlow are documented in this file.
   fails. The DuckDB insert is now retried in isolation; the audit
   publish runs exactly once after a successful insert and a publish
   failure is logged as `audit_publish_failed` instead of re-driving
-  the retry loop. Closes Kimi audit H-C3. Two regression tests in
+  the retry loop. Closes audit H-C3. Two regression tests in
   `tests/unit/test_audit_publisher.py` pin the contract:
   `test_record_usage_no_duplicate_insert_when_publish_raises` and
   `test_record_usage_skips_publish_when_all_inserts_fail`.
@@ -573,7 +803,7 @@ All notable changes to AgentFlow are documented in this file.
   warning (`search_index_initial_rebuild_failed`) instead of
   aborting startup. The 60-second periodic rebuilder (which already
   catches its own exceptions) is still scheduled, so the search
-  surface can recover without a process restart. Closes Kimi audit
+  surface can recover without a process restart. Closes audit
   M-C1. Regression test:
   `tests/unit/test_lifespan_search_resilience.py::test_lifespan_survives_search_rebuild_failure`.
 
@@ -586,7 +816,7 @@ All notable changes to AgentFlow are documented in this file.
   literals (including `''`-escaped quotes) are masked with sentinel
   placeholders and restored after the rewrites. The `INTERVAL '...'`
   rewrite still runs first against raw SQL so quoted intervals
-  continue to collapse. Closes part of Kimi audit H-C2 (literal
+  continue to collapse. Closes part of audit H-C2 (literal
   corruption vector). Seven regression tests in
   `tests/unit/test_clickhouse_backend.py::TestTranslateSqlLiteralProtection`
   pin the contract against `::FLOAT`, `NOW()`, `COUNT(*)`, `TRUE`,
@@ -595,7 +825,7 @@ All notable changes to AgentFlow are documented in this file.
   against the system trust store explicitly via
   `ssl.create_default_context()` plumbed through to `urlopen`. Insecure
   HTTP backends (default for local-compose) omit the context kwarg so
-  Python's `http.client` path is unchanged. Closes part of Kimi audit
+  Python's `http.client` path is unchanged. Closes part of audit
   H-C2 (no explicit HTTPS validation). Two regression tests cover the
   secure (CERT_REQUIRED + check_hostname True) and insecure (`None`
   context) paths.
@@ -614,7 +844,7 @@ All notable changes to AgentFlow are documented in this file.
   rather than a 500. The latter parses its input through `sqlglot`
   (DuckDB dialect) and rejects multi-statement or non-`SELECT`
   payloads with `BackendExecutionError` before the `EXPLAIN` wrapper
-  runs. Closes Kimi audit H-C1. 13 new regression tests in
+  runs. Closes audit H-C1. 13 new regression tests in
   `tests/unit/test_duckdb_backend_sql_hardening.py` pin both paths
   against an injection corpus (semicolons, comments, UNION,
   numeric-prefix names, dot-pathology, whitespace) plus
@@ -625,7 +855,7 @@ All notable changes to AgentFlow are documented in this file.
   prior hard-coded `223345` would collide on the replication stream the
   moment a second instance came up against the same source. Default
   preserved as `DEFAULT_MYSQL_SERVER_ID = 223345` so existing
-  deployments are unchanged. Closes Kimi audit L-C2. Regression test
+  deployments are unchanged. Closes audit L-C2. Regression test
   `test_mysql_server_id_overridable_via_env` covers env override,
   invalid-int fallback, and unset-env fallback.
 - `_CONNECT_SECRET_KEY` in `src/ingestion/connectors/{mysql,postgres}_cdc.py`
@@ -634,13 +864,13 @@ All notable changes to AgentFlow are documented in this file.
   `FileConfigProvider` `${file:/path:<key>}` syntax, not a credential).
   The previous `"pass" + "word"` concatenation was security through
   obscurity — bytecode collapses the expression and string scanners
-  still see the result. Closes Kimi audit L-C1.
+  still see the result. Closes audit L-C1.
 - Redundant `event_type == prefix` clauses dropped from
   `src/quality/validators/{schema,semantic}_validator.py`. Python's
   `str.startswith(prefix)` already returns True for the exact-equality
   case (`"order.".startswith("order.")`), so the `or event_type == prefix`
   branch could never fire when the prefix was a non-empty string.
-  Closes Kimi audit L-C3.
+  Closes audit L-C3.
 - `AuthManager` no longer grows its `_rate_windows`,
   `_failed_auth_windows`, and `_runtime_plaintext_by_hash` dictionaries
   unbounded. A new `_sweep_expired_windows()` helper drops entries
@@ -650,7 +880,7 @@ All notable changes to AgentFlow are documented in this file.
   is cheap and bounds growth between reloads). `load()` also purges
   cached plaintext-by-hash entries for hashes that no longer appear in
   the live `_hashed_keys` list, so a revoked/rotated key's plaintext
-  cannot remain pinned in memory across reloads. Closes Kimi audit
+  cannot remain pinned in memory across reloads. Closes audit
   H-C4. Regression tests in
   `tests/unit/test_auth_manager_memory_bounds.py` cover the sweep on
   load, the sweep on clear, the plaintext cache purge, and idempotency
@@ -664,15 +894,9 @@ wave 2 dependency bumps that landed in sessions 11–19.
 
 ### Documentation
 
-- Top-level [`docs/SESSION_HANDOFF.md`](docs/SESSION_HANDOFF.md) — the
-  entry point for picking up the project cold. Includes the four
-  orientation commands to run first, the priority-tiered open work
-  (Tier A actionable Dependabot PRs, Tier B externally user-gated
-  A04/A05/A03, Tier C forward backlog), a compressed view of sessions
-  11 → 17, and the load-bearing lessons from session 17's regression
-  (Contract Tests path filter, Dependabot cascade transitive
-  conflicts, memory-staleness check before recommending). README
-  surfaces it at the top of the Documentation index.
+- Curated the README Documentation index as the cold-start entry point,
+  grouping the architecture, API reference, on-call runbooks, and security
+  audit so the project's published docs are reachable in one hop.
 
 ### Fixed
 
@@ -793,7 +1017,7 @@ wave 2 dependency bumps that landed in sessions 11–19.
   optional-pyyaml `try/except ImportError` blocks (PyYAML is currently
   a hard runtime dependency, but the JSON-fallback machinery in
   `webhook_dispatcher.py`, `slo.py`, `alerts/dispatcher.py` etc. is
-  intentionally kept available — see SESSION_HANDOFF.md anti-tasks).
+  intentionally kept available).
 - `types-redis` added to the dev extra. Two
   `# type: ignore[import-untyped,unused-ignore]` annotations on
   `import redis.asyncio as redis` retired in `src/serving/cache.py`
@@ -913,16 +1137,12 @@ wave 2 dependency bumps that landed in sessions 11–19.
 - Prepared npm publishing for Trusted Publishing through GitHub Actions OIDC:
   the TypeScript SDK publish workflow now requires npm CLI 11.5.1+ and no
   longer passes `NPM_TOKEN` to the production `npm publish` step.
-- Recorded the npm Trusted Publishing handoff: the new package was first
-  published as `@yuliaedomskikh/agentflow-client@1.1.0`, Trusted Publisher
-  setup succeeded for `brownjuly2003-code/agentflow` with workflow
-  `publish-npm.yml`, CLI `npm trust list` readback is complete, and future
-  recovery-code use must keep a two-code reserve through the
-  `npm-recovery-codes` skill.
-- Documented the completed replacement npm account bootstrap for
-  `yulia.edomskikh@gmail.com`, the saved 2FA recovery-code reserve, and the
-  switch of future TypeScript SDK publishing to
-  `@yuliaedomskikh/agentflow-client`.
+- Recorded the npm Trusted Publishing handoff: the package
+  `@yuliaedomskikh/agentflow-client@1.1.0` was first published and Trusted
+  Publisher setup succeeded for `brownjuly2003-code/agentflow` with workflow
+  `publish-npm.yml`; CLI `npm trust list` readback is complete.
+- Switched future TypeScript SDK publishing to the
+  `@yuliaedomskikh/agentflow-client` npm scope.
 - Clarified that legacy `NPM_TOKEN` revocation remains blocked until a
   successful trusted-publish workflow run for `@yuliaedomskikh/agentflow-client`
   and accepted external-gate intake evidence exist.
@@ -946,11 +1166,10 @@ wave 2 dependency bumps that landed in sessions 11–19.
 
 ### Security (audit follow-up sprint 2026-04-27/28)
 
-Two external audits delivered against `4a13d36` (Claude Opus + Codex p1–p9,
-archived under `docs/audits/2026-04-27/`). Six commits closed all
-P0/P1/P2 findings.
+Two internal security audits were delivered against `4a13d36`. Six commits
+closed all P0/P1/P2 findings.
 
-**Tenant isolation across the control plane (Codex p1 R3/R5, p2_1 #1-3,
+**Tenant isolation across the control plane (audit p1 R3/R5, p2_1 #1-3,
 p3 #4):** `pipeline_events` and `dead_letter_events` got a
 `tenant_id VARCHAR DEFAULT 'default'` column with backwards-compatible
 `ALTER TABLE ADD COLUMN IF NOT EXISTS` migration in init paths. Writers
@@ -962,23 +1181,23 @@ normalizer accepts an explicit `topic=` argument and falls back through
 now scope to `request.state.tenant_id`. Cross-tenant regression tests
 added.
 
-**SQL guard centralization (Codex p2_1 #4, p2_2 #4, p3 #1):** new
+**SQL guard centralization (audit p2_1 #4, p2_2 #4, p3 #1):** new
 `_prepare_nl_sql()` helper in `nl_queries.py` is the only path that
 validates translated SQL via `validate_nl_sql()`; called from
 `execute_nl_query`, `paginated_query`, and `explain` before tenant
 scoping and pagination wrapping. Closes the bypass on `/v1/query`
 (paginated) and `/v1/query/explain`. PII masking and explain
 `tables_accessed` rewritten on `sqlglot` AST so tenant-quoted SQL like
-`"acme"."users_enriched"` is correctly extracted (Codex p3 #3).
+`"acme"."users_enriched"` is correctly extracted (audit p3 #3).
 
-**Entity allowlist enforcement (Codex p2_1 #4, p3 #2):** new
+**Entity allowlist enforcement (audit p2_1 #4, p3 #2):** new
 `tenant_key_allowed_tables()` helper in `auth/manager.py`. Applied to
 NL query / explain / paginated query, batch query/metric items,
 `/v1/search` (intersection with tenant key allowlist + post-filter so
 metric documents are not silently dropped for scoped keys), and
 `/v1/metrics/{metric}`.
 
-**Auth fail-closed + entropy + scopes (Codex p2_1 #5, p2_2 #1-3):**
+**Auth fail-closed + entropy + scopes (audit p2_1 #5, p2_2 #1-3):**
 auth middleware now fails closed with `503` when no API keys are
 configured; opt out with `AGENTFLOW_AUTH_DISABLED=true` for local dev
 or `app.state.auth_disabled = True` for tests. Failed-auth throttling
@@ -987,7 +1206,7 @@ immediate peer is in `AGENTFLOW_TRUSTED_PROXIES`. Generated API keys
 now use `secrets.token_urlsafe(32)` (256-bit) instead of
 `secrets.token_hex(4)` (32-bit).
 
-**Secret hygiene (Codex p2_2 #5/8, p9 #4-5):** rotated active webhook
+**Secret hygiene (audit p2_2 #5/8, p9 #4-5):** rotated active webhook
 signing secret in `config/webhooks.yaml`, replaced tracked plaintext
 API keys in `k8s/staging/values-staging.yaml` with placeholders +
 `.yaml.example` schema reference, env-driven
@@ -1013,7 +1232,7 @@ capabilities, and applies `RuntimeDefault` seccomp; a memory `emptyDir`
 mounts at `/tmp` for Python tempfile / httpx caches. NetworkPolicy is
 off by default (enable per cluster).
 
-**Supply chain (Codex p9):** committed `sdk-ts/package-lock.json`
+**Supply chain (audit p9):** committed `sdk-ts/package-lock.json`
 (closes ENOLOCK on `npm audit`); `publish-npm.yml` switched to
 `npm ci` + `npm test` + `npm audit` before publish. New `npm-audit` job
 added to `security.yml`. `aquasecurity/trivy-action` pinned from
@@ -1030,7 +1249,7 @@ SQL injection via dynamic partition keys), `langchain-core>=1.2.22`
 bypass), `langsmith>=0.7.31`. Both `pyproject.toml` and
 `integrations/pyproject.toml`.
 
-**OpenAPI drift gate (Codex p4 #5):** `scripts/export_openapi.py`
+**OpenAPI drift gate (audit p4 #5):** `scripts/export_openapi.py`
 gained a `--check` mode that diffs the regenerated `docs/openapi.json`
 and `docs/agent-tools/*.json` against committed copies. Wired into
 `contract.yml`; `docs/agent-tools/**` and `scripts/export_openapi.py`
@@ -1047,7 +1266,7 @@ branch gate; the job was removed
 and DORA metrics fall back to the GitHub Actions API source
 already wired into `scripts/dora_metrics.py`.
 
-**Python SDK alignment with server v1 contract (Codex p8 F1–F10):**
+**Python SDK alignment with server v1 contract (audit p8 F1–F10):**
 `api_version=` parameter and `X-AgentFlow-Version` header on sync and
 async clients; capture of server version + deprecation headers into
 `client.last_server_version` / `last_deprecation_warning`. Async
@@ -1069,7 +1288,7 @@ re-exported from `agentflow.__init__.__all__`. New
 `sdk/agentflow/py.typed` marker; Hatch include rule keeps it in the
 wheel/sdist.
 
-**Test coverage gaps (Codex p5):** new unit suites covering
+**Test coverage gaps (audit p5):** new unit suites covering
 previously zero-coverage modules — `tests/unit/test_clickhouse_backend.py`
 (14 tests: SQL translation, basic-auth POST, UNKNOWN_TABLE mapping,
 URLError mapping, table_columns fallbacks, EXPLAIN, scalar, https
@@ -1087,9 +1306,9 @@ not exercise auth (sets `AGENTFLOW_AUTH_DISABLED=true`); opt out with
 the new `requires_auth_enforcement` marker.
 `app.state.auth_disabled = False` is reset on every lifespan startup
 so the test bypass flag does not leak across `TestClient` instances
-(closes Codex review P2 on auth/middleware persistence).
+(closes review P2 on auth/middleware persistence).
 
-**Documentation hygiene (Codex p6):** TypeScript SDK examples now
+**Documentation hygiene (audit p6):** TypeScript SDK examples now
 import from `"@yuliaedomskikh/agentflow-client"` (was `"agentflow"`); placeholder
 `https://api.agentflow.dev` examples replaced with
 `http://localhost:8000`; clone URL points at
@@ -1109,9 +1328,8 @@ reset on lifespan startup so the test bypass flag does not leak across
 `670 passed, 4 skipped` on
 `pytest tests/unit tests/integration tests/sdk tests/contract`.
 
-**Audits archived:** the two source audits and the two CX task specs
-that drove the impl are kept under `docs/audits/2026-04-27/` with a
-README that maps findings to the six closing commits.
+**Audit closure:** two internal security audits drove the work; their
+findings map to the six closing commits.
 
 ### Added
 
@@ -1248,8 +1466,6 @@ See [docs/migration/v1.1.md](docs/migration/v1.1.md) for upgrade instructions fr
 
 ### Documentation
 
-- v1.1 sprint task briefs under `docs/codex-tasks/2026-04-22/`
-  (T01-T10, self-contained one-PR ТЗ). (f448626)
 - `docs/operations/aws-oidc-setup.md`, `docs/operations/chaos-runbook.md`,
   `docs/operations/codecov-setup.md`.
 - `docs/contracts/how-to-add-entity.md`.