@event4u/agent-config 9.8.0 → 9.9.0

package/docs/succession.md

@@ -1,80 +0,0 @@
-# Succession — the minimal knowledge to take over
-
-> **Bus-factor doc (road-to-maintainer-bus-factor Phase 3).** If the maintainer
-> is unavailable, this is what a successor needs to keep `main` healthy and cut
-> releases. **No secret values live here — pointers only.** Companion:
-> [`release-runbook.md`](release-runbook.md) (the how-to-release steps).
-
-## Honest bus-factor (tracked, not inflated)
-
-- **Distinct humans who have reviewed/merged in the trailing 90 days: 1** (the
-  maintainer, `@matze4u`). The project is a single-maintainer repo; an AI
-  self-review gate (deferred — see the roadmap Phase 1) raises the floor but is
-  **not** independent human review.
-- Recompute this number honestly at any time:
-
-  ```bash
-  # merged PRs in the last 90 days + who reviewed them
-  gh pr list --state merged --search "merged:>=$(date -v-90d +%Y-%m-%d 2>/dev/null || date -d '90 days ago' +%Y-%m-%d)" \
-    --json number,author,reviews \
-    --jq '[.[] | .reviews[]?.author.login] | unique'
-  ```
-
-  Report the count as-is. A bus-factor of 1 stated plainly beats a bus-factor of
-  1 implied to be more.
-
-## Secrets / tokens — where they live, what they gate
-
-Configured in **GitHub → Settings → Secrets and variables → Actions** (repo
-secrets), never in the tree. None is required for the *core* release (version
-bump + tag + GitHub Release); they gate the **downstream** publish/deploy legs.
-
-| Secret | Gates | Missing → |
-|---|---|---|
-| `RELEASE_PR_TOKEN` (optional PAT / App token, `contents:write` + `pull-requests:write`) | Unattended release PR checks in [`release.yml`](../.github/workflows/release.yml) | One manual **"Approve workflows to run"** click per release (deliberate checkpoint, not a failure). |
-| — (none: **npm OIDC Trusted Publishing**) | `publish-npm.yml` — uses `id-token: write`, no stored npm token | If OIDC trust is misconfigured on npmjs, npm publish fails; fix the trusted-publisher config on the npm package, not a secret. |
-| `CLOUDFLARE_ACCOUNT_ID`, `CLOUDFLARE_API_TOKEN`, `CLOUDFLARE_WORKER_SUBDOMAIN`, `MCP_SMOKE_TOKEN` | `deploy-mcp-worker.yml` (MCP worker deploy + smoke) | MCP worker deploy skips/fails; core release unaffected. |
-| `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY` | `cross-model-canary.yml` + any AI-council / self-review automation | Canary + council automation skip; core release unaffected. |
-| `GITHUB_TOKEN` (auto-provided) | all workflows' default auth | n/a — GitHub injects it. |
-
-The live source of truth for which workflow needs which secret is the
-`secrets.*` references in [`.github/workflows/`](../.github/workflows/) — grep
-there if this table drifts:
-
-```bash
-grep -rhoE "secrets\.[A-Z_]+" .github/workflows/ | sort -u
-```
-
-## Operator-gated steps (need a human with credentials)
-
-- **Release-PR workflow approval** — the "Approve workflows to run" click when
-  `RELEASE_PR_TOKEN` is absent (see the runbook § 3.A).
-- **Branch-protection ruleset** — applied in GitHub → Settings → Rules UI;
-  source of truth mirrored in [`branch-protection-policy.md`](contracts/branch-protection-policy.md).
-  Not in code; a successor edits it in the UI.
-- **Repo administration** (visibility / rename / delete) — the
-  `production-visibility` environment gates manual approval; see
-  [`CONTRIBUTING.md`](../CONTRIBUTING.md).
-- **npm trusted-publisher config** — set on npmjs.org for the package, not in
-  this repo.
-
-## "Healthy main" — what good looks like
-
-- Latest `main` commit is green on all required checks for its PR shape
-  (see [`branch-protection-policy.md`](contracts/branch-protection-policy.md),
-  [`ci-green-floor.md`](contracts/ci-green-floor.md)).
-- No drift gate red: `release-drift.yml`, `release-guard.yml`,
-  `check-visibility-drift.yml`, the consistency + claims + proof gates.
-- `docs/CLAIMS.md` resolves (`task check-claims`); `docs/proof.md` is in sync
-  (`task build-proof-check`).
-- No completed roadmap left unarchived in `agents/roadmaps/` (the
-  `roadmap:progress-check` backstop).
-
-## Minimal takeover checklist
-
-1. Get `gh` authenticated as a repo admin; confirm `gh auth status`.
-2. Read [`release-runbook.md`](release-runbook.md) end-to-end.
-3. Confirm the secrets above are present for whichever downstream legs matter.
-4. Cut a `--dry-run` release (`task release -- --dry-run`) to see the pipeline
-   with zero mutations.
-5. When ready, follow the runbook for a real release.

package/docs/threat-model.md

