@event4u/agent-config 1.9.1

package/.agent-src/guidelines/agent-infra/role-mode-router.md

@@ -0,0 +1,89 @@
+# Role Mode Router
+
+Maps common entry signals to the correct role mode defined in
+[`role-contracts`](role-contracts.md). The router is advisory —
+it proposes a mode, the user can veto with `/mode none`.
+
+## Entry signal → mode
+
+| Signal pattern | Inferred mode |
+|---|---|
+| "implement X", "add feature", `/jira-ticket`, `/bug-fix` | `developer` |
+| `/review-changes`, `/judge`, "review this PR", PR open on active branch | `reviewer` |
+| "add tests", "why does X fail", test output pasted in context | `tester` |
+| "I want a feature", `/feature-explore`, `/feature-plan`, "what should it do" | `po` |
+| "production is down", `break-glass: true`, hotfix branch, live incident framing | `incident` |
+| "what's the strategy", `/feature-roadmap`, multi-step work with unclear order | `planner` |
+
+The signals are **non-exclusive**. When two patterns match, prefer the
+narrower one (`incident` > `developer`; `reviewer` > `tester`).
+
+## Surfacing the inferred switch
+
+Before doing any work, the agent emits **one line** in the user's
+language (per `language-and-tone`):
+
+```
+> entering {mode} mode — contract: {goal-field} / {constraints-field} / {output-field}
+```
+
+This is the only announcement. Do not narrate the reasoning for the
+mode choice. If the user is silent, proceed; if they reply
+`/mode none` or `/mode <other>`, switch immediately.
+
+## When NOT to infer
+
+- `roles.active_role` is already non-empty in `.agent-settings.yml` —
+  respect the explicit setting; do not second-guess it.
+- `roles.default_role` is set and matches the inferred mode — still
+  surface the announcement (it reassures the user the frame loaded).
+- No signal matches — **do NOT guess**. Stay mode-less and let
+  `ask-when-uncertain` handle the scope question.
+
+## Precedence
+
+1. Explicit `/mode <name>` in the current message — wins absolutely.
+2. `roles.active_role` from `.agent-settings.yml` — sticky within session.
+3. Router inference from the entry signal table above.
+4. `roles.default_role` fallback — only when no signal matches.
+5. No mode — rule `role-mode-adherence` stays inert.
+
+## Veto path
+
+```
+> 1. Switch to {mode-b} — run /mode {mode-b}
+> 2. Stay in {mode-a}
+> 3. Clear mode — run /mode none
+```
+
+The agent MUST use numbered options (per `user-interaction`) and accept
+both the number and the spelled-out slash command.
+
+## Interactions
+
+- [`role-contracts`](role-contracts.md) — the contracts this router targets.
+- [`role-mode-adherence`](../../rules/role-mode-adherence.md) — enforces
+  the contract once a mode is active.
+- [`ask-when-uncertain`](../../rules/ask-when-uncertain.md) — the
+  fallback when no signal matches.
+- [`/mode`](../../commands/mode.md) — user-facing override.
+
+## Signal table maintenance
+
+The table lives here, not in `role-contracts.md`. Commands and rules
+reference modes by slug only — the routing layer is the single place
+that maps free-form intent to a slug. Add a signal only when:
+
+- ≥3 real sessions in `agents/sessions/` have surfaced the same pattern.
+- The pattern does not collide with an existing row (check neighbours).
+- The inferred mode is one of the six — never invent a seventh.
+
+Signals captured but not yet promoted live in a scratch list at the
+bottom of this file (delete when promoted).
+
+## Scratch list (candidates)
+
+<!-- Add `{signal} → {mode}` lines here; promote to the table above
+     only after the criteria in the previous section are met. -->
+
+_None yet._

package/.agent-src/guidelines/agent-infra/runtime-layer.md

