@event4u/agent-config 9.9.0 → 9.11.0

package/dist/agent-src/templates/contexts/knowledge-pages.md

@@ -2,8 +2,8 @@
 
 Templates for the four typed directories added beside the existing
 anti-hallucination knowledge cards (`agents/knowledge/<source>.md`,
-[`knowledge-card.md`](knowledge-card.md)). **Existing cards stay untouched
-by this template** — sibling addition, not a migration.
+[`knowledge-card.md`](knowledge-card.md)). **Existing cards are untouched by
+this template** — this is a sibling addition, not a migration.
 
 ## The four directories
 
@@ -11,48 +11,48 @@ by this template** — sibling addition, not a migration.
 |---|---|---|
 | `agents/knowledge/sessions/` | Episodic | What happened — consolidated session learnings, one file per topic or date |
 | `agents/knowledge/concepts/` | Semantic | What is true — project facts: coding standards, module structure, API shapes, domain terms |
-| `agents/knowledge/procedures/` | Procedural | How to — step-by-step knowledge on the way to becoming a skill (`skill-candidates.md` lives here) |
+| `agents/knowledge/procedures/` | Procedural | How to — step-by-step knowledge on its way to becoming a skill (`skill-candidates.md` lives here) |
 | `agents/knowledge/decisions/` | Decision record | Small decisions not big enough for a full ADR |
 
 `agents/knowledge/INDEX.md` catalogs all five surfaces (cards + the four
-directories), one line per page — generated by
-`src/scripts/generate_knowledge_index.ts`. **Retrieval protocol: index
-first, `grep` keywords second, read the specific file third.** Never
-enumerate every knowledge file directly — no search infrastructure by
-design.
+directories) with one line per page — generated by
+`src/scripts/generate_knowledge_index.ts`. **Retrieval protocol: read the
+index first, `grep` for keywords second, read the specific file third.**
+Never enumerate every knowledge file directly; there is no search
+infrastructure by design — index-first + grep only.
 
 ## Storage location IS the sharing policy
 
-Personal, cross-project knowledge → the ADR-100 user-global store
+Personal, cross-project knowledge belongs in the ADR-100 user-global store
 (`~/.event4u/agent-config/knowledge/`, via `knowledge_global_cli.ts`) —
-never these project-local directories. Team knowledge → here, in the
-consumer repo, so the whole team benefits via git. Promotion to global
-requires cross-project evidence via the existing manual promotion path —
-never automatic.
+never in these project-local directories. Team knowledge belongs here, in
+the consumer repo, so the whole team benefits from it via git. Promotion
+from project-local to global requires cross-project evidence and goes
+through the existing manual global-store promotion path — never automatic.
 
 **Enforced at commit time.** A pre-commit gate
-(`src/scripts/check_knowledge_sharing.ts`) refuses a commit staging a
-`visibility: private` page under `agents/knowledge/` (belongs in the
-global store) or a gitignored `agents/memory/intake/` file staged by
-accident. Warns — never blocks — on 5+ new knowledge files in one
-commit, for a second look.
+(`src/scripts/check_knowledge_sharing.ts`) refuses a commit that stages a
+page with `visibility: private` under `agents/knowledge/` (it belongs in
+the global store instead) or a gitignored `agents/memory/intake/` file
+staged by accident. It warns — never blocks — when a commit adds 5+ new
+knowledge files at once, so the batch gets a second look.
 
 ## Entry micro-schema — `date + what + why`
 
-Every entry (especially in `sessions/`) states, at minimum:
+Every page entry (especially in `sessions/`) states, at minimum:
 
 ```markdown
 - 2026-07-05: <what happened / was learned> — <why it matters>
 ```
 
-Keep entries short; longer explanation goes in the page body below the
+Keep entries short. Longer explanation belongs in the page body below the
 entry list, not stuffed into one line.
 
 ## Page frontmatter — optional, warn-linted only (v1)
 
