@aiwg/cli 2026.10.12 → 2026.10.15

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 (104) 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 +44 -1
  4. package/dist/src/artifacts/corpus-tools/cli.js +32 -0
  5. package/dist/src/artifacts/corpus-tools/discovery-log.js +1 -1
  6. package/dist/src/artifacts/corpus-tools/expand-cli.js +89 -0
  7. package/dist/src/artifacts/corpus-tools/expand-queue.js +38 -0
  8. package/dist/src/artifacts/corpus-tools/expand-state.js +40 -0
  9. package/dist/src/artifacts/corpus-tools/expand.js +125 -0
  10. package/dist/src/artifacts/corpus-tools/resolve-cli.js +91 -0
  11. package/dist/src/artifacts/corpus-tools/resolve-corpus.js +41 -0
  12. package/dist/src/artifacts/corpus-tools/resolve.js +105 -0
  13. package/dist/src/cli/handlers/doctor-args.js +40 -0
  14. package/dist/src/cli/handlers/doctor-help.js +4 -2
  15. package/dist/src/cli/handlers/use-bundle-counts.js +32 -6
  16. package/dist/src/cli/handlers/use-skill-assets.js +207 -0
  17. package/dist/src/cli/handlers/use.js +30 -193
  18. package/dist/src/cli/handlers/utilities.js +5 -31
  19. package/dist/src/config/authorization-cli.js +11 -3
  20. package/dist/src/config/worker-context.js +33 -4
  21. package/dist/src/decision/context-pruning-common.js +41 -0
  22. package/dist/src/decision/context-pruning-evaluation.js +366 -0
  23. package/dist/src/decision/context-pruning-pilot.js +431 -0
  24. package/dist/src/decision/context-pruning-types.js +19 -0
  25. package/dist/src/decision/context-pruning.js +5 -847
  26. package/dist/src/decision/ensemble/contract.js +4 -24
  27. package/dist/src/decision/heldout/collector.js +1 -1
  28. package/dist/src/decision/qualification/release.js +5 -62
  29. package/dist/src/extensions/manifest.js +8 -1
  30. package/dist/src/extensions/project-local-doctor.js +78 -2
  31. package/dist/src/extensions/validation.js +10 -11
  32. package/dist/src/features/catalog.js +1 -1
  33. package/dist/src/gates/evaluate.js +5 -15
  34. package/dist/src/gates/heldout.js +42 -0
  35. package/dist/src/gates/index.js +2 -1
  36. package/dist/src/gates/upstream-ceiling.js +111 -0
  37. package/dist/src/models/provider-models.js +5 -8
  38. package/dist/src/models/worker-installation-store.mjs +228 -0
  39. package/dist/src/models/worker-installation.mjs +7 -162
  40. package/dist/src/models/wrapper-definitions.js +14 -0
  41. package/dist/src/models/wrapper-deployment.js +48 -25
  42. package/dist/src/models/wrapper-enforcement.js +72 -0
  43. package/dist/src/policy/hitl-check.js +80 -0
  44. package/dist/src/providers/provider-definitions.js +10 -10
  45. package/dist/src/research/clients/arxiv.js +10 -4
  46. package/dist/src/research/clients/base.js +5 -4
  47. package/dist/src/research/clients/crossref.js +9 -1
  48. package/dist/src/research/clients/semantic-scholar.js +73 -44
  49. package/dist/src/research/identity.js +85 -0
  50. package/dist/src/research/index.js +1 -0
  51. package/dist/src/research/reference-match.js +89 -0
  52. package/dist/src/rules/activation.d.mts +2 -0
  53. package/dist/src/rules/activation.mjs +23 -0
  54. package/dist/src/rules/core-startup.d.mts +2 -0
  55. package/dist/src/rules/core-startup.mjs +31 -0
  56. package/dist/src/skills/adapters/local.js +32 -9
  57. package/dist/src/skills/agent-skills.js +2 -0
  58. package/dist/src/skills/cli-display.js +33 -0
  59. package/dist/src/skills/cli.js +2 -26
  60. package/dist/src/skills/collision-discovery.js +84 -0
  61. package/dist/src/skills/deployer.js +20 -75
  62. package/dist/src/skills/deployment-ownership.js +74 -0
  63. package/dist/src/skills/doctor.js +2 -2
  64. package/dist/src/skills/importer.js +4 -26
  65. package/dist/src/skills/registry.js +22 -7
  66. package/dist/src/smiths/context-pipeline/agents-md.js +34 -0
  67. package/dist/src/smiths/context-pipeline/aiwg-md.js +3 -0
  68. package/dist/src/smiths/context-pipeline/bridge-ownership.js +50 -0
  69. package/dist/src/smiths/context-pipeline/generator.js +40 -104
  70. package/dist/src/smiths/context-pipeline/managed-hook.js +10 -0
  71. package/dist/src/smiths/context-pipeline/parallelism-section.js +7 -3
  72. package/package.json +6 -2
  73. package/tools/agents/deploy-agents.mjs +2 -123
  74. package/tools/agents/providers/antigravity.mjs +4 -6
  75. package/tools/agents/providers/base.mjs +3 -3
  76. package/tools/agents/providers/claude.mjs +3 -5
  77. package/tools/agents/providers/codex.mjs +3 -5
  78. package/tools/agents/providers/context-write.mjs +12 -0
  79. package/tools/agents/providers/copilot.mjs +3 -5
  80. package/tools/agents/providers/cursor.mjs +3 -5
  81. package/tools/agents/providers/factory.mjs +3 -5
  82. package/tools/agents/providers/grok-build.mjs +17 -12
  83. package/tools/agents/providers/hermes-skill-lifecycle.mjs +144 -0
  84. package/tools/agents/providers/hermes-startup.mjs +209 -0
  85. package/tools/agents/providers/hermes.mjs +9 -359
  86. package/tools/agents/providers/model-wrapper.mjs +90 -0
  87. package/tools/agents/providers/muse.mjs +3 -3
  88. package/tools/agents/providers/omp.mjs +3 -1
  89. package/tools/agents/providers/openclaw.mjs +3 -5
  90. package/tools/agents/providers/opencode.mjs +3 -5
  91. package/tools/agents/providers/pi.mjs +1 -1
  92. package/tools/agents/providers/provider-paths-staging.mjs +9 -0
  93. package/tools/agents/providers/rule-delivery.mjs +26 -228
  94. package/tools/agents/providers/rule-presentation.mjs +13 -4
  95. package/tools/agents/providers/rule-projection.mjs +119 -0
  96. package/tools/agents/providers/rule-startup.mjs +70 -0
  97. package/tools/agents/providers/stale-artifact-prune.mjs +128 -0
  98. package/tools/agents/providers/warp.mjs +5 -7
  99. package/tools/agents/providers/windsurf.mjs +14 -62
  100. package/tools/plugin/package-plugins.mjs +2 -2
  101. package/tools/plugin/plugin-links.mjs +3 -0
  102. package/tools/skills/codex-skill-transform.mjs +232 -0
  103. package/tools/skills/deploy-skills-codex.mjs +8 -249
  104. package/tools/warp/warp-content.mjs +548 -0
