@event4u/agent-config 14.23.0 → 16.0.0

package/dist/agent-src/guidelines/agent-infra/corpus-grounding-authoring.md

@@ -0,0 +1,91 @@
+# Corpus-grounding authoring guide — qualification, shape, governance
+
+> The gate every new domain corpus passes before it enters
+> `src/skills/<skill>/data/`. Architecture: ADR-061; engine + manifest
+> contract: [`corpus-grounding`](../../skills/corpus-grounding/SKILL.md).
+
+## 1. Qualification checklist — ALL must hold
+
+- [ ] **Decision-rule utility test.** The domain's *selection/constraint*
+  decision is externalizable as auditable rules that **beat the agent's
+  priors**. 8 rows with strong conditionals beat 300 flat rows — row
+  count is never the argument.
+- [ ] **Before-action test.** Grounding constrains the option space
+  *before* the agent acts. Mid-action lookup is **reference** (→
+  `references/` / RAG); post-action checking is **validation** (→ a
+  rule/linter); the procedure itself is **method** (→ a framework skill).
+  Route each to its mechanism — never the corpus.
+- [ ] **"Fits in 5 lines" test.** If the knowledge compresses into ≤5
+  lines of an always-on rule, write the rule. A corpus that thin is
+  grounding theater.
+- [ ] **Owner + cadence.** A named maintainer and a refresh cadence are
+  declared in the manifest (`owner`, `refresh_cadence`) — the engine's
+  schema validator refuses manifests without them. Unowned corpora rot;
+  they are not merged (domain-adoption Gate 2).
+- [ ] **Provenance pin.** `upstream{repo, sha, last_checked}` names the
+  authoritative source and its version (git SHA, spec version like
+  "ATT&CK v16" / "WCAG 2.2", or vendor-doc date).
+- [ ] **Evidence gate for conditional candidates.** Domains on the
+  *conditional* list (architecture-pattern selection, finance method
+  selection) additionally require the change-my-mind anchor: the corpus
+  measurably beats the existing framework skill over **≥10 real
+  sessions**. Until then they stay `[~]` deferred.
+
+## 2. Shape — what a domain ships
+
+```
+src/skills/<domain-skill>/data/
+  manifest.json     # schema-agnostic plug-in (see corpus-grounding SKILL.md)
+  <axis>.csv        # the corpus — domain declares its OWN columns
+```
+
+- Tier honestly: `lookup-only` (search + rule columns the agent applies)
+  is the right starting tier for most domains; `conditional-grounding`
+  (engine-evaluated reasoning map + decision rules) only when a natural
+  category→rules two-stage exists; `constraint-emission` only for mature
+  directive-integrated domains (frontend).
+- Every output carries `confidence` + `evidence_gap` — engine-enforced.
+- Consultation default (Tier 1): the skill queries, proposes grounded
+  options, the human confirms. Directive integration is the exception,
+  not the goal ("directive engines everywhere" = orchestration envy).
+- Validate before merge:
+  `./scripts-run src/skills/corpus-grounding/scripts/ground validate --manifest …`
+  plus a smoke query, plus an eval-fixture test under `tests/`.
+
+## 3. Governance per shipped corpus (Step 9.8)
+
+| Obligation | Mechanism |
+|---|---|
+| Named owner + cadence | `manifest.json` keys — schema-validator-enforced |
+| Staleness visibility | `upstream.last_checked` bumped on every refresh; quarterly default |
+| Link integrity | `Docs URL` / source columns are plain URLs; `check-refs` + the quarterly refresh catch 404s |
+| Eval lock | one `tests/scripts/<domain>_corpus.test.ts` with representative queries |
+| License | source obligations recorded in the owning skill (ATTRIBUTION pattern) |
+
+## 4. Rejected domains — recorded, do not relitigate (Step 9.7)
+
+Per ADR-061 §5 and the 2026-06-03 council (3-model deep debate, no
+split), the following are **rejected as corpora**:
+
+| Candidate | Why rejected | Right mechanism |
+|---|---|---|
+| People/org practices (hiring loops, comp, 1:1 cadence) | Volatile, culturally specific ("fads"); rules don't beat priors stably | Framework skills (`hiring-loop-design`, `comp-banding`, …) |
+| GTM playbooks | Same volatility; context dominates selection | Framework skills + discovery interviews |
+| Founder-strategy verdicts | Verdicts are human decisions (strategy-safety-floor); no auditable selection rule | Framework skills + safety floors |
+| Formula/spec lookup (WACC, WCAG criterion text, API param lists) | Mid-action **reference**, not pre-action grounding | `references/` docs / RAG |
+| Lint-able conventions (no hardcoded hex, commit format) | Post-action **validation** | Rules / linters (`tokens.ts validate`, commit lints) |
+| Anything ≤5 always-on lines | Grounding theater | A rule |
+
+Conditional (deferred, evidence-gated — NOT rejected): finance *method
+selection*, architecture-pattern selection. Watch note:
+`agents/settings/contexts/domain-watch/conditional-grounding-candidates.md`.
+
+## 5. Shipped domain corpora (registry)
+
+| Domain | Skill / manifest | Tier | Source pin |
+|---|---|---|---|
+| Frontend design | `design-intelligence/data/manifest.json` | conditional-grounding | external reference @ b7e3af80 |
+| Security / threat-modeling | `threat-modeling/data/manifest.json` | conditional-grounding | MITRE ATT&CK v16 + OWASP ASVS 4.0 (derived) |
+| API design | `api-design/data/manifest.json` | lookup-only | RFC 9110/9457 + field-standard practice (derived) |
+| DB-query tuning | `database/data/manifest.json` | lookup-only | PostgreSQL 16 / MySQL 8 docs (derived) |
+| Accessibility patterns | `accessibility-auditor/data/manifest.json` | lookup-only | W3C ARIA APG + WCAG 2.2 (derived) |

