@event4u/agent-config 2.26.0 → 3.1.0

package/docs/contracts/settings-api.md

@@ -0,0 +1,207 @@
+---
+stability: beta
+keep-beta-until: 2026-08-18
+---
+
+# Settings GUI — REST API Contract (v1)
+
+> Local-only HTTP API exposed by `agent-config ui:serve` and reused by
+> `agent-config settings` / `agent-config setup`. Listens on `127.0.0.1`
+> only; no auth, no cross-origin. The browser SPA is the sole client —
+> the legacy `/onboard` chat skill has been retired.
+>
+> Server-side validators live in `src/server/schemas/`; the JSON-Schema
+> emitted at `GET /api/v1/schema` is derived from those Zod modules via
+> `zod-to-json-schema` so client and server cannot drift.
+
+## Conventions
+
+- Base path: `/api/v1`. Any breaking change bumps the version segment.
+- Content type: `application/json; charset=utf-8` on every request and
+  response unless noted.
+- Errors: HTTP status carries the verdict; bodies are
+  `{ error: { code, message, fields?: Array<{ path, message }> } }`.
+- Time format: ISO-8601 UTC (`2026-05-20T14:23:11.842Z`).
+- File mtime: integer milliseconds since epoch (`fs.statSync(...).mtimeMs`
+  truncated to integer) — wire-stable across JSON parsers.
+- Optimistic locking: every endpoint that mutates an on-disk file
+  echoes `lastModified` on read and requires `If-Unmodified-Since` on
+  write. Drift returns **409 Conflict** with the current file body so
+  the client can render a 3-way merge.
+
+## Endpoints
+
+### `GET /api/v1/schema`
+
+Returns the JSON-Schema rendition of `settingsSchema` and `userMdSchema`
+so the SPA can build forms without bundling Zod.
+
+Response (200):
+
+```json
+{
+    "settings": { "$schema": "...", "type": "object", "properties": { ... } },
+    "userMd":   { "$schema": "...", "type": "object", "properties": { ... } },
+    "generatedAt": "2026-05-20T14:23:11.842Z"
+}
+```
+
+### `GET /api/v1/settings`
+
+Returns the **three-layer merged** settings tree plus the freshness
+token for optimistic locking. Merge order (per **ADR-020** + roadmap
+`road-to-global-only-install` § Phase 2.2):
+
+```text
+defaults (config/agent-settings.template.yml)
+  < global (~/.event4u/agent-config/settings/.agent-settings.yml)
+    < project (<projectRoot>/settings/.agent-settings.yml, optional)
+```
+
+Defaults come from the package template with `__COST_PROFILE__` /
+`__USER_TYPE__` placeholders substituted for their permissive defaults
+(`balanced` / `""`). Global and project layers are read with the typed
+subdir preferred over the legacy flat path. The route mirrors
+`scripts/install.py::read_layered_settings` 1:1 so the Python installer
+and the Fastify GUI cannot drift.
+
+Response (200):
+
+```json
+{
+    "values":       { "cost_profile": "balanced", "...": "..." },
+    "lastModified": 1747749791842,
+    "path":         "settings/.agent-settings.yml",
+    "legacyHints":  { "user_name": "Matze" }
+}
+```
+
+`legacyHints` is an out-of-band sidecar carrying values that have moved
+out of `settingsSchema` but still live in a pre-v2 file on disk. Keys
+are omitted when empty, never `null`. Current hints:
+
+| Key         | Source (legacy)        | New home                                |
+| ----------- | ---------------------- | --------------------------------------- |
+| `user_name` | `personal.user_name`   | `.agent-user.md` &rarr; `identity.name` |
+
+The wizard consumes hints on first run only — when `.agent-user.md`
+does not yet exist — to pre-fill the merged identity field. Subsequent
+PUTs strip the legacy keys (Zod-unknown), so the next read returns no
+hints.
+
+Errors: **404** when **neither** the global nor the project file
+exists (defaults alone are not an "installed" state — the SPA should
+redirect to `/#/wizard/Welcome`); **500** with `code=YAML_PARSE` when
+either layer is on disk but unparseable (body includes the line/column).
+
+### `POST /api/v1/settings/diff`
+
+Computes the merged delta without writing. Used by the **Preview
+changes** modal. Request:
+
+```json
+{
+    "values":             { "...": "..." },
+    "ifUnmodifiedSince":  1747749791842
+}
+```
+
+Response (200): `{ "changes": [{ "path": "cost_profile", "from": "minimal", "to": "balanced" }, ...] }`.
+
+Errors: **409** on mtime drift; **422** on validation failure (`fields`
+populated).
+
+### `PUT /api/v1/settings`
+
+Validates, merges with disk, writes atomically.
+
+Request: same shape as `/diff`. Required header:
+`If-Unmodified-Since: <ms-epoch>`.
+
+Response (200): `{ "lastModified": <new-ms-epoch>, "writtenPaths": [".agent-settings.yml"] }`.
+
+Errors: **412 Precondition Required** when the header is absent;
+**409 Conflict** when the on-disk mtime is newer than the header value;
+**422 Unprocessable Entity** with per-field errors on validation
+failure; **500** with `code=ATOMIC_WRITE` if the temp-rename loop fails.
+
+### `GET /api/v1/user-md`
+
+Reads `<projectRoot>/.agent-user.md`. Returns `{ body: '', exists: false, lastModified: null }`
+when the file is missing (wizard pre-fill case).
+
+### `GET /api/v1/user-md/template`
+
+Returns the package-shipped template (`templates/agent-user.md`) when
+present, else 204 No Content. Wizard uses this to pre-fill the textarea
+on first run.
+
+### `PUT /api/v1/user-md`
+
+Validates the body through `userMdSchema` (`gray-matter` parse must
+succeed; ≤ 8 000 chars). Atomic-writes with mode 0600.
+
+Required header: `If-Unmodified-Since: <ms-epoch>` (omitted only when
+`exists=false` on the prior GET — server treats absence as "create new").
+
+### `GET /api/v1/wizard/state`
+
+Returns the persisted partial wizard state, or
+`{ step: 0, totalSteps: <N>, partial: {}, startedAt: null }` when no
+state file exists.
+
+### `POST /api/v1/wizard/state`
+
+Persists partial state between step transitions. Body:
+`{ step: number, partial: Record<string, unknown> }`.
+
+### `POST /api/v1/wizard/finish`
+
+Two-Phase-Commit (council HIGH 2026-05-18): assigns a `txnId`, writes
+`settings.yml.tmp-{txnId}` + `user-md.tmp-{txnId}` + an empty
+`wizard.commit-intent-{txnId}` marker, renames both target files, then
+deletes the marker. Server boot replays orphaned markers idempotently.
+
+Response (200): `{ writtenPaths: string[], txnId: string }`.
+
+Errors: **500** with `code=TXN_PARTIAL` when the marker survives a crash
+(client should redirect the user to a "your last save is being
+recovered" screen and refetch state).
+
+## CLI: `agent-config settings migrate`
+
+Companion to the layered reader (ADR-020). Lifts an existing
+project-local `.agent-user.yml` / `.agent-settings.yml` into
+`~/.event4u/agent-config/`. Idempotent — refuses to overwrite a
+non-empty global file without `--force`. Order matches Phase 5
+amendment A2 (`copy → verify`; the destructive `move` step is owned by
+`migrate-to-global`, not this subcommand).
+
+Flags:
+
+- `--from <path>` — project root to read from (default: `cwd`).
+- `--force` — overwrite a non-empty global file.
+- `--dry-run` — list intended copies; zero writes; exit 0.
+
+Exit codes: `0` on success or no-op; `1` on validation failure or a
+non-empty global file without `--force`.
+
+## Status codes summary
+
+| Code | Meaning                                              |
+| ---- | ---------------------------------------------------- |
+| 200  | Success                                              |
+| 204  | No content (template-not-shipped case)               |
+| 404  | Target file missing                                  |
+| 409  | `If-Unmodified-Since` drift                          |
+| 412  | `If-Unmodified-Since` header missing on write        |
+| 422  | Validation failure (`error.fields` populated)        |
+| 500  | YAML parse / atomic-write / 2PC partial recovery     |
+
+## Test fixtures
+
+Round-trip fixtures live in `tests/server/fixtures/`. Every endpoint
+above has a happy-path test in `tests/server/<endpoint>.test.ts` and at
+least one error-path test (409 or 422). The schema↔template parity
+test (`tests/server/schemas/parity.test.ts`) is the gate that keeps
+`settingsSchema` and `config/agent-settings.template.yml` in lockstep.

package/docs/contracts/settings-gui-agent-mode.schema.json

@@ -0,0 +1,128 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://event4u.app/contracts/settings-gui-agent-mode.schema.json",
+    "title": "settings-gui-agent-mode",
+    "description": "Machine-readable mode of `agent-config settings`. When invoked with `--agent`, the CLI emits a single JSON envelope to stdout instead of opening a browser; the caller (chat agent, CI script, IDE extension) drives the wizard or settings editor via the same `/api/v1/*` routes through this envelope. Lives at `docs/contracts/settings-gui-agent-mode.schema.json` per the frontend-engineer council finding (roadmap line 333).",
+    "type": "object",
+    "additionalProperties": false,
+    "required": ["version", "kind", "endpoint", "auth"],
+    "properties": {
+        "version": {
+            "type": "string",
+            "const": "1",
+            "description": "Envelope schema version. Bumped on breaking changes."
+        },
+        "kind": {
+            "type": "string",
+            "enum": ["wizard", "settings"],
+            "description": "Which mode the server booted in. `wizard` = first-run flow; `settings` = settings editor."
+        },
+        "endpoint": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["base", "discoveryFile"],
+            "properties": {
+                "base": {
+                    "type": "string",
+                    "format": "uri",
+                    "pattern": "^http://127\\.0\\.0\\.1:[0-9]+/?$",
+                    "description": "Fastify server URL. Always 127.0.0.1; the port is picked from the foundation roadmap's port-picker."
+                },
+                "discoveryFile": {
+                    "type": "string",
+                    "description": "Absolute path to `.agent-config/skill-bridge.port` / `.token` / `.pid` discovery file the caller should read for handshake."
+                }
+            }
+        },
+        "auth": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["scheme", "token"],
+            "properties": {
+                "scheme": {
+                    "type": "string",
+                    "const": "Bearer"
+                },
+                "token": {
+                    "type": "string",
+                    "description": "Random per-boot token; the caller MUST send `Authorization: Bearer <token>` on every API request. Token rotates on every `agent-config settings` boot."
+                }
+            }
+        },
+        "routes": {
+            "type": "object",
+            "description": "Stable list of routes the caller may use. Schema-bound to roadmap step 0.4; new routes added here MUST land in `docs/contracts/settings-api.md` simultaneously.",
+            "additionalProperties": false,
+            "properties": {
+                "settings": {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "properties": {
+                        "get": {"type": "string", "const": "/api/v1/settings"},
+                        "diff": {"type": "string", "const": "/api/v1/settings/diff"},
+                        "put": {"type": "string", "const": "/api/v1/settings"}
+                    }
+                },
+                "userMd": {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "properties": {
+                        "get": {"type": "string", "const": "/api/v1/user-md"},
+                        "put": {"type": "string", "const": "/api/v1/user-md"},
+                        "template": {"type": "string", "const": "/api/v1/user-md/template"}
+                    }
+                },
+                "wizard": {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "properties": {
+                        "state": {"type": "string", "const": "/api/v1/wizard/state"},
+                        "finish": {"type": "string", "const": "/api/v1/wizard/finish"}
+                    }
+                }
+            }
+        },
+        "shutdown": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["signal", "timeoutSeconds"],
+            "properties": {
+                "signal": {
+                    "type": "string",
+                    "enum": ["SIGTERM", "SIGINT"],
+                    "description": "Signal the caller sends to gracefully stop the server."
+                },
+                "timeoutSeconds": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "maximum": 60,
+                    "description": "Caller's grace window before SIGKILL. Server drains in-flight requests within this window."
+                }
+            }
+        },
+        "capabilities": {
+            "type": "array",
+            "description": "Optional feature flags the server advertises. Callers MAY ignore unknown values for forward compatibility.",
+            "items": {
+                "type": "string",
+                "enum": ["wizard.resumeState", "settings.diff", "settings.optimisticLock", "userMd.template", "wizard.crashRecovery"]
+            },
+            "uniqueItems": true
+        }
+    },
+    "examples": [
+        {
+            "version": "1",
+            "kind": "settings",
+            "endpoint": {
+                "base": "http://127.0.0.1:41999/",
+                "discoveryFile": "/Users/dev/proj/.agent-config/skill-bridge.port"
+            },
+            "auth": {
+                "scheme": "Bearer",
+                "token": "9f3a7b2c1d4e8f6a"
+            },
+            "capabilities": ["settings.diff", "settings.optimisticLock"]
+        }
+    ]
+}

