@event4u/agent-config 9.25.0 → 9.27.0

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@event4u/agent-config",
     "mcpName": "io.github.event4u-app/agent-config",
-    "version": "9.25.0",
+    "version": "9.27.0",
     "description": "Governed skills, rules and commands for AI coding tools (Claude Code, Cursor, Windsurf, Copilot) — every claim machine-checked, including \"zero runtime daemon\".",
     "license": "MIT",
     "private": false,

package/src/config/agents-paths.yml

@@ -114,6 +114,21 @@
   writer: /team-knowledge:bootstrap skill
   rationale: Deterministic template pages; review-then-commit flow (nothing here is the artifact)
 
+# ---------------------------------------------------------------------------
+# Self-improvement proposals (TRACKED — listed for classification, not ignored)
+# ---------------------------------------------------------------------------
+
+- path: /agents/proposals/
+  scope: both
+  policy: tracked
+  writer: learning-to-rule-or-skill skill (drafts) → upstream-contribute (PR)
+  rationale: |
+    Proposal drafts must be committed — the proposal-drift workflow reads their
+    stage: frontmatter in CI, and upstream-contribute opens a PR from them. Listed
+    here because agents-layout.md requires every new top-level agents/ entry to
+    appear in this manifest; the entry is inert for the gitignore gate, which reads
+    policy: ignored only.
+
 # ---------------------------------------------------------------------------
 # Ghostwriter profiles
 # ---------------------------------------------------------------------------

package/src/config/evaluator-budgets.json

@@ -58,11 +58,11 @@
       "deterministic": false
     },
     "cli_help_command_count": {
-      "max": 86,
-      "last_measured": 86,
-      "last_measured_at": "2026-08-06",
+      "max": 88,
+      "last_measured": 88,
+      "last_measured_at": "2026-08-07",
       "method": "registry enumeration — count of `{ name: '...', disposition` entries in src/cli/registry.ts (NOT --help prose parsing; methods historically disagreed 74 vs 76 vs 79)",
-      "baseline_note": "80 → 81 on 2026-08-03 (release 9.15.0 gate). This RECORDS growth that already shipped through its own reviewed PR; it does not authorize new surface. The +1 is f02db54c2 (fix(cli): register routing:doctor in the CLI registry) — the command existed, only its registry entry was missing, and the registering PR did not move this budget. The gate did its job again: breach WARNS on main and BLOCKS on release, which is the conscious-decision point rather than a silently raised cap. Re-measured 2026-08-03 via the pinned method: 81. Headroom stays zero by design — the next registry addition must move this number in its own PR. 81 → 82 on 2026-08-04: the `handoff` subcommand (road-to-agent-handoff-resume Phase 4) registers in the same PR that adds the surface, per this record's own contract. Re-measured via the pinned method: 82. 82 → 84 on 2026-08-04: the `route:explain` + `route:audit` verbs (routing-correctness validation surface) register in the same PR that adds the surface. Re-measured via the pinned method: 84. 84 → 85 on 2026-08-05: the `settings:set` verb (road-to-zero-ceremony-settings Phase 2 — the one agent-reachable settings writer) registers in the same PR that adds the surface, per this record's own contract. Re-measured via the pinned method: 85. 85 → 86 on 2026-08-06: the `conformance:behavior` verb (road-to-agent-behavior-conformance Phase 5 — replays the local transcript store through the four mechanised conformance checks) registers in the same PR that adds the surface, per this record's own contract. Re-measured via the pinned method: 86."
+      "baseline_note": "80 → 81 on 2026-08-03 (release 9.15.0 gate). This RECORDS growth that already shipped through its own reviewed PR; it does not authorize new surface. The +1 is f02db54c2 (fix(cli): register routing:doctor in the CLI registry) — the command existed, only its registry entry was missing, and the registering PR did not move this budget. The gate did its job again: breach WARNS on main and BLOCKS on release, which is the conscious-decision point rather than a silently raised cap. Re-measured 2026-08-03 via the pinned method: 81. Headroom stays zero by design — the next registry addition must move this number in its own PR. 81 → 82 on 2026-08-04: the `handoff` subcommand (road-to-agent-handoff-resume Phase 4) registers in the same PR that adds the surface, per this record's own contract. Re-measured via the pinned method: 82. 82 → 84 on 2026-08-04: the `route:explain` + `route:audit` verbs (routing-correctness validation surface) register in the same PR that adds the surface. Re-measured via the pinned method: 84. 84 → 85 on 2026-08-05: the `settings:set` verb (road-to-zero-ceremony-settings Phase 2 — the one agent-reachable settings writer) registers in the same PR that adds the surface, per this record's own contract. Re-measured via the pinned method: 85. 85 → 86 on 2026-08-06: the `conformance:behavior` verb (road-to-agent-behavior-conformance Phase 5 — replays the local transcript store through the four mechanised conformance checks) registers in the same PR that adds the surface, per this record's own contract. Re-measured via the pinned method: 86. 86 → 88 on 2026-08-07: the `sessions:list` + `sessions:claim` verbs (road-to-parallel-session-coordination — the shell surface of the shared session register, needed because /roadmap:next is command markdown and can only reach the register through a shell call) register in the same PR that adds the surface, per this record's own contract. Re-measured via the pinned method: 88."
     },
     "mcp_public_tool_count": {
       "max": 19,

package/src/config/gate-coverage.yml

@@ -44,7 +44,7 @@
 # ----------------------------------------------------------
 # 240 `lint_*` / `check_*` / `audit_*` scripts live under `src/scripts/`
 # (the count is computed, not asserted — `check_gate_coverage.count_gate_scripts`).
-# **31 of them emit the machine-readable `scanned: <N>` line under their
+# **32 of them emit the machine-readable `scanned: <N>` line under their
 # CI-identical argv, and all 31 are listed below.** The manifest is therefore
 # complete with respect to its own contract, and covers ~13 % of the population.
 #
@@ -599,3 +599,31 @@ gates:
       check_kernel_prefix_stability). The canary is what distinguishes that from
       a gate scanning nothing — it plants the removal-permitting class with no
       evidence and the gate reds.
