@event4u/agent-config 7.4.0 → 8.0.0

package/docs/positioning-evidence.md

@@ -0,0 +1,86 @@
+# Positioning evidence & decision (B0)
+
+> Market-readiness roadmap B0. The evidenced differentiators the positioning
+> rests on, the H1 options that were weighed, and the decision. Every
+> differentiator below is **shipped and machine-checked**, not aspirational —
+> each names the artifact that backs it.
+
+## The problem
+
+External adoption is ≈0. The prior README H1 — *"Governed skills, rules & work
+journeys for AI coding agents"* — was abstract and interchangeable: no single
+uncopyable hook. This document fixes the one sentence that carries the
+differentiator.
+
+## Evidenced differentiators
+
+1. **Machine-checked honest marketing (the Claims-Ledger).** Every public claim
+   that carries a `<!-- claim:ID -->` marker must bind to a resolvable evidence
+   pointer in [`CLAIMS.md`](CLAIMS.md), or CI fails. Unbacked claims are logged
+   as visible debt rather than hidden. Evidence:
+   [`src/scripts/check_claims.ts`](../src/scripts/check_claims.ts),
+   [`CLAIMS.md`](CLAIMS.md).
+2. **A self-verifying proof page.** [`proof.md`](proof.md) is generated from the
+   ledger (claim → evidence table) plus the honest-null benchmark runs
+   (*including the nulls*) plus a "verify it yourself" command block a skeptic
+   runs on a fresh checkout. Drift-gated in CI. Evidence:
+   [`src/scripts/build_proof.ts`](../src/scripts/build_proof.ts),
+   [`proof.md`](proof.md).
+3. **Published honest-nulls.** Measured null results ship rather than hide (e.g.
+   a recursive-verification wrapper measured for null lift; an orchestration
+   auto-flip held at a documented honest-null). Evidence:
+   [`benchmark.md`](benchmark.md).
+4. **No-runtime, host-agnostic governance.** Rules compile into each tool's
+   native format at projection time; the same governance rides on 7+ hosts with
+   no daemon. Surgical uninstall (JSON-pointer + SHA-256, never a neighbour
+   tool's keys). Evidence:
+   [`contracts/no-runtime-boundary.md`](contracts/no-runtime-boundary.md),
+   [`contracts/install-layout.md`](contracts/install-layout.md).
+5. **A 30-second wedge.** `production-validator` — a single self-contained Claude
+   Code subagent (one `curl` into `.claude/agents/`) that runs the last gate
+   before "done": no mock/stub on the shipped path, validated against real
+   systems. Evidence: [`wedge/production-validator/`](wedge/production-validator/).
+
+## Competitive frame
+
+The dominant competitor wins on reach behind a loud, **unbacked** headline
+performance number (present in several files, no reproducible methodology). The
+only defensible, uncopyable inverse is **reproducible honesty**: they cannot
+adopt a Claims-Ledger + proof page without exposing their own unbacked numbers.
+"Honesty" alone can read as merely defensive, so the wedge and the governed
+depth carry the offensive substance.
+
+## H1 options weighed
+
+- **Option 1 — verifiability as frame.** *"Agent Config — every claim
+  machine-checked, including 'zero runtime'."* Subline: 261 skills, 93 rules,
+  7 hosts; run the proof page yourself; no daemon, no lock-in, no unverifiable
+  promises.
+- **Option 2 — architecture first.** *"Governed AI agents with zero runtime —
+  and a proof page you verify in 30 seconds."*
+- **Option 3 — host-agnostic.** *"Write your agent governance once — run it in
+  7 hosts, with a proof page that can't lie."*
+
+## Decision
+
+**Adopted: Option 1** (verifiability as frame).
+
+Council (claude-sonnet-4-5 + gpt-4o, 2026-07-04) split only on headline vs.
+subline placement, and converged on the substance: the stateless / host-agnostic
+/ no-runtime architecture is the technical moat, and the Claims-Ledger + proof
+page is the maximally-uncopyable trust bootstrap. The decisive argument: in a
+low-trust market, "zero runtime" on its own is just another unverifiable
+promise — making **verifiability the frame** and the architectural claims *what
+you verify* is what makes "zero runtime" credible. The maintainer made the final
+call per the B0 "human picks" gate.
+
+**Biggest risk (tracked):** "machine-checked" can read as compliance-boring
+rather than a competitive weapon — mitigated by framing it offensively
+("built to be checked, in a market that runs on unbacked headlines"), not
+defensively.
+
+## Applied to
+
+- README H1 + hero line (this repo).
+- `distribution/launch-story-draft.md` headline placeholder (resolved).
+- `distribution/awesome-list-submission.md` (already Option-1-aligned).

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.4.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
@@ -731,6 +786,18 @@ hooks:
   rtk_wrap:
     enabled: false
 
+  # PreToolUse anti-slop nudge (road-to-anti-slop-detector Phase 3). Default-OFF.
+  # When enabled, runs the lint_design_slop registry against about-to-be-written
+  # UI content (html/css/jsx/…) and WARNS (exit 2, never blocks) on P0/P1
+  # aesthetic tells — the side-stripe signature, gradient-text, magic z-index,
+  # etc. Flags are rebuttable: declare intent in DESIGN.md, design-slop-disable,
+  # or proceed. Anti-loop: a file::rule signature surfaced 3x goes silent so it
+  # never traps the agent. The universal gate is the lint_design_slop linter/CI;
+  # this hook is a host-limited convenience layer (pre_tool_use fires on ~2-3
+  # hosts). Opt in once you trust the signal-to-noise on your UI.
+  design_slop:
+    enabled: false
+
 # --- Decision engine ---
 #
 # Controllable gates layered over the observability surface. Absent
@@ -841,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>"