@event4u/agent-config 8.11.0 → 8.12.0

package/dist/agent-src/skills/agent-docs-writing/SKILL.md

@@ -270,6 +270,89 @@ mv agents/tmp/<filename> agents/tmp.old/<filename>
 
 See `docs/contracts/agents-layout.md § User Inbox Workflow`.
 
+## Transient-reference discipline — mechanics (migrated from the `no-roadmap-references` rule)
+
+Body of [`no-roadmap-references`](../../rules/no-roadmap-references.md)
+(per P4 of `road-to-kernel-and-router.md`). The Iron Law — never link a
+specific `agents/roadmaps/` or `agents/runtime/council/` file from a stable
+artifact — stays in the rule; the pattern catalog lives here.
+
+### Forbidden patterns
+
+These paths must not appear inside a stable artifact:
+
+- `agents/roadmaps/<file>.md`, `agents/roadmaps/archive/<file>.md`,
+  `agents/roadmaps/skipped/<file>.md`
+- `agents/runtime/council/questions/<file>.md`,
+  `agents/runtime/council/responses/<file>.json`,
+  `agents/runtime/council/sessions/<file>.json` or `<timestamp>/...`
+
+Stable artifact = any file under `src/{rules,skills,domains}/`,
+`src/agent-src/{contexts,templates,personas}/`, `agents/settings/contexts/`,
+`docs/guidelines/`, `docs/contracts/`, `docs/architecture.md`,
+`docs/customization.md`, `docs/getting-started.md`, `docs/catalog.md`,
+`AGENTS.md`, `README.md`, `copilot-instructions.md`.
+
+CI enforcement: `scripts/check_no_roadmap_refs.ts` (roadmap layer)
+and `scripts/check_council_references.ts` (council layer) — both
+fail the build on any new violation.
+
+### Allowed patterns
+
+- `agents/roadmaps/` and `agents/runtime/council/` subdirs as **directory**
+  mentions (talking about the layer, not a specific file)
+- Roadmap → roadmap references (siblings within the transient layer)
+- The `ai-council` skill and `/council:*` commands documenting the
+  output path schema
+- Inline council convergence summary — e.g. *"Council
+  (claude-sonnet-4-5 + gpt-4o, 2026-05-06) converged on …"* with
+  date + members, no filepath
+- Council sessions, `agents/runtime/.agent-chat-history`, commit messages, PR
+  descriptions — transient by construction, not part of the package
+  surface
+
+### Structural carve-outs (immutable inputs / decision provenance)
+
+Two source/target shapes are exempt from the council-link ban
+because the target is **immutable input** or **decision provenance**,
+not transient drafting state. The linter implements these directly
+(`STRUCTURAL_CARVEOUTS` in `scripts/check_council_references.ts`);
+they do **not** need an inline `<!-- council-ref-allowed: ... -->`
+pragma.
+
+| Source | Target | Why |
+| --- | --- | --- |
+| `agents/settings/contexts/evaluation-*.md` | `agents/runtime/council/questions/<question>.md` | Question file is a frozen function-parameter / spend-gate input, not documentation. |
+| `docs/contracts/*.md` | `agents/runtime/council/sessions/<ts>/synthesis.md` | Synthesis is the audit-trail receipt; contract inlines the decision body itself. |
+
+Driven by the 2026-05-14 P3.4 council round (claude-sonnet-4-5 +
+gpt-4o, converged on rule refactor over escape-hatch overuse). Any
+other source/target combination still needs an inline pragma or
+inline-summary rewrite.
+
+### What to do instead
+
+When a stable artifact needs to cite a transient finding:
+
+1. Identify the durable conclusion — decision, contract, lesson,
+   mechanic.
+2. Promote it to a context file under `agents/settings/contexts/` (ADR,
+   mechanics doc, locked decision). The roadmap or council session
+   can then point at the context, not the other way around.
+3. Reference the context from the stable artifact.
+4. For council convergences specifically: inline a convergence-summary
+   block (members, date, cost if relevant — see
+   [`ai-council`](../ai-council/SKILL.md) § Output format) instead of
+   linking the session JSON.
+
+Failure modes:
+
+- *"I'll just link to the roadmap, it's evidence."* The roadmap
+  gets archived, then deleted, then the link rots. **Promote first,
+  link second.**
+- *"I'll just link to the session JSON, it's evidence."* The session
+  is gone in 7 days. **Inline first, link never.**
+
 ## Do NOT
 
 - Do NOT create docs unless there's a real need (new module, significant change).

