@event4u/agent-config 14.22.0 → 15.0.0

package/dist/agent-src/guidelines/agent-infra/self-improvement-pipeline.md

@@ -0,0 +1,134 @@
+# Self-Improvement Pipeline
+
+Five-stage flow that turns real project experience into reviewed
+rule / skill / command / guideline changes. No autonomous self-edits;
+every upstream change ships via a human-reviewed PR.
+
+Referenced by `road-to-curated-self-improvement.md`. Consumed by the live
+artifacts — the `skill-improvement-trigger` rule and the existing skills
+`learning-to-rule-or-skill`, `skill-improvement-pipeline`, and
+`upstream-contribute` — each becomes a stage, not a standalone invocation.
+
+## The five stages
+
+```
+Project event ── capture ── classify ── propose ── gate ── upstream
+    │              │            │           │         │         │
+ (bug,         learning-    scope:     proposal     human    upstream-
+  success,     to-rule-or-  project-   doc          review    contribute
+  review       skill        vs-        (full        +gate     PR
+  pattern)                  package    evidence)    script
+```
+
+Each stage has a fixed input and a fixed output so the flow is
+resumable and auditable. A stage that cannot produce its output
+blocks — it does not hand a half-filled doc to the next stage.
+
+### Stage 1 — Capture
+
+- **Trigger:** a rule-worthy event. Bug pattern repeats, review
+  finding recurs, a successful pattern is worth codifying.
+  The existing `skill-improvement-trigger` rule signals the event.
+- **Input:** raw observation (PR link, log line, review comment).
+- **Output:** learning note at `agents/learnings/<date>-<slug>.md`
+  with frontmatter `source`, `evidence[]` (≥1 link), `stage: captured`.
+- **Guardrails:** nothing is written into `dist/agent-src/` at this stage.
+  Learnings live in the consumer repo until promoted.
+
+### Stage 2 — Classify
+
+- **Trigger:** explicit invocation or pipeline progression.
+- **Input:** learning note from Stage 1.
+- **Output:** same file, frontmatter extended with:
+  - `scope: project | package`
+  - `type: rule | skill | command | guideline`
+  - `stage: classified`
+- **Guardrails:** classification is reversible. A `package`-scoped
+  learning with single-repo evidence is auto-demoted to `project`
+  at the gate.
+
+### Stage 3 — Propose
+
+- **Trigger:** classified learning enters the drafter.
+- **Executor:** `learning-to-rule-or-skill` skill drafts the artefact
+  body; `skill-improvement-pipeline` refines it.
+- **Input:** classified learning + any referenced existing artefact.
+- **Output:** proposal doc at
+  `agents/proposals/<proposal_id>.md` following
+  [`proposal.example.md`](../../templates/agents/proposal.example.md).
+  Frontmatter `stage: proposed`.
+- **Guardrails:** the draft body and the proposal doc are a single
+  file. An artefact draft without its proposal wrapper is rejected.
+
+### Stage 4 — Gate
+
+- **Trigger:** proposal doc committed or staged.
+- **Executor:** `scripts/check_proposal.ts`.
+- **Input:** proposal doc from Stage 3.
+- **Output:** verdict recorded in the proposal doc section 9
+  (`pass | request changes | block`). Frontmatter `stage: gated`
+  only after a `pass`.
+- **Gate checks (all must pass):**
+  1. At least **2 independent evidence** entries (distinct PRs,
+     issues, or incidents).
+  2. `skill_linter` zero errors on the draft body.
+  3. `check_portability` zero violations (no project identifiers
+     on `package`-scoped proposals).
+  4. `check_references` resolves every link.
+  5. `size-enforcement` within the budget for the artefact type.
+  6. `preservation-guard` justifies any replacement (section 6 of
+     the proposal doc).
+- **Guardrails:** the gate is not a rubber stamp. A `block` verdict
+  stays in the proposal as history; the pipeline restarts at
+  Stage 3 if the author wants to revise.
+
+### Stage 5 — Upstream
+
+- **Trigger:** gate passed AND a human approver signed off.
+- **Executor:** `upstream-contribute` skill. Refuses invocation if
+  the proposal frontmatter is not `stage: gated`.
+- **Input:** gated proposal doc.
+- **Output:** PR against `event4u/agent-config` carrying the
+  proposal doc as the PR body. Standard package CI runs.
+  Frontmatter `stage: upstream` and `upstream_pr_url` set.
+- **Guardrails:** no `upstream-contribute` invocation ever edits
+  `.agent-src.uncondensed/` in the consumer repo. Writes happen
+  in the fork / PR branch of the package repo only.
+
+## Stage ownership
+
+| Stage | Human role | Automation |
+|---|---|---|
+| 1 Capture | Any contributor | `skill-improvement-trigger` rule auto-triggers |
+| 2 Classify | Drafter | `learning-to-rule-or-skill` suggests |
+| 3 Propose | Drafter + reviewer | `skill-improvement-pipeline` refines |
+| 4 Gate | Gate script | fully automated, block is final |
+| 5 Upstream | Approver | `upstream-contribute` opens the PR |
+
+## When to skip stages
+
+- **Typo / wording fix** — direct PR, no proposal needed. Pipeline
+  is for behaviour-changing proposals.
+- **Documentation-only fix** — direct PR.
+- **Adding a missing example** — direct PR if the rule semantics
+  do not change.
+
+When in doubt, run the pipeline. Overhead is bounded; churn from
+unreviewed upstream changes is not.
+
+## Anti-patterns
+
+- **Do NOT** open an upstream PR without a proposal doc. Reviewers
+  need the evidence in one place.
+- **Do NOT** promote a learning with one piece of evidence. Two
+  independent sources is the minimum; the gate enforces it.
+- **Do NOT** edit `.agent-src.uncondensed/` directly in a consumer
+  project "just to try it out". Drafts live in `agents/proposals/`.
+- **Do NOT** treat a `block` verdict as a personal rejection. The
+  gate checks structural shape, not author intent.
+
+## See also
+
+- [`proposal.example.md`](../../templates/agents/proposal.example.md) — the template every proposal derives from
+- [`artifact-drafting-protocol`](../../rules/artifact-drafting-protocol.md) — Understand → Research → Draft sequence used inside Stage 3
+- [`preservation-guard`](../../rules/preservation-guard.md) — invoked by the gate to check replacement proposals

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