@@ -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
+
@@ -11,7 +11,7 @@ import { importImpl } from '../../_resolve-impl.mjs';
11
11
  *
12
12
  * What this provider SKIPS:
13
13
  * - Commands: Hermes has no AIWG slash-command file surface
14
- * - Rules: compressed directives are in AGENTS.md; full bodies via `aiwg show rule`
14
+ * - Rules: .hermes/rules holds complete kernels and indexes, reached by startup hooks
15
15
  *
16
16
  * See: docs/integrations/hermes-quickstart.md
17
17
  */
@@ -37,12 +37,12 @@ import {
37
37
  getAddonSkillDirs,
38
38
  normalizeDeploymentMode,
39
39
  collectFrameworkArtifacts,
40
- listOnDemandRuleFiles,
41
- renderOnDemandRuleSection,
42
40
  stripPlatformsFromContent,
43
41
  } from './base.mjs';
44
42
 
45
- import { writeContextFileSync } from './context-write.mjs';
43
+ import { assertContextBudget, generateAgentsMd, generateHermesMd } from './hermes-startup.mjs';
44
+ export { assertContextBudget, generateAgentsMd, generateHermesMd };
45
+ import { createHermesSkillLifecycle } from './hermes-skill-lifecycle.mjs';
46
46
 
47
47
  // ============================================================================