-None of these fields are mandatory in v1 (schema-as-contract deferred
-until real team usage data exists). When present, warn-linted for shape
-only:
+None of these fields are mandatory in v1 (schema-as-contract is explicitly
+deferred until real team usage data exists). When present, they are
+warn-linted for shape only:
 
 ```yaml
 ---
@@ -66,8 +66,9 @@ contested: []              # append-only array — see "Contested entries" below
 
 ## Contested entries — never silently resolved
 
-A live contradiction between documented and observed reality gets an
-**append-only** `contested:` entry, never a silent rewrite:
+When a live contradiction is found between documented and observed
+reality, the page gets an **append-only** `contested:` entry instead of a
+silent rewrite:
 
 ```yaml
 contested:
@@ -77,10 +78,10 @@ contested:
     session: "<session id or chat-history pointer>"
 ```
 
-Resolution is always human — via the `team-knowledge:consolidate` gate,
-or an isolated, this-turn-approved fix commit. ≥2 unresolved `contested`
-entries on one page → flagged by the knowledge lint for consolidation
-attention.
+Resolution is always human — either via the `team-knowledge:consolidate`
+gate, or via an isolated, this-turn-approved fix commit. A page carrying
+≥2 unresolved `contested` entries is flagged by the knowledge lint for
+consolidation attention.
 
 ## Page size budget
 
@@ -91,26 +92,27 @@ tiny pages do.
 ## What this substrate is — honest framing
 
 A **governed second-brain substrate**: working-memory continuity across
-compactions + sessions (hot-context cache, dispatcher-wide, 7 platforms),
-deterministic where safe (dedup, recurrence, index regen, fold rollups,
-scale tripwires), human-gated where meaning is at stake (consolidate
-gate, promotion, contested flow). It is **not** self-organizing
-intelligence — governed files; the learning loop is human-reviewed by
-design.
-
-**External viewers — read-only, on purpose.** Any Markdown tool (incl.
-Obsidian) can VIEW `agents/knowledge/` — but edits outside
-`/team-knowledge consolidate` silently desync `INDEX.md` + recurrence
-counters at next session start; exactly the failure the gate prevents.
-No `.obsidian/` config shipped, deliberately (council claude-sonnet-4-5
-+ gpt-4o, 2026-07-07 — converged 2/2 reject: out-of-gate edits are an
-unguardable dual-write; an editable vault re-creates the
-knowledge-as-truth model the 2026-07-05 verdict rejected).
+compactions and sessions (hot-context cache, dispatcher-wide on all 7
+platforms), deterministic where safe (dedup, recurrence, index regen,
+fold rollups, scale tripwires), human-gated where meaning is at stake
+(consolidate gate, promotion, contested flow). It is **not**
+self-organizing intelligence — the substrate is governed files, and the
+learning loop is human-reviewed by design.
+
+**External viewers — read-only, on purpose.** Any Markdown tool
+(including Obsidian) can VIEW `agents/knowledge/` — but edits made
+outside `/team-knowledge consolidate` silently desync `INDEX.md` and
+the recurrence counters at the next session start, which is exactly the
+failure the gate exists to prevent. No `.obsidian/` config is shipped,
+deliberately (council claude-sonnet-4-5 + gpt-4o, 2026-07-07 —
+converged 2/2 on reject: out-of-gate edits are an unguardable
+dual-write; an editable vault re-creates the knowledge-as-truth model
+the 2026-07-05 verdict rejected).
 
 ## See also
 
 - [`knowledge-card.md`](knowledge-card.md) — the existing anti-hallucination
   card template (unchanged, unaffected by this addition).
 - [`context-document`](../../../skills/context-document/SKILL.md) —
-  structured, on-demand codebase-area documentation (different, manual
+  structured, on-demand codebase-area documentation (a different, manual
   surface; complements rather than duplicates these pages).

package/dist/agent-src/templates/contexts/lesson-card.md

@@ -69,5 +69,5 @@ revalidate_if: "<condition that would invalidate — e.g. the endpoint gains a s
 
 ## See also
 
-- [`project-intelligence`](../contexts/execution/project-intelligence.md) — Class C safety spec, evidence/diagnosis split, decay rules, privacy floor.
-- [`evidence-discipline`](../contexts/execution/evidence-discipline.md) — v1 spine, trust tiers, the rollback target.
+- [`project-intelligence`](dist/agent-src/contexts/execution/project-intelligence.md) — Class C safety spec, evidence/diagnosis split, decay rules, privacy floor.
+- [`evidence-discipline`](dist/agent-src/contexts/execution/evidence-discipline.md) — v1 spine, trust tiers, the rollback target.

package/dist/agent-src/templates/contexts/tenant-boundaries.md

@@ -16,10 +16,10 @@
 - [ ] **Single-tenant** — one database per deployment. No cross-tenant
       leakage is possible at the infra layer. Delete this file if true
       and the app will never shard.
-- [ ] **Multi-tenant, shared DB** — one table with a tenant key
+- [ ] **Multi-tenant, shared database** — one table with a tenant key
       column (e.g., `tenant_id`, `workspace_id`).
 - [ ] **Multi-tenant, schema per tenant** — one DB, one schema each.
-- [ ] **Multi-tenant, DB per tenant** — each tenant has its own
+- [ ] **Multi-tenant, database per tenant** — each tenant has its own
       connection.
 
 ## Tenant identifier

package/dist/agent-src/templates/contexts.md

@@ -24,7 +24,7 @@ agents (and developers) quickly orient themselves when working in that area.
 |---|---|---|
 | **Module** | Document a module's structure and purpose | `client-software.md` |
 | **Domain** | Document a business domain across modules | `import-pipeline.md` |
-| **Service** | Document a complex service and its deps | `customer-service.md` |
+| **Service** | Document a complex service and its dependencies | `customer-service.md` |
 | **Integration** | Document an external API/system integration | `probaus-api.md` |
 | **Infrastructure** | Document infrastructure or DevOps concerns | `queue-system.md` |
 

package/dist/agent-src/templates/features.md

@@ -22,7 +22,7 @@ Templates for feature plan files stored in `agents/features/` or `{module_root}/
 | 💡 | Idea | Rough concept, not yet validated |
 | 🔍 | Exploring | Being researched and brainstormed |
 | 📋 | Planned | Structured plan complete, ready for roadmap |