package/dist/agent-src/skills/decision-review/SKILL.md

@@ -173,8 +173,94 @@ strengthening evidence.
   `skipped` (stale — age > `review_after_days`), surface them to
   the user; do not silently use stale entries as if they were current.
 
+## Decision-revisit gate — mechanics (migrated from the `decision-revisit-gate` rule)
+
+Body of [`decision-revisit-gate`](../../rules/decision-revisit-gate.md)
+(per P4 of `road-to-kernel-and-router.md`). The Iron Law — benefit blocked
+by a lock → surface + offer re-evaluation, never silent compliance — stays
+in the rule; the lock catalog, fire steps, and failure modes live here.
+
+### What counts as a "lock"
+
+- An eval verdict recorded as an honest null (a mechanism was tested,
+  showed no lift, and the disposition says "don't rebuild without new
+  evidence").
+- A memory entry or `agents/settings/contexts/` note tagged "don't
+  relitigate" / "settled" / a locked council convergence.
+- A budget or frugality-canon line (`token-budget-discipline`,
+  `telegraph-speak`, thin-projector trimming) that rejects a change on
+  cost grounds alone.
+- An ADR whose decision is being cited as a blocker for the current change.
+- A **hard structural cap** (kernel size, per-domain persona cap, rich-skill
+  ratio). A change that genuinely *qualifies* to cross the cap — e.g. a new
+  rule that truly meets the kernel-membership inclusion criteria — triggers a
+  **cap-raise proposal + maintainer/council approval**, never a silent
+  downgrade of the rule to fit the old number (e.g. demoting a must-always-fire
+  rule to `auto` just because the kernel says 9). Fitting the cap is not a
+  reason to weaken a qualifying rule; but a rule that does **not** meet the
+  criteria stays out — the cap is not the reason, the criteria are.
+
+### What to do when it fires
+
+1. **Mechanism-match check — do this FIRST.** A verdict settles the
+   *mechanism it tested*, not every future proposal that resembles it.
+   Before applying the lock, verify the blocked change is actually the
+   same mechanism — not merely a similar-sounding one. A null on
+   hardened blocking enforcement does not automatically cover
+   discretionary contextual nudges; a null on one architecture does not
+   cover a materially different one. If the mechanism differs, the lock
+   does not apply — proceed, noting the distinction.
+2. **If the mechanism genuinely matches**, do not silently comply.
+   Surface, in one short block:
+   - What change is blocked.
+   - Which lock blocks it (cite the memory/context/ADR).
+   - Under what conditions the lock was recorded (date, evidence, or
+     "maintainer decision" if settled-by-decision rather than
+     settled-by-evidence).
+   - What has changed since (new evidence, new model generation, new
+     tooling, repeated encounters) that makes revisiting worth the cost.
+3. **Offer numbered options** (per [`user-interaction`](../../rules/user-interaction.md)),
+   always including: re-evaluate the lock in the AI council. Other
+   options: keep the lock as-is, or proceed without the blocked change.
+4. **On re-evaluation:** run this skill's Procedure above for the
+   backward audit and route to [`ai-council`](../ai-council/SKILL.md)
+   for the debate mechanics. The rule owns the obligation to surface;
+   this skill and the council own the procedure.
+5. **Record the outcome** with scope + `revisit-if` per
+   [`ai-council`](../ai-council/SKILL.md)'s convergence-summary
+   contract — every re-evaluated lock gets a fresh, correctly-scoped
+   disposition, not a re-statement of the old one.
+
+### When NOT to fire
+
+- The blocked change has no real benefit — the gate is not a lever to
+  reopen every settled question; [`no-cheap-questions`](../../rules/no-cheap-questions.md)
+  still governs whether the resulting numbered-options block is a real
+  question or noise. A revisit-offer with a genuine trade-off is never
+  a "cheap question" under that rule — but a revisit-offer with no
+  actual case for change is.
+- The mechanism-match check (step 1) shows the lock is the same
+  mechanism and no new evidence exists — apply the lock, no surfacing
+  needed; this is the lock working as intended.
+- The user already declined a revisit on this exact lock this
+  conversation — per [`scope-control § Decline = silence`](../../rules/scope-control.md),
+  do not re-ask.
+
+### Failure modes
+
+- Treating a "don't relitigate" memory as permanently closed instead of
+  as settled-under-conditions-X.
+- Applying a null verdict to a superficially similar but architecturally
+  different mechanism without running the mechanism-match check.
+- Letting the token-frugality canon auto-reject a net-positive change
+  without surfacing the trade-off — see [`token-budget-discipline`](../../rules/token-budget-discipline.md)'s
+  value-over-budget clause.
+- Silently dropping a good idea because "we already decided this" —
+  the canonical failure the gate exists to stop.
+
 ## See also
 
+- [`decision-revisit-gate`](../../rules/decision-revisit-gate.md) — the rule whose migrated mechanics live above.
 - [`decision-record`](../decision-record/SKILL.md) — forward flow: lock a new choice.
 - [`adr-create`](../adr-create/SKILL.md) — file the ADR after a decision is locked.
 - [`blameless-post-mortem`](../blameless-post-mortem/SKILL.md) — incident review; may hand off to decision-review when a prior architectural choice is implicated.

package/dist/agent-src/skills/module-detect-on-the-fly/SKILL.md

@@ -1,7 +1,7 @@
 ---
 model_tier: medium
 name: module-detect-on-the-fly
-description: "Use when editing a file under a module-shaped path (`Modules/*`, `packages/*`, `apps/*`, `internal/*`) while `modules.enabled` is `false` — asks the user once whether to enable the config."
+description: "Use when editing a module-shaped path (`Modules/*`, `packages/*`, `apps/*`) while `modules.enabled` is false — asks once to enable it; also the project/stack + task-runner detection reference."
 domain: process
 workspaces:
   - agent-config-maintainer
@@ -119,6 +119,63 @@ Confirm both flags via `get_modules_config()` before running detection.
   the options block, continue the work and treat the project as flat
   for the rest of the session.
 
+## Project & module detection reference
+
+_Origin: migrated from `src/rules/architecture.md` per the P4 pattern of `road-to-kernel-and-router.md`. The rule keeps the Iron-Law block, General Principles, and the ADR paragraph; the detection mechanics live here._
+
+### Project detection
+
+Detect the current project type from the **Git remote URL**, **directory name**, or **project files**:
+
+- **PHP** — `composer.json` (framework slot: Laravel via `artisan`, Symfony via `bin/console`, standalone otherwise).
+- **JS / TS** — `package.json` (framework slot: Next.js via `next` dep, Nuxt via `nuxt`, Express / Fastify / NestJS via deps; plain Node otherwise).
+- **Python** — `pyproject.toml` / `requirements.txt` (framework slot: Django via `django`, FastAPI via `fastapi`, Flask via `flask`).
+- **Go** — `go.mod` (framework slot: `gin`, `echo`, `fiber`, stdlib `net/http`).
+- **Ruby** — `Gemfile` (framework slot: Rails via `rails` gem, Sinatra otherwise).
+- **Rust** — `Cargo.toml` (framework slot: `axum`, `actix-web`, `rocket`).
+- Check `AGENTS.md` or `agents/` for project-specific documentation.
+
+Tooling lives in a runner file at the project root — detect once and reuse the result:
+`Taskfile.yml` → `task`, `Makefile` → `make`, `package.json` `scripts:` → `npm` / `pnpm` / `yarn`, `pyproject.toml` `[tool.poetry.scripts]` or `[project.scripts]` → `poetry` / `uv`, framework CLIs (`artisan`, `bin/console`, `manage.py`, `bin/rails`) when the matching manifest is present.
+
+### Project-specific architecture docs
+
+Each project documents its own architecture in `./agents/` and/or `AGENTS.md`.
+**Always read those files** before making structural decisions. Do not rely on
+generic rules for project-specific directory layouts, database conventions, or
+module systems.
+
+### Module-level documentation
+
+Some projects use a module system (e.g. `app/Modules/` in Laravel, `apps/`/`packages/` in a Turborepo, `src/modules/` in NestJS, `internal/` in Go).
+Module roots and the per-module agent-docs folder are configured via
+`modules.root_paths` and `modules.agent_folder` in `.agent-settings.yml`
+(resolve at runtime via `scripts/_lib/agent_settings.ts::enumerate_modules()`).
+Modules may have their own agent docs under
+`{module_root}/*/{agent_folder}/` (Laravel shape: `app/Modules/*/agents/`) with:
+
+- Module descriptions and feature docs
+- Module-specific roadmaps (`agents/roadmaps/`)
+- Module-specific documentation (`Docs/`)
+
+When working on a module, **always check for module-level agent docs** first.
+
+### Packages
+
+Packages (Composer, npm, etc.) may also use `./agents/` in their root
+for package-specific docs and roadmaps. Treat them the same way as projects.
+
+### Build / task runner detection
+
+Projects use either `Makefile` or `Taskfile.yml` (or both) for common commands.
+**Always check which one exists** and read it to discover available targets for
+testing, quality checks, container access, migrations, etc.
+
+- `Makefile` → use `make <target>`
+- `Taskfile.yml` → use `task <target>`
+
+Prefer these targets over raw `docker compose exec` commands when available.
+
 ## See also
 
 - `module-management` — the active skill once modules are configured.

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: "8.11.0"
+agent_config_version: "8.12.0"
 
 # --- Project identity ---
 project:

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

@@ -7,6 +7,18 @@ trust: durable
 # Optional for project-local cards; required (plus a provenance footer) once a
 # card is promoted to the global store. Resolve via knowledge_global.classify_tier.
 tier: "<public | vendor | proprietary>"
+# sensitivity — orthogonal to tier: WHETHER this card may ever leave the
+# project at all (tier is WHERE it came from). Phase 1, road-to-feedback-8.11
+# / successor note to ADR-119. Three machine-anchored classes:
+#   prohibited = contains redaction-class content; never leaves the repo
+#                (machine-derived from the redaction scan — never hand-set).
+#   project    = DEFAULT. Stays project-local; promotion refused unless a
+#                human explicitly reclassifies the card to `shareable`.
+#   shareable  = eligible for the global store; must pass redaction AND
+#                carry full promotion provenance (see the footer once
+#                promoted: source_repo, owner, review_after, promotion_reason).
+# Required (and machine-checked) once a card is promoted to the global store.
+sensitivity: "project"
 origin: "<brief description — e.g. npm package / remote API / legacy DB>"
 url: "<canonical upstream URL>"
 ref: "<pinned version tag or commit SHA — never blind main>"

package/dist/discovery/deprecation-report.md

@@ -1,6 +1,6 @@
 # Discovery — Deprecation Report
 
-- Generated: `2026-07-12T08:25:51Z`
+- Generated: `2026-07-12T13:30:17Z`
 - Deprecated artefacts: **0**
 
 _None. Tree is clean._

package/dist/discovery/discovery-manifest.json

@@ -4945,7 +4945,7 @@
     },
     {
       "category": "rule",
-      "checksum": "sha256:e0cedb7e0bd96806a7eae9b750add16d04e00dc8e62ee7adff8c44ca0c231489",
+      "checksum": "sha256:93f763246cf4e462db9c4d54fc033ffb9c0ce5865a2e25b6b0381a84308f04ff",
       "install": {
         "default": true,
         "removable": false
@@ -5177,7 +5177,7 @@
     },
     {
       "category": "rule",
-      "checksum": "sha256:e9251d55c8c1d4c9841c3e374833b1bc986acfc1a666ba77604d885133bad5eb",
+      "checksum": "sha256:c642c0a5798b5bfed082b9c2e86e4c3f8830e2971d1bba12df59094e060ee6da",
       "install": {
         "default": true,
         "removable": false
@@ -5382,7 +5382,7 @@
     },
     {
       "category": "rule",
-      "checksum": "sha256:4e3fc01547374c7d76af3b02a77e0667ad10544c63c035ba34b78e90fedaee11",
+      "checksum": "sha256:f09f13f41eab26421f29cc731f8b1b737f9f37079c913416ba686bc9d45a8bc2",
       "install": {
         "default": true,
         "removable": false
@@ -5867,7 +5867,7 @@
     },
     {
       "category": "rule",
-      "checksum": "sha256:e8d150ab415cdaf12ef8132617eadc395d7efdf01f10b579da2288c794bc9bfc",
+      "checksum": "sha256:b5477c078fa690cfd61150f3dc7d79dbac6397517d283bec29948c506a1dc9c8",
       "install": {
         "default": true,
         "removable": false
@@ -6329,7 +6329,7 @@
     },
     {
       "category": "rule",
-      "checksum": "sha256:da3379d2b9d801b5a6ee309934494cc0c03ea60a11d9af129130388801ca3f2f",
+      "checksum": "sha256:b4f586610cd51268c9bdb8360a798642244d9b2d2521bf5100298bbdce1ec3fc",
       "install": {
         "default": true,
         "removable": false
@@ -6465,7 +6465,7 @@
     },
     {
       "category": "rule",
-      "checksum": "sha256:21910e7a90c08dd9da8a40e7c7be640529a4e4051644ed3744d6147cb8e98381",
+      "checksum": "sha256:3878d1b74420f68e2681b636718f60a3a8b3cb224cd5df1b74936d824e74bf6c",
       "install": {
         "default": true,
         "removable": false
@@ -6549,7 +6549,7 @@
     },
     {
       "category": "rule",
-      "checksum": "sha256:ea7e4237e99f269ed95efd37f673e8b85b726030ba6f926b3fb4a998677b2fe8",
+      "checksum": "sha256:d6e74bc3809c7b9d0a692bafae238c905e16c812fa4ffe884d37dbb419e3f90d",
       "install": {
         "default": true,
         "removable": false
@@ -6616,7 +6616,7 @@
     },
     {
       "category": "rule",
-      "checksum": "sha256:d3cb7efd6c419f13ace8126264f1a1f2c01d9d445f80c451022c0bb811902fa1",
+      "checksum": "sha256:db20269002f94ba1564050797367485a33264fba95a37cef8dfe23cba460e4d0",
       "install": {
         "default": true,
         "removable": false
@@ -7174,7 +7174,7 @@
     },
     {
       "category": "rule",
-      "checksum": "sha256:37983317316d9ff13f9bea53a8177a19252655e8b82dba4391f107785b3a4e79",
+      "checksum": "sha256:1a7625fcb13e1268adf9cfe417a3b3de13edd1d4a60a9a849345ab7e2120c102",
       "install": {
         "default": true,
         "removable": false
@@ -7386,7 +7386,7 @@
     },
     {
       "category": "skill",
-      "checksum": "sha256:4709fc13a7ccb37a335f229f97c407497ad4fdbd85f15900f5de504fff0c022a",
+      "checksum": "sha256:88c6ff8281b0ee68b5d6d9402bd4b39087f7fb05e5ad92957fd24a63ee0f4032",
       "install": {
         "default": true,
         "removable": false
@@ -8640,7 +8640,7 @@
     },
     {
       "category": "skill",
-      "checksum": "sha256:a76ad1dc72b58db24793cf28f4d80abb5dc1300783baca29d3df299ceea6410e",
+      "checksum": "sha256:21fe1e1cab3bf7e739a0e3dbfe48ec60c0da59caae1c791b7003e1ccb1f6f42e",
       "install": {
         "default": false,
         "removable": true
@@ -10642,7 +10642,7 @@
     },
     {
       "category": "skill",
-      "checksum": "sha256:d3b4d5038ff32f3c24ee7b66c76833ea0486c82ad51332b7009cc60479d9d484",
+      "checksum": "sha256:da0978b98607af3fb63fee16e5fa45e9b79a62803678518fbedd6aec3165e647",
       "install": {
         "default": true,
         "removable": false
@@ -13277,7 +13277,7 @@
       "workspaces": []
     }
   ],
-  "checksum": "sha256:2e4ae6b3ee79b3233182c1b5fb33c5566263418e004db05c76963e26ec7e1d63",
+  "checksum": "sha256:56deb428fad47a9e6ba6ba1abd224d75de548b62783275e3766d23dff86f5709",
   "deprecations": [
     {
       "key": "tier",
@@ -13420,7 +13420,7 @@
       "reason": "scaffold template for ticket-bundle tickets (ADR-101); carries no runtime frontmatter — emit-tickets fills it in per ticket"
     }
   ],
-  "generated_at": "2026-07-12T08:25:51Z",
+  "generated_at": "2026-07-12T13:30:17Z",
   "packs": [
     {
       "artefact_count": 105,

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

@@ -1 +1 @@
-359effcea577be7f6892e96e07d5bebced7efc6d4803bbac0a8e7661daf3ceb8  discovery-manifest.json
+e086e9b77bd9a0446fe86ca182d410759d46295fbb58e85044bde42b0310b165  discovery-manifest.json

package/dist/discovery/discovery-manifest.summary.md

@@ -1,6 +1,6 @@
 # Discovery Manifest — Summary
 
-- Generated: `2026-07-12T08:25:51Z`
+- Generated: `2026-07-12T13:30:17Z`
 - Scanner: `c24312e116f8`
 - Artefacts: **555**
 - Unassigned: **0**

package/dist/discovery/orphan-report.md

@@ -1,6 +1,6 @@
 # Discovery — Orphan Report
 
-- Generated: `2026-07-12T08:25:51Z`
+- Generated: `2026-07-12T13:30:17Z`
 - Orphan artefacts: **0**
 
 > An orphan is an artefact whose declared pack has no other members.

package/dist/discovery/packs.json

@@ -1,6 +1,6 @@
 {
-  "checksum": "sha256:2e4ae6b3ee79b3233182c1b5fb33c5566263418e004db05c76963e26ec7e1d63",
-  "generated_at": "2026-07-12T08:25:51Z",
+  "checksum": "sha256:56deb428fad47a9e6ba6ba1abd224d75de548b62783275e3766d23dff86f5709",
+  "generated_at": "2026-07-12T13:30:17Z",
   "packs": [
     {
       "always_on": false,

package/dist/discovery/trust-report.md

@@ -1,6 +1,6 @@
 # Discovery — Trust Report
 
-- Generated: `2026-07-12T08:25:51Z`
+- Generated: `2026-07-12T13:30:17Z`
 - Workspaces tracked: **10**
 - Human-review-required artefacts: **3**
 

package/dist/discovery/workspaces.json

@@ -1,6 +1,6 @@
 {
-  "checksum": "sha256:2e4ae6b3ee79b3233182c1b5fb33c5566263418e004db05c76963e26ec7e1d63",
-  "generated_at": "2026-07-12T08:25:51Z",
+  "checksum": "sha256:56deb428fad47a9e6ba6ba1abd224d75de548b62783275e3766d23dff86f5709",
+  "generated_at": "2026-07-12T13:30:17Z",
   "scanner_version": "c24312e116f8",
   "workspaces": [
     {

package/dist/mcp/registry-manifest.json

@@ -9,7 +9,7 @@
     "homepage": "https://event4u-app.github.io/agent-config",
     "name": "@event4u/agent-config",
     "repository": "https://github.com/event4u-app/agent-config",
-    "version": "8.11.0"
+    "version": "8.12.0"
   },
   "registries": [
     {