+
+  - id: check_corpus_staleness
+    argv: ["--quiet", "--today", "2026-08-06"]
+    min_scanned: 5
+    corpus: "src/skills/*/data/manifest.json — grounding-corpus manifests (6 at baseline; brand, database, accessibility-auditor, api-design, design-intelligence, threat-modeling)"
+    status: enforced
+    canary:
+      class: missing-declared-csv
+      path: src/skills/zz-canary-corpus/data/manifest.json
+      content: |
+        {
+          "manifest_version": 1,
+          "refresh_cadence": "quarterly",
+          "upstream": { "last_checked": "2026-07-01" },
+          "domains": { "d": { "file": "nope.csv", "search_cols": ["a"], "output_cols": ["b"] } }
+        }
+    note: >
+      `--today` is PINNED in argv on purpose, and it is the whole reason this
+      gate is testable at all: the five upstream-vendored corpora share
+      `last_checked: 2026-06-07`, so an unpinned reference date makes this row
+      flip from green to red on 2026-09-15 with no diff behind it. The pinned
+      date keeps the coverage guard measuring COVERAGE; the real calendar check
+      is the workflow step, which runs unpinned and is meant to red when the
+      cadence is actually missed. Changing the pin is how you re-baseline after a
+      re-vendor, and it should be visible in a diff.
+      The canary plants a manifest whose declared CSV does not exist — the exact
+      gap `corpus-grounding/scripts/schema_validator.ts` leaves open, since it
+      computes the path and never opens the file.

package/src/config/gate-violation-baselines.json

