@event4u/agent-config 8.8.0 → 8.10.0

package/docs/guidelines/agent-infra/simplicity-and-goal-demos.md

@@ -0,0 +1,151 @@
+# Simplicity and Goal Discipline — wrong/right demos
+
+Recognition surface for [`minimal-safe-diff § Anti-over-engineering`](../../src/rules/minimal-safe-diff.md)
+(own-orphan cleanup, speculative-complexity bans) and the goal-driven
+execution clause in `think-before-action`. Per council convergence
+(2026-07-10): the demos ARE the enforcement — an agent that has never seen
+the violation cannot recognize it, no matter how crisp the checklist question.
+Match your diff against the *right* column before presenting.
+
+## 1. Over-abstraction vs. one function
+
+**Ask:** "Add a function to calculate a percentage discount."
+
+**Wrong — Strategy pattern for a single caller (PHP):**
+
+```php
+interface DiscountStrategy { public function calculate(float $amount): float; }
+final class PercentageDiscount implements DiscountStrategy { /* … */ }
+final class FixedDiscount implements DiscountStrategy { /* … */ }
+final readonly class DiscountConfig { /* strategy, minPurchase, maxDiscount */ }
+final class DiscountCalculator { /* 30+ lines of orchestration */ }
+```
+
+**Right — one function until the second discount type is real:**
+
+```php
+function calculateDiscount(float $amount, float $percent): float
+{
+    return $amount * ($percent / 100);
+}
+```
+
+**Why:** No second caller, no second strategy → no abstraction. When the
+second type genuinely arrives, refactor then (`prefer-enums-over-literals` /
+Strategy sniff test governs that moment). The wrong version is not "bad
+code" — it is *premature* code: harder to read, more surface to test, and
+speculative until the requirement exists.
+
+## 2. Speculative features vs. just-what-was-asked
+
+**Ask:** "Save user preferences to the database."
+
+**Wrong — options nobody requested (TypeScript):**
+
+```ts
+class PreferenceManager {
+  constructor(db: Db, cache?: Cache, validator?: Validator) { /* … */ }
+  save(userId: number, prefs: Prefs,
+       opts: { merge?: boolean; validate?: boolean; notify?: boolean } = {}) {
+    // merging, validation, cache write, notification fan-out — all unasked
+  }
+}
+```
+
+**Right — the ask, nothing else:**
+
+```ts
+async function savePreferences(db: Db, userId: number, prefs: Prefs) {
+  await db.query('UPDATE users SET preferences = $1 WHERE id = $2',
+    [JSON.stringify(prefs), userId]);
+}
+```
+
+**Why:** Every optional parameter with one call site, every "flexibility"
+flag, and every handler for a scenario that cannot occur is speculative
+complexity. Add caching when performance data demands it, validation when bad
+data appears, merging when the requirement lands.
+
+## 3. Drive-by refactor vs. surgical diff
+
+**Ask:** "Fix the bug where an empty email crashes the validator."
+
+**Wrong:** the fix PLUS improved email regex, new username length checks,
+rewritten comments, and a fresh docstring — four changes, one was asked.
+
+**Right:** only the lines that make the empty-email case safe change; every
+other line of the function is byte-identical.
+
+**Why:** Every changed line must trace to the stated task
+(`minimal-safe-diff`). The "improvements" belong in a follow-up proposed via
+`active-remediation`'s note-and-ask ladder — not smuggled into the bug fix.
+
+## 4. Style drift vs. match-existing-style
+
+**Ask:** "Add logging to the upload function."
+
+**Wrong:** the diff adds logging AND flips quote style, adds type hints,
+reshapes the boolean return, reflows whitespace — the reviewer can no longer
+see the logging change.
+
+**Right:** logger import + three log lines, inserted in the file's existing
+style (its quoting, its spacing, its return pattern), even where you would
+personally write it differently.
+
+**Why:** Style consistency is a repo property, not a per-diff taste decision.
+A diff that reformats while changing behavior hides the behavior change.
+
+## 5. Own-orphan vs. pre-existing dead code
+
+**Ask:** "Replace the legacy formatter call in `processA` with the new one."
+
+**Wrong (too little):** `processA` no longer calls `legacyFormat()`, but the
+now-unused import and the helper it alone referenced stay behind — the diff
+shipped its own litter.
+
+**Wrong (too much):** while in the file, the agent also deletes
+`oldHelper()`, which `processB` — untouched by this diff — still references
+in another module, or which was already orphaned *before* this task.
+
+**Right:** remove exactly the imports/variables/functions whose **last
+reference disappeared in a file this diff touched**; anything still
+referenced from untouched files — or orphaned before the task — is
+pre-existing debt: mention it, don't delete it.
+
+**Why:** The boundary is mechanical (grep after editing), so there is no
+judgment call to rationalize — see
+[`minimal-safe-diff § Own-orphan cleanup`](../../src/rules/minimal-safe-diff.md#own-orphan-cleanup).
+
+## 6. Vague plan vs. verifiable per-step plan
+
+**Ask:** "Add rate limiting to the API."
+
+**Wrong — unverifiable narration:**
+
+```
+1. Review the code
+2. Identify issues
+3. Implement rate limiting
+4. Test the changes
+```
+
+**Right — every step carries its check:**
+
+```
+1. In-memory limit on one endpoint → verify: 11th request in a minute → 429 (test)
+2. Extract to middleware, all endpoints → verify: limit fires on /users AND /posts; existing endpoint tests stay green
+3. Shared store backend → verify: counter survives app restart; two instances share the count
+```
+
+**Why:** A step without a `verify:` is an assumption. Strong criteria let the
+loop run independently (`verify-before-complete` then has something to
+check); "make it work" guarantees clarification churn after the fact instead
+of before.
+
+## Key insight
+
+The wrong versions are not obviously wrong — they follow known patterns and
+"best practices". The failure is **timing**: complexity added before the
+requirement exists costs comprehension, bugs, and test surface today for a
+tomorrow that may never come. Solve today's problem simply; refactor when the
+second requirement is real.

package/docs/guidelines/agent-infra/tool-description-as-policy.md

@@ -0,0 +1,35 @@
+# Tool description as policy
+
+Authoring guideline for skills, commands, and MCP tools. Shared block — cited
+from [`skill-writing`](../../../src/skills/skill-writing/SKILL.md),
+[`command-writing`](../../../src/skills/command-writing/SKILL.md), and
+[`mcp-builder`](../../../src/skills/mcp-builder/SKILL.md).
+
+## The principle
+
+Policy that governs *how a tool is used* belongs **inside the tool's own
+description**, where it fires at the decision point the model is already
+reading — not in always-on prose the model may not have loaded when it reaches
+for the tool. The description is the highest-signal, best-timed place to encode
+usage policy.
+
+## What to encode in the description
+
+- **Workflow sequencing.** If tool B must follow tool A ("call `memory_lookup`
+  with `detail:index` FIRST, then `memory_get` the ids"), say so in B's
+  description, not in a separate rule.
+- **Preconditions.** What must be true before the tool is called (a built
+  artifact present, a prior step run) — stated where the model chooses to call.
+- **ID / output provenance.** When the tool returns handles (ids, paths, PR
+  numbers), instruct: **copy them verbatim from the tool result, never from
+  memory** — context decay silently corrupts a remembered id.
+- **A mandatory "why" intent field.** Require the caller to state the intent of
+  the call; a tool that forces "why am I calling this" cuts reflexive misuse.
+- **Turn-end contracts.** If the tool ends the turn or hands off, the
+  description says so — the caller does not discover it after the fact.
+
+## Why here, not as an always-on rule
+
+An always-on rule pays context cost on every turn and may be evicted before the
+decision; the description is loaded exactly when the tool is under
+consideration. Encode the policy at the point of use.

package/docs/guidelines/design-canon.md

@@ -60,3 +60,4 @@ Pull when: choosing or auditing an icon library.
 - `docs/guidelines/design-antipatterns.md` — the anti-slop catalog (T7 default-font tell, C1/C5 palette tells) this canon helps you escape.
 - `brand-source-of-truth` / `brand-consistency` — the precedence this index obeys.
 - `design-intelligence` — the consumer that surfaces these on a brief signal.
+- **Reference, don't vendor** (`domain-adoption-policy`): palette hex tables, font-width CSVs, easing/motion constant libraries, print-CSS recipes, and device-frame recipes are **referenced from maintained upstreams, never forked** into this suite — a vendored data table rots, fork-drifts, and couples the suite to one aesthetic. Corpus assets (palettes, easing tables, device frames) stay upstream references, not forks.

package/docs/proof.md

@@ -27,19 +27,23 @@ evidence pointer, or `task check-claims` fails the build.
 | Claim | Kind | Evidence | Resolves |
 |---|---|---|---|
 | The release process is documented as an inheritable runbook + succession doc, and the project's bus-factor (trailing-90-day distinct human reviewers) is tracked and reported truthfully — currently 1, not implied to be more. | qual | `docs/succession.md#trailing 90 days` | ✅ |
-| 172 commands. | quant | `src/scripts/check_artefact_count_messaging.ts#Artefact-count messaging gate` | ✅ |
+| 177 commands. | quant | `src/scripts/check_artefact_count_messaging.ts#Artefact-count messaging gate` | ✅ |
+| The retrieval economy cuts always-loaded context tokens ~65.6% measured against the FULL always-loaded projection — 98,529 → 33,897 tokens (eager rule load + skill/command descriptions + MCP schemas, thin-flipped). Method: `agent-config benchmark` over the pinned token baseline; the baseline is the honest "what the user pays if everything loads eagerly", NOT a synthetic full-corpus strawman (council Q4). | quant | `internal/bench/reports/token-baseline.json#eager_rule_load` | ✅ |
 | 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 non-coding domain skills (finance/founder/ops/content) are forged on TS/PHP and labeled unvalidated until they pass a sourced domain-truth fixture; no public prose implies proven domain correctness, and the validated count is CI-ratcheted. | qual | `src/scripts/domain_soundness_status.ts#checkRatchet` | ✅ |
 | On the READ-ONLY FAN-OUT slice family, tier-downshifted subagent dispatch (lite/haiku vs session-tier-proxy sonnet) nets a ≥30% USD-weighted token-cost reduction at held quality — measured 2026-07-08 (n=10 paired live dispatches, 20 telemetry lines): 10/10 exact-match on BOTH arms, 29.4% fewer raw tokens, 76.5% USD-weighted cost reduction at the 3x haiku↔sonnet price ratio. FAMILY-SCOPED — the mechanical-edit family is unmeasured and its downshift (incl. the deferred tier downgrades of existing units) stays gated. Negative control held: an open-ended synthesis/unknown slice never resolves below the session tier (inferSliceTier → medium/inherit, never lite). | quant | `internal/bench/routing-downshift/results-2026-07-08.md#FAMILY-SCOPED PROVE` | ✅ |
 | 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- and HOST-SCOPED — measured on three hosts: claude-haiku-4-5 (weak) shows the family-scoped lift (trapE 0.533→1.000, 7/7 discordant, corpus cost 1.71x); claude-sonnet-4-6 (strong) is a ceiling null; gpt-5-mini (non-Claude weak, codex prompt-prepend surface) FAILED replication with headroom (corpus Δ=+0.024 p=0.70, capability trend n.s. — no harm claimed, injection-surface confound documented). Therefore discipline_profile: auto enables the lift only where measured (vendor-granular unknown_defaults). Non-claims — the balanced router profile was removed after a NULL measurement (p=0.81, n=24); no full-tier recommendation exists; no cross-vendor lift is claimed. | quant | `docs/benchmark.md#REPLICATION FAILED` | ✅ |
 | Behavioural-eval coverage is measured per tier and CI-ratcheted so it can only rise; the current coverage and its gap are published, never implied as "264 evaluated skills". | qual | `src/scripts/skill_eval_coverage.ts#checkRatchet` | ✅ |
+| A hand-rolled, dependency-free BM25 + trigram lexical index resolves the "recalls but does not rank" gap: on the retrieval-precision corpus (9 keyword-overlapping-confuser tasks) it drives the mean top tie-set from 3.333 (the `_score` bucket scorer) to 1.0 — every needed decision uniquely top-ranked — with precision@1 and precision@5 unchanged at 1.0. Method: deterministic, model-free re-ranking of the SAME retrieved entry set; both scorers measured over the identical store via `measure_lexical_ranking.ts`. | quant | `internal/bench/reports/lexical-ranking.json` | ✅ |
 | The whole layer is compiled into host agents with zero runtime daemon. | qual | `docs/contracts/no-runtime-boundary.md#file-first, no-runtime suite` | ✅ |
-| 100 governed rules. | quant | `src/scripts/check_artefact_count_messaging.ts#Artefact-count messaging gate` | ✅ |
-| The second-brain substrate ships as continuity convenience; its cross-session task lift is unmeasured. A deterministic recall scorer + corpus exist (the rig), but no paired run has measured a lift, so no "second brain" capability claim is made until a backed lift entry exists. | qual | `docs/second-brain-scope.md#no measured task-lift` | ✅ |
-| 267 skills (README hero + feature list). | quant | `src/scripts/check_artefact_count_messaging.ts#Artefact-count messaging gate` | ✅ |
+| 103 governed rules. | quant | `src/scripts/check_artefact_count_messaging.ts#Artefact-count messaging gate` | ✅ |
+| On a deterministic multi-session recall corpus, the memory substrate produces a measured, placebo-controlled recall lift — memory-on 27/27 vs no-memory 10/27 and vs equal-byte placebo 9/27 (claude-haiku-4-5, n=9 tasks x 3 seeds, sign test p=0.031 for BOTH pairings). Scoped honestly: this is the context-value upper bound (perfect retrieval on a one-fact-per-task corpus), not retrieval precision under a large store. | quant | `internal/bench/reports/second-brain-delta.json` | ✅ |
+| Removing the perfect-retrieval assumption, the substrate's REAL keyword retrieval recalls the needed decision into the top-5 under keyword-overlapping confusers (precision@5 9/9) and the model disambiguates it from the co-injected confusers — retrieval-on 27/27 vs no-memory 5/27 and vs equal-count placebo 5/27 (claude-haiku-4-5, 9 tasks x 3 seeds, sign test p=0.008 both). Named limit: retrieval RECALLS but does not RANK (mean tie-set 3.3, ties broken by store order, not relevance) — the discrimination gap that motivates the SQLite-FTS5 activation path (ADR-116) at larger scale. | quant | `internal/bench/reports/second-brain-retrieval.json` | ✅ |
+| Every artifact the package ships — source AND the condensed projection that reaches consumers — is machine-scanned in CI for hidden-Unicode, mixed-script-confusable, and instruction-smuggling payloads (the rules-file-backdoor class); a finding blocks the release before `npm publish`, not just the merge. | qual | `.github/workflows/publish-npm.yml#lint_agent_security` | ✅ |
+| 270 skills (README hero + feature list). | quant | `src/scripts/check_artefact_count_messaging.ts#Artefact-count messaging gate` | ✅ |
 | 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` | ✅ |
 
-**12 backed claim(s)** — all evidence pointers resolve in CI.
+**16 backed claim(s)** — all evidence pointers resolve in CI.
 
 Artefact counts in public prose (skills, commands, governed rules,
 guidelines, personas) are **generated from source and CI-drift-checked**:
@@ -74,25 +78,36 @@ deliberately, not overnight.
 runway, RICE, incident command, messaging), but the skills are forged on
 TS/PHP — "promising, not proven" off those stacks. A disclaimer floor
 bounds *liability*, not *correctness*: a skill can be format-correct,
-disclaimered, and still embed a wrong domain assumption. Today **0 of 20**
+disclaimered, and still embed a wrong domain assumption. Today **9 of 20**
 default-surface domain skills carry a sourced `domain-truth` fixture
-(`./scripts-run src/scripts/domain_soundness_status`); all are labeled
-`unvalidated` and the validated count is CI-ratcheted. Authoring the
-answer keys needs domain competence (a cited method, not the skill's own
-output), so validation lands deliberately — the gap is published, never
-implied away.
-
-**Second-brain substrate — continuity convenience, task-lift unmeasured.**
-The memory substrate is built (working-memory continuity across
-compaction, promotable knowledge cards, contradiction surfacing), but
-whether it beats a no-memory baseline on a reproducible task is **not yet
-measured**. The measurement rig exists — a deterministic multi-session
-recall corpus + scorer (`./scripts-run src/scripts/second_brain_score
---dry-run`, no model-in-the-loop grading) — but the paired
-`memory-on`/`off`/`placebo` run is spend-bearing and pending. So no
-"second brain" capability claim is made anywhere; the substrate ships as
-continuity convenience until a paired run backs a lift. Boundary vs a
-human PKM is stated in [`docs/second-brain-scope.md`](second-brain-scope.md).
+(`./scripts-run src/scripts/domain_soundness_status`); the rest are labeled
+`unvalidated` and the validated count is CI-ratcheted. The fixtures landed
+so far are the **deterministic** targets (runway, unit-economics, DCF,
+forecasting, scenario band/sensitivity), whose answer keys are computed
+from cited standard formulas — never the skill's own output; the
+**rubric** targets (incident command, messaging, fundraising, editorial)
+need domain-competent grounding and remain unvalidated, so validation
+lands deliberately — the gap is published, never implied away.
+
+**Second-brain substrate — measured recall lift, honestly bounded.** On a
+deterministic multi-session recall corpus, the memory substrate beats a
+no-memory baseline AND an equal-byte placebo: memory-on **27/27** vs
+no-memory **10/27** vs placebo **9/27** (claude-haiku-4-5, 9 tasks × 3
+seeds, sign test **p = 0.031** for both pairings) — a real,
+placebo-controlled lift (`internal/bench/reports/second-brain-delta.json`).
+Scoped, not oversold: this is the context-value upper bound (perfect
+retrieval on a one-fact-per-task corpus), NOT retrieval precision under a
+large store; the lift concentrates exactly where memory is the only source
+and ties where the prompt self-contains the fact. Boundary vs a human PKM,
+and why the Obsidian export stays declined, are in
+[`docs/second-brain-scope.md`](second-brain-scope.md).
+
+A follow-up removed the perfect-retrieval assumption: against a store of
+keyword-overlapping confusers the REAL retrieval recalls the needed
+decision into the top-5 (9/9) and the model disambiguates it — retrieval-on
+**27/27** vs no-memory **5/27** and vs placebo **5/27** (p=0.008 both). The
+honest limit: the keyword scorer recalls but does not rank (mean tie-set
+3.3), which is the SQLite-FTS5 activation signal (ADR-116) at scale.
 
 ## 3. Known limits (published, witness-tested)
 

package/docs/release-runbook.md

@@ -37,6 +37,9 @@ the **workflow_dispatch** on `release.yml` (inputs: `bump`, `version`,
       to recover a partial run — see § 5).
 - [ ] You have read [`succession.md`](succession.md) if any secret-gated
       downstream (npm publish, cloud deploy) must succeed this release.
+- [ ] The release satisfies [`release-sizing.md`](contracts/release-sizing.md) —
+      one primary product goal, and a `Rollback:` line for every new /
+      substantially reworked subsystem (gate: `src/scripts/lint_changelog_rollback.ts`).
 
 ## 2. The pipeline — what `release.ts` does (9 steps)
 

package/docs/second-brain-scope.md

@@ -9,35 +9,70 @@
 > Roadmap: `road-to-second-brain-delta-proof`. Verdict of record:
 > `agents/settings/contexts/second-brain-delta-verdict.md` (council 2026-07-07).
 
-## The honest status (2026-07-08)
+## The honest status (2026-07-09 — measured PASS, bounded)
 
 The substrate is **built** (typed knowledge dirs, INDEX generator, retrieval
 protocol, `hot_context_hook` working-memory continuity across compaction,
-`fold_intake`, contradiction surfacing). What is **not yet measured** is the
-*delta*: whether agent-facing memory beats a no-memory baseline on a
-reproducible multi-session task.
+`fold_intake`, contradiction surfacing), and the cross-session recall *delta*
+is now **measured** — a real, placebo-controlled lift, honestly scoped.
 
-- **The measurement rig exists** — a deterministic multi-session recall corpus
+- **The measurement rig** — a deterministic multi-session recall corpus
   (`internal/bench/second-brain/corpus/`) + a scorer
-  (`src/scripts/second_brain_score.ts`) with no model-in-the-loop grading. It
-  dry-runs correctly and discriminatingly on hand-written transcripts.
-- **The paired run does not** — the 3-arm `memory-on` / `memory-off` /
-  `placebo` measurement (Phase 2) is spend-bearing and has not been run. So
-  there is **no measured task-lift**, and therefore **no "second brain"
-  capability claim** is made anywhere in public prose. This is the
-  falsifiability lock: the marker never outruns the evidence.
+  (`src/scripts/second_brain_score.ts`) with no model-in-the-loop grading.
+- **The paired run (Phase 2)** — `memory-on` / `memory-off` / `placebo` on a
+  fixed host (claude-haiku-4-5), 9 tasks × 3 seeds (81 calls). Result:
+  memory-on **27/27**, no-memory **10/27**, equal-byte placebo **9/27**;
+  memory-on beats BOTH, sign test **p = 0.031** for each pairing → **PASS**.
+  Full report: `internal/bench/reports/second-brain-delta.json`
+  (claim `second-brain-recall-lift`).
+- **Where the lift lives** — it concentrates on the retrieval-accuracy tasks
+  where the prior fact is available ONLY from memory (memory-on 3/3, baseline
+  0/3). It **ties** on the three tasks whose k+1 prompt already self-contains
+  the signal (a correction stated in-prompt, or a contradiction the prompt
+  names) — exactly where memory is not the only source. memory-on never loses.
 
-Until the paired run backs a lift, the substrate is documented as **continuity
-convenience** — it carries working memory across sessions and compaction — not
-a proven task-accuracy multiplier.
+### The scoping caveat (stated, not buried)
 
-## What it IS (by design; task-lift unmeasured)
+The Phase-2 delta is the **context-value upper bound**: the corpus is
+one-fact-per-task, so memory-on injects the exact fact (perfect retrieval). It
+shows that **the right prior fact, surfaced, lets the model answer — and that
+this beats both no memory and equal-byte noise** (the placebo isolates mechanism
+from mere extra context).
+
+**The retrieval-precision follow-up removed the perfect-retrieval assumption**
+(2026-07-09, claim `second-brain-retrieval-precision`,
+`internal/bench/reports/second-brain-retrieval.json`). Against a populated store
+whose distractors deliberately share query keywords with the needed decision,
+the REAL `memory_lookup` retrieval recalls the needed decision into the top-5 in
+**9/9** cases, and the model disambiguates it from the co-injected confusers —
+**retrieval-on 27/27 vs no-memory 5/27 and vs equal-count placebo 5/27**
+(sign test p=0.008 both). **Named limit (honest):** the keyword scorer
+**recalls but does not rank** — mean tie-set 3.3 entries share the top score,
+ties broken by store order, not relevance. So recall into the top-k holds *at
+this scale*; once more than k entries share a keyword it would degrade — which
+is exactly the discrimination gap the SQLite-FTS5 activation path (ADR-116)
+exists to close. The public claims are scoped to exactly this.
+
+**Second named limit (separator recall, found 2026-07-10 in a labelled replay
+of real maintainer queries):** `_score()` matches raw substrings, so a query
+key whose token separator differs from the stored field misses entirely —
+`ai_council`, `roadmap-progress`, `force-push` score 0 against space-normalized
+`key` fields that spaced variants (`ai council`) hit at 0.8. The precision
+measurement above did not probe this class (its confusers share exact
+keywords), so it is scoped OUT of the precision claim. Deliberately not
+hot-fixed: naive scoring is locked until the scale tripwire (the archived
+retrieval-economy roadmap's D5), and the FTS5 unicode61 tokenizer splits on
+separators, closing this structurally at activation time. Reproduce:
+`memory_lookup --types product-rules --key "ai_council"` vs `--key "ai council"`
+against any populated store.
+
+## What it IS (measured lift, bounded as above)
 
 | Capability | What it does | Evidence status |
 |---|---|---|
-| Working-memory continuity | `hot_context_hook` re-injects a bounded, deterministic cache across session boundaries and Claude Code compaction | mechanism shipped; task-lift **unmeasured** |
-| Promotable knowledge cards/pages | typed dirs + INDEX + retrieval protocol, with redaction + team-share gate | mechanism shipped; task-lift **unmeasured** |
-| Contradiction surfacing | a session that contradicts a prior decision is flagged on promote | mechanism shipped; catch-rate **unmeasured** |
+| Working-memory continuity | `hot_context_hook` re-injects a bounded, deterministic cache across session boundaries and Claude Code compaction | mechanism shipped; recall lift **measured (bounded PASS)** |
+| Promotable knowledge cards/pages | typed dirs + INDEX + retrieval protocol, with redaction + team-share gate | mechanism shipped; recall lift **measured (bounded PASS)** |
+| Contradiction surfacing | a session that contradicts a prior decision is flagged on promote | mechanism shipped; ties in-prompt, lift where memory is the only source |
 
 ## What it is NOT
 
@@ -52,15 +87,23 @@ a proven task-accuracy multiplier.
   link-density, hybrid human-facing retrieval — is a *different product* for a
   *different consumer* (a person, not an agent). This package writes
   agent-facing memory; it does not serve a human graph browser.
-- **Not a measured accuracy multiplier** — see the honest status above.
+- **Not an unbounded accuracy multiplier** — the recall lift is measured but
+  scoped to the context-value upper bound (see honest status), not proven
+  retrieval precision under a large store.
 
-## Interop, not competition (gated on a measured lift)
+## Interop, not competition (export declined, on the record)
 
-If — and only if — the Phase-2 paired run shows a real lift, the sanctioned
-next step is a **one-way export** (promoted cards → plain Obsidian-compatible
-Markdown + wikilinks), positioning agent-config as the *writer* and a human PKM
-as the *reader*: complementary, never a replacement. Absent a measured lift,
-the exporter is not built.
+The Phase-2 paired run did show a real (bounded) lift, which unlocks the
+optional one-way export (promoted cards → Obsidian-compatible Markdown). It is
+**deliberately not built**: the delta-verdict of record
+(`agents/settings/contexts/second-brain-delta-verdict.md`, council 2026-07-07)
+**rejected** Obsidian compatibility — the dual-write hazard (an external edit
+that never commits silently diverges the INDEX + recurrence counters) outweighs
+the browsing convenience, and the measured lift is a bounded context-value
+result, not a retrieval-precision proof that would justify a new external
+surface. If a human-PKM bridge is ever wanted, the sanctioned path is a
+read-only static render, not an editable vault. Positioning stays: agent-config
+writes agent-facing memory; it does not replace a human PKM.
 
 ## Verify
 

package/docs/self-review-gate.md

@@ -0,0 +1,51 @@
+# Self-review gate (dogfooded PR review)
+
+The package reviews its own PRs with the exact machinery it ships —
+[`adversarial-review`](../src/skills/adversarial-review/SKILL.md) +
+[`agent-security-review`](../src/skills/agent-security-review/SKILL.md) — via
+[`.github/workflows/self-review-gate.yml`](../.github/workflows/self-review-gate.yml)
+and [`src/scripts/self_review_gate.ts`](../src/scripts/self_review_gate.ts).
+
+`road-to-maintainer-bus-factor` Phase 1.
+
+## Current status — ADVISORY, inert without a secret
+
+This is an **honest floor, not independent human review**, and today it is
+**advisory + inert-without-secret**. Do not read it as "every PR is
+AI-reviewed" — that is only true once the maintainer arms it (below).
+
+| Job | Runs | Spend | Blocks merge |
+|---|---|---|---|
+| `gate-dry-run` | every PR | none (no API) | never — prints the review plan only |
+| `live-advisory` | every PR **iff** `ANTHROPIC_API_KEY` is set | one review call | never — posts findings, records what *would* block |
+
+Without the `ANTHROPIC_API_KEY` repo secret, `live-advisory` is a **logged
+no-op** (never a failing check) — exactly the `cross-model-canary.yml` pattern.
+
+## The teeth (defined + wired, not yet armed)
+
+`self_review_gate.ts` exposes pure, unit-tested:
+
+- `classifyBlocking(finding)` — a finding is merge-blocking **iff**
+  `kind ∈ {security, claim}` **and** `severity ∈ {critical, high}`. Style and
+  correctness findings, and low/medium security findings, advise only. (Council
+  2026-07-08, claude-sonnet-4-5 + gpt-4o: a 100 %-blocking gate at
+  solo-maintainer token cost gets ignored or gamed — block only on the narrow
+  security/claim × high+ intersection.)
+- `gateVerdict(findings, {enforce})` — mirrors
+  `check_quality_regression.gateVerdict`: `0` pass / `2` block. Shipped
+  `enforce: false` (advisory always returns `0` and reports the would-block
+  set).
+
+## Arming it (maintainer, one flip)
+
+1. Add the `ANTHROPIC_API_KEY` repo secret (per-PR budget sign-off) — turns
+   `live-advisory` from no-op into a real dogfooded review.
+2. Pass `--enforce` in the live job to arm the teeth (block on
+   security/claim × high+).
+3. Require the `Self-review gate` check in branch protection
+   (`road-to-maintainer-bus-factor` Phase 2) so even solo merges pass the gate.
+4. Record the floor CLAIM on the proof page **once it is live** — not before
+   (an inert gate is not a passed gate).
+
+Blocker `self-review-gate-cost` (maintainer-owned) gates steps 1–2.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@event4u/agent-config",
-    "version": "8.8.0",
+    "version": "8.10.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/agent-src/scripts/update_roadmap_progress.ts

@@ -67,8 +67,9 @@ const _require = createRequire(import.meta.url);
 // CHECKBOX_RE = re.compile(r"^\s*[-*]\s+\[([ xX~\-])\]\s", re.MULTILINE)
 const CHECKBOX_RE = /^[ \t\n\r\f\v]*[-*][ \t\n\r\f\v]+\[([ xX~\-])\][ \t\n\r\f\v]/gm;
 // PHASE_RE (MULTILINE) — H2/H3 "Phase <id>" with optional separator + name.
+// Numeric ids accept dotted sub-phases ("1.0", "4.1", "2.3.1").
 const PHASE_RE =
-    /^(#{2,3})[ \t\n\r\f\v]+Phase[ \t\n\r\f\v]+(\d+[a-z]?|[IVX]+|[A-Z](?:\d+)?)(?:[\s:—\-]+([\s\S]*?))?[ \t\f\v\r]*$/gm;
+    /^(#{2,3})[ \t\n\r\f\v]+Phase[ \t\n\r\f\v]+(\d+(?:\.\d+)*[a-z]?|[IVX]+|[A-Z](?:\d+)?)(?:[\s:—\-]+([\s\S]*?))?[ \t\f\v\r]*$/gm;
 // TITLE_RE = re.compile(r"^#\s+(?:Roadmap:\s*)?(.+?)\s*$", re.MULTILINE)
 const TITLE_RE = /^#[ \t\n\r\f\v]+(?:Roadmap:[ \t\n\r\f\v]*)?(.+?)[ \t\f\v\r]*$/m;
 const EXCLUDE_NAMES: ReadonlySet<string> = new Set([

package/src/scripts/_dispatch.bash

@@ -167,6 +167,12 @@ Tier 2 — maintenance / internal (hooks, MCP, memory, telemetry):
   mcp:run                    Run the built-in MCP server over stdio
                              (requires `mcp:setup` first; see docs/mcp-server.md)
                              (experimental — beta gates: docs/contracts/mcp-beta-criteria.md)
+  affected                   Show artefacts related to <artefact> via the discovery
+                             relation-graph (relation-filtered BFS). Flags: --depth N
+  graph-explain              Seed on a <concept>, expand 2 hops over the discovery
+                             relation-graph with a node budget. Flags: --budget N
+  benchmark                  Report context-token reduction vs the full always-loaded
+                             projection (from the pinned token baseline). Flags: --format
   roadmap:progress           Regenerate agents/roadmaps-progress.md from open roadmaps
   roadmap:progress-check     Fail if agents/roadmaps-progress.md is stale (for CI)
   roadmap:archive            Archive completed roadmaps (branch-touched by default;
@@ -431,6 +437,24 @@ cmd_mcp_render() {
   exec_ts "$script" "$@"
 }
 
+cmd_affected() {
+  local script
+  script="$(resolve_script "src/scripts/discovery_graph.ts")"
+  exec_ts "$script" affected "$@"
+}
+
+cmd_graph_explain() {
+  local script
+  script="$(resolve_script "src/scripts/discovery_graph.ts")"
+  exec_ts "$script" explain "$@"
+}
+
+cmd_benchmark() {
+  local script
+  script="$(resolve_script "src/scripts/benchmark.ts")"
+  exec_ts "$script" "$@"
+}
+
 cmd_mcp_check() {
   local script
   script="$(resolve_script "src/scripts/mcp_render.ts")"
@@ -1031,6 +1055,9 @@ main() {
     mcp:setup)               cmd_mcp_setup "$@" ;;
     mcp:run)                 cmd_mcp_run "$@" ;;
     use)                     cmd_use "$@" ;;
+    affected)                cmd_affected "$@" ;;
+    graph-explain)           cmd_graph_explain "$@" ;;
+    benchmark)               cmd_benchmark "$@" ;;
     roadmap:progress)        cmd_roadmap_progress "$@" ;;
     roadmap:progress-check)  cmd_roadmap_progress_check "$@" ;;
     roadmap:archive)         cmd_roadmap_archive "$@" ;;