package/docs/contracts/smoke-contracts.md

@@ -34,8 +34,8 @@ the paths touched in the PR:
 
 | Tier | Globs that trigger | Script |
 |---|---|---|
-| kernel | `.agent-src.uncompressed/rules/**`, `.agent-src/rules/**`, `router.json`, `scripts/measure_rule_budget.py` | `scripts/smoke/kernel.sh` |
-| router | `router.json`, `.agent-src.uncompressed/rules/**`, `.agent-src.uncompressed/skills/**`, `docs/contracts/**`, `docs/guidelines/**` | `scripts/smoke/router.sh` |
+| kernel | `.agent-src.uncompressed/rules/**`, `.agent-src/rules/**`, `dist/router.json`, `scripts/measure_rule_budget.py` | `scripts/smoke/kernel.sh` |
+| router | `dist/router.json`, `.agent-src.uncompressed/rules/**`, `.agent-src.uncompressed/skills/**`, `docs/contracts/**`, `docs/guidelines/**` | `scripts/smoke/router.sh` |
 | schema | `.agent-src.uncompressed/skills/**`, `.agent-src.uncompressed/rules/**`, `scripts/schemas/**`, `scripts/skill_linter.py`, `scripts/validate_frontmatter.py` | `scripts/smoke/schema.sh` |
 | skills | `.agent-src.uncompressed/skills/**` | `scripts/smoke/skills.sh` |
 
