@event4u/agent-config 9.2.0 → 9.3.0

package/docs/governance-advantage.md

@@ -33,7 +33,7 @@ the host lacks (a static host gives it no runtime attention guarantee, but a
 runtime-only system gives it nothing at all here). A runtime-only system contributes *nothing* on these hosts.
 
 ### 2. Intent routing, not a 500-artefact dump
-A prompt does not load all 275 skills. `dist/router.json` (101 routed rules, intent →
+A prompt does not load all 276 skills. `dist/router.json` (101 routed rules, intent →
 skill, keyword/phrase/path triggers) carries the right skill on intent. The
 governance value is *selection discipline* — the host gets the relevant rule
 set, not the whole catalogue as context ballast.

package/docs/guidelines/component-oriented-and-oop-development.md

@@ -0,0 +1,181 @@
+# Component-Oriented & Object-Oriented Development
+
+> Cross-cutting development standard: **think in reusable units, and — in an
+> object-oriented / class-based codebase — treat object-oriented design as a
+> high-priority default where it reduces complexity.** Split by surface below
+> (frontend / backend), each pointing to the stack-specific carve-outs rather
+> than restating them. Framework-neutral by construction — React / Storybook /
+> Laravel / Symfony specifics live in their own skills, never here.
+
+## Paradigm-appropriate first — detect, then apply
+
+**Reuse is universal; OOP is paradigm-scoped.** Detect the codebase's paradigm
+before applying the object-oriented half: class-based / OO code (PHP, Java, C#,
+typical TS/React service layers) → this standard's OOP guidance is the
+high-priority default. A **functional / pipeline / actor-model** codebase
+(Elixir/Phoenix, Clojure, Haskell, Go-idiomatic, heavy FP-in-TS) → apply *that*
+paradigm's principles (immutability, pure functions, pattern-matching,
+composition of functions), and read the OOP bullets as "the same rigor, its
+paradigm's shape." **Never impose classes on functional code to satisfy this
+standard** — consistency with the codebase's chosen paradigm wins over OOP
+advocacy, always.
+
+## The standard, in one breath
+
+- **Reuse before you build** (every paradigm). Compose from units that already
+  exist — audit first, reuse the design system / shared abstractions, extract a
+  new unit only when the same shape repeats.
+- **Object-oriented where it fits** (in an OO codebase). Encapsulation, single
+  responsibility, composition over inheritance, and behavior-rich objects are
+  the high-priority default *when they reduce complexity* — not a quota to hit,
+  and not imposed on a codebase that has chosen a different paradigm.
+
+## The load-bearing caveat — reuse/OOP is a tool, never a mandate to abstract
+
+This standard **never** authorizes speculative abstraction. It is bounded by the
+package's restraint posture and defers to it on every conflict:
+
+- [`minimal-safe-diff`](../../src/rules/minimal-safe-diff.md) (+ its
+  anti-over-engineering mechanics) — smallest change; no premature abstraction,
+  no speculative feature, no rewrite for taste.
+- [`senior-engineering-discipline`](../../src/rules/senior-engineering-discipline.md)
+  — reuse the *existing* abstraction; generalize, don't overfit; never invent an
+  API to look object-oriented.
+- [`improve-before-implement`](../../src/rules/improve-before-implement.md) —
+  "does it fit the existing architecture?" before adding structure.
+- **When NOT to use a pattern** ([`php/patterns.md`](php/patterns.md) §) — KISS &
+  YAGNI trump pattern purity: no interface for a single implementation, no
+  pattern for a five-line function, no class where a function is clearer.
+
+Rule of thumb: **two real repetitions (or a genuine second axis of change)
+before you extract.** One occurrence is not a component; one branch is not a
+Strategy. A reviewer should be able to name the concrete duplication or the
+concrete change-axis the abstraction removes.
+
+**Precedence (explicit): `minimal-safe-diff` / YAGNI always trump OOP
+advocacy.** When "prefer OO shape" and "smallest change" conflict, the smallest
+change wins — this standard adds a *consideration*, never a competing objective
+that pressures preemptive abstraction. The review lens (below) may flag OO shape
+only where the duplication or the growing branch is **already present in the
+diff**, never as "this could grow later."
+
+## Frontend — think in reusable components
+
+Component-first is the default mindset, not an afterthought: decompose a screen
+into composable units, reuse the project's primitives, and extract shared shells
+when they repeat. Depth and mechanics already live in dedicated skills — consult
+them, don't duplicate:
+
+- [`fe-design`](../../src/skills/fe-design/SKILL.md) § Component Architecture —
+  the stack-agnostic "kind, not framework" taxonomy, granularity, extract-on-3+.
+- [`ui-component-architect`](../../src/skills/ui-component-architect/SKILL.md) —
+  how to *shape* a reusable component: composition over inheritance, slot
+  contracts, prop-API caps, controlled/uncontrolled, the componentization
+  threshold (repeat **and** real state).
+- [`existing-ui-audit`](../../src/skills/existing-ui-audit/SKILL.md) — the
+  reuse-before-invent gate: inventory existing components/tokens/primitives
+  first (enforced by [`ui-audit-gate`](../../src/rules/ui-audit-gate.md)).
+- [`design-tokens`](../../src/skills/design-tokens/SKILL.md) /
+  [`design-system-capture`](../../src/skills/design-system-capture/SKILL.md) —
+  the shared token/design-system layer components draw from.
+
+**Component workshop (Storybook et al.) — when the project is large enough.**
+For a project with a real, growing shared-component library, isolating and
+documenting each reusable component in a component workshop (Storybook or the
+ecosystem equivalent) pays for itself — it makes components discoverable,
+reviewable in isolation, and reused instead of re-invented. It is **not** worth
+the setup for a small surface with a handful of one-off components. The
+framework-specific setup is a carve-out, not a generic mandate — React /
+Storybook specifics: [`react-shadcn-ui`](../../src/skills/react-shadcn-ui/SKILL.md)
+§ Component workshop.
+
+Framework carve-outs (never restated here): React →
+[`react-shadcn-ui`](../../src/skills/react-shadcn-ui/SKILL.md); Next.js
+server/client component boundary →
+[`nextjs-patterns`](../../src/skills/nextjs-patterns/SKILL.md); Laravel FE →
+[`blade-ui`](../../src/skills/blade-ui/SKILL.md) /
+[`livewire`](../../src/skills/livewire/SKILL.md) /
+[`flux`](../../src/skills/flux/SKILL.md); styling →
+[`tailwind-engineer`](../../src/skills/tailwind-engineer/SKILL.md).
+
+## Backend — object-oriented where it reduces complexity
+
+The structural half — thin handlers, business logic in services / use-cases,
+behavior-rich domain models, validation at the boundary — is owned by
+[`architecture`](../../src/rules/architecture.md) and holds across paradigms. In
+an **object-oriented / class-based** service layer, layer the OO principles below
+on top of it, each applied only where it earns its place. In a **functional /
+pipeline** codebase, apply that paradigm's equivalent (pure functions +
+composition instead of behavior-rich objects; a dispatch map / pattern-match
+instead of a Strategy class) — the goal (encapsulate change, one responsibility,
+compose don't duplicate) is paradigm-independent; only its *shape* is OO here:
+
+- **Encapsulation** — objects own their data + the behavior over it; no anemic
+  bags mutated from the outside.
+- **Single responsibility** — one class, one reason to change; no god services.
+- **Composition over inheritance** — inject collaborators; reach for a base
+  class only for genuine is-a substitutability, not code sharing.
+- **Behavior-rich domain objects** — push rules into the model, keep services
+  orchestration-thin.
+- **Patterns where they earn their place** — a Strategy when a branch on a
+  discriminator will grow (`if-else` chain → polymorphism); a Factory when
+  construction is non-trivial; DI on an abstraction when there is a *real*
+  second implementation. Not before.
+
+Language / framework carve-outs (never restated here): PHP →
+[`php-coding-patterns`](php/php-coding-patterns.md) +
+[`patterns.md`](php/patterns.md) (+ `patterns/strategy.md`,
+`patterns/dependency-injection.md`, `patterns/factory.md`, `patterns/service-layer.md`)
++ skills [`php-coder`](../../src/skills/php-coder/SKILL.md) /
+[`php-service`](../../src/skills/php-service/SKILL.md); Laravel →
+[`laravel`](../../src/skills/laravel/SKILL.md); Symfony →
+[`symfony-workflow`](../../src/skills/symfony-workflow/SKILL.md); Next.js / TS →
+[`nextjs-patterns`](../../src/skills/nextjs-patterns/SKILL.md); cross-language
+clean-code baseline → [`code-clarity`](code-clarity.md).
+
+## Enums over scattered literals
+
+A field with two or more non-boolean states is an enum, not a bare string /
+magic number — the small OO move that keeps a codebase greppable and safe to
+change. Full rule + the defer-and-ask flow for pre-existing literals:
+[`prefer-enums-over-literals`](../../src/rules/prefer-enums-over-literals.md).
+
+## How this is reviewed
+
+"Reuse existing components + object-oriented shape (where it reduces
+complexity)" is a check on the code-quality review lens
+([`judge-code-quality`](../../src/skills/judge-code-quality/SKILL.md)), so it
+reaches `/review-changes`, `/judge`, the subagent judge modes, and team-mode's
+fallback review frame. It fires **only where the duplication or the growing
+branch is already present in the diff** — never "this could grow later" — and
+in the **codebase's own paradigm** (it will not tell a functional service to
+grow a class). It stays a human-judgment call that defers to the codebase's own
+conventions — never a generic SOLID dogma imposed over a project that has chosen
+differently.
+
+## Council review (2026-07-15)
+
+Deep debate, 3 rounds, cross-vendor (`anthropic/claude-sonnet-4-5` +
+`openai/gpt-4o`), $0.16. Split verdict; the load-bearing (anthropic) critique —
+that an "OOP-supreme default" over-indexes on OOP for a multi-paradigm consumer
+base and can conflict with `minimal-safe-diff` — was applied, bounded by this
+standard's stated purpose (OOP *is* a deliberate high priority for the operator):
+
+- **Paradigm-appropriate framing** — OOP is the high-priority default *within an
+  OO / class-based codebase*; detect and defer to a functional / pipeline /
+  actor paradigm; never impose classes on functional code (§ Paradigm-appropriate).
+- **Explicit precedence** — `minimal-safe-diff` / YAGNI win on conflict; the
+  review lens flags only *already-present* duplication / complexity, never
+  preemptive (§ caveat, § How this is reviewed).
+
+Divergence held: the frontend section stays (an intentional FE / backend
+entry-point + carve-out index, per the operator's explicit "split by FE /
+backend" ask) — against the anthropic "delete as redundant"; it is a cohesive
+index of the existing FE surfaces, not a claim of novel guidance. Trace:
+`agents/runtime/council/responses/component-oop-standard.json/` (gitignored, local-only).
+
+## See also
+
+- [`architecture`](../../src/rules/architecture.md) — the structural home this layers onto.
+- [`code-clarity`](code-clarity.md) — the cross-language clean-code baseline.
+- [`minimal-safe-diff`](../../src/rules/minimal-safe-diff.md) · [`senior-engineering-discipline`](../../src/rules/senior-engineering-discipline.md) — the restraint anchors this standard is bounded by.

package/docs/proof.md

@@ -27,7 +27,7 @@ evidence pointer, or `task check-claims` fails the build.
 | Claim | Kind | Evidence | Resolves |
 |---|---|---|---|
 | The release process is documented as an inheritable runbook + succession doc, and the project's bus-factor (trailing-90-day distinct human reviewers) is tracked and reported truthfully — currently 1, not implied to be more. | qual | `docs/succession.md#trailing 90 days` | ✅ |
-| 184 commands. | quant | `src/scripts/check_artefact_count_messaging.ts#Artefact-count messaging gate` | ✅ |
+| 189 commands. | quant | `src/scripts/check_artefact_count_messaging.ts#Artefact-count messaging gate` | ✅ |
 | A MEASURED-BUT-NOT-SHIPPED experiment — the thin rule projection reduced eager rule load 78,513 → 13,881 GPT-tokens (whole always-loaded projection 98,529 → 33,897, ~65.6%), but FAILED the quality gate (thin win-rate 36.2% vs required 48%) and does not ship; it un-defers only behind `discipline_profile: essential`. Shipped behavior does NOT include this reduction. Method: `agent-config benchmark` over the pinned token baseline; the baseline is the honest "what the user pays if everything loads eagerly", NOT a synthetic full-corpus strawman (council Q4); quality gate per the Phase-0 paired judge run. | quant | `internal/bench/reports/token-baseline.json#eager_rule_load` | ✅ |
 | The first cross-vendor parity pass (5 orchestration-corpus tasks × 2 vendors × 3 repeats, identical prompts via the council transport, $0.16) measured real per-host finding-count differences — claude-sonnet-4-5 surfaced ~2× the findings of gpt-4o on the multi-file analysis task (median 11 vs 5) while both vendors were identical on the planted hollow-implementation task (2 vs 2) and perfectly silent on the clean-code negative control (0 vs 0, no spurious findings). The per-task `finding_floor` values are calibrated from the cross-host lower envelope and the gate is armed. | quant | `internal/bench/reports/parity-count.json#min over hosts of median` | ✅ |
 | On a weak host (claude-haiku-4-5) the package produces a significant, placebo-controlled discipline lift on scope/downstream traps; on a strong host the same measurement is a published null — the package transplants discipline a weak model lacks, not model intelligence. | quant | `docs/benchmark.md#weak-host-specific` | ✅ |
@@ -45,7 +45,7 @@ evidence pointer, or `task check-claims` fails the build.
 | On a deterministic multi-session recall corpus, the memory substrate produces a measured, placebo-controlled recall lift — memory-on 27/27 vs no-memory 10/27 and vs equal-byte placebo 9/27 (claude-haiku-4-5, n=9 tasks x 3 seeds, sign test p=0.031 for BOTH pairings). Scoped honestly: this is the context-value upper bound (perfect retrieval on a one-fact-per-task corpus), not retrieval precision under a large store. | quant | `internal/bench/reports/second-brain-delta.json` | ✅ |
 | Removing the perfect-retrieval assumption, the substrate's REAL keyword retrieval recalls the needed decision into the top-5 under keyword-overlapping confusers (precision@5 9/9) and the model disambiguates it from the co-injected confusers — retrieval-on 27/27 vs no-memory 5/27 and vs equal-count placebo 5/27 (claude-haiku-4-5, 9 tasks x 3 seeds, sign test p=0.008 both). Named limit: retrieval RECALLS but does not RANK (mean tie-set 3.3, ties broken by store order, not relevance) — the discrimination gap that motivates the SQLite-FTS5 activation path (ADR-116) at larger scale. | quant | `internal/bench/reports/second-brain-retrieval.json` | ✅ |
 | Every artifact the package ships — source AND the condensed projection that reaches consumers — is machine-scanned in CI for hidden-Unicode, mixed-script-confusable, and instruction-smuggling payloads (the rules-file-backdoor class); a finding blocks the release before `npm publish`, not just the merge. | qual | `.github/workflows/publish-npm.yml#lint_agent_security` | ✅ |
-| 275 skills. | quant | `src/scripts/check_artefact_count_messaging.ts#Artefact-count messaging gate` | ✅ |
+| 276 skills. | quant | `src/scripts/check_artefact_count_messaging.ts#Artefact-count messaging gate` | ✅ |
 | Removes only its own keys from a shared host config (matched by JSON-pointer + SHA-256), never a neighbour tool's entries. | qual | `docs/contracts/install-layout.md#JSON-pointer` | ✅ |
 
 **21 backed claim(s)** — all evidence pointers resolve in CI.
@@ -77,11 +77,11 @@ shipping theater; the full per-cell data is committed at
 `internal/bench/reports/persona-placebo.json`.
 
 **Behavioural-eval coverage — the honest baseline.** Skill *quality* is only
-as good as its measurement. Today **42 of 275** skills carry a behavioural
+as good as its measurement. Today **42 of 276** skills carry a behavioural
 `evals.json`; the highest-traffic / highest-cost tiers (default-surface +
 `rich` + routers) are **fully covered (35 of 35)**, the long tail
-(7 of 240) is not. We publish that gap rather than imply
-"275 evaluated skills": coverage is measured per tier
+(7 of 241) is not. We publish that gap rather than imply
+"276 evaluated skills": coverage is measured per tier
 (`./scripts-run src/scripts/skill_eval_coverage`), **CI-ratcheted so it can
 only rise**, and the priority tiers carry a hard **tier floor**: every
 rich / default-surface / router skill MUST have a behavioural eval or an

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@event4u/agent-config",
-    "version": "9.2.0",
+    "version": "9.3.0",
     "description": "Universal AI Agent OS — audited skills, governance rules, commands, and templates for AI coding tools (Claude Code, Cursor, Windsurf, Copilot).",
     "license": "MIT",
     "private": false,
@@ -70,7 +70,8 @@
         "lint:ts": "eslint 'src/**/*.ts'",
         "test:ts": "vitest run",
         "prepack": "npm run build && npm run build:discovery && npm run build:mcp-manifest && node src/scripts/prepack-check.mjs",
-        "prepublishOnly": "./scripts-run src/scripts/check_release_includes_discovery"
+        "prepublishOnly": "./scripts-run src/scripts/check_release_includes_discovery",
+        "prepare": "[ -d .git ] && bash src/scripts/install-hooks.sh || true"
     },
     "publishConfig": {
         "access": "public",

package/src/scripts/ai_council/prompts.ts

@@ -88,6 +88,13 @@ correctness lens AND a shipping-risk lens:
    Is the blast radius bigger than the title implies?
 5. Reviewer fatigue — is anything in the diff that a tired reviewer
    would rubber-stamp but should not?
+6. Reuse & object-oriented shape — does the diff reinvent a component
+   or abstraction the codebase likely already provides (should compose
+   / reuse instead), and where it adds structure, is the OO shape
+   (encapsulation, composition over inheritance) justified by
+   complexity it removes rather than speculative abstraction? Judge in
+   the codebase's own paradigm — do not push classes onto functional /
+   pipeline code; smallest-change still wins over OO advocacy.
 End with: APPROVE / REQUEST_CHANGES / REJECT, one sentence why, and
 the single highest-leverage change the PR author should make before
 merge.`;

package/src/scripts/hook_manifest.yaml

@@ -145,6 +145,17 @@ concerns:
     script: src/scripts/team_review_gate_hook.ts
     args: []
     fail_closed: false
+  # Reply-shape backstop for the direct-answers rule (reply-close): a PR
+  # created THIS turn must end the reply as the literal last raw URL. This
+  # PostToolUse hook fires right after a PR *create* (gh pr create, or a
+  # github create-pull-request tool) that produced a `…/pull/<n>` URL, and
+  # WARNS in context (exit 2) so the reminder lands before the reply closes.
+  # Never blocks; unconditional (reinforces an always-on rule, fires only on
+  # the rare create event, so no settings gate). fail_closed: false.
+  pr-url-reminder:
+    script: src/scripts/pr_url_reminder_hook.ts
+    args: []
+    fail_closed: false
 
 platforms:
   augment:
@@ -152,7 +163,7 @@ platforms:
     session_end:      [chat-history]
     stop:             [chat-history, hot-context, verify-before-complete]
     pre_tool_use:     [block-no-verify, rtk-wrap, design-slop]
-    post_tool_use:    [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan]
+    post_tool_use:    [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan, pr-url-reminder]
 
   claude:
     session_start:    [chat-history, hot-context, first-run-gate, onboarding-gate, verify-before-complete, minimal-safe-diff, profile-staleness, wrapper-freshness, surface-probe]
@@ -160,7 +171,7 @@ platforms:
     stop:             [chat-history, hot-context, verify-before-complete, team-review-gate]
     user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff]
     pre_tool_use:     [block-no-verify, rtk-wrap, design-slop]
-    post_tool_use:    [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan]
+    post_tool_use:    [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan, pr-url-reminder]
 
   # Cowork — the Claude desktop app's local-agent-mode runtime, built
   # on top of the Claude Code CLI. Same lifecycle vocabulary, same
@@ -182,7 +193,7 @@ platforms:
     stop:             [chat-history, hot-context, verify-before-complete]
     user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff]
     pre_tool_use:     [block-no-verify, rtk-wrap, design-slop]
-    post_tool_use:    [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan]
+    post_tool_use:    [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan, pr-url-reminder]
 
   # Phase 7.5 — Cursor. `.cursor/hooks.json` (project) is read by the
   # IDE and CLI; `~/.cursor/hooks.json` (user) is opt-in via
@@ -196,7 +207,7 @@ platforms:
     session_end:        [chat-history]
     stop:               [chat-history, hot-context, verify-before-complete]
     user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff]
-    post_tool_use:      [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan]
+    post_tool_use:      [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan, pr-url-reminder]
 
   # Phase 7.6 — Cline. Hooks live under `.clinerules/hooks/<HookName>`
   # (project, no file extension, must be executable per Cline docs) or
@@ -211,7 +222,7 @@ platforms:
     session_end:        [chat-history]
     stop:               [chat-history, hot-context, verify-before-complete]
     user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff]
-    post_tool_use:      [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan]
+    post_tool_use:      [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan, pr-url-reminder]
 
   # Phase 7.7 — Windsurf (Cascade). Hooks live at `.windsurf/hooks.json`
   # (project) or `~/.codeium/windsurf/hooks.json` (user). Cascade has
@@ -245,7 +256,7 @@ platforms:
     session_end:        [chat-history]
     stop:               [chat-history, hot-context, verify-before-complete]
     user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff]
-    post_tool_use:      [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan]
+    post_tool_use:      [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan, pr-url-reminder]
 
   # Phase 7.9 — Copilot has no hook surface. Concerns route through
   # rule-only fallback; the dispatcher silently no-ops on --platform copilot.

package/src/scripts/install-hooks.sh

@@ -8,32 +8,47 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 # This installer lives at src/scripts/install-hooks.sh, so the repo root
 # (which owns .git/) is two levels up.
 PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
-HOOKS_DIR="$PROJECT_ROOT/.git/hooks"
+# Resolve the SHARED hooks dir via git so this also works from a linked worktree
+# (where $PROJECT_ROOT/.git is a file, not a dir, and a literal .git/hooks path
+# would break under `set -e`). --git-common-dir points at the main .git even from
+# a worktree; fall back to the literal path only outside a git repo.
+if COMMON_GIT_DIR="$(git -C "$PROJECT_ROOT" rev-parse --git-common-dir 2>/dev/null)"; then
+    case "$COMMON_GIT_DIR" in /*) : ;; *) COMMON_GIT_DIR="$PROJECT_ROOT/$COMMON_GIT_DIR" ;; esac
+    HOOKS_DIR="$COMMON_GIT_DIR/hooks"
+else
+    HOOKS_DIR="$PROJECT_ROOT/.git/hooks"
+fi
 
 mkdir -p "$HOOKS_DIR"
 
 cat > "$HOOKS_DIR/pre-push" << 'EOF'
 #!/usr/bin/env bash
-# Pre-push hook: verify dist/agent-src/ is in sync with .agent-src.uncondensed/
-# and that the canonical command count matches README + getting-started docs.
+# Pre-push hook: mirror the CI "Sync + Generate Tools Consistency" gate LOCALLY
+# so derived-output drift is caught BEFORE push, not in remote CI.
 #
-# The command-count gate exists because three consecutive PRs landed
-# post-CI count-drift fixes (e.g. f2fb0026 "bump command count
-# 101→103"). Catching the drift pre-push stops it from flooding remote
-# CI. Runtime ~0.1s.
+# History: the remote "Consistency" check failed in a large share of PRs because
+# the old hook only verified dist sync + the COMMAND count — it missed
+# guideline/skill/rule count drift and the generate-tools / router / corpus
+# outputs (e.g. a new guideline bumping the count in README + docs/architecture).
+# `task consistency` is the EXACT CI mirror (sync-check + sync-check-hashes +
+# sync + generate-tools + compile-router + compile-corpus + `git diff --quiet`),
+# so any derived-output drift blocks the push here. Runtime ~15-40s (it
+# regenerates the tool trees) — cheaper than a red CI run and a fixup re-push.
 
 fail=0
 
-echo "🔍 Checking dist/agent-src/ sync..."
-if ! ./scripts-run src/scripts/condense --check; then
-    echo "❌  dist/agent-src/ is out of sync. Run 'task sync' and condense changed .md files, then commit."
-    fail=1
-fi
-
-echo "🔍 Checking command count messaging..."
-if ! ./scripts-run src/scripts/check_command_count_messaging; then
-    echo "❌  Command-count drift in README / AGENTS.md / getting-started. Run 'task counts-update', stage the changes, then re-commit."
-    fail=1
+if ! command -v task >/dev/null 2>&1; then
+    echo "⚠️  'task' (go-task) not found — cannot run the consistency gate locally."
+    echo "    Install it (https://taskfile.dev) so pre-push can mirror the CI check;"
+    echo "    skipping the consistency check for this push."
+else
+    echo "🔍 Consistency — mirroring the CI 'Sync + Generate Tools Consistency' gate..."
+    if ! task consistency; then
+        echo "❌  Derived outputs drifted (counts / dist / generated tool trees / router / corpus)."
+        echo "    'task consistency' just regenerated them into your working tree —"
+        echo "    review + 'git add' the changes (or run 'task consistency-fix'), commit, then re-push."
+        fail=1
+    fi
 fi
 
 echo "🔍 Checking for leftover conflict markers / unmerged paths..."

package/src/scripts/pr_url_reminder_hook.ts

@@ -0,0 +1,177 @@
+#!/usr/bin/env node
+/**
+ * PostToolUse PR-URL reminder — reply-shape backstop for `direct-answers`.
+ *
+ * The `direct-answers` rule (reply-close) requires: a PR created THIS turn puts
+ * its raw URL as the **literal last line** of the reply. That is a behavioural
+ * rule with no deterministic backstop, so it can be silently missed — the URL
+ * ends up inline mid-reply instead of last. This hook fires right after a
+ * PR-creating tool call, extracts the created PR URL from the tool output, and
+ * WARNS in context (exit 2) so the reminder lands exactly when the PR is born,
+ * before the reply closes.
+ *
+ * Fires ONLY on an actual PR *create*:
+ *   - a shell command matching `gh pr create`, OR
+ *   - a GitHub tool whose name means "create a pull request"
+ *     (e.g. create_pull_request / createPullRequest / pulls.create),
+ * AND only when the tool output actually contains a `…/pull/<n>` URL — so a
+ * failed / dry-run create (no URL) does not nag, and `gh pr view/checks/list/
+ * comment` (which also print PR URLs) never fire it.
+ *
+ * Warn only — never blocks (fail_closed: false). Unconditional: it reinforces
+ * an always-on rule and only fires on the rare PR-create event, so it carries
+ * no settings gate (mirrors verify-before-complete / roadmap-progress).
+ *
+ * Exit codes (dispatcher contract): 0 allow · 2 warn (+ `{decision,reason}`
+ * JSON on stdout).
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const EXIT_ALLOW = 0;
+const EXIT_WARN = 2;
+
+type JsonValue = string | number | boolean | null | JsonValue[] | { [k: string]: JsonValue };
+type JsonObject = { [k: string]: JsonValue };
+
+// Tool names across platforms whose command field carries a shell command
+// (kept in lock-step with verify_before_complete_hook.COMMAND_TOOLS).
+const COMMAND_TOOLS: ReadonlySet<string> = new Set([
+  "launch-process",
+  "launch_process",
+  "Bash",
+  "BashTool",
+  "run-process",
+  "runProcess",
+  "shell",
+  "execute_shell",
+  "RunShellCommand",
+]);
+
+// A shell command that CREATES a pull request. Anchored on a shell separator so
+// it matches inside a chained command (`git push && gh pr create …`) but not a
+// substring of another word. `gh pr view/checks/list/comment` do not match.
+const _GH_PR_CREATE = /(?:^|[\s;&|`(])gh\s+pr\s+create\b/i;
+
+// A non-shell tool whose NAME means "create a pull request" (github-api / MCP).
+const _CREATE_PR_TOOL = /(?:create[_-]?pull_?request|createpullrequest|pulls[._-]create|create_pr\b)/i;
+
+// A GitHub pull-request URL as printed by `gh pr create` / returned as html_url.
+const _PR_URL = /https?:\/\/github\.com\/[^\s"'`<>]+\/pull\/\d+/i;
+
+function _isObject(v: unknown): v is JsonObject {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/** Return [tool_name, command_text] from a tool-event payload. */
+function _extractCommand(payload: JsonObject): [string | null, string | null] {
+  const toolRaw = payload["tool_name"] ?? payload["toolName"] ?? payload["tool"];
+  const tool = typeof toolRaw === "string" ? toolRaw : null;
+  if (!(tool !== null && COMMAND_TOOLS.has(tool))) {
+    return [tool, null];
+  }
+  const ti = payload["tool_input"];
+  if (_isObject(ti)) {
+    for (const key of ["command", "cmd", "shell_command"]) {
+      const v = ti[key];
+      if (typeof v === "string" && v) {
+        return [tool, v];
+      }
+    }
+  }
+  for (const key of ["command", "cmd"]) {
+    const v = payload[key];
+    if (typeof v === "string" && v) {
+      return [tool, v];
+    }
+  }
+  return [tool, null];
+}
+
+/** Best-effort extraction of the tool-output text from the envelope. */
+function _toolOutput(envelope: JsonObject): string {
+  for (const key of ["tool_response", "tool_result", "toolResponse", "output", "result", "stdout"]) {
+    const v = envelope[key];
+    if (typeof v === "string") {
+      return v;
+    }
+    if (_isObject(v) || Array.isArray(v)) {
+      return JSON.stringify(v);
+    }
+  }
+  return JSON.stringify(envelope);
+}
+
+/** True when this tool event created a pull request. */
+function _isPrCreate(tool: string | null, command: string | null): boolean {
+  if (command !== null && _GH_PR_CREATE.test(command)) {
+    return true;
+  }
+  return tool !== null && _CREATE_PR_TOOL.test(tool);
+}
+
+export function main(): number {
+  let envelope: JsonValue;
+  try {
+    const raw = _readStdin();
+    envelope = raw.trim() ? (JSON.parse(raw) as JsonValue) : {};
+  } catch {
+    return EXIT_ALLOW; // never block on a malformed envelope
+  }
+  if (!_isObject(envelope)) {
+    return EXIT_ALLOW;
+  }
+
+  const [tool, command] = _extractCommand(envelope);
+  if (!_isPrCreate(tool, command)) {
+    return EXIT_ALLOW;
+  }
+
+  const match = _PR_URL.exec(_toolOutput(envelope));
+  if (match === null) {
+    return EXIT_ALLOW; // create attempted but no URL produced (failed / dry-run) — do not nag
+  }
+  const url = match[0];
+
+  // `reason` (≤ 200 chars) goes to stderr; `additional_context` is what
+  // surfaces back to the model on platforms that support it — so the
+  // actionable instruction lives there (a stderr-only reason would not
+  // change the reply that this hook exists to shape).
+  const reason = `PR created this turn (${url}) — end your reply with this raw URL as the literal last line (direct-answers/reply-close).`;
+  const additional_context =
+    `You created a pull request this turn: ${url}\n\n` +
+    `Per the direct-answers rule (reply-close): a PR created this turn must appear ` +
+    `as the raw URL on the LITERAL LAST LINE of your reply — not inline mid-message. ` +
+    `Before ending the turn, make your final line exactly:\n${url}\n` +
+    `If it already is, no action needed.`;
+  process.stdout.write(`${JSON.stringify({ decision: "warn", reason, additional_context })}\n`);
+  return EXIT_WARN;
+}
+
+function _readStdin(): string {
+  return fs.readFileSync(0, "utf-8");
+}
+
+function _isCliEntry(): boolean {
+  if (process.argv[1] === undefined) {
+    return false;
+  }
+  const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+  if (import.meta.url === argvUrl) {
+    return true;
+  }
+  // Symlinked invocation (installed projection, or macOS /var → /private/var
+  // temp dirs) makes the raw URLs differ; compare realpaths so the guard fires.
+  try {
+    const here = fs.realpathSync(fileURLToPath(import.meta.url));
+    const argv = fs.realpathSync(path.resolve(process.argv[1]));
+    return here === argv;
+  } catch {
+    return false;
+  }
+}
+
+if (_isCliEntry()) {
+  process.exit(main());
+}