@event4u/agent-config 1.20.0 → 1.22.0

package/.agent-src/contexts/communication/rules-auto/cli-output-handling-mechanics.md

@@ -1,87 +0,0 @@
-# CLI output handling — mechanics
-
-Codebase navigation tips, the redirect-summarize-target fallback
-pattern, the general rules around exit codes / summary lines, and the
-CLI-over-MCP catalog for the
-[`cli-output-handling`](../../../rules/cli-output-handling.md) rule.
-The Iron Law, the detection rule (`rtk_installed`), the verbose-command
-table, and the exceptions list live in the rule; this file is the
-lookup material when the agent has to fall back from `rtk`.
-
-## Codebase Navigation
-
-### Use what you already have
-
-- Edited a file → the edit tool already returned the result. Skip re-reading.
-- Ran a command → you have the output. Skip re-running to "verify".
-- File in context from recent messages → skip reloading.
-- Found a symbol → use it. Skip searching again differently.
-
-### Search before reading
-
-- **Search first** — `codebase-retrieval`, `search_query_regex`, or `grep`.
-- **Load only what you need** — use `view_range` or `search_query_regex`, not full files.
-- **Small files** (< 50 lines) — OK to read fully.
-
-### Ignored files (`.augmentignore`)
-
-- `vendor/`, `node_modules/`, lock files, and generated files are excluded from `codebase-retrieval`.
-- When you need to understand a vendor package (base class, interface, API), **read the specific file** with `view`. This bypasses the ignore.
-- Load only the file you need — never browse entire vendor directories.
-
-### Minimize tool calls
-
-- **Parallel reads** — read multiple files in one batch, not sequentially.
-- **`search_query_regex`** over full file reads.
-- **`view_range`** when you know the exact lines.
-- **One `codebase-retrieval` call** with all symbols — batch, not 5 separate calls.
-
-## Fallback Pattern: Redirect, Summarize, Target
-
-When `rtk` has no matching subcommand for the tool at hand, fall back to
-this pattern. Every command that MAY produce more than ~30 lines of output:
-
-### Step 1: Redirect to file
-```bash
-docker compose exec -T <service> <command> 2>&1 > /tmp/<tool>-output.txt
-echo "EXIT=$?"
-```
-
-### Step 2: Read ONLY the summary
-```bash
-tail -5 /tmp/<tool>-output.txt
-```
-
-### Step 3: If errors exist, read ONLY what you need to fix
-```bash
-grep "ERROR\|error\|✏️" /tmp/<tool>-output.txt | head -20
-grep "app/Services/MyService.php" /tmp/<tool>-output.txt
-```
-
-**NEVER** do:
-- `cat /tmp/<tool>-output.txt` (loads everything)
-- Read the full output of a passing command (waste)
-- Read diffs you don't plan to act on
-
-## General Rules
-
-For tool-specific commands → see the `quality-tools` skill.
-
-1. **Exit code first**: Check `$?` before reading ANY output. If 0, you're done — skip reading.
-2. **Summary line**: Most tools print a summary as the last few lines. That's all you need.
-3. **Targeted grep**: When you need details, `grep` for the specific file or error type.
-4. **Read once, act, move on**: Once you've read output and acted on it, skip re-reading.
-5. **Iterative fixing**: Fix one error at a time, re-run, check exit code.
-   Output becomes stale after each fix — always re-run before reading again.
-
-## CLI Over MCP
-
-MCP servers are **significantly more token-expensive** than CLI equivalents.
-When both options exist, prefer the CLI tool.
-
-- **Git**: `git` CLI, not Git MCP
-- **Files**: shell commands, not filesystem MCP
-- **APIs**: `curl`/`httpie`, not HTTP MCP
-- **Database**: `mysql`/`psql` CLI, not DB MCP
-
-Exception: MCPs with **unique capabilities** (Sentry, Playwright, Jira).

package/.agent-src/contexts/communication/rules-auto/command-suggestion-policy-mechanics.md

