@event4u/agent-config 1.22.0 → 1.24.0

package/.agent-src/rules/no-cheap-questions.md

@@ -20,17 +20,9 @@ NEVER OFFER NUMBERED CHOICES WITHOUT A REAL TRADE-OFF.
 
 ## What counts as cheap
 
-- **Sequencing** — "Step 2 or 3 next?" when the roadmap orders them.
-- **Format-only** — "Table or paragraph?"; no semantic trade-off.
-- **Commit asks** — forbidden by [`commit-policy`](commit-policy.md).
-- **CI / test asks** — [`verify-before-complete`](verify-before-complete.md) decides, not the user.
-- **Fenced-step re-asks** — "Start Phase 1?" after *"plan only"*; see [`scope-control § fenced step`](scope-control.md#fenced-step--user-set-review-gates).
-- **Iron-Law option** — breaches `commit-policy`, `scope-control § git-ops`, or `non-destructive-by-default`.
-- **Context-derived** — answer follows from prior turn / standing instruction / roadmap; act, state the assumption inline.
-- **Dominant option** — one choice obviously correct; alternatives carry no upside.
-- **Re-ask after decline** — forbidden per [`scope-control § decline = silence`](scope-control.md#decline--silence--no-re-asking-on-the-same-task).
-
-Examples per class: [`asking-and-brevity-examples § cheap-question-catalog`](../docs/guidelines/agent-infra/asking-and-brevity-examples.md#cheap-question-class-catalog--extended-examples).
+Nine classes — sequencing · format-only · commit asks (forbidden by [`commit-policy`](commit-policy.md)) · CI / test asks ([`verify-before-complete`](verify-before-complete.md) decides) · fenced-step re-asks ([`scope-control § fenced step`](scope-control.md#fenced-step--user-set-review-gates)) · Iron-Law option (breaches `commit-policy`, `scope-control § git-ops`, or `non-destructive-by-default`) · context-derived · dominant option · re-ask after decline ([`scope-control § decline = silence`](scope-control.md#decline--silence--no-re-asking-on-the-same-task)).
+
+Per-class patterns and examples: [`asking-and-brevity-examples § cheap-question-catalog`](../docs/guidelines/agent-infra/asking-and-brevity-examples.md#cheap-question-class-catalog--extended-examples).
 
 ## Pre-Send Self-Check — MANDATORY before every question
 
@@ -55,6 +47,4 @@ Any "yes" → **do not ask**. Pick the dominant path, state assumption inline (*
 
 In doubt → ask. This rule narrows asking, never widens silence.
 
-## Interactions
-
-[`ask-when-uncertain`](ask-when-uncertain.md) · [`autonomous-execution`](autonomous-execution.md) · [`commit-policy`](commit-policy.md) · [`scope-control`](scope-control.md) · [`non-destructive-by-default`](non-destructive-by-default.md) · [`user-interaction`](user-interaction.md) · [`direct-answers`](direct-answers.md).
+Cross-rule index: [`frugality-charter § cross-references`](../contexts/contracts/frugality-charter.md#cross-references--frugality-canon-rules).

package/.agent-src/rules/roadmap-progress-sync.md

@@ -1,7 +1,7 @@
 ---
 type: "auto"
 tier: "1"
-description: "Any touch to agents/roadmaps/ — create/rename/delete/move, edit checkboxes ([x]/[~]/[-]), add/rename/remove phases — must regenerate dashboard and archive if 0 open items, same response"
+description: "Any roadmap touch (file move, checkbox flip, phase change) regens dashboard same response; archive at 0 open. Autonomous runs flip each checkbox the SAME reply, never batched at the end."
 source: package
 triggers:
   - path_prefix: "agents/roadmaps/"
@@ -11,7 +11,41 @@ routes_to:
 
 # Roadmap Progress Sync
 
-**Iron Law.** Any touch to `agents/roadmaps/` regenerates the dashboard in the same response; archive the roadmap when 0 open items remain.
+## Iron Law 1 — dashboard sync, same response
 
-Body migrated to `guideline:agent-infra/roadmap-progress-mechanics` (per P4 of `road-to-kernel-and-router.md`).
+```
+ANY ROADMAP TOUCH → REGENERATE THE DASHBOARD, SAME RESPONSE.
+NO EXCEPTIONS. NO "I'LL DO IT AT THE END". NO BATCHING ACROSS TURNS.
+```
+
+Roadmap touch = create / rename / delete / move file, add/rename/remove a phase, OR flip any checkbox (`[ ]` ↔ `[x]` ↔ `[~]` ↔ `[-]`). Regen command: `./agent-config roadmap:progress`. Archive (`git mv` → `archive/`) the moment `count_open == 0` — same response.
+
+## Iron Law 2 — real-time checkbox cadence (autonomous execution)
+
+```
+EVERY DONE STEP FLIPS [ ] → [x] IN THE SAME REPLY THAT LANDS THE WORK.
+NO "I UPDATE THE ROADMAP AT THE END OF THE PHASE."
+NO "FOUR STEPS DONE, ONE COMMIT, ONE REGEN."
+A REPLY THAT LANDS A VERIFIED STEP WITHOUT FLIPPING ITS CHECKBOX
+IS A RULE VIOLATION, NOT AN OVERSIGHT.
+```
+
+`/roadmap:process-step`, `/roadmap:process-phase`, `/roadmap:process-full`, and any other multi-step autonomous run flip the box for step N **before** moving on to step N+1. The dashboard is a real-time monitor, not a post-hoc summary. Batched flips at the archive commit defeat the dashboard's purpose.
+
+**Step counts as done** when its code/doc change is written and saved AND the verification cited in the step has passed (fresh output in this reply or an earlier one).
+
+**In-progress marker.** When a step takes more than one reply, mark it `[~]` the moment work starts and regen — the user sees one row move `[ ] → [~] → [x]` instead of silent rows. `[~]` stays open for `count_open` but advances the phase percentage.
+
+## Pre-send self-check — MANDATORY
+
+Before sending any reply that landed roadmap work:
+
+1. Did this reply land a step (code/doc saved + verification passed)?
+2. Is its checkbox flipped to `[x]` / `[~]` / `[-]` in `agents/roadmaps/<file>.md`? If no → flip, then continue.
+3. Did `./agent-config roadmap:progress` run after the flip? If no → run, then continue.
+4. Did `count_open` reach 0? If yes → `git mv` to `archive/` and regen again — same reply.
+
+Any "no" at step 2 or 3 → reply is incomplete. Do not send.
+
+Long-form mechanics (failure-mode catalog, Copilot fallback, `[~]` vs `[ ]` semantics, hook + CI defence-in-depth) live in `guideline:agent-infra/roadmap-progress-mechanics`.
 Trigger-set above activates this routing under the `balanced` and `full` profiles.

package/.agent-src/rules/token-efficiency.md

@@ -21,16 +21,14 @@ NEVER load full command output into context. Redirect → read summary → targe
 ```
 
 ```
-NEVER call the same tool more than 2 times in a row with similar parameters.
-If you catch yourself repeating a tool call — STOP, rethink, try a different approach, or ask the user.
+NEVER CALL THE SAME TOOL >2 TIMES IN A ROW WITH SIMILAR PARAMETERS.
+IF YOU CATCH YOURSELF REPEATING → STOP, RETHINK, ASK.
 ```
 
 ## Fresh Output Over Memory
 
-When a tool or command returns a value (branch name, file path, PR number), use that EXACT value in subsequent API calls. NEVER substitute a value from earlier in the conversation. Context decay → silent mismatches — fresh output is the only source of truth.
+When a tool returns a value (branch name, file path, PR number), use that EXACT value in subsequent API calls. NEVER substitute a value from earlier in the conversation. Context decay causes silent mismatches — fresh output is the only source of truth.
 
-## Mechanics — anti-loop patterns, conversation efficiency, exceptions
+## Mechanics
 
-The anti-loop patterns (extended-reasoning loops, "CRITICAL INSTRUCTION" self-prompting), the act-skip-narration / stop-early / keep-output-minimal / don't-re-read / minimize-tool-calls clauses, and the small-output / debugging / explicit-full-output exceptions all live in [`contexts/communication/rules-auto/token-efficiency-mechanics.md`](../contexts/communication/rules-auto/token-efficiency-mechanics.md). The rule above is the obligation surface; the mechanics file is the lookup material.
-
-This rule NEVER overrides `user-interaction` or command rules. Token efficiency means fewer *unnecessary* words — NOT skipping required questions, numbered options, or command steps.
+Anti-loop patterns, act-skip-narration / stop-early / minimize-tool-calls clauses, and small-output / debugging exceptions: [`token-efficiency-mechanics`](../contexts/communication/rules-auto/token-efficiency-mechanics.md). Precedence: never overrides `user-interaction` or command rules.

package/.agent-src/skills/adr-create/SKILL.md

@@ -0,0 +1,197 @@
+---
+name: adr-create
+description: "Use when capturing an architectural decision — naming the file, picking the next ADR number, filling Status / Context / Decision / Consequences, and regenerating the index — even without saying 'ADR'."
+source: package
+execution:
+  type: assisted
+  handler: shell
+  timeout_seconds: 30
+  allowed_tools: []
+  command:
+    - python3
+    - scripts/adr/regenerate_index.py
+---
+
+# adr-create
+
+## When to use
+
+Use this skill when:
+
+- A non-trivial architectural choice needs a written record (kernel
+  membership, cap raises, contract changes, library swap, deprecation).
+- A decision overrides a previous one and needs `supersedes:` linkage.
+- A roadmap phase closes and the chosen variant must be cited.
+- The user says "write an ADR for X", "decision log this", "we need
+  a record of why we picked Y".
+
+Do NOT use when:
+
+- The change is reversible without governance impact (typo, lint
+  fix, refactor that stays inside one module).
+- The decision is already covered by an existing ADR — extend or
+  supersede it instead of duplicating.
+- A skill, rule, or guideline is the better home (use those skills).
+
+## Goal
+
+- Sequential `ADR-NNN-<slug>.md` numbering with no gaps.
+- Standard template: Status, Context, Decision, Consequences,
+  Alternatives, References.
+- Regenerated index so readers find the ADR by topic, not by ls.
+- Zero MCP-tool dependency — pure filesystem + Python.
+
+## Preconditions
+
+- An ADR directory exists (default `docs/adr/`; `docs/decisions/` is
+  the recognised alias used in this package and many older projects).
+- The decision is **already made** — ADRs record outcomes, they do
+  not run the decision process. For unresolved trade-offs, run the
+  council or consult `adversarial-review` first.
+
+## Procedure
+
+### 1. Inspect and resolve the ADR directory
+
+Identify the canonical directory in this order:
+
+1. `docs/adr/` — default per spec.
+2. `docs/decisions/` — accepted alias if `docs/adr/` is missing.
+3. Anything else — fail, ask the user to pick one of the two
+   canonical paths. Do not invent a third location.
+
+### 2. Pick the next ADR number
+
+Scan the directory for `ADR-*.md`, parse the leading 3-digit number,
+take `max + 1` (zero-padded). For an empty directory, start at `001`.
+Reject re-use of an existing number — the index regenerator treats
+duplicates as a hard failure.
+
+### 3. Pick a slug
+
+Short, hyphen-lowercase, scope-revealing. Match peer ADRs in the
+directory. Examples: `kernel-swap-deferred`, `flat-cluster-subs`,
+`http-bridge-deferred-with-trigger`. Reject slugs longer than 60 chars.
+
+### 4. Author the ADR
+
+Use the standard template (frontmatter + body). All sections are
+required; "n/a" is acceptable for genuinely empty Alternatives or
+References blocks but never for Status, Context, Decision, or
+Consequences.
+
+```markdown
+---
+adr: NNN
+status: proposed | accepted | superseded | deprecated
+date: YYYY-MM-DD
+decision: <slug>
+supersedes: — | ADR-MMM
+superseded_by: — | ADR-MMM
+phase: <roadmap> · <phase-id>
+---
+
+# ADR-NNN — <Decision Title>
+
+## Status
+
+**<Proposed | Accepted | …>** · YYYY-MM-DD.
+
+## Context
+
+What problem forced this decision? What constraints applied? What
+alternatives were on the table at decision time?
+
+## Decision
+
+The chosen variant, in one paragraph. Concrete enough that a reader
+six months later knows what was actually picked.
+
+## Consequences
+
+### Accepted
+
+- Hard guarantees we now make.
+
+### Trade-offs
+
+- What we gave up. Mitigations, if any.
+
+## Alternatives considered
+
+- **Variant X — <name>.** Rejected because <reason>.
+- **Variant Y — <name>.** Rejected because <reason>.
+
+## References
+
+- Linked roadmap, contract, prior ADR, council session id.
+```
+
+### 5. Regenerate the index
+
+Run the dispatcher:
+
+```bash
+python3 scripts/runtime_dispatcher.py run --skill adr-create
+# or directly:
+python3 scripts/adr/regenerate_index.py --dir docs/adr/
+```
+
+The script scans `ADR-*.md`, reads frontmatter (`adr`, `status`,
+`date`, `decision`, `supersedes`), and writes `INDEX.md` with one
+table row per ADR plus broken-supersede warnings on stderr.
+
+### 6. Validate
+
+- `python3 scripts/adr/regenerate_index.py --check` exits 0
+  (index is up to date, no number gaps, no broken supersedes).
+- The project's CI / quality pipeline passes locally.
+
+## Output format
+
+1. Path of the new `ADR-NNN-<slug>.md` file.
+2. Path of the regenerated `INDEX.md`.
+3. One-line summary of the decision.
+4. Linked roadmap or phase, if any.
+
+## Gotchas
+
+- `docs/adr/` is the default path; some projects use
+  `docs/decisions/` (this package included). Pass `--dir` to the
+  index regenerator when running outside the default.
+- Frontmatter `adr:` is the canonical number; the filename prefix
+  must match. The index regenerator fails on mismatch.
+- ADRs are append-only history. To revise a decision, write a new
+  ADR with `supersedes: ADR-MMM` and flip the old one's status to
+  `superseded`.
+- Never delete an ADR file — supersede it. Deletion breaks
+  historical links and round-trips through git history checks.
+
+## Frugality Standards
+
+Apply the [Frugality Charter](../../contexts/contracts/frugality-charter.md)
+to every ADR you author.
+
+**Examples in this artifact:**
+- Per the charter's default-terse rule, `## Context` states the
+  forcing function in 2–3 sentences; no historical narrative.
+- Per the cite-don't-restate principle, `## Decision` links the
+  rules / contracts it overrides; no rule body is quoted in full.
+- Per the cheap-question check, `## Alternatives considered` lists
+  genuine design alternatives, not strawmen.
+
+**Pre-save self-check:**
+1. Does `## Context` carry more than 5 sentences of setup?
+2. Does `## Decision` restate rule text instead of citing the rule?
+3. Are alternatives evaluated with a real consequence each, or with
+   stylistic preference?
+4. Does the ADR forecast consequences with hedge phrases ("might",
+   "could potentially") instead of decidable claims?
+
+## Do NOT
+
+- Skip Context — a decision without context is folklore.
+- Reuse an existing ADR number — the index regenerator hard-fails.
+- Author ADRs for reversible refactors or minor cleanups.
+- Cite a council session id without ensuring the file is committed
+  or otherwise reachable from the repo (per `no-council-references`).

package/.agent-src/skills/agent-docs-writing/SKILL.md

@@ -168,6 +168,7 @@ When starting work, read documentation in this order:
 | Significant multi-step change | Ask user about creating a roadmap in `agents/roadmaps/` |
 | New convention introduced | Update relevant doc in `./agents/` or `.augment/guidelines/` |
 | Database schema changed | Update `agents/docs/database-setup.md` |
+| Architectural decision made | Use the [`adr-create`](../adr-create/SKILL.md) skill — writes a numbered ADR under `docs/adr/` (or `docs/decisions/`) and regenerates the index |
 
 ## When to update documentation
 
@@ -187,7 +188,7 @@ After completing a significant code change, run this mental checklist:
 | New API endpoint | OpenAPI annotations, `AGENTS.md` API section |
 | New module created | Create `app/Modules/{Module}/agents/` |
 | Service/repository signature changed | Check if referenced in `agents/docs/services-and-repos.md` |
-| New environment variable | `.env.example`, `AGENTS.md` env section |
+| New environment variable | `.env.example`, `AGENTS.md` environment section |
 | Docker/compose change | `agents/docs/docker.md`, `Makefile` documentation |
 | New Artisan command | `AGENTS.md` commands section |
 | New pattern/convention introduced | Relevant guideline in `.augment/guidelines/` |
@@ -220,6 +221,27 @@ Do NOT auto-update docs without the user's knowledge. Flag what needs updating a
 - AGENTS.md and copilot-instructions.md have different audiences — don't copy content between them.
 - Module docs go in `app/Modules/*/agents/`, NOT in the central `agents/` directory.
 
+## Frugality Standards
+
+Apply the [Frugality Charter](../../contexts/contracts/frugality-charter.md)
+to every agent-doc update you author.
+
+**Examples in this artifact:**
+- Per the charter's default-terse rule, doc updates state what
+  changed; no "In this section we will…" frames.
+- Per the cheap-question check, AGENTS.md surface offers options
+  only where the project genuinely diverges.
+- Per the post-action summary suppression, doc edits append change
+  notes to the existing log entry; no new "Summary of changes" block.
+
+**Pre-save self-check:**
+1. Does the doc open with a narrative intro instead of the actual
+   content?
+2. Are paragraphs added that summarize an existing table?
+3. Does the doc duplicate the rule index instead of linking the
+   relevant rule?
+4. Is German prose present outside `DE: / EN:` anchor blocks?
+
 ## Do NOT
 
 - Do NOT create docs unless there's a real need (new module, significant change).

package/.agent-src/skills/command-writing/SKILL.md

@@ -166,6 +166,29 @@ multi-paragraph explanation, extract it into a skill and call it.
   `.agent-src.uncompressed/`.
 * Duplicating another command's workflow instead of delegating via `skills:`.
 
+## Frugality Standards
+
+Apply the [Frugality Charter](../../contexts/contracts/frugality-charter.md)
+to every command you author.
+
+**Examples in this artifact:**
+- Per the charter's default-terse rule, command output blocks state
+  the action result, not "Now we will execute…".
+- Per the post-action summary suppression, the success path emits
+  the artifact (PR URL, commit hash) without a wrapping summary.
+- Per the cheap-question check, never offer "preview vs. execute"
+  as a numbered option when the command's role is to execute.
+
+**Pre-save self-check:**
+1. Does any command step prescribe a "Let me…" or "Found it" output
+   line?
+2. Does the command default to multi-line summaries when a one-line
+   outcome suffices?
+3. Is a confirmation gate used outside the Iron-Law / Routine /
+   Contextual taxonomy?
+4. Are template placeholders (`{{var}}`) accompanied by setup prose
+   instead of action prose?
+
 ## Do NOT
 
 * Do NOT set `disable-model-invocation: false`

package/.agent-src/skills/context-authoring/SKILL.md

@@ -156,6 +156,29 @@ schema regex and by `scripts/lint_load_context.py`. Body links to
 Canonical reference: `rule-writing` § 3b and
 `docs/contracts/load-context-schema.md`.
 
+## Frugality Standards
+
+Apply the [Frugality Charter](../../contexts/contracts/frugality-charter.md)
+to every context file you author.
+
+**Examples in this artifact:**
+- Per the charter's index nature, context files are reviewer fuel —
+  they hold mechanics, not Iron-Law obligations.
+- Per the cite-don't-restate principle, when a section mirrors a
+  rule, link the rule and stop.
+- Per the act-skip-narration rule, lookup tables open the section;
+  explanatory prose follows only if the table is ambiguous.
+
+**Pre-save self-check:**
+1. Does the context file restate Iron-Law text instead of linking
+   the rule?
+2. Does any section open with "This document explains…" instead of
+   the lookup material?
+3. Are placeholders (`<add me>`, `TBD`) shipped instead of actual
+   content?
+4. Are the cited rules linked with stable anchors (verified to
+   exist)?
+
 ## Do NOT
 
 - Do NOT copy content between projects. Every context file is local to its

package/.agent-src/skills/conventional-commits-writing/SKILL.md

@@ -113,6 +113,29 @@ Or add `BREAKING CHANGE:` in the commit body/footer.
 - Squash merge titles should describe the net effect, not every internal detail
 - `refactor` means NO behavior change — if behavior changes, use `feat` or `fix`
 
+## Frugality Standards
+
+Apply the [Frugality Charter](../../contexts/contracts/frugality-charter.md)
+to every commit message you author.
+
+**Examples in this artifact:**
+- Per the charter's default-terse rule, the subject states the
+  change in 50 chars; no scaffolding ("This commit will…").
+- Per the post-action summary suppression, the body lists changed
+  surfaces in bullets — no closing paragraph re-summarizing them.
+- Per the cheap-question check, never propose a `feat` vs. `chore`
+  numbered choice when the type is decidable from the diff.
+
+**Pre-save self-check:**
+1. Does the subject line carry filler ("various improvements",
+   "general updates")?
+2. Does the body re-narrate the diff instead of stating intent?
+3. Are co-author / attribution footers present without explicit user
+   request (per
+   [`no-attribution-footers`](../../rules/no-attribution-footers.md))?
+4. Is the type / scope chosen from the diff, not from the asker's
+   framing?
+
 ## Do NOT
 
 - Do NOT use vague messages: `update stuff`, `fix bug`, `changes`

package/.agent-src/skills/guideline-writing/SKILL.md

@@ -130,6 +130,28 @@ Above the split signal, break by sub-topic into sibling files in the same folder
 * Hollowing out a skill into "see guideline" — the skill must remain
   executable (see `preservation-guard`).
 
+## Frugality Standards
+
+Apply the [Frugality Charter](../../contexts/contracts/frugality-charter.md)
+to every guideline you author.
+
+**Examples in this artifact:**
+- Per the charter's index nature, guidelines describe practice
+  patterns; they do **not** restate Iron-Laws from rules.
+- Per the act-skip-narration rule, code examples lead with the
+  pattern, not its motivation.
+- Per the cheap-question check, guidelines do not prescribe stylistic
+  forks ("table vs. paragraph") — pick one.
+
+**Pre-save self-check:**
+1. Does the guideline restate text from a rule body instead of
+   linking the rule?
+2. Are code examples preceded by narrative ramp-up?
+3. Does the guideline introduce a new convention without citing the
+   rule that holds the obligation?
+4. Are sections labeled "Overview" / "Background" carrying only
+   restatement?
+
 ## Do NOT
 
 * Do NOT add `type:` or `alwaysApply:` to the frontmatter

package/.agent-src/skills/learning-to-rule-or-skill/SKILL.md

@@ -285,6 +285,15 @@ Decision: Create focused skill for Laravel route inspection via JSON and jq.
 Learning: "I forgot to run PHPStan once."
 Decision: No action — one-off, already covered by verify-before-complete rule.
 
+Learning: "We re-invented a per-format PDF extractor in three different
+analysis skills."
+Decision: Update the affected skills to dispatch to
+[`markitdown`](../markitdown/SKILL.md) instead of writing new
+extractors. Non-text ingestion (PDF / DOCX / XLSX / PPTX / image /
+audio) goes through the upstream `markitdown-mcp` server first; only
+write a custom extractor if `markitdown` cannot handle the format and
+the gap is documented in its skill body.
+
 ## Environment notes
 
 Prefer updating existing rule/skill when possible.