@@ -0,0 +1,89 @@
+# Runtime Layer
+
+Guideline for defining and using execution metadata on skills.
+
+## Execution block
+
+Skills can optionally declare an `execution` block in YAML frontmatter:
+
+```yaml
+execution:
+  type: manual | assisted | automated
+  handler: none | shell | php | node | internal
+  timeout_seconds: 30
+  safety_mode: strict
+  allowed_tools: []
+```
+
+## Execution types
+
+| Type | Meaning | Default |
+|---|---|---|
+| `manual` | Skill is instructional only — no automated actions | ✅ default |
+| `assisted` | Skill prepares actions for human confirmation | |
+| `automated` | Skill can execute safely without confirmation | |
+
+If no `execution` block is present, the skill is treated as `manual`.
+
+## Handler types
+
+| Handler | When to use |
+|---|---|
+| `none` | No handler needed (manual skills) |
+| `shell` | Executes shell commands (e.g., linting, testing) |
+| `php` | Executes PHP code (e.g., artisan commands) |
+| `node` | Executes Node.js scripts |
+| `internal` | Uses internal agent capabilities only |
+
+## Safety mode
+
+| Mode | Meaning |
+|---|---|
+| `strict` | All safety checks enforced, no bypass allowed |
+
+Only `strict` is allowed in this phase. Future phases may introduce `relaxed` for trusted environments.
+
+## Allowed tools
+
+An explicit list of external tool identifiers the skill may access during execution.
+Empty list (`[]`) means no external tools.
+
+```yaml
+allowed_tools:
+  - github
+  - jira
+```
+
+Tool names must match entries in the tool registry (see tool-integration roadmap).
+
+## Rules for authors
+
+1. **Default is manual** — omitting the execution block means the skill is manual.
+2. **Assisted before automated** — prefer `assisted` unless the skill is provably safe.
+3. **Handler must match type** — `automated` requires a handler other than `none`.
+4. **Safety mode is mandatory for automated** — `automated` without `safety_mode: strict` is invalid.
+5. **Allowed tools must be declared** — undeclared tool usage is a linter error.
+6. **Timeout is advisory** — used for planning, not hard enforcement in this phase.
+
+## Migration
+
+Existing skills without an execution block remain valid.
+No migration is required — the execution block is purely additive.
+
+## Validation
+
+The skill linter validates:
+
+- `execution.type` must be one of: `manual`, `assisted`, `automated`
+- `execution.handler` must be one of: `none`, `shell`, `php`, `node`, `internal`
+- `automated` type requires `handler` ≠ `none`
+- `automated` type requires `safety_mode: strict`
+- `allowed_tools` entries must be strings
+- Unknown fields inside `execution` block produce warnings
+
+## Anti-patterns
+
+- Adding `automated` to skills that modify files without verification
+- Using `shell` handler without specifying which commands are safe
+- Declaring `allowed_tools` without a matching tool registry entry
+- Setting `timeout_seconds: 0` (use a positive value or omit)

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

@@ -0,0 +1,135 @@
+# 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
+existing skills `capture-learnings`, `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 `capture-learnings` 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 `.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.py`.
+- **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.uncompressed/` 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 | `capture-learnings` 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.uncompressed/` 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
+
+- [`road-to-curated-self-improvement.md`](../../../agents/roadmaps/road-to-curated-self-improvement.md) — roadmap this guideline implements
+- [`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/.agent-src/guidelines/agent-infra/size-and-scope.md