@@ -1,62 +0,0 @@
-# Command Suggestion — mechanics
-
-Output format, anti-noise specifics, and "what this rule does NOT do"
-catalog for the
-[`command-suggestion-policy`](../../../rules/command-suggestion-policy.md)
-rule. The Iron Law (suggest, never invoke), the six-condition fire
-gate, and the subordination list live in the rule; this file is the
-lookup material for the rendered output and engine behavior.
-
-## What to emit — exact format
-
-Render exactly one numbered-options block conforming to
-`user-interaction`:
-
-```
-> 💡 Your request matches a command. Pick one or run the prompt as-is:
->
-> 1. /implement-ticket — drive ticket end-to-end through refine → plan → implement → test
-> 2. /refine-ticket — tighten the AC and risks on a ticket before planning
-> 3. Just run the prompt as-is, no command
-
-**Recommendation: 1 — /implement-ticket** — the request matches its trigger description (`setze ticket abc-123 um`). Pick the last option to skip the command and run the prompt as written.
-```
-
-Rules — non-negotiable:
-
-- The "run as-is" option is **always present**, **always last**, never removed.
-- At most `commands.suggestion.max_options` command suggestions
-  precede the as-is option (default 4 → 5 total).
-- Exactly **one** `Recommendation:` line follows the block, naming
-  the highest-scoring command — or no recommendation when the top
-  two scores are within 0.05 of each other (single-source-of-truth
-  Iron Law from `user-interaction`).
-- Free-text replies count as the as-is option unless they
-  unambiguously name one of the listed commands.
-
-## Anti-noise — silent when uncertain
-
-The engine's `rank.py` already drops:
-
-- Matches below the `confidence_floor` (default 0.6, per-command
-  override in frontmatter).
-- Single matches scoring `< floor + 0.1` with no structural bonus
-  (high uncertainty isn't worth interrupting for).
-- Short prompts (< 6 words) hitting > 2 commands with no structural
-  bonus (ticket key, file path) — too vague to disambiguate.
-- Pure-continuation messages (`ok`, `weiter`, `mach weiter`, `go on`,
-  …) — no new intent signal, no structural bonus → silent.
-- Suggestions that fired for the same `(command, evidence)` pair
-  within the cooldown window (default 10m, per-command override).
-
-If the engine returns an empty list → emit nothing. The user's
-prompt runs exactly as it would without this rule.
-
-## What this rule does NOT do
-
-- Invoke any command. Picking option N is what triggers `slash-command-routing-policy`.
-- Stack with other questions. One numbered-options block per turn.
-- Re-trigger on its own output. Command names emitted in the
-  suggestion block are excluded from the next-turn matcher input.
-- Override `enabled: false`, blocklist entries, or per-conversation opt-out.
-- Suggest commands that are not in the locked eligibility table.

package/.agent-src/contexts/communication/rules-auto/docs-sync-mechanics.md

@@ -1,78 +0,0 @@
-# Docs Sync — mechanics
-
-Update tables, distribution manifests, hook registries, and content
-consistency check details for the
-[`docs-sync`](../../../rules/docs-sync.md) rule. The Iron Rule, the
-mandatory sequence, the two modes (reactive/proactive), the
-settings-template sync, and the "Do NOT" list live in the rule; this
-file is the lookup material when a sync trigger fires.
-
-## What to update — count and category tables
-
-When a file is **added, removed, or renamed**:
-
-| Change | Files to update |
-|---|---|
-| Skill/command/rule count changes | `contexts/augment-infrastructure.md` (count + category table) |
-| New skill category | `contexts/augment-infrastructure.md` + `contexts/skills-and-commands.md` |
-| New workflow chain | `contexts/skills-and-commands.md` (workflow chains section) |
-
-## Cross-reference updates
-
-When a skill is **added or its scope changes**, check and update:
-
-| What | Where to check |
-|---|---|
-| Inline routing hints | "see X skill" or "use X instead" references in other skills |
-| Guideline cross-references | Guidelines that reference the changed skill |
-| Command skill references | Commands that use the changed skill |
-
-## Distribution manifests and hook registries
-
-`.augment/`-internal sync (counts, contexts, cross-refs) is one half. The
-other half is **distribution manifests** that ship the package to consumers
-and **hook registries** that wire engine code into platform lifecycles.
-These are not auto-derived — they drift silently until CI catches them, and
-on cooperative platforms (no pre-commit) they can sit broken in a branch
-for hours.
-
-When a **skill** is added, renamed, or deleted under
-`.agent-src.uncompressed/skills/`:
-
-| Manifest | Required update |
-|---|---|
-| `.claude-plugin/marketplace.json` | Add/remove the `./.claude/skills/<name>` entry in `plugins[0].skills[]`, alphabetical position. Caught by `scripts/lint_marketplace.py` in CI. |
-| `.augment-plugin/marketplace.json` | Skill-name-agnostic — no update needed. Touch only when plugin metadata (description, tags) changes. |
-| `.github/plugin/marketplace.json` | Same as above — metadata-only manifest. |
-
-When a **hook** is added, renamed, or deleted under
-`.agent-src.uncompressed/templates/scripts/work_engine/hooks/builtin/`:
-
-| Registry | Required update |
-|---|---|
-| `templates/scripts/work_engine/hooks/builtin/__init__.py` | New hook class → add the import + `__all__` entry. Single source of truth for engine-side registration. |
-| `templates/consumer-settings/claude-settings.json` | Only when a **new platform event** is wired (e.g. first time a hook listens on `SessionEnd`). Existing hooks reuse the `./agent-config chat-history:hook --platform claude` dispatcher — no per-hook entry needed. |
-| `templates/consumer-settings/augment-cli-hooks.json` | Same logic — new platform event → new `command` block; new hook on existing event → no update. |
-
-Failure mode that motivated this section: a skill on disk without its
-`marketplace.json` entry passes local edits, builds, and tests — only
-CI catches it via `lint_marketplace`. The cooperative path is
-"agent updates the manifest in the same response as the skill"; the
-structural backstop is a pre-commit hook installed by
-`scripts/install-hooks.sh` that runs `lint_marketplace` on every
-commit. Run the installer once per clone; bypass for an unrelated WIP
-commit is `git commit --no-verify`.
-
-## Content consistency check
-
-When a rule, skill, or guideline's **content** is changed (not just
-metadata), search for all other artefacts that cover the same topic
-and verify they are consistent:
-
-```bash
-grep -rl "TOPIC" .augment/rules/ .augment/skills/ .augment/guidelines/ --include="*.md"
-```
-
-If any file contradicts or is missing the updated information →
-update it in the same response. Inconsistent documentation is worse
-than no documentation.