-| 🗺️ | Roadmapped | Roadmap(s) generated, ready for impl |
+| 🗺️ | Roadmapped | Roadmap(s) generated, ready for implementation |
 | 🔄 | In Progress | Implementation started |
 | ✅ | Complete | Feature shipped |
 | ❌ | Rejected | Decided not to build |

package/dist/agent-src/templates/roadmaps.md

@@ -8,7 +8,7 @@ Templates for roadmap files stored in `agents/roadmaps/` or `{module_root}/{Modu
 
 1. **Be precise and concise.** Aim for 500–1000 lines max. If larger, split into multiple files.
 2. **Checkboxes are mandatory, not decorative.** Every active roadmap MUST contain at least one `- [ ]` per non-intro phase. Decision tables, ICE matrices, and block-sequencing tables capture the *why*; checkboxes capture the *what to do next*. A roadmap without checkboxes is invisible to `agents/roadmaps-progress.md` — the dashboard cannot count it, the next reader thinks no work is planned. Enforced by [`roadmap-progress-sync`](../rules/roadmap-progress-sync.md) Iron Law #2.
-   - **Glyph semantics:** `[ ]` open · `[x]` done · `[~]` **deferred** (planned for later — blocks silent archive per `roadmap-progress-sync` Iron Law 3) · `[-]` **cancelled** (won't do — explicit drop). Pick `[~]` vs `[-]` honestly; former carries follow-up-roadmap obligations, latter does not. Optional inline annotations: `<!-- deferred: reason -->` / `<!-- cancelled: reason -->` on same line.
+   - **Glyph semantics:** `[ ]` open · `[x]` done · `[~]` **deferred** (planned for later — blocks silent archive per `roadmap-progress-sync` Iron Law 3) · `[-]` **cancelled** (won't do — explicit drop). Pick `[~]` vs `[-]` honestly; the former carries follow-up-roadmap obligations, the latter does not. Optional inline annotations: `<!-- deferred: reason -->` / `<!-- cancelled: reason -->` on the same line.
    - **Status is binary: `ready` (default) or `draft`.** New roadmaps are created **ready** unless the user explicitly says draft — `ready` is implicit and need not be written. Drafts declare it via frontmatter at the top of the file (`---\nstatus: draft\n---`) and are hidden from the dashboard until the flag is removed or flipped to `ready`. Use `draft` while the roadmap is still being authored, while waiting for upstream decisions, as a capture-only synthesis that has not been promoted to executable phases, or as a follow-up roadmap (see rule 17 below) that is not yet ready to surface. There are no other status values; legacy banners like `**Status: directional**` are removed.
 3. **State the goal first.** One sentence at the top — what is the outcome?
 4. **List prerequisites** — what must exist or be running before starting.
@@ -60,10 +60,10 @@ Templates for roadmap files stored in `agents/roadmaps/` or `{module_root}/{Modu
     `task lint-roadmap-complexity` (plate-token detection skipped when
     `horizon_weeks > 0`).
 17. **Follow-up roadmaps from deferred items carry `parent_roadmap`.**
-    When a roadmap closes with `[~]` deferred items,
+    When a roadmap closes with `[~]` deferred items, the
     [`roadmap-management`](../skills/roadmap-management/SKILL.md) skill
     spawns a follow-up under `agents/roadmaps/road-to-<parent>-followup.md`.
-    Follow-up's frontmatter declares back-link:
+    The follow-up's frontmatter declares the back-link:
     ```yaml
     ---
     complexity: lightweight
@@ -71,51 +71,53 @@ Templates for roadmap files stored in `agents/roadmaps/` or `{module_root}/{Modu
     parent_roadmap: <parent-slug>
     ---
     ```
-    Follow-up's body opens with `## Context` block citing
-    `agents/roadmaps/archive/<parent>.md`. Deferred steps copied
-    **verbatim** (with original phase context) so plan survives
-    migration. If follow-up is "ready but blocked" rather than draft,
-    omit `status:` and add body note `> Blocked until <condition>` —
-    dashboard surfaces roadmap, readers honor body convention.
-    Authoring contract: [`roadmap-writing § 7`](../skills/roadmap-writing/SKILL.md);
+    The follow-up's body opens with a `## Context` block citing
+    `agents/roadmaps/archive/<parent>.md`. Deferred steps are copied
+    **verbatim** (with their original phase context) so the plan
+    survives the migration. If the follow-up is "ready but blocked"
+    rather than draft, omit `status:` and add a body note
+    `> Blocked until <condition>` — the dashboard surfaces the
+    roadmap, readers honor the body convention. Authoring contract:
+    [`roadmap-writing § 7`](../skills/roadmap-writing/SKILL.md);
     spawn procedure: [`roadmap-management § Spawn follow-up`](../skills/roadmap-management/SKILL.md).
-18. **Declare execution mode.** Every roadmap MAY declare how it
+18. **Declare the execution mode.** Every roadmap MAY declare how it
     should be executed by `/roadmap:process-*` via frontmatter:
     ```yaml
     execution:
       mode: autonomous        # autonomous | phase-checkpoints | interactive
     ```
-    - `interactive` (default when field absent) — today's behavior:
+    - `interactive` (default when the field is absent) — today's behavior:
       every gate fires as authored by its owning rule.
-    - `phase-checkpoints` — run halts at each phase boundary with a
-      compact status + continue prompt; inside a phase behaves like
+    - `phase-checkpoints` — the run halts at each phase boundary with a
+      compact status + continue prompt; inside a phase it behaves like
       `autonomous`.
-    - `autonomous` — at run start loop derives an **execution
+    - `autonomous` — at run start the loop derives an **execution
       contract** (see
       [`roadmap-execution-contract`](../contexts/execution/roadmap-execution-contract.md))
-      and ONE confirmation activates all run grants; run then proceeds
-      without interruptions except safety floors.
-
-    Field is a **declaration of intent, not a permission grant** —
-    permissions granted only by user's this-turn acceptance of the
-    run-start execution contract. Frontmatter never lifts a Hard
-    Floor, never authorizes a merge, never substitutes for contract
-    confirmation. Unknown values rejected by roadmap lint. Follow-up
-    roadmaps (rule 17) inherit parent's mode as *suggested* option
-    during creation but question always asked again.
+      and ONE confirmation activates all run grants; the run then
+      proceeds without interruptions except the safety floors.
+
+    The field is a **declaration of intent, not a permission grant** —
+    permissions are granted only by the user's this-turn acceptance of
+    the run-start execution contract. Frontmatter never lifts a Hard
+    Floor, never authorizes a merge, and never substitutes for the
+    contract confirmation. Unknown values are rejected by the roadmap
+    lint. Follow-up roadmaps (rule 17) inherit the parent's mode as the
+    *suggested* option during creation but the question is always asked
+    again.
 19. **Source-derived roadmaps carry a gap-table + provenance; internally
-    originated roadmaps carry neither.** Fires **only** when a roadmap
-    originates from an external input (suggestion, competitive/capability
-    harvest, external LLM ideation thread) or adopts external capabilities
-    into the suite. Does **not** fire for ordinary internally-originated
-    roadmaps — those add no Provenance block, no gap-table ritual. When it
-    fires:
+    originated roadmaps carry neither.** This rule fires **only** when a
+    roadmap originates from an external input (a suggestion, a competitive
+    or capability harvest, an external LLM ideation thread) or adopts
+    external capabilities into the suite. It does **not** fire for ordinary
+    internally-originated roadmaps — those add no Provenance block and no
+    gap-table ritual. When it fires:
     - **(a) Gap-table before drafting.** Audit each proposed item against
-      the existing skill / command / rule surface; keep only verified gaps
-      — `KEEP` (genuine gap) / `FOLD` (into existing artefact) / `CUT`
-      (already covered). Plan integrates, doesn't dump.
-    - **(b) `## Provenance` block** — source by a **neutral descriptor**
-      (never the raw competitor / tool name, per
+      the existing skill / command / rule surface and keep only verified
+      gaps — `KEEP` (genuine gap) / `FOLD` (into an existing artefact) /
+      `CUT` (already covered). The plan integrates, it does not dump.
+    - **(b) `## Provenance` block** — source named by a **neutral
+      descriptor** (never the raw competitor / tool name, per
       [`source-confidentiality`](../rules/source-confidentiality.md));
       retain the real link as an `ENC1:` token via
       `src/scripts/_lib/link_crypto.ts encrypt --value <url>`.
@@ -123,10 +125,11 @@ Templates for roadmap files stored in `agents/roadmaps/` or `{module_root}/{Modu
       session filepath ([`no-roadmap-references`](../rules/no-roadmap-references.md)).
     Authoring contract:
     [`roadmap-writing § 8`](../skills/roadmap-writing/SKILL.md).
-20. **Blockers are structured, not free prose.** A gate only user (or a
-    maintainer) can clear — decision, external dependency, evidence
-    threshold, kernel-budget soak window — records as a `## Blockers`
-    entry, not a stray sentence. Shape (one entry per blocker):
+20. **Blockers are structured, not free prose.** When a roadmap has a
+    gate that only the user (or a maintainer) can clear — a decision,
+    an external dependency, an evidence threshold, a kernel-budget soak
+    window — record it as a `## Blockers` entry, not a stray sentence.
+    Shape (one entry per blocker):
     ```markdown
     ## Blockers
 
@@ -135,84 +138,88 @@ Templates for roadmap files stored in `agents/roadmaps/` or `{module_root}/{Modu
     - **Owner:** user             <!-- user | maintainer | external -->
     - **Blocks:** Phase N — {phase name}
     - **What to do:**
-      1. {Concrete, copy-pasteable step owner must execute.}
-      2. {Include commands, file paths, expected outcomes.}
+      1. {Concrete, copy-pasteable step the owner must execute.}
+      2. {Include commands, file paths, and expected outcomes.}
     - **Resolved when:** {decidable signal, e.g. "task X exits 0"}
     ```
-    `### blocker: <id>` is the parse anchor dashboard generator reads;
-    ids unique within roadmap. All five fields required. A cleared
-    blocker flips `Status: resolved` (kept for history) instead of
-    deleted — resolve-flip runs in same reply as checkbox flip that
-    cleared it, per
-    [`roadmap-progress-sync`](../rules/roadmap-progress-sync.md). Step
-    gated by a specific blocker may cross-reference inline:
+    `### blocker: <id>` is the parse anchor the dashboard generator
+    reads; ids are unique within the roadmap. All five fields are
+    required. A cleared blocker flips `Status: resolved` (kept for
+    history) instead of being deleted — the resolve-flip runs in the
+    same reply as the checkbox flip that cleared it, per
+    [`roadmap-progress-sync`](../rules/roadmap-progress-sync.md). A
+    step gated by a specific blocker may cross-reference it inline:
     `- [ ] … <!-- blocked-by: <blocker-id> -->`.
 
-    **Legacy fallback.** Body-level `> Blocked until <condition>` note
-    (follow-up-roadmap convention from rule 17) is parsed by dashboard
-    generator as one implicit roadmap-level blocker (`Owner: user`,
-    instructions = note text) — existing roadmaps surface in
-    dashboard's `Blocker` column without retrofit. New roadmaps prefer
-    structured form above; renders richer instructions in per-roadmap
-    breakdown.
+    **Legacy fallback.** A body-level `> Blocked until <condition>`
+    note (the follow-up-roadmap convention from rule 17) is parsed by
+    the dashboard generator as one implicit roadmap-level blocker
+    (`Owner: user`, instructions = the note text) — existing roadmaps
+    surface in the dashboard's `Blocker` column without retrofit.
+    New roadmaps should prefer the structured form above; it renders
+    richer instructions in the per-roadmap breakdown.
 
 21. **Related roadmaps share a common filename prefix.** When you create
-    more than one roadmap that belongs together — a follow-up, siblings
-    split from one body of work in a single pass, or phases of one
-    initiative in separate files — give them a shared `road-to-<family>-…`
-    prefix so relatedness is visible in `agents/roadmaps/` and the
-    dashboard groups them. `<family>` = short kebab slug for the shared
-    initiative; the suffix distinguishes members:
+    more than one roadmap that belongs together — a follow-up, a set of
+    siblings split from one body of work in a single pass, or phases of
+    one initiative carved into separate files — give them a shared
+    `road-to-<family>-…` prefix so the relationship is visible on sight
+    in `agents/roadmaps/` and the dashboard groups them. `<family>` is a
+    short kebab slug naming the shared initiative; the suffix
+    distinguishes the members:
     - **Split-in-one-pass siblings** → `road-to-<family>-<part>.md`
       (e.g. `road-to-auth-hardening-backend.md`,
       `road-to-auth-hardening-frontend.md`,
       `road-to-auth-hardening-infra.md`).
-    - **Follow-ups** → `road-to-<parent>-followup.md` (rule 17): the
+    - **Follow-ups** → `road-to-<parent>-followup.md` (rule 17) is the
       special case where `<parent>` is the family prefix; keep the
       `parent_roadmap:` back-link.
     - **Sibling (non-parent/child) roadmaps** carry no `parent_roadmap:`;
       the shared prefix is the only linkage — do **not** invent a new
-      frontmatter field. Cross-link siblings by name in each `## Context`
-      block when it helps a reader.
-    Pick the `<family>` slug **once, up front**, before the first of the
-    set — renaming a prefix later means migrating inbound references. A
-    lone roadmap keeps plain `road-to-<slug>.md`; the convention fires
-    only when ≥2 related roadmaps are created together or as a follow-up
-    chain.
+      frontmatter field for it. Cross-link siblings by name in each
+      `## Context` block when it helps a reader.
+    Pick the `<family>` slug **once, up front**, before writing the first
+    of the set — renaming a prefix later means migrating inbound
+    references. A lone roadmap with no siblings keeps the plain
+    `road-to-<slug>.md` form; the convention fires only when ≥2 related
+    roadmaps are created together or as a follow-up chain.
 
 22. **Human gates are the exception — author for autonomous execution.**
-    Roadmap exists to be worked through without stopping; every human
-    checkpoint interrupts that. Default human-gate count: **zero**.
+    A roadmap exists to be worked through without stopping; every human
+    checkpoint interrupts that. Default number of human gates in a
+    roadmap: **zero**.
     - Every step is **agent-executable**. `- [ ] User verifies X`,
-      `- [ ] Manually check Y`, dedicated "Review / Sign-off" phases =
-      authoring bugs — replace with agent-verifiable check (command,
-      targeted test, grep) or delete.
-    - Exit + acceptance criteria are **agent-decidable** signals (command
-      exit code, file exists, test passes) — never "user approves",
-      "looks good", "sign-off".
-    - **Human gate** allowed only when only a human can **decide or
-      authorize**: Hard-Floor action (deploy, prod data/infra), billable
-      spend, contested product / architecture decision. Record as
-      structured `## Blockers` entry (rule 20) — never as inline checkbox
-      step scattered through phases.
-    - **External dependency = blocker, not human gate**, whenever agent
-      can probe its status (CI run finished, package version published,
-      upstream PR merged, API reachable, DNS propagated): record as
-      blocker whose `Resolved when:` names the agent-checkable probe
-      (command / URL / query) — do not assign to a human.
-    - **Merge is never a completion requirement.** Roadmap is
-      implementation-complete once checkboxes ticked and verification
-      ran; delivery stays the user's call (no merge / push / commit
-      steps, per `commit-policy`). Merge may appear as a blocker only
-      when later roadmap work technically depends on the merged state.
+      `- [ ] Manually check Y`, and dedicated "Review / Sign-off" phases
+      are authoring bugs — replace them with an agent-verifiable check
+      (a command, a targeted test, a grep) or delete them.
+    - Exit and acceptance criteria are **agent-decidable** signals (a
+      command exit code, a file that exists, a test that passes) — never
+      "user approves", "looks good", or "sign-off".
+    - A **human gate** is allowed only when only a human can **decide or
+      authorize**: a Hard-Floor action (deploy, prod data/infra),
+      billable spend, or a contested product / architecture decision.
+      Record it as a structured `## Blockers` entry (rule 20) — never as
+      an inline checkbox step scattered through phases.
+    - An **external dependency is a blocker, not a human gate**, whenever
+      the agent can probe its status (CI run finished, package version
+      published, upstream PR merged, API reachable, DNS propagated):
+      record it as a blocker whose `Resolved when:` names the
+      agent-checkable probe (command / URL / query) — do not assign it
+      to a human.
+    - **Merge is never a completion requirement.** A roadmap is
+      implementation-complete once its checkboxes are ticked and
+      verification ran; delivery stays the user's call (no merge / push /
+      commit steps, per `commit-policy`). Merge may appear as a blocker
+      only when later roadmap work technically depends on the merged
+      state.
     - Do **not** restate safety floors as steps. `non-destructive-by-default`,
-      `security-sensitive-stop`, `commit-policy` fire at run time on
-      their own; authored "STOP: confirm with user before X" duplicates
-      them → only adds interruptions.
-    Gate-test before any checkpoint: *"Could the agent clear this with a
-    tool or command during the run?"* Yes → step, not gate. No →
-    structured blocker with decidable `Resolved when:`, owned by a human
-    only when the blocker is a genuine human gate.
+      `security-sensitive-stop`, and `commit-policy` fire at run time on
+      their own; an authored "STOP: confirm with user before X" duplicates
+      them and only adds interruptions.
+    Gate-test before writing any checkpoint: *"Could the agent clear this
+    with a tool or command during the run?"* Yes → it is a step, not a
+    gate. No → structured blocker with a decidable `Resolved when:`,
+    owned by a human only when the blocker is a genuine human gate.
     `task lint-roadmap-complexity` warns on human-gate step patterns,
     human-gate phase headings, and human-approval exit criteria.
 
@@ -220,15 +227,17 @@ Templates for roadmap files stored in `agents/roadmaps/` or `{module_root}/{Modu
     behavior-changing step MAY carry a named verification command on its
     own inline-annotation line, e.g.
     `- [ ] Add the tenant-scope guard <!-- verify: task test -- --filter=TenantScopeTest -->`.
-    When declared, `/roadmap:process-*` will not accept its `[x]` flip
-    without a **fresh green run of that exact command** in the same run
-    (flip-guard, see
+    When a step declares one, `/roadmap:process-*` will not accept its
+    `[x]` flip without a **fresh green run of that exact command** in the
+    same run (enforced by the flip-guard, see
     [`roadmap-process-loop § 5b`](../contexts/execution/roadmap-process-loop.md)).
-    The machine-checkable tightening of rule 22's agent-decidable signals —
-    bind it on **behavior-changing** steps (a new guard, migration, wired
-    endpoint); doc-only / prose steps leave it off. Keep the command
-    **narrow** (targeted test / grep / build of the touched surface),
-    never the full CI pipeline (`roadmap-ci-steps-policy`).
+    This is the machine-checkable tightening of rule 22's agent-decidable
+    signals — bind it on **behavior-changing** steps (a new guard, a
+    migration, a wired endpoint); doc-only / prose steps leave it off and
+    stay governed by the ordinary flip-guard. Keep the command **narrow**
+    (a targeted test / grep / build of the touched surface), never the
+    full CI pipeline — per `roadmap-ci-steps-policy` a `verify:` must not
+    be a full-suite gate.
 
 ---
 
@@ -236,11 +245,11 @@ Templates for roadmap files stored in `agents/roadmaps/` or `{module_root}/{Modu
 
 Every roadmap must pass the project's quality pipeline before it is
 considered done. **Where** that gate runs depends on
-`quality.local_auto_run`: `false` or missing (default) → agent does NOT
-run the pipeline locally — user runs it manually, remote CI on the PR
-is the authoritative gate; run-end report says *"quality gates
-delegated to remote CI"*, never that the tools passed. When
-`local_auto_run: true`, **when** the local pipeline runs during
+`quality.local_auto_run`: when `false` or missing (the default), the
+agent does NOT run the pipeline locally — the user runs it manually and
+remote CI on the PR is the authoritative gate; the run-end report says
+*"quality gates delegated to remote CI"*, never that the tools passed.
+When `local_auto_run: true`, **when** the local pipeline runs during
 `/roadmap:process-step|phase|full` is governed by
 `roadmap.quality_cadence` in `.agent-settings.yml`
 (`end_of_roadmap` default → once before archival; `per_phase` → after
@@ -320,10 +329,10 @@ complexity: lightweight
 - [ ] {Observable, testable criterion}
 - [ ] All quality gates pass (PHPStan, Rector, tests)
 
-<!-- ## Blockers — INCLUDE ONLY when a gate exists that only user /
+<!-- ## Blockers — INCLUDE ONLY when a gate exists that only the user /
      a maintainer can clear (decision, external dependency, evidence
-     threshold, soak window). OMIT entirely when none — see rule 20
-     for full shape.
+     threshold, soak window). OMIT entirely when there are none — see
+     rule 20 for the full shape.
 ### blocker: <kebab-id>
 - **Status:** open
 - **Owner:** user

package/dist/agent-src/templates/rule.md

@@ -10,7 +10,8 @@
 2. Copy the template below into `src/rules/{rule-name}.md`.
 3. Replace placeholders, drop sections that don't apply.
 4. Run `task lint-skills` and `./scripts-run src/scripts/lint_load_context`.
-5. Condense: `bash scripts/condense.sh --changed` then follow the agent flow.
+5. Project to `dist/agent-src/`: `task sync` (writes the projection, including the
+   path rewrite). Verify with `bash scripts/condense.sh --check`.
 
 ## Path conventions — load-bearing
 

package/dist/agent-src/templates/scripts/tier_usage_report.ts

@@ -234,7 +234,7 @@ function _within_window(ts_bucket: string, window_days: number | null): boolean
     return ms >= Date.now() - window_days * 24 * 60 * 60 * 1000;
 }
 
-type BucketKey = string; // `${tier}${command}` — composite (tier, command) key.
+type BucketKey = string; // `${tier}\0${command}` — composite (tier, command) key.
 interface RowStats {
     count: number;
     distinct_users: number;
@@ -274,7 +274,7 @@ function aggregate(log_path: string, window_days: number): AggregateResult {
         }
         kept += 1;
         const tier = Math.trunc(rec.tier);
-        const key = `${tier}${rec.command}`;
+        const key = `${tier}\0${rec.command}`;
         if (!keyMeta.has(key)) {
             keyMeta.set(key, { tier, command: rec.command });
             counts.set(key, 0);