package/dist/agent-src/guidelines/agent-infra/critical-thinking.md

@@ -0,0 +1,156 @@
+# Critical Thinking
+
+Reference guideline for Wing-1 deep-thinking work — evaluate
+arguments by their evidence and logic, not by surface plausibility or
+author authority. Identifies fallacies, weighs evidence type,
+steelmans before criticizing. Pairs with `first-principles` (which
+rebuilds from primitives) and `inversion-thinking` (which negates the
+goal). Adopted under the **Reference-Guideline Sunset Policy** and
+cross-referenced from:
+
+- [`deep-reading-analyst`](../../skills/deep-reading-analyst/SKILL.md)
+  — L2 Standard / L3 Deep evaluation depth.
+- [`receiving-code-review`](../../skills/receiving-code-review/SKILL.md)
+  — steelman bot / human review feedback before changing code.
+- [`improve-before-implement`](../../rules/improve-before-implement.md)
+  — challenge weak requirements with evidence-grade analysis.
+- [`adversarial-review`](../../skills/adversarial-review/SKILL.md)
+  — paired stress-test on a diff after critique.
+
+> **Core principle:** "Steelman first, criticize second." — attacking
+> the strongest version of an argument is the only valid critique.
+
+## Argument Quality Assessment
+
+### Evidence Evaluation Matrix
+
+| Evidence Type | Strength | Red Flags |
+|---|---|---|
+| Peer-reviewed research | High | Sample size, conflicts of interest |
+| Original data | High | Collection methodology, bias |
+| Expert consensus | Medium-High | Field consensus vs. single expert |
+| Case studies | Medium | Selection bias, generalizability |
+| Anecdotes | Low | Not representative |
+| *"Studies show…"* (no citation) | Very Low | Vague, unverifiable |
+
+### Logical Fallacy Checklist
+
+**Causal fallacies:**
+
+- [ ] Post hoc (A before B ≠ A caused B).
+- [ ] Correlation ≠ causation.
+- [ ] Oversimplified cause (single factor explains complex
+  phenomenon).
+
+**Evidence fallacies:**
+
+- [ ] Cherry-picking (selective evidence).
+- [ ] Survivorship bias (only successful cases visible).
+- [ ] Hasty generalization (small sample → broad claim).
+
+**Rhetorical fallacies:**
+
+- [ ] Ad hominem (attack person, not argument).
+- [ ] Appeal to authority (without expertise in relevant field).
+- [ ] Strawman (misrepresenting opponent's position).
+- [ ] Slippery slope (extreme outcome without justification).
+- [ ] False dichotomy (only 2 options when more exist).
+
+**Statistical fallacies:**
+
+- [ ] Base rate neglect (ignoring prior probability).
+- [ ] Absolute vs. relative risk confusion.
+- [ ] Misleading averages (mean hiding distribution).
+
+## Critical Questions Protocol
+
+### Level 1 — Comprehension
+
+- What is the core claim?
+- What evidence supports it?
+- What are the key assumptions?
+
+### Level 2 — Analysis
+
+- Is the evidence sufficient for the claim?
+- Are there logical gaps?
+- What's missing from this argument?
+
+### Level 3 — Evaluation
+
+- How strong is this argument overall?
+- What would strengthen / weaken it?
+- What are alternative explanations?
+
+### Level 4 — Synthesis
+
+- How does this fit with other knowledge?
+- Where might the author be correct despite flaws?
+- What's the charitable interpretation?
+
+## Source Credibility Assessment
+
+**Author background:**
+
+- Relevant expertise in the field?
+- Potential conflicts of interest?
+- Track record of accuracy?
+
+**Publication context:**
+
+- Peer-reviewed? Editorial standards?
+- Primary source or interpretation?
+- Publication date (currency)?
+
+**Motivation analysis:**
+
+- What's the author's goal? (inform / persuade / sell)
+- Who benefits from this claim?
+- What's the intended audience?
+
+## Counter-Evidence Search
+
+When analyzing strong claims, actively look for:
+
+1. Studies with opposite findings.
+2. Expert disagreement.
+3. Failed replications.
+4. Boundary conditions (when doesn't it work?).
+
+## Balanced Evaluation Template
+
+```markdown
+## Argument Strengths
+- [What's well-supported]
+- [Strong evidence points]
+
+## Argument Weaknesses
+- [Logical gaps]
+- [Weak or missing evidence]
+
+## Unanswered Questions
+- [What the argument doesn't address]
+
+## Conditional Truth
+This argument is strongest when: [context]
+This argument is weakest when:   [context]
+```
+
+## Steelmanning Practice
+
+Before criticizing, construct the **strongest possible version** of
+the argument:
+
+1. Fill in logical gaps charitably.
+2. Add best possible supporting evidence.
+3. Address obvious objections.
+4. THEN evaluate this strongest version.
+
+This prevents attacking strawmen and ensures fair evaluation.
+
+---
+
+## ADOPT citation
+
+Adapted from an external reference.
+

package/dist/agent-src/guidelines/agent-infra/cross-source-consistency-mechanics.md

@@ -0,0 +1,109 @@
+# Cross-Source Consistency — Mechanics
+
+> The discrepancy taxonomy, the scan procedure, the confidence-tiered noise control, worked examples, and the precedence table for the `cross-source-consistency` rule
+
+_Companion to `src/rules/cross-source-consistency.md` (P4 pattern of `road-to-kernel-and-router.md`). The Iron Law, the fire/not-fire scope, and the subordination clauses stay in the rule; this file carries the taxonomy detail, the scan procedure, and the examples._
+
+## The discrepancy taxonomy
+
+| # | Class | Definition | Canonical example |
+|---|---|---|---|
+| a | **text ↔ image** | The ticket/spec text contradicts an attached mockup, screenshot, or diagram. | Text: "show birthdays **today**". Mockup: a birthday from two days ago. |
+| b | **silent-but-needed** | The spec is silent on a behavior that is clearly required for the feature to be correct. | Spec: weekend-shifting only. Clearly also needed: public-holiday shifting — but never specified. |
+| c | **spec ↔ codebase/reality** | The spec contradicts what the code, DB, API, or a real source actually does. | Spec: "the endpoint returns `dueDate`". The DTO has no such field. |
+| d | **intra-ticket** | Acceptance criteria, description, and comments contradict each other. | Description: real-time. AC: "nightly batch is fine." |
+
+Type (a) and (d) are **contradictions between present sources** — the agent
+must not pick one silently. Type (b) is a **scope decision** — the inferred
+behavior may be right, but adding it is a scope expansion the user owns. Type
+(c) routes the *verification* to `source-discovery` (read the real source); this
+rule only owns *surfacing the conflict and asking*.
+
+## The scan procedure
+
+Run this whenever planning, refining, estimating, roadmapping, or implementing
+from a ticket/spec that carries a second source:
+
+1. **Enumerate the sources.** Ticket text, every attachment (mockup / screenshot
+   / diagram), the AC block, description, comments, and — for implementation —
+   the relevant codebase/DB/API surface. If an attachment cannot be read,
+   say so; do not assume it agrees.
+2. **Compare pairwise for type (a), (c), (d).** For each pair, ask: do they state
+   the same thing about the same requirement? A mismatch is a discrepancy.
+3. **Scan for type (b) — silence.** List the behaviors the feature obviously
+   needs but the spec never mentions (weekend/holiday shifts, empty states,
+   error paths, permission edges, pagination, timezone). Each unstated-but-needed
+   behavior is a candidate to surface — not to implement.
+4. **Classify confidence.** High = the sources plainly disagree, or the missing
+   behavior is clearly load-bearing. Low = the "conflict" is a plausible
+   re-reading, or the missing behavior may be intentionally out of scope.
+5. **Decide per the setting** (below), then **batch** every surviving discrepancy
+   into ONE question folded into this turn's single `ask-when-uncertain` prompt.
+
+## Confidence-tiered noise control (`consistency.cross_source`)
+
+The rule fires only under a real trade-off (it must pass the
+`no-cheap-questions` Pre-Send Self-Check). The setting tunes how aggressively:
+
+| Value | High-confidence discrepancy | Low-confidence discrepancy |
+|---|---|---|
+| `on` (default) | Surface + ask before proceeding. | Surface + ask (batched into the same question). |
+| `auto` | Surface + ask. | State as an explicit assumption and proceed (no question). |
+| `off` | No cross-source checking — legacy behavior. | No cross-source checking. |
+
+Batching is the anti-noise mechanism: N discrepancies for one artefact become
+one numbered-options block, never N prompts. Plain vagueness (a single unclear
+source, no second source to compare) is **not** a discrepancy — it stays with
+`ask-when-uncertain` so the two disciplines never double-fire on the same input.
+
+## Worked examples
+
+### Example 1 — text ↔ image (type a)
+
+Ticket: *"The tile shows employees who have their birthday **today**."* Attached
+mockup: a card with a birthday dated **two days ago**.
+
+- Wrong: implement "today" (or implement "recent, like the mockup") and move on.
+  Both are silent guesses on a real contradiction — a violation even if the
+  chosen reading turns out correct.
+- Right: *"The ticket text says 'today' but the mockup shows a birthday from two
+  days ago. Which is authoritative — (1) strictly today, (2) a recent window as
+  the mockup implies, (3) something else?"* Then implement the confirmed reading;
+  `design-fidelity` governs building it 1:1 afterwards.
+
+### Example 2 — silent-but-needed (type b)
+
+Ticket update: *"If a birthday falls on the weekend, show it on the next
+workday."* The spec never mentions public holidays.
+
+- Wrong: also shift birthdays that fall on a public holiday, because it is
+  "obviously" consistent with the weekend rule — a silent scope expansion.
+- Right: *"The spec covers weekend-shifting but is silent on public holidays.
+  Should birthdays on a public holiday also shift to the next workday? (1) yes,
+  same as weekends, (2) no, holidays are out of scope, (3) only regional
+  holidays."* Obvious-to-the-agent ≠ in-scope; `scope-control` owns the
+  expansion permission.
+
+## Precedence & subordination
+
+| Neighbour rule | Relationship |
+|---|---|
+| `ask-when-uncertain` | **Parent ask discipline.** This rule folds its discrepancy into that rule's single question. `ask-when-uncertain` fires on *missing* info; this adds *conflicting present* sources. Never a second question block. |
+| `scope-control` | **Permission authority** for the type-(b) silent-scope-expansion. This rule surfaces the expansion; `scope-control` gates it. |
+| `design-fidelity` | **Fires after** this rule. This rule resolves a text↔image conflict at decision time; `design-fidelity` then enforces build-time 1:1 fidelity to the resolved design. |
+| `source-discovery` / `source-discovery-gate` | **Owns verification** for type (c). This rule surfaces the spec↔code conflict; `source-discovery` provides the evidence procedure. |
+| `no-cheap-questions` | **Floor.** A discrepancy ask must carry a real trade-off; batch, never nag. |
+| `active-remediation` | **Sibling shape.** Its never-silently-ignore ladder is the response model this rule applies to source discrepancies rather than code issues. |
+
+## Failure modes
+
+- **Silent-correct-guess.** Picking the right reading of a contradiction without
+  asking. Correct output, wrong process — still a violation.
+- **Double-firing.** Emitting a discrepancy question AND a separate
+  `ask-when-uncertain` / `improve-before-implement` question about the same
+  underlying uncertainty. Fold into one turn's one question.
+- **Noise creep.** Surfacing plausible re-readings as if they were hard
+  contradictions. Use the confidence tier; `auto` states low-confidence as an
+  assumption instead of asking.
+- **Silent scope expansion.** Implementing an inferred-but-unspecified behavior
+  because it seems obvious. It is a scope decision the user owns.

package/dist/agent-src/guidelines/agent-infra/developer-judgment.md

@@ -0,0 +1,82 @@
+# Developer Judgment Guideline
+
+When the agent should challenge, when it should ask, and when it should just execute.
+
+## Decision table
+
+| Situation | Agent behavior | Max delay |
+|---|---|---|
+| Clear, well-defined request | Execute immediately | 0 |
+| Minor ambiguity | Ask ONE clarifying question | 10s |
+| Request overlaps existing code | Point out existing solution | 15s |
+| Request contradicts architecture | Challenge with evidence, propose alternative | 30s |
+| Request is technically harmful | Warn, propose safe alternative | 30s |
+| User insists after challenge | Execute immediately | 0 |
+| Simple task (config, typo, docs) | Never challenge | 0 |
+
+## What makes a good challenge
+
+✅ **Good challenge:**
+- References specific files or code
+- Offers a concrete alternative
+- Fits in 2-3 sentences
+- Ends with numbered options
+
+❌ **Bad challenge:**
+- Vague ("this might be problematic")
+- No alternative offered
+- Long explanation before the point
+- Blocks work without clear reason
+
+## Examples
+
+### Good: Existing functionality
+
+```
+> ⚠️ `UserService::deactivate()` (app/Services/UserService.php:45) already handles
+> account deactivation with email notification.
+>
+> 1. Extend existing method with the new parameter
+> 2. Create separate method — I'll document the overlap
+```
+
+### Good: Architecture concern
+
+```
+> ⚠️ This would create a direct dependency from Module A to Module B's internals.
+> The current pattern uses events for cross-module communication.
+>
+> 1. Use an event instead (follows existing pattern)
+> 2. Add direct dependency (I'll add a note about the coupling)
+```
+
+### Bad: Vague concern
+
+```
+> I'm not sure this is the best approach. There might be issues with this design.
+> Should I look into alternatives?
+```
+
+→ This wastes the user's time. Either have a specific concern or don't raise one.
+
+## Integration with rules and skills
+
+| Component | Role |
+|---|---|
+| `improve-before-implement` rule | Triggers validation on feature/architecture tasks |
+| `validate-feature-fit` skill | Deep analysis when rule detects potential misfit |
+| `ask-when-uncertain` rule | General uncertainty handling (complementary) |
+| `think-before-action` rule | Analysis-first workflow (complementary) |
+
+## The spectrum of judgment
+
+```
+Silent ────────────────── Challenging ──────────────── Blocking
+  ↑                           ↑                          ↑
+  Bug fixes                   Features                   NEVER
+  Config                      Architecture
+  Docs                        New patterns
+```
+
+The agent NEVER reaches "Blocking". The right side of the spectrum is
+"Challenge and let the user decide", never "refuse to implement".

package/dist/agent-src/guidelines/agent-infra/direct-answers-demos.md

@@ -0,0 +1,142 @@
+---
+demo_for: direct-answers
+layer: pattern-memory
+prose_delta:
+  rule_chars_before: 4098
+  rule_chars_after: 4514
+  measured_at: phase-3.3-cross-link-landing
+  note: "+416 chars from the Examples cross-link block; future prose-pruning rounds (out of scope for Phase 3) will pull pattern prose from the rule into this demo and drive the after-count below the before-count."
+---
+
+# direct-answers — Pattern Memory
+
+> Wrong / right / why demos for the three Iron Laws of
+> `direct-answers` (no flattery, no invented facts, brevity by
+> default). Linked from
+> [`direct-answers`](../../rules/direct-answers.md)
+> § Examples. Outcome baseline at
+> [`tests/golden/outcomes/direct_answers.json`](../../../tests/golden/outcomes/direct_answers.json).
+
+## Demo 1 — Flattery opener (Iron Law 1)
+
+### Wrong shape
+
+```
+User: Wie viele Always-Rules gibt es aktuell?
+
+Agent: Sehr gute Frage! Das ist tatsächlich eine spannende
+Eigenschaft des Systems. Lass mich das für dich aufschlüsseln —
+aktuell sind es 38 Always-Rules.
+```
+
+**Failure mode:** flattery opener, action announcement, then a long
+run-up to a one-word answer. Iron Law 1 + Iron Law 3 violated together.
+
+### Right shape
+
+```
+User: Wie viele Always-Rules gibt es aktuell?
+
+Agent: 38.
+```
+
+### Why it works
+
+One question with one true answer = one sentence. No run-up, no
+cushion, no "let me…". The number is the whole answer.
+
+## Demo 2 — Hedged claim without verification (Iron Law 2)
+
+### Wrong shape
+
+```
+User: Hat verify-before-complete ein "load_context"-Feld?
+
+Agent: Ja, ich glaube schon — die meisten Always-Rules haben das
+inzwischen. Sollte in der Frontmatter stehen.
+```
+
+**Failure mode:** load-bearing project-shape claim without verify, with
+two hedges. Iron Law 2 § Severity-tiered: project-shape claims must be
+backed by a tool call when one suffices — and here a `view` / `grep`
+easily suffices.
+
+### Right shape
+
+```
+User: Hat verify-before-complete ein "load_context"-Feld?
+
+Agent: [grept frontmatter]
+Nein. `verify-before-complete.md` deklariert keinen load_context-
+Eintrag (nur die anderen vier Safety-Floor-Rules tun das).
+```
+
+### Why it works
+
+Tool call before the answer, then a concrete statement with reasoning.
+If the verify cost were too high → ask, don't guess. Here a `grep`
+costs two seconds, so a tool call is mandatory.
+
+## Demo 3 — Post-hoc summary creep (Iron Law 3)
+
+### Wrong shape
+
+```
+User: Wie öffne ich die VBC-Demos?
+
+Agent: Hier der Pfad zur Datei:
+
+`docs/guidelines/agent-infra/verify-before-complete-demos.md`
+
+Zusammenfassend: das ist die Demo-Datei für die Iron Law des
+verify-before-complete-Rule. Sie folgt dem wrong/right/why-Schema
+und ist Teil der Phase 3 von road-to-context-layer-maturity.
+Lass mich wissen, falls du Fragen dazu hast.
+```
+
+**Failure mode:** useless summary after the answer, then a service
+phrase. Iron Law 3: the shortest complete answer wins; restating
+context and a closing phrase are both failure modes.
+
+### Right shape
+
+```
+User: Wie öffne ich die VBC-Demos?
+
+Agent: `docs/guidelines/agent-infra/verify-before-complete-demos.md`
+```
+
+### Why it works
+
+The path is the whole answer. No re-frame of the question, no
+"in summary", no offered follow-up. If the user wants more, they ask.
+
+## Demo 4 — Functional emoji vs prose flair
+
+### Wrong shape
+
+```
+Agent: 🚀 Tests sind durch! ✨ Alle 47 grün 🎉 Bereit für den nächsten Schritt 💪
+```
+
+**Failure mode:** emoji as a style element, not as a functional
+marker. § Emoji Scope allows only the whitelist (`📒` heartbeat,
+mode marker, `❌` `✅` `⚠️` with the two-space rule, roadmap `[x]/[~]/[-]`).
+Everything else is noise.
+
+### Right shape
+
+```
+Agent: Tests durch:
+
+$ vendor/bin/pest -q
+............................................... 47 passed
+
+✅  47/47 grün, Exit 0.
+```
+
+### Why it works
+
+Exactly one emoji from the whitelist (`✅` with two-space), used
+functionally as a status marker next to the CLI output. No decoration,
+no reaction emojis.