@event4u/agent-config 1.22.0 → 1.23.0

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Shared agent configuration \u2014 skills for AI coding tools (Claude Code, Augment, Cursor, Cline, Windsurf, Gemini CLI).",
-    "version": "1.22.0"
+    "version": "1.23.0"
   },
   "plugins": [
     {
@@ -15,6 +15,7 @@
       "source": "./",
       "strict": false,
       "skills": [
+        "./.claude/skills/adr-create",
         "./.claude/skills/adversarial-review",
         "./.claude/skills/agent-docs-writing",
         "./.claude/skills/agent-handoff",
@@ -61,6 +62,7 @@
         "./.claude/skills/context-document",
         "./.claude/skills/context-refactor",
         "./.claude/skills/conventional-commits-writing",
+        "./.claude/skills/cost-report",
         "./.claude/skills/copilot-agents",
         "./.claude/skills/copilot-agents-init",
         "./.claude/skills/copilot-agents-optimization",
@@ -172,6 +174,7 @@
         "./.claude/skills/package-test",
         "./.claude/skills/performance",
         "./.claude/skills/performance-analysis",
+        "./.claude/skills/persona-writing",
         "./.claude/skills/pest-testing",
         "./.claude/skills/php-coder",
         "./.claude/skills/php-debugging",
@@ -211,9 +214,11 @@
         "./.claude/skills/roadmap-process-full",
         "./.claude/skills/roadmap-process-phase",
         "./.claude/skills/roadmap-process-step",
+        "./.claude/skills/roadmap-writing",
         "./.claude/skills/rtk-output-filtering",
         "./.claude/skills/rule-compliance-audit",
         "./.claude/skills/rule-writing",
+        "./.claude/skills/script-writing",
         "./.claude/skills/security",
         "./.claude/skills/security-audit",
         "./.claude/skills/sentry-integration",

package/AGENTS.md

@@ -167,9 +167,9 @@ appends to `agents/.rule-budget-history.jsonl`.
 
 ```
 .agent-src.uncompressed/      ← edit here
-  skills/       (136 skills)
-  rules/        (59 rules)
-  commands/     (102 commands)
+  skills/       (140 skills)
+  rules/        (60 rules)
+  commands/     (103 commands)
   personas/     (7 personas)
   templates/    (AGENTS.md, copilot-instructions.md, skill.md, …)
   contexts/

package/CHANGELOG.md

@@ -318,6 +318,41 @@ our recommendation order, not its support status.
   users" tension without removing any path that an existing user
   might rely on.
 
+## [1.23.0](https://github.com/event4u-app/agent-config/compare/1.22.0...1.23.0) (2026-05-08)
+
+### Features
+
+* **skills:** add script-writing skill for scripts/ conventions ([1f8655d](https://github.com/event4u-app/agent-config/commit/1f8655d6cbf007410e3846ab502eea5745a7f66f))
+* **scripts:** Phase 10.7 --quiet flag + silent Taskfile + caveman compile-time toggle ([1d319e6](https://github.com/event4u-app/agent-config/commit/1d319e61a3c782eb5c86075f34275306a67c621c))
+* **linter:** frugality charter writer-cite validator + writer skill citations ([0e34709](https://github.com/event4u-app/agent-config/commit/0e3470965d5e2f4a8b11f27137d4ba43d2471be2))
+* **verbosity:** add verbosity toggles + gate routine outputs ([580d4cc](https://github.com/event4u-app/agent-config/commit/580d4cc2d1f4d4b091b6128f0a29d1f7e619895d))
+* **roadmap-sync:** pre-commit backstop blocks stale dashboard ([c577fc0](https://github.com/event4u-app/agent-config/commit/c577fc0aabc13faaae64c88d20d8ca66338ae5fc))
+* **create-pr:** drop council-review prompt ([e694811](https://github.com/event4u-app/agent-config/commit/e694811f7ca06b3db275cc70e83e6dbc4db72e42))
+* cite SPARC escalation thresholds in test-driven-development ([836f2ed](https://github.com/event4u-app/agent-config/commit/836f2edc2c288bcc7f878e97f42de954add8bb5b))
+* add mcp-request-signing guideline with HTTP-bridge appendix ([2ab67cd](https://github.com/event4u-app/agent-config/commit/2ab67cd401333ea61f47d43e952e7b07958feff3))
+* add cost-report command with token cost tracking ([262d865](https://github.com/event4u-app/agent-config/commit/262d865072d613647a439e89f83ded7334b60b1b))
+* add adr-create skill with index regeneration script ([7225105](https://github.com/event4u-app/agent-config/commit/7225105797d6810cad75bfa851f02b100e41ba29))
+
+### Bug Fixes
+
+* **docs:** bump command counts to 103 after cost-report addition ([2810fa5](https://github.com/event4u-app/agent-config/commit/2810fa5a54b7099123ae65e6c7c1325430bf3b77))
+
+### Documentation
+
+* sync counts (139 skills, 60 rules) + meta cleanups ([00c8b21](https://github.com/event4u-app/agent-config/commit/00c8b211edbc86cbe2f886107227e6bd46049c3b))
+* codify defer-with-trigger harvest policy ([b30dcd7](https://github.com/event4u-app/agent-config/commit/b30dcd72d0ffbd1fb2dbdd8ca28493a5b05a6bed))
+
+### Refactoring
+
+* **rules:** apply trim-frugality-canon Phase 1-3 trims ([ea1828a](https://github.com/event4u-app/agent-config/commit/ea1828af7bc69426386f6852cb69891309dce65f))
+
+### Chores
+
+* regenerate stale generated mirrors ([ea52e94](https://github.com/event4u-app/agent-config/commit/ea52e94415c4db5598e91d001e0fbeee10cae9be))
+* regenerate auto-generated artefacts ([fbe7d9e](https://github.com/event4u-app/agent-config/commit/fbe7d9ef137c9e584d7f88ce660afe29ab1a8d00))
+* bump skill/command/guideline counts and compression hashes ([18f4fad](https://github.com/event4u-app/agent-config/commit/18f4fad2372fd4347210199986909319c24ea0ec))
+* archive ruflo-adoption, move caveman-integration to skipped ([4c6c1eb](https://github.com/event4u-app/agent-config/commit/4c6c1eb1e00356421e0038704a82e1f10ac9a3e5))
+
 ## [1.22.0](https://github.com/event4u-app/agent-config/compare/1.21.0...1.22.0) (2026-05-07)
 
 ### Features

package/README.md

@@ -7,7 +7,7 @@ Give your AI agents an audit-disciplined orchestration contract — testing, Git
 > Your agent picks up the project's stack, runs tests, prepares PRs, fixes CI — and follows your team's coding standards while doing it. Stack-aware skill sets ship for PHP (Laravel · Symfony · Zend/Laminas), JavaScript (Next.js · React · Node), and cross-stack concerns (API · testing · security · observability).
 
 <p align="center">
-  <strong>136 Skills</strong> · <strong>59 Rules</strong> · <strong>102 Commands</strong> · <strong>56 Guidelines</strong> · <strong>8 AI Tools</strong>
+  <strong>140 Skills</strong> · <strong>60 Rules</strong> · <strong>103 Commands</strong> · <strong>58 Guidelines</strong> · <strong>8 AI Tools</strong>
 </p>
 
 ---
@@ -343,7 +343,7 @@ kernel set: [`docs/contracts/kernel-membership.md`](docs/contracts/kernel-member
 | [`/jira-ticket`](.agent-src/commands/jira-ticket.md) | Read ticket from branch, implement feature |
 | [`/compress`](.agent-src/commands/compress.md) | Compress skills for token efficiency |
 
-→ [Browse all 95 active commands](.agent-src/commands/)
+→ [Browse all 103 active commands](.agent-src/commands/)
 
 ---
 
@@ -368,7 +368,7 @@ Every developer gets the same behavior. No per-user setup needed.
 native slash-commands)
 
 > **What this means in practice:** Augment Code and Claude Code get the full
-> package (rules + 136 skills + 95 native commands). Cursor, Cline, Windsurf,
+> package (rules + 140 skills + 103 native commands). Cursor, Cline, Windsurf,
 > Gemini CLI, and GitHub Copilot only get the **rules** natively; skills and
 > commands are available to them as documentation the agent can read, not as
 > first-class features.
@@ -413,6 +413,8 @@ for the per-rule routing.
 - **Challenge to improve** — agents are thought partners, not yes-machines
 - **Strict by design** — quality over flexibility
 - **Zero overhead by default** — nothing runs until you ask for it
+- **Terse-by-default chat output** — verbosity flags off, intent narration off,
+  caveman-speak prose-only — flip back via [`docs/customization.md` § Verbosity](docs/customization.md#verbosity)
 
 ---
 
@@ -480,10 +482,8 @@ re-enabled or the chat ends. Full scoring contract and hardening:
 Edit in `.agent-src.uncompressed/`, compress, verify:
 
 ```bash
-task sync          # Sync non-.md files
 task ci            # Run all CI checks
 task test          # Run all tests
-task lint-skills   # Lint skills, rules, commands
 ```
 
 → Full commands and project structure: [**docs/development.md**](docs/development.md)

package/docs/architecture.md

@@ -96,10 +96,10 @@ fails on any source-side violation, without producing artifacts.
 
 | Layer | Count | Purpose |
 |---|---|---|
-| **Skills** | 136 | On-demand expertise — stack analysis (Laravel · Symfony · Zend / Laminas · Next.js · React · Node), testing, Docker, API design, security, observability, … |
-| **Rules** | 59 | Always-active constraints — coding standards, scope control, verification, language-and-tone, agent-authority |
-| **Commands** | 102 | Slash-command workflows — `/commit`, `/create-pr`, `/fix ci`, `/optimize skills`, `/feature plan`, `/work`, `/implement-ticket`, `/compress`, … |
-| **Guidelines** | 56 | Reference material cited by skills — PHP patterns, Eloquent, Playwright, agent-infra, … |
+| **Skills** | 140 | On-demand expertise — stack analysis (Laravel · Symfony · Zend / Laminas · Next.js · React · Node), testing, Docker, API design, security, observability, … |
+| **Rules** | 60 | Always-active constraints — coding standards, scope control, verification, language-and-tone, agent-authority |
+| **Commands** | 103 | Slash-command workflows — `/commit`, `/create-pr`, `/fix ci`, `/optimize skills`, `/feature plan`, `/work`, `/implement-ticket`, `/compress`, … |
+| **Guidelines** | 58 | Reference material cited by skills — PHP patterns, Eloquent, Playwright, agent-infra, … |
 | **Templates** | 7 | Scaffolds for features, roadmaps, contexts, skills, overrides |
 | **Contexts** | 5 | Shared knowledge about the system itself |
 

package/docs/customization.md

@@ -120,6 +120,78 @@ behavior — the per-profile table is just the initial default.
 
 `custom` ignores these defaults — set every value explicitly.
 
+### Verbosity
+
+The `verbosity:` block and `caveman.speak_scope` control how much narration
+the agent emits around routine actions. Defaults are tuned for token
+frugality — flip values to `true` (or higher tier) to restore legacy verbose
+output. Iron-Law gates (`commit-policy`, `scope-control` git-ops,
+`non-destructive-by-default`) ALWAYS confirm regardless of these flags.
+
+| Setting | Values | Default | Description |
+|---|---|---|---|
+| `verbosity.preview_artifacts` | `true`, `false` | `false` | Show generated commit messages, PR titles/bodies, and branch names before acting. `false` = use the generated content directly. |
+| `verbosity.routine_confirmations` | `true`, `false` | `false` | Confirmation prompts for routine workflow steps when there is one obvious answer ("looks good — commit?"). Iron-Law gates always ask regardless. |
+| `verbosity.offer_council_in_delivery` | `true`, `false` | `false` | Offer "run AI Council on this?" inside delivery commands (`/feature-plan`, `/review-changes`, `/roadmap-create`). The `/council` command itself is unaffected. |
+| `verbosity.post_action_reports` | `off`, `minimal`, `full` | `minimal` | Multi-line status / summary blocks after a successful action. `off` = no report; `minimal` = one-line confirmation; `full` = bullet list. |
+| `verbosity.intent_announcements` | `true`, `false` | `false` | Intent announcements ("Let me check…", "Now I will…", "Found it") in skill bodies. `false` = act and emit the result. |
+| `verbosity.script_output` | `silent`, `minimal`, `verbose` | `minimal` | Stdout chatter from `scripts/*.py`, `scripts/*.sh`, and `.augment/scripts/`. `silent` = stderr only; `minimal` = one summary line per script; `verbose` = pre-Phase-10 per-step prints. Iron-Law surfaces (release confirms, install secrets prompts, error markers) ignore this key. |
+| `verbosity.taskfile_command_echo` | `true`, `false` | `false` | Suppress the `task: [name] cmd...` echo Taskfile prints before each task body. `true` = echoes preserved (legacy behaviour); `false` = `silent: true` is set on every Phase-10 safe task. |
+| `caveman.speak_scope` | `off`, `prose_only`, `aggressive` | `prose_only` | How widely caveman-speak grammar applies in chat. `off` = no caveman; `prose_only` = caveman in body prose, numbered options + Iron-Law-literal blocks stay full prose; `aggressive` = caveman everywhere except Iron-Law literals. |
+
+The cross-rule index for these defaults lives in
+[`.agent-src.uncompressed/contexts/contracts/frugality-charter.md`](../.agent-src.uncompressed/contexts/contracts/frugality-charter.md).
+Writer skills (`skill-writing`, `rule-writing`, `command-writing`,
+`guideline-writing`, `roadmap-writing`, `persona-writing`,
+`agent-docs-writing`, `context-authoring`, `conventional-commits-writing`,
+`readme-writing`, `readme-writing-package`, `adr-create`) cite the charter
+under their `## Frugality Standards` section.
+
+#### Behavior change vs. legacy — `/create-pr` silent draft default
+
+When `verbosity.routine_confirmations: false` (the new default),
+`/create-pr` creates the PR as a **draft silently** instead of asking
+"draft or ready?". A one-line postscript surfaces the override:
+
+```
+→ #42 opened: https://github.com/org/repo/pull/42
+→ created as draft — run `gh pr ready 42` to flip
+```
+
+Per-invocation overrides (no settings change required):
+
+| You want | Argument |
+|---|---|
+| Ready-for-review immediately | `/create-pr:ready` or `/create-pr:final` |
+| Explicit draft (no postscript change) | `/create-pr:draft` |
+| Numbered prompt restored | set `verbosity.routine_confirmations: true` |
+
+`/create-pr` still skips the AI council prompt unconditionally per the
+existing carve-out — `verbosity.offer_council_in_delivery` does not
+re-enable it. Use `/council diff:<base>..<head>` separately.
+
+#### Script-output level — env-var overrides
+
+`verbosity.script_output` is read by `scripts/_lib/script_output.py`.
+For incident debugging when editing `.agent-settings.yml` is awkward,
+two env vars override the file for the current process tree:
+
+| Env var | Value | Effect |
+|---|---|---|
+| `AGENT_SCRIPT_VERBOSITY` | `silent`, `minimal`, `verbose` | Authoritative — wins over the settings file |
+| `SCRIPT_OUTPUT_VERBOSE` | `1` | Alias — equivalent to `AGENT_SCRIPT_VERBOSITY=verbose` |
+
+Once the helper resolves the level, it exports the resolved value back
+into `AGENT_SCRIPT_VERBOSITY` so child processes inherit the same level
+without re-reading the settings file. Per-call `--quiet` flags on a
+child script still win at the call site (per-call override > inherited
+level).
+
+Iron-Law surfaces — production-deploy confirmation prompts in
+`scripts/release.py`, secret-installer prompts in `install_*_key.sh`,
+and any output via `error()` — bypass the helper and stay loud at every
+level.
+
 ---
 
 ## Project documentation

package/docs/decisions/INDEX.md

@@ -0,0 +1,15 @@
+# ADR Index
+
+_Auto-generated by `scripts/adr/regenerate_index.py`. Do not edit._
+
+| # | Title | Status | Date | Supersedes |
+|---|---|---|---|---|
+| [ADR-001](ADR-001-kernel-swap-deferred.md) | Kernel Swap Deferred | accepted | 2026-05-06 | — |
+| [ADR-002](ADR-002-kernel-bucket-overrides.md) | Kernel Bucket Overrides | — | — | — |
+| [ADR-003](ADR-003-flat-cluster-subs-and-colon-syntax.md) | Flat Cluster Subs And Colon Syntax | — | — | — |
+
+## Unnumbered (legacy)
+
+| # | Title | Status | Date | Supersedes |
+|---|---|---|---|---|
+| [ADR-rule-kernel-and-router](ADR-rule-kernel-and-router.md) | — | — | — | — |

package/docs/getting-started.md

@@ -115,7 +115,7 @@ Your agent is now:
 - **Respecting your codebase** — no conflicting patterns
 - **Following standards** — consistent code quality
 
-This is enforced automatically by 59 rules. No configuration needed.
+This is enforced automatically by 60 rules. No configuration needed.
 
 ---
 
@@ -153,7 +153,7 @@ Your agent now understands slash commands:
 | `/quality-fix` | Run and fix all quality checks |
 | `/chat-history` | Inspect the persistent chat-history log (read-only `show`) |
 
-→ [Browse all 95 active commands](../.agent-src/commands/)
+→ [Browse all 103 active commands](../.agent-src/commands/)
 
 ---
 

package/docs/guidelines/agent-infra/asking-and-brevity-examples.md

@@ -12,21 +12,22 @@ always-loaded rule body — extracted to fit the always-rule budget.
 
 ## Vague-request triggers — example questions
 
-Companion to `ask-when-uncertain` § Vague-request triggers. The rule
-lists the trigger patterns and the "missing info" columns; this file
-adds the example question to ask back at the user.
+Companion to `ask-when-uncertain` § Vague-request triggers. This
+section is the canonical home for the nine trigger patterns, the
+missing-info each one hides, and the example clarifying question —
+the rule cites it instead of restating the catalog.
 
-| Pattern | Example clarifying question |
-|---|---|
-| "improve / optimize this" | "Optimize for what — execution speed or readability?" |
-| "add caching" | "Which cache driver, and what invalidates it?" |
-| "make it better / cleaner" | "What specifically feels wrong in the current code?" |
-| "clean up this file" | "Remove unused code, reformat, or restructure?" |
-| "fix this" (without specifying) | "What output/behavior is wrong right now?" |
-| "refactor X" | "Refactor toward what — smaller methods, extract class, or something else?" |
-| "use best practices" | "Best practices for what specifically — testing, naming, structure?" |
-| "handle errors properly" | "For which failure modes, and what should happen on error?" |
-| "add a UI / component / tile / page" when the repo mixes frameworks | "This repo uses {A} and {B} for UI — which one for this?" |
+| Pattern | Missing info | Example clarifying question |
+|---|---|---|
+| "improve / optimize this" | metric — speed, readability, memory? | "Optimize for what — execution speed or readability?" |
+| "add caching" | store, scope, invalidation | "Which cache driver, and what invalidates it?" |
+| "make it better / cleaner" | by what standard? | "What specifically feels wrong in the current code?" |
+| "clean up this file" | dead code, format, refactor? | "Remove unused code, reformat, or restructure?" |
+| "fix this" (no symptom) | what output is wrong? | "What output/behavior is wrong right now?" |
+| "refactor X" | target pattern, boundaries | "Refactor toward what — smaller methods, extract class, or something else?" |
+| "use best practices" | whose, for what? | "Best practices for what specifically — testing, naming, structure?" |
+| "handle errors properly" | which errors — log/retry/propagate? | "For which failure modes, and what should happen on error?" |
+| "add a UI / component / tile / page" in mixed-framework repo | which stack? | "This repo uses {A} and {B} for UI — which one for this?" |
 
 ## One-question-per-turn — why serial always wins
 
@@ -49,8 +50,10 @@ next. Serial preserves the framing; parallel destroys it.
 
 ## Cheap-question class catalog — extended examples
 
-Companion to `no-cheap-questions` § What counts as cheap. The rule
-lists the classes; this file adds longer-form examples per class.
+Companion to `no-cheap-questions` § What counts as cheap. This
+section is the canonical home for the nine cheap-question classes
+and their per-class patterns — the rule cites it instead of
+restating the catalog.
 
 | Class | Pattern · why cheap | Concrete example |
 |---|---|---|
@@ -66,9 +69,10 @@ lists the classes; this file adds longer-form examples per class.
 
 ## Direct-answers — severity-tiered claim examples
 
-Companion to `direct-answers` § Iron Law 2 (no invented facts). The
-rule lists the severity table; this file adds concrete examples and
-hedge-language patterns.
+Companion to `direct-answers` § Iron Law 2 (no invented facts). This
+section is the canonical home for the severity tiers, per-tier
+verification actions, and the override carve-out — the rule cites it
+instead of restating the table.
 
 | Severity | Examples | Verification action |
 |---|---|---|
@@ -76,6 +80,10 @@ hedge-language patterns.
 | **Medium — project-shape** | "This project uses Pest for testing", "controllers live under `app/Http/Controllers`" | Verify if one tool call reaches it; otherwise hedge: *"I'd guess X — not checked"*. |
 | **Low — well-known idioms** | "PHP `array_map` returns a new array", "git tags are immutable", "JS arrays are zero-indexed" | Inference acceptable. Mark as inference if not 100% sure. |
 
+**Override:** "just guess" / "rough estimate" / "skip verify" in the
+user's turn drops every claim to **Low** for that turn only. Reverts
+on the next turn unless the user repeats the override.
+
 Hedge-language patterns:
 
 - ✅ "haven't verified X — likely from {known-similar-codebase}"

package/docs/guidelines/agent-infra/carve-out-predicates.md

@@ -0,0 +1,17 @@
+# Decidable Carve-Out Predicates
+
+Companion to [`frugality-charter`](../../../.agent-src.uncompressed/contexts/contracts/frugality-charter.md). Each carve-out below carries a one-sentence test. If the test cannot be answered yes/no from the artifact alone, the carve-out does not fire and default-terse rules apply.
+
+## Predicates
+
+- **Iron-Law literal** — the prose is an ALL-CAPS fenced block inside a rule whose title appears in [`docs/contracts/kernel-membership.md`](../../contracts/kernel-membership.md).
+
+- **Numbered-options with genuine trade-off** — the options differ in consequence (a chosen path produces a measurably different artifact or state), not in sequencing or output format. Per [`no-cheap-questions § What counts as cheap`](../../../.agent-src.uncompressed/rules/no-cheap-questions.md#what-counts-as-cheap).
+
+- **Security-sensitive prompt** — the prompt requires credential input OR modifies auth / tenant / secret state, matching a trigger in [`security-sensitive-stop`](../../../.agent-src.uncompressed/rules/security-sensitive-stop.md).
+
+- **Structured CLI contract** — the script's stdout is consumed by another script (a downstream parser exists under `scripts/` or `.augment/scripts/`), so the format is part of an interface contract, not narration.
+
+## How to use
+
+Writer skills (`skill-writing`, `rule-writing`, `command-writing`, `guideline-writing`, `context-authoring`, `agent-docs-writing`, `conventional-commits-writing`, `readme-writing`, `readme-writing-package`, `adr-create`, `persona-writing`, `roadmap-writing`) cite this file when an artifact's pre-save check needs a decidable test for a carve-out exception. The default is **terse** — predicates here only fire when the artifact provides the yes/no evidence.

package/docs/guidelines/agent-infra/mcp-request-signing.md

@@ -0,0 +1,199 @@
+# MCP Request Signing (HMAC-SHA256)
+
+Reference guideline for signing JSON-RPC requests crossing any non-stdio
+MCP transport — HTTP, SSE, WebSocket, anything routable. Stdio over a
+trusted parent-child pipe is **outside** the scope of this guideline; only
+network-exposed transports require signing.
+
+Lands ahead of any HTTP-MCP transport so the security floor is in place
+when one becomes a real consumer use case (see
+[`road-to-mcp-server.md`](../../../agents/roadmaps/road-to-mcp-server.md)
+Phase 4 D4 — allowlist).
+
+Adapted from
+[`ruvnet/ruflo`](https://github.com/ruvnet/ruflo) — commit
+[`1dd1db1`](https://github.com/ruvnet/ruflo/blob/1dd1db1ec2572ce68f6805dff98c177b5771cbf9/ruflo/src/mcp-bridge/mcp-stdio-kernel.js)
+`ruflo/src/mcp-bridge/mcp-stdio-kernel.js` — `CRYPTO_SEG`. The full
+Express bridge (`index.js`, ~1.6k LOC) stays authoritative-link only;
+this guideline forks the **primitive**, not the runtime.
+
+## When signing is mandatory
+
+- Any HTTP / SSE / WebSocket MCP transport — the wire is shared with
+  arbitrary callers.
+- Any cross-host stdio bridge (parent and child on different machines).
+- Any MCP server reachable from a browser context.
+
+## When signing is **not** required
+
+- Plain stdio MCP server invoked as a child process by one trusted client
+  on the same host. The OS pipe is the trust boundary.
+- Local-only loopback served behind a Unix domain socket with `0700`
+  permissions on the socket file.
+
+If unsure → sign. The cost is one HMAC per request.
+
+## Signing pattern (~30 LOC reference)
+
+`KERNEL_SECRET` is a per-installation shared secret loaded from env or a
+secrets store. Never commit it. `randomUUID()` is Node's
+`crypto.randomUUID`.
+
+```js
+import { createHmac, randomUUID } from 'node:crypto';
+
+const KERNEL_SECRET = process.env.MCP_KERNEL_SECRET;
+const KERNEL_ID = `mcp-kernel-${process.pid}`;
+
+function signRequest(payload) {
+  const timestamp = Date.now();
+  const nonce = randomUUID();
+  const data = `${timestamp}:${nonce}:${JSON.stringify(payload)}`;
+  const signature = createHmac('sha256', KERNEL_SECRET)
+    .update(data)
+    .digest('hex');
+  return { timestamp, nonce, signature, kernelId: KERNEL_ID };
+}
+
+// On every outbound MCP request:
+const sig = signRequest(body);
+headers['X-MCP-Kernel'] = sig.kernelId;
+headers['X-MCP-Signature'] = sig.signature;
+headers['X-MCP-Timestamp'] = String(sig.timestamp);
+headers['X-MCP-Nonce'] = sig.nonce;
+```
+
+Header names are project-namespaced; the upstream Ruflo file uses
+`X-RVF-*`, the convention here is `X-MCP-*`.
+
+## Verification pattern (server-side counterpart)
+
+```js
+import { createHmac, timingSafeEqual } from 'node:crypto';
+
+const KERNEL_SECRET = process.env.MCP_KERNEL_SECRET;
+const MAX_SKEW_MS = 5 * 60 * 1000;        // 5 min
+const seenNonces = new Map();             // nonce -> expiresAt
+
+function verifyRequest(headers, rawBody) {
+  const ts = Number(headers['x-mcp-timestamp']);
+  const nonce = headers['x-mcp-nonce'];
+  const sig = headers['x-mcp-signature'];
+  if (!ts || !nonce || !sig) return false;
+  if (Math.abs(Date.now() - ts) > MAX_SKEW_MS) return false;
+  if (seenNonces.has(nonce)) return false;          // replay
+  const data = `${ts}:${nonce}:${rawBody}`;
+  const expected = createHmac('sha256', KERNEL_SECRET).update(data).digest();
+  const got = Buffer.from(sig, 'hex');
+  if (got.length !== expected.length) return false;
+  if (!timingSafeEqual(got, expected)) return false;
+  seenNonces.set(nonce, Date.now() + MAX_SKEW_MS);
+  return true;
+}
+```
+
+`timingSafeEqual` is non-negotiable — `===` on a hex string is a timing
+oracle. The nonce store must evict on `expiresAt` to bound memory; a
+plain `setInterval` sweep every minute is enough.
+
+## Threat model
+
+| Threat | Mitigation in this pattern |
+|---|---|
+| **Replay** — attacker captures a valid request and resends it | `nonce` + `seenNonces` set; replays inside the skew window are rejected, replays outside it fail the timestamp check |
+| **MITM (non-stdio)** — wire-level rewrite | HMAC over `${ts}:${nonce}:${body}` — any payload tamper invalidates the signature; pair with TLS in production |
+| **Clock skew abuse** — long-lived request | `MAX_SKEW_MS = 5 min` rejects out-of-window timestamps |
+| **Timing oracle on signature compare** | `timingSafeEqual`, never `===` |
+| **Secret exfil via repo / log** | `KERNEL_SECRET` from env or secrets store; never log raw headers; redact `X-MCP-Signature` in any audit trail |
+| **Allowlist bypass** | Signing **does not** authorize what's called — pair with the allowlist enforced at server boot ([`road-to-mcp-server.md`](../../../agents/roadmaps/road-to-mcp-server.md) Phase 4 **D4**); a valid signature on a non-allowlisted tool name still rejects |
+
+## Citation hooks
+
+- [`road-to-mcp-server.md`](../../../agents/roadmaps/road-to-mcp-server.md)
+  **Phase 4 D4** — allowlist enforced at server boot. Signing layers
+  *under* the allowlist: verify signature → look up tool in allowlist →
+  execute. Both gates must pass.
+- [`road-to-mcp-server.md`](../../../agents/roadmaps/road-to-mcp-server.md)
+  **Phase 6 F2 / F3** — SSE transport, cloud bundle. These are the
+  triggers that make this guideline load-bearing; until then it is
+  reference material for the deferred-with-trigger HTTP-bridge slot of
+  [`road-to-ruflo-adoption.md`](../../../agents/roadmaps/road-to-ruflo-adoption.md)
+  Phase 2 P2.1.
+
+## Operational notes
+
+- **Secret rotation** — rotate `MCP_KERNEL_SECRET` on a fixed cadence
+  (90 days minimum). Both client and server reload from env on the next
+  request; in-flight requests fail and retry with the new secret.
+- **Multi-client deployments** — give every client kernel a distinct
+  `KERNEL_ID` so logs attribute to a source even though all use the
+  same shared secret.
+- **Don't sign `tools/list`** — `tools/list` is read-only metadata; it
+  can stay unsigned in deployments where the metadata itself is public.
+  `tools/call` must always be signed.
+
+## Out-of-scope
+
+- The full Express bridge in `ruflo/src/mcp-bridge/index.js` (~1.6k LOC,
+  HTTP routing, SSE streaming, auth proxying) — authoritative-link only,
+  not forked. If we ever need an HTTP-MCP server, build on this
+  guideline + the host's web framework, not on Ruflo's runtime.
+- Asymmetric signing (Ed25519, ECDSA). HMAC-SHA256 is sufficient for
+  shared-secret deployments. Asymmetric is only worth the complexity
+  when keys cross trust boundaries the shared-secret model can't
+  represent.
+
+## Appendix — HTTP-bridge `stdio-kernel` pattern (reference)
+
+Portable shape of Ruflo's `mcp-stdio-kernel.js` (~250 LOC), on hand for
+the day a real HTTP-MCP consumer surfaces (`road-to-mcp-server.md`
+Phase 6 F2 / F3). Full file stays **authoritative-link only**:
+[`mcp-stdio-kernel.js`](https://github.com/ruvnet/ruflo/blob/1dd1db1ec2572ce68f6805dff98c177b5771cbf9/ruflo/src/mcp-bridge/mcp-stdio-kernel.js).
+
+**Trigger to inline more:** both — (a) Phase 1 ships stdio prompt fetch
+in ≥1 confirmed client, (b) ≥1 consumer surfaces a concrete HTTP-MCP
+use case. Until then, this appendix + upstream link is the adoption.
+
+### Pattern shape
+
+The kernel sits between the HTTP transport and the spawned stdio MCP
+child. Inbound: HTTP → `verifyRequest` → JSON-RPC onto child stdin.
+Outbound: child stdout → parsed → signed response → HTTP.
+
+```
+client ──HTTP──▶ kernel.verify ──stdin──▶ stdio MCP child
+client ◀─HTTP── kernel.sign  ◀─stdout── stdio MCP child
+```
+
+Six load-bearing pieces:
+
+1. **Process supervisor** — spawn with `stdio: ['pipe', 'pipe', 'inherit']`,
+   restart on exit with bounded backoff, SIGTERM on shutdown.
+2. **JSON-RPC framing** — newline-delimited JSON; buffer partial
+   stdout reads; drop unparseable frames with a logged warning, never
+   crash the bridge.
+3. **Request-id correlation** — kernel generates outbound `id`, maps
+   `kernelId → clientId`; slow calls can't cross-talk between HTTP
+   clients.
+4. **Verification gate** — `verifyRequest` (above) before stdin write;
+   failure is a 401, never a 500; never log the raw signature.
+5. **Allowlist enforcement** — after verify, look up the JSON-RPC
+   `method` in the boot-time allowlist (`road-to-mcp-server.md` **D4**).
+   Non-allowlisted → JSON-RPC `-32601 Method not found`; no enumeration
+   leak.
+6. **Backpressure** — bound the in-flight queue per kernel (Ruflo
+   uses 32); beyond it, return `429`. Otherwise a flood OOMs the child.
+
+### Out of this appendix
+
+Express routes / middleware / SSE upgrade — host web framework.
+Ruflo marketplace + `mcp__claude-flow__*` tools — never adopted (see
+`road-to-ruflo-adoption.md` Sunset path). Multi-tenant routing —
+out-of-scope until a consumer surfaces a tenancy requirement.
+
+### Citation hooks
+
+- `road-to-mcp-server.md` **Phase 6 F2 / F3** — SSE / cloud-bundle work
+  starts here; the upstream link is the authoritative source.
+- `road-to-ruflo-adoption.md` **P2.1** — landed this appendix; full
+  bridge fork stays out-of-scope unless the dual trigger fires.

package/docs/guidelines/agent-infra/roadmap-progress-mechanics.md

@@ -9,10 +9,17 @@ _Origin: migrated from `.agent-src.uncompressed/rules/roadmap-progress-sync.md`
 
 # Roadmap Progress Sync
 
-> **Enforced by:** [`scripts/roadmap_progress_hook.py`](../../scripts/roadmap_progress_hook.py)
-> on Augment + Claude Code (`PostToolUse`). Hook is primary; the prose
-> below is the specification the hook implements and the fallback when
-> the platform has no hook surface.
+> **Enforced by (defence in depth):**
+> 1. [`scripts/roadmap_progress_hook.py`](../../scripts/roadmap_progress_hook.py)
+>    on Augment + Claude Code (`PostToolUse`) — auto-regen on write.
+> 2. `.git/hooks/pre-commit` (installed by `scripts/install-hooks.sh`) —
+>    blocks any commit whose staged set touches `agents/roadmaps/` or
+>    `agents/roadmaps-progress.md` while the dashboard is stale.
+> 3. `task ci` runs `roadmap-progress-check` so a PR cannot land with a
+>    stale dashboard even if local hooks were bypassed.
+>
+> Hook is primary; the prose below is the specification the hook
+> implements and the fallback when the platform has no hook surface.
 
 ## Iron Law — dashboard sync
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@event4u/agent-config",
-    "version": "1.22.0",
+    "version": "1.23.0",
     "description": "Shared agent configuration \u2014 skills, rules, commands, guidelines, and templates for AI coding tools",
     "license": "MIT",
     "private": false,

package/scripts/_lib/__init__.py

@@ -0,0 +1,5 @@
+# scripts/_lib — shared helpers for scripts/*.py.
+#
+# Phase 10 of road-to-token-frugality. The first member is
+# `script_output` — a thin verbosity-aware print router that reads
+# `.agent-settings.yml` and the `AGENT_SCRIPT_VERBOSITY` env var.