@event4u/agent-config 9.8.0 → 9.9.0

package/docs/contracts/ai-team-config.md

@@ -1,224 +0,0 @@
----
-stability: beta
-keep-beta-until: 2026-10-10
----
-
-# AI-Team Config (`ai_team` block)
-
-**Purpose.** Lock the schema, validation, and quota rules for the `/team`
-cross-model review family — one strong external model (via the codex CLI,
-subscription-authed) reviewing inside the repo. Team mode is the **depth**
-complement to the council's **breadth**; this contract is the boundary that
-prevents drift across the settings template, the loader, the `/team`
-wrappers, and the quota counter.
-
-**Audience.** Authors of `src/scripts/ai_team/config.ts`, the `/team`
-command family, the doctor `team` section, and the setup wizard. Also
-reviewers checking that new team features keep the schema intact.
-
-**Status.** Internal-locked. Changes require a contract version bump and a
-revision entry in the consuming roadmap.
-
-## File location
-
-Unlike the council (ALWAYS user-global `.ai-council.yml` — see
-[ai-council-config.md](ai-council-config.md)), the `ai_team` block lives in
-the **project settings cascade**:
-
-```
-<project>/.agent-settings.yml   →   ai_team: { … }
-```
-
-read via `load_agent_settings` (`src/scripts/_lib/agent_settings.ts`) and
-validated by `src/scripts/ai_team/config.ts:load_ai_team_config`. Team mode
-is a per-project posture (default-off), not a per-developer credential
-store — the codex CLI carries the subscription auth itself, so there is
-nothing secret to centralize. The shipped defaults live in
-`src/config/agent-settings.template.yml` and are mirrored by the wizard
-schema (`src/server/schemas/settings.ts`, enforced by the schema↔template
-parity test).
-
-## Schema
-
-```yaml
-ai_team:
-  enabled: <bool>                 # master switch, default false
-  model: <string>                 # default 'auto'
-  allow_delegate: <bool>          # second opt-in for the write path, default false
-  max_calls_per_day: <int >= 0>   # default 50; counts into the shared openai bucket
-  suppress_setup_hint: <bool>     # default false; cosmetic wizard-hint suppression
-  review_gate:                    # managed governance of the plugin's Stop-hook Review Gate
-    managed: <bool>               # default false = byte-identical pre-Phase-4 behavior
-    max_consecutive_blocks: <int >= 1>  # default 3; circuit-breaker loop bound
-```
-
-| Key | Type | Default | Semantics |
-|---|---|---|---|
-| `enabled` | bool | `false` | Master switch. `false` = `/team` commands are never suggested and every invocation refuses with an enable pointer — byte-identical to pre-feature behavior. `true` = the family is live; per-command gates below still apply. |
-| `model` | string | `'auto'` | Model handed to the codex CLI. `'auto'` = pass **no** `--model` flag; the codex CLI's own default applies. Any other value passes through **verbatim** as `--model <value>`. |
-| `allow_delegate` | bool | `false` | Second opt-in for the **only** wrapper that delegates write access (`/team:delegate`). Refuses with an enable pointer until BOTH `enabled` and `allow_delegate` are `true`. |
-| `max_calls_per_day` | int ≥ 0 | `50` | Per-day ceiling on team calls, read against the **shared** `cli_call_budget` openai bucket (see § Quota). `0` blocks all team calls. |
-| `suppress_setup_hint` | bool | `false` | Suppress the one-line wizard/init recommendation to install the codex plugin on Claude-Code hosts. Cosmetic only. |
-| `review_gate.managed` | bool | `false` | Managed governance of the codex plugin's Stop-hook Review Gate (Phase 4). `false` = no counting, no circuit breaker — the Stop path is byte-identical to pre-Phase-4 dispatch. `true` = consecutive BLOCK verdicts are counted per session (first-line `ALLOW:`/`BLOCK:` contract of the gate transcript; anything else is honestly `UNKNOWN` and never counted) and the circuit breaker trips at the bound. |
-| `review_gate.max_consecutive_blocks` | int ≥ 1 | `3` | Circuit-breaker bound. At this many CONSECUTIVE BLOCKs in one session a visible notice is injected **exactly once** and the managed layer stops re-blocking — the user decides, never an infinite Claude↔Codex loop. An ALLOW verdict resets the counter. Unknown keys inside `review_gate` are rejected fail-closed, same as the parent block. |
-
-### Why `model: 'auto'` instead of a pinned ID
-
-A hardcoded model ID rots silently (the council's own CLI default is a
-deliberate, documented *pin* — `DEFAULT_OPENAI_CLI_MODEL` in
-`src/scripts/ai_council/clients.ts`, see
-[ai-council-config.md](ai-council-config.md)). Team mode inverts that:
-under a subscription the *strongest* available model is the rational
-default, and only the codex CLI knows what that currently is. `'auto'`
-therefore delegates the choice to the CLI; a set value is a user pin and
-passes through verbatim — the loader never rewrites or "corrects" it.
-
-**`review_gate` (Phase 4, shipped):** the loop-bound governance block is
-live — module `src/scripts/ai_team/review_gate.ts` (counter state under
-`agents/runtime/state/team-review-gate.json`, ledger under
-`agents/runtime/team/events.log`, one `team.gate: BLOCK 2/3` /
-`ALLOW reset` line per gate verdict). The gate itself stays upstream's;
-upstream's own warning applies while it is enabled unmanaged: "The
-review gate can create a long-running Claude/Codex loop and may drain
-usage limits quickly." Any other key stays rejected fail-closed.
-
-## Role semantics — the council-verdict design constraint
-
-Verbatim from the consuming roadmap's council verdict, binding on every
-team-mode phase:
-
-> **Council verdict on team-mode frontmatter (claude-sonnet-4-5 + gpt-4o,
-> 2026-07-12, unanimous REJECT):** skills/commands get NO `team_mode` /
-> role frontmatter. Role semantics belong in the `ai_team` config block +
-> prompt library (reusing subagent-orchestration's implementer/judge frame
-> and status envelope), not smeared across 271 skill files while the
-> feature's role model does not operationally exist. Revisit-if: Phase 2
-> execution turns out to be blocked SPECIFICALLY on artefact-level role
-> metadata — then re-open via decision-revisit-gate, not by silently
-> adding the key.
-
-Operationally: ALL role semantics (builder/reviewer/verifier selection,
-eligibility) live HERE — in this `ai_team` block — plus the prompt
-library, reusing `subagent-orchestration`'s implementer/judge frame and
-its `subagent-status.json` envelope. **No `team_mode`/role frontmatter key
-is added to skill/command/rule schemas.**
-
-## Quota — one subscription, one counter
-
-```
-TEAM CALLS COUNT INTO THE EXISTING cli_call_budget OPENAI BUCKET.
-ONE SUBSCRIPTION, ONE COUNTER. NEVER A PARALLEL COUNTER.
-```
-
-The daily CLI-call counter is already **generic per-provider** — no
-team-specific counting system exists or may be built:
-
-- **State file:** `~/.event4u/agent-config/cli-calls.json`
-  (`CLI_CALLS_FILENAME`, `src/scripts/ai_council/clients.ts:716`), shape
-  `{ date: "YYYY-MM-DD", counts: { <provider>: <int> } }`, resets on UTC
-  date rollover.
-- **Read:** `load_cli_call_counts(path?)` —
-  `src/scripts/ai_council/clients.ts:738`. Returns today's per-provider
-  counts; empty on rollover.
-- **Increment:** `record_cli_call(provider, path?)` —
-  `src/scripts/ai_council/clients.ts:774`. Returns the new total.
-- **Gate + increment on the transport itself:** `CliClient.ask()` checks
-  the counter *before* spawning (`clients.ts` § quota gate, returns
-  `error: 'cli_quota_exhausted'` + a `block_quota` events-log line when
-  exhausted) and records the call *after* — even failed calls count, so a
-  broken CLI cannot burn the budget in a tight loop.
-- **The openai bucket:** `OpenAICliClient` (`clients.ts:1275`) has
-  `name = 'openai'`; council CLI calls and team calls land on the **same**
-  `counts.openai` entry.
-
-A `/team` invocation therefore reuses the existing seams, in preference
-order:
-
-1. **Through the transport** — construct `OpenAICliClient` with
-   `max_calls_per_day: <ai_team.max_calls_per_day>`; the gate, the
-   exhausted-error, the events-log line, and the increment all come for
-   free.
-2. **Direct** (for `/team:status` rendering or a pre-flight check) —
-   `load_cli_call_counts()['openai'] ?? 0` to read,
-   `record_cli_call('openai')` to count. No new helper exists because
-   none is needed; adding a team-side duplicate of this counter is a
-   contract violation.
-
-`ai_team.max_calls_per_day` and the council's
-`cli_call_budget.max_calls_per_day.openai` are two *ceilings* over the
-same *counter*: whichever path a call takes, it increments the one shared
-bucket, and each surface enforces its own configured cap against that
-shared count.
-
-**Worked example — two ceilings, one counter.** Council ceiling
-`cli_call_budget.max_calls_per_day.openai: 100`, team ceiling
-`ai_team.max_calls_per_day: 50`, shared counter at 45 openai calls today:
-both paths are open. Five team calls later the counter reads 50 — team
-calls are now blocked (50 >= 50) while council CLI calls continue until
-the counter reaches 100. Whichever path fires a call, the same counter
-moves; each surface only decides where *its* ceiling sits on that shared
-count. `/team status` renders exactly this state: the live counter, both
-ceilings, and which path (if any) is currently blocked.
-
-### Team-review envelope
-
-Every `/team:review` return — plugin path and multi-host fallback alike — is emitted in the
-team-review status envelope (`src/skills/subagent-orchestration/schemas/team-review-status.json`),
-which extends the `subagent-status.json` frame: `status` (`DONE | DONE_WITH_CONCERNS |
-NEEDS_CONTEXT | BLOCKED`), `findings[]` (`severity`/`evidence`/`suggested_fix`/`location?`),
-`reviewed_ref` (HEAD sha of the bundle), `model` (`'auto'` = codex CLI default), and
-`quota` (`{used, ceiling}` on the shared `cli_call_budget` openai bucket); unparseable model
-output is preserved verbatim in `raw` with status `DONE_WITH_CONCERNS` — never silently dropped.
-Plugin text is summarized INTO the envelope and preserved verbatim beneath — never rewritten.
-<!-- PLACEHOLDER: the team-review-envelope subsection (review-gate ledger
-     line format `team.gate: BLOCK n/N` read by /team status) is inserted
-     here by the orchestrator in a later step. Do not remove this marker. -->
-
-## Validation rules (fail-closed)
-
-`load_ai_team_config` / `build_ai_team_config`
-(`src/scripts/ai_team/config.ts`) raise `TeamConfigError` when:
-
-1. `ai_team` is present but not a mapping,
-2. any **unknown key** appears under `ai_team` (a typo must never
-   silently disable a gate),
-3. `enabled` / `allow_delegate` / `suppress_setup_hint` is not a boolean,
-4. `model` is not a non-empty string,
-5. `max_calls_per_day` is not a non-negative integer (booleans rejected).
-
-An **absent** `ai_team` block is not an error — it yields the defaults
-(`AI_TEAM_DEFAULTS`) and the feature stays off.
-
-## Default-off posture
-
-Every team-mode capability is default-off. With the block absent or
-`enabled: false`, all paths are byte-identical to pre-feature behavior:
-no command suggestions, no wrapper execution, no quota consumption, no
-wizard nagging beyond the single suppressible setup hint.
-`/team:delegate` is doubly gated (`enabled` AND `allow_delegate`).
-
-## No-claims constraint
-
-No public claim about cross-model review quality ("a second model finds
-errors the first never sees", "two strongest models catch each other's
-errors", or any review-lift assertion) may exist anywhere in the tree
-until the pre-registered three-arm defect-finding benchmark has produced
-a verdict bound in CLAIMS.md. Workflow-value prose is allowed; lift
-claims are not. An honest null keeps the feature documented as workflow
-value only.
-
-## Boundary vs. the council
-
-Team mode and the council are complements, not variants — the council's
-neutrality contract is untouched by team mode:
-
-| Axis | Council ([ai-council-config.md](ai-council-config.md)) | Team (`ai_team`) |
-|---|---|---|
-| Shape | N members, breadth | One strong reviewer, depth |
-| Repo access | NEVER (artefact text + neutral preamble only) | Full (reviewer runs inside the working tree) |
-| Config location | User-global `.ai-council.yml` (ADR-104) | Project `.agent-settings.yml` cascade |
-| Default models | Mid-tier, cost-conscious | Subscription's strongest (`model: 'auto'`) |
-| Quota | `cli_call_budget` per provider | Same counter — shared openai bucket |
-
-This link is deliberately one-directional (team → council); the council
-contract does not reference team mode.

package/docs/contracts/analysis-memory-loop.md

@@ -1,149 +0,0 @@
----
-stability: draft
-keep-draft-until: first-skill-ships
-owner: road-to-analysis-workbench
----
-
-# Analysis Memory Loop — produce → propose → promote → retrieve
-
-> **Status:** draft · **Owner:** road-to-analysis-workbench
-> · **Governed by:** `src/rules/non-destructive-by-default.md`,
-> `src/rules/domain-safety-disclaimer.md`
-
-Contract for the closed learning loop in the `analysis-workbench` pack.
-Binds all analysis skills: `blameless-post-mortem`, `root-cause-frameworks`,
-`premortem`, `decision-review`.
-
----
-
-## § 1 — Produce: what analysis flows draft
-
-Post-mortem, RCA, decision-review, and near-miss flows MUST draft
-`incident-learnings` and `historical-patterns` **candidates** into the
-`/memory propose` provisional JSONL intake stream.
-
-Candidates are produced; they are **never auto-promoted** to curated memory.
-The human drives promotion. An analysis skill that skips the draft step or
-claims self-promotion violates this contract.
-
-### Candidate schema (minimum)
-
-```jsonc
-{
-  "type":               "incident-learnings" | "historical-patterns",
-  "summary":            "one-line human-readable pattern",
-  "evidence_paths":     ["path/to/file", "path/to/other"],
-  "decision_surface":   ["area1", "area2"],
-  "last_validated":     "YYYY-MM-DD",
-  "review_after_days":  90,
-  "applicable_scope":   "project" | "domain" | "global"
-}
-```
-
-`last_validated` defaults to today. `review_after_days` defaults to 90.
-`applicable_scope` defaults to `"project"`.
-
----
-
-## § 2 — Propose: intake and dedup pre-check
-
-Before drafting a **new** candidate, each skill calls `retrieve()` over the
-same key-space (incident type, affected paths, decision area).
-
-- **Match found** — propose a `frequency`/`supersedes` **update** to the
-  existing entry, not a new entry. The proposal notes which existing entry is
-  being reinforced or superseded.
-- **No match** — draft a new candidate as described in § 1.
-
-This dedup check is not optional. A skill that skips it and produces a
-duplicate candidate fails the loop contract.
-
----
-
-## § 3 — Promote: the admission gate
-
-`/memory promote` runs `scripts/check_memory_proposal.py`.
-
-**Admission criteria** (unchanged from the existing gate):
-
-- `≥ 2 distinct file paths` referenced in `evidence_paths`, OR
-- `≥ 3 future decisions` the pattern would change (listed in
-  `decision_surface`).
-
-Failing either criterion → proposal stays provisional; skill surfaces the
-gap to the user and suggests either deferring or strengthening evidence.
-
-The agent NEVER overrides or bypasses this gate. Redaction is enforced by
-`check_memory.py` (no customer names, secrets, internal IPs, project-rooted
-paths) before any entry is promoted.
-
----
-
-## § 4 — Retrieve: staleness is explicit
-
-`retrieve()` returns:
-
-```jsonc
-{
-  "results": [...],
-  "skipped": [
-    {
-      "id":      "...",
-      "reason":  "stale",
-      "details": "last_validated=YYYY-MM-DD, review_after_days=90"
-    }
-  ]
-}
-```
-
-Stale entries (age > `review_after_days`) appear in `skipped`, NOT in
-`results`. A skill that silently uses stale entries (ignores `skipped`)
-violates this contract. Stale matches MUST be surfaced to the user.
-
----
-
-## § 5 — Handoff: incident-commander → blameless-post-mortem
-
-`incident-commander` produces a handoff skeleton. That skeleton **may carry
-an empty or TBD root cause** — incomplete evidence at incident close is
-normal.
-
-`blameless-post-mortem`:
-
-1. **Accepts** any incoming skeleton, complete or not.
-2. Invokes `root-cause-frameworks` to fill gaps; `root-cause-frameworks`
-   returns ranked candidates with confidence levels, not a forced verdict.
-3. Marks the post-mortem `status: draft` if root cause remains unresolved
-   after the analysis pass.
-4. NEVER rejects or stalls on an incomplete skeleton.
-
-A post-mortem marked `draft` can still produce `incident-learnings`
-candidates (`summary` must note the open question).
-
----
-
-## § 6 — Framework-neutrality scope
-
-The `framework-neutrality-in-generic-skills` rule governs **tech-stack names**
-(Laravel, React, Django). It does **not** govern analysis method names.
-
-5-whys, fishbone, fault-tree, STAMP/STPA, and similar are method names used
-generically across analysis skills. Using them in a skill named
-`root-cause-frameworks` is not a framework-neutrality violation.
-
----
-
-## § 7 — What this contract does NOT cover
-
-- The schema of curated memory entries (governed by `low-impact-corpus-format.md`).
-- The internal mechanics of `check_memory_proposal.py` (lives in `src/scripts/`).
-- AI-specific RCA (deferred; gated on `road-to-security-hardening`).
-
----
-
-## See also
-
-- [`low-impact-corpus-format.md`](low-impact-corpus-format.md) — curated memory schema.
-- [`ADR-096`](../decisions/ADR-096-analysis-workbench.md) — council decisions behind this contract.
-- `src/skills/blameless-post-mortem/SKILL.md` — primary consumer (Phase 2).
-- `src/skills/root-cause-frameworks/SKILL.md` — RCA engine (Phase 2).

package/docs/contracts/at-rest-encryption.md

@@ -1,191 +0,0 @@
----
-stability: experimental
----
-
-# At-Rest Encryption Contract
-
-> **Status** · v0 / design · 2026-05-24. Phase 8 of the
-> employee-product workstream.
-> Single-user, single-machine encryption for the three workspace
-> stores added in Phases 4 / 5 / 7. Does **not** touch the existing
-> `agents/memory/` store — that gets a separate decision.
->
-> **Architecture locked 2026-06-08 → [`ADR-062`](../decisions/ADR-062-encrypt-at-rest-store-architecture.md).**
-> Two decisions the store-wiring PR implements: (A) the shipped
-> `workspace_crypto.py` currently uses **Fernet**, not the AES-256-GCM
-> `AC1\0` envelope this contract specifies — the code is re-ciphered to
-> match the contract (safe: flag default-OFF, no field data to migrate);
-> (B) store access is **Python-authoritative end-to-end** — the Node GUI
-> server stops touching the encrypted files directly and routes through
-> the Python CLI (no `keytar`, no dual-runtime crypto). The wiring is a
-> deliberate dedicated PR with a must-have checklist (CI-exercised
-> cipher, concurrency-safe migration, key rotation, kill-switch, envelope
-> versioning, cross-runtime test) — see ADR-062.
-
-## Threat model
-
-The stores written under `~/.event4u/agent-config/workspace/` will
-hold actual customer data once recruit-session participants adopt
-the workspace: offer drafts naming customer X, mail drafts with
-contact email + phone, memos referencing internal pricing. Three
-threats this contract addresses:
-
-| Threat | Surface | Defence |
-|---|---|---|
-| **Lost / stolen laptop** | FDE may not be enabled or may be unlocked | Per-user key wrapped by OS keyring; cipher blob useless without the keyring entry. |
-| **Shared workstation** | Another OS user reads `~/.event4u/...` | POSIX 0600 + keyring entry scoped to the user account. |
-| **Accidental `git add ~/.event4u/...`** | User commits the store from a misconfigured shell | Encrypted blob is opaque; secrets do not leak as plaintext into the diff. Pre-commit hook detects the path; encryption is defence-in-depth. |
-
-Explicit non-goals:
-
-- **Not** protection against a compromised OS user account.
-- **Not** protection against a malicious admin / root.
-- **Not** protection against memory dumps while the workspace is
-  running.
-- **Not** a substitute for full-disk encryption — the contract
-  explicitly recommends FDE in `docs/guides/at-rest-encryption.md`.
-
-## Cipher choice
-
-**AES-256-GCM** for the data blob. Single per-user master key,
-32 random bytes, generated on first workspace launch.
-
-The master key is stored in the OS keyring:
-
-| OS | Library | Backend |
-|---|---|---|
-| macOS | `keyring` (Python) / `keytar` (Node) | Keychain |
-| Linux | `keyring` / `keytar` | Secret Service / libsecret (gnome-keyring, KWallet) |
-| Windows | `keyring` / `keytar` | Credential Manager |
-
-Service name: `event4u-agent-config-workspace`. Account name:
-`<os-user>`. The keyring entry is the **only** persistent copy of
-the master key on the machine — never written to disk in plaintext,
-never logged.
-
-## Scope
-
-**Shipped — encrypted at rest:**
-
-| Path | Form | ADR | Sensitivity |
-|---|---|---|---|
-| `workspace/documents/**/*.md` | whole-file `.md.enc`, Python-authoritative read | 062 | offer / mail / memo / brief bodies |
-| `workspace/documents/**/*.history.jsonl` | per-record (one base64 `AC1\0` line per revision) | 064 | edit metadata + SHAs |
-| `workspace/analytics/events.jsonl` | per-record (one base64 `AC1\0` line per event) | 064 | event counters; lower sensitivity |
-| `workspace/sessions/**/*.jsonl` | per-record (Python-authoritative; Node routes all 5 session endpoints through the CLI) | 064 | host replies may contain customer data |
-
-**Intentionally plaintext (encryption declined — [`ADR-065`](../decisions/ADR-065-tier3-inbox-handoff-v0.md)):**
-
-| Path | Form | Why not encrypted |
-|---|---|---|
-| `workspace/inbox/**/*.md` | plaintext, ephemeral (24h prune), Python-authoritative, ships dark behind `AGENT_CONFIG_TIER3_INBOX` | the Tier-3 hand-off holds a rendered prompt the user **reads to copy-paste**; that same content already lives in the **encrypted sessions store**, so encrypting it defends against no incremental threat (security theater). **Trigger to revisit:** if the inbox ever carries content NOT mirrored in sessions, encrypt it via the documents whole-file `.md.enc` pattern. |
-
-Does **not** encrypt (v0):
-
-- `agents/memory/` — under the maintainer's repo, separate decision.
-- `.agent-settings.yml` — config, no customer data.
-- `package.json` / lockfiles / source — public surface.
-
-## Storage layout (encrypted)
-
-Each plaintext file is replaced by a sibling cipher file:
-
-```
-workspace/documents/offer/kundeX-angebot-2026-05-24.md
-  → workspace/documents/offer/kundeX-angebot-2026-05-24.md.enc
-```
-
-`.enc` envelope:
-
-```
-| 4 bytes  | magic: "AC1\0"
-| 1 byte   | version: 0x01
-| 12 bytes | GCM nonce
-| 16 bytes | GCM auth tag
-| N bytes  | ciphertext
-```
-
-Filename itself is **not** encrypted in v0 (filename leakage is an
-accepted trade-off — slugs are kebab-case derived from titles and
-may contain customer names; mitigation: title slug allowlist
-documented in `workspace-documents.md`).
-
-## Part B operations (documents) — shipped
-
-`workspace_documents.py` owns document encryption (Python-authoritative,
-ADR-062 Option 4):
-
-- **Write** (`create` / `save`): when the flag is on, the `.md` body is
-  written as `<slug>.md.enc` via atomic temp+fsync+rename; the opposite form
-  is removed so a slug never has both.
-- **Read** (`read` / `list` / `export`): auto-detects `.md` vs `.md.enc` on
-  disk and decrypts the `.enc` — **independent of the flag** (decryption needs
-  only the key), so a read is correct after the flag flips either way.
-- **Node read path**: the GUI server's recent-documents rail calls
-  `workspace_documents.py list --json --root <writeRoot>/workspace/documents`
-  rather than reading files directly — so it never has to decrypt `.enc` in
-  Node. The script is resolved from the server source tree.
-- **`migrate`**: non-destructive plaintext → `.enc` (encrypt, verify-decrypt,
-  then delete plaintext; idempotent; rolls back a file on verify failure).
-- **`decrypt-all`**: kill-switch — every `.md.enc` back to plaintext `.md`
-  (works after the flag is off; `AGENT_CONFIG_NO_ENCRYPTION` also forces
-  plaintext writes).
-- **`rekey`**: rotate the master key and re-encrypt every document under the
-  new key (coherent only when the key lives in keyring/keyfile, not pinned via
-  `AGENT_CONFIG_WORKSPACE_KEY`).
-
-## Feature flag + migration
-
-Single setting in `.agent-settings.yml`:
-
-```yaml
-workspace:
-  encrypt_at_rest: true   # default from v1.0
-```
-
-Migration on first launch after upgrade:
-
-1. Detect any plaintext files under the encrypted scope.
-2. Show one-time modal: "Encrypt your local workspace store?"
-   with options [Encrypt now] / [Keep plaintext (not recommended)].
-3. On "Encrypt now": iterate, encrypt-in-place atomically (write
-   `.enc.tmp`, fsync, rename, delete plaintext). Roll back on any
-   error.
-4. On "Keep plaintext": flip `encrypt_at_rest: false`. Next
-   workspace launch re-asks unless the user sets
-   `workspace.encrypt_at_rest_dismissed: true`.
-
-## Recovery path
-
-The master key lives in the OS keyring. Recovery scenarios:
-
-- **Re-install OS / move to a new machine**: workspace prompts on
-  first launch to either restore an exported key file (`.event4u-recovery.key`)
-  or treat the encrypted store as inaccessible.
-- **Lost master key, no export**: workspace surfaces a destructive
-  banner: "encrypted store is unrecoverable; delete and start
-  fresh?" — explicit user click required.
-- **Key export**: `npx @event4u/agent-config workspace:export-key`
-  prompts the user to pick a target file. The export is the raw
-  32-byte key in a labelled wrapper; the user is responsible for
-  storing it safely (password manager, hardware token, paper
-  backup).
-
-## Coverage (Phase 8 Step 4)
-
-- Round-trip: encrypt → decrypt produces identical bytes for ≥ 5
-  fixture documents.
-- Wrong key → GCM auth failure → renderer surfaces a clear "wrong
-  key" error, not a generic crash.
-- Keyring-missing-entry path (mocked) → migration modal appears.
-- Concurrent writers → second writer waits on the file lock, no
-  truncation.
-- Threat-model checklist verified against `threat-modeling` skill.
-
-## Cross-references
-
-- Phase 4 stores: [`daily-workspace`](daily-workspace.md).
-- Phase 5 stores: [`workspace-documents`](workspace-documents.md).
-- Phase 7 store: [`local-analytics`](local-analytics.md).
-- Guide (deferred to Phase 8 Step 5): `docs/guides/at-rest-encryption.md`.
-- Memory-store decision (deferred): out of scope for v0.