@event4u/agent-config 7.4.0 → 8.0.0

package/docs/CLAIMS.md

@@ -0,0 +1,108 @@
+# Claims Ledger
+
+> Every public-facing claim (README, docs, site, marketplace copy) that carries a
+> `<!-- claim:<id> -->` marker binds here to resolvable evidence. `check_claims`
+> (in `task ci`) fails the build if a markered claim has no `backed` ledger entry
+> with a resolving evidence pointer. This is the package's falsifiability culture
+> turned on its own marketing — **we sell honesty, so the selling is machine-checked.**
+>
+> Enforced by [`src/scripts/check_claims.ts`](../src/scripts/check_claims.ts).
+> Roadmap: `road-to-final-state-and-market-readiness.md` Phase 1 / Track B (B1).
+
+## How it works
+
+- A public sentence that makes a capability or quantitative claim gets an HTML
+  marker: `<!-- claim:my-claim-id -->` (invisible in rendered Markdown).
+- The marker's `id` must match a `### claim: my-claim-id` block below with
+  `status: backed` and a resolving `evidence` pointer.
+- **Only markered claims are enforced.** Unmarkered prose is never checked — the
+  ledger tightens as claims are bound over time, never retroactively breaking CI.
+- `status: unbacked` entries are **inventory** (documented debt): they record a
+  claim that is not yet bound. They do NOT fail the build, but markering their
+  claim in prose does (forces the binding first).
+
+## Entry schema
+
+```
+### claim: <kebab-id>
+- claim: <the sentence, roughly as it appears publicly>
+- kind: quant | qual | comparative
+- evidence: <pointer>            # see grammar below
+- status: backed | unbacked
+- last_verified: <YYYY-MM-DD>
+```
+
+**Evidence-pointer grammar (v1):**
+
+- `path/to/file.md` or `path/to/file.md:42` — the repo file exists (line advisory).
+- `path/to/file.md#substring` — the file exists AND contains `substring`.
+- `https://… (YYYY-MM-DD)` — external cite carrying a dated stamp (not fetched in CI).
+
+---
+
+## Backed claims
+
+### claim: no-runtime-daemon
+- claim: The whole layer is compiled into host agents with zero runtime daemon.
+- kind: qual
+- evidence: docs/contracts/no-runtime-boundary.md#file-first, no-runtime suite
+- status: backed
+- last_verified: 2026-07-04
+
+### claim: surgical-uninstall
+- claim: Removes only its own keys from a shared host config (matched by JSON-pointer + SHA-256), never a neighbour tool's entries.
+- kind: qual
+- evidence: docs/contracts/install-layout.md#JSON-pointer
+- status: backed
+- last_verified: 2026-07-04
+
+### claim: discipline-lift-weak-host
+- claim: 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.
+- kind: quant
+- evidence: docs/benchmark.md#weak-host-specific
+- status: backed
+- last_verified: 2026-07-05
+
+### claim: essential-tier-cost-factor
+- claim: 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.
+- kind: quant
+- evidence: docs/benchmark.md#Full-corpus P1 gate
+- status: backed
+- last_verified: 2026-07-07
+
+---
+
+## Unbacked inventory (documented debt — not yet markered in prose)
+
+These are real README claims that need a durable binding before they may carry a
+`<!-- claim: -->` marker. Counts are drift-prone: binding them requires a
+count-source mechanism (a generated number the prose must match), which is
+follow-up work (roadmap B1.2). Listed here so the debt is visible, not hidden.
+
+### claim: skill-count
+- claim: 258 skills (README hero + feature list).
+- kind: quant
+- evidence: needs a generated count-source binding (discovery manifest) — B1.2
+- status: unbacked
+- last_verified:
+
+### claim: command-count
+- claim: 162 commands.
+- kind: quant
+- evidence: needs a generated count-source binding (discovery manifest) — B1.2
+- status: unbacked
+- last_verified:
+
+### claim: rule-count
+- claim: 93 governed rules.
+- kind: quant
+- evidence: needs a generated count-source binding (discovery manifest) — B1.2
+- status: unbacked
+- last_verified:
+
+### claim: host-agent-count
+- claim: Compiled into 7+ host agents (Claude Code, Cursor, Augment, Cline, Windsurf, Copilot, Gemini).
+- kind: quant
+- evidence: needs binding to the projection targets list — B1.2
+- status: unbacked
+- last_verified:

package/docs/MIGRATION.md

@@ -35,7 +35,7 @@ recognised on a clear error path.
 `.implement-ticket-state.json` file:
 
 ```bash
-python3 -m work_engine.migration.v0_to_v1 .implement-ticket-state.json
+node agent-config-templates/scripts/work_engine/migration/v0_to_v1.js .implement-ticket-state.json
 ```
 
 This:
@@ -58,7 +58,7 @@ finds only the legacy file, it stops with:
 ```
 error: Found legacy state file .implement-ticket-state.json but no
 .work-state.json. The default state file was renamed in 1.15.0. Run
-`python3 -m work_engine.migration.v0_to_v1 .implement-ticket-state.json`
+`node agent-config-templates/scripts/work_engine/migration/v0_to_v1.js .implement-ticket-state.json`
 to migrate, or pass `--state-file .implement-ticket-state.json` to
 keep using the old name. See docs/MIGRATION.md.
 ```
@@ -112,7 +112,7 @@ If your project commits state files (uncommon but supported):
 - Stability level: `work_engine` is **beta** — see
   [`docs/contracts/STABILITY.md`](contracts/STABILITY.md).
 - Source of truth for the migrator:
-  [`templates/scripts/work_engine/migration/v0_to_v1.py`](../src/agent-src/templates/scripts/work_engine/migration/v0_to_v1.py).
+  [`templates/scripts/work_engine/migration/v0_to_v1.ts`](../src/agent-src/templates/scripts/work_engine/migration/v0_to_v1.ts).
 
 ## Older versions
 

package/docs/architecture.md

@@ -146,10 +146,10 @@ note, package-internal path-swap, description budget, and the
 
 | Layer | Count | Purpose |
 |---|---|---|
-| **Skills** | 258 | On-demand expertise — stack analysis (Laravel · Symfony · Zend / Laminas · Next.js · React · Node), testing, Docker, API design, security, observability, … |
-| **Rules** | 93 | Always-active constraints — coding standards, scope control, verification, language-and-tone, agent-authority |
-| **Commands** | 162 | Slash-command workflows — `/commit`, `/create-pr`, `/fix ci`, `/optimize skills`, `/feature plan`, `/work`, `/implement-ticket`, `/condense`, … |
-| **Guidelines** | 86 | Reference material cited by skills — PHP patterns, Eloquent, Playwright, agent-infra, … |
+| **Skills** | 264 | On-demand expertise — stack analysis (Laravel · Symfony · Zend / Laminas · Next.js · React · Node), testing, Docker, API design, security, observability, … |
+| **Rules** | 95 | Always-active constraints — coding standards, scope control, verification, language-and-tone, agent-authority |
+| **Commands** | 166 | Slash-command workflows — `/commit`, `/create-pr`, `/fix ci`, `/optimize skills`, `/feature plan`, `/work`, `/implement-ticket`, `/condense`, … |
+| **Guidelines** | 87 | Reference material cited by skills — PHP patterns, Eloquent, Playwright, agent-infra, … |
 | **Templates** | 7 | Scaffolds for features, roadmaps, contexts, skills, overrides |
 | **Contexts** | 5 | Shared knowledge about the system itself |
 
@@ -226,8 +226,8 @@ execution:
   type: manual | assisted | automated
   handler: shell | php | node | internal | none
   command:                       # required for shell/php/node runtime paths
-    - python3
-    - scripts/skill_linter.py
+    - ./scripts-run
+    - src/scripts/skill_linter
     - "--all"
   timeout_seconds: 120
   allowed_tools: []

package/docs/benchmark.md

@@ -1,17 +1,30 @@
 # Discipline-Axis Wrapper-Lift Benchmark (v2)
 