48
48
  // Hermes home resolution (HERMES_HOME) — #2119
@@ -115,7 +115,7 @@ export const paths = {
115
115
  // #2119: previously hardcoded os.homedir() — wrong for any operator running
116
116
  // Hermes under a non-default HERMES_HOME (multi-profile, hermes-role, etc.).
117
117
  skills: path.resolve(HERMES_HOME, 'skills', '.aiwg'),
118
- rules: '', // Inlined into AGENTS.md + reachable via `aiwg show rule`
118
+ rules: '.hermes/rules', // Complete files reached through the startup hook
119
119
  };
120
120
 
121
121
  // Kernel skills (always-loaded) deploy to the platform-native dir.
@@ -128,12 +128,13 @@ export const kernelSkillsPath = path.resolve(HERMES_HOME, 'skills');
128
128
  // Consumers (deploy verification, doctor, status) should use this rather than
129
129
  // re-reading os.homedir() to stay consistent with the deploy target.
130
130
  export const hermesHome = HERMES_HOME;
131
+ export const { updateBundledManifest, migrateLegacySkillPath } = createHermesSkillLifecycle({ getHermesHome, paths, kernelSkillsPath });
131
132
 
132
133
  export const support = {
133
134
  agents: 'aggregated', // Agents aggregated into lean AGENTS.md
134
135
  commands: 'indexed', // Full command bodies via aiwg discover/show; no native file loader
135
136
  skills: 'native', // $HERMES_HOME/skills/ is the native skill location
136
- rules: 'agents-md+cli', // compressed in AGENTS.md; full bodies via CLI/MCP
137
+ rules: 'prose-hook', // RULES-INDEX and complete local kernel files
137
138
  };
138
139
 