@@ -1,30 +0,0 @@
-# Threat Model — agent-config
-
-`agent-config` (AC) is a file-first, **no-runtime** skill/rule/command suite.
-It ships artifacts (skills, rules, commands, MCP configs, hooks, installer) to
-11 host AI tools and is published as `@event4u/agent-config`. It runs no server
-and holds no user data. Threats are about **artifact integrity** and
-**supply-chain / distribution surface**, not app auth or billing.
-
-## Threat table
-
-| # | Surface | Attack vector | Current controls | Gap | Mitigation |
-|---|---|---|---|---|---|
-| a | **Malicious skill / rule via PR** — a contributed `.md` file smuggles prompt-injection or data-exfiltration payloads into the shipped artifact tree | Adversarial PR contributor embeds: (1) invisible Unicode (bidi / zero-width / Tag-block) to hide instructions, (2) role-takeover imperatives, (3) lethal-trifecta pattern in a new skill (private-data + untrusted-content + egress on one autonomous path) | `lint_hidden_unicode.py` — blocks Trojan-Source and invisible-char attacks; `lint_instruction_smuggling.py` — blocks disclosure-suppression and injection-tag prose; `lint_skill_frontmatter_safety.py` — blocks wildcard `allowed_tools`, `bypassPermissions`, unsafe `execution.type: automated`; PR review gate | No automated SARIF upload to GitHub Code Scanning; lethal-trifecta detection is architectural (rule) not linted structurally beyond the frontmatter check | Wire `lint_agent_security.py --sarif` output to GitHub Advanced Security on every PR (`lint_workflow_security.py` — P2); add structural trifecta check to frontmatter linter |
-| b | **Supply-chain compromise of AC's own deps** — a malicious version of an npm or Python dependency is pulled during CI / install and executes arbitrary code or modifies shipped artifacts | Dependency confusion / typosquatting attack on `package.json` or `requirements.txt` deps; compromised upstream package | `package-lock.json` + `requirements.txt` pin exact versions; CI installs from lockfile (`npm ci`) | No documented dep-audit policy; no Dependabot / Renovate automation; no integrity check (`npm audit` / `pip-audit`) in CI gate | Add `npm audit --audit-level=high` + `pip-audit` as a required CI step; document quarterly manual review cadence; pin Python deps in a lockfile (`pip-compile`) |
-| c | **Hostile consumer-repo environment** — AC's installer or hooks execute inside a repo whose `.git/hooks`, `.env`, or workspace files are attacker-controlled | Consumer repo pre-installs malicious Git hooks that intercept the AC installer or post-install hook; `.env` leaks tokens that AC hooks read; untrusted files are passed to AC linters | AC installer writes its own hooks under its namespace; AC hooks run as the user's shell — they do not read `.env` by design; `untrusted-input-defense` rule governs agent behaviour at runtime | No sandboxed execution for AC hooks; installer does not verify consumer hook integrity before writing | Document that AC hooks must not read repo-local env files; add installer pre-flight that warns if foreign hooks exist in `.git/hooks/`; scope AC hook writes to explicit namespaced filenames |
-| d | **Lethal-trifecta surface** — a skill combining private-data access + untrusted-content ingestion + external communication on one autonomous path enables confused-deputy / data-exfiltration attacks | Prompt-injected content inside a fetched doc instructs an agent to read a local secret and POST it to an attacker-controlled endpoint | `src/rules/lethal-trifecta-guard.md` (Iron Law: break one leg or gate egress behind human-in-the-loop); `src/rules/untrusted-input-defense.md` (untrusted content is data, never instructions; spotlighting); `lint_skill_frontmatter_safety.py` (flags over-broad tool grants) | These are authoring-time controls — no runtime *behavioural-enforcement* layer exists (input sanitization ≠ enforcement — see ADR-123) | Runtime behavioural enforcement stays out of scope for AC (`ADR-123-runtime-security-scope-and-spawn-hardening`): AC ships the rules, the consumer's tool-execution layer enforces them; the outbound content-scan guard is deferred with a `revisit-if`, not silently dropped. `lethal-trifecta-guard.md` and `untrusted-input-defense.md` are the canonical reference — do not re-describe here |
-| e | **Malicious metadata / frontmatter injection** — a PR embeds hostile YAML in a skill's frontmatter (e.g. injecting a trigger keyword that causes a dangerous skill to fire in unintended contexts, or adding `permissionMode: bypassPermissions`) | PR contributor adds `permissionMode: bypassPermissions` or a wildcard `allowed_tools: ["*"]` entry to an existing skill's frontmatter; or crafts a trigger keyword to hijack routing | `lint_skill_frontmatter_safety.py` — HIGH-severity block on `bypassPermissions`, wildcard `allowed_tools`, unsafe `execution.type: automated` without safety floor; `lint_hidden_unicode.py` — catches invisible chars inside frontmatter YAML values; PR review gate; `scripts/validate_frontmatter.py` schema validation | Schema validation does not verify trigger-keyword semantic safety (a plausible keyword that causes over-broad firing is not caught) | Extend `validate_frontmatter.py` to flag trigger keywords that match security-sensitive path prefixes (e.g. a skill triggering on `"auth"` when it has `execution.type: automated`) |
-| f | **Skill self-update — safety-floor rewrite** — an agent is social-engineered (via chat or a PR) into weakening a kernel rule, safety floor, or MCP/tool allowlist | A PR removes the Iron Law block from `non-destructive-by-default.md`; or a chat prompt instructs the agent to edit `security-sensitive-stop.md` to narrow its self-modification clause; or a PR modifies `scope-control` to remove the Hard Floor | `src/rules/security-sensitive-stop.md` — "self-modification via chat" clause: requests to weaken safety floors / kernel rules / MCP allowlists must route through `scope-control` gates; `src/rules/scope-control.md` — kernel-rule edits require own PR + ≥ 24 h soak; `dist/agent-src/` is read-only (source-of-truth rule); `scripts/check_condensation.py` detects Iron-Law section deletion or downgrade | No automated per-rule diff check that fires specifically when a kernel rule's Iron Law section is removed; relies on PR reviewer recognising the file class | Add a CI check (`scripts/check_kernel_rule_integrity.py` — P3+) that asserts Iron Law fenced-code blocks survive unchanged in all files listed in `docs/contracts/kernel-membership.md` |
-| g | **Subprocess spawn-env inheritance** — AC's own transport spawns an external CLI (the AI-council provider CLIs; consumer-runtime hooks spawn `git`) with the full parent `process.env`, so an attacker-influenced env var in the parent becomes RCE when the child (or a `git` it invokes internally) runs | A poisoned `GIT_EXTERNAL_DIFF` / `core.pager` / `GIT_SSH_COMMAND`, the `GIT_CONFIG_COUNT`/`_KEY_<n>`/`_VALUE_<n>` config-injection trio (sets `core.fsmonitor` → shell on every `git status`), a dynamic-loader `LD_PRELOAD` / `DYLD_INSERT_LIBRARIES` / `GCONV_PATH`, `GIT_ALTERNATE_OBJECT_DIRECTORIES` / `HOSTALIASES`, or a runtime hook `NODE_OPTIONS` / `BASH_ENV` / `PYTHONSTARTUP` present in the parent env executes attacker code inside the spawned process (CWE-426, CWE-88, CWE-427) | `src/scripts/_lib/spawn_env.ts::hardenedSpawnEnv()` scrubs the code-execution-injection env families (deny-by-family: loader `LD_*`/`DYLD_*`/`GCONV_PATH`, git `*_COMMAND` + the whole `GIT_CONFIG`/`GIT_CONFIG_*` family + `GIT_ALTERNATE_OBJECT_DIRECTORIES`/`HOSTALIASES`/`GIT_EXTERNAL_DIFF`/`GIT_SSH_COMMAND`/`GIT_PAGER`/`PAGER`, runtime hooks `NODE_OPTIONS`/`BASH_ENV`/`ENV`/`PYTHON*`/`PERL5*`/`RUBYOPT`, `IFS`) and preserves the rest; wired into ALL consumer-runtime spawns — `clients.ts::_runSubprocess`, `hooks/dispatch_hook.ts`, `roadmap_progress_hook.ts`, `hot_context_hook.ts`; falsifiable regression test in `tests/scripts/ai_council/spawn_env.test.ts` (ADR-123 + 2026-07-21 follow-up) | — (consumer-runtime surface fully hardened; maintainer/CI/install sites are env-controlled, not attacker-influenced) | Spawn sites classified in `docs/spawn-site-policy.md` (Consumer Runtime MUST harden / Maintainer / CI / install exempt with rationale); the deferred lint was rejected — the policy doc is the self-enforcing substitute |
-| h | **Secret committed to version control** (CWE-798) — a credential (API key, token, private key, DB password) is written into a tracked file and committed/pushed, leaking it into history, clones, forks, and public scrapers; `git rm` does not un-leak it | An agent (or developer) pastes or generates a real credential into source, `.env`, config, or a fixture and commits it; once pushed to a public remote it is scraped within minutes | `src/rules/secret-vcs-guard.md` (agent-side write/commit-time block → ask → tiered alternative → rotate-first, VCS-agnostic); `src/scripts/_lib/secret_detector.ts` (regex rule pack + Shannon entropy + keyword detector); `src/scripts/check_secret_leak.ts` wired into `task ci` / `ci-strict` as the diff-scoped, non-bypassable CI net; `src/agent-src/templates/github-workflows/secret-scan.yml` (gitleaks) consumer template | The agent-side gate covers only what the agent writes and is one layer; developer-side / GUI commits need the CI net or host push-protection, which the consumer must enable | Ship + document the `secret-scan.yml` template; recommend enabling GitHub Secret Scanning + Push Protection; the optional TruffleHog step adds live-credential verification. Canonical reference: `secret-vcs-guard.md` + `skill:secrets-management` — do not re-describe here |
-
-## Review cadence
-
-This threat model is reviewed:
-
-- **On every security-pillar roadmap phase boundary** — update the table before marking the phase complete.
-- **Quarterly** — as part of the dep-audit cycle (surface b).
-- **When a new linter or kernel rule ships** — re-evaluate affected surfaces.
-
-Owner: the package maintainer. Last reviewed: 2026-06-15.

