@event4u/agent-config 14.21.0 → 14.23.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (235) hide show
  1. package/.augment-plugin/marketplace.json +3 -3
  2. package/.augment-plugin/plugin.json +1 -1
  3. package/.claude-plugin/marketplace.json +1 -1
  4. package/CHANGELOG.md +164 -187
  5. package/CREDITS.md +37 -0
  6. package/README.md +1 -1
  7. package/dist/agent-src/commands/analyze/inbox.md +380 -5
  8. package/dist/agent-src/commands/analyze/repo.md +4 -2
  9. package/dist/agent-src/commands/pr/merge.md +47 -38
  10. package/dist/agent-src/commands/roadmap/next.md +8 -0
  11. package/dist/agent-src/contexts/communication/rules-auto/token-efficiency-mechanics.md +69 -0
  12. package/dist/agent-src/contexts/execution/auto-dispatch-classification.md +5 -5
  13. package/dist/agent-src/contexts/execution/autonomy-mechanics.md +12 -0
  14. package/dist/agent-src/rules/external-code-graph-interop.md +19 -14
  15. package/dist/agent-src/rules/notes-first-reasoning.md +36 -25
  16. package/dist/agent-src/rules/token-efficiency.md +26 -3
  17. package/dist/agent-src/scripts/_cli_entry.ts +51 -0
  18. package/dist/agent-src/scripts/archive_completed_roadmaps.ts +120 -27
  19. package/dist/agent-src/scripts/roadmap_gates.ts +4 -20
  20. package/dist/agent-src/scripts/roadmap_set_step.ts +5 -2
  21. package/dist/agent-src/scripts/stubs_due.ts +4 -18
  22. package/dist/agent-src/scripts/update_roadmap_progress.ts +7 -24
  23. package/dist/agent-src/skills/code-intelligence/SKILL.md +82 -1
  24. package/dist/agent-src/skills/git-workflow/references/push-closes-its-loop.md +9 -0
  25. package/dist/agent-src/skills/roadmap-writing/SKILL.md +17 -0
  26. package/dist/agent-src/skills/tailwind-engineer/SKILL.md +52 -2
  27. package/dist/agent-src/templates/agent-settings.md +0 -1
  28. package/dist/agent-src/templates/agents/agent-project-settings.example.yml +1 -1
  29. package/dist/cli/registry.js +1 -1
  30. package/dist/cli-delegate/_cli_entry.js +8 -0
  31. package/dist/cli-delegate/_lib/pin_resolver.js +170 -0
  32. package/dist/cli-delegate/archival_sweep.js +8 -0
  33. package/dist/cli-delegate/archive_completed_roadmaps.js +542 -0
  34. package/dist/cli-delegate/check_update_banner.js +923 -0
  35. package/dist/cli-delegate/{chunk-ZVBOHSVF.js → chunk-2KKXJW25.js} +23 -9
  36. package/dist/cli-delegate/chunk-5EK5WQN6.js +28 -0
  37. package/dist/cli-delegate/chunk-7XGD2OEU.js +96 -0
  38. package/dist/cli-delegate/chunk-DBH4AHDK.js +155 -0
  39. package/dist/cli-delegate/{chunk-4FS4WRXP.js → chunk-IAI3XL43.js} +15 -3
  40. package/dist/cli-delegate/chunk-JO25G5H7.js +20 -0
  41. package/dist/cli-delegate/{chunk-643Z7FIC.js → chunk-KCNTUSPI.js} +7 -1
  42. package/dist/cli-delegate/chunk-LTYVIY76.js +7961 -0
  43. package/dist/cli-delegate/chunk-QAJS5YWY.js +999 -0
  44. package/dist/cli-delegate/{chunk-YS6XTLEK.js → chunk-TYSY33MD.js} +56 -6
  45. package/dist/cli-delegate/chunk-ULET4BYS.js +328 -0
  46. package/dist/cli-delegate/chunk-YDQSHTD7.js +187 -0
  47. package/dist/cli-delegate/chunk-YWVXLR44.js +48 -0
  48. package/dist/cli-delegate/chunk-ZZQBUHFK.js +273 -0
  49. package/dist/cli-delegate/cmd_conformance.js +2 -2
  50. package/dist/cli-delegate/cmd_export.js +2 -2
  51. package/dist/cli-delegate/cmd_handoff.js +45 -13
  52. package/dist/cli-delegate/cmd_prune.js +2 -2
  53. package/dist/cli-delegate/cmd_session_recycle.js +4 -14
  54. package/dist/cli-delegate/cmd_settings_migrate.js +2 -2
  55. package/dist/cli-delegate/cmd_settings_set.js +1 -1
  56. package/dist/cli-delegate/cmd_sync.js +2 -2
  57. package/dist/cli-delegate/cmd_uninstall.js +2 -2
  58. package/dist/cli-delegate/cmd_validate.js +2 -2
  59. package/dist/cli-delegate/dashboard_mode.js +16 -0
  60. package/dist/cli-delegate/gate_budget.js +24 -0
  61. package/dist/cli-delegate/gate_execute.js +25 -0
  62. package/dist/cli-delegate/guarded_baseline.js +18 -0
  63. package/dist/cli-delegate/resume_probe.js +22 -0
  64. package/dist/cli-delegate/roadmap_gates.js +638 -0
  65. package/dist/cli-delegate/roadmap_set_step.js +173 -0
  66. package/dist/cli-delegate/stub_queue.js +47 -0
  67. package/dist/cli-delegate/stubs_due.js +38 -0
  68. package/dist/cli-delegate/ticket_bundles.js +59 -0
  69. package/dist/cli-delegate/update_roadmap_progress.js +60 -0
  70. package/dist/discovery/deprecation-report.md +1 -1
  71. package/dist/discovery/discovery-manifest.json +13 -13
  72. package/dist/discovery/discovery-manifest.json.sha256 +1 -1
  73. package/dist/discovery/discovery-manifest.summary.md +1 -1
  74. package/dist/discovery/dormancy-report.md +1 -1
  75. package/dist/discovery/orphan-report.md +1 -1
  76. package/dist/discovery/packs.json +2 -2
  77. package/dist/discovery/trust-report.md +1 -1
  78. package/dist/discovery/workspaces.json +2 -2
  79. package/dist/hooks/dispatch.js +1813 -946
  80. package/dist/install/claudeLayerCarriage.js +237 -0
  81. package/dist/install/claudePathsPlan.js +79 -0
  82. package/dist/install/hostLayerFingerprint.js +1 -1
  83. package/dist/install/install.mjs +21 -3
  84. package/dist/install/partitionEligibility.js +231 -117
  85. package/dist/install/ruleLayerPartition.js +10 -7
  86. package/dist/mcp/registry-manifest.json +2 -2
  87. package/dist/mcp/server.json +2 -2
  88. package/dist/mcp/server.mjs +10870 -7641
  89. package/dist/scripts/_lib/lean_projection_mode.js +108 -0
  90. package/dist/scripts/_lib/router_match.js +243 -0
  91. package/dist/scripts/_lib/rule_injection.js +216 -0
  92. package/dist/scripts/condense.js +52 -45
  93. package/dist/scripts/project_thin_rules.js +139 -19
  94. package/dist/server/schemas/settings.js +16 -3
  95. package/docs/MIGRATION.md +105 -1
  96. package/docs/contracts/settings-classes.md +40 -8
  97. package/docs/guidelines/agent-infra/minimal-safe-diff-mechanics.md +73 -0
  98. package/docs/guidelines/agent-infra/notes-horizon-mechanics.md +90 -0
  99. package/llms.txt +1 -1
  100. package/package.json +7 -4
  101. package/src/agent-src/scripts/_cli_entry.ts +51 -0
  102. package/src/agent-src/scripts/archive_completed_roadmaps.ts +120 -27
  103. package/src/agent-src/scripts/roadmap_gates.ts +4 -20
  104. package/src/agent-src/scripts/roadmap_set_step.ts +5 -2
  105. package/src/agent-src/scripts/stubs_due.ts +4 -18
  106. package/src/agent-src/scripts/update_roadmap_progress.ts +7 -24
  107. package/src/config/agent-settings.template.yml +47 -1
  108. package/src/config/continuity-surface.json +516 -0
  109. package/src/config/estate-count-budget.json +1 -1
  110. package/src/config/evaluator-budgets.json +4 -4
  111. package/src/config/gate-coverage.yml +29 -8
  112. package/src/config/gate-violation-baselines.json +8 -8
  113. package/src/config/gitignore-block.txt +19 -0
  114. package/src/config/hook-token-budget.json +7 -6
  115. package/src/config/host-injection-effect.json +73 -0
  116. package/src/config/packed-binary-manifest.json +33 -0
  117. package/src/config/preamble-payload-budget.json +112 -105
  118. package/src/config/publish-surface.json +4 -2
  119. package/src/config/routing-coverage-seed.json +9 -2
  120. package/src/install/claudeLayerCarriage.ts +273 -0
  121. package/src/install/claudePathsPlan.ts +76 -0
  122. package/src/install/hostLayerFingerprint.ts +1 -1
  123. package/src/install/partitionEligibility.ts +261 -127
  124. package/src/install/ruleLayerPartition.ts +19 -23
  125. package/src/scripts/_cli/cmd_session_recycle.ts +2 -25
  126. package/src/scripts/_cli/handoff_sessions.ts +14 -44
  127. package/src/scripts/_dispatch.bash +77 -27
  128. package/src/scripts/_lib/auto_dispatch.ts +2 -2
  129. package/src/scripts/_lib/catalogue_layer_parity.ts +146 -0
  130. package/src/scripts/_lib/continuity_slot.ts +295 -0
  131. package/src/scripts/_lib/continuity_surface.ts +296 -0
  132. package/src/scripts/_lib/continuity_writer.ts +253 -0
  133. package/src/scripts/_lib/corpus_manifest.ts +26 -9
  134. package/src/scripts/_lib/hook_settings.ts +86 -1
  135. package/src/scripts/_lib/injection_effect.ts +151 -0
  136. package/src/scripts/_lib/layer_overlap_notice.ts +50 -6
  137. package/src/scripts/_lib/lean_projection_mode.ts +127 -0
  138. package/src/scripts/_lib/packed_binary_predicate.ts +262 -0
  139. package/src/scripts/_lib/pin_resolver.ts +13 -0
  140. package/src/scripts/_lib/recycle_envelope_paths.ts +109 -21
  141. package/src/scripts/_lib/regression_neighbourhood.ts +159 -22
  142. package/src/scripts/_lib/retired_status.ts +74 -0
  143. package/src/scripts/_lib/session_eol.ts +44 -0
  144. package/src/scripts/_lib/session_index_trust.ts +346 -0
  145. package/src/scripts/_lib/skill_catalogue.ts +156 -21
  146. package/src/scripts/_lib/standing_bound_ratchet.ts +154 -0
  147. package/src/scripts/_lib/subagent_capsule.ts +117 -8
  148. package/src/scripts/_lib/vendored_grammar_upstream.ts +280 -0
  149. package/src/scripts/ai_council/api_transport.ts +5 -0
  150. package/src/scripts/ai_council/deliberation_metrics.ts +353 -0
  151. package/src/scripts/ai_council/prompts.ts +9 -0
  152. package/src/scripts/ai_council/synthesis_disagreement.ts +206 -0
  153. package/src/scripts/audit_mcp_tools.ts +69 -25
  154. package/src/scripts/build_mcp_catalog.ts +24 -1
  155. package/src/scripts/capture_skill_catalogue.ts +24 -11
  156. package/src/scripts/check_candidate_lines.ts +499 -0
  157. package/src/scripts/check_continuity_surface.ts +475 -0
  158. package/src/scripts/check_dependency_floors.ts +13 -6
  159. package/src/scripts/check_estate_count.ts +40 -79
  160. package/src/scripts/check_host_tree_parity.ts +291 -0
  161. package/src/scripts/check_pack_size.ts +262 -23
  162. package/src/scripts/check_preamble_payload_budget.ts +136 -7
  163. package/src/scripts/check_roadmap_trackable.ts +19 -16
  164. package/src/scripts/check_rule_layer_partition.ts +54 -34
  165. package/src/scripts/check_rule_projection_integrity.ts +102 -2
  166. package/src/scripts/check_single_delivery.ts +97 -31
  167. package/src/scripts/check_update_banner.ts +13 -0
  168. package/src/scripts/ci_settle.ts +205 -5
  169. package/src/scripts/code_graph/build.ts +217 -15
  170. package/src/scripts/code_graph/cli.ts +334 -15
  171. package/src/scripts/code_graph/detect.ts +38 -0
  172. package/src/scripts/code_graph/extract.ts +11 -0
  173. package/src/scripts/code_graph/grammar_probe.ts +43 -0
  174. package/src/scripts/code_graph/loader.ts +88 -14
  175. package/src/scripts/code_graph/query.ts +144 -11
  176. package/src/scripts/code_graph/resolution_tiers.ts +238 -0
  177. package/src/scripts/code_graph/sqlite_store.ts +262 -6
  178. package/src/scripts/code_graph/types.ts +117 -3
  179. package/src/scripts/code_graph/validate.ts +26 -1
  180. package/src/scripts/code_graph/verbs.ts +590 -0
  181. package/src/scripts/condense.ts +54 -42
  182. package/src/scripts/corpus_manifest.ts +5 -5
  183. package/src/scripts/council_cli.ts +11 -12
  184. package/src/scripts/count_intent_disagreement.ts +426 -0
  185. package/src/scripts/handoff_context_hook.ts +118 -1
  186. package/src/scripts/hook_effect_doctor.ts +82 -1
  187. package/src/scripts/hook_manifest.json +1 -1
  188. package/src/scripts/hook_manifest.yaml +87 -12
  189. package/src/scripts/hooks/block_speaking_inbox_dir.ts +182 -16
  190. package/src/scripts/hooks/chain_nudge_hook.ts +282 -0
  191. package/src/scripts/hooks/code_graph_context_hook.ts +201 -0
  192. package/src/scripts/hooks/concern_registry.ts +4 -2
  193. package/src/scripts/hooks/host_semantics.ts +1 -1
  194. package/src/scripts/hooks/orchestration_record_hook.ts +2 -2
  195. package/src/scripts/hooks/push_settle_hook.ts +3 -2
  196. package/src/scripts/hooks/rule_inject_hook.ts +108 -21
  197. package/src/scripts/hooks/session_eol_hook.ts +120 -2
  198. package/src/scripts/hooks/skill_route_hook.ts +11 -4
  199. package/src/scripts/hot_context_hook.ts +62 -7
  200. package/src/scripts/inbox_source_census.ts +322 -0
  201. package/src/scripts/install-hooks.sh +82 -0
  202. package/src/scripts/{lint_carrier_integrity.ts → lint_deferral_integrity.ts} +60 -214
  203. package/src/scripts/lint_plan_risk_register.ts +13 -17
  204. package/src/scripts/lint_roadmap_blockers.ts +164 -1
  205. package/src/scripts/mcp_server/consumer_tool_catalog.json +152 -2
  206. package/src/scripts/mcp_server/graph_tools.ts +294 -0
  207. package/src/scripts/mcp_server/path_util.ts +31 -0
  208. package/src/scripts/mcp_server/suggest_skill.ts +72 -0
  209. package/src/scripts/mcp_server/tool_catalog_source.ts +7 -1
  210. package/src/scripts/mcp_server/tools.ts +5 -69
  211. package/src/scripts/media/lib/adapter-contract.md +7 -2
  212. package/src/scripts/media/lib/fixtures/flux/asset-0001.png +0 -0
  213. package/src/scripts/media/lib/fixtures/gemini-image/asset-0001.png +0 -0
  214. package/src/scripts/media/lib/fixtures/ideogram/asset-0001.png +0 -0
  215. package/src/scripts/model_rule_injection.ts +61 -4
  216. package/src/scripts/project_thin_rules.ts +149 -16
  217. package/src/scripts/rdp_candidates_delta.ts +276 -0
  218. package/src/scripts/rdp_quality_eval.ts +217 -19
  219. package/src/scripts/release_mix_taxonomy.json +3 -2
  220. package/src/scripts/report_host_injection_effect.ts +189 -0
  221. package/src/scripts/report_layer_overlap.ts +41 -0
  222. package/src/scripts/report_skill_menu_census.ts +341 -0
  223. package/src/scripts/report_standing_payload_by_host.ts +650 -0
  224. package/src/scripts/schemas/agent-settings.schema.json +7 -1
  225. package/src/scripts/session_memory_index.ts +81 -8
  226. package/src/scripts/skill_tools/score_skill_relevance.ts +70 -6
  227. package/src/scripts/skill_tools/suggest_skill_for_task.ts +37 -3
  228. package/src/server/schemas/settings.ts +23 -4
  229. package/src/vendor/grammars/README.md +86 -0
  230. package/src/vendor/grammars/tree-sitter-javascript.wasm +0 -0
  231. package/src/vendor/grammars/tree-sitter-php.wasm +0 -0
  232. package/src/vendor/grammars/tree-sitter-typescript.wasm +0 -0
  233. package/src/scripts/_lib/carrier_status.ts +0 -118
  234. package/src/scripts/_lib/estate_carrier_cases.ts +0 -72
  235. package/src/scripts/hooks/code_graph_nudge_hook.ts +0 -191
