@event4u/agent-config 17.1.0 → 17.2.1

package/.augment-plugin/marketplace.json

@@ -1,20 +1,20 @@
 {
   "name": "event4u-agent-config",
   "description": "Governed agent system — skills, rules, commands, and guidelines for AI-assisted development.",
-  "version": "17.1.0",
+  "version": "17.2.1",
   "owner": {
     "name": "event4u",
     "email": "dev@event4u.app"
   },
   "metadata": {
     "description": "A policy-driven execution system that enforces quality, consistency, and developer-like behavior for AI agents.",
-    "version": "17.1.0"
+    "version": "17.2.1"
   },
   "plugins": [
     {
       "name": "agent-config",
       "description": "Full governed agent system — rules, skills, commands, guidelines, and runtime tooling.",
-      "version": "17.1.0",
+      "version": "17.2.1",
       "source": ".",
       "category": "governance",
       "tags": [

package/.augment-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-config",
   "description": "A governed skill framework for AI agents — runtime execution, tooling, observability, feedback, and lifecycle management with policy-driven quality enforcement.",
-  "version": "17.1.0",
+  "version": "17.2.1",
   "author": {
     "name": "event4u",
     "email": "dev@event4u.app"

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Bootstrap shim for the event4u agent-config suite. This plugin ships ONLY the dispatcher hooks plus one install-pointer skill — ALL content (skills, rules, commands) is installed via `npx -y @event4u/agent-config init`, which writes the file projection AND registers the same hooks in ~/.claude/settings.json. DEPRECATED as a content channel; kept so the marketplace listing stays discoverable. Its hooks run only alongside a global npm install of the package (`npx -y @event4u/agent-config init` or `npm i -g`); a project-local install is never used. On a plugin-only install no dispatcher is reachable, no hook runs, and the fail_closed guards (block-no-verify, block-kernel-rule-writes, block-plumbing-writes) are OFF — only the session start says so.",
-    "version": "17.1.0",
+    "version": "17.2.1",
     "keywords": [
       "agent-config",
       "skills",

package/CHANGELOG.md

@@ -403,6 +403,98 @@ An entry belongs under a dated release section, not here — see
 > that forces a new era split (`# Era: 17.2.x`, etc.) — see
 > [`docs/contracts/CHANGELOG-conventions.md § Era splits`](docs/contracts/CHANGELOG-conventions.md).
 
+## [17.2.1](https://github.com/event4u-app/agent-config/compare/17.2.0...17.2.1) (2026-10-23)
+
+### Release highlights
+
+- **Behaviour changes:** _none_
+- **Default changes + migration:** Breaking, pending in `BREAKING_CHANGES.md` and shipped by this release: **Three `fail_closed` hook guards run where they were silent.** The installed claude hook command now reaches a dispatcher staged under `~/.event4u/agent-config/runtime/` after a project-local install and before `PATH` ([`3f8c98e`](https://github.com/event4u-app/agent-config/commit/3f8c98e74), #2455). On machines installed through `npx`, or hosts launched with a bare `PATH`, every hook command used to end in a silent `exit 0`; there `block-no-verify` (refuses `git … --no-verify` and `core.hooksPath` overrides), `block-kernel-rule-writes` and `block-plumbing-writes` (refuse agent writes to this package's kernel rules and hook plumbing) now run and may refuse a tool call for the first time. Classed breaking by the AI council, 2026-10-19 (`agents/evidence/council/hook-carrier-release-note-class-20261019.md`). **`uninstall --global --purge` stops being a recursive delete of the host anchor.** Old scope: `fs.rmSync(anchor, { recursive: true })` on whole host configuration roots — `~/.claude/`, `~/.codex/`, `~/.config/zed/` — so everything under them went, whoever wrote it. New scope: only the anchor-relative paths this package's own deploy inventory recorded writing; the anchor itself is never removed, directories are pruned only when left empty, a recorded symlink is unlinked rather than followed, and a purge with no readable inventory for that anchor exits 1 having deleted nothing. A second change in the same area: a plain `uninstall --global` now keeps the lockfile while recorded content is still on disk, where it used to delete it.
+- **Security and correctness:** _none_
+- **Honest nulls:** _none_
+- **Known limitations:** _none_
+
+> **Governance mix:** governance-only 1 vs consumer-only 0 (mixed 0, maintenance 1; taxonomy 1.1.0; range 4e79c57090c8..36c8616ea2f4).
+
+### Documentation
+
+* **ci:** record the shipped cloud-release rate-limit fix ([b3d4b2f](https://github.com/event4u-app/agent-config/commit/b3d4b2f6d7334d8c78ee48bdb098efb30808703f))
+
+### CI
+
+* **cloud-release:** pace the asset upload and skip what is already attached ([91d4b73](https://github.com/event4u-app/agent-config/commit/91d4b73ebab6b68a53581092354803014dbf0c0c))
+
+Tests: 32297 (+0 since 17.2.0)
+
+## [17.2.0](https://github.com/event4u-app/agent-config/compare/17.1.0...17.2.0) (2026-10-23)
+
+### Release highlights
+
+- **Behaviour changes:** _none_
+- **Default changes + migration:** Breaking, pending in `BREAKING_CHANGES.md` and shipped by this release: **Three `fail_closed` hook guards run where they were silent.** The installed claude hook command now reaches a dispatcher staged under `~/.event4u/agent-config/runtime/` after a project-local install and before `PATH` ([`3f8c98e`](https://github.com/event4u-app/agent-config/commit/3f8c98e74), #2455). On machines installed through `npx`, or hosts launched with a bare `PATH`, every hook command used to end in a silent `exit 0`; there `block-no-verify` (refuses `git … --no-verify` and `core.hooksPath` overrides), `block-kernel-rule-writes` and `block-plumbing-writes` (refuse agent writes to this package's kernel rules and hook plumbing) now run and may refuse a tool call for the first time. Classed breaking by the AI council, 2026-10-19 (`agents/evidence/council/hook-carrier-release-note-class-20261019.md`). **`uninstall --global --purge` stops being a recursive delete of the host anchor.** Old scope: `fs.rmSync(anchor, { recursive: true })` on whole host configuration roots — `~/.claude/`, `~/.codex/`, `~/.config/zed/` — so everything under them went, whoever wrote it. New scope: only the anchor-relative paths this package's own deploy inventory recorded writing; the anchor itself is never removed, directories are pruned only when left empty, a recorded symlink is unlinked rather than followed, and a purge with no readable inventory for that anchor exits 1 having deleted nothing. A second change in the same area: a plain `uninstall --global` now keeps the lockfile while recorded content is still on disk, where it used to delete it.
+- **Security and correctness:** keep the binding inside the size ratchet and the built-path test unskipped (4201565); land the nightly evaluator record through a pull request (75dae15); name the map's render result map-render.json, clear of the design-sync artefact name (9868be2); fit the two map tools into the kernel payload band and dispose of their state (4f362af); keep Playwright out of the bundles and regenerate what the map moved (dc896f4); close the independent review's findings on the map (8956a5b); +2 more.
+- **Honest nulls:** _none_
+- **Known limitations:** _none_
+
+> **Governance mix:** governance-only 10 vs consumer-only 7 (mixed 19, maintenance 2; taxonomy 1.1.0; range 81949b9dba26..ffe878edc5db).
+
+### Features
+
+* **hooks:** bind the InstructionsLoaded observer on claude ([8bb7fe6](https://github.com/event4u-app/agent-config/commit/8bb7fe6dce33e743d112eb3faba1d6d5cebd0b74))
+* **code-graph:** the map remembers, compares and flags merge risks ([77bf99c](https://github.com/event4u-app/agent-config/commit/77bf99c53ca7c4e761ffc472cc3ebef60660f621))
+* **code-graph:** draw this repository's artefact layer on its own map ([9f2c328](https://github.com/event4u-app/agent-config/commit/9f2c328edffbb550aa7425df522d4d88875a03f6))
+* **code-graph:** link documents to the files they name ([153ddef](https://github.com/event4u-app/agent-config/commit/153ddef9e1e03652e676e8fb0f203e44feab68af))
+* **code-graph:** read a project's SCIP index into the graph ([f80d8ce](https://github.com/event4u-app/agent-config/commit/f80d8cea56d4b13642fad0f5af7b7cda66675853))
+* **code-graph:** index Python, Go, Java and Vue ([2ff8f31](https://github.com/event4u-app/agent-config/commit/2ff8f3159c29e145455b0c7b10cb909faa739d93))
+* **code-graph:** keep the map fresh, readable over MCP, and diffable ([936cad9](https://github.com/event4u-app/agent-config/commit/936cad9e938117a67e701f29356ee2e00d18d732))
+* **code-graph:** read Laravel's conventions into the graph ([e69e6e5](https://github.com/event4u-app/agent-config/commit/e69e6e5c2290c9d73174d5800057cc33ffa446e0))
+* **code-graph:** draw the project map into agents/map/ ([213a10c](https://github.com/event4u-app/agent-config/commit/213a10c043785ea3af947a35f94b90d8f0d4f62f))
+
+### Bug Fixes
+
+* **ci:** keep the binding inside the size ratchet and the built-path test unskipped ([4201565](https://github.com/event4u-app/agent-config/commit/4201565a647fe075d69646c42ff39d07af70176f))
+* **ci:** land the nightly evaluator record through a pull request ([75dae15](https://github.com/event4u-app/agent-config/commit/75dae15a18edde57fcfbdb8fcb23c2d536bf855c))
+* **code-graph:** name the map's render result map-render.json, clear of the design-sync artefact name ([9868be2](https://github.com/event4u-app/agent-config/commit/9868be25d59ce85c5f5814b20c6bb63ae1b48292))
+* **ci:** fit the two map tools into the kernel payload band and dispose of their state ([4f362af](https://github.com/event4u-app/agent-config/commit/4f362af254c9d39bd8869499b3e5b88848b39050))
+* **ci:** record the map's runtime dependencies and tighten its verify clauses ([9705541](https://github.com/event4u-app/agent-config/commit/97055419e6447ed882e00a8b9d4e6bda53baf273))
+* **ci:** keep Playwright out of the bundles and regenerate what the map moved ([dc896f4](https://github.com/event4u-app/agent-config/commit/dc896f4749f07eea8bcd159e8cf25cb1857402eb))
+* **code-graph:** close the independent review's findings on the map ([8956a5b](https://github.com/event4u-app/agent-config/commit/8956a5b970b55fe22957918f1fb9c422757c326f))
+* **project-map:** use the lite model tier, the schema's lowest band ([c4833a9](https://github.com/event4u-app/agent-config/commit/c4833a9c6989a52a952b310e9707bf8725dbfeaa))
+* **code-graph:** keep the hook bundle under its ceiling ([2356031](https://github.com/event4u-app/agent-config/commit/2356031a2f56b87a3f53717bc5b49db51096e0de))
+* **code-graph:** index the consumer project and actually write its index ([e15e45c](https://github.com/event4u-app/agent-config/commit/e15e45c7ce13de2cda7c486652d546cbca972e7e))
+
+### Documentation
+
+* **roadmap:** name unopim and larasend as the code-graph benchmark subjects ([eb4599e](https://github.com/event4u-app/agent-config/commit/eb4599e460609ab0437ec0afb9bf4a9074972e73))
+* **evidence:** re-ratify the binding after the CI-fix delta (round 5) ([12cbfa6](https://github.com/event4u-app/agent-config/commit/12cbfa68d33b0a293e0772b266c924c0b0ea3835))
+* **roadmap:** claim the observer's concern in the estate and type the council prompts ([ae8d5a9](https://github.com/event4u-app/agent-config/commit/ae8d5a993b9324bdf47e0c2fe9944e973f0049d7))
+* **evidence:** ratification record for the InstructionsLoaded binding ([ae1162c](https://github.com/event4u-app/agent-config/commit/ae1162c0e43cac457f666afe4cc98f641c45399e))
+* **roadmap:** close step 1.1 and its ratification-quorum blocker ([bc66921](https://github.com/event4u-app/agent-config/commit/bc66921a44fa6a74312a4d5938442431e1524404))
+* **roadmaps:** archive road-to-a-map-that-draws-itself — every step and criterion closed ([d40e797](https://github.com/event4u-app/agent-config/commit/d40e797f990afadf94b79a243ce0b83108718c55))
+* **adr:** register agents/map/ for derived views and correct the stale graph claim ([66f75c5](https://github.com/event4u-app/agent-config/commit/66f75c5cd02d4506afbd60c7c92685d70572283b))
+* **roadmaps:** plan a project map the code-graph engine draws itself ([06f332a](https://github.com/event4u-app/agent-config/commit/06f332a2550a1797b050d046d43f9a1dd6a7e7cf))
+
+### CI
+
+* **tests:** bound the FFmpeg install and let a stall skip the stitch cases ([1d0f01b](https://github.com/event4u-app/agent-config/commit/1d0f01b4cb3f0940a226d0a96a94ebeb2948e954))
+
+### Chores
+
+* **hooks:** record the admission of the instructions-observer concern ([a5ee675](https://github.com/event4u-app/agent-config/commit/a5ee675245df43e7279ee0ef485c98867ab5d99b))
+* **plugin:** regenerate hooks/hooks.json in matrix order ([339b306](https://github.com/event4u-app/agent-config/commit/339b3062cc73ef2995f2b493d5ea627c850c3d27))
+* **ci:** regenerate the ADR index and lower the source-size ratchet to the live total ([7c11522](https://github.com/event4u-app/agent-config/commit/7c11522b49c1dac1199e142ed17c8b6e9fa06f22))
+* **adr:** regenerate the evidence census for ADR-297's provenance kind ([18b7d11](https://github.com/event4u-app/agent-config/commit/18b7d113e811f17c1115010676e49c6d0c8e9849))
+* **tokens:** trim the map's surfaces, then re-anchor the two that still grew ([5d61dab](https://github.com/event4u-app/agent-config/commit/5d61dab35e0540492109a4b9233b198e9df6bc3c))
+* **index:** regenerate the catalog for project map ([1522e30](https://github.com/event4u-app/agent-config/commit/1522e30103815b03c1a777cb4a24c234e3995f7e))
+* **proof:** regenerate after the merge with main ([c4d0a11](https://github.com/event4u-app/agent-config/commit/c4d0a1133339e081f738a2f3df353d649110449c))
+* **sync:** project the map command, the code-intelligence step and the analyze changes ([5651955](https://github.com/event4u-app/agent-config/commit/5651955b72866023bde89afc1e85a0001a944a93))
+
+### Other
+
+* **code-graph:** record the map's costs and the orientation benchmark ([84c2421](https://github.com/event4u-app/agent-config/commit/84c24216f474eab896d4f8979b2353b37f81e4b6))
+* **code-graph:** pre-register the orientation benchmark and add the map cost probe ([1fdc013](https://github.com/event4u-app/agent-config/commit/1fdc013f9038ee50495bfe1ab0c3e75ecd90b3b3))
+
+Tests: 32297 (+82 since 17.1.0)
+
 ## [17.1.0](https://github.com/event4u-app/agent-config/compare/17.0.0...17.1.0) (2026-10-23)
 
 ### Release highlights

package/README.md

@@ -4,10 +4,10 @@
 
 [![Smoke](https://github.com/event4u-app/agent-config/actions/workflows/smoke.yml/badge.svg)](https://github.com/event4u-app/agent-config/actions/workflows/smoke.yml) [![Public install smoke (3 OS × 2 Node)](https://github.com/event4u-app/agent-config/actions/workflows/smoke-public-install.yml/badge.svg)](https://github.com/event4u-app/agent-config/actions/workflows/smoke-public-install.yml) [![npm](https://img.shields.io/npm/v/@event4u/agent-config?style=flat-square&label=npm&color=orange)](https://www.npmjs.com/package/@event4u/agent-config) [![agent-config MCP server](https://glama.ai/mcp/servers/event4u-app/agent-config/badges/score.svg)](https://glama.ai/mcp/servers/event4u-app/agent-config) [![MCP Toplist](https://mcptoplist.com/badge/glama%2Fevent4u-app%2Fagent-config.svg)](https://mcptoplist.com/server/glama%2Fevent4u-app%2Fagent-config)
 
-[![Skills](https://img.shields.io/badge/Skills-301-orange?style=flat-square)](dist/agent-src/skills/) [![Rules](https://img.shields.io/badge/Rules-122-orange?style=flat-square)](dist/agent-src/rules/) [![Commands](https://img.shields.io/badge/Commands-209-orange?style=flat-square)](dist/agent-src/commands/) [![Guidelines](https://img.shields.io/badge/Guidelines-121-orange?style=flat-square)](docs/guidelines/) [![Personas](https://img.shields.io/badge/Personas-29-orange?style=flat-square)](dist/agent-src/personas/) [![Advisors](https://img.shields.io/badge/Advisors-5-orange?style=flat-square)](dist/agent-src/personas/advisors/) <!-- claim:published-artifact-counts -->
+[![Skills](https://img.shields.io/badge/Skills-301-orange?style=flat-square)](dist/agent-src/skills/) [![Rules](https://img.shields.io/badge/Rules-122-orange?style=flat-square)](dist/agent-src/rules/) [![Commands](https://img.shields.io/badge/Commands-210-orange?style=flat-square)](dist/agent-src/commands/) [![Guidelines](https://img.shields.io/badge/Guidelines-121-orange?style=flat-square)](docs/guidelines/) [![Personas](https://img.shields.io/badge/Personas-29-orange?style=flat-square)](dist/agent-src/personas/) [![Advisors](https://img.shields.io/badge/Advisors-5-orange?style=flat-square)](dist/agent-src/personas/advisors/) <!-- claim:published-artifact-counts -->
 [![downloads](https://img.shields.io/npm/dm/@event4u/agent-config?style=flat-square&label=downloads%2Fmonth&color=orange)](https://www.npmjs.com/package/@event4u/agent-config)
 
-<sub>**How these are counted** — one canonical counter, `agent-config` → `update_counts --check`, re-derives all six from the tree and fails CI when one is off by one. Two bases are not what the linked directory shows, so they are stated here rather than left to be inferred: **Commands 209** counts every command file **recursively** (the linked directory holds 62 at its top level) and **Rules 122** counts the **source** rules while the linked projection holds 121 — one rule is dormant and is not projected. **Personas 29** excludes the directory README. Counts are of files and directories: none of them measures quality, activation or adoption. <!-- claim:published-artifact-counts --></sub>
+<sub>**How these are counted** — one canonical counter, `agent-config` → `update_counts --check`, re-derives all six from the tree and fails CI when one is off by one. Two bases are not what the linked directory shows, so they are stated here rather than left to be inferred: **Commands 210** counts every command file **recursively** (the linked directory holds 62 at its top level) and **Rules 122** counts the **source** rules while the linked projection holds 121 — one rule is dormant and is not projected. **Personas 29** excludes the directory README. Counts are of files and directories: none of them measures quality, activation or adoption. <!-- claim:published-artifact-counts --></sub>
 
 **Try it in 30 seconds** — drop one read-only subagent into any repo and watch it check "done": `@production-validator check this branch is actually done`. No wizard, no lock-in, nothing else installed — the [30-second wedge ↓](#quickstart) is the whole first step. Start at the proof, not the catalog: **[event4u-app.github.io/agent-config/proof/](https://event4u-app.github.io/agent-config/proof/)**.
 

package/dist/agent-src/commands/project/analyze.md

@@ -31,7 +31,9 @@ Gather in parallel:
 - Check for: `artisan`, `Makefile`, `Taskfile.yml`, `docker-compose.yml`
 - Check for: `phpstan.neon`, `ecs.php`, `rector.php`, `config-dev/`
 - Check for: `.github/workflows/`, `CODEOWNERS`, `.editorconfig`
-- Check for module roots (resolve via `scripts/_lib/agent_settings.ts::enumerate_modules()`; Laravel shape: `app/Modules/`), multi-tenant indicators (`customer_database`)
+- Check for module roots (resolve via `scripts/_lib/agent_settings.ts::enumerate_modules()`; Laravel shape: `app/Modules/`)
+- Probe the database connections the project declares (`config/database.php` `connections`, `DB_CONNECTION*` keys in `.env.example`, `$connection` properties on models); more than one connection used by models is a multi-database / multi-tenant indicator — name the connections as found, never assume their names
+- Build or refresh the code map: `agent-config code-graph map`. Structure (areas, hubs, cycles, request paths) is read from `agents/map/MAP.md` below, not re-derived by hand <!-- ref-ignore -->
 - Read: `AGENTS.md`, `.github/copilot-instructions.md` (if exist)
 
 **Assurance dimensions — do NOT hand-detect these.** Run
@@ -137,6 +139,7 @@ full pass, so "continue" is dominant and asking is a routine confirmation.
 Analyze the directory structure:
 
 - Map top-level directories with file counts
+- Read `agents/map/MAP.md` first: its areas, infrastructure files, cycles and request paths ARE the structure section — link to it rather than restating it <!-- ref-ignore -->
 - Identify pattern: MVC, modules, services, repositories, DTOs
 - Count: Models, Controllers, Services, Jobs, Commands, Events, Policies
 - Detect: multi-tenancy, API versioning, queue usage
@@ -150,13 +153,14 @@ ARCHITECTURE:
 
   Pattern:      {Modular MVC + Service Layer + Repository}
   API:          {Versioned REST (/api/v1/, /api/v2/)}
-  Multi-Tenant: {✅ Dual-DB (api_database + customer_database) | ❌}
+  Databases:    {connections the models use, as probed — e.g. "2 (mysql, tenant)" | 1}
+  Map:          agents/map/MAP.md ({n} areas · largest {name})
 
 ───────────────────────────────────────────────
 CODE INVENTORY:
 ───────────────────────────────────────────────
 
-  Models:        {count}  (api_database: {n}, customer_database: {n})
+  Models:        {count}  (per connection, when more than one is in use)
   Controllers:   {count}
   Services:      {count}
   Repositories:  {count}
@@ -288,9 +292,8 @@ Write all remaining analysis files that haven't been created yet:
 - `agents/evidence/analysis/architecture/database.md` — schema, connections, multi-tenancy
 - `agents/evidence/analysis/architecture/api.md` — versioning, routes, middleware, auth
 - `agents/evidence/analysis/architecture/infrastructure.md` — Docker, CI/CD, deployment
-- `agents/evidence/analysis/architecture/patterns.md` — design patterns used
-- `agents/evidence/analysis/models/api-database.md` — all api_database models
-- `agents/evidence/analysis/models/customer-database.md` — all customer_database models
+- `agents/evidence/analysis/architecture/patterns.md` — design patterns used; for module and area structure, link `agents/map/MAP.md` instead of restating it <!-- ref-ignore -->
+- `agents/evidence/analysis/models/<connection>.md` — one per database connection the probe found, all models on it
 - `agents/evidence/analysis/modules/{module}.md` — one per module
 - `agents/evidence/analysis/testing/test-map.md` — test suites, coverage, strategy
 

package/dist/agent-src/commands/project/map.md

@@ -0,0 +1,58 @@
+---
+model_tier: lite
+name: project-map
+pack: engineering-base
+visibility: internal
+sub: map
+cluster: project
+skills: [code-intelligence]
+description: Draw the code map into agents/map/
+suggestion:
+  eligible: false
+  rationale: "Cluster sub-command — reached via its cluster head's routing or its explicit /cluster:sub name; not independently suggested (surface-consolidation)."
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# project-map
+
+## Instructions
+
+Build the map of the project the user is standing in, then point at it. The map is
+deterministic and local: no model call, no network, nothing committed by default
+(`agents/map/` is gitignored, ADR-297). <!-- ref-ignore -->
+
+### 1. Build
+
+```bash
+agent-config code-graph map
+```
+
+It builds or updates the code graph first when it is absent or behind, then writes
+`agents/map/index.html`, `agents/map/MAP.md`, one `agents/map/areas/<id>.md` per <!-- ref-ignore -->
+area of five or more files, and `agents/map/map.json`. With Playwright present it <!-- ref-ignore -->
+also renders the page at three widths and reports the render check; without it the
+check reads `unverified`, which is not a pass.
+
+`--root <path>` maps another checkout; `--open` opens the page; `--no-verify`
+skips the render check.
+
+### 2. Report
+
+Quote the command's summary lines (files, areas, largest area, graph state, render
+check) and give the path to `agents/map/index.html`. Do not paraphrase the counts. <!-- ref-ignore -->
+
+### 3. Answer from the map, when the user asked a question
+
+Read `agents/map/MAP.md` first, then the page of the area in question. Say which <!-- ref-ignore -->
+answers came from the map and which from a follow-up `code-graph query` or a file
+read — the map groups files by coupling, it does not explain what they do.
+
+## Rules
+
+- **Never edit `agents/map/` by hand.** Every file there is regenerated. <!-- ref-ignore -->
+- **A `behind:N` or `edited` graph state is part of the answer.** Say it.
+- **"Isolated" is not "dead".** A file reached by reflection, a string path or a
+  framework convention the engine does not read is isolated too.

package/dist/agent-src/commands/project.md

@@ -2,10 +2,10 @@
 model_tier: medium
 name: project
 disable-model-invocation: true
-argument-hint: "[analyze|health]"
+argument-hint: "[analyze|health|map]"
 pack: engineering-base
-intent: "Project dispatcher — full analysis or quick health check"
-routes_to: [project-analyze, project-health]
+intent: "Project dispatcher — full analysis, quick health check, or the project map"
+routes_to: [project-analyze, project-health, project-map]
 replaces: []
 visibility: internal
 description: Project orchestrator — routes to analyze (full audit) and health (read-only status check)
@@ -35,6 +35,7 @@ Top-level orchestrator for the `/project` family — project-wide inspection.
 |---|---|---|
 | `/project analyze` | `commands/project/analyze.md` | Full project analysis — detect stack, inventory modules, audit docs, create missing contexts |
 | `/project health` | `commands/project/health.md` | Quick health check — status of docs, modules, contexts, roadmaps; creates nothing |
+| `/project map` | `commands/project/map.md` | Draw the code map into `agents/map/` — areas, files, links; offline, gitignored |
 
 Sub-command names match the locked contract in
 [`docs/contracts/command-clusters.md`](../docs/contracts/command-clusters.md).
@@ -50,6 +51,7 @@ Sub-command names match the locked contract in
 
    > 1. analyze — full project audit (writes missing contexts)
    > 2. health — read-only status check (creates nothing)
+   > 3. map — draw the code map into `agents/map/`
 
 ## Rules
 

package/dist/agent-src/skills/code-intelligence/SKILL.md

@@ -38,6 +38,10 @@ code-graph and no appetite to build one — plain `grep`/read is right there.
 
 ## Procedure
 
+0. **Orient first, when the question is "where does X live" rather than "who
+   calls X".** If `agents/map/MAP.md` exists, read it: it names the project's <!-- ref-ignore -->
+   areas (files grouped by coupling), its infrastructure files and its cycles.
+   No map yet? `agent-config code-graph map` builds one in seconds. Then query.
 1. **Detect the source.** `agent-config code-graph detect` — is a fresh consumer
    `graph.json` or native cache present? (A consumer-shipped fresh index wins;
    the native engine covers stale-or-absent — ADR-124 § 2.)
@@ -246,6 +250,8 @@ paragraph claiming "the same five answers" directly after a list of four:
 | `graph_query` | `query` |
 | `graph_path` | `path` |
 | `graph_node` | no CLI verb — one symbol's location, in-edges, out-edges and degree |
+| `graph_map_status` | whether `agents/map/` exists, its counts and freshness | <!-- ref-ignore -->
+| `graph_area` | one area of the map: files, hubs, what it depends on |
 
 `untested` has no tool of its own; it is a flag on `graph_impact`, because the
 two answer the same question over the same diff and a separate tool would have

package/dist/agent-src/templates/agents/agent-project-settings.example.yml

@@ -39,7 +39,7 @@ schema_version: 1
 # CI guard: a release bump of `package.json` must update this value
 # in lockstep — see scripts/check_template_pin_drift.ts (road-to-
 # portable-runtime-and-update-check P3.3).
-agent_config_version: "17.1.0"
+agent_config_version: "17.2.1"
 
 # --- Project identity ---
 project:

package/dist/cli/registry.js

@@ -77,7 +77,7 @@ export const REGISTRY = [
     { name: 'affected', disposition: 'delegate', synopsis: 'Artefacts related to <artefact> via the discovery relation-graph (BFS).' },
     { name: 'graph-explain', disposition: 'delegate', synopsis: 'Seed on a <concept>, expand 2 hops over the discovery relation-graph with a node budget.' },
     { name: 'benchmark', disposition: 'delegate', synopsis: 'Report context-token reduction vs the full always-loaded projection.' },
-    { name: 'code-graph', disposition: 'delegate', synopsis: 'Deterministic code-graph engine: build|detect|refresh|validate|query|affected|path|explain, plus the gate verbs impact|tests-for|untested|dead.' },
+    { name: 'code-graph', disposition: 'delegate', synopsis: 'Deterministic code-graph engine: build|detect|refresh|validate|query|affected|path|explain|map, plus the gate verbs impact|tests-for|untested|dead.' },
     { name: 'hooks:install', disposition: 'delegate', synopsis: 'Install the combined pre-commit hook.' },
     { name: 'hooks:status', disposition: 'delegate', synopsis: 'Print the runtime hook matrix (per-platform install + bindings).' },
     { name: 'hooks:doctor', disposition: 'delegate', synopsis: 'Diagnose hook health: concerns, posture, missing trampolines (read-only).' },

package/dist/cli-delegate/cmd_conformance.js

@@ -2364,19 +2364,11 @@ import * as fs4 from "node:fs";
 import * as path4 from "node:path";
 
 // src/scripts/code_graph/types.ts
-var GUESS_RESOLVED_VIA = /* @__PURE__ */ new Set([
-  "name-lookup",
-  "dynamic",
-  // The accepted-edge filter is a DENYLIST, so a new value is accepted by
-  // default — which is exactly backwards for this one. `foreign` must be
-  // listed here or a consumer's graph would silently answer the gate verbs
-  // as if this package had resolved its edges.
-  "foreign"
-]);
+var GUESS_RESOLVED_VIA = /* @__PURE__ */ new Set(["name-lookup", "dynamic", "foreign"]);
 function isStatedResolution(resolved_via) {
   return !GUESS_RESOLVED_VIA.has(resolved_via);
 }
-var SCHEMA_VERSION = 4;
+var SCHEMA_VERSION = 5;
 var EXT_LANG = {
   ".php": "php",
   ".ts": "typescript",
@@ -2386,37 +2378,24 @@ var EXT_LANG = {
   ".js": "javascript",
   ".jsx": "javascript",
   ".mjs": "javascript",
-  ".cjs": "javascript"
+  ".cjs": "javascript",
+  ".py": "python",
+  ".go": "go",
+  ".java": "java",
+  ".vue": "typescript"
 };
 
 // src/scripts/code_graph/validate.ts
-var RELATIONS = /* @__PURE__ */ new Set(["calls", "imports", "uses", "inherits", "member", "tests"]);
+var words = (s) => new Set(s.split(" "));
+var RELATIONS = words(
+  "calls imports uses inherits member tests routes-to renders includes reads migrates persists relates documents"
+);
 var CONFIDENCES = /* @__PURE__ */ new Set(["EXTRACTED", "INFERRED", "AMBIGUOUS"]);
-var RESOLVED_VIA = /* @__PURE__ */ new Set([
-  "same-file",
-  "import-specifier",
-  "path-alias",
-  "psr4",
-  "route-table",
-  "test-import",
-  "name-lookup",
-  "dynamic",
-  // Adapted from a consumer's own graph file; see `foreign.ts`.
-  "foreign"
-]);
-var PROVIDERS = /* @__PURE__ */ new Set(["native", "foreign"]);
-var KINDS = /* @__PURE__ */ new Set([
-  "file",
-  "class",
-  "interface",
-  "trait",
-  "function",
-  "method",
-  "constant",
-  "type",
-  "enum",
-  "skipped"
-]);
+var RESOLVED_VIA = words(
+  "same-file import-specifier path-alias psr4 route-table directive-scan schema-call eloquent-relation compiler-index test-import name-lookup dynamic foreign"
+);
+var PROVIDERS = /* @__PURE__ */ new Set(["native", "foreign", "scip"]);
+var KINDS = words("file class interface trait function method constant type enum skipped route table");
 function validateGraph(g) {
   const errors = [];
   const push = (m) => {
@@ -2435,6 +2414,7 @@ function validateGraph(g) {
     if (typeof n !== "object" || n === null) return push(`node[${i}] not an object`);
     const nn = n;
     if (typeof nn["id"] !== "string") push(`node[${i}].id must be a string`);
+    else if (ids.has(nn["id"])) push(`node[${i}].id is a duplicate: ${nn["id"]}`);
     else ids.add(nn["id"]);
     if (!KINDS.has(nn["kind"])) push(`node[${i}].kind invalid: ${String(nn["kind"])}`);
     if (typeof nn["source_file"] !== "string") push(`node[${i}].source_file must be a string`);
@@ -2546,7 +2526,7 @@ function detectSources(root, nativeCache) {
   } catch {
   }
   const scip = scipCandidates.find((p) => fs4.existsSync(p));
-  if (scip) out.push({ kind: "scip", path: scip, present: true, note: "SCIP detected \u2014 peer tooling required (no owned reader)" });
+  if (scip) out.push({ kind: "scip", path: scip, present: true, note: "SCIP \u2014 index.scip merges into the build" });
   if (fs4.existsSync(nativeCache)) out.push({ kind: "native", path: nativeCache, present: true, ...freshness(abs, nativeCache, null) });
   return out;
 }
@@ -2628,6 +2608,7 @@ function emitSqliteTwin(graph, serialized, jsonPath) {
       db.exec(
         "CREATE TABLE meta (key TEXT PRIMARY KEY, value TEXT NOT NULL);CREATE TABLE nodes (id TEXT PRIMARY KEY, label TEXT NOT NULL, kind TEXT, source_file TEXT, l0 INTEGER, l1 INTEGER, l2 INTEGER, l3 INTEGER);CREATE TABLE edges (source TEXT NOT NULL, target TEXT NOT NULL, relation TEXT NOT NULL, confidence TEXT NOT NULL, candidates TEXT, ambiguity_reason TEXT, resolved_via TEXT, provider TEXT);CREATE INDEX edges_source ON edges(source);CREATE INDEX edges_target ON edges(target);CREATE INDEX nodes_label ON nodes(label);CREATE INDEX nodes_source_file ON nodes(source_file);"
       );
+      db.exec("BEGIN");
       const meta = db.prepare("INSERT INTO meta (key, value) VALUES (?, ?)");
       meta.run("source_checksum", graph.source_checksum);
       meta.run("json_size", String(stat.size));
@@ -2666,14 +2647,17 @@ function emitSqliteTwin(graph, serialized, jsonPath) {
           e.provider
         );
       }
+      db.exec("COMMIT");
       stampUserVersion(db, GRAPH_STORE_VERSION);
     } finally {
       db.close();
     }
     fs5.renameSync(tmp, twin);
     return true;
-  } catch {
+  } catch (e) {
     fs5.rmSync(tmp, { force: true });
+    process.stderr.write(`code-graph: index not written: ${e.message}
+`);
     return false;
   }
 }

package/dist/discovery/deprecation-report.md

@@ -1,6 +1,6 @@
 # Discovery — Deprecation Report
 
-- Generated: `2026-10-23T06:28:42Z`
+- Generated: `2026-10-23T14:16:10Z`
 - Deprecated artefacts: **0**
 
 _None. Tree is clean._

package/dist/discovery/discovery-manifest.json

@@ -1747,7 +1747,7 @@
     },
     {
       "category": "command",
-      "checksum": "sha256:8bba107cef996a7ab75233a7c018c6294add3784f42ca7a4812f14adf5383dc7",
+      "checksum": "sha256:affd55963df4d3e9ba7e8281f8123dd1043a04ba5c1b33b6871f72290b19000b",
       "install": {
         "default": true,
         "removable": false
@@ -1772,12 +1772,12 @@
     },
     {
       "category": "command",
-      "checksum": "sha256:eee6f3f9303011d7fd27d1d3770c1c0a99f4fbe9cf52d2c43d693b0c32f10621",
+      "checksum": "sha256:1514c6d09bee3cbbc1996d9d0e7ee1c9dd38829ef293ded1e0e8f1eabed1f7bd",
       "install": {
         "default": true,
         "removable": false
       },
-      "intent": "Project dispatcher — full analysis or quick health check",
+      "intent": "Project dispatcher — full analysis, quick health check, or the project map",
       "lifecycle": "active",
       "name": "project",
       "pack": "engineering-base",
@@ -1788,7 +1788,8 @@
       "replaces": [],
       "routes_to": [
         "project-analyze",
-        "project-health"
+        "project-health",
+        "project-map"
       ],
       "slug": "project",
       "trust": {
@@ -1826,6 +1827,31 @@
         "agent-config-maintainer"
       ]
     },
+    {
+      "category": "command",
+      "checksum": "sha256:3a29995588969e6a591002e4ff5dade2ef9fac6c77edcd648f55da4559c4e8f9",
+      "install": {
+        "default": true,
+        "removable": false
+      },
+      "lifecycle": "active",
+      "name": "project-map",
+      "pack": "engineering-base",
+      "packs": [
+        "meta"
+      ],
+      "path": "src/domains/engineering-base/project/map/command.md",
+      "slug": "project-map",
+      "trust": {
+        "confidence": "high",
+        "human_review_required": false,
+        "level": "core"
+      },
+      "visibility": "internal",
+      "workspaces": [
+        "agent-config-maintainer"
+      ]
+    },
     {
       "category": "command",
       "checksum": "sha256:4317113046ac890122c413921e5acf353f8b6e45006fde6d35159a35d5f529a9",
@@ -9180,7 +9206,7 @@
     },
     {
       "category": "skill",
-      "checksum": "sha256:f2f711982f79425c130bc2b3df13e7737dc3c21613592b68f198b08aa13d210c",
+      "checksum": "sha256:cda3a959dd75ff8af2c300111f194ce3c1cc074f7b091769670ab39458534b63",
       "install": {
         "default": true,
         "removable": false
@@ -15094,7 +15120,7 @@
       "workspaces": []
     }
   ],
-  "checksum": "sha256:bd2c2d43c509910e8aefc47e34982aa12079b4cc772d9f1380226df82bb2b0e7",
+  "checksum": "sha256:78594c2e14f67a1cb0b14a85d62c2ccdc967977ab6bf4bf0f1a869d1a91d4e35",
   "deprecations": [
     {
       "key": "tier",
@@ -15243,7 +15269,7 @@
       "reason": "scaffold template for ticket-bundle tickets (ADR-101); carries no runtime frontmatter — emit-tickets fills it in per ticket"
     }
   ],
-  "generated_at": "2026-10-23T06:28:42Z",
+  "generated_at": "2026-10-23T14:16:10Z",
   "packs": [
     {
       "artefact_count": 130,
@@ -16009,7 +16035,7 @@
     },
     {
       "always_on": true,
-      "artefact_count": 307,
+      "artefact_count": 308,
       "description": "Artefacts that maintain this package (agent-config itself).",
       "domain": "meta",
       "human_review_required": 0,
@@ -16025,7 +16051,7 @@
       "trust_level_default": "core",
       "trust_summary": {
         "advisory": 0,
-        "core": 305,
+        "core": 306,
         "experimental": 2,
         "professional": 0,
         "restricted": 0
@@ -16116,27 +16142,27 @@
   "scanner_version": "de0a22b4ac4c",
   "stats": {
     "by_category": {
-      "command": 209,
+      "command": 210,
       "rule": 122,
       "skill": 301,
       "subagent": 3,
       "template": 1
     },
     "by_lifecycle": {
-      "active": 618,
+      "active": 619,
       "archived": 0,
       "deprecated": 0,
       "experimental": 18
     },
     "by_trust_level": {
       "advisory": 8,
-      "core": 501,
+      "core": 502,
       "experimental": 24,
       "professional": 103,
       "restricted": 0
     },
     "documented_unassigned_count": 27,
-    "total_artefacts": 636,
+    "total_artefacts": 637,
     "unassigned_count": 0
   },
   "unassigned": [],

package/dist/discovery/discovery-manifest.json.sha256

@@ -1 +1 @@
-49a3f57527f2284ac399784ab42ecbe4559adbd118178d1da7ffe0c0e1dfe6b8  discovery-manifest.json
+ae24bd45782c87fa0948de3cc5148ae565fc362b8b1e0997fbd6f155be39e922  discovery-manifest.json