@event4u/agent-config 7.4.0 → 8.0.0

package/README.md

@@ -1,14 +1,16 @@
 <p align="center"><a href="https://event4u.app"><img alt="event4u Agent Config" src=".github/assets/banner.png"></a></p>
 
-# Agent Config — Governed skills, rules & work journeys for AI coding agents
+# Agent Config — every claim machine-checked, including "zero runtime"
 
 [![Smoke](https://github.com/event4u-app/agent-config/actions/workflows/smoke.yml/badge.svg)](https://github.com/event4u-app/agent-config/actions/workflows/smoke.yml) [![Public install smoke (3 OS × 2 Node)](https://github.com/event4u-app/agent-config/actions/workflows/smoke-public-install.yml/badge.svg)](https://github.com/event4u-app/agent-config/actions/workflows/smoke-public-install.yml) [![npm](https://img.shields.io/npm/v/@event4u/agent-config?style=flat-square&label=npm&color=orange)](https://www.npmjs.com/package/@event4u/agent-config) [![agent-config MCP server](https://glama.ai/mcp/servers/event4u-app/agent-config/badges/score.svg)](https://glama.ai/mcp/servers/event4u-app/agent-config)
 
-[![Skills](https://img.shields.io/badge/Skills-258-orange?style=flat-square)](dist/agent-src/skills/) [![Rules](https://img.shields.io/badge/Rules-93-orange?style=flat-square)](dist/agent-src/rules/) [![Commands](https://img.shields.io/badge/Commands-162-orange?style=flat-square)](dist/agent-src/commands/) [![Guidelines](https://img.shields.io/badge/Guidelines-86-orange?style=flat-square)](docs/guidelines/) [![Personas](https://img.shields.io/badge/Personas-26-orange?style=flat-square)](dist/agent-src/personas/) [![Advisors](https://img.shields.io/badge/Advisors-5-orange?style=flat-square)](dist/agent-src/personas/advisors/)
+[![Skills](https://img.shields.io/badge/Skills-264-orange?style=flat-square)](dist/agent-src/skills/) [![Rules](https://img.shields.io/badge/Rules-95-orange?style=flat-square)](dist/agent-src/rules/) [![Commands](https://img.shields.io/badge/Commands-166-orange?style=flat-square)](dist/agent-src/commands/) [![Guidelines](https://img.shields.io/badge/Guidelines-87-orange?style=flat-square)](docs/guidelines/) [![Personas](https://img.shields.io/badge/Personas-29-orange?style=flat-square)](dist/agent-src/personas/) [![Advisors](https://img.shields.io/badge/Advisors-5-orange?style=flat-square)](dist/agent-src/personas/advisors/)
 
 > **Choose your experience — developer · founder · content · agency · finance · ops. Add packs. Get a focused command set, not a 500-artefact dump.** Bring your own AI provider.
 
-**258 skills, 162 commands, 93 governed rules** — plus a capability router that loads the right skill on intent, and multi-agent orchestration with consensus review. The whole layer is compiled into 7+ host agents (Claude Code, Cursor, Augment, Cline, Windsurf, Copilot, Gemini) with **zero runtime daemon**. Six role-shaped entry paths sit on top, so any host becomes a reliable team member — without locking you to a single model or vendor.
+**Every public claim in this README is machine-checked — [verify it yourself](docs/proof.md).** In a market that runs on unbacked headline numbers, this one binds each claim to resolvable evidence or fails its own build.
+
+**258 skills, 162 commands, 93 governed rules** — plus a capability router that loads the right skill on intent, and multi-agent orchestration with consensus review. The whole layer is compiled into 7+ host agents (Claude Code, Cursor, Augment, Cline, Windsurf, Copilot, Gemini) with **zero runtime daemon**.<!-- claim:no-runtime-daemon --> Six role-shaped entry paths sit on top, so any host becomes a reliable team member — without locking you to a single model or vendor.
 
 ### What's different
 
@@ -16,11 +18,17 @@ It is both deep **and** disciplined — and honest about what it deliberately is
 
 - **Depth that routes itself** — 258 skills + 162 commands, with a capability router that loads the right one on intent, not a 500-artefact context dump.
 - **Governance on every host** — rules compiled into each tool's native format at projection time; deterministic runtime hooks added on hook-capable hosts. This config-space, host-agnostic governance is the moat ([the governance advantage](docs/governance-advantage.md) · [enforcement by host](docs/enforcement-by-host.md)).
-- **Surgical uninstall** — removes only its own keys from a shared host config (matched by JSON-pointer + SHA-256), never a neighbour tool's entries.
+- **Surgical uninstall** — removes only its own keys from a shared host config (matched by JSON-pointer + SHA-256), never a neighbour tool's entries.<!-- claim:surgical-uninstall -->
 - **Pack-scoped install** — writes the active pack only, not a 500-artefact dump.
 
 **What it deliberately is *not*** — a content + governance layer, not a runtime: **no background daemon, no separate state database, no self-rewriting memory, no auto-build pipeline.** The host agent runs the loop; every learned change is human-reviewed; the same layer stays portable across tools. Capability without a process to babysit.
 
+> **Where this comes from (honest provenance).** The skills, rules, and personas
+> are distilled from real production work on TypeScript and PHP codebases. The
+> governance mechanics are stack-agnostic, but the domain heuristics are richest
+> where they were forged — treat coverage on other stacks as promising, not
+> proven, and tell us where it falls short.
+
 See exactly [what works on which host](docs/capability-matrix.md), or jump to [things you can do in a minute](docs/cookbook.md).
 
 ### Pick your profile — six entry paths
@@ -105,6 +113,13 @@ lists the end-to-end workflows (`/implement-ticket`, `/work`,
 
 ## Prove it
 
+Don't take the claims on trust — **verify them.** [`docs/proof.md`](docs/proof.md)
+is generated from source: a claim→evidence table (every public claim binds to a
+resolvable pointer, or CI fails), honest-null benchmarks *including the runs where
+the package changed nothing*, and a "verify it yourself" block you run on a fresh
+checkout. The proof page fails CI if it drifts from its sources — reproducibility
+is the proof.
+
 Audit-disciplined by construction — every memory consult, decision
 key, and hook concern lands in `agents/runtime/state/` so you can replay it.
 [Core principles](#core-principles) names the four invariants;
@@ -125,6 +140,21 @@ opt-in measurement loop. Source-of-truth tree is
 
 ## Quickstart
 
+**Try one thing in 30 seconds** — before the full suite, drop in a single
+self-contained subagent and see the discipline on your own repo:
+
+```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
+# then in Claude Code:  @production-validator check this branch is actually done
+```
+
+`production-validator` is read-only and installs nothing else — it gates "done"
+by hunting mocks/stubs on the shipped path and demanding real-system evidence
+([what it does](docs/wedge/production-validator/README.md)). Like it? Install the
+full suite:
+
 **Three steps. Five minutes. Browser wizard, no YAML by hand.**
 
 ```bash
@@ -408,7 +438,7 @@ When a prompt matches a command's purpose ("setze ticket ABC-123 um" → `/imple
 | [**Migration**](docs/MIGRATION.md) | Per-version upgrade steps |
 | [**Showcase**](docs/showcase.md) | More examples & expected behavior |
 
-Browse content: [all 162 commands](dist/agent-src/commands/) · [skills catalog](docs/skills-catalog.md) · [full catalog](docs/catalog.md) · [`llms.txt`](llms.txt).
+Browse content: [all 166 commands](dist/agent-src/commands/) · [skills catalog](docs/skills-catalog.md) · [full catalog](docs/catalog.md) · [`llms.txt`](llms.txt).
 
 ---
 

package/dist/agent-src/commands/analytics/prune.md

@@ -35,7 +35,7 @@ from racing.
 ### 1. Run the implementation
 
 ```bash
-python3 packages/core/installer/python/workspace_analytics.py prune
+./agent-config analytics prune
 ```
 
 No flags. The 90-day window is fixed by contract.

package/dist/agent-src/commands/analytics/show.md

@@ -45,7 +45,7 @@ POSTs. Defaults to a 30-day window and markdown output.
 ### 2. Run the implementation
 
 ```bash
-python3 packages/core/installer/python/workspace_analytics.py \
+./agent-config analytics \
     show [--window=...] [--event=...] [--role=...] [--format=...]
 ```
 

package/dist/agent-src/commands/analyze/decision.md

@@ -81,11 +81,11 @@ key-space (decision area, affected paths) per
 
 Surface the candidate and ask:
 
-> 1. Propose this candidate to `/memory propose` (recommended)
+> 1. Propose this candidate to `/memory propose`
 > 2. Refine before proposing — suggest changes
 > 3. Skip memory candidate for now
 
-**Empfehlung:** 1
+**Recommendation:** 1
 
 If the candidate fails the admission gate (< 2 distinct evidence paths
 AND < 3 future decisions in `decision_surface`), surface the gap and

package/dist/agent-src/commands/analyze/incident.md

@@ -94,11 +94,11 @@ type, affected paths) per
 
 Surface the draft and ask:
 
-> 1. Propose this candidate to `/memory propose` (recommended)
+> 1. Propose this candidate to `/memory propose`
 > 2. Refine before proposing — suggest changes
 > 3. Skip memory candidate for now
 
-**Empfehlung:** 1
+**Recommendation:** 1
 
 ### Rules
 

package/dist/agent-src/commands/analyze/near-miss.md

@@ -90,11 +90,11 @@ draft an `incident-learnings` candidate via `/memory propose`:
 
 ### 5. Surface the candidate to the user
 
-> 1. Propose this candidate to `/memory propose` (recommended)
+> 1. Propose this candidate to `/memory propose`
 > 2. Refine before proposing — suggest changes
 > 3. Skip memory candidate for now
 
-**Empfehlung:** 1
+**Recommendation:** 1
 
 ### Rules
 

package/dist/agent-src/commands/analyze/postmortem.md

@@ -108,11 +108,11 @@ update an existing one.
 
 Present the draft candidate and ask:
 
-> 1. Propose this candidate to `/memory propose` (recommended)
+> 1. Propose this candidate to `/memory propose`
 > 2. Refine before proposing — suggest changes
 > 3. Skip memory candidate for now
 
-**Empfehlung:** 1
+**Recommendation:** 1
 
 ### Rules
 

package/dist/agent-src/commands/analyze/premortem.md

@@ -82,11 +82,11 @@ If the analysis surfaces a pattern worth preserving for future plans:
 
 3. Surface the candidate to the user and ask:
 
-> 1. Propose this candidate to `/memory propose` (recommended)
+> 1. Propose this candidate to `/memory propose`
 > 2. Refine before proposing — suggest changes
 > 3. Skip memory candidate for now
 
-**Empfehlung:** 1
+**Recommendation:** 1
 
 ### Rules
 

package/dist/agent-src/commands/cost-report.md

@@ -100,6 +100,31 @@ BUDGET_PERIOD=week node scripts/cost/budget.mjs check
 
 Allowed values: `today`, `week`, `month`, `all` (default).
 
+### 6. Orchestration telemetry summary (when telemetry exists)
+
+Read the current-month JSONL from `agents/runtime/state/audit/YYYY-MM.jsonl`
+(`YYYY-MM` = current UTC month). If it exists and has lines with `input_kind:
+"orchestration"`, surface an orchestration summary via `readOrchestrationMetrics`
+from `src/scripts/_lib/subagent_steering.ts`:
+
+```
+Orchestration telemetry (YYYY-MM, N dispatches):
+  avg token_delta:     ±NNN  (positive = cost more; negative = saved)
+  spawn_failure_rate:  N.N%  (threshold: 10%)
+  verify_skip_rate:    N.N%  (threshold: 1%)
+  guardrail breaches:  [token_blowup | spawn_failure | verify_skip | none]
+```
+
+No orchestration lines yet (capture not running or no delegated dispatches this
+month) → surface:
+
+> No orchestration telemetry yet — subagent dispatches begin writing to
+> `agents/runtime/state/audit/YYYY-MM.jsonl` once `subagents.enabled: true`
+> and a dispatch runs.
+
+Skip this step entirely if the user did not ask about orchestration telemetry and
+there is no `agents/runtime/state/audit/` directory.
+
 ## Rules
 
 - **Local-only.** Never persist cost data to remote stores. The

package/dist/agent-src/commands/evals/analyze.json

@@ -0,0 +1,30 @@
+{
+  "command": "analyze",
+  "intent": "Analysis dispatcher — classify input by keywords, propose a weighted framework path, let the user pick",
+  "cases": [
+    {
+      "prompt": "analyze what went wrong in yesterday's deploy",
+      "expected": "analyze"
+    },
+    {
+      "prompt": "run a post-mortem on the checkout outage",
+      "expected": "analyze"
+    },
+    {
+      "prompt": "we're about to launch — do a pre-mortem on the migration plan",
+      "expected": "analyze"
+    },
+    {
+      "prompt": "review the decision we made about the queue architecture last quarter",
+      "expected": "analyze"
+    },
+    {
+      "prompt": "that was almost a data-loss incident — analyze the near miss",
+      "expected": "analyze"
+    },
+    {
+      "prompt": "walk me through a structured incident analysis for the API downtime",
+      "expected": "analyze"
+    }
+  ]
+}

package/dist/agent-src/commands/evals/mission-upgrade.json

@@ -0,0 +1,30 @@
+{
+  "command": "mission-upgrade",
+  "intent": "Upgrade a Laravel application one major version (10→11, 11→12) via the gated /work engine with a structured breaking-change catalog",
+  "cases": [
+    {
+      "prompt": "upgrade our Laravel app from 10 to 11",
+      "expected": "mission-upgrade"
+    },
+    {
+      "prompt": "bump laravel/framework to the next major version",
+      "expected": "mission-upgrade"
+    },
+    {
+      "prompt": "run the Laravel 11 to 12 upgrade with the breaking-change catalog",
+      "expected": "mission-upgrade"
+    },
+    {
+      "prompt": "plan and execute the framework major-version upgrade for this Laravel project",
+      "expected": "mission-upgrade"
+    },
+    {
+      "prompt": "migrate this app to the new Laravel major release",
+      "expected": "mission-upgrade"
+    },
+    {
+      "prompt": "our composer.json pins laravel 10 — take it to 11 safely",
+      "expected": "mission-upgrade"
+    }
+  ]
+}

package/dist/agent-src/commands/implement-ticket.md

@@ -61,7 +61,7 @@ engine — they make a `lite`-tier build safe (per
   `done`. If a dependency is open, STOP and surface it — never build
   out of order.
 - **Pre-build staleness gate.** Run
-  `python3 src/scripts/lint_ticket_buildable.ts` on the bundle. An
+  `./scripts-run src/scripts/lint_ticket_buildable` on the bundle. An
   `adr_refs` SHA drift is a **hard** stop ("re-emit the bundle"); a
   `source_refs` SHA drift only **warns** and proceeds (split severity).
 - **Boundary guard.** Carry the ticket's `boundaries`

package/dist/agent-src/commands/knowledge/forget.md

@@ -46,7 +46,7 @@ If the prefix is missing → print the usage line above and stop. Do
 ### 2. Run the implementation
 
 ```bash
-python3 packages/core/installer/python/knowledge_ingest.py \
+./agent-config knowledge \
     forget <ingest-id-prefix>
 ```
 

package/dist/agent-src/commands/knowledge/ingest.md

@@ -55,7 +55,7 @@ Run before any file is touched:
 ### 3. Run the implementation
 
 ```bash
-python3 packages/core/installer/python/knowledge_ingest.py \
+./agent-config knowledge \
     ingest <path> [--no-redact] [--markitdown=<bin>]
 ```
 

package/dist/agent-src/commands/knowledge/list.md

@@ -46,7 +46,7 @@ sorted by `created_at` ascending. Read-only by default; `--pin` and
 ### 2. Run the implementation
 
 ```bash
-python3 packages/core/installer/python/knowledge_ingest.py \
+./agent-config knowledge \
     list [--format=...] [--pin <id-prefix>] [--unpin <id-prefix>]
 ```
 

package/dist/agent-src/commands/memory/load.md

@@ -66,15 +66,16 @@ If the lookup helper does not yet support `--priority`, fall back to a
 file-only sweep:
 
 ```bash
-python3 - <<'PY'
-import pathlib, yaml
-for f in sorted(pathlib.Path("agents/memory").rglob("*.yml")):
-    data = yaml.safe_load(f.read_text(encoding="utf-8")) or {}
-    for e in data.get("entries", []) or []:
-        if e.get("priority") == "critical" and e.get("status") == "active":
-            print(f"--- {f.parent.name}/{e.get('id')}")
-            print(yaml.safe_dump(e, sort_keys=False), end="")
-PY
+node -e '
+const fs = require("fs"), path = require("path"), yaml = require("js-yaml");
+const glob = (dir) => fs.readdirSync(dir, {recursive: true}).filter(f => f.endsWith(".yml")).map(f => path.join(dir, f));
+for (const f of glob("agents/memory").sort()) {
+    const data = yaml.load(fs.readFileSync(f, "utf8")) || {};
+    for (const e of data.entries || [])
+        if (e.priority === "critical" && e.status === "active")
+            console.log("---", path.basename(path.dirname(f)) + "/" + e.id, "\n" + yaml.dump(e, {sortKeys: false}));
+}
+'
 ```
 
 The Tier-0 slice is surfaced once per `/memory:load` invocation, even
@@ -88,7 +89,7 @@ Before loading, count the entries:
 
 ```bash
 ./agent-config memory:lookup --types <type> --format json | \
-  python3 -c "import sys, json; print(len(json.load(sys.stdin)))"
+  node -e "const d = []; process.stdin.on('data', c => d.push(c)); process.stdin.on('end', () => console.log(JSON.parse(d.join('')).length))"
 ```
 
 If the count exceeds 25, warn:
@@ -131,7 +132,7 @@ After step 4, count unreviewed intake entries for the same type:
 
 ```bash
 ./agent-config memory:lookup --types <type> --intake-only --format json | \
-  python3 -c "import sys, json; print(len(json.load(sys.stdin)))"
+  node -e "const d = []; process.stdin.on('data', c => d.push(c)); process.stdin.on('end', () => console.log(JSON.parse(d.join('')).length))"
 ```
 
 Read `memory.review_threshold` from `.agent-settings.yml` (default 10).

package/dist/agent-src/commands/memory/promote.md

@@ -116,6 +116,36 @@ schema to write to and record the override in the `source:` block.
 
 Show the YAML draft and ask for confirmation before writing.
 
+### 3b. Contradiction check — durable types only
+
+For the behaviorally load-bearing durable types (`incident-learnings`,
+`product-rules`, `domain-invariants`), run the mechanical contradiction
+detector before writing (same primary key + Jaccard body similarity
+< 0.3 → same topic, different claim):
+
+```bash
+./scripts-run src/scripts/check_memory_contradiction \
+    --type <type> --key <curated id or key field> --body "<draft body>"
+```
+
+- Exit `0` → proceed to Step 4.
+- Exit `1` → a potential contradiction pair was surfaced. **Never
+  auto-resolve** (council REJECT list). Ask the human via the contested
+  flow:
+
+  ```
+  > ⚠️ The draft may contradict an existing durable entry (same key, low similarity).
+  >
+  > 1. Approve new + mark the existing entry `contested` (with provenance: what changed, which session)
+  > 2. Revise the new draft — the existing entry stands
+  > 3. Both are valid in different scopes — narrow the new entry's key and re-check
+  ```
+
+Warning surface, not a gate — the human's pick resolves it; the
+detector never blocks a promote on its own. Non-durable types
+(`sessions`-style exploratory content, `recurring-patterns`, …) are
+deliberately not checked — they evolve legitimately.
+
 ### 4. Write the curated entry (content-addressed)
 
 Compute the content hash and write a **one-entry file** at

package/dist/agent-src/commands/memory/propose.md

@@ -75,7 +75,21 @@ Ask once, numbered. If the user picks `skip`, proceed without them:
   primary tag picks the intake JSONL file, the promoter resolves the
   curated target via tag intersection.
 
-### 4. Emit via the shared helper
+### 4. Check for a near-duplicate (advisory)
+
+```bash
+./scripts-run src/scripts/check_memory_similarity --type <type> --body "<body>"
+```
+
+Token-Jaccard similarity against existing intake signals of the same
+type — advisory, additive, never touches the exact-match dedup in
+Step 5. Exit 1 (≥ 80% similar) → surface the matched signal id and ask
+whether to reuse/update it instead of creating a new one; proceed to
+Step 5 only if the user confirms this is a genuinely distinct finding.
+Exit 0 with a "nearest match" note (40–79% similar) → mention it, then
+proceed. Exit 0 with no match → proceed silently.
+
+### 5. Emit via the shared helper
 
 ```bash
 ./agent-config memory:signal \
@@ -95,7 +109,7 @@ automatically — re-running the command on the same finding will
 silently skip the write. Add `--force` only when deliberate duplication
 is intended (rarely).
 
-### 5. Confirm and close
+### 6. Confirm and close
 
 ```
 > ✅ Signal queued as id=<sig-xxxxxx> in <file>.

package/dist/agent-src/commands/mission/upgrade.md

@@ -42,7 +42,7 @@ Before starting, confirm:
 Any fail → surface the conflict and stop. Run:
 
 ```bash
-python3 src/scripts/lint_missions.ts --check-precondition upgrade .
+./scripts-run src/scripts/lint_missions --check-precondition upgrade .
 ```
 
 (Currently a documented stub — full live-repo check lands in Phase 1 PoC.)

package/dist/agent-src/commands/module/explore.md

@@ -41,11 +41,15 @@ unset):
 - **Node / TS monorepo**: Check `packages/`, `apps/`, or `modules/`.
 - **Python**: Check top-level package dirs under `src/<package>/` or flat `<package>/`.
 - **Go**: Check `internal/<domain>/` or `cmd/<service>/`.
-- If none of the above exists:
-  ```
-  ⚠️  No module system found (no Modules/, src/<Domain>/, packages/, internal/, or equivalent directory).
-  ```
-  Stop.
+
+If both the `modules:` block and the fallback table yield nothing:
+
+```
+⚠️  No module system found (no Modules/, src/<Domain>/, packages/, internal/, or equivalent directory).
+   Run `./scripts-run src/scripts/propose_modules_config` to surface candidates.
+```
+
+Stop.
 
 ### 2. List available modules
 
@@ -82,8 +86,8 @@ Let `{module_dir}` be the selected module's `module_path` from
 
 **Structure:**
 - List all directories and files (2 levels deep)
-- Count PHP files per directory (Controllers, Services, Models, Jobs, Commands, etc.)
-- List route files and their contents
+- Count source files per directory (Controllers, Services, Models, Jobs, Commands, etc. — adapt to the configured stack)
+- List route / entry-point files and their contents
 
 **Code:**
 - Use `codebase-retrieval` to understand the module's purpose and key classes