@@ -0,0 +1,189 @@
+# size-and-scope-guidelines
+
+## Purpose
+
+Ensure all system components stay:
+
+- readable
+- maintainable
+- executable
+- non-redundant
+
+Prevent:
+- oversized rules
+- bloated skills
+- command overreach
+- duplicated knowledge
+
+---
+
+# Core principle
+
+> Split by responsibility, NOT by length.
+
+Size is a signal — not the goal.
+
+---
+
+# Golden size rules
+
+## Rules & system instructions
+
+- Ideal: **< 60 lines**
+- Acceptable: **< 100–120 lines**
+- Hard limit: **< 200 lines**
+
+Reason:
+- Loaded frequently
+- Must be reliably followed
+- Large files get partially ignored
+
+---
+
+## Skills
+
+- Target: **300–900 words**
+- Warning: **>1200 words**
+- Strong split signal: **>1500 words**
+
+Focus:
+- scanability
+- one responsibility
+- executable workflow
+
+---
+
+## Commands
+
+- Target: **200–600 words**
+- Acceptable: **up to ~1000 words**
+
+Commands orchestrate — not implement.
+
+---
+
+## AGENTS.md
+
+- Target: **200–800 words**
+- Acceptable: **up to ~1200 words**
+
+High-level only.
+
+---
+
+## copilot-instructions.md
+
+- Ideal: **< 60 lines**
+- Acceptable: **< 100–150 lines**
+
+Must stay lightweight.
+
+---
+
+## Guidelines
+
+- Target: **400–1500 words**
+- Can exceed if needed
+
+Guidelines are reference — not execution.
+
+---
+
+# Component responsibilities
+
+## Rules
+
+- constraints only
+- no workflows
+- no long explanations
+
+---
+
+## Skills
+
+Must contain:
+
+- When to use
+- Procedure
+- Validation
+- Output format
+- Gotchas
+- Do NOT
+
+---
+
+## Commands
+
+- orchestrate workflows
+- delegate to skills
+- do not contain deep logic
+
+---
+
+## Guidelines
+
+- define conventions
+- support skills
+- must NOT replace workflows
+
+---
+
+## AGENTS.md
+
+- entrypoint
+- system overview
+- interaction model
+
+---
+
+## copilot-instructions.md
+
+- behavioral hints
+- style guidance
+
+---
+
+# Anti-patterns
+
+## Too large
+
+- skill solves multiple problems
+- rule explains instead of constraining
+- command contains implementation
+- AGENTS.md becomes documentation dump
+
+---
+
+## Too small
+
+- skill has no real workflow
+- rule is just a suggestion
+- command adds no value
+
+---
+
+# Boundary rule (critical)
+
+> A skill must remain usable WITHOUT opening a guideline.
+
+If not → the skill is too weak.
+
+---
+
+# Decision checklist
+
+Before creating or modifying:
+
+1. Is this a constraint → Rule
+2. Is this a workflow → Skill
+3. Is this orchestration → Command
+4. Is this reference → Guideline
+5. Is this entrypoint → AGENTS.md
+6. Is this behavior hint → copilot-instructions.md
+
+---
+
+# Final principle
+
+> Small enough to understand quickly
+> Large enough to be useful

package/.agent-src/guidelines/agent-infra/tool-integration.md

@@ -0,0 +1,73 @@
+# Tool Integration
+
+Guideline for declaring and using external tool integrations in skills.
+
+## Core principle
+
+Tools are permissions, not abilities. Every tool access must be declared, allowlisted, and auditable.
+
+## Tool declaration in skills
+
+Skills declare tool usage in the `execution.allowed_tools` field:
+
+```yaml
+execution:
+  type: assisted
+  handler: internal
+  allowed_tools:
+    - github
+    - jira
+```
+
+## Permission model
+
+| Rule | Description |
+|---|---|
+| Deny by default | No tool access unless explicitly declared |
+| Allowlist only | Only registered tools can be used |
+| Read-first | Prefer read-only actions; write actions require explicit approval |
+| No hidden credentials | Tools must not embed or assume credentials |
+
+## Tool permissions
+
+Skills can declare fine-grained permissions per tool:
+
+```yaml
+tool_permissions:
+  github:
+    actions:
+      - read_pr
+      - create_pr
+  jira:
+    actions:
+      - read_ticket
+      - search_tickets
+```
+
+## Supported tools
+
+| Tool | Available actions | Default |
+|---|---|---|
+| `github` | read_pr, read_issue, create_pr, list_files | read-only |
+| `jira` | read_ticket, search_tickets, add_comment | read-only |
+
+New tools require:
+1. An adapter implementation in `scripts/tools/`
+2. Registration in the tool registry
+3. Documentation in `agents/docs/tools/`
+
+## Validation rules (linter)
+
+| Condition | Severity |
+|---|---|
+| Undeclared tool in allowed_tools | error |
+| Tool listed but not in registry | warning |
+| Automated execution with undeclared tools | error |
+| Permission block missing for restricted tool | warning |
+
+## Anti-patterns
+
+- Using tools without declaring them in `allowed_tools`
+- Assuming credentials are available in the environment
+- Mixing read and write actions without explicit separation
+- Adding tools to a skill that doesn't need them