@@ -131,7 +131,7 @@ the final baseline line) for CI summary parsing.
 | Symptom | Likely cause | Fix |
 |---|---|---|
 | `kernel.sh` reports > 9 missing fences | Kernel rule lost its Iron Law block during edit | Restore the fence; update `EXEMPT_FROM_FENCE` only for new dispatch indexes |
-| `router.sh` reports > 0 broken pointers | `router.json` references an id without a rule file | Add the rule or remove the route — never edit the smoke baseline up |
+| `router.sh` reports > 0 broken pointers | `dist/router.json` references an id without a rule file | Add the rule or remove the route — never edit the smoke baseline up |
 | `schema.sh` reports FAILs | A skill / rule lost a required field | Restore via [`scripts/schemas/skill.schema.json`](../../scripts/schemas/skill.schema.json) |
 | `skills.sh` 5/5 random sample fails | Hand-edit broke frontmatter or renamed directory without updating `name:` | Restore filename ↔ slug coupling |
 

package/docs/contracts/tier-3-contrib-plugin.md

@@ -34,7 +34,7 @@ Tier-3 is the explicit overflow bucket.
 
 The following surfaces are Tier-3 candidates as of 2026-05-12. They
 were surfaced during the
-[`2026-05-12-installer-expansion`](../../agents/council-sessions/2026-05-12-installer-expansion/synthesis.md)
+[`2026-05-12-installer-expansion`](../../agents/runtime/council/sessions/2026-05-12-installer-expansion/synthesis.md)
 council round and have **no entries** in `_VALID_TOOLS`,
 `USER_SCOPE_PATHS`, `SCOPE_SUPPORT`, or the bash `VALID_TOOLS` set.
 

