@event4u/agent-config 5.10.1 → 6.1.0

package/docs/decisions/ADR-061-corpus-grounding-layer.md

@@ -0,0 +1,170 @@
+---
+adr: 061
+status: accepted
+date: 2026-06-07
+decision: corpus-grounding-layer
+supersedes: —
+superseded_by: —
+phase: frontend design intelligence (road-to-frontend-design-intelligence, Phase 0)
+type: structural
+---
+
+# ADR-061 — Reusable corpus-grounding layer; frontend is its first instance
+
+## Status
+
+**Accepted** · 2026-06-07. Records the AI-council convergence
+(anthropic/claude-sonnet-4-5 + anthropic/claude-opus-4-5 + openai/gpt-4o,
+deep 3-round debate, 2026-06-03 — no split, no tie-break) plus the four
+implementation forks resolved 2026-06-07 (anthropic/claude-sonnet-4-5 +
+openai/gpt-4o, converged).
+
+## Context
+
+The package's UI directive set (`audit → design → apply → review → polish`)
+produces design briefs from agent judgment plus the `fe-design` heuristics —
+there is no queryable design-knowledge corpus. The MIT-licensed
+`nextlevelbuilder/ui-ux-pro-max-skill` repository ships exactly that: ~15
+tabular CSVs (161-row `ui-reasoning` with JSON decision rules, WCAG-adjusted
+color token sets, typography pairings, chart-selection knowledge, 16
+per-framework best-practice files) plus a dependency-free pure-stdlib BM25
+engine. The owner's escalated goal — *"real knowledge + real orchestration in
+every domain, as flexible and good as possible"* — reshaped the adoption from
+"copy a frontend corpus" into "build a reusable grounding layer; frontend is
+its first instance."
+
+## Decision
+
+### 1. Four-operation routing — never one corpus for everything
+
+Each domain's knowledge is split across four mechanisms; conflating them is a
+named failure mode ("grounding theater"):
+
+| Operation | When | Mechanism |
+|---|---|---|
+| **Grounding** | *before* action — constrains the option space | curated corpus + decision rules |
+| **Reference** | *during* action — factual lookup | on-demand `references/` / RAG, not the corpus |
+| **Validation** | *after* action — constraint check | rules / linters |
+| **Method** | the procedure itself | framework skill |
+
+A corpus **grounds** (pre-action). Mid-action lookup is reference; post-action
+checking is a rule; the procedure stays a skill.
+
+### 2. One shared engine, invoked not inherited
+
+A generic engine lives at `src/skills/_lib/corpus-grounding/`
+(`bm25_search.py`, `decision_engine.py`, `schema_validator.py`) with a
+**versioned interface-stability contract** documented in its README before any
+domain adopts it. Domains plug in via a manifest; the engine is grep-able,
+never a hidden god-dependency. Retrieval: BM25 default with a structured
+`filters` pre-filter from day one; retriever selected by name
+(`bm25`/`structured`/`hybrid`); embeddings only on measured recall failure,
+never network-by-default.
+
+### 3. Schema-agnostic plug-in contract — explicitly NOT uniform
+
+Each domain declares its own axes via a manifest (corpus files, search
+columns, output columns, reasoning-map location) and an output tier:
+**lookup-only → conditional-grounding (decision rules) → constraint-emission**.
+Forcing the frontend schema onto other domains is a named failure mode. Every
+corpus output carries a **confidence score + an evidence-gap line** by
+contract (prevents false precision / authority inflation).
+
+### 4. Grounding default = lightweight consultation
+
+Default integration: a skill consults the corpus → proposes grounded options
+with confidence + evidence-gap → human confirms. Directive-engine integration
+is reserved for mature, naturally-sequential domains (frontend keeps its
+directive engine — Tier 2); "directive engines everywhere" is rejected as
+orchestration envy. `directives/ui/design.py` never imports the engine — the
+corpus call lives in the skill layer (`ui-design-brief` /
+`design-intelligence`), keeping the engine an optional dependency.
+
+### 5. Qualification by decision-rule utility, NOT row count
+
+A domain qualifies when (i) its selection/constraint decision is
+externalizable as auditable rules that beat the agent's priors, and (ii)
+grounding happens before action. Verdicts:
+
+- **Strong**: security/threat-modeling (MITRE-derived), accessibility
+  (WCAG/ARIA patterns), API design, DB-query tuning.
+- **Conditional (evidence-gated)**: finance *method selection*,
+  architecture-pattern selection — thin pre-action selection corpora only;
+  land only if a corpus measurably beats the existing framework skill over
+  ≥10 real sessions (the council's change-my-mind anchor).
+- **Reject as corpus**: anything that is really reference (→ RAG), really
+  validation (→ rule), volatile/culturally-specific (people/org fads), or a
+  thin corpus that doesn't beat priors. Test: *if it fits in 5 lines of an
+  always-on rule, it's a rule, not a corpus.*
+
+### 6. Provenance / freshness — the upstream-source line is part of DoD
+
+Every adopted asset carries an inline upstream-source line: upstream repo +
+commit SHA + last-checked date. Per-corpus header additionally names a
+maintainer + refresh cadence + last-validated date (domain-adoption Gate 2).
+CI link-checks; volatile content is tiered by rot velocity or marked
+reference-only. **Definition of done for every adoption phase includes this
+line** (refresh stays mechanical, not archaeological).
+
+### 7. Licensing
+
+Root corpus + scripts: MIT (Next Level Builder, 2024) → retain notice.
+`ui-styling`-derived material: **Apache-2.0** (vendored "claudekit"; the
+dedicated `LICENSE.txt` wins over the MIT frontmatter claim) → retain notice,
+mark modified files (§4b), ship the license copy alongside derived assets.
+Recorded in `src/skills/design-intelligence/ATTRIBUTION.md`.
+
+### 8. Implementation forks (council-resolved 2026-06-07)
+
+| Fork | Resolution |
+|---|---|
+| Pack placement | **New `frontend-design` pack** (ADR-013 amendment, same PR). `requires: [engineering-base]`, `suggests: [react, nextjs]` — corpus is stack-agnostic data, React never required. Keeps ~1 MB of design data out of `engineering-base`. |
+| `google-fonts.csv` (745 KB, 1923 rows) | **Skip.** Redundant with the public Google Fonts API; `typography.csv` (73 curated pairings) carries the pairing decision. Document the API fallback for fonts outside the curated set. |
+| Stack-corpus surfacing | **`--stack <name>` search domain** on the one grounding engine — single mechanism, no 16-way prose-staleness vector. |
+| Brand→token pipeline | **Defer** with a watch note pinning the upstream commit SHA; adopt on first consumer demand. |
+
+### 9. Out of scope (explicit)
+
+- The upstream slide/presentation engine (out of frontend scope).
+- The Gemini generative brand-asset suite (logo/CIP/icon/banner/social) —
+  gated by `domain-adoption-policy`; see the domain-watch note. If gates
+  pass later, it adapts into `pack-ai-video` (no second image-gen stack).
+- Business-pack corpora (people/org, GTM, founder-strategy verdicts) —
+  rejected per the qualification rubric; reference belongs to RAG,
+  validation to rules.
+
+## Consequences
+
+- A new domain ships a manifest + data + a named owner — not a forked engine.
+- `engineering-base` stays lean; design intelligence is opt-in via the
+  `frontend-design` pack.
+- The skill-bundled `scripts/` + `data/` delivery path becomes a sanctioned,
+  tested pattern (delivery-mechanism gate, Phase 1) — load-bearing for every
+  later domain corpus.
+- Corpus maintenance is a standing cost: named owner + cadence per corpus, or
+  the corpus is not merged.
+
+## Alternatives considered
+
+- **One corpus for everything (CSV per domain)** — rejected; conflates the
+  four operations, produces grounding theater + maintenance bloat.
+- **Fold the corpus into `fe-design`** — rejected 2-of-3; size discipline.
+  `fe-design` stays heuristics and *invokes* `design-intelligence`.
+- **Directive engines for every domain** — rejected; consultation default.
+- **Keep `.cjs` token generators on Node** — rejected unanimously; ported to
+  Python (no Node runtime dependency for core flows).
+- **Adopt `google-fonts.csv`** — rejected; public-API-redundant bloat.
+
+## References
+
+- `agents/roadmaps/archive/road-to-frontend-design-intelligence.md` —
+  implementing roadmap, archived 2026-06-07 (full source analysis + phase
+  plan + per-step evidence notes).
+- [ADR-013 — Discovery frontmatter contract](ADR-013-discovery-frontmatter-contract.md)
+  — `frontend-design` pack amendment (2026-06-07).
+- `src/skills/design-intelligence/ATTRIBUTION.md` — upstream provenance +
+  license obligations.
+- `agents/settings/contexts/domain-watch/generative-brand-assets.md` — gated
+  Gemini-suite watch note.
+- Upstream: `nextlevelbuilder/ui-ux-pro-max-skill` @
+  `b7e3af80f6e331f6fb456667b82b12cade7c9d35` (last checked 2026-06-07).

package/docs/decisions/ADR-062-encrypt-at-rest-store-architecture.md

@@ -0,0 +1,121 @@
+---
+adr: 062
+status: accepted
+date: 2026-06-08
+decision: encrypt-at-rest-store-architecture
+supersedes: —
+superseded_by: —
+phase: employee-product Phase 8 (road-to-employee-product-and-external-proof, Step 3)
+type: structural
+---
+
+# ADR-062 — Encrypt-at-rest store architecture: AES-256-GCM + Python-authoritative store access
+
+## Status
+
+**Accepted** · 2026-06-08. Design converged via two-round AI-council debate
+(anthropic/claude-sonnet-4-5 + openai/gpt-4o, design mode, 2026-06-08). Both
+members independently converged in round 2. This ADR records the architecture;
+the **implementation is a dedicated follow-up PR** (scope + must-haves below) —
+it is deliberately **not** bundled into a reconciliation diff.
+
+## Context
+
+Phase 8 of the employee-product workstream adds at-rest encryption for the
+three workspace stores under `~/.event4u/agent-config/workspace/`
+(sessions `*.jsonl`, documents `*.md` + `*.history.jsonl`, analytics
+`events.jsonl`). The crypto layer `workspace_crypto.py` is shipped behind the
+`workspace.encrypt_at_rest` flag (default **OFF** — no field data is encrypted
+yet). A prior council (2026-06-07) deferred the *store wiring* to its own PR
+because the Node-side crypto/key approach was undecided.
+
+Two problems had to be resolved before any wiring:
+
+1. **Cipher drift.** `docs/contracts/at-rest-encryption.md` specifies
+   **AES-256-GCM** (envelope `AC1\0` + version + 12-byte nonce + 16-byte tag +
+   ciphertext) and lists `keytar` (Node) alongside `keyring` (Python). The
+   shipped `workspace_crypto.py` actually uses **Fernet** (AES-128-CBC +
+   HMAC-SHA256, magic `E4U-WSv1`). Fernet is not natively reproducible in
+   Node's `node:crypto`; AES-256-GCM is.
+2. **The Node GUI server reads/writes the stores directly** (`src/server/routes/workspace.ts`
+   via `fs` — readdir/readFile/writeFile/appendFile, filtering by `.jsonl` /
+   `.md`). If Python writes `.enc`, those direct reads break.
+
+## Decision
+
+### A — Cipher: align the code to the contract's **AES-256-GCM**
+
+The code is wrong, not the contract. Re-cipher `workspace_crypto.py` from
+Fernet to AES-256-GCM with the documented `AC1\0` + version-byte envelope,
+keeping the public API (`encrypt_bytes` / `decrypt_bytes` / `encrypt_file` /
+`decrypt_file`) and the plaintext-pass-through-on-read back-compat. Reject
+unknown envelope versions explicitly. Safe to do because the flag is default-OFF
+and **no Fernet-encrypted field data exists** to migrate. AES-256-GCM is native
+in both `cryptography` (Python `AESGCM`) and `node:crypto`, so the same envelope
+is byte-reproducible across runtimes.
+
+### B — Store access: **Option 4, Python-authoritative end-to-end**
+
+The Node GUI server stops reading/writing the encrypted store files directly.
+All store access routes through the Python CLI modules (the canonical writers),
+which own encryption. Rejected alternatives:
+
+- **keytar in Node** — `keytar` is deprecated (Dec 2022, superseded by
+  Electron `safeStorage`); cross-library keychain interop between Python
+  `keyring` and `keytar` is unproven. Both council members rejected it.
+- **Reimplement Fernet in Node** — moot once A picks AES-256-GCM, and still a
+  new format-fiddly surface.
+- **Dual native crypto** — duplicates the security-critical path in two
+  runtimes; the council called line-count "narrowness" that leaves a dual-write
+  footgun a false economy.
+
+To avoid Python interpreter cold-start cost (the dissent's concern, sharp on
+Windows ~200–500 ms), store reads use **batched** CLI calls (e.g.
+`workspace_sessions.py list --decrypt` returns all decrypted records in one
+subprocess), not one subprocess per file.
+
+## Consequences
+
+- The follow-up PR is a **real refactor of the GUI data path**, not a wiring
+  one-liner. The council was explicit: *"ship the right architecture now, or
+  don't ship encryption at all"* — Option 1 (shell-out as a temporary
+  intermediate) was rejected as process theatre.
+- The flag stays **default OFF** through this work; the `true` flip waits for
+  external (recruit-session) validation per `agents/roles/EVIDENCE_BASIS.md`'s
+  sibling reasoning.
+
+### Must-haves before the implementation PR is greenlit (council checklist)
+
+1. **`cryptography` exercised in CI.** Today the round-trip tests in
+   `tests/test_workspace_crypto.py` **skip** when `cryptography` is absent —
+   and it is absent in CI, so the cipher has never actually round-tripped under
+   test. The implementation PR MUST add `cryptography` to the test job so the
+   AES-256-GCM round-trip genuinely runs (otherwise the cipher ships unverified
+   — a `verify-before-complete` violation on a security primitive).
+2. **Migration with concurrency safety.** Detect plaintext → encrypt-in-place
+   atomically (temp + fsync + rename + delete), roll back on any error; refuse
+   to migrate while the GUI server is running (or make it non-destructive).
+3. **Key rotation path.** Wrong-key today = permanent data loss; ship
+   `workspace_crypto.py rekey` + a documented recovery/export flow.
+4. **Kill-switch / rollback criteria.** `AGENT_CONFIG_NO_ENCRYPTION` already
+   forces-disable reads; add an emergency bulk-decrypt and a documented
+   error-rate auto-disable.
+5. **Envelope version semantics.** Version byte defined; unknown versions
+   rejected with a clear error, not a crash.
+6. **Cross-runtime integration test.** Python encrypts → Node reads back the
+   decrypted record through the Python-authoritative path (Option 4).
+
+## Alternatives
+
+See § Decision B rejected alternatives (keytar / Fernet-in-Node / dual native)
+and the cipher A alternative (keep Fernet + reconcile the contract to document
+it — rejected because it forecloses native Node interop and the contract's
+AES-256-GCM was the deliberate original design).
+
+## References
+
+- Contract: [`docs/contracts/at-rest-encryption.md`](../contracts/at-rest-encryption.md).
+- Crypto layer: `src/cli/python/workspace_crypto.py`.
+- GUI store IO: `src/server/routes/workspace.ts`.
+- Prior deferral: AI-council 2026-06-07 (recorded in the roadmap Phase 8 Step 3 deferral note).
+- Roadmap: `agents/roadmaps/archive/road-to-employee-product-and-external-proof.md` Phase 8.

