@event4u/agent-config 1.21.0 → 1.23.0

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/naming.md

@@ -41,7 +41,7 @@ source: package
 | Pattern | When | Examples |
 |---|---|---|
 | `{verb}-{target}` | Action commands | `create-pr`, `fix-ci`, `commit` |
-| `{target}-{verb}` | Target-first grouping | `roadmap-create`, `roadmap-execute` |
+| `{target}-{verb}` | Target-first grouping | `roadmap-create` (legacy atomic; current cluster form is `/roadmap:create` and `/roadmap:process-step|phase|full`) |
 | `{scope}-{action}` | Scoped actions | `optimize-agents`, `review-changes` |
 
 ### Guidelines

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.21.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.

package/scripts/_lib/script_output.py

@@ -0,0 +1,140 @@
+"""Verbosity-aware print router for scripts/*.py.
+
+Phase 10 of road-to-token-frugality. Single source of truth for how
+maintenance scripts emit progress, success, warnings, and errors.
+
+Resolution order (first wins):
+  1. AGENT_SCRIPT_VERBOSITY env var      (silent | minimal | verbose)
+  2. SCRIPT_OUTPUT_VERBOSE=1 alias       (== verbose)
+  3. .agent-settings.yml verbosity.script_output
+  4. Default: minimal
+
+Once resolved, the level is exported back into AGENT_SCRIPT_VERBOSITY
+so child processes inherit the same level (Phase 10.1c). Explicit
+--quiet flags on the child still win at the call site.
+
+Levels:
+  silent   = stderr only; success() drops; info() drops; warn() drops
+  minimal  = success() collapsed to one end-of-run summary; info() drops
+  verbose  = pre-Phase-10 behaviour, every call prints
+
+error() always writes to stderr regardless of level. Iron-Law surfaces
+(release confirms, install secrets prompts) bypass this module and use
+plain print() so they cannot be silenced.
+"""
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+from typing import Final
+
+VALID_LEVELS: Final[tuple[str, ...]] = ("silent", "minimal", "verbose")
+DEFAULT_LEVEL: Final[str] = "minimal"
+ENV_VAR: Final[str] = "AGENT_SCRIPT_VERBOSITY"
+ENV_ALIAS: Final[str] = "SCRIPT_OUTPUT_VERBOSE"
+SETTINGS_FILE: Final[str] = ".agent-settings.yml"
+
+_resolved_level: str | None = None
+_pending_summary: list[str] = []
+
+
+def _read_settings_level(settings_path: Path) -> str | None:
+    """Read verbosity.script_output from .agent-settings.yml.
+
+    Returns None when the file is missing, PyYAML is unavailable, or
+    the key is absent. Errors fall through to the default level.
+    """
+    if not settings_path.is_file():
+        return None
+    try:
+        import yaml  # type: ignore[import-untyped]
+    except ImportError:
+        return None
+    try:
+        with settings_path.open(encoding="utf-8") as fh:
+            data = yaml.safe_load(fh) or {}
+    except (OSError, yaml.YAMLError):
+        return None
+    section = data.get("verbosity") if isinstance(data, dict) else None
+    if not isinstance(section, dict):
+        return None
+    value = section.get("script_output")
+    if isinstance(value, str) and value in VALID_LEVELS:
+        return value
+    return None
+
+
+def resolve_level(settings_path: Path | None = None) -> str:
+    """Resolve and cache the active verbosity level.
+
+    First call wins; subsequent calls return the cached value so the
+    process is internally consistent. Tests reset via reset_level().
+    """
+    global _resolved_level
+    if _resolved_level is not None:
+        return _resolved_level
+
+    env_value = os.environ.get(ENV_VAR, "").strip().lower()
+    if env_value in VALID_LEVELS:
+        _resolved_level = env_value
+    elif os.environ.get(ENV_ALIAS, "").strip() == "1":
+        _resolved_level = "verbose"
+    else:
+        path = settings_path or Path(SETTINGS_FILE)
+        _resolved_level = _read_settings_level(path) or DEFAULT_LEVEL
+
+    # Inheritance: export resolved level so child processes see it.
+    os.environ[ENV_VAR] = _resolved_level
+    return _resolved_level
+
+
+def reset_level() -> None:
+    """Clear the cached level. Test helper."""
+    global _resolved_level
+    _resolved_level = None
+    _pending_summary.clear()
+
+
+def info(message: str) -> None:
+    """Per-step progress note. Drops at silent + minimal."""
+    if resolve_level() == "verbose":
+        print(message)
+
+
+def success(message: str) -> None:
+    """Per-step success. At minimal collected for end-of-run summary;
+    at verbose printed immediately; at silent dropped."""
+    level = resolve_level()
+    if level == "verbose":
+        print(message)
+    elif level == "minimal":
+        _pending_summary.append(message)
+
+
+def warn(message: str) -> None:
+    """Warning. Stderr at all levels except silent."""
+    if resolve_level() != "silent":
+        print(message, file=sys.stderr)
+
+
+def error(message: str) -> None:
+    """Error. Always stderr regardless of level."""
+    print(message, file=sys.stderr)
+
+
+def flush_summary(headline: str | None = None) -> None:
+    """Emit the pending success() summary at end-of-run.
+
+    No-op at verbose (already printed) and silent (suppressed).
+    Use the explicit `headline` arg to override the auto-pick.
+    """
+    level = resolve_level()
+    if level != "minimal" or not _pending_summary:
+        return
+    if headline:
+        print(headline)
+    else:
+        # Default: print the last collected line as the headline.
+        print(_pending_summary[-1])
+    _pending_summary.clear()