-> Generated by `scripts/bench_ab_v2_stats.py --markdown`. Source: `internal/bench/reports/ab-v2/`. Re-render with `task bench:ab:v2:diff`.
+> **Curated composite of two pinned reports** — the weak-host result and the
+> strong-host result side by side. It is deliberately NOT auto-generated from the
+> single latest `ab-v2` report: a single-report render would bury one host's
+> finding (a strong-host null would erase the weak-host lift, and vice versa).
+> Regenerate the pinned sections with `task bench:ab:v2:diff` — each
+> `<!-- pinned:<id> -->` region renders from ITS pinned report
+> (`docs/benchmark.pinned.yml`); curated prose outside the markers is
+> never touched (`-- --check` is the drift gate). Pinned sources:
+> weak host = `internal/bench/reports/ab-v2/2026-06-15T03-52-35Z-ab-v2-paired.json`;
+> strong host = `internal/bench/reports/ab-v2/2026-07-05T07-00-31Z-ab-v2-paired.json`;
+> cost-factor sweep = `internal/bench/reports/ab-v2/2026-07-07T05-35-14Z-ab-v2-paired.json`.
 
 ## Honesty labels (read first)
 
+<!-- pinned:honesty -->
 > 1. **Wrapper-lift on a fixed host (`claude-haiku-4-5`), NOT model-vs-model.** Measures what the agent-config package does to ONE host model on a neutral fixture — not a capability ranking.
 > 2. **Discipline axis, not capability.** The headline is the *discipline* delta (did it stay minimal / verify / ask / not destroy / update downstream), not whether the goal was achievable.
 > 3. **PILOT — low statistical power (N=2 tasks × 12 seed(s)).** Directional only.
 > 4. **Paired design**, errored runs excluded; McNemar (capability) + Wilcoxon signed-rank (discipline) + effect sizes.
 > 5. **Not comparable to SWE-bench / GAIA / Fable scores** — a different question entirely.
+<!-- /pinned:honesty -->
 
-## Gate verdict: **PASS**
+## Weak host (`claude-haiku-4-5`) — Gate verdict: **PASS**
 
+<!-- pinned:weak-stats -->
 - capability lift significant: `False`
 - discipline lift significant: `True`
 - status-bucket better (package vs vanilla): `False`
@@ -73,6 +86,124 @@
 - Arms: vanilla (plugin off) · package (real plugin) · package-rdp (plugin + RDP rules) · placebo (plugin off + equal-length inert prose).
 - Corpus: `internal/bench/corpora/ab-trackb-v2.yaml` (5 trap archetypes). Scoring: `bench_ab_scoring_v2.py` (deterministic, no LLM judge).
 - Roadmap: `agents/roadmaps/road-to-discipline-axis-benchmark.md`.