package/docs/decisions/ADR-063-append-jsonl-encryption-deferred.md

@@ -0,0 +1,83 @@
+---
+adr: 063
+status: accepted
+date: 2026-06-08
+decision: append-jsonl-encryption-deferred
+supersedes: —
+superseded_by: —
+phase: employee-product Phase 8 (road-to-employee-product-and-external-proof, Step 3)
+type: structural
+---
+
+# ADR-063 — Append-JSONL store encryption deferred (nonce-management gate)
+
+## Status
+
+**Accepted** · 2026-06-08. AI-council (claude-sonnet-4-5 + gpt-4o, design mode,
+2026-06-08). Records why encrypt-at-rest Part B ships **documents-only** and
+what must be solved before the append-heavy JSONL stores are encrypted.
+
+## Context
+
+ADR-062 chose AES-256-GCM + Option-4 Python-authoritative store access. The
+three workspace stores have different write shapes:
+
+- **documents** — whole-file `<slug>.md`. Whole-file `.md.enc` is a natural
+  fit; encrypted in Part B.
+- **sessions** — `sessions/<day>/<id>.jsonl`, **append-heavy** (one record per
+  host turn).
+- **analytics** — `analytics/events.jsonl`, **append-heavy** on a hot UI path.
+- **document revision logs** — `<slug>.history.jsonl`, append-once-per-save.
+
+AES-256-GCM encrypts a whole blob — you cannot append a line to an encrypted
+blob. Two strategies were weighed:
+
+- **Whole-file read-decrypt-append-encrypt-rewrite** per append: O(file) per
+  event under a lock — unacceptable for the analytics hot path.
+- **Per-record encryption** (one envelope per line, append stays append):
+  attractive, but the council flagged it as **cryptographically unsafe as
+  sketched** — AES-GCM security collapses on (key, nonce) reuse, and the
+  design had no nonce-derivation scheme, no crash/concurrency reuse proof, no
+  nonce-exhaustion handling.
+
+## Decision
+
+**Defer encryption of all append-JSONL stores** — `sessions/*.jsonl`,
+`analytics/events.jsonl`, and document `*.history.jsonl` — to a dedicated
+follow-up. Part B encrypts document `.md` bodies only (the highest-sensitivity
+content: offer / mail / memo / brief bodies). The append-JSONL set stays
+plaintext until a per-record encryption protocol is designed and ADR'd.
+
+## Consequences
+
+- Document bodies are encrypted end-to-end (write + Python-authoritative read);
+  edit metadata in `.history.jsonl` and session/analytics records remain
+  plaintext for now. The at-rest-encryption contract scope table is updated to
+  mark this split explicitly so no one assumes the JSONL stores are protected.
+- The flag stays default-OFF; nothing about today's behaviour changes.
+
+### Must-solve before append-JSONL encryption (the follow-up ADR's gate)
+
+1. **Nonce-derivation scheme** that provably never reuses (key, nonce):
+   deterministic from (key, file-id, monotonic-record-index) or a
+   crash-persistent counter — not bare random per line.
+2. **Concurrent-append serialization** (file lock + atomic record-index
+   allocation) so two writers cannot mint the same nonce.
+3. **Crash safety** — partial/truncated final record detected and skipped, not
+   fatal; counter state survives process restart.
+4. **Nonce-exhaustion / rotation** before the GCM 2^32-per-key limit.
+5. **Hot-path cost** — analytics `emit()` must stay non-blocking; per-record
+   encryption must not reintroduce whole-file rewrite.
+
+## Alternatives
+
+Whole-file-rewrite-per-append (rejected: O(file) on the hot path) and
+ship-all-three-now with random per-line nonces (rejected: nonce-reuse
+vulnerability). See ADR-062 for the cipher + Option-4 architecture this builds
+on.
+
+## References
+
+- ADR-062 — encrypt-at-rest store architecture (cipher + Option 4).
+- Contract: [`docs/contracts/at-rest-encryption.md`](../contracts/at-rest-encryption.md).
+- Stores: `src/cli/python/workspace_sessions.py`, `workspace_analytics.py`, `workspace_documents.py`.

