@event4u/agent-config 7.5.0 → 8.0.0

package/docs/proof.md

@@ -0,0 +1,86 @@
+<!-- GENERATED by src/scripts/build_proof.ts — do NOT hand-edit.
+     Drift-checked in CI (`task build-proof-check`). Regenerate with
+     `./scripts-run src/scripts/build_proof` after editing docs/CLAIMS.md. -->
+
+# Proof — verify our claims yourself
+
+We sell falsifiability, so the selling is machine-checked. Every
+public claim binds to resolvable evidence; a skeptic can reproduce
+every check below on a fresh checkout. This page is itself generated
+from those sources and fails CI if it drifts.
+
+## See it run (< 60s, real output)
+
+![The trust surface running green — every "verify it yourself" command below, recorded from a real run](media/proof-demo.gif)
+
+The recording is of the exact commands in § 5, nothing staged. Its
+commands are re-executed in CI (`.github/workflows/proof-demo.yml`), so a
+demo that showed something broken would turn CI red — the recording
+cannot drift from current behavior.
+
+## 1. Every public claim binds to evidence
+
+Rendered from [`docs/CLAIMS.md`](CLAIMS.md). A `<!-- claim:ID -->` marker in
+README/docs must resolve to a `backed` entry here with a resolving
+evidence pointer, or `task check-claims` fails the build.
+
+| Claim | Kind | Evidence | Resolves |
+|---|---|---|---|
+| On a weak host (claude-haiku-4-5) the package produces a significant, placebo-controlled discipline lift on scope/downstream traps; on a strong host the same measurement is a published null — the package transplants discipline a weak model lacks, not model intelligence. | quant | `docs/benchmark.md#weak-host-specific` | ✅ |
+| The lift-carrying essential cut (kernel + downstream-changes) keeps a significant weak-host discipline lift at a fraction of the full load's tokens, and the lift is FAMILY-SCOPED — full-corpus P1 gate (n=90 pairs): scope/downstream family 0.533→1.000 (7/7 discordant favour essential), other families flat at ceiling, corpus-wide 1.71x tokens; the full load's residual over essential is not significant (p=0.37, n=24). Non-claim on the flip side — the balanced router profile (kernel + tier-1 by size) was removed after measuring a NULL lift (p=0.81, n=24, claude-haiku-4-5, 2026-07-07), and no full-tier recommendation exists anywhere until its own evidence gate passes. | quant | `docs/benchmark.md#Full-corpus P1 gate` | ✅ |
+| The whole layer is compiled into host agents with zero runtime daemon. | qual | `docs/contracts/no-runtime-boundary.md#file-first, no-runtime suite` | ✅ |
+| Removes only its own keys from a shared host config (matched by JSON-pointer + SHA-256), never a neighbour tool's entries. | qual | `docs/contracts/install-layout.md#JSON-pointer` | ✅ |
+
+**4 backed claim(s)** — all evidence pointers resolve in CI.
+
+We also publish our **debt**: 4 claim(s) are logged as
+`unbacked` inventory in the ledger — not yet bound, and therefore not
+allowed to carry a marker in public prose. Hiding them would be the
+opposite of the point.
+
+## 2. We publish honest nulls
+
+Benchmark results — **including the runs where the package changed nothing** —
+live in [`docs/benchmark.md`](benchmark.md). We do not delete a measured null to
+make a number look better; the null is the evidence of honesty.
+
+## 3. Known limits (published, witness-tested)
+
+Each limitation below is stated by the skill itself and carries a witness
+test that reproduces it. If the limitation is ever fixed, its witness goes
+red — so a "Known limit" can never quietly become false.
+
+| skill | known limit | witness |
+|---|---|---|
+| `check-refs` | Only validates references to known-root paths (docs/, skills/, rules/, commands/, contexts/, personas/, …). A relative-path link such as `./sibling.md` or `../foo.md` is not matched, so a broken relative link is never reported. | [`tests/scripts/witness/check_refs_relative_gap.test.ts`](../tests/scripts/witness/check_refs_relative_gap.test.ts) |
+
+## 4. What is checkable — us vs. the category
+
+This is not a takedown — the point is the last column. For each claim,
+our evidence is a pointer you can resolve on a fresh checkout; the wider
+category is described only by what is publicly observable, never a named
+competitor and never a counter-claim to anyone's headline number. A claim
+is "checkable" only when its `our evidence` pointer resolves — CI enforces
+that (`task check-comparison`), so this column can never lie.
+
+| Claim | Our evidence | The category | Checkable? |
+|---|---|---|---|
+| No runtime — no background daemon, no state database, no auto-write memory. | [`docs/contracts/no-runtime-boundary.md#file-first`](../docs/contracts/no-runtime-boundary.md) | Swarm-runtime tools in this category ship a background process and/or a state store by design; that is an architectural fact of the runtime approach, not a defect. | ✅ |
+| Capability/benchmark results are published — including the runs where the package changed nothing. | [`docs/benchmark.md`](../docs/benchmark.md) | A category headline figure (e.g. an '84.8%' score) appears across marketing surfaces with no reproducible methodology published — so it cannot be verified either way. | ✅ |
+| Every public claim binds to machine-checked evidence. | [`docs/CLAIMS.md`](../docs/CLAIMS.md) | Marketing claims in this category are not bound to a machine-checked ledger a reader can reproduce. | ✅ |
+| Skills publish their own known limits, each with a witness test. | [`tests/scripts/witness/check_refs_relative_gap.test.ts`](../tests/scripts/witness/check_refs_relative_gap.test.ts) | Published known-limitation surfaces backed by reproducing tests are not a standard artifact in this category. | ✅ |
+
+## 5. Verify it yourself
+
+On a fresh checkout, reproduce the claims above:
+
+```bash
+task check-claims   # every markered public claim binds to resolvable evidence
+task check-refs     # no broken internal references
+task check-skill-gaps    # every logged known-limit cites a real witness test
+task check-comparison    # every comparison-table "our evidence" pointer resolves
+task build-proof-check   # this page is in sync with its sources
+```
+
+If a claim ever loses its binding, or this page drifts from the ledger,
+CI goes red. Reproducibility is the proof.