package/.agent-src/contexts/communication/rules-auto/package-ci-checks-mechanics.md

@@ -1,85 +0,0 @@
-# Package CI checks — mechanics
-
-The five required local-CI checks, the quick one-liner, and the
-post-edit workflow rules for the
-[`package-ci-checks`](../../../rules/package-ci-checks.md) rule. The
-Iron Law, the activation trigger, and the "Do NOT" list live in the
-rule; this file is the lookup material when an agent is about to
-push or open a PR in the `agent-config` package repo.
-
-## Required checks (in order)
-
-Run all of these before pushing — they match the GitHub Actions workflows exactly:
-
-### 1. Sync check
-
-```bash
-bash scripts/compress.sh --check          # .agent-src/ matches .agent-src.uncompressed/
-bash scripts/compress.sh --check-hashes   # compression hashes are clean
-```
-
-**Common failure:** Edited uncompressed file but forgot `bash scripts/compress.sh --mark-done {path}`.
-
-### 2. Consistency checks
-
-```bash
-python3 scripts/check_compression.py   # compressed variants are valid
-python3 scripts/check_references.py     # no broken cross-references
-python3 scripts/check_portability.py    # no project-specific references in shared files
-```
-
-**Common failure:** Changed code-blocks in uncompressed but didn't re-compress.
-
-### 3. Linter
-
-```bash
-python3 scripts/skill_linter.py --all   # 0 FAIL required
-```
-
-**Common failure:** New skill missing analysis/verification sections.
-
-### 4. Tests
-
-```bash
-python3 -m pytest tests/ --tb=short     # all tests must pass
-```
-
-**Common failure:** Changed `compress.py` behavior without updating test expectations.
-
-### 5. README
-
-```bash
-python3 scripts/readme_linter.py README.md --root .
-```
-
-## Quick one-liner
-
-Run all checks in sequence — stops on first failure:
-
-```bash
-bash scripts/compress.sh --check && \
-bash scripts/compress.sh --check-hashes && \
-python3 scripts/check_compression.py && \
-python3 scripts/check_references.py && \
-python3 scripts/check_portability.py && \
-python3 scripts/skill_linter.py --all && \
-python3 -m pytest tests/ --tb=short && \
-python3 scripts/readme_linter.py README.md --root .
-```
-
-## After editing skills/rules
-
-When you edit a file in `.agent-src.uncompressed/`:
-
-1. Edit the uncompressed file
-2. Edit the compressed file in `.agent-src/` to match
-3. Run `bash scripts/compress.sh --mark-done {relative-path}` to update the hash
-4. Verify with `bash scripts/compress.sh --check-hashes`
-
-**If you skip step 3, the CI pipeline WILL fail.**
-
-## After editing `scripts/compress.py`
-
-Changes to `compress.py` often break existing tests in `tests/test_compress.py`.
-Always run `python3 -m pytest tests/test_compress.py -v --tb=short` immediately
-after changing `compress.py` — don't wait until the end.