@@ -1,36 +1,42 @@
 {
-  "$comment": "Violation ratchet for gates whose dead scan root was repaired. A repair REVEALS pre-existing debt; it does not create it. Each entry records the count revealed at repair time \u2014 the gate fails only when its count RISES. Lowering a count is a normal commit; raising one is a defect. Entries expire: a baseline that has not dropped within 56 days of `landed` (or of `reaffirmed.date`) fails its gate, because a number that never moves is suppression with extra steps. Mechanism + rationale: src/scripts/_lib/gate_baseline.ts. Decision: AI council 2026-08-02, roadmap road-to-gates-that-can-fail blocker `dead-gate-finding-triage`.",
+  "$comment": "Violation ratchet for gates whose dead scan root was repaired. A repair REVEALS pre-existing debt; it does not create it. Each entry records the count revealed at repair time — the gate fails only when its count RISES. Lowering a count is a normal commit; raising one is a defect. Entries expire: a baseline that has not dropped within 56 days of `landed` (or of `reaffirmed.date`) fails its gate, because a number that never moves is suppression with extra steps. Mechanism + rationale: src/scripts/_lib/gate_baseline.ts. Decision: AI council 2026-08-02, roadmap road-to-gates-that-can-fail blocker `dead-gate-finding-triage`.",
   "gates": {
     "check_no_new_legacy_path:hardcoded-scan-roots": {
       "count": 49,
       "landed": "2026-08-04",
-      "note": "Lines under src/scripts/**/*.{ts,mts,mjs} that pass the retired `.agent-src.uncondensed` directory into `path.join(...)` \u2014 a filesystem path CONSTRUCTED against the tree ADR-051 abandoned, which is the exact shape of all 14 dead gates. Deliberately narrow so the number is signal, not noise: 236 raw mentions under src/scripts \u2192 147 string-literal lines \u2192 67 path-constructing lines when the pass was written, after exempting src/scripts/_lib/agent_src.ts (the shared resolver, whose job IS owning the constant \u2014 gates that route through it survived the move). Detectors holding the literal as data to match, strip, or print are not counted, and no prose, docs, tests or fixtures are read: that full-tree shape was measured at 44 files / 213 hits and rejected as the wrong lint (see the note in check_no_new_legacy_path.ts::find_offenders). Recorded at 58 rather than 67 because Phase 1's scan-root repairs were landing on this branch while the pass was being written and had already removed 9 \u2014 a baseline above the truth silently permits new violations. This count goes to ZERO as the remaining repairs land; every repair is a lowering commit. Lowered 56\u219251 by the road-to-renewal-foundation Phase 1 dead-root sweep (check_always_budget, check_portability, check_references, lint_framework_leakage, lint_agents_md). Lowered 51\u219249 by the gate-hardening adoption PR: skill_collision_clusters and skill_overlap were repointed at the live skills tree via the shared resolver \u2014 two gates that had been reading the retired container and scoring 0 of 288 skills."
+      "note": "Lines under src/scripts/**/*.{ts,mts,mjs} that pass the retired `.agent-src.uncondensed` directory into `path.join(...)` — a filesystem path CONSTRUCTED against the tree ADR-051 abandoned, which is the exact shape of all 14 dead gates. Deliberately narrow so the number is signal, not noise: 236 raw mentions under src/scripts → 147 string-literal lines → 67 path-constructing lines when the pass was written, after exempting src/scripts/_lib/agent_src.ts (the shared resolver, whose job IS owning the constant — gates that route through it survived the move). Detectors holding the literal as data to match, strip, or print are not counted, and no prose, docs, tests or fixtures are read: that full-tree shape was measured at 44 files / 213 hits and rejected as the wrong lint (see the note in check_no_new_legacy_path.ts::find_offenders). Recorded at 58 rather than 67 because Phase 1's scan-root repairs were landing on this branch while the pass was being written and had already removed 9 — a baseline above the truth silently permits new violations. This count goes to ZERO as the remaining repairs land; every repair is a lowering commit. Lowered 56→51 by the road-to-renewal-foundation Phase 1 dead-root sweep (check_always_budget, check_portability, check_references, lint_framework_leakage, lint_agents_md). Lowered 51→49 by the gate-hardening adoption PR: skill_collision_clusters and skill_overlap were repointed at the live skills tree via the shared resolver — two gates that had been reading the retired container and scoring 0 of 288 skills."
     },
     "audit_user_type_axis": {
       "count": 1,
       "landed": "2026-08-02",
-      "note": "One orphan user-type value: `legal`. Five legal-review-prep skills (contract-review, dpa-review, nda-triage, legal-intake-triage, legal-practice-profile) declare `recommended_for_user_types: [legal]`, but there is no `user-types/legal.yml` \u2014 the pack shipped an axis value with no user-type definition behind it, and the dead scan root hid it (the audit reported used=0 orphans=0 while reading zero skills; it now reads 288 and reports used=8). Clearing this entry is a product call, not a copy edit: either author `user-types/legal.yml` (tagline, recommended packs, install-path hint) or drop `legal` from those five skills. Not decided here because both options change shipped pack behaviour."
+      "note": "One orphan user-type value: `legal`. Five legal-review-prep skills (contract-review, dpa-review, nda-triage, legal-intake-triage, legal-practice-profile) declare `recommended_for_user_types: [legal]`, but there is no `user-types/legal.yml` — the pack shipped an axis value with no user-type definition behind it, and the dead scan root hid it (the audit reported used=0 orphans=0 while reading zero skills; it now reads 288 and reports used=8). Clearing this entry is a product call, not a copy edit: either author `user-types/legal.yml` (tagline, recommended packs, install-path hint) or drop `legal` from those five skills. Not decided here because both options change shipped pack behaviour."
     },
     "lint_handoffs": {
       "count": 18,
       "landed": "2026-08-02",
-      "note": "All 18 are `handoff_tier_mismatch`: a senior-tier skill links to a peer whose frontmatter carries no `tier` (reported as tier='unset') \u2014 e.g. build-buy-partner \u2192 adr-create, customer-research \u2192 po-discovery, gated-reach \u2192 threat-modeling. This is a tier-metadata backfill backlog on the LINKED-TO skills, not a broken link. The one genuinely dangling link revealed by the same repair (competitive-positioning \u2192 a non-existent ../analyze-reference-repo/SKILL.md; it is a command, not a skill) was FIXED in the repairing commit rather than baselined. Clearing this entry means backfilling `tier` on the linked-to skills, or deciding that `tier: unset` on a link target is not a violation and narrowing the rule."
+      "note": "All 18 are `handoff_tier_mismatch`: a senior-tier skill links to a peer whose frontmatter carries no `tier` (reported as tier='unset') — e.g. build-buy-partner → adr-create, customer-research → po-discovery, gated-reach → threat-modeling. This is a tier-metadata backfill backlog on the LINKED-TO skills, not a broken link. The one genuinely dangling link revealed by the same repair (competitive-positioning → a non-existent ../analyze-reference-repo/SKILL.md; it is a command, not a skill) was FIXED in the repairing commit rather than baselined. Clearing this entry means backfilling `tier` on the linked-to skills, or deciding that `tier: unset` on a link target is not a violation and narrowing the rule."
     },
     "lint_pack_boundaries": {
       "count": 337,
       "landed": "2026-08-02",
-      "note": "Markdown links between source artefacts that cross a pack boundary the source pack's `requires` graph does not reach \u2014 revealed when the scan root moved off the deleted packages/ tree to the live corpus (0 -> 753 artefacts scanned). 82 distinct pack pairs across 131 source files; largest single class is engineering-base -> meta (73), skills in a consumer-installable pack citing this package's own maintenance skills. Each is a link that dangles for a consumer who installs the source pack without the target's. Judged real drift rather than an over-strict gate because it is long-tailed \u2014 top bucket 22%, no single systematic cause \u2014 unlike the lint_artefact_frontmatter case, where one required shape had 0-of-288 adoption. Fix per finding: add the edge to packs.yml requires, retarget the link, or move the artefact."
+      "note": "Markdown links between source artefacts that cross a pack boundary the source pack's `requires` graph does not reach — revealed when the scan root moved off the deleted packages/ tree to the live corpus (0 -> 753 artefacts scanned). 82 distinct pack pairs across 131 source files; largest single class is engineering-base -> meta (73), skills in a consumer-installable pack citing this package's own maintenance skills. Each is a link that dangles for a consumer who installs the source pack without the target's. Judged real drift rather than an over-strict gate because it is long-tailed — top bucket 22%, no single systematic cause — unlike the lint_artefact_frontmatter case, where one required shape had 0-of-288 adoption. Fix per finding: add the edge to packs.yml requires, retarget the link, or move the artefact."
     },
     "check_gate_completeness": {
       "count": 217,
       "landed": "2026-08-05",
-      "note": "Ledger adoption ratchet. 217 of 221 CI-registered gates do not yet carry per-target completeness accounting (`_lib/gate_ledger.ts`) or a `// ledger-exempt:` marker. This is deliberately NOT a sweep: road-to-skill-ecosystem-gate-integrity Phase 1 adopts exactly three gates (lint_framework_leakage, check_references, lint_roadmap_complexity) plus the checker itself to prove the interface, and the remainder migrates as gates are touched. Shrink-only from here \u2014 the number may not grow, so a NEW gate must adopt or exempt.",
+      "note": "Ledger adoption ratchet. 217 of 221 CI-registered gates do not yet carry per-target completeness accounting (`_lib/gate_ledger.ts`) or a `// ledger-exempt:` marker. This is deliberately NOT a sweep: road-to-skill-ecosystem-gate-integrity Phase 1 adopts exactly three gates (lint_framework_leakage, check_references, lint_roadmap_complexity) plus the checker itself to prove the interface, and the remainder migrates as gates are touched. Shrink-only from here — the number may not grow, so a NEW gate must adopt or exempt.",
       "falsifier": "./scripts-run src/scripts/check_gate_completeness"
     },
     "check_depth_budget": {
       "count": 4,
       "landed": "2026-08-06",
-      "note": "Four depth files exceed the 16,000-char per-file ceiling: rule-body-migration-inventory.md (23,782), design-antipatterns.md (20,707), roadmap-process-loop.md (20,360), orchestration-telemetry.md (16,155). Recorded rather than fixed because splitting four large reference documents is unrelated to the change that introduced the ceiling, and a gate that lands as four instant blockers is the shape this repository has already recorded as a failure. Shrink-only from here: a FIFTH over-ceiling file reds. roadmap-process-loop.md is the file that motivated the gate \u2014 it states 'Size budget: <= 4,000 chars' in its own header and is 5x over it, which is what a declared budget with nothing measuring it decays into. The ceiling is a GROWTH RATCHET, not a measured quality threshold: the 7,308-trajectory study behind the 3,500-token skill ceiling (ADR-217) was taken on procedural always-co-loaded skills, and this layer is declarative and loaded one or two files at a time. Replace the number when someone measures comprehension on THIS layer."
+      "note": "Four depth files exceed the 16,000-char per-file ceiling: rule-body-migration-inventory.md (23,782), design-antipatterns.md (20,707), roadmap-process-loop.md (20,360), orchestration-telemetry.md (16,155). Recorded rather than fixed because splitting four large reference documents is unrelated to the change that introduced the ceiling, and a gate that lands as four instant blockers is the shape this repository has already recorded as a failure. Shrink-only from here: a FIFTH over-ceiling file reds. roadmap-process-loop.md is the file that motivated the gate — it states 'Size budget: <= 4,000 chars' in its own header and is 5x over it, which is what a declared budget with nothing measuring it decays into. The ceiling is a GROWTH RATCHET, not a measured quality threshold: the 7,308-trajectory study behind the 3,500-token skill ceiling (ADR-217) was taken on procedural always-co-loaded skills, and this layer is declarative and loaded one or two files at a time. Replace the number when someone measures comprehension on THIS layer."
+    },
+    "gate-self-test:registered-non-adopters": {
+      "count": 24,
+      "landed": "2026-08-06",
+      "note": "Self-test adoption ratchet, expressed as a shrink-only NON-adopter count. 24 of the 32 gates registered enforced in gate-coverage.yml carry neither a `--self-test` (`_lib/gate_self_test.ts`) nor a `// self-test-exempt: <reason>` marker, so nothing proves they DISCRIMINATE — an enforced `scanned:` floor proves a gate read something, only a self-test proves the reading changes the verdict. Deliberately NOT an adoption column ratcheted upward: check_gate_coverage.ts's own report_hardening_ratchet rejects that shape in this same file (\"grades the solution instead of the problem\"), and the sibling adoption ratchet (check_gate_completeness) is already a non-adopter count. Population is the manifest, not every script under src/scripts: padding the manifest to move this number would mean adding a floor per row. Shrink-only from here — a NEW registered gate must adopt or exempt. Migration mechanism, same as the ledger ratchet above: gates adopt as they are touched, not in a sweep — the eight current adopters were each added alongside a real change to that gate. The 56-day non-stagnation clause applies unchanged, so a count parked here fails on its own.",
+      "falsifier": "./scripts-run src/scripts/check_gate_coverage"
     }
   }
 }