package/docs/decisions/ADR-064-append-jsonl-per-record-encryption.md

@@ -0,0 +1,113 @@
+---
+adr: 064
+status: accepted
+date: 2026-06-08
+decision: append-jsonl-per-record-encryption
+supersedes: —
+superseded_by: —
+phase: employee-product Phase 8 (road-to-employee-product-and-external-proof, Step 3)
+type: structural
+---
+
+# ADR-064 — Append-JSONL per-record encryption protocol
+
+## Status
+
+**Accepted** · 2026-06-08. Resolves the nonce-management gate ADR-063 set.
+Design converged via AI-council (claude-sonnet-4-5 + gpt-4o, design mode,
+2026-06-08) — a cautious round that raised six refinements (nonce-count
+awareness, single-writer enforcement, per-store corruption policy, envelope
+versioning, OS preconditions, scope sequencing); the protocol below folds them
+in. First store shipped under this protocol: **analytics**.
+
+## Context
+
+ADR-063 deferred encrypting the append-heavy JSONL stores because AES-GCM
+cannot append to a blob and the per-record scheme needed a nonce-management
+design. This ADR fixes the protocol.
+
+## Decision
+
+### Protocol — per-record self-contained envelope
+
+Each JSONL record is encrypted independently into its own `AC1\0` AES-256-GCM
+envelope (the Part-A cipher, with its version byte), base64-encoded as **one
+line**. Append = `encrypt_line(json)` → a single atomic `O_APPEND` write. No
+whole-file rewrite, no shared counter. Helpers live in `workspace_crypto`
+(`encrypt_line` / `decrypt_line`); `decrypt_line` passes a plaintext JSON line
+(`{`/`[`-prefixed) through unchanged, so a file with mixed plaintext+encrypted
+records (flag flipped mid-life) reads correctly.
+
+- **Nonce (N1):** a fresh **random 96-bit nonce per record**. NIST SP 800-38D
+  permits random-construction nonces up to 2^32 invocations per key; a session
+  or analytics file is many orders below that, and `rekey` resets the per-key
+  count. Random nonces carry **no crash-fragile counter state** — the prior
+  round's "catastrophic reuse" concern was about counters resetting on crash,
+  which this scheme does not use.
+- **Concurrency (N2):** correctness rests on **single-writer-per-file**, not
+  locks. Each record line is independent (own nonce, own envelope), so one
+  atomic append per line suffices. The single-writer guarantee is
+  **architectural**: the Python store module is the sole writer. For sessions
+  (Node reads+writes today) this means routing through the Python CLI
+  (ADR-062 Option 4) so there is still exactly one writer — the protocol is
+  single-writer-based, **not** Python-only-based, so it extends to sessions
+  unchanged.
+- **Corruption (N3) — per store:** *analytics* is best-effort telemetry →
+  skip-and-continue on a torn/undecryptable line. *Document history* (when it
+  lands) is state-critical → fail-closed. The reader policy is the store's
+  call, not the protocol's.
+- **Versioning (N4):** the envelope version byte (Part A) lets a future
+  scheme coexist; unknown versions already reject.
+
+### Operations parity
+
+Each encrypted append-JSONL store ships `migrate` (plaintext → per-record
+`.enc` lines, idempotent), `decrypt-all` (kill-switch → plaintext, works
+flag-off), and `rekey` (rotate key + re-encrypt every record). `prune` (and any
+age/query reader) is decrypt-aware but keeps the original encrypted line at
+rest.
+
+### Rollout order
+
+1. **analytics** — Python-only, single-writer already true. **Shipped.**
+2. **document `.history.jsonl`** — Python-only, inside `workspace_documents.py`;
+   its whole-file `.md` migrate/rekey/decrypt-all gained a parallel per-line
+   history pass. **Shipped.**
+3. **sessions** — Node reads+writes; the Option-4 Node-session refactor routed
+   all 5 endpoints (list / read / launch / append) through the Python CLI
+   (`--root` validated, `--host` / `--data-json` for record fidelity).
+   **Shipped.** All three append-JSONL stores now encrypt at rest.
+
+> **Routing choice (sessions):** the refactor went **uniform** Python-routing
+> (reads + writes always through the CLI, like documents), not the
+> conditional flag-gated routing this ADR's design round leaned toward. Uniform
+> removes the need for Node to read the flag (Python owns the flag decision —
+> true single source of truth), is consistent with the documents precedent, and
+> is fully CI-testable (plaintext path needs no `cryptography`). The design
+> round's perf concern targeted *machine-hot* appends; session appends are
+> human-turn-paced, so the per-op subprocess cost is imperceptible.
+
+## Consequences
+
+- Analytics records are encrypted at rest when the flag is on; the flag stays
+  **default-OFF**, so nothing changes for today's users.
+- `emit()` stays non-blocking and never raises: a crypto error DROPS the event
+  (consistent with the existing scrub-fail-drop), never persists it
+  unencrypted.
+- The shared `encrypt_line`/`decrypt_line` protocol is now the contract the
+  history + session follow-ups reuse verbatim.
+
+## Alternatives
+
+Counter-based nonces (rejected: crash-fragile state, concurrent-index
+allocation) and whole-file read-modify-rewrite per append (rejected by ADR-063:
+O(file) on the analytics hot path). See ADR-062 (cipher + Option 4) and ADR-063
+(the deferral gate this resolves).
+
+## References
+
+- ADR-062 — cipher + Python-authoritative architecture.
+- ADR-063 — the deferral + nonce gate this resolves.
+- `src/cli/python/workspace_crypto.py` (`encrypt_line`/`decrypt_line`),
+  `workspace_analytics.py` (emit/read/prune/migrate/decrypt-all/rekey).
+- Contract: [`docs/contracts/at-rest-encryption.md`](../contracts/at-rest-encryption.md).