+<!-- /pinned:weak-stats -->
+
+## Cost-factor sweep (`claude-haiku-4-5`) — lift per loaded-context cost
+
+> **Question:** the full package buys its weak-host lift at ~12× vanilla tokens.
+> How much of the lift survives in trimmed rule-only configurations at a
+> fraction of that cost? Four arms, same paired design (2 tasks × 12 seeds,
+> n=24 pairs/arm), same host, same deterministic scorer. The trimmed arms run
+> plugin-OFF + ONLY the named rule bodies injected via system prompt
+> (`rules_subset_text()` in `bench_ab_v2_run.ts`, tier membership from
+> `dist/router.json`).
+
+<!-- pinned:cost-factor-table -->
+| arm | loaded content | injected chars | mean tokens/run | cost factor | mean discipline | lift vs vanilla |
+|---|---|---|---|---|---|---|
+| `vanilla` | none | 0 | 103,319 | 1.0× | 0.458 | — |
+| `rules-balanced` | kernel + tier 1 (shipped `balanced` profile) | 98,825 | 303,186 | **2.9×** | 0.417 | −0.042 (p=0.8127, **NULL**) |
+| `rules-kernel-dc` | kernel (9 rules) + `downstream-changes` | 30,698 | 344,483 | **3.3×** | 0.917 | **+0.458 (p=0.0135, significant)** |
+| `package` | full plugin | 0 | 1,210,078 | **11.7×** | 1.000 | **+0.542 (p=0.0017, significant)** |
+
+(generated from the pinned report — curated labels from `docs/benchmark.pinned.yml`)
+<!-- /pinned:cost-factor-table -->
+
+Residual of the full package over `rules-kernel-dc`: Δ=+0.083, Wilcoxon p=0.37
+(only 2 discordant pairs) — **not significant**.
+
+Three findings:
+
+1. **~95% of the lift survives at ~3× cost.** The kernel + `downstream-changes`
+   configuration keeps a significant discipline lift (0.917 vs the full
+   package's 1.000; the residual is not significant at this N) at ~28% of the
+   full package's tokens. The 12× full load is not required for this trap
+   family's lift.
+2. **Content selection beats size — the shipped `balanced` profile is a null.**
+   `rules-balanced` injects 3× more chars than `rules-kernel-dc` and costs
+   almost the same per run, but delivers ZERO lift: it lacks
+   `downstream-changes` (a tier-2 rule), and `scope-control` alone does not
+   correct the downstream trap. This is the placebo result again, sharpened:
+   not only is length inert, even 33 real rules are inert on a trap their
+   lift-carrying rule doesn't cover. Any low-cost weak-host profile must be
+   cut by lift-carrying content, not by tier size.
+3. **Cost is behaviour, not just context.** `rules-kernel-dc` injects a third
+   of `rules-balanced`'s chars but costs slightly MORE — the discipline
+   behaviour itself (verification turns, downstream edits) spends tokens. The
+   token factor cannot be dialed by context size alone.
+
+**Honest scope:** weak host only; the 2-task scope/downstream family (the family
+with the proven lift), N=24 pairs/arm — the full package covers 4 more trap
+archetypes the trimmed arms were NOT tested on here. Rules-only injection, not a
+full plugin projection (no skills/commands/hooks in the trimmed arms). Before
+shipping any trimmed default, sweep the full corpus (done below).
+
+- Report: `internal/bench/reports/ab-v2/2026-07-07T05-35-14Z-ab-v2-paired.json`.
+- Arms: `rules-kernel-dc` / `rules-balanced` in `src/scripts/bench_ab_v2_run.ts` (opt-in, not in the default arm list).
+
+### Full-corpus P1 gate (`claude-haiku-4-5`, all 30 tasks) — family-scoped PASS
+
+> **The essential lift is real, replicates, and is family-scoped.** Full corpus
+> (all 5 trap archetypes + agentic-debug + the Laravel downstream trap),
+> `vanilla` vs `rules-kernel-dc` × 3 seeds = 180 runs (n=90 pairs, 0 errored),
+> run from a frozen checkout so mid-run edits could not contaminate the
+> per-run rule reads. Corpus-wide the discipline delta is +0.056 (0.872 →
+> 0.928, Wilcoxon p=0.084, rb=0.53) — NOT significant, because vanilla Haiku
+> is already at/near the discipline ceiling on every family except the
+> scope/downstream one. Inside that family the pilot lift replicates exactly:
+> trapE (now 5 tasks incl. Laravel + meso variants) 0.533 → 1.000, Δ=+0.467,
+> ALL 7 discordant pairs favouring the essential cut (sign test p≈0.016); all
+> other families flat at ceiling (largest counter-noise: trapA −0.083 on 2
+> discordant pairs). **Corpus-wide cost factor: 1.71x** (132,036 → 225,956
+> mean tokens/run) — cheaper than the family-only 3.3x, because the
+> discipline behaviour only spends turns where the trap exists.
+
+| axis | vanilla | rules-kernel-dc | Δ | test |
+|---|---|---|---|---|
+| capability (pass-rate) | 92% | 92% | 0 | McNemar p=1.0, h=0.0 |
+| discipline, full corpus (0–1) | 0.872 | 0.928 | +0.056 | Wilcoxon p=0.084, rb=0.53 (n≠0=14) |
+| discipline, scope/downstream family (n=15) | 0.533 | 1.000 | +0.467 | 7/7 discordant favour essential (sign p≈0.016) |
+| mean tokens/run | 132,036 | 225,956 | +93,920 (~1.7x) | — |
+
+**Verdict for the tiering roadmap's P1 gate:** family-scoped PASS. The
+`essential` tier's claim stays honest-scoped to the scope/downstream family —
+the lift does not extend to families where the host is already at ceiling, and
+it costs ~1.7x on a realistic mixed corpus. The Phase-4 default flip remains
+additionally gated on the P2 non-Claude replication.
+
+- Report: `internal/bench/reports/ab-v2/2026-07-07T07-04-39Z-ab-v2-paired.json`.
+
+## Strong host (`sonnet`, full 30-task corpus) — Gate verdict: **HONEST-NULL**
+
+- capability lift significant: `False`
+- discipline lift significant: `False`
+- status-bucket better (package vs vanilla): `False`
+
+> **Honest null on a strong host, across the full corpus.** A re-run of the SAME
+> package on `sonnet` over the entire discipline corpus — all 5 trap archetypes +
+> agentic-debug + a Laravel/PHP downstream trap (`trapE-scope-laravel-01`) — with
+> `vanilla` vs `package` × 3 seeds (180 runs, n=84 paired). The discipline axis
+> does not move (Δ=+0.000, Wilcoxon p=1.0) and capability is flat-to-slightly-lower,
+> because a capable host is *already* at the discipline ceiling on these
+> deterministic traps — exactly what the weak-host section predicts. The package
+> is a redundant no-op here, **at ~5× the tokens.** This is not a failure: it is
+> the empirical bound on the weak-host claim, and it holds in PHP as in TS. **No
+> strong-host lift is claimed.**
+
+### Table — `package` vs `vanilla` (n=84 pairs, host `sonnet`)
+
+<!-- pinned:strong-table -->
+| axis | vanilla | package | Δ | test |
+|---|---|---|---|---|
+| capability (pass-rate) | 94% | 89% | −5pp | McNemar p=0.125, h=-0.174 |
+| discipline (0–1) | 0.929 | 0.929 | +0.000 | Wilcoxon p=1.0, rb=0.0 (n≠0=5) |
+| mean tokens/run | 185,584 | 929,716 | +744,132 (~5×) | — |
+
+(host `sonnet`, n=84 pairs — generated from the pinned report)
+<!-- /pinned:strong-table -->
+
+- Report: `internal/bench/reports/ab-v2/2026-07-05T07-00-31Z-ab-v2-paired.json` (A6 of `road-to-final-state-and-market-readiness.md`).
+- Methodology: identical to the weak-host section (pinned host, deterministic scorer, paired design); the only change is the host model and the full-corpus scope.
 
 ## Recursive self-verification (ADR-106) — HONEST-NULL
 

package/docs/benchmark.pinned.yml

@@ -0,0 +1,31 @@
+# Pin manifest for the curated composite `docs/benchmark.md`
+# (road-to-flow-learnings Phase 3).
+#
+# Each section renders INDEPENDENTLY from ITS pinned report via
+# `src/scripts/render_benchmark_composite.ts` — never from the single
+# latest report (the composite's in-file curation rationale stands).
+# Curated prose lives OUTSIDE the `<!-- pinned:<id> -->` markers and is
+# never touched by the renderer. Pinned reports are operator-local
+# (untracked); the renderer skips cleanly where they are absent.
+sections:
+  - id: honesty
+    mode: honesty-labels
+    report: internal/bench/reports/ab-v2/2026-06-15T03-52-35Z-ab-v2-paired.json
+  - id: weak-stats
+    mode: stats-body
+    report: internal/bench/reports/ab-v2/2026-06-15T03-52-35Z-ab-v2-paired.json
+  - id: cost-factor-table
+    mode: arm-cost-table
+    report: internal/bench/reports/ab-v2/2026-07-07T05-35-14Z-ab-v2-paired.json
+    arms:
+      - id: vanilla
+        label: none
+      - id: rules-balanced
+        label: kernel + tier 1 (shipped `balanced` profile)
+      - id: rules-kernel-dc
+        label: kernel (9 rules) + `downstream-changes`
+      - id: package
+        label: full plugin
+  - id: strong-table
+    mode: compact-table
+    report: internal/bench/reports/ab-v2/2026-07-05T07-00-31Z-ab-v2-paired.json

package/docs/capability-matrix.md

@@ -15,6 +15,7 @@ transform — `.mdc`, workflow, or an aggregated single file) · **— none**
 | `rules` | ✅ native | — none | ✅ native | 🔁 adapter | 🔁 adapter | ✅ native | 🔁 adapter | 🔁 adapter † | — none |
 | `skills` | ✅ native | ✅ native | ✅ native | — none | — none | — none | — none | — none | — none |
 | `commands` | ✅ native | — none | ✅ native | 🔁 adapter | 🔁 adapter | — none | — none | — none | — none |
+| `subagents` | ✅ native | — none | — none | 🔁 adapter | 🔁 adapter | 🔁 adapter | — none | — none | — none |
 | `personas` | ✅ native | — none | ✅ native | ✅ native | — none | — none | — none | — none | — none |
 | `user-types` | ✅ native | — none | ✅ native | ✅ native | — none | — none | — none | — none | — none |
 | `hooks` | — none | ✅ native | — none | — none | — none | — none | — none | — none | — none |