package/.agent-src/contexts/communication/rules-auto/review-routing-awareness-mechanics.md

@@ -1,65 +0,0 @@
-# Review Routing Awareness — mechanics
-
-Memory-lookup snippet, "do NOT overreach" guardrails, and anti-pattern
-catalog for the
-[`review-routing-awareness`](../../../rules/review-routing-awareness.md)
-rule. The four required-behavior steps and the "when this rule applies"
-trigger live in the rule; this file is the lookup material for the
-fallback path and the failure-mode list.
-
-## Memory-lookup fallback
-
-If neither `.github/ownership-map.yml` (or `agents/ownership-map.yml`)
-nor `.github/historical-bug-patterns.yml` (or
-`agents/historical-bug-patterns.yml`) exists, fall back to the
-engineering-memory layer via
-[`memory-access`](../../../../docs/guidelines/agent-infra/memory-access.md):
-
-```python
-from scripts.memory_lookup import retrieve
-extra = retrieve(
-    types=["ownership", "historical-patterns"],
-    keys=<changed file paths>,
-    limit=5,
-)
-```
-
-Curated memory (`agents/memory/ownership.yml`,
-`agents/memory/historical-patterns.yml`) carries the same schema as the
-project-local YAMLs and is merged into the routing output alongside
-them. If both memory and project YAMLs are absent, skip the rule and
-rely on [`reviewer-awareness`](../../../rules/reviewer-awareness.md)
-defaults. **Do not invent owners or patterns** from context.
-
-## Surface findings — worked examples
-
-When producing a review plan, include:
-
-- **Owner-mapped roles** — explicitly preferred over generic roles. If
-  the ownership map says `app/Billing/**` is owned by `finance-engineering
-  + security`, use those, not "backend + security".
-- **Historical-pattern warnings** — list every matched pattern with a
-  short label and the required control, e.g. _"Pattern: N+1 on tenant
-  listings → add an eager-load regression test"_.
-- **Confidence note** — if the ownership map is stale (last updated > 6
-  months ago per the `updated` field), say so. Ownership maps rot.
-
-## Do NOT overreach
-
-- **Never rename paths** or add ownership entries as a side effect of a
-  code change. Ownership map edits are a separate, explicit task.
-- **Never mark a change safe** only because no pattern matched. Pattern
-  absence means "no known hit", not "no risk".
-- **Never copy historical-pattern names into the diff** as code comments
-  or commit messages — they are routing metadata, not commentary.
-
-## Anti-patterns — reject them
-
-- Suggesting owners "because this looks like billing code" without
-  consulting the ownership map when one exists.
-- Inventing historical patterns from general knowledge — patterns must
-  come from the project's own registry.
-- Downgrading a matched high-severity pattern because "the author said
-  it's fine" — the pattern was registered because it bit before.
-- Treating an out-of-date map as absent. Flag staleness; do not silently
-  skip.