package/docs/skills-catalog.md

@@ -3,7 +3,7 @@
 All **251 skills** available in this package, in alphabetical order.
 Click a skill name to open its SKILL.md and read the full guidance.
 
-> **Regenerate:** `python3 scripts/generate_catalog.py`
+> **Regenerate:** `./scripts-run src/scripts/generate_catalog`
 > This file is auto-generated from `SKILL.md` frontmatter — do not edit manually.
 
 | Skill | What your agent learns |

package/docs/troubleshooting.md

@@ -6,8 +6,8 @@ and include the output of:
 
 ```bash
 composer show event4u/agent-config            # or: npm ls @event4u/agent-config
-php --version
-python3 --version
+node --version
+
 bash scripts/install --verbose --dry-run
 ```
 
@@ -111,17 +111,17 @@ we cannot validate changes without access to a Windows setup.
 
 ---
 
-## `Python 3 is required but was not found`
+## `Node.js is required but was not found`
 
-The bridge installer is Python-based and needs Python 3.8+ on PATH.
+The installer is Node.js-based and needs Node 20.11+ on PATH.
 
-- **macOS 12.3+**: Python 3 is pre-installed as `python3`.
-- **Linux**: `apt install python3` / `dnf install python3` / equivalent.
-- **Windows**: install from [python.org](https://www.python.org/downloads/)
+\- **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.
 
-The portability check, condensation pipeline, and test suite also depend
+
 on Python 3 — it is required for contributors, not just consumers.
 
 ---

package/docs/wedge/production-validator/README.md

@@ -0,0 +1,57 @@
+# production-validator — the 30-second Claude Code subagent
+
+A single, self-contained Claude Code subagent that runs the **last gate before
+"done"**: it audits that no mock, stub, fake, `TODO`, or placeholder remains on
+your shipped code, and that the change was actually exercised against a real
+system — not just green tests over hollow code.
+
+One file. No install of anything else. No runtime, no daemon, no account.
+
+## What it does
+
+Before you call a feature done, `@production-validator` greps the shipped path
+(excluding tests/mocks) for hollow implementations, checks that each "done"
+claim has real-system evidence, and returns a `READY` / `NOT READY` verdict with
+`file:line` citations. It reads and runs; it never modifies your code.
+
+## Install (30 seconds)
+
+Drop the one file into your repo's project-level agents directory:
+
+```bash
+mkdir -p .claude/agents
+curl -fsSL https://raw.githubusercontent.com/event4u-app/agent-config/main/docs/wedge/production-validator/production-validator.md \
+  -o .claude/agents/production-validator.md
+```
+
+Or copy [`production-validator.md`](production-validator.md) into
+`.claude/agents/` by hand. That's the whole install.
+
+## Use
+
+In Claude Code, ask for it explicitly or let it auto-delegate before you ship:
+
+```text
+@production-validator check this branch is actually done
+```
+
+Example output:
+
+```text
+production-validator
+  blocker  src/payments/refund.ts:42 — refund() returns a hard-coded {ok:true};
+           no call to the payment provider on the shipped path.
+  must-fix src/payments/refund.test.ts mocks the provider; no integration run
+           exercises the real API.
+  Final gate: NOT READY — refund() is a stub; validate against the real provider.
+```
+
+## Why this one
+
+It carries an anti-hallucination discipline (Evidence-First): "done" is a claim
+until the real path is shown to run. It is read-only and single-purpose, so it is
+safe to try on any repo in one command.
+
+Part of [`event4u/agent-config`](../../../README.md) — a governed skill / rule /
+persona layer for AI coding agents. This subagent is the standalone wedge; the
+full suite adds the router, orchestration, and governance around it.

package/docs/wedge/production-validator/production-validator.md

@@ -0,0 +1,56 @@
+---
+name: production-validator
+description: Use before declaring a feature done or a PR ready. Audits that no mock, stub, fake, TODO, or placeholder remains on the shipped (non-test) path and that the change ran against real systems — not just green tests over hollow code.
+tools: Read, Grep, Glob, Bash
+model: inherit
+---
+
+You are the **Production Validator** — the last gate before "done".
+
+Your single question: **is the shipped code real, or does a green test hide a stub?**
+A passing test suite is a claim, not proof. Your job is to confirm the
+implementation under the test actually exists and ran against a real system.
+
+## What you hunt
+
+- `mock`, `stub`, `fake`, `spy`, or in-memory doubles that leaked onto a
+  **non-test** (shipped) code path.
+- `TODO`, `FIXME`, `NotImplemented`, `raise NotImplementedError`, `throw new
+  Error("not implemented")`, `pass`, or empty function bodies on the shipped path.
+- Hard-coded fixture values returned from production code (a function that always
+  returns the same canned result regardless of input).
+- Features whose only validation is against mocks — never against the real
+  dependency (DB, HTTP API, queue, filesystem, external service).
+
+## How you work
+
+1. Scope to the shipped diff/paths under review — exclude `test`, `tests`,
+   `spec`, `__tests__`, `*.test.*`, `*.spec.*`, fixtures, and mocks directories.
+2. Grep the shipped path for the markers above (`mock|stub|fake|TODO|FIXME|
+   NotImplemented|placeholder`). For each hit, decide: real code, or hollow?
+3. For each "done" claim, find evidence the real path executed — a run against a
+   real dependency, an integration test hitting the real system, or a manual
+   trace. Green unit tests over mocks are **not** that evidence.
+4. Apply the removal test: *if every test double were deleted, would this feature
+   still function end-to-end?* If no, it is not done.
+
+## What you do NOT do
+
+- You do not judge whether the tests are well-designed or the coverage is
+  sufficient — that is a QA concern, not yours.
+- You do not review performance, style, or architecture.
+- You do not modify code. You read, grep, run to verify, and report.
+
+## Output
+
+Report a short verdict:
+
+- **Severity** per finding: `blocker` (a hollow implementation on the shipped
+  path, or a "done" claim with no real-system validation) · `must-fix` · `note`.
+- **Evidence**: cite `file:line` for every mock/stub/placeholder or the exact
+  gap in real-system validation.
+- **Final gate line**: `READY` only if no blockers remain and the real path is
+  shown to run; otherwise `NOT READY — <one-line reason>`.
+
+A single confirmed hollow path on shipped code is a `blocker`, never a nit.
+When in doubt, withhold `READY` and name what evidence is missing.

package/docs/wizard.md

@@ -118,7 +118,7 @@ is unaffected.
 
 Suppress the auto-launch with `--no-ui`, `AGENT_CONFIG_NO_UI=1`, or
 by running in CI (`CI=1`). Preview the gate verdict without
-installing anything via `python3 scripts/install.py --dry-run`,
+installing anything via `npx @event4u/agent-config install --dry-run`,
 which prints a plan summary and exits 0 with zero filesystem
 writes.
 
@@ -147,7 +147,7 @@ With the GUI suppressed, pass profile + pack on the command line —
 `npx -y @event4u/agent-config init --no-ui --profile=developer
 --pack=engineering-base` — or hand-edit `.agent-settings.yml`
 directly. Preview the gate verdict and the planned writes with
-`python3 scripts/install.py --dry-run` (zero filesystem writes,
+`npx @event4u/agent-config install --dry-run` (zero filesystem writes,
 exits 0). Settings can still be hand-edited at any time; the GUI
 is opt-in, not required.
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@event4u/agent-config",
-    "version": "7.5.0",
+    "version": "8.0.0",
     "description": "Universal AI Agent OS — audited skills, governance rules, commands, and templates for AI coding tools (Claude Code, Cursor, Windsurf, Copilot).",
     "license": "MIT",
     "private": false,

package/src/config/agent-settings.template.yml

@@ -52,8 +52,53 @@ profile:
 # tree (.augment/) always project the full set in 6.0.0.
 projection:
   mode: legacy-all
-
-# --- Cost profile ---
+  # --- Consumer-scoped RULE projection (road-to-request-scoped-rule-load P1,
+  #     opt-in) ---
+  # Workspace scope for the RULE layer only (independent of `mode` above,
+  # which covers skills/commands). Absent or empty = legacy-all: every rule
+  # projects, exactly as today. Non-empty = only rules whose `workspaces:`
+  # frontmatter intersects this list project into .claude/rules,
+  # .cursor/rules, .windsurf/rules, .clinerules and .windsurfrules. Kernel
+  # rules ALWAYS project (unconditional by definition); untagged rules fail
+  # safe and ship. Example consumer scope:
+  #   rule_workspaces: [engineering]
+  # Default flip to a scoped value is a human release gate — see
+  # agents/settings/contexts/consumer-scoping-audit-2026-07-07.md.
+  # rule_workspaces: []
+  #
+  # Optional second axis, same semantics per pack ids (packs.yml). When set,
+  # a non-kernel rule also needs a `packs:` intersection to project — e.g.
+  # deselecting `frontend-design` removes ui-audit-gate + design-fidelity.
+  # rule_packs: []
+
+# --- Discipline profile (successor knob, opt-in until the evidence gates pass) ---
+#
+# The ONE runtime knob for the discipline-rule tier (council verdicts
+# 2026-07-07: weak-host-lift-tiering + token-program-integration). Measured
+# on claude-haiku-4-5 (docs/benchmark.md § Cost-factor sweep):
+#
+# off       = kernel only (9 Iron-Law rules, ~1x tokens). For hosts with a
+#             MEASURED null lift (src/config/host-capabilities.yml).
+# essential = kernel + the lift-carrying rules (downstream-changes;
+#             scope-control is already kernel). ~3.3x tokens, keeps a
+#             significant discipline lift (+0.458, p=0.0135) — the full
+#             package's residual over it is not significant (p=0.37).
+# full      = every rule tier (~11.7x tokens). EXPERIMENTAL opt-in only:
+#             residual lift over essential not established.
+# auto      = resolve per session against host-capabilities.yml — model on
+#             the measured NULL-lift list -> off, otherwise -> essential.
+#
+# This key WINS over the legacy `rule_loading_tier` below (mapping when
+# absent: minimal->off, balanced->essential, full->full, custom->custom).
+# The installer fills the placeholder per preset with the value that
+# preserves each preset's prior behaviour (minimal->off,
+# balanced->essential, full->full) — same resolution as the legacy
+# mapping, no behaviour change. The flip of the shipped default to
+# `auto` is evidence-gated (P2 non-Claude replication, see
+# agents/roadmaps/road-to-discipline-profile-tiering.md).
+discipline_profile: __DISCIPLINE_PROFILE__
+
+# --- Cost profile (legacy knob — superseded by discipline_profile above) ---
 #
 # Master switch that controls which rule tiers load each session.
 # See docs/customization.md for the authoritative description and
@@ -100,7 +145,7 @@ lean_projection:
 #
 # Configurable in the browser setup wizard (Setup → Skills → Token budget).
 tokens:
-  rich_skills: on
+  rich_skills: "on"
 
 # --- Cost tracking + budget enforcement ---
 #
@@ -320,6 +365,16 @@ reasoning:
 # in the same response — that cadence is governed by `roadmap-progress-sync`
 # and is non-negotiable. This setting only governs *quality tool runs*.
 roadmap:
+  # PER-ROADMAP OVERRIDE NOTE — `execution.mode` frontmatter
+  # (autonomous | phase-checkpoints | interactive, per
+  # templates/roadmaps.md rule 18) changes ONLY the run's interaction
+  # pattern: which asks are batched into the run-start execution
+  # contract and where checkpoint prompts fire. It overrides NONE of
+  # the keys below — `skip_pre_run_gate`, `quality_cadence`, and
+  # `dashboard_regen_cadence` keep their global meaning in every mode,
+  # and no mode lifts a safety floor. See
+  # contexts/execution/roadmap-execution-contract.md.
+
   # Skip the /roadmap:process-* pre-run confirmation gate (true, false).
   #   true  = default. The command name names the scope; a discoverable
   #           single active roadmap (or a named one) starts the loop
@@ -853,6 +908,6 @@ legal_review_prep:
 # key. Keep the key in your user-global settings so encrypted provenance stays
 # recoverable across fresh clones.
 #
-# Generate one:  python3 src/scripts/_lib/link_crypto.py keygen
+# Generate one:  ./scripts-run src/scripts/_lib/link_crypto keygen
 # secrets:
 #   link_encryption_key: "<paste generated key here>"

package/src/config/agents-paths.yml

@@ -0,0 +1,254 @@
+# Ignore/track classification manifest for agent-config managed paths.
+#
+# Consumed by:
+#   - scripts/generate_gitignore_block.ts  → src/config/gitignore-block.txt
+#   - scripts/check_gitignore_freshness.ts → CI drift gate (Phase 3.4)
+#   - scripts/lint_agents_layout.ts        → cross-checks policy labels
+#
+# Fields:
+#   path     - the ignore pattern (gitignore syntax)
+#   scope    - package (source repo only) | consumer | both
+#   policy   - tracked | tracked-generated | ignored | carve-out | legacy
+#   writer   - the script / skill / human that creates this path (for audit)
+#   rationale - one-line justification
+#   legacy   - true: add to LEGACY_PATTERNS in sync_gitignore.ts for cleanup
+#   comment  - optional comment block to emit above the pattern in the gitignore
+
+# ---------------------------------------------------------------------------
+# Settings files
+# ---------------------------------------------------------------------------
+
+- path: .agent-settings.yml
+  scope: both
+  policy: ignored
+  writer: installer (scripts/install.py)
+  rationale: Per-user active settings; contains local-path secrets
+
+- path: .agent-settings
+  scope: both
+  policy: ignored
+  writer: installer (legacy flat format, pre-YAML migration)
+  rationale: Legacy flat key=value settings; migrated on first wizard run
+  legacy: true
+
+- path: .agent-settings.backup.key-value
+  scope: both
+  policy: ignored
+  writer: installer (migration backup)
+  rationale: One-shot backup during settings migration; safe to delete after
+  legacy: true
+
+- path: .agent-settings.local.yml
+  scope: both
+  policy: ignored
+  writer: developer (manual)
+  rationale: Machine-local overrides that must never be shared
+
+# ---------------------------------------------------------------------------
+# User persona + observation buffer
+# ---------------------------------------------------------------------------
+
+- path: .agent-user.md
+  scope: both
+  policy: ignored
+  writer: /agents:user:init skill
+  rationale: Personal user identity; local-only by default (shared opt-in deferred)
+  comment: |
+    # Agent config — user-persona file (.agent-user.md, written by /agents user init)
+    # Contains who the user is and how they want to be addressed. Local-only by
+    # default; commit explicitly only via the deferred --shared opt-in.
+    # See docs/contracts/agent-user-schema.md.
+
+- path: .agent-user.md.bak
+  scope: both
+  policy: ignored
+  writer: installer (backup)
+  rationale: Safety backup during persona migration
+
+- path: .agent-user.observations.jsonl
+  scope: both
+  policy: ignored
+  writer: /agents:user:review skill
+  rationale: Append-only raw observation buffer; never shared
+  comment: |
+    # Agent config — user-persona observation buffer (append-only JSONL,
+    # never shared). Feeds /agents user review / accept only.
+
+# ---------------------------------------------------------------------------
+# Memory intake (gitignored; curated YAML subsets are committed)
+# ---------------------------------------------------------------------------
+
+- path: /agents/memory/intake/
+  scope: both
+  policy: ignored
+  writer: /memory:mine-session skill
+  rationale: Raw low-confidence intake; promotion to committed YAML is human-gated
+  comment: |
+    # Agent config — raw memory intake (append-only, low-confidence, agent-written
+    # by /memory mine-session). Local scratch only — commit ONLY the curated YAML
+    # promoted out of it (agents/memory/<type>/*.yml stays tracked).
+
+- path: /agents/memory/ephemeral/
+  scope: both
+  policy: ignored
+  writer: Evidence v2 project-intelligence pipeline (contexts/execution/project-intelligence.md)
+  rationale: Per-session trial-and-error observations; TTL managed; never promoted
+
+# ---------------------------------------------------------------------------
+# Knowledge intake (gitignored; committed pages live in agents/knowledge/)
+# ---------------------------------------------------------------------------
+
+- path: /agents/knowledge/intake/
+  scope: both
+  policy: ignored
+  writer: /team-knowledge:consolidate skill
+  rationale: Append-only JSONL events; consolidated into committed pages on human review
+  comment: |
+    # Agent config — typed knowledge-observation events (append-only JSONL).
+    # Consolidated via /team-knowledge consolidate into committed pages under
+    # agents/knowledge/{sessions,concepts,procedures,decisions}/.
+
+- path: /agents/.bootstrap-staging/
+  scope: both
+  policy: ignored
+  writer: /team-knowledge:bootstrap skill
+  rationale: Deterministic template pages; review-then-commit flow (nothing here is the artifact)
+
+# ---------------------------------------------------------------------------
+# Ghostwriter profiles
+# ---------------------------------------------------------------------------
+
+- path: /agents/ghostwriter/*.md
+  scope: both
+  policy: ignored
+  writer: /ghostwriter:fetch skill
+  rationale: Real-person voice profiles; local-only by default; shared opt-in deferred
+  comment: |
+    # Agent config — ghostwriter profiles (real-person public-figure voices).
+    # Local-only by default; commit explicitly only via the deferred --shared opt-in.
+    # See docs/contracts/ghostwriter-schema.md.
+
+- path: "!/agents/ghostwriter/README.md"
+  scope: both
+  policy: carve-out
+  writer: maintainer
+  rationale: README is tracked and ships with the package
+
+- path: /agents/ghostwriter/*.md.bak
+  scope: both
+  policy: ignored
+  writer: /ghostwriter:fetch skill (backup)
+  rationale: Safety backup during profile updates
+
+# ---------------------------------------------------------------------------
+# Chat history (legacy path; current installs use agents/runtime/)
+# ---------------------------------------------------------------------------
+
+- path: /agents/.agent-chat-history
+  scope: both
+  policy: ignored
+  writer: scripts/chat_history.py (legacy flat path)
+  rationale: Legacy location; current installs write to agents/runtime/.agent-chat-history
+  legacy: true
+
+- path: /agents/.agent-chat-history.bak
+  scope: both
+  policy: ignored
+  writer: scripts/chat_history.py
+  rationale: Crash-recovery backup; local-only
+  legacy: true
+
+- path: /agents/.agent-chat-history.*.bak
+  scope: both
+  policy: ignored
+  writer: scripts/chat_history.py
+  rationale: Timestamped backup variants; local-only
+  legacy: true
+
+# ---------------------------------------------------------------------------
+# Telemetry
+# ---------------------------------------------------------------------------
+
+- path: .agent-engagement.jsonl
+  scope: both
+  policy: ignored
+  writer: ./agent-config telemetry:record
+  rationale: Artefact engagement telemetry; default-off; maintainer-only
+  comment: |
+    # Agent config — artefact engagement telemetry (default-off, maintainer-only, never commit)
+
+- path: .agent-engagement.jsonl.bak
+  scope: both
+  policy: ignored
+  writer: ./agent-config telemetry:record (backup)
+  rationale: Telemetry log backup
+
+# ---------------------------------------------------------------------------
+# Volatile runtime (entire tree)
+# ---------------------------------------------------------------------------
+
+- path: /agents/runtime/
+  scope: both
+  policy: ignored
+  writer: multiple scripts (council, chat-history, metrics, hooks, mcp-telemetry, etc.)
+  rationale: All volatile session/TTL artefacts; single catch-all per the Volatile Runtime policy
+  comment: |
+    # Agent config — volatile runtime artefacts (machine-generated,
+    # regenerated on demand, never committed). Single catch-all per the
+    # Volatile Runtime policy: everything under agents/runtime/ is
+    # local-only — price cache, council questions/responses/sessions,
+    # council events log, Tier 1 hook runtime state, chat-history, budget
+    # history, density / frugality / logs / mcp-telemetry / tmp scratch.
+    # Durable evidence cited from docs / ADRs lives in agents/evidence/;
+    # decision records in agents/decisions/.
+
+# ---------------------------------------------------------------------------
+# Hook + wizard runtime state
+# ---------------------------------------------------------------------------
+
+- path: /agents/state/
+  scope: both
+  policy: ignored
+  writer: hooks (context_hygiene_hook.py, etc.) + GUI wizard
+  rationale: Per-rule hook state and wizard resume snapshot; local-only per Volatile Runtime policy
+  comment: |
+    # Agent config — Tier 1 hook + wizard runtime state (machine-generated,
+    # regenerated on demand, never committed). Holds the dispatcher lock,
+    # per-rule hook state, and the GUI wizard resume snapshot.
+
+# ---------------------------------------------------------------------------
+# User inbox (agents/tmp) and processed archive (agents/tmp.old)
+# ---------------------------------------------------------------------------
+
+- path: /agents/tmp/
+  scope: both
+  policy: ignored
+  writer: user (human)
+  rationale: |
+    User inbox — user drops notes/todos; agent reads + moves to tmp.old/ on
+    consumption. Agent scratch never goes here. See docs/contracts/agents-layout.md § User Inbox Workflow.
+  comment: |
+    # Agent config — user inbox (free-form notes/todos for the agent to consume).
+    # User-owned; never auto-swept by the janitor.
+    # Agent scratch → agents/runtime/tmp/ (NOT this dir).
+    # See docs/contracts/agents-layout.md § User Inbox Workflow.
+
+- path: /agents/tmp.old/
+  scope: both
+  policy: ignored
+  writer: agent (moves consumed tmp/ files here)
+  rationale: Processed inbox archive; TTL 30 days (janitor sweeps); never contains agent scratch
+  comment: |
+    # Agent config — processed inbox archive. The agent moves consumed tmp/ files
+    # here after processing (roadmap created, note promoted, etc.).
+    # Janitor TTL: 30 days. See docs/contracts/agents-layout.md § User Inbox Workflow.
+
+# ---------------------------------------------------------------------------
+# Wizard partial state
+# ---------------------------------------------------------------------------
+
+- path: /.agent-config/wizard-state.json
+  scope: both
+  policy: ignored
+  writer: Fastify wizard server (POST /api/v1/wizard/state)
+  rationale: Step-transition crash-recovery; deleted on wizard finish; local-only

package/src/config/budgets.yml

@@ -0,0 +1,16 @@
+# Consumer-tool load-budget caps for this package's projections.
+#
+# Single source of truth for the budget gates — scripts read these values
+# instead of hard-coding them (measure_augment_budget, and any future
+# per-tool budget meter).
+
+augment_workspace_guidelines:
+  # Verified platform maximum: 99,024 chars (re-measured 2026-07; the old
+  # 49,512 ceiling from the 2026-05-08 baseline is obsolete). We deliberately
+  # gate against a LOWER internal cap to keep headroom for consumer-side
+  # additions and future rules — raise total_cap_chars only as needed, and
+  # NEVER above platform_max_chars.
+  platform_max_chars: 99024
+  total_cap_chars: 64000
+  warn_threshold: 0.85
+  fail_threshold: 0.95

package/src/config/discovery/packs.yml

@@ -304,6 +304,7 @@
   label: Meta
   description: Artefacts that maintain this package (agent-config itself).
   workspaces: [agent-config-maintainer]
+  requires: [engineering-base]  # reasoning-orchestrator (meta) invokes adversarial-review (engineering-base)
   trust_level_default: core
   domain: meta
   size_class: core

package/src/config/discovery/unassigned-artefacts.yml

@@ -36,6 +36,8 @@
   reason: scaffold for project deployment-order context
 - path: src/agent-src/templates/contexts/knowledge-card.md
   reason: fill-in skeleton for committed knowledge cards (evidence-first structure discovery / ADR-098); frontmatter is the example shape a filled card carries, not a runtime artefact
+- path: src/agent-src/templates/contexts/knowledge-pages.md
+  reason: convention doc for the typed agents/knowledge/ page directories (road-to-knowledge-system); documents the optional page frontmatter shape, carries none itself
 - path: src/agent-src/templates/contexts/lesson-card.md
   reason: fill-in skeleton for Class-C learned lessons (Evidence v2 project-intelligence); frontmatter is the example shape a filled lesson carries, not a runtime artefact
 - path: .agent-src.uncondensed/templates/contexts/observability.md