package/docs/contracts/trust-and-safety.md

@@ -0,0 +1,144 @@
+---
+stability: beta
+keep-beta-until: 2026-08-21
+---
+
+# Trust & Safety Layer — Phase 5 of the monorepo migration
+
+> **Status:** active · **Stability:** beta · **Owner:** monorepo-phase-5
+> · **Authoritative ADR:** [`ADR-018`](../decisions/ADR-018-trust-and-safety-layer.md)
+
+Phase 1 stamped every artefact with `trust.level`,
+`trust.confidence`, and `trust.human_review_required`. Phase 5
+**enforces** those fields: the installer surfaces them at selection
+time, the compressor injects banners into compiled output, the
+runtime gates `human_review_required: true` artefacts before final
+output, and a lint catches drift. This contract is what those four
+consumers depend on.
+
+## § 1 — Trust levels
+
+A closed enum on `trust.level`:
+
+| level         | meaning                                                              |
+|---------------|----------------------------------------------------------------------|
+| `core`        | Iron-Law / structural. Cannot be downgraded. Kernel rules sit here.  |
+| `professional`| Domain expertise the user opted into; no human-review floor.         |
+| `advisory`    | High-impact judgement. Installer **must** confirm; banner injected.  |
+| `restricted`  | Reserved for future legal / regulated content. Same surface as advisory, stricter copy. |
+| `experimental`| Pre-stable. May be removed without ADR.                              |
+
+`trust.confidence` is a parallel signal (`high` · `medium` · `low`)
+used by the manifest's summary; it does **not** gate behaviour.
+
+`trust.human_review_required: true` is the per-artefact banner gate.
+Independent of `trust.level` so a `professional` artefact can still
+demand review on its specific surface.
+
+## § 2 — HRR banner
+
+The compressor (`scripts/compress.py`) prepends every artefact whose
+frontmatter declares `trust.human_review_required: true` with:
+
+```text
+<!-- agent-config:human-review-banner -->
+> HUMAN REVIEW REQUIRED · trust: <level> · owner: <domain>
+
+<original body>
+```
+
+- The HTML comment is the parser-stable marker
+  (`_HRR_BANNER_MARKER` in `scripts/compress.py`). Runtime detection
+  greps for this string, never the prose line.
+- Idempotent: re-compressing a file that already carries the marker
+  leaves it unchanged.
+- `<domain>` is the first pack id that ships the artefact (e.g.
+  `finance-basic`, `founder-strategy`); falls back to `core` for
+  unscoped artefacts.
+
+## § 3 — Domain safety floors
+
+Each pack that ships any `advisory`/`restricted` artefact MUST also
+ship at least one rule whose logical filename contains
+`safety-floor`. The current set:
+
+| pack                    | safety-floor rule                                  |
+|-------------------------|----------------------------------------------------|
+| `core` (universal)      | `rules/engineering-safety-floor.md`                |
+| `pack-finance-basic`    | `rules/finance-safety-floor.md`                    |
+| `pack-finance-advanced` | inherits `finance-safety-floor` from `pack-finance-basic` |
+| `pack-founder-strategy` | `rules/strategy-safety-floor.md`                   |
+
+A safety-floor rule:
+
+- Carries `trust.level: advisory` and `trust.human_review_required: true`
+  itself — it ships with the banner.
+- Names what the agent must **not** issue (final investment call, binding
+  legal advice, single-path strategic verdict) and what it must surface
+  instead (alternatives, sensitivity, assumptions, jurisdiction).
+- Loads automatically alongside the rest of the pack — no opt-in.
+
+## § 4 — Installer flow
+
+[`packages/core/installer/src/trust-escalation.ts`](../../packages/core/installer/src/trust-escalation.ts)
+implements the gate:
+
+1. **Display.** The pack picker reads `packs[].trust_summary` from
+   `dist/discovery/discovery-manifest.json` and renders one line per pack:
+   `Finance basic: 3 advisory · 3 professional · human-review on 1`.
+2. **Confirm.** Selecting a pack with any `advisory`/`restricted`
+   artefact triggers a confirm prompt. Non-interactive mode (CI,
+   agent-mode) requires `--accept-advisory=<pack-id>[,<pack-id>...]`
+   explicitly; absence aborts with a non-zero exit.
+3. **Agent-mode.** Emits a structured `confirm` question type with the
+   trust counts inline; the host agent must relay it verbatim per
+   `command-suggestion-policy`.
+4. **Lockfile.** `.agent-config.lock.json` records the accepted trust
+   counts per pack at install time. A later `sync` that finds the
+   manifest's `trust_summary` has **escalated** (more advisory /
+   restricted artefacts than were accepted) re-runs the confirm step
+   before applying.
+
+## § 5 — Coherence lint
+
+`scripts/lint_trust_coherence.py` (wired into `ci-fast` and `ci-full`)
+asserts three invariants over `dist/discovery/discovery-manifest.json`:
+
+1. **Safety-floor presence.** Every pack with
+   `trust_summary.advisory + trust_summary.restricted > 0` ships at
+   least one artefact whose logical path contains `safety-floor`.
+2. **Banner presence.** Every artefact with
+   `trust.human_review_required: true` has its compiled output under
+   `.agent-src/<logical>` and that output contains
+   `<!-- agent-config:human-review-banner -->`.
+3. **Kernel trust floor.** Every rule listed in `dist/router.json` `kernel[]`
+   declares `trust.level: core`. No escalation (advisory blocks the
+   Iron-Law floor) and no demotion (experimental cannot guarantee it).
+
+Exits 0 clean, 1 on any violation. Tests in
+`tests/test_lint_trust_coherence.py` lock the seven failure modes.
+
+## § 6 — What this contract does **not** do
+
+- **Per-user permissions.** Trust is a property of artefacts, not of
+  users. The installer confirms once at install / sync time; there is
+  no runtime per-action authorisation.
+- **Rewriting the Iron Law floor.** `non-destructive-by-default`,
+  `commit-policy`, `scope-control § git-ops`, `security-sensitive-stop`
+  keep their universal scope — this contract references them, never
+  re-declares them. See [`safety-model`](safety-model.md) and
+  [`kernel-membership`](kernel-membership.md).
+- **Versioning the trust enum.** A new level (e.g. a future
+  `regulated`) requires a follow-on ADR; this contract enumerates the
+  current closed set.
+
+## § 7 — References
+
+- ADR: [`ADR-018 — Trust & Safety Layer`](../decisions/ADR-018-trust-and-safety-layer.md)
+- Compressor implementation: [`scripts/compress.py`](../../scripts/compress.py)
+  (`_inject_hrr_banner`, `_HRR_BANNER_MARKER`)
+- Installer implementation: [`packages/core/installer/src/trust-escalation.ts`](../../packages/core/installer/src/trust-escalation.ts)
+- Lint implementation: [`scripts/lint_trust_coherence.py`](../../scripts/lint_trust_coherence.py)
+- Sibling contracts: [`safety-model`](safety-model.md) ·
+  [`kernel-membership`](kernel-membership.md) ·
+  [`ADR-013` — discovery frontmatter](../decisions/ADR-013-discovery-frontmatter-contract.md)

