@event4u/agent-config 7.5.0 → 8.0.0

package/docs/decisions/ADR-109-subagent-v1-contract.md

@@ -0,0 +1,246 @@
+---
+adr: 109
+status: accepted
+date: 2026-07-04
+decision: subagent-v1-contract
+supersedes: —
+superseded_by: —
+phase: road-to-final-state-and-market-readiness
+type: standing
+---
+
+# ADR-109 — The `subagent-v1` contract (new discovery category, default-off, static projection)
+
+## Status
+
+**Accepted** · 2026-07-04 · maintainer decision after an AI-council debate
+(claude-sonnet-4-5 + gpt-4o, 2 rounds). Track A keystone (A1) of
+`road-to-final-state-and-market-readiness.md`.
+
+## Context
+
+Track A adds a **capability** layer: named subagent units that a host can invoke
+as distinct, tool-scoped execution contexts (Claude Code's `.claude/agents/`).
+The wedge — `production-validator` — already ships hand-written in that native
+format. A1 turns that one hand-written file into a governed, projected artifact
+type without breaching the no-runtime identity floor (no daemon, no auto-write,
+no in-process swarm, no dispatch we enforce).
+
+The council was asked to converge the contract shape. Both members agreed on the
+category and the schema completeness; the residual dissent was a documentation
+nuance (don't over-claim cross-host equivalence), folded in below.
+
+## Decision
+
+### 1. A new discovery category `subagent` (not `agent`, not a persona subtype)
+
+- **Name `subagent`.** `agent` is overloaded (the host is "the agent"; this
+  package is "agent-config"). `subagent` = a subordinate, delegated, addressable
+  execution context.
+- **A distinct category, not a persona subtype.** Personas are reference lenses
+  projected as *context* for a single session; a subagent is an *addressable
+  execution context* with its own tool manifest and model. Folding subagents into
+  personas would force every persona to grow a `tools` field it ignores, or add
+  subtype-specific projection logic (a parallel schema inside one category). The
+  categories today are `['skill', 'rule', 'command', 'template']`; `subagent`
+  becomes the 5th.
+
+### 2. Source schema `subagent-v1` (governance fields REQUIRED, not optional)
+
+```yaml
+schema_version: subagent-v1
+name: <handle>                      # REQUIRED — matches filename stem, addressable
+description: <one line>             # REQUIRED — user-facing summary
+model_tier: high|medium|lite|inherit  # REQUIRED — reuses model_tier.ts; `inherit` is a
+                                      #   documented passthrough sentinel (→ CC `model: inherit`),
+                                      #   NOT a new tier→model mapping
+tools: [Read, Grep, Glob, Bash, …]  # REQUIRED — enum-validated against the CC tool set
+trust: {level, confidence, human_review_required}  # REQUIRED — mirrors the skill trust block (ADR-013)
+lifecycle: active|deprecated|experimental|archived # REQUIRED — reuse the existing lifecycle enum
+discovery:
+  visible: false                    # REQUIRED — default-off; linter enforces `false`
+  requires_capability: <cap>        # REQUIRED — host-capability gate (e.g. claude_subagents)
+  categories: [<tag>, …]            # OPTIONAL — pack-include tags
+```
+
+Body: a free-form Markdown system prompt (like personas). Governance fields are
+**required** — optional governance would create a two-tier system (governed
+legacy artifacts vs. ungoverned subagents), which breaks trust filtering and the
+"governed config layer" promise. The source carries governance metadata that
+does **not** project to `.claude/agents/` (CC has no such fields) but does drive
+discovery filtering, docs generation, and cross-host warnings.
+
+**Banned fields (would imply runtime we do not have):** `auto_invoke_on`,
+`max_iterations`, `timeout`, `cost_limit`, `memory_strategy`, `delegates_to`.
+
+### 3. Native-Claude-Code translation
+
+Projected file: `.claude/agents/<name>.md` with frontmatter `{name, description,
+tools, model}` + the body. `model` is derived from `model_tier` by **reusing**
+`src/scripts/_lib/model_tier.ts` (`TIER_TO_CLAUDE_MODEL`: high→opus, medium→sonnet,
+lite→haiku); `model_tier: inherit` projects to `model: inherit` (passthrough).
+No new mapping is invented (ADR-034/035 stands).
+
+### 4. Cross-host degradation (host-agnostic, honestly limited)
+
+Only Claude Code has native subagents. Elsewhere a subagent projects to a
+**loadable context file**, gated by `requires_capability`:
+
+| Host | Projection | Invocation |
+|---|---|---|
+| Claude Code | `.claude/agents/<name>.md` | `@<name>` (host-native) |
+| Cursor / Windsurf / Cline | context file the host can load on intent | manual — **no `@`-dispatch** |
+| Copilot / Gemini | skipped (no context surface) | — |
+
+**Honest limitation (published, per the package's own honesty floor):** on
+non-Claude-Code hosts the artifact degrades to *passive reference* — the system
+prompt is available, but there is no host-native dispatch. This is **governance
+parity, not feature parity**: trust / lifecycle / model-tier apply uniformly; the
+automation does not. We do not fake dispatch (that would need a runtime we refuse
+to add).
+
+**Implementation (`generate_subagent_host_contexts`, condense.ts).** The non-CC
+projection emits a passive-reference context file carrying the honest no-dispatch
+banner + a governance block (trust level / lifecycle / model tier / tools) + the
+body verbatim, reaper-safe per host:
+
+- Cursor → `.cursor/subagents/<name>.md`; Windsurf → `.windsurf/subagents/<name>.md`
+  (dedicated subdir with its own reaper — no collision with the aggressive
+  `_clean_modern_dir` rule reapers).
+- Cline → `.clinerules/<name>.subagent.md` (a real file; that dir's reaper only
+  unlinks symlinks, so it survives).
+- Copilot / Gemini → skipped (no per-file context surface).
+
+Council (claude-sonnet-4-5 + gpt-4o, 2026-07-05) converged on *project the file*
+over honest-null: the body is ~95% reusable review discipline and ~5% dispatch
+syntax, so an advanced user loads it on intent and applies the discipline
+manually. No ADR amendment was needed — this realises the §4 table as written.
+
+### 5. Default-off + non-dispatch (mechanical)
+
+- **Default-off** = `discovery.visible: false` (required; linter enforces the
+  value is `false`). No glob pulls subagents; a pack opts in explicitly via
+  `include: ["subagent:<name>"]` or `include: ["subagent:category:<tag>"]`.
+- **Non-dispatch is free.** We have no runtime; we only project a file. The host
+  (or the user via `@<name>`) decides invocation. No `auto_dispatch` flag exists
+  (it would imply `true` is possible — it is not).
+
+### 6. Determinism / lint guarantees (part of A1)
+
+- `tools` validated against the CC tool enum — build-time failure, never a broken
+  `.claude/agents/` YAML in the user's IDE.
+- `model_tier` validated against `model_tier.ts` (+ the `inherit` sentinel).
+- `name` globally unique within the `subagent` category (projection-path
+  collision guard), matching the filename stem.
+- `discovery.visible` must be present and `false`.
+
+### 7. Explicitly cut from v1
+
+Multi-subagent orchestration (`delegates_to`), custom tool definitions, and
+per-artifact `supported_hosts` lists (use `requires_capability` + a central
+capability matrix instead). Revisit only in a `subagent-v2` if evidence demands.
+
+## Consequences
+
+- A 5th discovery category, one new schema, one source location (`src/subagents/`),
+  a translation step, and lint rules — all additive; existing categories untouched.
+- `production-validator` becomes the first `src/` subagent unit and the single
+  source of truth for the wedge (the hand-written `docs/wedge/` copy is superseded
+  by projection).
+- **Gate A still governs shipping:** a unit is default-off and ships as
+  recommended-opt-in **only** if the A3 eval (on `internal/bench/orchestration/`)
+  beats both baselines at acceptable token cost; otherwise it stays in `src/` as a
+  documented honest-null. This ADR defines the *contract*, not a promotion.
+
+## Alternatives considered
+
+- **Persona subtype** — rejected: semantic dilution + schema creep (tools field on
+  all personas, or subtype-specific projection).
+- **Optional governance fields** — rejected: creates ungoverned-by-default
+  artifacts, breaking the trust model (council round 2, decisive).
+- **CC-only (no degradation)** — rejected: violates host-agnostic positioning; a
+  CC-locked artifact is Claude Code config that wandered into the repo.
+- **Faked dispatch on non-CC hosts** — rejected: runtime cosplay we cannot honor.
+
+## Amendment 1 (2026-07-04) — discovery-manifest integration = Option B
+
+The original decision left *how* subagents join the discovery manifest open. A
+follow-up council (claude-sonnet-4-5 + gpt-4o, 2 rounds) surfaced the concrete
+gap: the manifest's `_classify` requires `workspaces` / `packs` / `install`,
+which this contract's minimal schema deliberately omits. Both members converged
+on **Option B**:
+
+- Add `subagent` to `_CATEGORY_VALUES` + `_CATEGORY_SCHEMA` + the `_iter_artefacts`
+  glob (`src/subagents/*.md`), and give `_classify` a **subagent branch** that
+  derives the manifest payload from the subagent-v1 fields:
+  `install: {default: false, removable: true}` (default-off), `packs: []`,
+  `workspaces: []`, plus `lifecycle` + `trust`.
+- **`packs: []` is legitimate** — "recommended for no pack; included only via
+  `include: ["subagent:<name>"]`". The "every artefact belongs to ≥1 pack"
+  invariant becomes "every artefact **except subagents**". Verified safe: every
+  manifest consumer of `.packs` already guards against empty
+  (`check_condensation`, `install`, `condense`, `lint_trust_coherence`), and
+  `lint_artefact_frontmatter` does not scan `src/subagents/`.
+- The `discovery-manifest.schema.json` `category` enum + `by_category` gain
+  `subagent`; the `workspaces`/`packs` `minItems: 1` is relaxed to a documented
+  note (non-emptiness for real categories stays enforced by `_classify`).
+
+**Rejected:** Option A (extend the schema with workspaces/packs/install →
+duplicate visibility source, de-facto ADR reversal) and Option C (keep subagents
+out of the manifest + a parallel name-resolver → duplicate load/parse/validate
+pipeline; LSP/tooling would need two discovery paths). "5th discovery category"
+is manifest terminology, so Option B satisfies A1 literally.
+
+The manifest (`dist/discovery/discovery-manifest.json`) is a **gitignored** build
+artifact — CI rebuilds it fresh, so this is a generator + schema change, not a
+committed-data change.
+
+## Amendment 2 (2026-07-05) — consumer distribution = wedge-only (A2)
+
+How subagents reach **consumers** (as opposed to the in-repo `.claude/agents/`
+projection): a fresh council (**claude-fable-5 + gpt-4o**, 2 rounds) converged on
+**wedge-only distribution**, reversing an earlier "synthesis" lean once the
+implementation blast-radius evidence was in hand.
+
+- **Decision:** subagents reach consumers ONLY via the wedge
+  (`docs/wedge/<name>/<name>.md`, shipped in npm `files[]` via `docs/`, installed
+  by a 30-second `curl` into `.claude/agents/`). They are **not** condensed to
+  `dist/`, **not** in the install bundle, and **not** in the shared source
+  enumeration (`_root_specs()` / `iter_all_sources` / `resolve_logical`).
+- **Why not ship in dist (the rejected synthesis):** `condense.cleanup_stale()`
+  deletes any `dist/agent-src/` file that does not round-trip through
+  `resolve_logical()`, so shipping subagents in dist requires teaching the shared
+  `_root_specs()` about them — a cross-cutting change to ~10 consumers
+  (`build_discovery_manifest`, three frontmatter/pack linters, namespace checks,
+  …). Exclusion-based containment would produce a **shipped-but-ungoverned**
+  executable-prompt class — for a *governed* config layer, worse than the blast
+  radius it hides. Marginal consumer value at n=1 unit ≈ one fewer curl for an
+  opt-in, high-trust artifact — not worth it. Revisit only at n≥3 units **and** a
+  documented curl-distribution failure signal.
+- **The wedge doc is now a projection of `src/subagents/`** (superseding the
+  hand-written copy), regenerated from `generate_claude_subagents()` so the two
+  channels cannot drift.
+
+**A2 install-completeness gate** (`tests/scripts/subagent_distribution.test.ts`):
+wedge↔src projection fidelity (no drift); coverage (every unit has a wedge doc);
+and negative-wiring locks — `resolve_logical('subagents/…')` is null, no
+`subagents/` path in `iter_all_sources`, the installer references no
+`dist/agent-src/subagents`, and `dist/agent-src/subagents/` does not exist. No
+byte-budget check (an arbitrary threshold on a system prompt is cargo-cult).
+
+*(Council side-fix: `AnthropicClient` extracted only `content[0].text`, dropping
+extended-thinking models' output — claude-fable-5 returned 3191 output tokens as
+empty text. Fixed to join all text-type blocks.)*
+
+## References
+
+- Council debate 2026-07-04 (claude-sonnet-4-5 + gpt-4o, 2 rounds).
+- Amendment-2 council 2026-07-05 (claude-fable-5 + gpt-4o, 2 rounds) — consumer distribution = wedge-only.
+
+- Council debate 2026-07-04 (claude-sonnet-4-5 + gpt-4o, 2 rounds).
+- Amendment-1 council 2026-07-04 (claude-sonnet-4-5 + gpt-4o, 2 rounds) — manifest integration = Option B.
+- ADR-034 / ADR-035 — `model_tier` → native model mapping (reused, not replaced).
+- `docs/contracts/subagent-boundary.md` — what a subagent owns vs. never owns.
+- `src/skills/subagent-orchestration/SKILL.md` — the in-session orchestration modes.
+- `road-to-final-state-and-market-readiness.md` — Track A (A1 keystone; A2 pipeline
+  proof; A3 eval gate).

package/docs/decisions/ADR-110-discipline-profile-resolution-locus.md

@@ -0,0 +1,105 @@
+---
+adr: 110
+status: accepted
+date: 2026-07-07
+decision: discipline-profile-resolution-locus
+supersedes: —
+superseded_by: —
+phase: road-to-discipline-profile-tiering
+type: standing
+---
+
+# ADR-110 — `discipline_profile` resolves at runtime (agent-in-the-loop); projection stays configuration-independent
+
+## Status
+
+**Accepted** · 2026-07-07 · maintainer decision implementing two same-day
+AI-council verdicts (claude-sonnet-4-5 + gpt-4o, 2-round debates each):
+weak-host-lift tiering (`agents/settings/contexts/weak-host-lift-tiering-verdict.md`)
+and token-program integration (`agents/settings/contexts/token-program-integration-verdict.md`).
+
+## Context
+
+The cost-factor sweep (`docs/benchmark.md § Cost-factor sweep`) established
+that the package's weak-host discipline lift survives at ~3.3x tokens
+(kernel + `downstream-changes`) with no significant residual from the full
+~11.7x load, and that hosts differ: `claude-sonnet-4-6` is a measured NULL
+(discipline ceiling). The councils converged on ONE runtime knob —
+`discipline_profile: auto | off | essential | full` — with `auto` gating the
+lift layer per host via an evidence-gated NULL-lift disable-list.
+
+The open design question this ADR records: **where does `auto` resolve?**
+Projection is static per project, but the host model is a *runtime* fact — a
+project is opened by Haiku one session and Fable the next, across vendors
+(Claude, GPT, Gemini, open-source). Candidates considered:
+
+1. **Runtime resolution (agent-in-the-loop)** — the agent resolves the knob
+   at session start against `src/config/host-capabilities.yml`.
+2. **Per-tool projection variants** — emit per-model projections; the host
+   picks one. Rejected: no host tool selects projections by model; N×M
+   projection matrix; violates the ADR-040 principle that trigger semantics
+   stay configuration-independent.
+3. **Hook-based rewrite** — a session-start hook mutates the loaded surface.
+   Rejected: hooks are deny/warn-only in the cross-host v1 contract (no
+   transparent rewrite); Claude-only mechanisms are forbidden here.
+
+## Decision
+
+1. **`discipline_profile` is a runtime knob, resolved agent-in-the-loop** —
+   the same enforcement model as `provider-lifecycle-discipline` (the agent
+   reads a declared fact at run time and applies the obligation; CI guards
+   the facts, not the runtime). Resolution semantics live in ONE function,
+   `resolve_discipline_profile()`
+   (`src/agent-src/templates/scripts/work_engine/_lib/agent_settings.ts`):
+   explicit value wins → `auto` checks the session model id against
+   `host-capabilities.yml` (prefix match; measured-NULL → `off`, otherwise →
+   `essential` under `unknown_default: lift_enabled`) → absent key maps from
+   legacy `rule_loading_tier` (minimal→off, balanced→essential, full→full,
+   custom→custom) → both absent → `essential`.
+2. **`host-capabilities.yml` is an evidence-gated disable-list, never a
+   taxonomy.** Entries name only models with a MEASURED null lift, each with
+   `measured:` provenance (date · pinned report · N) or an explicit
+   `extrapolated: true` maintainer flag. Unknown models resolve fail-safe to
+   the lift (`essential`). Vendor-neutral by construction: any model id can
+   be measured onto the list.
+3. **Projection is unchanged by this ADR.** Bodies still project per
+   `lean_projection.mode` (eager-all today); the knob governs which
+   discipline tiers the agent honours at runtime — exactly the semantics the
+   legacy `rule_loading_tier` already had. The *physical* per-host token
+   saving lands when thin projection un-defers (as a sub-mechanism of
+   `essential`, re-swept, per the token-program-integration verdict), at
+   which point `lean_projection.mode` is absorbed. This keeps ADR-040's
+   guarantee: trigger semantics are configuration-independent.
+4. **`discipline_profile` joins `MERGEABLE_KEYS`** (user-global cascade), as
+   the successor of the already-mergeable `rule_loading_tier`.
+5. **Defaults are evidence-gated.** The template ships the key commented-out
+   (legacy mapping applies) until the P1 full-corpus + P2 non-Claude gates
+   pass (`agents/roadmaps/road-to-discipline-profile-tiering.md`); the flip
+   target is `auto`.
+
+## Consequences
+
+- One resolution function, unit-tested, shared by scripts and documented for
+  agents — no per-tool drift in mapping semantics.
+- Strong hosts get an honest `off` the moment their null is *measured*, never
+  by vendor folklore; the disable-list only grows by measurement.
+- Until thin projection lands, `auto`/`essential` on an eager-projection host
+  changes which rules the agent honours, not the loaded bytes — the cost
+  claims in the settings docs say so explicitly (the measured 3.3x applies
+  where loading is physical: sysprompt injection today, thin projection
+  later).
+- The legacy `rule_loading_tier` stays readable indefinitely; the wizard and
+  presets migrate when the `balanced` cut is retired (roadmap Phase 2).
+
+## Alternatives
+
+Per-tool projection variants and hook rewrites (rejected above); a maintained
+strong/weak model registry (explicitly rejected by the tiering council —
+speculative, unmaintainable at model-release cadence).
+
+## References
+
+- `agents/settings/contexts/weak-host-lift-tiering-verdict.md`
+- `agents/settings/contexts/token-program-integration-verdict.md`
+- `docs/benchmark.md § Cost-factor sweep`
+- ADR-040 (projection-time filtering), ADR-002 (kernel budget)

package/docs/decisions/INDEX.md

@@ -112,6 +112,8 @@ _Auto-generated by `scripts/adr/regenerate_index.py`. Do not edit._
 | [ADR-106](ADR-106-recursive-verification-benchmark-gate.md) | Recursive Verification Benchmark Gate | accepted | 2026-06-23 | — |
 | [ADR-107](ADR-107-legal-domain-pack-adoption.md) | Legal Domain Pack Adoption | accepted | 2026-06-24 | — |
 | [ADR-108](ADR-108-open-source-forever-no-commercial-tier.md) | Open Source Forever No Commercial Tier | accepted | 2026-06-24 | — |
+| [ADR-109](ADR-109-subagent-v1-contract.md) | Subagent V1 Contract | accepted | 2026-07-04 | — |
+| [ADR-110](ADR-110-discipline-profile-resolution-locus.md) | Discipline Profile Resolution Locus | accepted | 2026-07-07 | — |
 | [ADR-200](ADR-200-python-to-typescript-migration.md) | Python To Typescript Migration | accepted | 2026-06-11 | — |
 
 ## Unnumbered (legacy)

package/docs/distribution/awesome-list-submission.md

@@ -0,0 +1,46 @@
+# awesome-list submission — DRAFT (not yet submitted)
+
+> Market-readiness roadmap B5. Submission copy for the community
+> "awesome-claude-code" / "awesome-claude-code-subagents" lists. **Draft only** —
+> submitting is a human act. Every line here is ledger-consistent: no unbacked
+> number, no invented third-party comparison. Lead with the wedge, not the OS.
+
+## Where to submit
+
+Candidate lists (verify each is active + read its CONTRIBUTING before opening a PR):
+
+- `awesome-claude-code` (skills / plugins / tooling)
+- `awesome-claude-code-subagents` (the wedge fits here — a single subagent)
+
+Track status in [`registry-submissions.md`](registry-submissions.md).
+
+## Entry A — the wedge (lead with this)
+
+**production-validator** — a read-only Claude Code subagent that runs the last
+gate before "done": it hunts mocks, stubs, and placeholders on the shipped
+(non-test) path and demands real-system evidence, returning a `READY` / `NOT
+READY` verdict with `file:line` citations. One `curl` into `.claude/agents/`, no
+other install, no runtime.
+
+- Link: `https://github.com/event4u-app/agent-config/tree/main/docs/wedge/production-validator`
+- One-liner (list-row form): `production-validator — the last-gate-before-done subagent: no mock/stub survives on the shipped path; install in one curl.`
+
+## Entry B — the suite (secondary)
+
+**event4u/agent-config** — a governed, no-runtime configuration layer for AI
+coding agents: audited skills, review personas, rules, and commands projected
+into 7+ hosts (Claude Code, Cursor, Windsurf, Copilot, …). Its distinguishing
+discipline: **every public claim is machine-checked** — the README binds each
+claim to resolvable evidence in a Claims-Ledger, and a generated proof page lets
+anyone reproduce the checks (`docs/proof.md`). Bring your own model.
+
+- Link: `https://github.com/event4u-app/agent-config`
+- One-liner: `agent-config — governed skills/rules/personas for AI coding agents, with machine-checked claims and a reproducible proof page. No runtime, bring your own model.`
+
+## Guardrails for whoever submits this
+
+- Do **not** add a performance number or a "better than X" comparison — the
+  suite's whole position is that claims are verifiable, so an unverifiable
+  submission line would be self-defeating.
+- Keep the wedge first: it is the low-friction door. The suite is the follow-on.
+- Re-check the target list is still maintained + follow its exact entry format.

package/docs/distribution/launch-story-draft.md

@@ -0,0 +1,58 @@
+# Launch-story — DRAFT (not published)
+
+> Market-readiness roadmap B5. A short narrative draft for a launch post
+> (Show HN / dev.to / discussions), centered on the wedge + reproducible honesty.
+> **Draft only** — not published; the final headline is gated on the B0
+> positioning decision. Every claim must stay ledger-bound; no unbacked number,
+> no third-party performance comparison.
+
+## Angle
+
+Not "another agent framework." The hook is **reproducible honesty**: an AI-agent
+config layer where every public claim is machine-checked, and you can verify it
+yourself in one command. Open with the wedge (something the reader installs in 30
+seconds), then reveal the discipline behind it.
+
+## Draft body
+
+> Most AI-agent tooling asks you to trust a headline number. This one lets you
+> **check it.**
+>
+> Start small — one file, 30 seconds:
+>
+> ```bash
+> curl -fsSL https://raw.githubusercontent.com/event4u-app/agent-config/main/docs/wedge/production-validator/production-validator.md \
+>   -o .claude/agents/production-validator.md
+> ```
+>
+> `@production-validator` is a read-only Claude Code subagent that runs the last
+> gate before "done": it finds the mock/stub/placeholder still sitting on your
+> shipped path and the "done" that was only ever validated against fakes.
+>
+> That one subagent is a slice of a larger governed layer — skills, review
+> personas, rules, commands across 7+ hosts, no runtime. What makes it different
+> isn't the size; it's that **the marketing is under CI too.** Every claim in the
+> README binds to evidence in a ledger, a generated proof page renders those
+> bindings plus the benchmark runs where the tool changed *nothing*, and a
+> "verify it yourself" block reproduces all of it on a fresh checkout. If a claim
+> ever loses its binding, the build goes red.
+>
+> Try the one file. If it earns its place, the rest is `npx @event4u/agent-config init`.
+
+## Placeholders to resolve before publishing
+
+- **H1 (decided, B0 · 2026-07-04):** *"Agent Config — every claim machine-checked,
+  including 'zero runtime'."* — adopted from the council's verifiability-as-frame
+  option. Use this headline for the post; do not substitute a provisional one.
+- Confirm the raw `curl` URL resolves on `main` at publish time.
+- Link the live proof page once a docs site (Starlight) hosts it, if built.
+
+## Guardrails
+
+- No performance claim or third-party comparison in the post.
+- The "benchmark runs where the tool changed nothing" line points at real
+  published nulls (`docs/benchmark.md`) — keep it truthful, do not dramatize.
+- Include the honest-provenance note: the skills/rules/personas are distilled
+  from real TypeScript/PHP production work; the governance is stack-agnostic but
+  domain heuristics are richest where forged — coverage elsewhere is promising,
+  not proven. (Roadmap B5.)

package/docs/end-to-end-walkthroughs.md

@@ -3,7 +3,7 @@
 Four cycle-by-cycle traces of the engine commands — backend ticket,
 free-form prompt, UI track, and a blocked path. Each walkthrough cites
 a checked-in **golden transcript** under [`tests/golden/baseline/`](../tests/golden/baseline/);
-the transcripts are regenerated by `python3 -m tests.golden.capture` and
+the transcripts are regenerated by `node node_modules/.bin/tsx tests/golden/capture.ts` and
 diffed in CI, so the cycle counts and directive names below stay
 in sync with the engine's actual behavior.
 
@@ -156,7 +156,7 @@ No work is committed, no auto-guess is taken.
 ## Reproducing these locally
 
 ```bash
-python3 -m tests.golden.capture --scenarios GT-1 GT-P1 GT-U2 GT-2
+node node_modules/.bin/tsx tests/golden/capture.ts --scenarios GT-1 GT-P1 GT-U2 GT-2
 ```
 
 Each scenario writes a fresh `transcript.json`, `delivery-report.md`,

package/docs/getting-started.md

@@ -129,7 +129,7 @@ Your agent is now:
 - **Respecting your codebase** — no conflicting patterns
 - **Following standards** — consistent code quality
 
-This is enforced automatically by 93 rules. No configuration needed.
+This is enforced automatically by 95 rules. No configuration needed.
 
 ---
 
@@ -169,7 +169,7 @@ Your agent now understands slash commands:
 | `/quality-fix` | Run and fix all quality checks |
 | `/chat-history import` | Pull a prior session into the current chat (resume) |
 
-→ [Browse all 162 active commands](../dist/agent-src/commands/)
+→ [Browse all 166 active commands](../dist/agent-src/commands/)
 
 ---
 

package/docs/guidelines/agent-infra/asking-and-brevity-examples.md

@@ -91,6 +91,21 @@ Hedge-language patterns:
 - ❌ "probably" alone — name what's unverified
 - ❌ "vermutlich" without hedge target  <!-- md-language-check: ignore -->
 
+### Volatile-fact freshness — which claims need a live source
+
+Generalizes `direct-answers` Iron Law 2's git/PR live-state clause to any
+research or knowledge claim, not just repo state.
+
+| Class | Examples | Rule |
+|---|---|---|
+| **Fresh-lookup** | current role/status of a person or org, prices/versions/quotas, laws & regulatory policy, an unrecognized entity (tool, package, product), a binary event (release, deprecation, incident) | Never answer from model memory — search or cite a live source, every time. These change silently and staleness is invisible until wrong. |
+| **Stable** | math/CS fundamentals, settled historical facts, language/framework basics pinned by the project's own lockfiles | Model knowledge is acceptable; no live lookup required. |
+
+The line is whether the fact **could have changed since training** in a way
+that matters for the claim. When in doubt, treat it as fresh-lookup — the
+cost of one extra search is far lower than a stale claim stated with
+confidence.
+
 ## Direct-answers — failure modes the user will call out
 
 Companion to `direct-answers` § Failure modes. The rule lists the
@@ -107,6 +122,15 @@ correction pattern.
 Acknowledge once, in the user's language, switch behavior, no
 excuses (mirrors `language-and-tone` § slip handling).
 
+### Bullet floor
+
+Companion to `direct-answers` § Iron Law 3. Multi-step content earns
+bullets; each bullet is a complete 1–2-sentence statement, never a
+fragment masquerading as a list item ("Faster." / "Better UX." with no
+subject or verb). A decline or refusal is never rendered as a bulleted
+list of reasons — declines are short prose, one or two sentences, because
+a bulleted refusal reads as a checklist to argue against rather than a
+direct answer.
 
 ## No Cheap Questions — Iron Law 3 detail (paternalistic state options)
 

package/docs/guidelines/agent-infra/corpus-grounding-authoring.md

@@ -49,7 +49,7 @@ src/skills/<domain-skill>/data/
   options, the human confirms. Directive integration is the exception,
   not the goal ("directive engines everywhere" = orchestration envy).
 - Validate before merge:
-  `python3 src/skills/corpus-grounding/scripts/ground.py validate --manifest …`
+  `./scripts-run src/skills/corpus-grounding/scripts/ground validate --manifest …`
   plus a smoke query, plus an eval-fixture test under `tests/`.
 
 ## 3. Governance per shipped corpus (Step 9.8)

package/docs/guidelines/agent-infra/linked-projects-onboarding-gate.md

@@ -28,8 +28,8 @@ recorded decision (opted-in or declined).
 Run the detector against the project root:
 
 ```bash
-python3 -c "from scripts._lib.linked_projects import detect_linked_projects; \
-import json,sys; print(json.dumps(detect_linked_projects('.')))"
+./scripts-run src/scripts/_lib/linked_projects detect .
+
 ```
 
 It returns config-attached siblings only (PhpStorm `.idea/modules.xml` +

package/docs/guidelines/agent-infra/missing-tool-handling.md

@@ -42,11 +42,11 @@ before working around it or installing it.
 
 ```
 > `yq` is not installed. It's the cleanest way to parse the ticket YAML
-> in the Bash prototype — the alternative is shelling out to python3,
-> which adds ~50ms to every run.
+> in the Bash prototype — the alternative is a JSON conversion step,
+> which adds ~20ms to every run.
 >
 > 1. Install via `brew install yq` (recommended — one-time, stays on PATH)
-> 2. Use the python3 fallback — slower but no install needed
+> 2. Use JSON conversion fallback — slower but no install needed
 > 3. Drop YAML — convert fixtures to JSON, use `jq` only
 > 4. Skip this path — I propose a different approach
 ```

package/docs/guidelines/agent-infra/verify-before-complete-demos.md

@@ -39,7 +39,7 @@ User: ist der Fix fertig?
 
 Agent: Frisch gerade ausgeführt:
 
-$ python3 -m pytest tests/test_load_context.py -v
+$ node node_modules/.bin/vitest run tests/scripts/load_context.test.ts
 ============================== 7 passed in 0.07s ===============================
 
 Exit code 0, 7/7 grün. Damit ist der Fix verifiziert.
@@ -74,7 +74,7 @@ User: also fertig zum committen?
 
 Agent: Ich verifiziere kurz — Tests laufen jetzt:
 
-$ python3 -m pytest tests/ -q
+$ node node_modules/.bin/vitest run -q
 ... 47 passed in 2.31s
 
 Grün. Plus ein quality-tools-Lauf:

package/docs/guidelines/augment-portability-patterns.md

@@ -48,7 +48,7 @@ Use direct script invocations instead.
 A subset of package scripts is exposed through a project-local CLI
 wrapper `./agent-config` (written into the project root by the
 installer, gitignored). Artefacts MUST prefer the CLI over raw
-`python3 scripts/…` paths for every command the CLI already covers.
+`./scripts-run src/scripts/…` paths for every command the CLI already covers.
 
 ## Translation tables — see mechanics
 

package/docs/guidelines/code-clarity.md

@@ -84,6 +84,25 @@ used once — inline it.
   inference makes this redundant in PHP 8+, TS, Python 3.10+, Go,
   Rust, etc. Annotate the parameter or return type instead.
 
+## Comment discipline — state a constraint, not a narration
+
+A code comment earns its place only by stating a constraint the code
+itself can't show — a non-obvious invariant, a workaround for a specific
+bug, a hidden dependency. It never narrates:
+
+- **Provenance** — "added for the X feature", "per ticket #123". That
+  belongs in the commit message or PR description, not the code; it rots
+  the moment the feature or ticket is forgotten.
+- **What the next line does** — well-named identifiers already say it.
+  A comment repeating the code is noise the reader skips past.
+- **Why the change is correct** — that's a message to the reviewer, not
+  to the next person reading the file after it's merged.
+
+Test: would removing the comment leave a future reader confused about a
+non-obvious constraint? If yes, keep it — tightened to the constraint
+alone. If the comment only restates what identifiers already convey, or
+explains the change's history rather than the code's behavior, cut it.
+
 ## See also
 
 - Language-specific anchors that link to this guideline:

package/docs/guidelines/design-antipatterns-triggers.json

@@ -5,7 +5,8 @@
     "Review this UI mockup for AI-slop patterns",
     "Create a feature card section with icons and descriptions",
     "Generate a hero section with a big metric and supporting stats",
-    "The design looks generic — how do I make it more distinctive?"
+    "The design looks generic — how do I make it more distinctive?",
+    "Remove the rocket emojis from the hero buttons — it looks AI-generated"
   ],
   "should_not_pull": [
     "Fix the authentication bug in the login controller",