package/.agent-src/contexts/communication/rules-auto/roadmap-progress-sync-mechanics.md

@@ -1,78 +0,0 @@
-# Roadmap Progress Sync — mechanics
-
-Mechanics, triggers, and failure-mode catalog for the
-[`roadmap-progress-sync`](../../../rules/roadmap-progress-sync.md)
-rule. The Iron Laws and status semantics live in the rule; this
-file holds the lookup material the rule pulls when a trigger fires.
-
-## How to regenerate
-
-```bash
-./agent-config roadmap:progress
-```
-
-The `./agent-config` wrapper is written into the project root by the
-package installer and delegates to the master CLI inside
-`node_modules/@event4u/agent-config/` or `vendor/event4u/agent-config/`.
-No global tooling required.
-
-## Triggers
-
-| Edit | Must run, same response |
-|---|---|
-| **Create a new roadmap file** | regenerate dashboard |
-| **Rename or delete a roadmap file** | regenerate dashboard |
-| Mark step `[x]`, `[~]`, `[-]`, or unmark back to `[ ]` | regenerate dashboard |
-| Add, rename, or remove a phase | regenerate dashboard |
-| **Last `[ ]` flips** — roadmap reaches `count_open == 0` | `git mv` → `archive/` (or `skipped/`) **then** regenerate dashboard |
-| Move roadmap between `roadmaps/` ↔ `archive/` ↔ `skipped/` | regenerate dashboard |
-
-**Batching rule:** if you edit multiple checkboxes in one response, a
-**single** regeneration at the end of that response is enough — but
-the response must not end without it. If one of those edits closes a
-roadmap, archive it first, then run the single regen.
-
-## Pre-send self-check — MANDATORY
-
-Before sending any reply that touched `agents/roadmaps/`, run this
-silent gate:
-
-1. Did this turn create, rename, delete, or move a roadmap file? → regen MUST be in the reply.
-2. Did this turn flip any checkbox in a roadmap file? → regen MUST be in the reply.
-3. Did the regen output (`✅ Wrote agents/roadmaps-progress.md · …`) actually appear this turn? → if no, run it now before sending.
-4. **Autonomous roadmap execution gate** — did this turn complete a roadmap step (code saved + verification passed) without flipping its checkbox? → flip `[x]` (or `[~]` if multi-turn) and regen before sending.
-5. **Trackable-roadmap gate** — did this turn create or substantially edit a roadmap file? → does it now contain at least one `- [ ]` per non-intro phase, **or** carry `status: draft` in frontmatter? → if neither, add the checklist or the draft flag before sending.
-
-Any "yes" + no regen run = rule violation. Rerun before sending.
-
-## Failure modes
-
-- **Created the roadmap, marked Phase 1 done across multiple turns,
-  never regenerated** — dashboard silently lies "this roadmap does
-  not exist" to the next reader. Canonical failure of this rule;
-  the rule was hardened in response to it.
-- **Regenerated yesterday, edited today, "I'll regen at session
-  end"** — session ends from a crash, regen never lands.
-- **Closed a roadmap (last `[ ]` → `[x]`) and regenerated before
-  `git mv`** — the closed roadmap reappears in "Open roadmaps".
-- **Edited the dashboard by hand to "fix it quickly"** — next regen
-  overwrites the manual edit; no audit trail of why.
-- **Autonomous run, four steps shipped across four turns, dashboard
-  flat the whole time, single regen at the end** — user lost
-  progress visibility for the entire run. Each completed step must
-  flip its checkbox in the reply that ships it.
-- **Decision-only roadmap shipped without checkboxes** — file
-  contains decisions / ICE / block-sequencing but zero `- [ ]`,
-  dashboard shows `0/0` or omits it. Pair with a `## Phase N`
-  section or mark `status: draft` (CI catches this now).
-- **Headings off-canon (`### P0 #N`, `## Block A`, `### Sequencing
-  — Phase 1`)** — `PHASE_RE` skips them, roadmap invisible to the
-  dashboard. Rename to `## Phase <id>` or mark `status: draft`.
-
-## Do NOT
-
-- Do NOT edit `agents/roadmaps-progress.md` by hand — always regenerate.
-- Do NOT defer the regen to "next commit" or "before push" — same response.
-- Do NOT rely on CI (`--check` mode) as the first line of defence — CI is last-line, not real-time.
-- Do NOT skip the regen because "only one checkbox changed" — the dashboard aggregates counts and phase percentages that shift on single edits.
-- Do NOT leave a 100%-complete roadmap in `agents/roadmaps/` "for review" — `git mv` to archive **before** regenerating, otherwise it reappears in "Open roadmaps".