@@ -62,7 +62,7 @@ import { createRequire } from 'node:module';
62
62
  import { spawnSync } from 'node:child_process';
63
63
  import * as fs from 'node:fs';
64
64
  import * as path from 'node:path';
65
- import { fileURLToPath, pathToFileURL } from 'node:url';
65
+ import { fileURLToPath } from 'node:url';
66
66
  import { run_archival_sweep } from './archival_sweep.js';
67
67
  import {
68
68
  evaluateDashboardOnDisk,
@@ -72,6 +72,8 @@ import {
72
72
  } from './dashboard_mode.js';
73
73
  import type * as YamlModule from 'yaml';
74
74
  import { headerFragment as stubHeaderFragment } from './stubs_due.js';
75
+
76
+ import { isCliEntry } from './_cli_entry.js';
75
77
  import { reportGuardedBaselines } from './guarded_baseline.js'; // third step state; contract lives there
76
78
 
77
79
  const _HERE = fileURLToPath(import.meta.url);
@@ -96,7 +98,9 @@ const EXCLUDE_DIRS: ReadonlySet<string> = new Set(['archive', 'skipped', 'stubs'
96
98
 
97
99
  // FRONTMATTER_RE = re.compile(r"\A---\n(.*?)\n---\s*\n", re.DOTALL)
98
100
  const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---[ \t\n\r\f\v]*\n/;
99
- const UNSCHEDULED_VALUES: ReadonlySet<string> = new Set(['draft', 'carrier']);
101
+ // A set of one since ADR-262 deleted `status: carrier`; the shape stays so a
102
+ // future unscheduled value is one entry rather than a control-flow change.
103
+ const UNSCHEDULED_VALUES: ReadonlySet<string> = new Set(['draft']);
100
104
 
101
105
  const MERGE_GATED_RE = /merge-gated/i;
102
106
  // PR_NUM_RE = re.compile(r"pr\s*[=#:]?\s*#?\s*(\d+)", re.IGNORECASE)
@@ -1438,28 +1442,7 @@ function main(argv?: readonly string[]): number {
1438
1442
  return guarded.problems > 0 ? 1 : 0;
1439
1443
  }
1440
1444
 
1441
- function _isCliEntry(): boolean {
1442
- if (process.argv[1] === undefined) {
1443
- return false;
1444
- }
1445
- const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
1446
- if (import.meta.url === argvUrl) {
1447
- return true;
1448
- }
1449
- // A symlinked invocation (e.g. via `.augment/scripts` → `dist/agent-src/scripts`,
1450
- // or macOS /var → /private/var temp dirs) makes the raw URLs differ:
1451
- // import.meta.url is the resolved real path while argv[1] keeps the symlink
1452
- // path. Compare realpaths so the entry guard still fires (without this the
1453
- // dashboard regen silently no-ops when run through the symlink).
1454
- try {
1455
- const here = fs.realpathSync(fileURLToPath(import.meta.url));
1456
- const argv = fs.realpathSync(path.resolve(process.argv[1]));
1457
- return here === argv;
1458
- } catch {
1459
- return false;
1460
- }
1461
- }
1462
- if (_isCliEntry() || process.argv[1] === _HERE) {
1445
+ if (isCliEntry(import.meta.url, 'update_roadmap_progress')) {
1463
1446
  try {
1464
1447
  process.exitCode = main();
1465
1448
  } catch (exc) {
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  model_tier: inherit
3
3
  name: code-intelligence
4
- description: "Route codebase-structure questions (who calls X, where is this used, what imports, change-impact) to an existing code-graph first: cheaper, never more precise; grep stays routine. Also 'call graph'."
4
+ description: "Route codebase-structure questions (who calls X, where used, change-impact) to an existing code-graph first: impact, tests-for, dead cheaper, never more precise; grep routine. Also 'call graph'."
5
5
  domain: engineering
6
6
  workspaces:
7
7
  - engineering
@@ -182,6 +182,84 @@ consumer-shipped SCIP index. Literal-string probes are reported as a separate
182
182
  cannot answer them at all, which is where grep stays necessary rather than a
183
183
  defect in the engine.
184
184
 
185
+ ## Staleness delivery — which hosts get it for free, and which do not
186
+
187
+ Migrated verbatim from `external-code-graph-interop` so the obligation stays in
188
+ the rule and the per-host delivery detail is paid only on activation.
189
+
190
+ On a host with a verified `pre_tool_use` contract, the `code-graph-context`
191
+ concern supplies this for free: once per session, on the first search or
192
+ code read, it delivers the graph's state as structured `additionalContext` —
193
+ `code-graph: fresh` or `code-graph: N commit(s) behind`. It is silent when no
194
+ graph exists, so hearing nothing is not evidence that the graph is fresh.
195
+
196
+ **On every other host that carrier does not exist**, and this section is the
197
+ delivery: run `agent-config code-graph detect --format json` before trusting a
198
+ relationship answer, and say which state you got. Which hosts those are is
199
+ `agent-config hooks:status` — resolved from the platform table, never guessed
200
+ from the host's name.
201
+
202
+ Either way the disposition is the same: `behind:N` → `agent-config code-graph
203
+ refresh` first, or use grep and say so. This is a freshness obligation, not an
204
+ ordering claim; the rule's query-first ordering still governs which source to
205
+ reach for.
206
+
207
+ ## The four gate verbs — a diff, not a symbol (2026-09-08)
208
+
209
+ `query` / `affected` / `path` / `explain` answer a question about a SYMBOL.
210
+ Four more answer a question about a DIFF, and they are documented here rather
211
+ than in § Procedure for a mechanical reason worth stating: step 4.3 of
212
+ `road-to-a-graph-that-is-shipped` verifies that this file's line 164 — the
213
+ **No class is graph-first** sentence — is unchanged, and inserting anything
214
+ above it moves that line. So the ordering claim K5 protects stays byte-fixed
215
+ and the new material sits below it.
216
+
217
+ Each of the four walks only edges whose resolution mechanism is a stated fact
218
+ (never a repo-wide same-name guess, never an untyped receiver), and each prints
219
+ the mechanisms it accepted, the mechanisms it refused, and the graph's
220
+ staleness — so a narrow answer is distinguishable from a decoupled one:
221
+
222
+ - `agent-config code-graph impact --diff <rev>` — callers, dependents and test
223
+ files reachable from the changed symbols, plus the producing edges and a
224
+ minimal read set.
225
+ - `agent-config code-graph tests-for <symbol>` — the test files that import it.
226
+ An empty list is a finding, not an error.
227
+ - `agent-config code-graph untested --diff <rev>` — changed symbols that no test
228
+ file imports.
229
+ - `agent-config code-graph dead [--entry-points F | --accept-missing-exports]` —
230
+ symbols with no accepted reference that no declared entry point names. It
231
+ **refuses** rather than answering while an entry-point source cannot be read:
232
+ this engine records no exportedness, so without a supplied list an
233
+ exported-but-unimported symbol is indistinguishable from a dead one, and a
234
+ confident false "dead" invites a deletion the graph cannot justify. Nothing it
235
+ lists is a deletion recommendation.
236
+
237
+ These answers reach an agent over MCP without shelling out, and the mapping is
238
+ **not** one tool per verb — corrected after an independent review found this
239
+ paragraph claiming "the same five answers" directly after a list of four:
240
+
241
+ | MCP tool | answers |
242
+ |---|---|
243
+ | `graph_impact` | `impact --diff`, **and** `untested --diff` via `untested_only: true` |
244
+ | `graph_tests_for` | `tests-for` |
245
+ | `graph_dead` | `dead` |
246
+ | `graph_query` | `query` |
247
+ | `graph_path` | `path` |
248
+
249
+ `untested` has no tool of its own; it is a flag on `graph_impact`, because the
250
+ two answer the same question over the same diff and a sixth tool would have cost
251
+ standing context for a boolean. `graph_impact` is the only one that is not
252
+ read-only — it runs `git diff --name-only` to resolve its rev — and
253
+ `graph_dead`'s refusal arrives as `status: "refused"`, never as `status: "ok"`
254
+ with an empty list.
255
+
256
+ **No ordering claim is added here, and no measurement claim either.** These
257
+ verbs are cheaper than reconstructing the same relationship by hand — that is a
258
+ claim about the ALTERNATIVE being a manual reconstruction, not about grep.
259
+ Nothing on this page says they beat grep, none of the four appears in the v2
260
+ benchmark corpus (which measures `callers`, `transitive-impact`, `path-between`
261
+ and `references`), and § Measured twice still governs that question.
262
+
185
263
  ## Do NOT
186
264
 
187
265
  - Do NOT rebuild a **fresh** consumer-shipped index — query it (interop
@@ -199,3 +277,6 @@ defect in the engine.
199
277
  discipline; the graph is one evidence source, still confirmed against the real
200
278
  code when load-bearing.
201
279
  - `agent-config code-graph` — the CLI surface over the engine (build / query / detect / affected).
280
+ - [`discovery_graph`](../../scripts/discovery_graph.ts) — this suite's OWN
281
+ artifact relation-graph (`affected`/`explain`). The external code-graph is the
282
+ *source-code* analogue; keep the two apart when answering.
@@ -68,6 +68,15 @@ returned 0, the turn closed, and the red arrived where the user found it.
68
68
  ending the turn silently on one is what the reminder exists to stop. Whether
69
69
  the reminder changes behavior is unmeasured — it ships as a carrier, not as a
70
70
  claim.
71
+ - **`ci_settle` will not answer for a head that stopped mattering.** Since
72
+ 2026-09-08 it reads the PR's `state` and compares its recorded head against
73
+ `git ls-remote` — before the wait and again at verdict time — and exits 2 with
74
+ a reason when the PR is merged, closed, or record-behind-branch. A green names
75
+ the head it is about. The measured reason: a merged PR's rollup kept answering
76
+ with its merge-time checks, so the tool reported `SETTLED GREEN — 40 check(s)`
77
+ for a commit that had zero check runs. The check does not apply to a fork PR
78
+ whose ref is not under this `origin`, and the line says so instead of claiming
79
+ it passed.
71
80
  - **Neither reaches a host without the slot.** `agent-config hooks:status`
72
81
  answers which slots are bound where you actually are; `post_tool_use` is
73
82
  unbound on windsurf and copilot, and there the settle obligation is
@@ -224,6 +224,23 @@ procedure when [`roadmap-management`](../roadmap-management/SKILL.md)
224
224
  spawns a follow-up). Bare `[~]` / `[-]` is allowed; annotated is
225
225
  preferred.
226
226
 
227
+ #### A prohibition-shaped step closes with `[x]`
228
+
229
+ A step whose content is a **prohibition** (*"Do not build the enforcement"*) has
230
+ no artifact to point at. `[~]` invents receiver work nobody owes, `[-]` mislabels
231
+ restraint as cancellation, `[ ]` makes an honoured bounded obligation
232
+ unarchivable. It closes with **`[x]`** — the obligation was discharged, and `[x]`
233
+ never required that something was created. Its `verify:` must name every
234
+ implementation, registration and semantically-equivalent surface (a structural
235
+ check, not one literal grep, which misses aliases and generated code); **fail if
236
+ an expected search root is missing**, checked BEFORE the absence check, because a
237
+ glob over a vanished directory returns nothing and reads as success; scope the
238
+ claim to the branch diff — *"this change introduced no enforcement"*, never the
239
+ unprovable *"enforcement exists nowhere"*; and be re-run at archival. Not for a
240
+ prohibition meant to hold indefinitely — that belongs in a rule, test or linter,
241
+ because a closed step stops watching. Council convention, 2026-09-08 (2 seats,
242
+ convergent); falsified if tooling defines `[x]` as requiring a positive mutation.
243
+
227
244
  ### 7. Follow-up roadmaps spawn from deferred items — frontmatter shape
228
245
 
229
246
  When a parent roadmap closes with `[~]` items, the
@@ -51,6 +51,42 @@ radius, spacing, shadow, font-size to a configured token. If the design hands yo
51
51
  (`bg-[#3B82F6]`, `mt-[17px]`) are a smell — accept only with a
52
52
  one-line comment naming the design source.
53
53
 
54
+ **That paragraph is written for greenfield, and artifact-bound work inverts
55
+ it.** When a provided finished design is the spec
56
+ ([`design-fidelity`](../../rules/design-fidelity.md)), `#3B82F6` is a decision
57
+ somebody already made and `bg-blue-500` is a guess about it. Three obligations
58
+ follow, and the third is the one this skill used to get wrong:
59
+
60
+ 1. **Do not snap.** Replacing the artifact's value with the nearest configured
61
+ token is the deviation the rule's Iron Law forbids — *"NEVER SWAP … SPACING,
62
+ OR COLOUR"* without explicit confirmation. An artifact-derived exact value is
63
+ not a smell here: it *is* the spec, and the source-naming comment the
64
+ paragraph above asks for is what records it.
65
+ 2. **Translate once, not per call site.** Where the artifact's literal genuinely
66
+ needs to live in the project's system, add **one** named project token
67
+ carrying that exact value and use it everywhere — one token the project owns
68
+ beats N approximations of the same colour. That is a token duty, not a
69
+ deviation: the value does not change.
70
+ 3. **Reconcile as a proposal, never autonomously.** Report each value's
71
+ distance to the nearest project token on the `Reconciled:` line below, and
72
+ let the human decide. Writing a *different* project value because the
73
+ difference looks small is exactly the unconfirmed swap (1) rules out — the
74
+ mode table at `design-fidelity.md:117-121` grants no visibility exemption,
75
+ and `structural` grants only the filling of a spec that is genuinely
76
+ **silent**, which an artifact stating `#3B82F6` is not.
77
+
78
+ **Why not "just approximate within tolerance", which is the eventual intent:**
79
+ that needs a tolerance to exist. There is none — no `reconcile`, `tolerance`,
80
+ `approximat` or `nearest` in the rule or its guideline — and both the threshold
81
+ and whether approximation is autonomous by default are owner decisions, tracked
82
+ as `blocker: approximation-tolerance` and `blocker: fidelity-default-flip` on
83
+ `road-to-design-intent-conformance`. Until they land, a skill granting that
84
+ autonomy would be re-writing the rule from underneath it.
85
+
86
+ Structure, controls, icons, grid and breakpoints are never this skill's to
87
+ adjust; those stay 1:1 with the artifact and belong to the rule, not to a
88
+ utility-class decision.
89
+
54
90
  Token authoring (DTCG 3-layer model, CSS-var/Tailwind generation) lives
55
91
  in [`design-tokens`](../design-tokens/SKILL.md); its
56
92
  `tokens.ts validate --dir <path>` is the **single token-discipline
@@ -103,7 +139,11 @@ When reviewing or proposing styles, return:
103
139
 
104
140
  1. Token map — every colour, spacing, radius, shadow, font-size mapped
105
141
  to its configured token; arbitrary values flagged with the design
106
- source they cite.
142
+ source they cite. Artifact-bound work adds a **Reconciled** block here:
143
+ one line per value, as `<artifact value> → <kept, or the token that
144
+ carries it exactly> (<distance to the nearest project token>)`. This is
145
+ the destination "report the distance" means; without it the obligation
146
+ has nowhere to land and is unobservable in the deliverable.
107
147
  2. Class list — ordered (layout → box-model → typography → colour →
108
148
  state → responsive); inline-style use justified per element.
109
149
  3. Extraction + risk call-out — component / constant / `@apply` / none
@@ -115,6 +155,7 @@ Concrete shape:
115
155
  ```
116
156
  Element: <selector or component name>
117
157
  Token map: <colour/spacing/etc → config token>
158
+ Reconciled: <artifact value → kept or exact-carrying token, + distance>
118
159
  Class list: <ordered classes>
119
160
  Inline style: <only if runtime-computed; else "none">
120
161
  Extraction: <component | constant | @apply | none — reason>
@@ -128,7 +169,16 @@ Risks: <arbitrary values, !important, dark-mode gaps>
128
169
  - `dark:` variants need a token map in both modes; one-sided dark
129
170
  styling is half a feature.
130
171
  - Arbitrary values (`mt-[17px]`) survive Tailwind upgrades but
131
- break the design system; they accumulate silently.
172
+ break the design system; they accumulate silently. **Artifact-bound is the
173
+ exception, not a loophole:** a value the provided design specifies is not
174
+ accumulation, and step 1's three obligations decide it. An arbitrary value
175
+ nobody can trace to a source is still the smell this bullet is about.
176
+ - **The carrier is CSS or a utility class; the value is the design's.** Static
177
+ presentation belongs in CSS / tokens / classes — `style=` is for what only
178
+ the runtime knows (a computed width, a live transform, a measured offset).
179
+ Porting an artifact's inline `style=` into classes is therefore expected and
180
+ is not a deviation, **as long as the resolved value comes out identical**.
181
+ Changing the carrier is free; changing the number is not.
132
182
  - `@apply` inside component CSS interacts with PurgeCSS — keep it
133
183
  in files Tailwind scans, not in vendor CSS.
134
184
  - **Anti-AI-slop catalog.** The bullets below are the Tailwind-specific
@@ -629,7 +629,6 @@ the canonical narrative lives in
629
629
  | `hooks.injection_scan.enabled` | `true`, `false` | `false` | PostToolUse prompt-injection scanner: scans tool output for injection signatures and warns in context (exit 2) — never blocks. |
630
630
  | `hooks.rtk_wrap.enabled` | `true`, `false` | `false` | PreToolUse RTK-wrap nudge: when `rtk` is on PATH, warns (exit 2, never blocks) to re-run a verbose CLI command wrapped with rtk. |
631
631
  | `hooks.design_slop.enabled` | `true`, `false` | `false` | PreToolUse anti-slop nudge: runs the `lint_design_slop` registry against about-to-be-written UI content and warns (exit 2, never blocks) on P0/P1 aesthetic tells. |
632
- | `hooks.code_graph.enabled` | `true`, `false` | `false` | PreToolUse code-graph nudge (deprecated — honest null 2026-07-28): when a code-graph index exists, warns once per session to query the graph before grep. Requires manually installing the ABI-locked parser pair. |
633
632
  | `pipelines.skill_improvement` | `true`, `false` | `true` | When `true`: propose learning capture after meaningful tasks. When `false`: silent. Included in every profile except `custom`. |
634
633
  | `roadmap.skip_pre_run_gate` | `true`, `false` | `true` | When `true` (default): `/roadmap:process-step\|phase\|full` skips the interactive pre-run summary and starts the loop immediately — the resolved roadmap, cadence, and council are surfaced inline so an unwanted pick can still be aborted. When `false`: the loop shows the pre-run summary with numbered options (Go / Different roadmap / Different scope / Toggle council / Abort) and waits. The gate is always shown — regardless of this flag — when the roadmap is ambiguous (multiple active, none named) or a scope / cadence conflict has no sensible default. |
635
634
  | `roadmap.quality_cadence` | `end_of_roadmap`, `per_phase`, `per_step` | `end_of_roadmap` | When `/roadmap:process-step|phase|full` runs the project's quality pipeline — only relevant when `quality.local_auto_run` is `true`; when it is `false` (the default) local pipeline runs are suppressed at every cadence and remote CI is the gate. Default skips per-step / per-phase runs and gates only the final archival. `per_phase` runs once after every phase; `per_step` is the legacy verbose mode. Step checkboxes and the dashboard are always updated regardless. |
@@ -39,7 +39,7 @@ schema_version: 1
39
39
  # CI guard: a release bump of `package.json` must update this value
40
40
  # in lockstep — see scripts/check_template_pin_drift.ts (road-to-
41
41
  # portable-runtime-and-update-check P3.3).
42
- agent_config_version: "14.21.0"
42
+ agent_config_version: "14.23.0"
43
43
 
44
44
  # --- Project identity ---
45
45
  project:
@@ -73,7 +73,7 @@ export const REGISTRY = [
73
73
  { name: 'affected', disposition: 'delegate', synopsis: 'Artefacts related to <artefact> via the discovery relation-graph (BFS).' },
74
74
  { name: 'graph-explain', disposition: 'delegate', synopsis: 'Seed on a <concept>, expand 2 hops over the discovery relation-graph with a node budget.' },
75
75
  { name: 'benchmark', disposition: 'delegate', synopsis: 'Report context-token reduction vs the full always-loaded projection.' },
76
- { name: 'code-graph', disposition: 'delegate', synopsis: 'Deterministic code-graph engine: build|detect|query|affected|path|explain|validate.' },
76
+ { 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.' },
77
77
  { name: 'hooks:install', disposition: 'delegate', synopsis: 'Install the combined pre-commit hook.' },
78
78
  { name: 'hooks:status', disposition: 'delegate', synopsis: 'Print the runtime hook matrix (per-platform install + bindings).' },
79
79
  { name: 'hooks:doctor', disposition: 'delegate', synopsis: 'Diagnose hook health: concerns, posture, missing trampolines (read-only).' },
@@ -0,0 +1,8 @@
1
+ import { createRequire as __acCreateRequire } from 'node:module'; const require = globalThis.require ?? __acCreateRequire(import.meta.url);
2
+ import {
3
+ isCliEntry
4
+ } from "./chunk-5EK5WQN6.js";
5
+ import "./chunk-JO25G5H7.js";
6
+ export {
7
+ isCliEntry
8
+ };
@@ -0,0 +1,170 @@
1
+ import { createRequire as __acCreateRequire } from 'node:module'; const require = globalThis.require ?? __acCreateRequire(import.meta.url);
2
+
3
+ // src/scripts/_lib/pin_resolver.ts
4
+ import { spawnSync } from "node:child_process";
5
+ import * as fs from "node:fs";
6
+ import * as path from "node:path";
7
+ import { fileURLToPath, pathToFileURL } from "node:url";
8
+ var PACKAGE_NAME = "@event4u/agent-config";
9
+ var PIN_KEY = "agent_config_version";
10
+ var NO_REEXEC_ENV = "AGENT_CONFIG_NO_PIN_REEXEC";
11
+ var REEXEC_DEPTH_ENV = "AGENT_CONFIG_PIN_REEXEC_DEPTH";
12
+ function _normalize(version) {
13
+ return version.trim().replace(/^v+/, "");
14
+ }
15
+ async function read_pin(cwd, options = {}) {
16
+ let settings;
17
+ try {
18
+ let loader = options.settings_loader;
19
+ if (loader === void 0) {
20
+ const specifier = "./agent_settings";
21
+ const mod = await import(specifier);
22
+ if (typeof mod.load_agent_settings !== "function") {
23
+ return null;
24
+ }
25
+ loader = mod.load_agent_settings;
26
+ }
27
+ settings = await loader({ cwd });
28
+ } catch {
29
+ return null;
30
+ }
31
+ const raw = settings[PIN_KEY];
32
+ if (typeof raw !== "string") {
33
+ return null;
34
+ }
35
+ const pin = raw.trim();
36
+ return pin || null;
37
+ }
38
+ function should_reexec(pin, installed, options = {}) {
39
+ const env = options.env ?? process.env;
40
+ if (env[NO_REEXEC_ENV] === "1") {
41
+ return false;
42
+ }
43
+ if (env[REEXEC_DEPTH_ENV] === "1") {
44
+ return false;
45
+ }
46
+ if (!pin) {
47
+ return false;
48
+ }
49
+ if (!installed) {
50
+ return false;
51
+ }
52
+ return _normalize(pin) !== _normalize(installed);
53
+ }
54
+ function build_reexec_argv(pin, argv) {
55
+ return ["npx", "--yes", `${PACKAGE_NAME}@${_normalize(pin)}`, ...argv];
56
+ }
57
+ function _which(cmd) {
58
+ const path_var = process.env.PATH ?? "";
59
+ const exts = process.platform === "win32" ? (process.env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD").split(";") : [""];
60
+ for (const dir of path_var.split(path.delimiter)) {
61
+ if (!dir) {
62
+ continue;
63
+ }
64
+ for (const ext of exts) {
65
+ const candidate = path.join(dir, cmd + ext.toLowerCase());
66
+ try {
67
+ const st = fs.statSync(candidate);
68
+ if (st.isFile()) {
69
+ if (process.platform !== "win32") {
70
+ fs.accessSync(candidate, fs.constants.X_OK);
71
+ }
72
+ return candidate;
73
+ }
74
+ } catch {
75
+ }
76
+ }
77
+ }
78
+ return null;
79
+ }
80
+ function _exec_runner(npx, argv, env) {
81
+ const result = spawnSync(npx, argv.slice(1), {
82
+ env,
83
+ stdio: "inherit"
84
+ });
85
+ process.exit(result.status ?? 1);
86
+ }
87
+ async function maybe_reexec(installed, options = {}) {
88
+ const cwd = options.cwd ?? process.cwd();
89
+ const argv = options.argv ?? process.argv.slice(1);
90
+ const env = options.env ?? process.env;
91
+ const pin_reader = options.pin_reader ?? ((c) => read_pin(c));
92
+ const which = options.which ?? _which;
93
+ const pin = await pin_reader(cwd);
94
+ if (!should_reexec(pin, installed, { env })) {
95
+ return null;
96
+ }
97
+ if (pin == null) {
98
+ throw new Error("maybe_reexec: pin narrowed to null after should_reexec");
99
+ }
100
+ const npx = which("npx");
101
+ if (!npx) {
102
+ return null;
103
+ }
104
+ const new_argv = build_reexec_argv(pin, argv.length > 0 ? argv.slice(1) : []);
105
+ const child_env = { ...env };
106
+ child_env[REEXEC_DEPTH_ENV] = "1";
107
+ const runner = options.runner ?? null;
108
+ if (runner === null) {
109
+ return _exec_runner(npx, new_argv, child_env);
110
+ }
111
+ return runner(npx, new_argv, child_env);
112
+ }
113
+ function _parse_cli(argv) {
114
+ let cwd = process.cwd();
115
+ let installed = "";
116
+ let forward = [];
117
+ let i = 0;
118
+ while (i < argv.length) {
119
+ const token = argv[i];
120
+ if (token === "--cwd" && i + 1 < argv.length) {
121
+ cwd = argv[i + 1];
122
+ i += 2;
123
+ } else if (token === "--installed" && i + 1 < argv.length) {
124
+ installed = argv[i + 1];
125
+ i += 2;
126
+ } else if (token === "--") {
127
+ forward = argv.slice(i + 1);
128
+ break;
129
+ } else {
130
+ i += 1;
131
+ }
132
+ }
133
+ return { cwd, installed, forward };
134
+ }
135
+ function _isCliEntry() {
136
+ if (process.argv[1] === void 0) {
137
+ return false;
138
+ }
139
+ if (true) {
140
+ if (path.basename(process.argv[1], ".js") === "pin_resolver") {
141
+ return true;
142
+ }
143
+ }
144
+ const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
145
+ if (import.meta.url === argvUrl) {
146
+ return true;
147
+ }
148
+ try {
149
+ const here = fs.realpathSync(fileURLToPath(import.meta.url));
150
+ const argv = fs.realpathSync(path.resolve(process.argv[1]));
151
+ return here === argv;
152
+ } catch {
153
+ return false;
154
+ }
155
+ }
156
+ if (_isCliEntry()) {
157
+ const { cwd, installed, forward } = _parse_cli(process.argv.slice(2));
158
+ const child_argv = ["agent-config", ...forward];
159
+ await maybe_reexec(installed, { cwd, argv: child_argv });
160
+ }
161
+ export {
162
+ NO_REEXEC_ENV,
163
+ PACKAGE_NAME,
164
+ PIN_KEY,
165
+ REEXEC_DEPTH_ENV,
166
+ build_reexec_argv,
167
+ maybe_reexec,
168
+ read_pin,
169
+ should_reexec
170
+ };
@@ -0,0 +1,8 @@
1
+ import { createRequire as __acCreateRequire } from 'node:module'; const require = globalThis.require ?? __acCreateRequire(import.meta.url);
2
+ import {
3
+ run_archival_sweep
4
+ } from "./chunk-YWVXLR44.js";
5
+ import "./chunk-JO25G5H7.js";
6
+ export {
7
+ run_archival_sweep
8
+ };