package/src/scripts/_cli/cmd_doctor.ts

@@ -90,6 +90,7 @@ import * as installed_tools from '../_lib/installed_tools.js';
 import * as user_global_paths from '../_lib/user_global_paths.js';
 import * as global_deploy_inventory from '../_lib/global_deploy_inventory.js';
 import { censusDuplicateScope } from '../_lib/duplicate_scope_census.js';
+import { git_common_dir } from '../_lib/git_common_dir.js';
 import * as sync_gitattributes from '../sync_gitattributes.js';
 import {
     PROJECT_ROOT_ENV,
@@ -897,27 +898,11 @@ const _PLACEHOLDER_EMAIL_RE = /^(t@t\.t|.*@example\.(com|org)|.*@localhost)$/i;
 const _PLACEHOLDER_NAME_RE = /^(t|test|user|nobody|x)$/i;
 
 export function _git_config_path(project_root: string): string | null {
-    const gd = path.join(project_root, '.git');
-    try {
-        const st = fs.statSync(gd);
-        if (st.isDirectory()) {
-            return path.join(gd, 'config');
-        }
-        // Worktree: `.git` is a file "gitdir: <path>".
-        const m = readText(gd).match(/^gitdir:\s*(.+)\s*$/m);
-        if (m === null) {
-            return null;
-        }
-        const gdPath = path.resolve(project_root, m[1]!.trim());
-        const commondirFile = path.join(gdPath, 'commondir');
-        if (pathExists(commondirFile)) {
-            const common = path.resolve(gdPath, readText(commondirFile).trim());
-            return path.join(common, 'config');
-        }
-        return path.join(gdPath, 'config');
-    } catch {
-        return null;
-    }
+    // The `.git`-file / `commondir` walk this used to inline now lives in
+    // `_lib/git_common_dir.ts`, so the session register and this check cannot
+    // drift into two different answers to "where is the common dir".
+    const common = git_common_dir(project_root);
+    return common === null ? null : path.join(common, 'config');
 }
 
 function _parse_git_user(configText: string): { name: string | null; email: string | null } {

package/src/scripts/_cli/cmd_route_audit.ts

@@ -36,8 +36,11 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import { match_prompt, type Router } from '../_lib/router_match.js';
 import { load_agent_settings } from '../_lib/agent_settings.js';
 import { read_entries } from '../chat_history.js';
+import { resolvePackageRoot } from '../_lib/package_root.js';
 
-const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
+// Marker-anchored, not hop-counted — see the sibling note in cmd_route_explain.ts.
+// Both routing commands were the last two `_cli` entries still counting hops.
+const REPO_ROOT = resolvePackageRoot(import.meta.url);
 const ROUTER_JSON = path.join(REPO_ROOT, 'dist', 'router.json');
 
 // cache-version: v1 — rebuildable audit log: delete-and-rerun rebuilds it from

package/src/scripts/_cli/cmd_route_explain.ts

@@ -31,8 +31,16 @@ import {
 } from '../_lib/router_match.js';
 import { measure, method_note } from '../_lib/token_count.js';
 import { load_agent_settings } from '../_lib/agent_settings.js';
+import { resolvePackageRoot } from '../_lib/package_root.js';
 
-const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
+// Marker-anchored, not hop-counted: this module runs from `src/scripts/_cli/`
+// (three levels down) AND from the precompiled `dist/cli-delegate/` (two), and
+// a fixed hop count is right in exactly one of them. Three hops from the bundle
+// landed on `<pkg>/..` — `node_modules/@event4u` for a scoped install — so
+// `route:explain` and `route:audit` reported dist/router.json as missing on
+// every invocation through the shipped binary while both worked under `tsx`.
+// The resolver exists precisely for this and 12 sibling commands already use it.
+const REPO_ROOT = resolvePackageRoot(import.meta.url);
 const ROUTER_JSON = path.join(REPO_ROOT, 'dist', 'router.json');
 const RULES_DIST_DIR = path.join(REPO_ROOT, 'dist', 'agent-src', 'rules');
 

package/src/scripts/_dispatch.bash

@@ -177,6 +177,10 @@ Tier 2 — maintenance / internal (hooks, MCP, memory, telemetry):
                              projection (from the pinned token baseline). Flags: --format
   code-graph                 Deterministic code-graph engine (ADR-124, Class A).
                              Usage: code-graph build|validate|detect|query|explain|affected|path [options]
+  sessions:list              List live agent sessions on this repository (shared
+                             session register). Flags: --json
+  sessions:claim             Claim a roadmap for this session so other sessions skip
+                             it; --release clears the claim
   roadmap:progress           Regenerate agents/roadmaps-progress.md from open roadmaps
   roadmap:progress-check     Fail if agents/roadmaps-progress.md is stale (for CI)
   roadmap:archive            Archive completed roadmaps (branch-touched by default;
@@ -579,6 +583,18 @@ cmd_mcp_run() {
   exec_ts "$server_main" "$@"
 }
 
+# Shared session register (road-to-parallel-session-coordination). Resolved from
+# PACKAGE_ROOT, not the consumer projection: the CLI imports the register library
+# under src/scripts/_lib/, which is package-internal and never shipped into
+# dist/agent-src/scripts/. Same shape as cmd_settings_set.
+cmd_sessions_list() {
+  exec_ts "$PACKAGE_ROOT/src/scripts/sessions_cli.ts" list "$@"
+}
+
+cmd_sessions_claim() {
+  exec_ts "$PACKAGE_ROOT/src/scripts/sessions_cli.ts" claim "$@"
+}
+
 cmd_roadmap_progress() {
   local script
   script="$(resolve_script "dist/agent-src/scripts/update_roadmap_progress.ts" ".augment/scripts/update_roadmap_progress.ts")"
@@ -1252,6 +1268,8 @@ main() {
     benchmark)               cmd_benchmark "$@" ;;
     code-graph)              cmd_code_graph "$@" ;;
     conformance:behavior)    cmd_conformance_behavior "$@" ;;
+    sessions:list)           cmd_sessions_list "$@" ;;
+    sessions:claim)          cmd_sessions_claim "$@" ;;
     roadmap:progress)        cmd_roadmap_progress "$@" ;;
     roadmap:progress-check)  cmd_roadmap_progress_check "$@" ;;
     roadmap:archive)         cmd_roadmap_archive "$@" ;;