@@ -0,0 +1,211 @@
+---
+demo_for: minimal-safe-diff, think-before-action
+layer: pattern-memory
+prose_delta:
+  rule_chars_before: 5927
+  rule_chars_after: 6903
+  measured_at: lint-examples-shape-conformance-pass
+  note: "Counts are of THIS demo file, measured with wc -c before and after the pass. The delta is frontmatter plus the Demo / Wrong shape / Right shape / Failure mode / Why it works headings required by lint_examples — no prose was migrated out of a rule and none was removed; every code block is byte-identical."
+---
+
+# Simplicity and Goal Discipline — wrong/right demos
+
+Recognition surface for [`minimal-safe-diff § Anti-over-engineering`](../../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.
+
+## Demo 1 — Over-abstraction vs. one function
+
+**Ask:** "Add a function to calculate a percentage discount."
+
+### Wrong shape
+
+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 */ }
+```
+
+**Failure mode:** the wrong version is not "bad code" — it is *premature*
+code: harder to read, more surface to test, and speculative until the
+requirement exists.
+
+### Right shape
+
+One function until the second discount type is real:
+
+```php
+function calculateDiscount(float $amount, float $percent): float
+{
+    return $amount * ($percent / 100);
+}
+```
+
+### Why it works
+
+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).
+
+## Demo 2 — Speculative features vs. just-what-was-asked
+
+**Ask:** "Save user preferences to the database."
+
+### Wrong shape
+
+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
+  }
+}
+```
+
+**Failure mode:** every optional parameter with one call site, every
+"flexibility" flag, and every handler for a scenario that cannot occur is
+speculative complexity.
+
+### Right shape
+
+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 it works
+
+Add caching when performance data demands it, validation when bad
+data appears, merging when the requirement lands.
+
+## Demo 3 — Drive-by refactor vs. surgical diff
+
+**Ask:** "Fix the bug where an empty email crashes the validator."
+
+### Wrong shape
+
+The fix PLUS improved email regex, new username length checks,
+rewritten comments, and a fresh docstring — four changes, one was asked.
+
+**Failure mode:** the "improvements" belong in a follow-up proposed via
+`active-remediation`'s note-and-ask ladder — not smuggled into the bug fix.
+
+### Right shape
+
+Only the lines that make the empty-email case safe change; every
+other line of the function is byte-identical.
+
+### Why it works
+
+Every changed line must trace to the stated task
+(`minimal-safe-diff`).
+
+## Demo 4 — Style drift vs. match-existing-style
+
+**Ask:** "Add logging to the upload function."
+
+### Wrong shape
+
+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.
+
+**Failure mode:** a diff that reformats while changing behavior hides the
+behavior change.
+
+### Right shape
+
+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 it works
+
+Style consistency is a repo property, not a per-diff taste decision.
+
+## Demo 5 — Own-orphan vs. pre-existing dead code
+
+**Ask:** "Replace the legacy formatter call in `processA` with the new one."
+
+### Wrong shape
+
+**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.
+
+**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.
+
+**Failure mode:** two directions of the same error — the diff shipped its own
+litter (too little), or it deleted code that untouched files still reference,
+or that was already orphaned before this task (too much).
+
+### Right shape
+
+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 it works
+
+The boundary is mechanical (grep after editing), so there is no
+judgment call to rationalize — see
+[`minimal-safe-diff § Own-orphan cleanup`](../../rules/minimal-safe-diff.md#own-orphan-cleanup).
+
+## Demo 6 — Vague plan vs. verifiable per-step plan
+
+**Ask:** "Add rate limiting to the API."
+
+### Wrong shape
+
+Unverifiable narration:
+
+```
+1. Review the code
+2. Identify issues
+3. Implement rate limiting
+4. Test the changes
+```
+
+**Failure mode:** a step without a `verify:` is an assumption.
+
+### Right shape
+
+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 it works
+
+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/dist/agent-src/guidelines/agent-infra/six-hats.md

@@ -0,0 +1,353 @@
+# Six Thinking Hats
+
+Reference guideline for Wing-1 deep-thinking work — Edward de Bono's
+six-perspective method for examining ideas through Facts · Feelings ·
+Cautions · Benefits · Creativity · Process — one hat at a time, to
+separate thinking modes and avoid the cross-talk that derails group
+decisions. Adopted under the **Reference-Guideline Sunset Policy** and
+cross-referenced from:
+
+- [`deep-reading-analyst`](../../skills/deep-reading-analyst/SKILL.md)
+  — L2 Standard analysis depth (multi-perspective sweep).
+- [`ai-council`](../../skills/ai-council/SKILL.md)
+  — multi-model consultation pattern; Six Hats is the per-perspective
+  decomposition the council voices use when adjudicating a decision.
+- [`/council`](../../../src/domains/meta/council/command.md)
+  — internal council orchestrator routing to per-hat persona prompts.
+
+> **Core principle:** "Wear one hat at a time." — separating thinking
+> modes reduces conflict and ensures comprehensive coverage of facts,
+> emotions, risks, value, alternatives, and meta-process.
+
+## When to Use
+
+Ideal for:
+
+- Multi-perspective decision review without role-locking
+- Group sessions where parallel thinking is needed
+- Avoiding the "this is good but risky" mode-mixing trap
+- Pre-mortem on a plan when [`inversion-thinking`](inversion-thinking.md)
+  is too narrow (Black hat alone) and you want all six lenses
+
+Do **not** use when the user wants depth on a single dimension (use
+[`mental-models`](mental-models.md)) or a structured decision artifact
+(use [`scqa-framework`](scqa-framework.md)).
+
+## The Six Hats
+
+### White Hat — Facts & Data
+
+**Focus:** objective information only.
+
+**Questions:**
+
+- What facts do we have?
+- What data is available?
+- What information is missing?
+- What are the numbers?
+- How do we verify this?
+
+**Language:** "According to…", "The data shows…", "We know that…",
+"We don't know…".
+
+**In content analysis:** extract factual claims · note cited sources ·
+identify missing data · separate facts from interpretations.
+
+**Template:**
+
+```markdown
+## Known Facts
+- [Verifiable fact 1]
+- [Verifiable fact 2]
+
+## Missing Information
+- [ ] [Gap 1]
+- [ ] [Gap 2]
+
+## Data Sources
+- [Citation 1]: [Quality rating]
+```
+
+### Red Hat — Emotions & Intuition
+
+**Focus:** gut feelings, hunches, intuitive responses.
+
+**Questions:**
+
+- What's my immediate reaction?
+- What does my gut say?
+- What emotions does this evoke?
+- What's my intuition telling me?
+
+**Language:** "I feel that…", "My gut says…", "This makes me
+uncomfortable because…", "I'm excited about…".
+
+**In content analysis:** note emotional response while reading ·
+identify what triggers strong feelings · trust instincts about
+credibility · recognize persuasive emotional appeals in text.
+
+**Template:**
+
+```markdown
+## Immediate Reactions
+- [Emotion] at [specific part]
+
+## Gut Feelings
+- Something feels off about: [intuition]
+- Exciting / Compelling: [what resonates]
+
+## Emotional Triggers in Text
+- Author uses [emotion] to persuade
+```
+
+**Important:** no justification needed. Pure feeling.
+
+### Black Hat — Caution & Risks
+
+**Focus:** critical judgment, potential problems.
+
+**Questions:**
+
+- What could go wrong?
+- What are the risks?
+- What's unrealistic?
+- Where's the weakness?
+- What are the downsides?
+
+**Language:** "A problem is…", "This won't work because…", "The risk
+here is…", "We're overlooking…".
+
+
+**In content analysis:** identify logical flaws · note unsupported
+claims · point out potential failures · question feasibility ·
+consider unintended consequences.
+
+**Template:**
+
+```markdown
+## Logical Weaknesses
+- [Flaw 1] in reasoning
+
+## Risks If Applied
+- Risk: [consequence]
+- When it fails: [scenario]
+
+## Missing Considerations
+- Doesn't account for: [factor]
+
+## Overly Optimistic Claims
+- [Claim] seems unrealistic because [reason]
+```
+
+**Important:** critical, not cynical. Necessary for risk assessment.
+
+### Yellow Hat — Benefits & Optimism
+
+**Focus:** positive aspects, value, opportunities.
+
+**Questions:**
+
+- What's the value here?
+- What are the benefits?
+- Why would this work?
+- What's the best-case scenario?
+- What opportunities does this create?
+
+**Language:** "The benefit is…", "This could work because…", "The
+value here is…", "An opportunity is…".
+
+**In content analysis:** extract valuable insights · identify strong
+arguments · note practical applications · find novel perspectives ·
+recognize what advances the field.
+
+**Template:**
+
+```markdown
+## Key Value Propositions
+- Valuable insight: [what's useful]
+
+## Strong Points
+- Well-supported: [argument]
+
+## Potential Applications
+- Could be used for: [use case]
+
+## Novel Contributions
+- New perspective on: [topic]
+
+## Best-Case Outcome
+If fully applied: [positive scenario]
+```
+
+**Important:** be realistic but generous. Find genuine value.
+
+### Green Hat — Creativity & Alternatives
+
+**Focus:** new ideas, possibilities, innovations.
+
+**Questions:**
+
+- What else is possible?
+- How else could we think about this?
+- What's a creative alternative?
+- What if we combined X with Y?
+- What's unconventional?
+
+**Language:** "What if…", "Another way to look at it…", "We could
+also…", "An alternative is…".
+
+**In content analysis:** extend the author's ideas further · generate
+alternatives to proposed solutions · combine with other frameworks ·
+apply to new domains · challenge assumptions creatively.
+
+**Template:**
+
+```markdown
+## Extensions of Ideas
+- Taking [concept] further: [new application]
+
+## Alternative Approaches
+Instead of [author's method], what if: [alternative]
+
+## Creative Combinations
+- [Idea from text] + [other framework] = [new insight]
+
+## Unconventional Applications
+- Apply this to [unexpected domain]
+
+## "What If" Scenarios
+- What if [assumption] were reversed?
+```
+
+**Important:** no criticism in green-hat mode. All ideas welcome.
+
+### Blue Hat — Process & Meta-Thinking
+
+**Focus:** managing thinking, overview, conclusions.
+
+**Questions:**
+
+- What have we covered?
+- What thinking mode do we need now?
+- What's the summary?
+- What's next?
+- How should we think about this?
+
+**Language:** "We've covered…", "The next step is…", "In summary…",
+"We need to focus on…".
+
+**In content analysis:** decide which hats to use when · synthesize
+findings from all hats · determine next steps · plan learning
+strategy · monitor the analysis process.
+
+**Template:**
+
+```markdown
+## Analysis Process
+1. White: Gathered facts
+2. Red: Noted reactions
+3. Black: Identified risks
+4. Yellow: Found value
+5. Green: Generated alternatives
+
+## Synthesis
+Combining all perspectives:
+- [Integrated insight]
+
+## Next Steps
+- [ ] Further research: [area]
+- [ ] Practical test: [action]
+- [ ] Deep dive: [topic]
+
+## Time Investment
+Worth [X] time because [reason]
+```
+
+**Important:** Blue hat organizes the other hats. It's the conductor.
+
+## Usage Patterns
+
+| Pattern | Sequence |
+|---|---|
+| **Quick evaluation (15 min)** | White → Red → Yellow → Black → Blue |
+| **Deep analysis (60 min)** | White → Red → Black → Yellow → Green → Blue → revisit any → Blue |
+| **Problem-solving** | White → Red → Green → Yellow → Black → Green → Blue |
+| **Decision-making** | White → Yellow → Black → Red → Blue |
+
+## Rules of Engagement
+
+1. **One hat at a time** — don't mix modes.
+2. **Everyone wears the same hat** — parallel thinking (if group).
+3. **Separate person from hat** — you're not "the critical person",
+   you're wearing the Black hat.
+4. **Time-box** — set limits per hat.
+5. **Blue hat controls** — decides sequence and timing.
+
+## Common Mistakes
+
+- ❌ **Mixing hats** — *"This is good (yellow) but risky (black)."*
+  ✅ **Separate:** Yellow session: *"This is good because X."* Then
+  Black session: *"The risk is Y."*
+- ❌ **Judging feelings** — *"That's irrational"* during Red hat.
+  ✅ **Accept feelings:** all emotions noted without judgment.
+- ❌ **Weak yellow** — *"I guess there's some value…"*.
+  ✅ **Genuine optimism:** really find the good.
+- ❌ **Staying too long** — 30 min per hat.
+  ✅ **Move on:** 5–10 min per hat is usually sufficient.
+
+## Application to Reading
+
+**When to use which hat:**
+
+- **Understanding stage:** White (facts), Red (reactions).
+- **Evaluation stage:** Black (critique), Yellow (value).
+- **Application stage:** Green (ideas), Blue (synthesis).
+
+**Full cycle:**
+
+1. White: what does the text actually say?
+2. Red: how do I feel about it?
+3. Black: what's wrong with it?
+4. Yellow: what's right with it?
+5. Green: what else could we do with this?
+6. Blue: so what? Now what?
+
+## Integration with Other Frameworks
+
+- **After [`first-principles`](first-principles.md):** use hats to
+  evaluate the rebuilt argument.
+- **After [`systems-thinking`](systems-thinking.md):** use Yellow /
+  Black on leverage points.
+- **Before [`critical-thinking`](critical-thinking.md):** use Red to
+  surface biases.
+- **During synthesis:** use Blue to organize findings.
+
+## Output Format
+
+```markdown
+# Six Hats Analysis: [Content Title]
+
+## White: Facts
+[Objective data]
+
+## Red: Feelings
+[Emotional response]
+
+## Black: Cautions
+[Risks and weaknesses]
+
+## Yellow: Benefits
+[Value and opportunities]
+
+## Green: Possibilities
+[Creative extensions]
+
+## Blue: Conclusions
+[Synthesis and next steps]
+```
+
+---
+
+## ADOPT citation
+
+Adapted from an external reference.