package/docs/decisions/ADR-065-tier3-inbox-handoff-v0.md

@@ -0,0 +1,86 @@
+---
+adr: 065
+status: accepted
+date: 2026-06-08
+decision: tier3-inbox-handoff-v0
+supersedes: —
+superseded_by: —
+phase: employee-product Phase 8 (road-to-employee-product-and-external-proof)
+type: structural
+---
+
+# ADR-065 — Tier-3 host hand-off inbox: plaintext, ephemeral v0 (encryption declined)
+
+## Status
+
+**Accepted** · 2026-06-08. Design converged via AI-council (claude-sonnet-4-5 +
+gpt-4o, design mode, 2026-06-08). The encrypt-at-rest arc (ADR-062/063/064)
+listed the inbox as the one deferred store; the council round that scoped it
+found the inbox did not exist yet **and** that encrypting it would be security
+theater. This ADR records the honest v0: build the hand-off, ship it plaintext.
+
+## Context
+
+ADR-023 specifies a **Tier-3 host hand-off**: for hosts the workspace cannot
+drive (Augment, Cursor, Cline, Windsurf, JetBrains), the workspace writes the
+rendered prompt into `~/.event4u/agent-config/workspace/inbox/<id>.md` and
+surfaces a copy-to-clipboard banner; the user opens the host themselves. No
+code wrote or read that file — the feature was specified, never built.
+
+## Decision
+
+Build the Tier-3 inbox as a **plaintext, ephemeral, content-minimal** store.
+
+- **Plaintext — encryption declined.** The inbox holds a prompt the user
+  *reads to copy-paste*; the adversary an at-rest cipher defends against is a
+  filesystem attacker. That same prompt content already lives in the
+  **encrypted sessions store**. Encrypting the inbox therefore stops **no
+  incremental threat** — it would add migrate/rekey/decrypt-all/Python-routing
+  complexity for zero marginal security. Revisit only if a distinct threat
+  model emerges (e.g. the inbox starts holding content not in sessions).
+- **Ephemeral.** `prune` drops hand-off files older than 24h; the store is a
+  transient hand-off surface, not durable storage.
+- **Content-minimal (v0).** The file is a small frontmatter header
+  (id / role / task / session / created_at) + the **rendered prompt body**
+  supplied by the caller. Skill-body pre-rendering **shipped** as a follow-up
+  ([`ADR-066`](ADR-066-skill-body-prerendering.md) — `--skill-hint` resolves the
+  skill body into the hand-off). Still **deferred:** host-tier **auto-detection**
+  (v0 takes the hand-off intent explicitly from the caller).
+- **Python-authoritative, ships dark.** `workspace_inbox.py`
+  (write / read / list / forget / prune, `--root` validated to
+  `…/workspace/inbox`) is the store; the Node `POST /api/v1/workspace/inbox`
+  + `GET /api/v1/workspace/inbox/:id` endpoints route through it and are
+  **gated behind `AGENT_CONFIG_TIER3_INBOX` (default off)** until the hand-off
+  UX is validated. The write endpoint returns `{id, path, banner}`; the banner
+  text only — clipboard / UI wiring is the Preact shell's job, deferred.
+- A pasted credential in the prompt is **scrubbed** on write (disposable
+  hand-off posture, same as the session/analytics telemetry stores).
+
+## Consequences
+
+- The Tier-3 hand-off has a real, tested writer/reader for the first time;
+  the encrypt-at-rest arc is closed (the inbox is intentionally plaintext, not
+  an outstanding encryption gap).
+- The feature ships dark — zero behaviour change until an operator sets the
+  flag.
+- If the inbox later carries content NOT mirrored in sessions, encryption
+  must be revisited (reuse the documents whole-file `.md.enc` pattern); the
+  contract scope table records this trigger.
+
+## Alternatives
+
+- **Encrypt the inbox** (the arc's original intent) — rejected as security
+  theater per the threat-model analysis above.
+- **Fold into `launch`** (write the inbox when a Tier-3 launch happens) —
+  rejected for v0: requires host-tier auto-detection, which is deferred; a
+  standalone endpoint is more testable and modular.
+- **Skill-body pre-rendering in v0** — rejected: a new skill-resolution trust
+  boundary; its own ADR.
+
+## References
+
+- ADR-023 — host-agent protocol (Tier-3 hand-off spec).
+- ADR-024 — workspace v0 floor (the inbox is a post-floor addition).
+- ADR-062/063/064 — the encrypt-at-rest arc this closes.
+- `src/cli/python/workspace_inbox.py`, `src/server/routes/workspace.ts`.
+- Contract: [`docs/contracts/at-rest-encryption.md`](../contracts/at-rest-encryption.md).

package/docs/decisions/ADR-066-skill-body-prerendering.md

@@ -0,0 +1,93 @@
+---
+adr: 066
+status: accepted
+date: 2026-06-08
+decision: skill-body-prerendering
+supersedes: —
+superseded_by: —
+phase: employee-product Phase 8 (road-to-employee-product-and-external-proof)
+type: structural
+---
+
+# ADR-066 — Skill-body pre-rendering for host hand-off (v0)
+
+## Status
+
+**Accepted** · 2026-06-08. Design converged via AI-council (claude-sonnet-4-5 +
+gpt-4o, design mode, 2026-06-08). Resolves the skill-body pre-rendering ADR-065
+(and ADR-024) deferred.
+
+## Context
+
+A role prompt carries one `skill_hint` (e.g. `doc-coauthoring`). Hosts without
+skill resolution — Codex / Gemini (Tier-1, no skill surface per ADR-024) and
+every Tier-3 host — cannot follow that reference, so the workspace must
+**pre-render the skill body** into the hand-off prompt. Skills live at
+`<skills-root>/<id>/SKILL.md` (YAML frontmatter + body); roots are
+`.agent-src.uncondensed/skills/` then `dist/agent-src/skills/` (only the latter
+exists in a consumer checkout). `skill_hint` is **package-controlled** (it comes
+from a shipped role prompt, not user input).
+
+## Decision
+
+### K1 — include the body **+ a one-line header** (option c)
+
+`workspace_skills.resolve_section(skill_hint)` returns a
+`## Skill context: <name>` section: the skill `name`, its one-line
+`description` (both from frontmatter), then the procedure **body** (frontmatter
+stripped). Body-only loses the skill's identity; the whole SKILL.md leaks
+metadata noise into the host prompt.
+
+### K2 — a dedicated resolver module
+
+`workspace_skills.py` owns skill → prompt-section rendering; the inbox store
+imports it and appends the section when `--skill-hint` is passed. The skill
+domain owns its own rendering syntax. *(Debt: the section markup lives in the
+skill module rather than a pure-data resolver + caller-side formatter. Accepted
+for v0; revisit if a second consumer needs a different format.)*
+
+### K3 — trust + bounds
+
+`skill_hint` is package-controlled but hardened anyway: charset-validate
+`^[a-z0-9][a-z0-9-]*$` (rejects path traversal), resolve **strictly under** a
+skills root (a `relative_to` guard backs the charset check), and the
+**existence-under-root** check is the de-facto allowlist (only real skill dirs
+resolve). A missing / invalid / unreadable skill **degrades to a one-line inline
+note** ("skill `<id>` not found — proceed without it"), never a crash. The body
+is **size-capped** at 64 KB (≫ the 912-line max). **No transitive resolution** —
+a skill body is included verbatim, it never pulls other skills → no cycles.
+*(Debt: a generated skill-id manifest allowlist is deferred to v1; the
+existence check covers v0.)*
+
+### K4 — scope
+
+v0 wires pre-rendering into the **Tier-3 inbox hand-off only** (the surface
+shipped in ADR-065): `workspace_inbox.py write --skill-hint <id>` +
+`POST /api/v1/workspace/inbox {skill_hint}`. Codex/Gemini Tier-1 pre-rendering
+rides the host-agent launch loop, which is unbuilt → out of scope. Ships dark
+behind the existing `AGENT_CONFIG_TIER3_INBOX` flag (no new flag).
+
+## Consequences
+
+- A Tier-3 hand-off now carries the skill context inline; a host with no skill
+  resolution can act on it.
+- Plaintext (the inbox is plaintext per ADR-065); no cryptography dependency.
+- Deferred to v1 (recorded debt): manifest-based skill-id allowlist, a
+  `--dry-run` resolve mode, and success / kill-switch metrics
+  (e.g. missing-skill rate). The feature ships dark, so these are not v0
+  blockers.
+
+## Alternatives
+
+- **Body-only / whole-SKILL.md** (K1 a/b) — rejected: identity loss vs metadata
+  noise.
+- **Resolver returns pure data, Node formats** (K2) — cleaner layering, deferred
+  as over-scoped for a single v0 consumer.
+- **Manifest allowlist in v0** (K3) — deferred; existence-under-root suffices
+  for package-controlled ids.
+
+## References
+
+- ADR-065 — Tier-3 inbox (the hand-off surface this renders into).
+- ADR-024 — notes Codex/Gemini lack skill resolution.
+- `src/cli/python/workspace_skills.py`, `workspace_inbox.py`, `src/server/routes/workspace.ts`.