package/.agent-src/contexts/communication/rules-auto/ui-audit-gate-mechanics.md

@@ -1,53 +0,0 @@
-# UI-audit gate — mechanics
-
-Findings-shape spec, failure-mode catalog, and cloud-surface
-adaptation for the
-[`ui-audit-gate`](../../../rules/ui-audit-gate.md) rule. The Iron
-Law, the activation triggers, the allow-list, and the action sequence
-when the gate fires live in the rule; this file is the lookup
-material when an agent has to verify what counts as findings or
-recognise a failure mode.
-
-## What "audit findings" means
-
-`state.ui_audit` is a non-empty dict carrying at least one of:
-
-- `components_found` — `{path, name, kind, similarity?}` inventory
-  entries from [`existing-ui-audit`](../../../skills/existing-ui-audit/SKILL.md).
-- `greenfield: true` plus `greenfield_decision` ∈
-  `{scaffold, bare, external_reference}`.
-- Legacy `components` alias — back-compat for the same shape.
-
-`null`, `{}`, or a dict without those keys is **not** findings;
-emit `@agent-directive: existing-ui-audit` instead of writing code.
-
-## Failure modes
-
-- Writing the component first and "thinking about reuse later".
-- Citing a similar-looking component from memory without verifying
-  it via the audit.
-- Treating `state.ui_audit = {}` as "audit ran, found nothing" —
-  empty dict is rejected on purpose; an audit that finds nothing
-  must record either ≥1 `components_found` or the greenfield branch.
-- Bypassing the gate for "just one tile".
-
-## Interactions
-
-- [`improve-before-implement`](../../../rules/improve-before-implement.md) — runs
-  first when the request is ambiguous; this rule is the next gate.
-- [`ask-when-uncertain`](../../../rules/ask-when-uncertain.md) — "just build it"
-  does **not** drop the audit; acknowledge, run audit, continue.
-- [`directives/ui/audit.py`](../../../templates/scripts/work_engine/directives/ui/audit.py)
-  — code-layer twin; this rule covers the cases where the engine
-  is not in the loop.
-- [`existing-ui-audit`](../../../skills/existing-ui-audit/SKILL.md) — the
-  skill that produces the findings.
-
-## Cloud Behavior
-
-On cloud surfaces the engine is not shipped, so `state.ui_audit`
-does not exist. The Iron Law still applies: take the visible
-inventory of files in conversation context as the audit, and
-surface a one-line audit summary in the reply before writing the
-component. The gate is satisfied by an explicit summary, not by
-silently skipping.