package/scripts/_phase2_shim_helper.py

@@ -25,7 +25,7 @@ PHASE2_SHIMS: list[tuple[str, str]] = [
     ("propose-memory", "memory propose"),
     # roadmap cluster
     ("roadmap-create",  "roadmap create"),
-    ("roadmap-execute", "roadmap execute"),
+    ("roadmap-execute", "roadmap process-phase"),
     # module cluster
     ("module-create",  "module create"),
     ("module-explore", "module explore"),

package/scripts/adr/regenerate_index.py

@@ -0,0 +1,79 @@
+#!/usr/bin/env python3
+"""Regenerate INDEX.md for an ADR directory. Parses ADR-*.md frontmatter
+(adr/status/date/decision/supersedes), writes INDEX.md, splits legacy
+non-numbered ADRs into an Unnumbered table, hard-fails on duplicate
+numbers, filename/frontmatter mismatch, or broken supersedes links."""
+import argparse, re, sys
+from pathlib import Path
+
+NAMED = re.compile(r"^ADR-(\d{3})-([a-z0-9-]+)\.md$")
+FM = re.compile(r"^---\n(.*?)\n---", re.DOTALL)
+FIELD = re.compile(r"^([a-z_]+):\s*(.+?)\s*$", re.MULTILINE)
+HEAD = "| # | Title | Status | Date | Supersedes |\n|---|---|---|---|---|"
+
+
+def fm(t):
+    m = FM.search(t)
+    return {k: v.strip(" \"'") for k, v in FIELD.findall(m.group(1))} if m else {}
+
+
+def scan(d):
+    num, leg, errs, seen = [], [], [], {}
+    for p in sorted(d.glob("ADR-*.md")):
+        if p.name == "INDEX.md": continue
+        meta, m = fm(p.read_text(encoding="utf-8")), NAMED.match(p.name)
+        if not m:
+            leg.append({"path": p.name, **meta}); continue
+        n = m.group(1)
+        if meta.get("adr") and meta["adr"].lstrip("0") != n.lstrip("0"):
+            errs.append(f"{p.name}: adr={meta['adr']} != filename {n}")
+        if n in seen: errs.append(f"ADR-{n} duplicate: {p.name} and {seen[n]}")
+        seen[n] = p.name
+        num.append({"num": n, "slug": m.group(2), "path": p.name, **meta})
+    nums = {r["num"] for r in num}
+    for r in num:
+        s = r.get("supersedes", "—")
+        if s and s != "—":
+            t = s.replace("ADR-", "").lstrip("0").zfill(3)
+            if t not in nums: errs.append(f"{r['path']}: supersedes ADR-{t} not found")
+    return num, leg, errs
+
+
+def row(r):
+    title = r.get("decision", r.get("slug", "—")).replace("-", " ").title()
+    label = f"ADR-{r['num']}" if "num" in r else r["path"][:-3]
+    return (f"| [{label}]({r['path']}) | {title} | {r.get('status','—')} "
+            f"| {r.get('date','—')} | {r.get('supersedes','—')} |")
+
+
+def render(num, leg):
+    out = ["# ADR Index", "", "_Auto-generated by `scripts/adr/regenerate_index.py`. Do not edit._", ""]
+    if not num and not leg: return "\n".join(out + ["No ADRs yet.", ""])
+    out += [HEAD, *(row(r) for r in num)]
+    if leg: out += ["", "## Unnumbered (legacy)", "", HEAD, *(row(r) for r in leg)]
+    return "\n".join(out + [""])
+
+
+def main():
+    ap = argparse.ArgumentParser(description="Regenerate ADR INDEX.md")
+    ap.add_argument("--dir", default="docs/adr/")
+    ap.add_argument("--check", action="store_true", help="exit 1 if INDEX.md is stale")
+    a = ap.parse_args()
+    d = Path(a.dir)
+    if not d.is_dir():
+        print(f"adr-dir not found: {d}", file=sys.stderr); return 2
+    num, leg, errs = scan(d)
+    for e in errs: print(f"error: {e}", file=sys.stderr)
+    if errs: return 2
+    rendered, idx = render(num, leg), d / "INDEX.md"
+    if a.check:
+        cur = idx.read_text(encoding="utf-8") if idx.exists() else ""
+        if cur != rendered: print(f"stale: {idx}", file=sys.stderr); return 1
+        return 0
+    idx.write_text(rendered, encoding="utf-8")
+    print(f"wrote {idx} ({len(num)} numbered, {len(leg)} legacy)")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/ai_council/one_off_archive/2026-05/_one_off_add_quiet.py

@@ -0,0 +1,149 @@
+#!/usr/bin/env python3
+"""One-off: add --quiet flag to every check_*/lint_* script that lacks one.
+
+Target pattern (the canonical example is check_one_off_location.py):
+- argparse parser exists
+- parser.add_argument("--quiet", action="store_true", help="Only print on failure")
+- success print lines matching `print(...✅...)` are wrapped:
+      if not args.quiet:
+          print("✅ ...")
+
+For scripts without argparse, fall back to a minimal sys.argv probe.
+Reports a manual-review list for anything that doesn't match the simple pattern.
+"""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+SCRIPTS = Path("scripts")
+SUCCESS_RE = re.compile(r'^(\s*)(print\((?:f)?["\'].*\u2705.*\))\s*$')
+# Accept any parser var name (parser, ap, p, …) — capture both lhs (args var) and rhs (parser var).
+PARSE_ARGS_RE = re.compile(
+    r"^(\s*)([A-Za-z_][A-Za-z_0-9]*)\s*=\s*([A-Za-z_][A-Za-z_0-9]*)\.parse_args\(.*\)\s*$"
+)
+TOP_IMPORT_RE = re.compile(r"^(?:import |from )\S")
+
+
+def has_quiet_flag(text: str) -> bool:
+    return '"--quiet"' in text or "'--quiet'" in text
+
+
+def has_argparse(text: str) -> bool:
+    return "argparse" in text and ".add_argument(" in text and ".parse_args(" in text
+
+
+def patch_argparse_script(text: str) -> tuple[str, int]:
+    """Insert --quiet arg before parse_args() call; gate ✅ print lines.
+
+    Returns (new_text, n_prints_gated). Caller checks both for sanity.
+    """
+    lines = text.splitlines(keepends=True)
+    out: list[str] = []
+    inserted = False
+    n_gated = 0
+    parse_args_var: str | None = None
+
+    for line in lines:
+        if not inserted:
+            m = PARSE_ARGS_RE.match(line.rstrip("\n"))
+            if m:
+                indent = m.group(1)
+                parse_args_var = m.group(2)  # lhs (args var)
+                parser_var = m.group(3)      # rhs (parser var: parser/ap/p/…)
+                out.append(
+                    f'{indent}{parser_var}.add_argument("--quiet", action="store_true", '
+                    'help="Only print on failure")\n'
+                )
+                inserted = True
+        out.append(line)
+
+    if not inserted or parse_args_var is None:
+        return text, 0
+
+    # Now rewrite: gate success prints behind `if not <var>.quiet:`
+    text2 = "".join(out)
+    lines2 = text2.splitlines(keepends=True)
+    out2: list[str] = []
+    for line in lines2:
+        m = SUCCESS_RE.match(line.rstrip("\n"))
+        if m:
+            indent, stmt = m.group(1), m.group(2)
+            out2.append(f"{indent}if not {parse_args_var}.quiet:\n")
+            out2.append(f"{indent}    {stmt}\n")
+            n_gated += 1
+        else:
+            out2.append(line)
+    return "".join(out2), n_gated
+
+
+def patch_plain_script(text: str) -> tuple[str, int]:
+    """For scripts without argparse: add a sys.argv probe near the top.
+
+    Inserts after the last `import` or `from` line. Gates ✅ prints behind QUIET.
+    """
+    lines = text.splitlines(keepends=True)
+    last_import = -1
+    for i, line in enumerate(lines):
+        # Only TOP-LEVEL imports (column 0) — skip nested imports inside try/def.
+        if TOP_IMPORT_RE.match(line):
+            last_import = i
+    if last_import < 0:
+        return text, 0
+    if "import sys" not in text:
+        lines.insert(last_import + 1, "import sys\n")
+        last_import += 1
+    lines.insert(last_import + 1, '\nQUIET = "--quiet" in sys.argv\n')
+
+    n_gated = 0
+    out: list[str] = []
+    for line in lines:
+        m = SUCCESS_RE.match(line.rstrip("\n"))
+        if m:
+            indent, stmt = m.group(1), m.group(2)
+            out.append(f"{indent}if not QUIET:\n")
+            out.append(f"{indent}    {stmt}\n")
+            n_gated += 1
+        else:
+            out.append(line)
+    return "".join(out), n_gated
+
+
+def main() -> int:
+    targets = sorted(SCRIPTS.glob("check_*.py")) + sorted(SCRIPTS.glob("lint_*.py"))
+    skipped, patched, manual = [], [], []
+
+    for f in targets:
+        text = f.read_text()
+        if has_quiet_flag(text):
+            skipped.append(f.name)
+            continue
+        if has_argparse(text):
+            new, n = patch_argparse_script(text)
+            if n == 0 or new == text:
+                manual.append((f.name, f"argparse but no ✅-print gated (n={n})"))
+                continue
+            f.write_text(new)
+            patched.append((f.name, n))
+        else:
+            new, n = patch_plain_script(text)
+            if n == 0 or new == text:
+                manual.append((f.name, "plain but no ✅-print to gate"))
+                continue
+            f.write_text(new)
+            patched.append((f.name, n))
+
+    print(f"Skipped (already had --quiet): {len(skipped)}")
+    for s in skipped:
+        print(f"  · {s}")
+    print(f"\nPatched: {len(patched)}")
+    for name, n in patched:
+        print(f"  · {name} (gated {n} print(s))")
+    print(f"\nManual review needed: {len(manual)}")
+    for name, why in manual:
+        print(f"  · {name}: {why}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/ai_council/one_off_archive/2026-05/_one_off_inject_quiet_flag.py

@@ -0,0 +1,33 @@
+#!/usr/bin/env python3
+"""One-off: inject {{.QUIET_FLAG}} into Taskfile cmds for --quiet-aware scripts."""
+from __future__ import annotations
+import re
+from pathlib import Path
+
+# Scripts that accept --quiet (verified: 20 total = 3 pre-existing + 17 patched).
+QUIET_AWARE = {
+    "check_always_budget", "check_one_off_location", "check_safety_floor_untouched",
+    "check_augmentignore", "check_command_count_messaging", "check_compressed_paths",
+    "check_council_layout", "check_council_references", "check_iron_law_prominence",
+    "check_md_language", "check_memory_proposal", "check_public_catalog_links",
+    "check_reply_consistency", "check_roadmap_trackable",
+    "lint_examples", "lint_handoffs", "lint_load_context", "lint_roadmap_complexity",
+    "lint_rule_interactions", "lint_rule_tiers",
+}
+
+TASKFILES = sorted(Path("taskfiles").glob("*.yml")) + [Path("Taskfile.yml")]
+patched = 0
+for tf in TASKFILES:
+    text = tf.read_text()
+    new = text
+    for name in QUIET_AWARE:
+        # Match: cmd: python3 scripts/<name>.py [args]
+        # Insert {{.QUIET_FLAG}} after the script path, before any other args.
+        pat = re.compile(rf"(python3 scripts/{name}\.py)(\s|$)(?!.*QUIET_FLAG)")
+        new, n = pat.subn(r"\1 {{.QUIET_FLAG}}\2", new)
+        if n:
+            patched += n
+    if new != text:
+        tf.write_text(new)
+        print(f"  patched: {tf}")
+print(f"\nTotal injections: {patched}")