@aiwg/cli 2026.10.14 → 2026.10.16

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 (210) hide show
  1. package/agentic/code/addons/aiwg-utils/rules/anti-laziness.core.md +13 -0
  2. package/agentic/code/addons/aiwg-utils/rules/anti-laziness.md +118 -0
  3. package/agentic/code/providers/pi/aiwg-bridge.ts +45 -7
  4. package/dist/src/artifacts/citation-parser.js +7 -6
  5. package/dist/src/artifacts/corpus-tools/citation-densify.js +4 -2
  6. package/dist/src/artifacts/corpus-tools/cli.js +37 -0
  7. package/dist/src/artifacts/corpus-tools/discovery-log.js +27 -25
  8. package/dist/src/artifacts/corpus-tools/expand-cli.js +90 -0
  9. package/dist/src/artifacts/corpus-tools/expand-dates.js +107 -0
  10. package/dist/src/artifacts/corpus-tools/expand-queue.js +41 -0
  11. package/dist/src/artifacts/corpus-tools/expand-review.js +104 -0
  12. package/dist/src/artifacts/corpus-tools/expand-state.js +56 -0
  13. package/dist/src/artifacts/corpus-tools/expand.js +124 -0
  14. package/dist/src/artifacts/corpus-tools/induction-audit.js +7 -6
  15. package/dist/src/artifacts/corpus-tools/integrity-scan.js +3 -3
  16. package/dist/src/artifacts/corpus-tools/radar-shared.js +7 -9
  17. package/dist/src/artifacts/corpus-tools/ref-files.js +11 -0
  18. package/dist/src/artifacts/corpus-tools/resolve-cli.js +99 -0
  19. package/dist/src/artifacts/corpus-tools/resolve-corpus.js +41 -0
  20. package/dist/src/artifacts/corpus-tools/resolve.js +119 -0
  21. package/dist/src/artifacts/corpus-tools/retrieval-lab.js +2 -1
  22. package/dist/src/artifacts/corpus-tools/sidecar-lint.js +4 -4
  23. package/dist/src/artifacts/corpus-tools/sidecar-repair.js +2 -1
  24. package/dist/src/artifacts/corpus-views/ref-parser.js +3 -17
  25. package/dist/src/artifacts/graph-query.js +5 -3
  26. package/dist/src/artifacts/hybrid-query.js +11 -2
  27. package/dist/src/artifacts/index-refresh.js +2 -0
  28. package/dist/src/cli/handlers/daemon.js +17 -1
  29. package/dist/src/cli/handlers/doctor-args.js +45 -0
  30. package/dist/src/cli/handlers/doctor-help.js +8 -3
  31. package/dist/src/cli/handlers/index.js +2 -2
  32. package/dist/src/cli/handlers/models-resource-sample.js +10 -0
  33. package/dist/src/cli/handlers/models.js +3 -2
  34. package/dist/src/cli/handlers/regenerate.js +8 -16
  35. package/dist/src/cli/handlers/sessions.js +7 -7
  36. package/dist/src/cli/handlers/subcommands.js +8 -0
  37. package/dist/src/cli/handlers/update.js +157 -0
  38. package/dist/src/cli/handlers/use.js +14 -4
  39. package/dist/src/cli/handlers/utilities.js +3 -586
  40. package/dist/src/cli/handlers/utility-doctor.js +412 -0
  41. package/dist/src/cli/services/deployment-verification.js +0 -1
  42. package/dist/src/config/aiwg-config.js +2 -1
  43. package/dist/src/config/authorization-cli.js +7 -3
  44. package/dist/src/config/dispatch-thresholds-runtime.d.mts +3 -2
  45. package/dist/src/config/dispatch-thresholds-runtime.mjs +17 -7
  46. package/dist/src/config/framework-aliases.js +12 -0
  47. package/dist/src/config/host-resource-report.d.mts +19 -0
  48. package/dist/src/config/host-resource-report.mjs +80 -0
  49. package/dist/src/config/host-resource-runtime.d.mts +34 -0
  50. package/dist/src/config/host-resource-runtime.mjs +293 -0
  51. package/dist/src/config/installed-selection.js +22 -0
  52. package/dist/src/config/worker-context.js +33 -4
  53. package/dist/src/config/worker-invocation-marker.d.mts +1 -0
  54. package/dist/src/config/worker-invocation-marker.mjs +2 -0
  55. package/dist/src/decision/heldout/access.js +74 -0
  56. package/dist/src/decision/heldout/calibration.js +1 -0
  57. package/dist/src/decision/heldout/collector.js +9 -2
  58. package/dist/src/effects/verifiers/file.js +22 -5
  59. package/dist/src/extensions/claude-attribution.js +82 -0
  60. package/dist/src/extensions/claude-hooks-installer.js +115 -69
  61. package/dist/src/extensions/commands/daemon.js +109 -0
  62. package/dist/src/extensions/commands/definitions.js +5 -89
  63. package/dist/src/features/catalog.js +1 -1
  64. package/dist/src/gates/evaluate.js +2 -2
  65. package/dist/src/gates/heldout.js +52 -0
  66. package/dist/src/gates/index.js +2 -1
  67. package/dist/src/lint/check-patterns.js +163 -0
  68. package/dist/src/lint/checks.js +268 -0
  69. package/dist/src/lint/reference-resolution.js +54 -0
  70. package/dist/src/lint/runner.js +3 -465
  71. package/dist/src/mcp/helpers.mjs +11 -1
  72. package/dist/src/memory/project-registry.js +44 -4
  73. package/dist/src/models/worker-installation-store.mjs +228 -0
  74. package/dist/src/models/worker-installation.mjs +7 -162
  75. package/dist/src/models/worker-plan.js +36 -5
  76. package/dist/src/models/wrapper-deployment.js +25 -12
  77. package/dist/src/models/wrapper-enforcement.js +47 -7
  78. package/dist/src/network-analysis/research.js +2 -1
  79. package/dist/src/policy/hitl-check.js +14 -4
  80. package/dist/src/policy/hitl-consume.js +54 -0
  81. package/dist/src/policy/hitl-receipt.js +2 -0
  82. package/dist/src/policy/hitl.js +11 -3
  83. package/dist/src/providers/provider-context-contracts.js +162 -0
  84. package/dist/src/providers/provider-definition-schema.js +136 -0
  85. package/dist/src/providers/provider-definitions.js +8 -1298
  86. package/dist/src/providers/provider-seeds-1.js +360 -0
  87. package/dist/src/providers/provider-seeds-2.js +387 -0
  88. package/dist/src/providers/provider-seeds-3.js +262 -0
  89. package/dist/src/research/clients/arxiv.js +14 -34
  90. package/dist/src/research/clients/base.js +53 -26
  91. package/dist/src/research/clients/crossref.js +9 -1
  92. package/dist/src/research/clients/semantic-scholar.js +73 -44
  93. package/dist/src/research/identity.js +117 -0
  94. package/dist/src/research/index.js +1 -0
  95. package/dist/src/research/query-cli.js +3 -87
  96. package/dist/src/research/query-options.js +87 -0
  97. package/dist/src/research/reference-match.js +135 -0
  98. package/dist/src/research/services/acquisition.js +9 -7
  99. package/dist/src/research/services/citation.js +5 -2
  100. package/dist/src/research/types.js +2 -0
  101. package/dist/src/rules/core-startup.d.mts +2 -0
  102. package/dist/src/rules/core-startup.mjs +31 -0
  103. package/dist/src/serve/mission-conductor.js +48 -4
  104. package/dist/src/sessions/adapters/grok-build-native.js +23 -0
  105. package/dist/src/sessions/adapters/grok-build.js +14 -7
  106. package/dist/src/sessions/workspace-discovery.js +5 -5
  107. package/dist/src/smiths/context-pipeline/agents-md.js +34 -0
  108. package/dist/src/smiths/context-pipeline/aiwg-md.js +19 -46
  109. package/dist/src/smiths/context-pipeline/bridge-ownership.js +50 -0
  110. package/dist/src/smiths/context-pipeline/claude-hook.js +1 -1
  111. package/dist/src/smiths/context-pipeline/code-regions.js +28 -0
  112. package/dist/src/smiths/context-pipeline/finalization.js +81 -51
  113. package/dist/src/smiths/context-pipeline/generator.js +49 -114
  114. package/dist/src/smiths/context-pipeline/managed-hook.js +11 -1
  115. package/dist/src/smiths/context-pipeline/muse-bridge.js +2 -2
  116. package/dist/src/smiths/context-pipeline/provider-policy.js +6 -12
  117. package/dist/src/smiths/context-pipeline/workspace-audit.js +299 -0
  118. package/dist/src/smiths/context-pipeline/workspace-bootstrap.js +148 -0
  119. package/dist/src/smiths/context-pipeline/workspace-context-shared.js +111 -0
  120. package/dist/src/smiths/context-pipeline/workspace-context.js +8 -1373
  121. package/dist/src/smiths/context-pipeline/workspace-doctor.js +192 -0
  122. package/dist/src/smiths/context-pipeline/workspace-document.js +201 -0
  123. package/dist/src/smiths/context-pipeline/workspace-extraction.js +205 -0
  124. package/dist/src/smiths/context-pipeline/workspace-migration.js +250 -0
  125. package/package.json +13 -2
  126. package/schemas/decision/D29Study.v10.schema.json +65 -0
  127. package/tools/agents/deploy-agents.mjs +12 -123
  128. package/tools/agents/providers/antigravity.mjs +1 -1
  129. package/tools/agents/providers/claude-post-deploy.mjs +12 -1
  130. package/tools/agents/providers/context-write.mjs +16 -0
  131. package/tools/agents/providers/grok-build.mjs +8 -5
  132. package/tools/agents/providers/hermes-skill-lifecycle.mjs +144 -0
  133. package/tools/agents/providers/hermes-startup.mjs +209 -0
  134. package/tools/agents/providers/hermes.mjs +9 -359
  135. package/tools/agents/providers/model-wrapper.mjs +5 -1
  136. package/tools/agents/providers/muse.mjs +3 -3
  137. package/tools/agents/providers/pi.mjs +4 -2
  138. package/tools/agents/providers/rule-delivery-surface.mjs +332 -0
  139. package/tools/agents/providers/rule-delivery.mjs +20 -1346
  140. package/tools/agents/providers/rule-deployment-commit.mjs +144 -0
  141. package/tools/agents/providers/rule-deployment-prepare.mjs +452 -0
  142. package/tools/agents/providers/rule-deployment-state.mjs +300 -0
  143. package/tools/agents/providers/rule-presentation.mjs +13 -4
  144. package/tools/agents/providers/rule-projection.mjs +119 -0
  145. package/tools/agents/providers/rule-startup.mjs +70 -0
  146. package/tools/agents/providers/stale-artifact-prune.mjs +128 -0
  147. package/tools/agents/providers/warp.mjs +2 -2
  148. package/tools/agents/providers/windsurf.mjs +11 -57
  149. package/tools/daemon/README.md +511 -0
  150. package/tools/daemon/adapters/base-adapter.mjs +84 -0
  151. package/tools/daemon/adapters/webhook-adapter.mjs +107 -0
  152. package/tools/daemon/agent-supervisor.mjs +299 -0
  153. package/tools/daemon/automation-engine.mjs +310 -0
  154. package/tools/daemon/autonomous-engine.mjs +346 -0
  155. package/tools/daemon/behavior-loader.mjs +316 -0
  156. package/tools/daemon/behavior.mjs +174 -0
  157. package/tools/daemon/concierge/intent-router.mjs +401 -0
  158. package/tools/daemon/concierge/orchestrator.mjs +272 -0
  159. package/tools/daemon/concierge/response-translator.mjs +462 -0
  160. package/tools/daemon/config.mjs +377 -0
  161. package/tools/daemon/cron-scheduler.mjs +178 -0
  162. package/tools/daemon/daemon-main.mjs +1169 -0
  163. package/tools/daemon/event-router.mjs +84 -0
  164. package/tools/daemon/file-watcher.mjs +383 -0
  165. package/tools/daemon/index.mjs +1181 -0
  166. package/tools/daemon/init-profile.mjs +124 -0
  167. package/tools/daemon/ipc-client.mjs +197 -0
  168. package/tools/daemon/ipc-ops-handlers.mjs +236 -0
  169. package/tools/daemon/ipc-server.mjs +275 -0
  170. package/tools/daemon/maintenance-owner.mjs +79 -0
  171. package/tools/daemon/memory-manager.mjs +386 -0
  172. package/tools/daemon/message-router.mjs +194 -0
  173. package/tools/daemon/provider-watcher.mjs +585 -0
  174. package/tools/daemon/pty-adapter.mjs +420 -0
  175. package/tools/daemon/repl-chat.mjs +359 -0
  176. package/tools/daemon/resource-bounds.mjs +88 -0
  177. package/tools/daemon/sandbox-transport.mjs +295 -0
  178. package/tools/daemon/scheduled-task-runner.mjs +535 -0
  179. package/tools/daemon/task-store.mjs +450 -0
  180. package/tools/daemon/tmux-manager.mjs +324 -0
  181. package/tools/daemon/update-policy.mjs +517 -0
  182. package/tools/daemon/web-server.mjs +399 -0
  183. package/tools/daemon/web-ui/index.html +585 -0
  184. package/tools/daemon/web-ui/styles.css +156 -0
  185. package/tools/docker/Dockerfile.daemon +35 -0
  186. package/tools/docker/container-manager.mjs +291 -0
  187. package/tools/messaging/adapter-registry.mjs +230 -0
  188. package/tools/messaging/adapters/base.mjs +326 -0
  189. package/tools/messaging/adapters/discord.mjs +462 -0
  190. package/tools/messaging/adapters/slack.mjs +402 -0
  191. package/tools/messaging/adapters/telegram.mjs +552 -0
  192. package/tools/messaging/chat-handler.mjs +297 -0
  193. package/tools/messaging/command-router.mjs +269 -0
  194. package/tools/messaging/event-bus.mjs +199 -0
  195. package/tools/messaging/index.mjs +456 -0
  196. package/tools/messaging/message-formatter.mjs +320 -0
  197. package/tools/messaging/room-manager.mjs +277 -0
  198. package/tools/messaging/types.mjs +94 -0
  199. package/tools/plugin/plugin-links.mjs +3 -0
  200. package/tools/providers/pi-bridge-policy.mjs +4 -0
  201. package/tools/ralph-external/daemon-supervisor.mjs +394 -0
  202. package/tools/ralph-external/lib/behavior-registry.mjs +270 -0
  203. package/tools/ralph-external/lib/worker-invocation-processes.mjs +3 -2
  204. package/tools/ralph-external/lib/worker-isolation-args.mjs +217 -0
  205. package/tools/ralph-external/lib/worker-isolation-status.mjs +19 -0
  206. package/tools/ralph-external/lib/worker-isolation.mjs +11 -237
  207. package/tools/ralph-external/lib/worker-overflow.mjs +10 -2
  208. package/tools/ralph-external/lib/worker-unit-cleanup.mjs +72 -0
  209. package/tools/ralph-external/session-launcher.mjs +7 -7
  210. package/tools/scripts/resource-preflight.mjs +3 -242