package/docs/contracts/universal-skills.md

@@ -76,7 +76,7 @@ Adding a skill to this allowlist:
 1. Open a PR that edits this file + the relevant skill's `recommended_for_user_types:` (omitted = universal).
 2. Cite ≥ 4 user-type prompts from `tests/eval/corpus-non-dev.yaml` that select the skill.
 3. Require approval from one Tier-1 reviewer (architecture-review-lens or skill-writing).
-4. Document the inclusion in `agents/eval-findings/` with the supporting eval prompts.
+4. Document the inclusion in `agents/evidence/eval-findings/` with the supporting eval prompts.
 
 Removing a skill is breaking. It must be announced in `STABILITY.md` with a deprecation window ≥ one minor release.
 

package/docs/contracts/write-engine.md

@@ -24,7 +24,7 @@ consumer command; the **only** axis of variation is:
 
 | Consumer command | Style source | Footer |
 |---|---|---|
-| `/ghostwriter:write` | `agents/ghostwriter/<slug>.md` (selected) | **Mandatory** |
+| `/ghostwriter:write` | `agents/reference/ghostwriter/<slug>.md` (selected) | **Mandatory** |
 | `/post-as:ghostwriter` | Same as above (thin alias) | **Mandatory** |
 | `/post-as:me` | `.agent-user.md` (project root) | **Omitted** — user is the author |