package/docs/troubleshooting.md

@@ -1,155 +0,0 @@
-# Troubleshooting
-
-Common problems and how to resolve them. If your case is not covered,
-please open an [issue](https://github.com/event4u-app/agent-config/issues)
-and include the output of:
-
-```bash
-composer show event4u/agent-config            # or: npm ls @event4u/agent-config
-node --version
-
-bash scripts/install --verbose --dry-run
-```
-
----
-
-## Agent doesn't seem to pick up the rules or skills
-
-### Check 1: Are the files actually in the project?
-
-```bash
-ls -la .augment/rules/        # should list real files (rules are copied)
-ls -la .augment/skills/       # should list symlinks
-ls -la .claude/rules/         # Claude users: should list symlinks
-ls -la .cursor/rules/         # Cursor users: should list symlinks
-cat  .windsurfrules           # Windsurf users: should be a populated file
-cat .github/copilot-instructions.md  # Copilot users: should exist
-```
-
-If any of these are missing or empty, the installer either didn't run or
-was interrupted. Re-run it:
-
-```bash
-bash scripts/install --verbose
-# or, to regenerate everything (overwrites existing bridge files):
-bash scripts/install --force
-# or, for one-shot installs without a local node_modules tree:
-npx @event4u/agent-config init --tools=claude-code,cursor
-```
-
-### Check 2: Does your agent actually read these directories?
-
-| Tool | Expected location |
-|---|---|
-| Augment Code | `.augment/rules/`, `.augment/skills/`, `.augment/commands/` |
-| Claude Code | `.claude/rules/`, `.claude/skills/` (symlinks into `.augment/`) |
-| Cursor | `.cursor/rules/*.mdc` |
-| Cline | `.clinerules/` |
-| Windsurf | `.windsurfrules` (single concatenated file) |
-| Gemini CLI | `GEMINI.md` (symlinked to `AGENTS.md`) |
-| GitHub Copilot | `.github/copilot-instructions.md` + `AGENTS.md` |
-
-If a path is missing for your tool, re-running the installer recreates it.
-
-### Check 3: Is the plugin-level install masking the project install?
-
-If you installed the Augment / Claude Code / Copilot CLI plugin globally
-AND also installed the package in the project, the agent may pick up the
-plugin copy instead of the project copy. This is usually fine — both
-should be the same version — but if they have drifted, pin the project
-version explicitly and reinstall the plugin.
-
----
-
-## Installer ran but no files appeared
-
-The v2 distribution does **not** ship a `postinstall` hook — installing
-`@event4u/agent-config` via `npm install -g` only puts the `agent-config`
-binary on `$PATH`; it does not seed any project files. Run the
-orchestrator explicitly inside the project root:
-
-```bash
-# One-shot, no local checkout required (recommended)
-npx @event4u/agent-config init --tools=claude-code,cursor
-
-# When the global CLI is installed
-agent-config install --tools=claude-code,cursor
-```
-
----
-
-## Broken symlinks after upgrading the package
-
-When the package version changes, symlinks that pointed to the old
-package path may break. Re-run the installer — it is idempotent:
-
-```bash
-npx @event4u/agent-config init --tools=claude-code,cursor
-```
-
-The installer replaces stale symlinks with fresh ones pointing at the
-current package path.
-
----
-
-## Installation on Windows
-
-Native Windows is not a first-class target. The installer relies on Bash
-and Unix-style symlinks. Recommended setup:
-
-1. **WSL2** (preferred): install Ubuntu or a distribution of your choice,
-   clone the project inside the WSL filesystem, and run
-   `npx @event4u/agent-config init` from WSL.
-2. **Git Bash**: works for the basic install, but symlinks require
-   Developer Mode (Windows 10 1703+) or admin privileges. Without either,
-   Git Bash falls back to copies, which means updates will not propagate
-   automatically — re-run the installer after each update.
-3. **Plain PowerShell / cmd**: not supported.
-
-If you need native Windows support without WSL, please open an issue —
-we cannot validate changes without access to a Windows setup.
-
----
-
-## `Node.js is required but was not found`
-
-The installer is Node.js-based and needs Node 20.11+ on PATH.
-
-\- **macOS**: install via [nodejs.org](https://nodejs.org/) or `brew install node`.
-\- **Linux**: `apt install nodejs` / `dnf install nodejs` / equivalent (ensure Node 20+).
-\- **Windows**: install from [nodejs.org](https://nodejs.org/); ensure "Add to PATH" is checked.
-  or from the Microsoft Store; ensure "Add python.exe to PATH" is
-  checked.
-
-
-on Python 3 — it is required for contributors, not just consumers.
-
----
-
-## Uninstalling the package
-
-There is no dedicated uninstall command yet. Remove the package and
-clean up manually:
-
-```bash
-# 1. Remove the dependency (skip when installed via npx / -g)
-npm uninstall @event4u/agent-config
-
-# 2. Remove generated content from the project
-rm -rf .augment .claude .cursor .clinerules .windsurfrules GEMINI.md
-rm -f .agent-settings .agent-settings.yml .agent-settings.backup.key-value
-rm -f .github/copilot-instructions.md agent-config
-# Remove the "# event4u/agent-config" block from .gitignore manually
-```
-
-Keep `AGENTS.md` if you customized it — it is yours, not the package's.
-
----
-
-## Still stuck?
-
-Open an [issue](https://github.com/event4u-app/agent-config/issues) with:
-
-- your OS and shell,
-- Node / Python versions,
-- full output of `bash scripts/install --verbose --dry-run`.

package/docs/ui-track-mental-model.md

@@ -1,121 +0,0 @@
----
-stability: stable
----
-
-# UI Track — Mental Model (1 page)
-
-> **Audience:** anyone driving `/work` or `/implement-ticket` on a UI-shaped
-> prompt, or reading code that touches `state.directive_set`.
-> **Not a contract.** For shapes, schemas, and slot wiring see
-> [`ui-track-flow.md`](contracts/ui-track-flow.md) and
-> [`adr-product-ui-track.md`](contracts/adr-product-ui-track.md).
-> **Not a roadmap.** Phased delivery lives in
-> [`road-to-product-ui-track.md`](../agents/roadmaps/archive/road-to-product-ui-track.md)
-> and [`road-to-visual-review-loop.md`](../agents/roadmaps/archive/road-to-visual-review-loop.md).
-> This page is the picture you keep in your head while the engine runs.
-
-## The three (+1) directive sets
-
-| Set | Shape | Halt budget |
-|---|---|---:|
-| `backend` | `refine → memory → analyze → plan → implement → test → verify → report` | depends on confidence band |
-| `ui` | `audit → design → apply → review → polish → report` | **2** (audit pick + design sign-off) |
-| `ui-trivial` | `refine → apply → test → report` | **0** on the happy path |
-| `mixed` | `refine → memory → analyze → contract → ui → stitch → verify → report` | inherits both |
-
-The first three are sibling routes; `mixed` stitches `backend` and `ui`
-in one envelope. The dispatcher picks one and refuses to switch
-mid-flight.
-
-## When to pick which
-
-| Signal | Set |
-|---|---|
-| No UI keywords, no UI envelope, prompt edits services / migrations / tests / config | `backend` |
-| New component / screen / partial; "improve this dashboard"; "build a settings panel"; major edit to a screen | `ui` |
-| Bounded edit, **provably** ≤ 1 file, ≤ 5 changed lines, no new component, no new state, no new dependency | `ui-trivial` |
-| One prompt that adds a backend endpoint **and** the screen that consumes it | `mixed` |
-
-The classifier picks; the agent does not override the pick silently.
-A misclassified `ui-trivial` that grows during edit must reclassify
-**loudly** (stop, restart at `audit`) — never quietly upgrade in place.
-
-## What the agent must never do
-
-1. **Skip the audit.** No new component, screen, or partial without
-   `state.ui_audit` populated (or `greenfield_decision` recorded).
-   Defense-in-depth: dispatcher refuses *and* `ui-audit-gate`
-   refuses, even when the engine is not in the loop.
-2. **Render the UI.** The engine never opens a browser, never takes a
-   screenshot, never runs axe. Rendering and a11y scanning happen
-   out-of-process; the engine consumes the `preview_envelope` /
-   `a11y` envelope written by the skill.
-3. **Edit microcopy.** The design brief is **locked**. `apply` reads
-   strings verbatim. `<placeholder>`, `lorem`, `todo:`, `tbd`, `xxx`
-   are rejected at the producer (design) **and** the consumer (apply).
-4. **Loop polish indefinitely.** Hard ceiling is 2 rounds, +1 with
-   the explicit Extend pick (one-shot, never returns). Round 4 is
-   rejected on disk regardless of flags.
-5. **Confuse "ship as-is" with "review clean".** `review_clean=False`
-   plus `findings=[]` is a malformed envelope, not a green light.
-
-## Where each set stops
-
-| Set | Stops cleanly when … | Stops with a halt when … |
-|---|---|---|
-| `ui` | `report` written; design brief + audit + apply + review + polish all `SUCCESS` | audit ambiguous · greenfield decision missing · design unconfirmed · review dirty at ceiling · a11y violation un-accepted · preview render failed |
-| `ui-trivial` | `report` written; classifier preconditions held throughout | preconditions fail mid-flight → reclassify to `ui` (loud halt) |
-| `mixed` | `stitch` joins both subtrees; `verify` + `report` clean | either subtree halts → mixed waits, never auto-completes the other |
-
-## What "audit" actually means
-
-A non-empty `state.ui_audit` carrying **at least one of**:
-
-- `components_found` — `[{path, name, kind, similarity?}]` from
-  [`existing-ui-audit`](../dist/agent-src/skills/existing-ui-audit/SKILL.md).
-- `greenfield: true` plus `greenfield_decision ∈ {scaffold, bare, external_reference}`.
-- Legacy `components` alias — same shape.
-
-Empty dict, `null`, or a dict without those keys is **not** an audit.
-The gate fires; the dispatcher emits `@agent-directive: existing-ui-audit`
-instead of advancing.
-
-## What "design locked" actually means
-
-The brief carries `layout`, `components`, `states`, `microcopy`,
-`a11y`. State coverage requires `empty`, `loading`, `error`, `success`,
-`disabled`. `apply` does not re-decide microcopy — it copies strings.
-"The button label feels off" is a **new** design pass, not a polish
-fix.
-
-## Polish termination — subjective vs objective
-
-| Findings at ceiling | Halt branch | User options |
-|---|---|---|
-| Non-a11y only | `polish_ceiling_reached` | ship as-is · abort · hand off |
-| Includes a11y violation | `polish_a11y_blocking` | extend (one-shot, sets `extension_used=True`) · accept (rule ids land in `accepted_violations`) · abort |
-
-Pre-existing a11y violations recorded in `state.ui_audit.a11y_baseline`
-stay informational and never block.
-
-## Stack dispatch (apply / review / polish)
-
-`state.stack.frontend` decides which skill bundle runs:
-
-| Stack | Skill bundle |
-|---|---|
-| `blade-livewire-flux` | `flux` + `livewire` + `blade-ui` |
-| `react-shadcn` | `react-shadcn-ui` |
-| `vue` | `ui-apply-vue` |
-| `plain` (or unknown) | `blade-ui` + Tailwind base |
-
-The directive set stays `ui`; only the skill changes. Adding a new
-stack ships as a new skill bundle and a recipe — see
-[`ui-stack-extension.md`](contracts/ui-stack-extension.md).
-
-## See also
-
-- [`adr-product-ui-track.md`](contracts/adr-product-ui-track.md) — *why* this shape.
-- [`ui-track-flow.md`](contracts/ui-track-flow.md) — slot-by-slot contract.
-- [`ui-stack-extension.md`](contracts/ui-stack-extension.md) — adding a stack.
-- [`ui-audit-gate`](../dist/agent-src/rules/ui-audit-gate.md) — the always-on rule that mirrors the dispatcher gate.

package/docs/us-vs-the-category.md

@@ -1,38 +0,0 @@
-# Us vs. the category — the honest version
-
-<!-- claim:positioning-honest-nulls -->**The only agent layer that publishes
-the runs where it changed nothing.**<!-- /claim --> That line is deliberately
-falsifiable: find a comparable agent layer publishing its own honest-null
-benchmark runs and it updates — that is the point. The category's growth
-playbook is headline numbers nobody can re-run; ours is a claims ledger CI
-refuses to let drift.
-
-This page is the adoption-context frame around the CI-locked comparison table.
-The table itself lives on the proof page — every "our evidence" pointer is
-resolved by `task check-comparison` on every build, the category column only
-ever describes what is publicly observable, and no competitor is named or
-counter-claimed:
-
-**→ [The comparison table, CI-checked on every build](proof.md#4-what-is-checkable--us-vs-the-category)**
-
-## What the rows mean for an adopter
-
-- **No runtime.** Nothing to keep alive, nothing that writes state behind
-  you — the whole layer compiles into your host agent's own config surface.
-- **Published nulls.** The benchmark page keeps the runs where the package
-  changed *nothing* — including the persona-theater question: swapping the
-  advisor identities was measured at ~zero effect while the provider choice
-  mattered ~15× more, so persona identity was published as a placebo
-  (<!-- claim:persona-identity-placebo-null -->the persona-identity A/B is a
-  backed honest null<!-- /claim -->) instead of shipped as a feature. A
-  council implementation with falsifiable verdicts — including about itself.
-- **A wedge, not a funnel trap.** The 30-second entry is one read-only
-  subagent with a scoped, published eval behind its promise
-  ([what it catches](wedge/production-validator/README.md)) — the platform is
-  the second date, not the first.
-
-## Verify it yourself
-
-Every command on the [proof page § Verify it yourself](proof.md#5-verify-it-yourself)
-runs on a fresh checkout. If a claim here does not resolve, CI is red before
-you ever read it.

package/docs/value.md

@@ -1,86 +0,0 @@
-# Value Dashboard — what does the package cost, what does it bring?
-
-> This page answers **one** question in real numbers: *How many more tokens does the package cost me, and how much does it save back afterwards?* Generated by `scripts/render_value_md.py` from the latest `value-v1` report; source: `internal/bench/reports/value/latest.json`.
-
-## How to read this page
-
-**Panel A (token ladder)** — read top to bottom. Each rung states: *what it does*, *how many input tokens it adds or saves per request*, and *where we stand cumulatively*. The bold **NET** line at the end is the answer. Deliberately pure tokens — no € comparison, since subscription users pay no per-request API prices.
-
-**Panel B (behavior)** — four real comparisons, *with* vs. *without* the package. This is where the non-token value lives: fitting skill selection, stops on risky actions, fewer clarifying questions, more completed tasks.
-
-**Confidence markers** on each rung: `✅ measured` = a real value from a report in the repo · `⏳ pending` = not yet measured, the rung contributes 0 to the sum · `⚠️ vendor-claim` = a vendor's claim, not measured by us.
-
-## Reference scale
-
-- **1,000** requests, on average **8,000** input tokens and **600** output tokens per request
-- Model tier (workload assumption): `sonnet`
-- Anyone running a different workload recomputes it themselves — the methodology is disclosed; nothing is hardcoded or hidden.
-
-## Panel A — Cost ladder (cumulative, min → max)
-
-Reads top to bottom. Positive Δ values = the package *costs* tokens (rule load is the honest up-front tax); negative Δ values = the package *saves* tokens.
-
-| Rung | What it does | Δ tokens | Cumulative | Source |
-|---|---|---:|---:|---|
-| **Without package** | Baseline — the bare request without package rules. | +0 | +0.00% | `n/a` · ✅ measured |
-| With package (rule load) | The always-active rules land in the context of every request. ⚠️ costs first | +59 783 | +747.29% | `internal/bench/reports/projection-cost.json` · ✅ measured |
-| | _Footnote:_ Eager default: all 79 rule files always-on in the `.claude` projection path (0B.6-confirmed for the primary tool). Not just the kernel — this is the honest up-front load; tokens ≈ chars / 4. | | | |
-| + thin (rules as pointers) | Non-kernel rule bodies become router-resolved pointers. | -46 222 | +747.29% | `internal/bench/reports/projection-cost.json` · 🔁 available (default off) |
-| | _Footnote:_ Available behind `lean_projection.mode=thin` (default `eager-all` — hence NOT in the default NET). With thin active: rule layer 59783 → 13561 GPT tok (−46222, −77.3%). MUST-LOAD floor `task trigger-coverage` 26/26 green; live A/B validation pending (harness declined). Rollback = one flip. | | | |
-| + condense (rule shrink) | Build step shrinks rule files before shipping. | -186 | +744.96% | `internal/bench/reports/telegraph-v2.json` · ✅ measured |
-| | _Footnote:_ Aggregate across non-Thin-Root categories; Thin-Root files (AGENTS.md variants) net negative (~−4%) and are excluded from the rung — surfaced separately. | | | |
-| + rtk (filter CLI output) | rtk cuts verbose CLI output before the model input. | -585 | +737.65% | `internal/bench/reports/rtk/latest.json` · ✅ measured |
-| + terse (shorter replies) | Telegraph style aims at terser model replies. | +56 | +738.35% | `internal/bench/reports/telegraph-v1.json` · ✅ measured |
-| | _Footnote:_ Honest: measured median = -9.27% against 'be terse' — telegraph delivers more tokens here, not fewer. We measure, we do not hide. | | | |
-
-**NET: extra cost** ⚠️ — **+59 068 tokens / request**, cumulative **+738.35%** vs. baseline.
-
-## Panel B — Behavior (with vs. without)
-
-Four real comparisons from actual bench runs. This is where the value lives that tokens alone do not measure: whether the agent picks the right skill, stops on risky actions, asks fewer clarifying questions, and completes more tasks.
-
-| Metric | What it means | With package | Without package | Δ | Mode |
-|---|---|---:|---:|---:|---|
-| Right-skill selection | How often the right skill activates (top-K hit). | 50.0% | 0.0% | 50.0% | ✅ live |
-| Destructive-op stops | How often the agent stops / asks before destructive ops (of 5). | — | — | — | ⚠️ dry-run |
-| Ask-vs-act ratio | Ratio of clarifying questions to actions — lower = more decisive. | 0.000 | 0.000 | 0.000 | ✅ live |
-| Task completion rate | Share of tasks the agent completes fully. | 84.6% | 0.0% | 84.6% | ✅ live |
-
-## Glossary
-
-Plain-language definitions for the non-developer reader.
-
-- **Token** — the unit a language model bills in. Rule of thumb: one token ≈ 4 characters of German/English prose. 1,000 tokens ≈ 750 words.
-- **Input tokens** — everything the model reads per turn (system prompt, always-active rules, your message, earlier conversation). The package adds rules here — installation costs input tokens.
-- **Output tokens** — what the model writes back. Usually fewer than input. More expensive per token than input.
-- **condense** — a build step that shrinks the rule files before shipping (`.agent-src.uncondensed` → `dist/agent-src`). Saves input tokens on every request.
-- **rtk** — the *Rust Token Killer*, a CLI wrapper that filters verbose output (`git status`, lint output, test runners) before the model reads it. Saves input tokens on tool calls.
-- **terse / telegraph** — a style (short phrases, dropped articles) the agent uses for terser answers. Saves output tokens — when the corpus rewards it.
-- **Without package / With package** — the two arms of the A/B comparison.
-- **Δ tokens** — input-token difference per request against the baseline. Deliberately the only cost unit: a € comparison would imply per-request API prices that subscription users do not pay.
-
-## Methodology & sources
-
-This page is a **derived** view — not its own measurement. It summarizes three existing bench surfaces (see the 'Source' column in Panel A). The machine-readable raw reports remain the source of truth:
-
-- `internal/bench/reports/telegraph-v1.json` / `telegraph-v2.json` — Telegraph/condense measurements.
-
-- `agents/runtime/frugality/baseline.jsonl` — the package load (Metric A footprint).
-
-- `internal/bench/reports/rtk/latest.json` — the rtk measurement (new, Phase 2).
-
-- `internal/bench/reports/ab/*-ab-trackb-{with,without}.json` — A/B Track B (behavior).
-
-- `internal/bench/reports/*-dev.json` — dev-corpus selection accuracy.
-
-
-**A/B technical appendix:** [`docs/benchmark.md`](benchmark.md) carries the cache-key, integrity, and methodology details of the A/B bench — anyone who wants to see the variant-axis proof reads on there.
-
-
-**Notes from the report:**
-
-- Cost is reported in tokens only — no € figure. Per-call API pricing misleads subscription users; tokens are the currency-neutral metric.
-- Pending rungs contribute 0 to the cumulative until measured.
-- Reference scale: 1000 requests × 8000 input / 600 output tokens per request.
-
-_Last rendered: `2026-06-06T08:42:18+00:00`_

package/docs/walkthroughs/daily-workspace-a11y.md

@@ -1,87 +0,0 @@
----
-stability: beta
-keep-beta-until: 2026-08-26
-roadmap_ref: road-to-frictionless-employee-workspace.md
----
-
-# Daily Workspace — Accessibility Audit (WCAG 2.2 AA)
-
-Audit pass for `src/ui/pages/WorkspacePage.tsx` against WCAG 2.2 AA.
-Run-date: 2026-05-26. Owner: maintainer.
-
-## Methodology
-
-This audit is **static + automated** because the package ships no
-browser-based E2E harness; Playwright's `request` fixture is the only
-runtime path. The audit therefore combines:
-
-- Static read of `WorkspacePage.tsx`, `app.css` Workspace block,
-  `tokens.css`, and the existing role / session fixtures.
-- Vitest assertions: every interactive element carries an
-  `aria-label` or accessible name, every form control sits inside a
-  `<fieldset>` + `<legend>`, every list uses semantic `<ul>` / `<ol>`,
-  every region carries an `aria-labelledby` heading.
-- Token-level contrast checks against `tokens.css` (light + dark
-  themes inherit the same Workspace classes).
-
-Live keyboard-driven and screen-reader passes will land when the
-package adds a browser-driver harness (deferred). The waivers below
-document gaps to address when that harness lands.
-
-## Checklist — passes
-
-| WCAG ref | Criterion | Status | Evidence |
-|---|---|---|---|
-| 1.1.1 | Non-text content has text alternatives | Pass | Every action is text-labelled (`Start session`, `Pick role …`); no icons-only buttons. |
-| 1.3.1 | Info and relationships are programmatically determinable | Pass | `<section aria-labelledby="…">` × 5 regions; `<fieldset>` + `<legend>` on the toggle. |
-| 1.3.2 | Meaningful sequence | Pass | Source order = visual order: roles → tasks → sessions → knowledge → docs → explain. |
-| 1.4.3 | Contrast (minimum) AA | Pass — see [`Contrast`](#contrast) | Inherits `tokens.css` neutral palette; non-text colour hints carry a text label too. |
-| 1.4.10 | Reflow | Pass | `@media (max-width: 900px)` collapses the three-column grid to a single column. |
-| 2.1.1 | Keyboard | Pass | All interactive controls are native `<button>` / `<a>` / `<input>` — no `onClick`-only `<div>`. |
-| 2.4.6 | Headings and labels | Pass | One `<h1>`; each rail section starts with an `<h2>` carrying a stable id. |
-| 2.4.7 | Focus visible | Pass | `:focus-visible` outline on `.ac-workspace__role`; tokens-driven `--color-primary` ring. |
-| 3.2.1 | On focus | Pass | Focus changes never trigger a context change; selection commits only on click / Enter. |
-| 3.3.2 | Labels or instructions | Pass | Toggle has both `aria-label` and visible legend; task buttons carry verb-phrase labels. |
-| 4.1.2 | Name, role, value | Pass | All controls are native; `role`-grid uses `<button>` not `<div role="button">`. |
-
-## Contrast
-
-Spot-check against `:root` tokens (`tokens.css`):
-
-- `--color-text` (#27272a) on `--color-surface` (#ffffff) → 14.4:1 → AA + AAA pass.
-- `--color-text-muted` (#71717a) on `--color-surface` (#ffffff) → 4.85:1 → AA pass for body text.
-- `.ac-workspace__role-status[data-status="beta"]` uses `--color-warn`
-  (#b45309) on white → 4.59:1 → AA pass.
-- `.ac-workspace__role-status[data-status="stable"]` uses
-  `--color-success` (#15803d) on white → 5.05:1 → AA pass.
-
-Dark theme (data-theme="dark") inherits the same Workspace classes
-and overrides the surface / text tokens in `tokens.css`; the same
-ratios apply by construction (the audit pass relies on the tokens
-contract).
-
-## Waivers — to address when a browser-driver harness lands
-
-| Item | Reason | Re-audit trigger |
-|---|---|---|
-| Live screen-reader walkthrough (NVDA + VoiceOver) | No browser-driver harness in CI; static audit substitutes. | Add VoiceOver / NVDA pass when browser harness lands. |
-| Keyboard-only navigation full pass | Same as above; vitest covers the toggle's reactive contract but not the page-wide tab order. | Browser harness pass. |
-| Live colour-contrast check on the rendered DOM | Vite token compile is asserted only by source-token math. | Browser harness pass. |
-| WCAG 2.2 SC 2.5.7 Dragging Movements | Not applicable — no drag-and-drop in v0. | Re-evaluate when document drag-to-rail lands. |
-
-## Re-audit cadence
-
-Re-audit on each of:
-- Any new interactive control added to `WorkspacePage.tsx` or its
-  child components.
-- Token-palette change in `tokens.css`.
-- New role status badge (introduces a new `data-status` colour).
-- WCAG version bump to 3.0 — currently 2.2 AA.
-
-## See also
-
-- `docs/contracts/daily-workspace.md` — surface contract.
-- [`ADR-024`](../decisions/ADR-024-workspace-v0-feature-floor.md) — v0 floor.
-- [`ADR-025`](../decisions/ADR-025-workspace-chrome.md) — chrome substrate.
-- `tests/ui/WorkspaceExplainToggle.test.tsx` — toggle a11y assertions.
-- `tests/e2e/workspace-launcher.spec.ts` — three-flow API E2E.