package/src/scripts/_lib/git_common_dir.ts

@@ -0,0 +1,128 @@
+/**
+ * Resolve a repository's **common git directory** — the one directory every
+ * worktree of a repo shares.
+ *
+ * Extracted from `_cli/cmd_doctor.ts::_git_config_path`, which has resolved the
+ * `commondir` file this way since the git-identity check shipped. It is
+ * extracted rather than re-implemented on purpose: a repo with two different
+ * answers to "where is the common dir" is a bug waiting for a symlinked parent,
+ * and the worktree-cleanup work already hit that class once.
+ *
+ * ## Why this reads files instead of shelling out to git
+ *
+ * `git rev-parse --git-common-dir` is the obvious implementation and is wrong
+ * for the callers here, twice over:
+ *
+ * 1. **Inherited `GIT_DIR` overrides discovery.** Git hooks export `GIT_DIR`,
+ *    and every child inherits it, so `execFileSync('git', …, { cwd })` silently
+ *    resolves against the *hook's* repository rather than `cwd` — in a linked
+ *    worktree those differ, and the symptom is wrong data, not an error. That
+ *    is exactly what `_lib/git_env.ts` exists to strip. A file-based resolution
+ *    has nothing to override and needs no such guard.
+ * 2. **The raw output is not comparable across checkouts.** Measured
+ *    2026-08-07: from a main checkout `git rev-parse --git-common-dir` prints
+ *    the **relative** `.git`; from a linked worktree it prints an absolute
+ *    path. A consumer comparing the raw strings concludes the two checkouts
+ *    have different common dirs. Only the resolved realpath is a repo identity.
+ *
+ * ## Symlinked parents converge
+ *
+ * Measured on a throwaway repo reached both directly and through a symlinked
+ * ancestor: all four accesses (main / worktree × real / symlinked) resolve to
+ * the same directory, because the returned path is realpath-normalised here.
+ * This is the opposite of the worktree-cleanup finding that motivated the
+ * check — there realpath reporting caused a mis-classification; here it is the
+ * property that makes one shared register possible.
+ *
+ * Never throws: every caller treats "no common dir" as a reason to degrade,
+ * not as an error worth failing a hook over.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** `fs.realpathSync` that falls back to the input when the path is unreadable. */
+function realpath_or_self(p: string): string {
+    try {
+        return fs.realpathSync(p);
+    } catch {
+        return p;
+    }
+}
+
+/**
+ * The **per-worktree** git directory for `project_root` — `.git` in a plain
+ * checkout, the linked gitdir in a worktree. This is where `HEAD` lives, so it
+ * is the right anchor for "which branch is THIS checkout on", as opposed to
+ * `git_common_dir` which is deliberately shared across worktrees.
+ */
+export function git_dir(project_root: string): string | null {
+    const dot_git = path.join(project_root, '.git');
+    try {
+        const st = fs.statSync(dot_git);
+        if (st.isDirectory()) {
+            return realpath_or_self(dot_git);
+        }
+        const m = fs.readFileSync(dot_git, 'utf-8').match(/^gitdir:\s*(.+)\s*$/m);
+        if (m === null) {
+            return null;
+        }
+        return realpath_or_self(path.resolve(project_root, m[1]!.trim()));
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Current branch name for `project_root`, or `null` on a detached HEAD or
+ * outside a repo.
+ *
+ * Reads `<git-dir>/HEAD` directly rather than shelling out, for the same reason
+ * as everything else in this module: hooks export `GIT_DIR`, and an inherited
+ * one silently redirects `git` to the wrong repository.
+ */
+export function current_branch(project_root: string): string | null {
+    const gd = git_dir(project_root);
+    if (gd === null) return null;
+    try {
+        const head = fs.readFileSync(path.join(gd, 'HEAD'), 'utf-8').trim();
+        const m = head.match(/^ref:\s*refs\/heads\/(.+)$/);
+        return m === null ? null : m[1]!.trim();
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * The common git directory for `project_root`, realpath-normalised, or `null`
+ * when `project_root` is not inside a git repository.
+ *
+ * - Plain checkout → `<project_root>/.git`.
+ * - Linked worktree → the `commondir` target of the worktree's gitdir, i.e. the
+ *   main checkout's `.git`, which is identical from every worktree of the repo.
+ * - Worktree gitdir without a `commondir` file → the gitdir itself (degenerate,
+ *   but the historical behaviour and not this change's to alter).
+ */
+export function git_common_dir(project_root: string): string | null {
+    const dot_git = path.join(project_root, '.git');
+    try {
+        const st = fs.statSync(dot_git);
+        if (st.isDirectory()) {
+            return realpath_or_self(dot_git);
+        }
+        // Linked worktree: `.git` is a FILE containing "gitdir: <path>".
+        const m = fs.readFileSync(dot_git, 'utf-8').match(/^gitdir:\s*(.+)\s*$/m);
+        if (m === null) {
+            return null;
+        }
+        const gitdir = path.resolve(project_root, m[1]!.trim());
+        const commondir_file = path.join(gitdir, 'commondir');
+        if (fs.existsSync(commondir_file)) {
+            const common = path.resolve(gitdir, fs.readFileSync(commondir_file, 'utf-8').trim());
+            return realpath_or_self(common);
+        }
+        return realpath_or_self(gitdir);
+    } catch {
+        return null;
+    }
+}