139
140
  export const capabilities = {
@@ -193,219 +194,6 @@ export function mapModel(shorthand, modelCfg, modelsConfig) {
193
194
  // AGENTS.md Generation
194
195
  // ============================================================================
195
196
 
196
- /**
197
- * Generate a lean AGENTS.md for Hermes
198
- *
199
- * Hermes reaches AGENTS.md through its startup pointer on every task. Reserve
200
- * the 19,000-character budget for CRITICAL kernel bodies and the kernel index.
201
- * See: docs/integrations/hermes-quickstart.md (Part 3)
202
- */
203
- // Hermes context cap is 20K chars (head-tail truncated above). Hard limit
204
- // to leave headroom for project-specific additions and skill-discovery.
205
- const HERMES_AGENTS_MD_HARD_CAP = 19_000;
206
- const HERMES_AGENTS_MD_SOFT_WARN = 15_000;
207
-
208
- /** Never truncate CRITICAL bodies. Report each contribution before promotion. */
209
- export function assertContextBudget(content, name = 'AGENTS.md', rules = []) {
210
- if (content.length <= HERMES_AGENTS_MD_HARD_CAP) return;
211
- const critical = rules.filter(rule => rule.tagged && rule.activation === 'kernel'
212
- && String(rule.enforcement || '').trim().toLowerCase() === 'critical');
213
- const sizes = critical.map(rule => ({ name: rule.name,
214
- chars: `## Rule: ${rule.name}\n\n${rule.body.trim()}`.length }));
215
- const total = sizes.reduce((sum, rule) => sum + rule.chars, 0) + Math.max(0, sizes.length - 1) * 2;
216
- throw new Error(
217
- `Hermes ${name} (${content.length} chars) exceeds hard cap of ${HERMES_AGENTS_MD_HARD_CAP}. ` +
218
- `Hermes truncates above 20K. ` +
219
- (total > HERMES_AGENTS_MD_HARD_CAP ? 'CRITICAL kernel set alone exceeds the cap. ' : 'Assembled context exceeds the cap; review wrappers and operator additions. ') +
220
- `CRITICAL kernel total: ${total} chars (bodies and rule headings).\n` +
221
- sizes.map(rule => ` ${rule.name}: ${rule.chars} chars`).join('\n')
222
- );
223
- }
224
-
225
- /**
226
- * Top-7 CRITICAL rule directives, inlined into AGENTS.md for guaranteed
227
- * priming on every Hermes turn (#1318 / S7; skill-discovery added #1347).
228
- *
229
- * The full rule bodies are reachable without MCP via `aiwg discover` and
230
- * `aiwg show rule <name> --body`; MCP exposes the same path through `rule-list` and
231
- * `rule-show` when configured (#1320). The bodies exceed Hermes's 20K context
232
- * cap if inlined verbatim (anti-laziness alone was 32K chars; it now ships as a compact core body, #3450), so we inline
233
- * compressed directives only and point to CLI/MCP for the full text.
234
- *
235
- * Selection criteria: rules tagged CRITICAL/HIGH enforcement level whose
236
- * violations are silent or destructive (cost of remembering to query
237
- * rule-show > cost of inlining the directive). skill-discovery is HIGH
238
- * but is the linchpin of the discover-first architecture across all
239
- * providers and is therefore inlined alongside the CRITICAL set.
240
- */
241
- const CRITICAL_RULE_DIRECTIVES = `## CRITICAL Rules (always apply)
242
-
243
- These are the highest-enforcement AIWG rules. Full bodies are reachable without
244
- MCP:
245
- - Find rules: \`aiwg discover "rule <topic>" --type rule\`
246
- - Fetch a rule: \`aiwg show rule <name> --body\`
247
-
248
- If the optional MCP sidecar is configured, the same surface is available through
249
- \`mcp_aiwg_rule_list\` and \`mcp_aiwg_rule_show\`.
250
-
251
- ### Rule: skill-discovery (discover-first protocol)
252
- Before declining a user request as "outside AIWG's scope" or improvising a
253
- workflow from training data, you MUST run \`aiwg discover "<user need>"\`
254
- against the user's need. Most AIWG skills are not in your context; they reach
255
- you through \`aiwg discover\` + \`aiwg show <type> <name>\`. If MCP is available,
256
- \`mcp_aiwg_discover\` and type-specific show tools are equivalent. Run discover
257
- whenever the user mentions AIWG, a framework name (sdlc, research, forensics,
258
- ops, marketing, security-engineering, media-curator, knowledge-base), or
259
- capability keywords (skill, agent, command, rule, workflow).
260
-
261
- ### Rule: no-attribution
262
- Never add AI-tool attribution to commits, PRs, code, or docs. No \`Co-Authored-By:\`,
263
- no "Generated with", no "Written by [AI tool]". The AI is a tool; tools don't sign
264
- their output. Applies to ALL platforms (Claude, Codex, Copilot, Cursor, etc.).
265
-
266
- ### Rule: citation-policy
267
- Never fabricate citations, DOIs, URLs, or page numbers. Only cite sources that
268
- exist in the research corpus (.aiwg/research/sources/). Match claim strength
269
- to evidence quality (GRADE): HIGH = "demonstrates"; MODERATE = "suggests";
270
- LOW = "limited evidence"; VERY LOW = "anecdotal". Document research gaps in
271
- .aiwg/research/TODO.md when no source supports a claim.
272
-
273
- ### Rule: token-security
274
- Never hard-code tokens, API keys, or secrets in source files or commit messages.
275
- Never pass tokens as CLI arguments (visible in process list). Never echo or log
276
- token values. Load from secure files (mode 600) or environment variables. Use
277
- heredoc scope for multi-step operations so tokens don't persist beyond use.
278
- Token files must NEVER be tracked in git (.gitignore enforced).
279
-
280
- ### Rule: versioning
281
- CalVer format: \`YYYY.M.PATCH\` (e.g., \`2026.5.3\`). NEVER use leading zeros
282
- (\`2026.01.5\` is broken — npm semver rejects it). Tags use \`v\` prefix.
283
- CHANGELOG must use same format. PATCH resets each month.
284
-
285
- ### Rule: ops-safety
286
- Detect interactive commands and flag for human execution (passwords, LUKS
287
- passphrases, MFA — agents cannot type these). Gate destructive operations
288
- (\`rm -rf\`, \`fdisk\`, \`mkfs\`, partition table changes) behind explicit
289
- human confirmation. Assess blast radius before execution (CRITICAL = multi-host
290
- / data loss; HIGH = single-host outage). Dry-run first when the tool supports it.
291
- Never cross host boundaries without confirmation.`;
292
-
293
- const HERMES_AGENTS_MD_FOOTER = `## Optional MCP Server Surface (\`aiwg mcp serve\`)
294
-
295
- MCP is optional. The baseline path is file deploy + \`aiwg discover\` /
296
- \`aiwg show\` from the CLI. MCP exposes the same AIWG catalog and execution
297
- surface as provider-agnostic tools when configured.
298
-
299
- **Discovery** (read-only, no project required):
300
- - \`mcp_aiwg_discover\` — semantic search across skills/agents/commands/rules
301
- - \`mcp_aiwg_skill_list\` / \`mcp_aiwg_skill_show\`
302
- - \`mcp_aiwg_command_list\` / \`mcp_aiwg_command_show\`
303
- - \`mcp_aiwg_rule_list\` / \`mcp_aiwg_rule_show\`
304
- - \`mcp_aiwg_agent_list\` / \`mcp_aiwg_agent_show\`
305
- - \`mcp_aiwg_template_list\` / \`mcp_aiwg_template_show\` / \`mcp_aiwg_template_render\`
306
-
307
- **Execution** (allow-listed):
308
- - \`mcp_aiwg_command_run\` — dispatches to any of 94 AIWG CLI commands. Destructive
309
- commands require \`confirmed: true\`.
310
-
311
- **Artifacts** (project-required, .aiwg/ directory):
312
- - \`mcp_aiwg_artifact_read\` / \`mcp_aiwg_artifact_write\``;
313
-
314
- function mergeHermesContext(file, generated, kind) {
315
- let existing = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
316
- existing = existing.replace(/\n?<!-- AIWG:rule-startup:start -->[\s\S]*?<!-- AIWG:rule-startup:end -->\n?/g, '');
317
- const start = `<!-- AIWG:hermes-${kind}:start -->`;
318
- const end = `<!-- AIWG:hermes-${kind}:end -->`;
319
- const managed = `${start}\n${generated}\n${end}`;
320
- if (existing.includes(start)) return existing.slice(0, existing.indexOf(start)) + managed + existing.slice(existing.indexOf(end) + end.length);
321
- if (kind === 'context' && existing.startsWith('# AIWG Integration') && existing.includes(HERMES_AGENTS_MD_FOOTER)) {
322
- existing = existing.slice(existing.indexOf(HERMES_AGENTS_MD_FOOTER) + HERMES_AGENTS_MD_FOOTER.length);
323
- } else if (kind === 'routing' && existing.includes(generated)) {
324
- existing = existing.replace(generated, '');
325
- }
326
- return existing ? `${existing.trimEnd()}\n\n${managed}\n` : `<!-- aiwg-managed -->\n${managed}\n`;
327
- }
328
-
329
- export function generateAgentsMd(agentCount, skillCount, targetDir, opts) {
330
- if (opts.contextFiles === false) return;
331
- const { dryRun } = opts;
332
-
333
- // Startup is reserved for rule contracts. Workflow routing, artifact catalogs,
334
- // and the optional MCP tool inventory duplicate discover/show and consume
335
- // Hermes's finite per-turn context before the kernel is appended.
336
- const header = `# AIWG Integration
337
-
338
- Skills: \`$HERMES_HOME/skills/\` (kernel), \`$HERMES_HOME/skills/.aiwg/\` (standard).
339
- Find: \`aiwg discover "rule <topic>" --type rule\`. Fetch: \`aiwg show rule <name> --body\`.
340
- MCP is optional; \`mcp_aiwg_rule_show\` exposes the same rule catalog.
341
- `;
342
-
343
- // On-demand tier (#1675): the MEDIUM/LOW rules not inlined above. Hermes has
344
- // no scanned rule dir, so the bridge file notes the tier with fetch hints.
345
- const onDemandSection = opts.srcRoot
346
- ? renderOnDemandRuleSection(listOnDemandRuleFiles(opts.srcRoot))
347
- : '';
348
- const migrated = new Set((opts.ruleDelivery?.rules || []).filter(rule => rule.tagged).map(rule => rule.name));
349
- const directives = CRITICAL_RULE_DIRECTIVES.split(/(?=^### Rule: )/m).filter(section => section.startsWith('### Rule: ') && !migrated.has(section.match(/^### Rule: ([^ \n]+)/)?.[1])).join('');
350
- const sections = [header, directives];
351
- if (onDemandSection) sections.push(onDemandSection);
352
- // The optional tool inventory is available on demand through the CLI.
353
- const destPath = path.join(targetDir, 'AGENTS.md');
354
- const output = mergeHermesContext(destPath, sections.join('\n\n'), 'context');
355
-
356
- assertContextBudget(output, 'AGENTS.md', opts.ruleDelivery?.rules);
357
-
358
- if (dryRun) {
359
- console.log(`[dry-run] Would write AGENTS.md (${output.length} chars, ${Math.round(output.length / 4)} tokens estimated)`);
360
- } else {
361
- writeContextFileSync(destPath, output, 'utf8');
362
- const charCount = output.length;
363
- const tokenEstimate = Math.round(charCount / 4);
364
- let budgetNote;
365
- if (charCount > HERMES_AGENTS_MD_SOFT_WARN) {
366
- budgetNote = `⚠ ${charCount} chars — above soft warn (${HERMES_AGENTS_MD_SOFT_WARN}); below hard cap (${HERMES_AGENTS_MD_HARD_CAP})`;
367
- } else {
368
- budgetNote = `✓ within budget (cap: ${HERMES_AGENTS_MD_HARD_CAP})`;
369
- }
370
- console.log(` Created AGENTS.md (${charCount} chars, ~${tokenEstimate} tokens, ${budgetNote})`);
371
- }
372
-
373
- return 1;
374
- }
375
-
376
- /**
377
- * Generate `.hermes.md` thin pointer at the project root (#1319 / S8).
378
- *
379
- * Hermes loads `.hermes.md` with priority over `AGENTS.md` (first-match-wins
380
- * at `agent/prompt_builder.py:1417-1456`). The pointer is short so the
381
- * actual context payload remains in AGENTS.md which is shared with other
382
- * tools (Claude Code, Codex, etc.).
383
- */
384
- export function generateHermesMd(targetDir, opts) {
385
- const { dryRun } = opts;
386
- const body = `# Hermes Routing
387
-
388
- AIWG project context lives in \`AGENTS.md\` (this file is a thin Hermes pointer).
389
-
390
- **Routing**: see \`AGENTS.md\` in this directory.
391
- **MCP**: AIWG is reachable via \`mcp_aiwg_*\` tools.
392
- **Skills**: kernel skills at \`$HERMES_HOME/skills/\`; standard skills at \`$HERMES_HOME/skills/.aiwg/\`.
393
- When unset, \`HERMES_HOME\` defaults to the platform-native Hermes home.
394
-
395
- Hermes loads only \`.hermes.md\` when it is present (first-match-wins). Keep
396
- this file minimal; its routing instruction tells the agent to read \`AGENTS.md\`
397
- when the full AIWG project context is needed.
398
- `;
399
- const destPath = path.join(targetDir, '.hermes.md');
400
- if (dryRun) {
401
- console.log(`[dry-run] Would write .hermes.md (${body.length} chars)`);
402
- } else {
403
- writeContextFileSync(destPath, mergeHermesContext(destPath, body, 'routing'), 'utf8');
404
- console.log(` Created .hermes.md (${body.length} chars)`);
405
- }
406
- return 1;
407
- }
408
-
409
197
  // ============================================================================
410
198
  // Skills Deployment
411
199
  // ============================================================================
@@ -527,7 +315,7 @@ async function deploySelected(opts) {
527
315
  }
528
316
 
529
317
  // ── AGENTS.md + .hermes.md ─────────────────────────────────────────────────
530
- // Generate AGENTS.md (with inlined CRITICAL rule priming, #1318/#1532)
318
+ // Generate the legacy scaffold; activation projection replaces it with the minimal hook.
531
319
  // AND .hermes.md thin pointer (resolves #1319 doc-debt, was claimed in
532
320
  // CHANGELOG but not previously implemented).
533
321
  if (opts.contextFiles !== false && !skillsOnly && !opts.commandsOnly && !opts.rulesOnly) {
@@ -557,7 +345,7 @@ async function deploySelected(opts) {
557
345
  if (!opts.quiet) {
558
346
  console.log('');
559
347
  console.log(`Skills root: ${kernelSkillsPath}`);
560
- console.log('Rules are in AGENTS.md as compressed directives; full bodies via `aiwg show rule <name> --body`.');
348
+ console.log('Rules are in .hermes/rules; read RULES-INDEX.md and every listed kernel file before task work.');
561
349
  console.log('Optional: configure config.yaml to connect AIWG MCP server.');
562
350
  console.log('See: docs/integrations/hermes-quickstart.md (optional MCP setup)');
563
351
  }
@@ -591,144 +379,6 @@ async function deploySelected(opts) {
591
379
  // Curator protection (#1317 / S6)
592
380
  // ============================================================================
593
381
 
594
- /**
595
- * Hermes v0.12.0+ ships an autonomous Curator (`agent/curator.py`) that
596
- * grades and archives skills on a 7-day cycle. Skills are excluded from
597
- * archival if either:
598
- * (a) they appear in `~/.hermes/skills/.bundled_manifest` (one name per
599
- * line, format `name:tag`), or
600
- * (b) their path's first component starts with `.` (verified at
601
- * `tools/skill_usage.py:241-243`).
602
- *
603
- * AIWG standard skills under `~/.hermes/skills/.aiwg/...` are protected
604
- * by (b) automatically. AIWG kernel skills land at the top level
605
- * (`~/.hermes/skills/<name>/SKILL.md`) and need explicit (a) registration.
606
- *
607
- * This function writes/updates the bundled manifest with the kernel-skill
608
- * names AIWG owns. Idempotent: existing entries (from Hermes's own bundle
609
- * or other tools) are preserved.
610
- */
611
- export function updateBundledManifest(kernelSkillNames, opts) {
612
- const { dryRun, quiet } = opts;
613
- const manifestPath = path.join(opts.kernelSkillsPath || kernelSkillsPath, '.bundled_manifest');
614
- const aiwgTag = 'aiwg-managed';
615
-
616
- // Read existing manifest (if any) and split into "ours" vs "theirs"
617
- let existing = '';
618
- try {
619
- existing = fs.readFileSync(manifestPath, 'utf-8');
620
- } catch {
621
- existing = '';
622
- }
623
- const theirs = [];
624
- for (const rawLine of existing.split('\n')) {
625
- const line = rawLine.trim();
626
- if (!line) continue;
627
- if (line.endsWith(`:${aiwgTag}`)) continue; // ours — drop, will re-add below
628
- theirs.push(line);
629
- }
630
- const ours = kernelSkillNames.map((n) => `${n}:${aiwgTag}`);
631
-
632
- // Stable order: theirs first (preserve operator/Hermes-bundled order), then ours
633
- const merged = [...theirs, ...ours].join('\n') + '\n';
634
-
635
- if (dryRun) {
636
- if (!quiet) {
637
- console.log(` [curator] [dry-run] Would write ${manifestPath} with ${ours.length} AIWG kernel + ${theirs.length} preserved entries`);
638
- }
639
- return;
640
- }
641
-
642
- try {
643
- fs.mkdirSync(path.dirname(manifestPath), { recursive: true });
644
- fs.writeFileSync(manifestPath, merged, 'utf-8');
645
- if (!quiet) {
646
- console.log(` [curator] Bundled manifest updated: ${ours.length} AIWG kernel skills protected (preserved ${theirs.length} pre-existing entries)`);
647
- }
648
- } catch (err) {
649
- if (!quiet) {
650
- console.log(` [curator] Warning: could not write bundled manifest: ${err.message}`);
651
- }
652
- }
653
- }
654
-
655
- // ============================================================================
656
- // Legacy skill path migration (#1316 / S5)
657
- // ============================================================================
658
-
659
- /**
660
- * Remove the legacy `~/.hermes/.aiwg/skills/` directory if it exists and the
661
- * new path `~/.hermes/skills/.aiwg/` is populated with AIWG content.
662
- *
663
- * Idempotent: re-running after migration is a no-op.
664
- *
665
- * Safety:
666
- * - Only removes when the new path exists and contains files
667
- * - Skips removal if the new path is empty (avoids losing skills during
668
- * an in-progress deploy where the new path hasn't been written yet)
669
- * - Operates only on the documented legacy path — never touches user-managed
670
- * directories under ~/.hermes/
671
- */
672
- export function migrateLegacySkillPath(opts) {
673
- const { dryRun, quiet } = opts;
674
- // Resolve through the same HERMES_HOME contract as every other path in
675
- // this provider (env var first, platform default otherwise): with
676
- // HERMES_HOME set, the legacy tree lives under that root — never under
677
- // the process home directory.
678
- const legacyPath = opts.hermesLegacySkills || path.join(getHermesHome(), '.aiwg', 'skills');
679
- const newPath = paths.skills;
680
-
681
- let legacyExists = false;
682
- try {
683
- legacyExists = fs.statSync(legacyPath).isDirectory();
684
- } catch {
685
- return; // no legacy path — nothing to migrate
686
- }
687
- if (!legacyExists) return;
688
-
689
- // Sanity: new path must exist and be non-empty before we remove the legacy one
690
- let newPopulated = false;
691
- try {
692
- const entries = fs.readdirSync(newPath);
693
- newPopulated = entries.length > 0;
694
- } catch {
695
- newPopulated = false;
696
- }
697
-
698
- if (!newPopulated) {
699
- if (!quiet) {
700
- console.log(` [migrate] Legacy skills detected at ${legacyPath}; new path not yet populated. Skipping cleanup until next deploy.`);
701
- }
702
- return;
703
- }
704
-
705
- if (dryRun) {
706
- console.log(` [migrate] [dry-run] Would remove legacy skill path: ${legacyPath}`);
707
- return;
708
- }
709
-
710
- try {
711
- fs.rmSync(legacyPath, { recursive: true, force: true });
712
- // Also remove the empty parent if it's now empty
713
- const parent = path.dirname(legacyPath);
714
- try {
715
- const remaining = fs.readdirSync(parent);
716
- if (remaining.length === 0) {
717
- fs.rmdirSync(parent);
718
- }
719
- } catch {
720
- // parent removal is best-effort
721
- }
722
- if (!quiet) {
723
- console.log(` [migrate] Removed legacy skill path: ${legacyPath}`);
724
- }
725
- } catch (err) {
726
- if (!quiet) {
727
- console.log(` [migrate] Warning: could not remove legacy path ${legacyPath}: ${err.message}`);
728
- }
729
- }
730
- }
731
-
732
382
  // ============================================================================
733
383
  // aiwg-orchestrate auto-install (#1242)
734
384
  // ============================================================================