@event4u/agent-config 14.22.0 → 15.0.0

package/dist/agent-src/contexts/execution/user-memory-channels.md

@@ -18,7 +18,7 @@ behaviour was to detect it and throw it away. It now has a second
 destination: `~/.event4u/agent-config/user/observations.jsonl`, the global
 observation buffer from ADR-138's sibling phase — mirroring, one level up,
 the project-local `.agent-user.observations.jsonl` contract in
-[`agent-user-schema.md § Observation buffer`](../../../docs/contracts/agent-user-schema.md#observation-buffer).
+[`agent-user-schema.md § Observation buffer`](../../docs/contracts/agent-user-schema.md#observation-buffer).
 
 **The project-scoped rule in Phase 3 (CONSOLIDATE) is unchanged.** No user
 fact enters `agents/memory/` curated YAML through this or any other path —
@@ -73,7 +73,7 @@ than at review, and from reusing the existing redaction gate verbatim:
   birthdays · financial figures · health / legal / therapy status ·
   demographics · external-source identifiers — refused when the
   observation is captured, per
-  [`agent-user-schema.md § Explicit exclusions`](../../../docs/contracts/agent-user-schema.md#explicit-exclusions).
+  [`agent-user-schema.md § Explicit exclusions`](../../docs/contracts/agent-user-schema.md#explicit-exclusions).
 - **Hidden unicode.** Every write routes through
   `knowledge_global_redaction.redaction_scan`, including its
   `hidden_unicode` class (the ADR-103 zero-width-smuggling detector) — the
@@ -120,7 +120,7 @@ against the project root once, during ORIENT:
   `seen_in[]` recurrence tally to the fact and appends it to the SAME
   global buffer Phase 2 uses — never a second store, never a
   project-indexed directory (the council's round-2 namespace refusal; see
-  [`agent-user-schema.md § Project attribution`](../../../docs/contracts/agent-user-schema.md#project-attribution-road-to-global-user-memory-phase-3)).
+  [`agent-user-schema.md § Project attribution`](../../docs/contracts/agent-user-schema.md#project-attribution-road-to-global-user-memory-phase-3)).
 
 **This is the only generalisation path.** A fact recurring in a
 *different* unmanaged project (Jaccard similarity ≥ `MERGE_THRESHOLD`,

package/dist/agent-src/contexts/execution/verification-mechanics.md

@@ -96,6 +96,6 @@ on the follow-up PR.
 ### Examples
 
 Wrong/right/why demos (hedged claims, trusting earlier runs,
-partial-verification creep): [`verify-before-complete-demos`](../../../../docs/guidelines/agent-infra/verify-before-complete-demos.md).
+partial-verification creep): [`verify-before-complete-demos`](../../guidelines/agent-infra/verify-before-complete-demos.md).
 Outcome baseline:
 [`tests/golden/outcomes/verify_before_complete.json`](../../../../tests/golden/outcomes/verify_before_complete.json).

package/dist/agent-src/contexts/judges/persona-voice-rubric.md

@@ -133,8 +133,8 @@ files `contexts/judges/no-consolidate-rationale.md`.
 
 ## References
 
-- [`docs/contracts/context-paths.md`](../../../docs/contracts/context-paths.md)
+- [`docs/contracts/context-paths.md`](../../docs/contracts/context-paths.md)
   — locked path tree (this file lives at `contexts/judges/`).
-- [`docs/contracts/load-context-schema.md`](../../../docs/contracts/load-context-schema.md)
+- [`docs/contracts/load-context-schema.md`](../../docs/contracts/load-context-schema.md)
   — frontmatter contract for citing this rubric from a slimmed `judge-*`
   skill in Phase 3a.2.

package/dist/agent-src/guidelines/abstraction-thresholds.md

@@ -0,0 +1,88 @@
+# Abstraction Thresholds — the per-class canon
+
+> The single source of truth for "how many repetitions before you extract". Every
+> other artifact that states a numeric extraction threshold cites this table and
+> names its artifact class — a bare number outside this file is drift
+> (enforced by `src/scripts/lint_abstraction_thresholds.ts`).
+
+_Origin: council convergence 2026-08-03 (claude-sonnet-4-5 + gpt-4o, unanimous), recorded in ADR-213. Before this file, four artifacts stated four bare numbers (2 / 3+ / ≥4 / ≥3) with no scope tags — an agent loading them together received contradictory instructions._
+
+## Why the bars differ — cost scales with the artifact class
+
+Extracting a pure helper function is a near-zero-cost act; extracting a stateful
+UI component creates a file, a props contract, and a test surface. The threshold
+is a price signal: the heavier the extraction, the more proven repetition it
+must buy. These are **deliberately different bars for different acts**, not
+editorial drift.
+
+## The canon
+
+| Artifact class | Concrete tag (what to check) | Threshold |
+|---|---|---|
+| **Code-level abstraction** — helper, method, class, Strategy, generic, config layer | any non-UI code shape | **2 real repetitions** (or a genuine second axis of change) |
+| **Pure-markup UI shell** — props-only fragment, no state (button shell, card frame, header) | renders props, holds no state | **3+ uses** |
+| **Stateful UI component** — carries real props/state (form, table, filter) | repeats **AND** has varying props / local state | **~4+ repeats AND real state** (both conditions) |
+| **Utility-class string** (Tailwind et al.) — repeated class list | identical class string | **≥ 3 duplications** (mechanism table: [`tailwind-engineer`](../skills/tailwind-engineer/SKILL.md)) |
+
+The code-level bar of **two** is this suite's settled base decision (the
+borrowed "Rule of Three" for code was evaluated and not adopted — see
+[`minimal-safe-diff-mechanics`](agent-infra/minimal-safe-diff-mechanics.md)).
+The UI rows are scoped carve-outs **above** that base bar, never a license to
+lower it.
+
+## The qualitative floor — applies to every row
+
+A number alone never justifies an extraction. In every class, a reviewer must
+be able to name the **concrete duplication or the concrete second axis of
+change** the abstraction removes. One occurrence is not a component; one branch
+is not a Strategy; a repeat with no varying props is inlined, not extracted.
+
+## Precedence
+
+[`minimal-safe-diff`](../rules/minimal-safe-diff.md) / YAGNI win on every
+conflict: these thresholds authorize extraction when repetition is **already
+present in the diff** — never speculative abstraction for "this could grow
+later". See [`component-oriented-and-oop-development`](component-oriented-and-oop-development.md)
+§ The load-bearing caveat.
+
+## The provided-artifact clause — repetition observable before the code exists
+
+ADR-213 authorises extraction on repetition **already present in the diff**. A
+handed-over **runnable** artifact makes repetition observable before any code
+exists at all: four `<Card>` instances are visible in the handover, so a port
+that writes them one at a time and extracts on the second is doing the
+threshold's own arithmetic in the wrong order.
+
+This is a **different mechanism** than the one the threshold tested, not a
+loophole in it. `adr_cite_check ADR-213` reports the record LIVE with an
+**indeterminate** review trigger and `reopen_policy: unclassified`, so
+investigation is permitted; the numbers themselves — 2 · 3+ · ~4+ — are
+**unchanged**, and this clause moves only *when* the count may be taken.
+
+**Two guards, both required. The first alone is insufficient.**
+
+1. **A runnable artifact, not a design comp.** A comp shows a picture of four
+   cards; a runnable artifact carries four instances of a thing. Counting
+   rectangles in an image is not counting repetition, and a comp therefore does
+   not qualify.
+2. **Repetition of the ELEMENT, not of its compositional context.** Four
+   `<Card>` instances show that Card is used four times. They do **not** show
+   that a `CardGrid` is needed — that needs multiple distinct contexts each
+   arranging several cards. Without this guard the clause would license
+   extracting a wrapper for every layout the artifact happens to contain once,
+   which is speculative abstraction with an artifact as its excuse.
+
+**Enforcement, stated honestly: guard (2) is model-carried and audit-enforced.**
+Nothing mechanical separates *"I saw four Cards"* from *"I saw a CardGrid
+pattern"* — the distinction is about what the repetition MEANS, and
+`lint_abstraction_thresholds.ts` checks numeric threshold drift, which is a
+different property. Guard (1) is checkable (is the handover runnable), guard (2)
+is not, and claiming otherwise would be the coverage inflation this tree forbids
+elsewhere. The discipline is the control.
+
+## See also
+
+- [`architecture`](../rules/architecture.md) — the rule that carries the code-level bar.
+- [`fe-design`](../skills/fe-design/SKILL.md) § Component granularity — the UI-shell bar in context.
+- [`ui-component-architect`](../skills/ui-component-architect/SKILL.md) § Componentization threshold — the stateful-component bar in context.
+- ADR-213 — the decision record scoping the bars.

package/dist/agent-src/guidelines/agent-infra/5w2h-analysis.md

@@ -0,0 +1,260 @@
+# 5W2H Analysis
+
+Reference guideline for Wing-1 deep-thinking work — the 5W2H systematic
+questioning method (What · Why · Who · When · Where · How · How-much) for
+comprehensive understanding of any topic, problem, or plan. Adopted under
+the **Reference-Guideline Sunset Policy** (see frontmatter `upstream` /
+`refresh_trigger` keys) and cross-referenced from:
+
+- [`deep-reading-analyst`](../../skills/deep-reading-analyst/SKILL.md)
+  — L1 Quick analysis depth.
+- [`refine-ticket`](../../skills/refine-ticket/SKILL.md)
+  — completeness check on a Jira / Linear ticket before estimation.
+- [`bug-investigate`](../../../src/domains/engineering-base/bug/investigate/command.md)
+  — gap analysis on an incident report before forming a hypothesis.
+
+> **Core principle:** "Quality of decisions equals quality of questions
+> asked." — 5W2H captures essence in seven dimensions.
+
+## When to Use
+
+Ideal for:
+
+- 📋 Quickly understanding complete article information
+- 🔍 Discovering information gaps and omissions
+- 📊 Evaluating plan feasibility
+- 💼 Analyzing business cases and proposals
+- 📝 Organizing complex information
+- ✅ Verifying information completeness
+
+Do **not** use when the user wants depth on a single dimension (use
+[`mental-models`](mental-models.md)) or pre-mortem on failure paths
+(use [`inversion-thinking`](inversion-thinking.md)).
+
+## The 7 Questions in Detail
+
+### W1: What (Content)
+
+**Core questions:**
+
+1. What is the main topic?
+2. What are the key claims / conclusions?
+3. What solutions are proposed?
+4. What core concepts are involved?
+5. What are the expected outcomes?
+
+**Deep inquiry:** What is the real problem? What is missing? What
+could go wrong? What are the alternatives?
+
+### W2: Why (Reasons)
+
+**Core questions:**
+
+1. Why discuss this topic now?
+2. Why is this solution effective?
+3. Why not choose other approaches?
+4. Why should the audience care?
+5. Why this timing?
+
+**Five Whys technique** — ask "why" five times to reach root cause:
+
+```
+Problem: [Surface issue]
+→ Why 1: [First layer]
+  → Why 2: [Second layer]
+    → Why 3: [Third layer]
+      → Why 4: [Fourth layer]
+        → Why 5: [Root cause] ← Real issue
+```
+
+### W3: Who (People)
+
+**Core questions:**
+
+1. Who is the target audience?
+2. Who are the stakeholders?
+3. Who is responsible for execution?
+4. Who benefits? Who loses?
+5. Whose expertise / cases are cited?
+6. Who is the author? (potential biases?)
+
+**Deep analysis:** stakeholder mapping · decision-makers vs. executors
+· who has veto power.
+
+### W4: When (Timing)
+
+**Core questions:**
+
+1. When to start?
+2. What is the timeline / schedule?
+3. When will results appear?
+4. How time-sensitive is this?
+5. When are key decisions needed?
+6. What is the historical context?
+
+**Time-trap identification:** unrealistic time expectations · missing
+key milestones · buffer time considered.
+
+### W5: Where (Context)
+
+**Core questions:**
+
+1. Where does this apply? (geography, industry, organization)
+2. Where is execution happening?
+3. Where to get resources?
+4. What are the limitations / constraints?
+5. What is the scope of impact?
+
+**Context dependency:** does it work in different environments? ·
+cultural differences · scale considerations.
+
+### H1: How (Methods)
+
+**Core questions:**
+
+1. What are the specific steps?
+2. What tools / methods are used?
+3. How to measure progress?
+4. How to handle obstacles?
+5. How to ensure quality?
+6. How to get started?
+
+**Process mapping:**
+
+```
+[Start] → [Step 1] → [Decision Point]
+                         ↓ Yes / ↓ No
+                    [Step 2A]  [Step 2B]
+                         ↓         ↓
+                    [Step 3] ← [Converge]
+                         ↓
+                    [End]
+```
+
+### H2: How Much (Metrics)
+
+**Core questions:**
+
+1. What is the cost? (money, time, opportunity, learning)
+2. How many resources needed?
+3. What is the expected ROI?
+4. What is the scale / magnitude?
+5. How big are the risks?
+6. What are the target metrics?
+
+**ROI analysis:**
+
+```
+Investment:
+- Direct costs:   [$]
+- Indirect costs: [$]
+- Total:          [$]
+
+Returns:
+- Expected benefit: [$]
+- Timeframe:        [X months]
+- ROI = (Benefit - Cost) / Cost × 100%
+
+Worth it?: [Yes / No]
+```
+
+## Complete Analysis Template
+
+### Quick version (15 min)
+
+```markdown
+# 5W2H Quick Analysis: [Article Title]
+
+**What**:     [One-line topic and solution]
+**Why**:      [Core motivation and value]
+**Who**:      [Target audience and executors]
+**When**:     [Timeline and urgency]
+**Where**:    [Applicability and context]
+**How**:      [Key steps (3–5)]
+**How much**: [Main costs and expected returns]
+
+## Gap Analysis
+
+Missing information: [List unanswered questions from 5W2H]
+Key risks:           [Risks based on missing info]
+```
+
+### Deep version (60 min)
+
+```markdown
+# 5W2H Deep Analysis: [Article Title]
+
+## 📋 What — Content Analysis
+[Detailed breakdown…]
+
+## 🎯 Why — Reason Analysis
+[Detailed breakdown…]
+[Five Whys analysis]
+
+## 👥 Who — People Analysis
+[Detailed breakdown…]
+[Stakeholder map]
+
+## ⏰ When — Time Analysis
+[Detailed breakdown…]
+[Timeline visualization]
+
+## 🌍 Where — Context Analysis
+[Detailed breakdown…]
+[Applicability matrix]
+
+## 🔧 How — Method Analysis
+[Detailed breakdown…]
+[Process flowchart]
+
+## 💰 How Much — Cost-Benefit Analysis
+[Detailed breakdown…]
+[ROI calculation]
+
+## 📊 Overall Assessment
+
+### Information completeness
+- ✅ Clearly answered:   [X / 7]
+- ⚠️  Partially answered: [List]
+- ❌ Completely missing: [List]
+
+### Feasibility score
+Based on 5W2H completeness: [X / 10]
+
+### Risk level
+Based on missing info: [High / Medium / Low]
+
+### Action recommendations
+1. [Specific recommendation based on analysis]
+2. [Information needed to supplement]
+3. [Priority actions to take]
+```
+
+## Integration with Other Frameworks
+
+### + Critical Thinking
+
+```
+5W2H              → Identify missing information
+Critical Thinking → Evaluate quality of existing information
+```
+
+### + SCQA
+
+```
+SCQA  → Understand problem framework
+5W2H  → Analyze solution completeness
+```
+
+### + Inversion
+
+```
+5W2H      → Forward analysis of plan
+Inversion → For each W / H, ask "what if it's missing?"
+```
+
+---
+
+## ADOPT citation
+
+Adapted from an external reference.

package/dist/agent-src/guidelines/agent-infra/active-remediation-mechanics.md

@@ -0,0 +1,99 @@
+# Active Remediation — Mechanics
+
+> Ladder detail, version-gated modernization, and anti-nagging guardrails for the `active-remediation` rule
+
+_Origin: migrated from `src/rules/active-remediation.md` per the P4 pattern of `road-to-kernel-and-router.md`. The Iron Law, the ladder tier names, and the live-security carve-out stay in the rule; this file carries the per-tier criteria and the modernization gates._
+
+## The ladder — classify, then act
+
+### Fix now (autonomous, inline) — a bounded amendment to `minimal-safe-diff`
+
+Allowed **only** when ALL hold — this is the testable "small + task-aligned" definition:
+
+- **Same request path / module** as the current task (not an unrelated feature).
+- **≤ ~10 changed lines** in one production file plus its test file — no wider cross-file ripple.
+- **No public-API / response-shape change**, no new parameter.
+- **No dependency bump, no migration, no data change.**
+- **Its verification ships in the same commit** — e.g. the security fix's negative test, or the correctness fix's case.
+
+Under those constraints the fix is auditable in the same diff and is *not* scope creep — it corrects a boundary the agent touched. Anything outside them → the fix is **note + ask**, never auto. (`minimal-safe-diff` still governs everything else: no reformatting, no opportunistic refactor, no drive-by rename.)
+
+### Note + ask (batched)
+
+Bigger, or diverges from the task → do **not** refactor inline, do **not** interrupt the flow. Note the site (file:line + the issue). Surface the batch as **one** numbered-options prompt (per `user-interaction`, one recommendation line) **after the task is delivered** — or mid-work only when the flow makes it natural. Each option must carry a real trade-off (`no-cheap-questions`). Refactor only on an explicit yes, as a separate scoped change (`scope-control`, `downstream-changes`).
+
+#### Option anatomy — a pickable fix, not a yes/no
+
+The user should be able to answer with one number and get a change they can predict. Each numbered option therefore names four things, in a line or two:
+
+1. **What changes** — the concrete edit, in the vocabulary of the code ("replace the three `array()` literals with `[]`", not "clean up the file").
+2. **Where** — file, or the group of files if the option covers a batch.
+3. **How large** — line count or an honest size class, so the user can weigh it without opening the diff.
+4. **What it costs** — the risk, the review burden, or the reason it was not simply done inline.
+
+Group findings by **fix shape**, never one option per finding: seven lint errors that are three `no-unused-vars`, three `prefer-const` and one genuine type hole are three options, not seven. The final option is always an explicit **leave it as is** — its absence is what turns a menu into pressure. One recommendation line under the block names your pick (`user-interaction` Iron Law 1).
+
+#### Carry-over — undecided is not finished
+
+An item the user has not answered stays live: raise it once more at the next natural task boundary, in the same batched form. Two bounds keep that from becoming nagging:
+
+- **A decline is terminal.** An explicit "leave it" / "ignore" closes the item for the task; re-raising it is the re-ask `scope-control` § Decline = silence forbids.
+- **Once per boundary, not once per reply.** The batch is a task-close artifact. Repeating it between steps is the continuation prompt `no-cheap-questions` Iron Law 4 forbids.
+
+### Propose a follow-up PR (many spots)
+
+When the issues are too many to fold in without blowing the current diff's scope, propose **one or more separate follow-up PRs** (or a roadmap under `agents/roadmaps/`, using the shared-prefix convention) so the user reviews the changes before merge. Creating the PR/roadmap is **permission-gated** — propose, get a yes, then create (`scope-control`, `commit-policy`).
+
+## Observed failing checks — classifying the red you already have
+
+The rule puts a check result you have already seen into the same ladder as a defect you read in a file. Running a command, reading seven errors, and walking past them is not scoping the work — it is looking away.
+
+The rule's two bounds, in full:
+
+- **Only output you already have.** The clause never obliges a check run; it fires on a result already in front of you. What runs locally stays the user's call — this package records "no proactive quality tools, remote CI gates only" as a standing preference — and the remote CI remains the authoritative gate. An obligation to *hunt* for red would contradict that outright; an obligation not to walk past red you already read does not.
+- **Ownership picks the tier, never the silence.** Caused by your diff → it is the task. Pre-existing and inside the fix-now bar → fix it. Pre-existing and wider, or many, or unrelated → note + ask, or a follow-up PR. There is no seventh option called "mention it in the closing summary" — that line reads as a status report and closes nothing.
+
+Classification is the whole of the work, and it runs on two axes:
+
+| | Inside the fix-now bar | Outside it |
+|---|---|---|
+| **Caused by this diff** | Fix it — it is the task, not remediation. | Fix it; a diff you cannot make green is not deliverable. Blocked → surface it as a blocker, never as a caveat. |
+| **Pre-existing** | Fix it with the work, and say in the commit body that it was pre-existing. | Note + ask with candidate fixes, or a follow-up PR when the batch is large. |
+
+Two failure shapes this table exists to name:
+
+- **"Not mine, so not mentioned."** Pre-existing red is the most common thing an agent walks past, because `minimal-safe-diff` reads like permission to ignore it. It is not: that rule bounds the *diff*, this one bounds the *silence*. The two are satisfied together by noting the finding and asking, which changes no line of code.
+- **"Mine, so quietly worked around."** A gate that goes green because the check was narrowed, an assertion loosened, or a file excluded is a defect with a green light on top. Route it through the ladder as an issue, and say what was narrowed.
+
+### Worked example — a red gate seen mid-task
+
+> the `check` task fails; the lint step reports 7 errors, all pre-existing on `main`, in files this branch does not touch.
+
+Wrong, and the canonical shape of it: finish the task, and close with *"the only thing still open is the lint finding — 7 errors on main, which makes the `check` task unusable as a chain"*. The sentence is accurate, the issue is named, and nothing about it is decided — the next session inherits it verbatim.
+
+Right: the errors are pre-existing, outside the fix-now bar (unrelated files, more than ~10 lines), so they are **note + ask** — after the task is delivered, one block:
+
+1. Fix the 3 `no-unused-vars` in `src/a.ts`, `src/b.ts` — ~6 lines, mechanical, ships in this PR.
+2. Fix all 7 in a separate follow-up PR — keeps this diff single-purpose; needs a branch (permission-gated).
+3. Suppress the two in generated output with a scoped ignore, fix the rest — smallest green path, adds a suppression to review.
+4. Leave as is — the `check` task stays unusable as a chain until someone else picks it up.
+
+One recommendation line names the pick. Whatever the user answers, the item is closed. If they answer nothing, it is raised once at the next task boundary — not carried silently into a third session.
+
+## Version-gated modernization
+
+Update stale idioms to the version the project **actually runs** — but only when that version is **verified**:
+
+- **Establish the version first** from the manifest constraint (`composer.json` `require`, `package.json` `engines`, `.tool-versions`, lockfile) — use the **lowest** bound; on an ambiguous/monorepo range, ask once. **Unknown version → do not touch** (must fit the project structure — this is the `source-discovery` gate).
+- **Syntax-only, behavior-preserving idioms** (e.g. `array()` → `[]`, `isset($x)?$x:$d` → `$x ?? $d`, string concat → template) that are provably equivalent → treat as a small fix (auto per the ladder).
+- **Behavioral changes** (`readonly`/typed properties, new language semantics) and **any dependency/version bump** → **ask only**, never auto (a version bump stays under `minimal-safe-diff`'s no-dependency-bump prohibition; a pure syntax idiom is categorically different).
+
+## Guardrails — don't become a nagging machine
+
+- Subordinate to `no-cheap-questions` (self-check items 3 & 14 — real trade-off, not a disguised continuation/commit ask), `autonomous-execution` (the end-of-session batch must not read as "shall I continue?"), `user-interaction`, `ask-when-uncertain` (one batched prompt = one question).
+- Threshold to surface at all: a **real, nameable** improvement with a concrete benefit. Cosmetic nitpicks with no trade-off → drop silently. The live-security carve-out is the only case that interrupts or overrides autonomy.
+
+## See also
+
+- [`active-remediation`](../../rules/active-remediation.md) — the rule this file details (Iron Law + ladder + live-security carve-out).
+- [`minimal-safe-diff`](minimal-safe-diff-mechanics.md) — the diff-shape mechanics the fix-now tier amends.