@@ -0,0 +1,144 @@
1
+ /** Preserve Hermes curator registration and migrate the legacy skill directory. */
2
+ import fs from 'node:fs';
3
+ import path from 'node:path';
4
+ export function createHermesSkillLifecycle({ getHermesHome, paths, kernelSkillsPath }) {
5
+ /**
6
+ * Hermes v0.12.0+ ships an autonomous Curator (`agent/curator.py`) that
7
+ * grades and archives skills on a 7-day cycle. Skills are excluded from
8
+ * archival if either:
9
+ * (a) they appear in `~/.hermes/skills/.bundled_manifest` (one name per
10
+ * line, format `name:tag`), or
11
+ * (b) their path's first component starts with `.` (verified at
12
+ * `tools/skill_usage.py:241-243`).
13
+ *
14
+ * AIWG standard skills under `~/.hermes/skills/.aiwg/...` are protected
15
+ * by (b) automatically. AIWG kernel skills land at the top level
16
+ * (`~/.hermes/skills/<name>/SKILL.md`) and need explicit (a) registration.
17
+ *
18
+ * This function writes/updates the bundled manifest with the kernel-skill
19
+ * names AIWG owns. Idempotent: existing entries (from Hermes's own bundle
20
+ * or other tools) are preserved.
21
+ */
22
+ function updateBundledManifest(kernelSkillNames, opts) {
23
+ const { dryRun, quiet } = opts;
24
+ const manifestPath = path.join(opts.kernelSkillsPath || kernelSkillsPath, '.bundled_manifest');
25
+ const aiwgTag = 'aiwg-managed';
26
+
27
+ // Read existing manifest (if any) and split into "ours" vs "theirs"
28
+ let existing = '';
29
+ try {
30
+ existing = fs.readFileSync(manifestPath, 'utf-8');
31
+ } catch {
32
+ existing = '';
33
+ }
34
+ const theirs = [];
35
+ for (const rawLine of existing.split('\n')) {
36
+ const line = rawLine.trim();
37
+ if (!line) continue;
38
+ if (line.endsWith(`:${aiwgTag}`)) continue; // ours — drop, will re-add below
39
+ theirs.push(line);
40
+ }
41
+ const ours = kernelSkillNames.map((n) => `${n}:${aiwgTag}`);
42
+
43
+ // Stable order: theirs first (preserve operator/Hermes-bundled order), then ours
44
+ const merged = [...theirs, ...ours].join('\n') + '\n';
45
+
46
+ if (dryRun) {
47
+ if (!quiet) {
48
+ console.log(` [curator] [dry-run] Would write ${manifestPath} with ${ours.length} AIWG kernel + ${theirs.length} preserved entries`);
49
+ }
50
+ return;
51
+ }
52
+
53
+ try {
54
+ fs.mkdirSync(path.dirname(manifestPath), { recursive: true });
55
+ fs.writeFileSync(manifestPath, merged, 'utf-8');
56
+ if (!quiet) {
57
+ console.log(` [curator] Bundled manifest updated: ${ours.length} AIWG kernel skills protected (preserved ${theirs.length} pre-existing entries)`);
58
+ }
59
+ } catch (err) {
60
+ if (!quiet) {
61
+ console.log(` [curator] Warning: could not write bundled manifest: ${err.message}`);
62
+ }
63
+ }
64
+ }
65
+
66
+ // ============================================================================
67
+ // Legacy skill path migration (#1316 / S5)
68
+ // ============================================================================
69
+
70
+ /**
71
+ * Remove the legacy `~/.hermes/.aiwg/skills/` directory if it exists and the
72
+ * new path `~/.hermes/skills/.aiwg/` is populated with AIWG content.
73
+ *
74
+ * Idempotent: re-running after migration is a no-op.
75
+ *
76
+ * Safety:
77
+ * - Only removes when the new path exists and contains files
78
+ * - Skips removal if the new path is empty (avoids losing skills during
79
+ * an in-progress deploy where the new path hasn't been written yet)
80
+ * - Operates only on the documented legacy path — never touches user-managed
81
+ * directories under ~/.hermes/
82
+ */
83
+ function migrateLegacySkillPath(opts) {
84
+ const { dryRun, quiet } = opts;
85
+ // Resolve through the same HERMES_HOME contract as every other path in
86
+ // this provider (env var first, platform default otherwise): with
87
+ // HERMES_HOME set, the legacy tree lives under that root — never under
88
+ // the process home directory.
89
+ const legacyPath = opts.hermesLegacySkills || path.join(getHermesHome(), '.aiwg', 'skills');
90
+ const newPath = paths.skills;
91
+
92
+ let legacyExists = false;
93
+ try {
94
+ legacyExists = fs.statSync(legacyPath).isDirectory();
95
+ } catch {
96
+ return; // no legacy path — nothing to migrate
97
+ }
98
+ if (!legacyExists) return;
99
+
100
+ // Sanity: new path must exist and be non-empty before we remove the legacy one
101
+ let newPopulated = false;
102
+ try {
103
+ const entries = fs.readdirSync(newPath);
104
+ newPopulated = entries.length > 0;
105
+ } catch {
106
+ newPopulated = false;
107
+ }
108
+
109
+ if (!newPopulated) {
110
+ if (!quiet) {
111
+ console.log(` [migrate] Legacy skills detected at ${legacyPath}; new path not yet populated. Skipping cleanup until next deploy.`);
112
+ }
113
+ return;
114
+ }
115
+
116
+ if (dryRun) {
117
+ console.log(` [migrate] [dry-run] Would remove legacy skill path: ${legacyPath}`);
118
+ return;
119
+ }
120
+
121
+ try {
122
+ fs.rmSync(legacyPath, { recursive: true, force: true });
123
+ // Also remove the empty parent if it's now empty
124
+ const parent = path.dirname(legacyPath);
125
+ try {
126
+ const remaining = fs.readdirSync(parent);
127
+ if (remaining.length === 0) {
128
+ fs.rmdirSync(parent);
129
+ }
130
+ } catch {
131
+ // parent removal is best-effort
132
+ }
133
+ if (!quiet) {
134
+ console.log(` [migrate] Removed legacy skill path: ${legacyPath}`);
135
+ }
136
+ } catch (err) {
137
+ if (!quiet) {
138
+ console.log(` [migrate] Warning: could not remove legacy path ${legacyPath}: ${err.message}`);
139
+ }
140
+ }
141
+ }
142
+
143
+ return { updateBundledManifest, migrateLegacySkillPath };
144
+ }
@@ -0,0 +1,209 @@
1
+ /** Legacy Hermes startup compatibility; activation delivery owns current startup policy. */
2
+ import fs from 'node:fs';
3
+ import path from 'node:path';
4
+ import { listOnDemandRuleFiles, renderOnDemandRuleSection } from './base.mjs';
5
+ import { writeContextFileSync } from './context-write.mjs';
6
+
7
+ /**
8
+ * Generate a lean AGENTS.md for Hermes
9
+ *
10
+ * Hermes reaches AGENTS.md through its startup pointer on every task. Reserve
11
+ * the 19,000-character budget for bootstrap, compact core and operator context.
12
+ * See: docs/integrations/hermes-quickstart.md (Part 3)
13
+ */
14
+ // Hermes context cap is 20K chars (head-tail truncated above). Hard limit
15
+ // to leave headroom for project-specific additions and skill-discovery.
16
+ const HERMES_AGENTS_MD_HARD_CAP = 19_000;
17
+ const HERMES_AGENTS_MD_SOFT_WARN = 15_000;
18
+
19
+ /** Preserve the harness limit for operator context; kernel bodies live in rules files. */
20
+ export function assertContextBudget(content, name = 'AGENTS.md') {
21
+ if (content.length <= HERMES_AGENTS_MD_HARD_CAP) return;
22
+ throw new Error(`Hermes ${name} (${content.length} chars) exceeds hard cap of ${HERMES_AGENTS_MD_HARD_CAP}. Review wrappers and operator additions.`);
23
+ }
24
+
25
+ /**
26
+ * Top-7 CRITICAL rule directives, inlined into AGENTS.md for guaranteed
27
+ * priming on every Hermes turn (#1318 / S7; skill-discovery added #1347).
28
+ *
29
+ * The full rule bodies are reachable without MCP via `aiwg discover` and
30
+ * `aiwg show rule <name> --body`; MCP exposes the same path through `rule-list` and
31
+ * `rule-show` when configured (#1320). The bodies exceed Hermes's 20K context
32
+ * cap if inlined verbatim (anti-laziness alone was 32K chars; it now ships as a compact core body, #3450), so we inline
33
+ * compressed directives only and point to CLI/MCP for the full text.
34
+ *
35
+ * Selection criteria: rules tagged CRITICAL/HIGH enforcement level whose
36
+ * violations are silent or destructive (cost of remembering to query
37
+ * rule-show > cost of inlining the directive). skill-discovery is HIGH
38
+ * but is the linchpin of the discover-first architecture across all
39
+ * providers and is therefore inlined alongside the CRITICAL set.
40
+ */
41
+ const CRITICAL_RULE_DIRECTIVES = `## CRITICAL Rules (always apply)
42
+
43
+ These are the highest-enforcement AIWG rules. Full bodies are reachable without
44
+ MCP:
45
+ - Find rules: \`aiwg discover "rule <topic>" --type rule\`
46
+ - Fetch a rule: \`aiwg show rule <name> --body\`
47
+
48
+ If the optional MCP sidecar is configured, the same surface is available through
49
+ \`mcp_aiwg_rule_list\` and \`mcp_aiwg_rule_show\`.
50
+
51
+ ### Rule: skill-discovery (discover-first protocol)
52
+ Before declining a user request as "outside AIWG's scope" or improvising a
53
+ workflow from training data, you MUST run \`aiwg discover "<user need>"\`
54
+ against the user's need. Most AIWG skills are not in your context; they reach
55
+ you through \`aiwg discover\` + \`aiwg show <type> <name>\`. If MCP is available,
56
+ \`mcp_aiwg_discover\` and type-specific show tools are equivalent. Run discover
57
+ whenever the user mentions AIWG, a framework name (sdlc, research, forensics,
58
+ ops, marketing, security-engineering, media-curator, knowledge-base), or
59
+ capability keywords (skill, agent, command, rule, workflow).
60
+
61
+ ### Rule: no-attribution
62
+ Never add AI-tool attribution to commits, PRs, code, or docs. No \`Co-Authored-By:\`,
63
+ no "Generated with", no "Written by [AI tool]". The AI is a tool; tools don't sign
64
+ their output. Applies to ALL platforms (Claude, Codex, Copilot, Cursor, etc.).
65
+
66
+ ### Rule: citation-policy
67
+ Never fabricate citations, DOIs, URLs, or page numbers. Only cite sources that
68
+ exist in the research corpus (.aiwg/research/sources/). Match claim strength
69
+ to evidence quality (GRADE): HIGH = "demonstrates"; MODERATE = "suggests";
70
+ LOW = "limited evidence"; VERY LOW = "anecdotal". Document research gaps in
71
+ .aiwg/research/TODO.md when no source supports a claim.
72
+
73
+ ### Rule: token-security
74
+ Never hard-code tokens, API keys, or secrets in source files or commit messages.
75
+ Never pass tokens as CLI arguments (visible in process list). Never echo or log
76
+ token values. Load from secure files (mode 600) or environment variables. Use
77
+ heredoc scope for multi-step operations so tokens don't persist beyond use.
78
+ Token files must NEVER be tracked in git (.gitignore enforced).
79
+
80
+ ### Rule: versioning
81
+ CalVer format: \`YYYY.M.PATCH\` (e.g., \`2026.5.3\`). NEVER use leading zeros
82
+ (\`2026.01.5\` is broken — npm semver rejects it). Tags use \`v\` prefix.
83
+ CHANGELOG must use same format. PATCH resets each month.
84
+
85
+ ### Rule: ops-safety
86
+ Detect interactive commands and flag for human execution (passwords, LUKS
87
+ passphrases, MFA — agents cannot type these). Gate destructive operations
88
+ (\`rm -rf\`, \`fdisk\`, \`mkfs\`, partition table changes) behind explicit
89
+ human confirmation. Assess blast radius before execution (CRITICAL = multi-host
90
+ / data loss; HIGH = single-host outage). Dry-run first when the tool supports it.
91
+ Never cross host boundaries without confirmation.`;
92
+
93
+ const HERMES_AGENTS_MD_FOOTER = `## Optional MCP Server Surface (\`aiwg mcp serve\`)
94
+
95
+ MCP is optional. The baseline path is file deploy + \`aiwg discover\` /
96
+ \`aiwg show\` from the CLI. MCP exposes the same AIWG catalog and execution
97
+ surface as provider-agnostic tools when configured.
98
+
99
+ **Discovery** (read-only, no project required):
100
+ - \`mcp_aiwg_discover\` — semantic search across skills/agents/commands/rules
101
+ - \`mcp_aiwg_skill_list\` / \`mcp_aiwg_skill_show\`
102
+ - \`mcp_aiwg_command_list\` / \`mcp_aiwg_command_show\`
103
+ - \`mcp_aiwg_rule_list\` / \`mcp_aiwg_rule_show\`
104
+ - \`mcp_aiwg_agent_list\` / \`mcp_aiwg_agent_show\`
105
+ - \`mcp_aiwg_template_list\` / \`mcp_aiwg_template_show\` / \`mcp_aiwg_template_render\`
106
+
107
+ **Execution** (allow-listed):
108
+ - \`mcp_aiwg_command_run\` — dispatches to any of 94 AIWG CLI commands. Destructive
109
+ commands require \`confirmed: true\`.
110
+
111
+ **Artifacts** (project-required, .aiwg/ directory):
112
+ - \`mcp_aiwg_artifact_read\` / \`mcp_aiwg_artifact_write\``;
113
+
114
+ function mergeHermesContext(file, generated, kind) {
115
+ let existing = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
116
+ existing = existing.replace(/\n?<!-- AIWG:rule-startup:start -->[\s\S]*?<!-- AIWG:rule-startup:end -->\n?/g, '');
117
+ const start = `<!-- AIWG:hermes-${kind}:start -->`;
118
+ const end = `<!-- AIWG:hermes-${kind}:end -->`;
119
+ const managed = `${start}\n${generated}\n${end}`;
120
+ if (existing.includes(start)) return existing.slice(0, existing.indexOf(start)) + managed + existing.slice(existing.indexOf(end) + end.length);
121
+ if (kind === 'context' && existing.startsWith('# AIWG Integration') && existing.includes(HERMES_AGENTS_MD_FOOTER)) {
122
+ existing = existing.slice(existing.indexOf(HERMES_AGENTS_MD_FOOTER) + HERMES_AGENTS_MD_FOOTER.length);
123
+ } else if (kind === 'routing' && existing.includes(generated)) {
124
+ existing = existing.replace(generated, '');
125
+ }
126
+ return existing ? `${existing.trimEnd()}\n\n${managed}\n` : `<!-- aiwg-managed -->\n${managed}\n`;
127
+ }
128
+
129
+ export function generateAgentsMd(agentCount, skillCount, targetDir, opts) {
130
+ if (opts.contextFiles === false || opts.ruleDelivery) return;
131
+ const { dryRun } = opts;
132
+
133
+ // Startup is reserved for rule contracts. Workflow routing, artifact catalogs,
134
+ // and the optional MCP tool inventory duplicate discover/show and consume
135
+ // Hermes's finite per-turn context before the kernel is appended.
136
+ const header = `# AIWG Integration
137
+
138
+ Skills: \`$HERMES_HOME/skills/\` (kernel), \`$HERMES_HOME/skills/.aiwg/\` (standard).
139
+ Find: \`aiwg discover "rule <topic>" --type rule\`. Fetch: \`aiwg show rule <name> --body\`.
140
+ MCP is optional; \`mcp_aiwg_rule_show\` exposes the same rule catalog.
141
+ `;
142
+
143
+ // On-demand tier (#1675): the MEDIUM/LOW rules not inlined above. Hermes has
144
+ // no scanned rule dir, so the bridge file notes the tier with fetch hints.
145
+ const onDemandSection = opts.srcRoot
146
+ ? renderOnDemandRuleSection(listOnDemandRuleFiles(opts.srcRoot))
147
+ : '';
148
+ const migrated = new Set((opts.ruleDelivery?.rules || []).filter(rule => rule.tagged).map(rule => rule.name));
149
+ const directives = CRITICAL_RULE_DIRECTIVES.split(/(?=^### Rule: )/m).filter(section => section.startsWith('### Rule: ') && !migrated.has(section.match(/^### Rule: ([^ \n]+)/)?.[1])).join('');
150
+ const sections = [header, directives];
151
+ if (onDemandSection) sections.push(onDemandSection);
152
+ // The optional tool inventory is available on demand through the CLI.
153
+ const destPath = path.join(targetDir, 'AGENTS.md');
154
+ const output = mergeHermesContext(destPath, sections.join('\n\n'), 'context');
155
+
156
+ if (!opts.ruleDelivery && !opts.deferRuleProjection) assertContextBudget(output, 'AGENTS.md');
157
+
158
+ if (dryRun) {
159
+ console.log(`[dry-run] Would write AGENTS.md (${output.length} chars, ${Math.round(output.length / 4)} tokens estimated)`);
160
+ } else {
161
+ writeContextFileSync(destPath, output, 'utf8');
162
+ const charCount = output.length;
163
+ const tokenEstimate = Math.round(charCount / 4);
164
+ let budgetNote;
165
+ if (charCount > HERMES_AGENTS_MD_SOFT_WARN) {
166
+ budgetNote = `⚠ ${charCount} chars — above soft warn (${HERMES_AGENTS_MD_SOFT_WARN}); below hard cap (${HERMES_AGENTS_MD_HARD_CAP})`;
167
+ } else {
168
+ budgetNote = `✓ within budget (cap: ${HERMES_AGENTS_MD_HARD_CAP})`;
169
+ }
170
+ console.log(` Created AGENTS.md (${charCount} chars, ~${tokenEstimate} tokens, ${budgetNote})`);
171
+ }
172
+
173
+ return 1;
174
+ }
175
+
176
+ /**
177
+ * Generate `.hermes.md` thin pointer at the project root (#1319 / S8).
178
+ *
179
+ * Hermes loads `.hermes.md` with priority over `AGENTS.md` (first-match-wins
180
+ * at `agent/prompt_builder.py:1417-1456`). The pointer is short so the
181
+ * actual context payload remains in AGENTS.md which is shared with other
182
+ * tools (Claude Code, Codex, etc.).
183
+ */
184
+ export function generateHermesMd(targetDir, opts) {
185
+ if (opts.contextFiles === false || opts.ruleDelivery) return;
186
+ const { dryRun } = opts;
187
+ const body = `# Hermes Routing
188
+
189
+ AIWG project context lives in \`AGENTS.md\` (this file is a thin Hermes pointer).
190
+
191
+ **Routing**: see \`AGENTS.md\` in this directory.
192
+ **MCP**: AIWG is reachable via \`mcp_aiwg_*\` tools.
193
+ **Skills**: kernel skills at \`$HERMES_HOME/skills/\`; standard skills at \`$HERMES_HOME/skills/.aiwg/\`.
194
+ When unset, \`HERMES_HOME\` defaults to the platform-native Hermes home.
195
+
196
+ Hermes loads only \`.hermes.md\` when it is present (first-match-wins). Keep
197
+ this file minimal; its routing instruction tells the agent to read \`AGENTS.md\`
198
+ when the full AIWG project context is needed.
199
+ `;
200
+ const destPath = path.join(targetDir, '.hermes.md');
201
+ if (dryRun) {
202
+ console.log(`[dry-run] Would write .hermes.md (${body.length} chars)`);
203
+ } else {
204
+ writeContextFileSync(destPath, mergeHermesContext(destPath, body, 'routing'), 'utf8');
205
+ console.log(` Created .hermes.md (${body.length} chars)`);
206
+ }
207
+ return 1;
208
+ }
209
+