heimdall-agent 1.0.0 → 1.2.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 (250) hide show
  1. package/README.md +57 -26
  2. package/README.pt-BR.md +443 -0
  3. package/agents/cloud-engineer.md +77 -0
  4. package/agents/code-sentinel.md +71 -34
  5. package/agents/database-architect.md +31 -25
  6. package/agents/frontend-designer.md +30 -28
  7. package/agents/mobile-designer.md +25 -24
  8. package/agents/modernizer.md +68 -0
  9. package/agents/orchestrator.md +107 -93
  10. package/agents/reviewer.md +102 -71
  11. package/agents/security-auditor.md +27 -27
  12. package/agents/tester.md +97 -90
  13. package/commands/grill-me.md +20 -4
  14. package/commands/orchestrate.md +16 -0
  15. package/commands/orchestrator.md +16 -0
  16. package/commands/plan.md +17 -1
  17. package/config/agents.json +31 -3
  18. package/config/mcp.json +72 -0
  19. package/config/models.json +26 -16
  20. package/config/profiles.json +2 -4
  21. package/config/skills.json +762 -573
  22. package/docs/SKILLS.md +393 -275
  23. package/docs/designs/old/2026-10-31 plan-lifecycle-backlog-and-clean-code-skill.md +87 -0
  24. package/docs/designs/old/2026-11-02 skill-upstream-audit-and-update.md +105 -0
  25. package/docs/designs/old/2026-11-05 communication-doctrine-bluf-ste.md +94 -0
  26. package/docs/designs/old/2026-11-06-cloud-engineer-and-resilience-synthesis.md +67 -0
  27. package/docs/designs/old/2026-11-06-herdr-native-agent-orchestration.md +45 -0
  28. package/docs/runs/skill-audit/2026-11-12-compare-report.json +1028 -0
  29. package/docs/runs/skill-audit/2026-11-12-upstream-audit.json +275 -0
  30. package/docs/runs/skill-audit/add_progressive_disclosure.cjs +30 -0
  31. package/docs/runs/skill-audit/check_heimdall_skills.ps1 +9 -0
  32. package/docs/runs/skill-audit/compare_classics.ps1 +26 -0
  33. package/docs/runs/skill-audit/compare_taste.ps1 +12 -0
  34. package/docs/runs/skill-audit/customization-report.json +380 -0
  35. package/docs/runs/skill-audit/diff_pending_skills.cjs +94 -0
  36. package/docs/runs/skill-audit/fetch_and_apply_skill.cjs +58 -0
  37. package/docs/runs/skill-audit/fetch_and_apply_taste_v2.cjs +65 -0
  38. package/docs/runs/skill-audit/inspect_pending_skills.cjs +71 -0
  39. package/docs/runs/skill-audit/inventory.json +308 -0
  40. package/docs/runs/skill-audit/list_local_taste.ps1 +1 -0
  41. package/docs/runs/skill-audit/phase5-update-plan.json +595 -0
  42. package/docs/runs/skill-audit/phase5-update-plan.md +138 -0
  43. package/docs/runs/skill-audit/probe.ps1 +16 -0
  44. package/docs/runs/skill-audit/probe_classics_branches.ps1 +3 -0
  45. package/docs/runs/skill-audit/probe_commits.ps1 +15 -0
  46. package/docs/runs/skill-audit/probe_repos.ps1 +17 -0
  47. package/docs/runs/skill-audit/probe_sentry_sec.ps1 +3 -0
  48. package/docs/runs/skill-audit/probe_sentry_sweep.ps1 +5 -0
  49. package/docs/runs/skill-audit/probe_snyk.ps1 +3 -0
  50. package/docs/runs/skill-audit/probe_snyk_recipes.ps1 +5 -0
  51. package/docs/runs/skill-audit/probe_taste_branches.ps1 +8 -0
  52. package/docs/runs/skill-audit/probe_taste_v19.ps1 +3 -0
  53. package/docs/runs/skill-audit/probe_user_repos.ps1 +19 -0
  54. package/docs/runs/skill-audit/prune_taste_skills.cjs +22 -0
  55. package/docs/runs/skill-audit/run_phase1_2.cjs +142 -0
  56. package/docs/runs/skill-audit/run_phase6_verification.cjs +107 -0
  57. package/docs/runs/skill-audit/show_16_details.ps1 +25 -0
  58. package/docs/runs/skill-audit/show_20_skills.ps1 +28 -0
  59. package/docs/runs/skill-audit/show_classics_diff.cjs +37 -0
  60. package/docs/runs/skill-audit/sync_agent_markdowns.cjs +30 -0
  61. package/docs/runs/skill-audit/taste-skill-upstream.md +542 -0
  62. package/docs/runs/skill-audit/update-manifest.md +88 -0
  63. package/docs/runs/skill-audit/update_config_skills.cjs +52 -0
  64. package/docs/runs/skill-audit/update_registry_phase7.cjs +83 -0
  65. package/docs/runs/skill-audit/upstream-status.json +563 -0
  66. package/docs/runs/skill-audit/verification-results.json +252 -0
  67. package/doctrine/AGENTS.md +42 -77
  68. package/hooks/git/pre-commit +11 -0
  69. package/hooks/heimdall-hook.cjs +81 -2
  70. package/hooks/herdr-agent-state.ps1 +55 -0
  71. package/hooks/hooks.json +0 -11
  72. package/lib/catalog-sync.cjs +167 -0
  73. package/lib/hermes-context.cjs +57 -0
  74. package/lib/model-context.cjs +123 -0
  75. package/lib/path-discovery.cjs +94 -0
  76. package/package.json +7 -3
  77. package/playbooks/01-interactive-grilling-gate.md +23 -6
  78. package/playbooks/02-fast-code-deep-verification.md +3 -2
  79. package/playbooks/03-adversarial-code-review.md +15 -7
  80. package/playbooks/05-canonical-plan-template.md +35 -19
  81. package/playbooks/06-model-registry-matrix.md +24 -13
  82. package/playbooks/07-legacy-code-modernization.md +74 -0
  83. package/playbooks/08-backlog-and-change-request-flow.md +122 -0
  84. package/setup.mjs +592 -172
  85. package/skills/antislop/SKILL.md +76 -56
  86. package/skills/antislop/VERSION +1 -0
  87. package/skills/antislop-copywriting/SKILL.md +407 -372
  88. package/skills/antislop-human/LICENSE-web-quality-skills +21 -0
  89. package/skills/antislop-human/SKILL.md +204 -147
  90. package/skills/antislop-human/contrast-check.py +168 -165
  91. package/skills/antislop-human/contrast-mcp.py +6 -3
  92. package/skills/antislop-human/references/A11Y-PATTERNS.md +249 -0
  93. package/skills/antislop-human/references/WCAG.md +127 -0
  94. package/skills/antislop-ui/LICENSE-web-quality-skills +21 -0
  95. package/skills/antislop-ui/SKILL.md +344 -304
  96. package/skills/antislop-ui/references/CORE-WEB-VITALS.md +181 -0
  97. package/skills/antislop-ui/references/WEB-BASELINE.md +28 -0
  98. package/skills/brainstorming/SKILL.md +296 -265
  99. package/skills/brainstorming/builder-check-prompt.md +23 -0
  100. package/skills/brainstorming/scripts/frame-template.html +213 -213
  101. package/skills/brainstorming/scripts/server.cjs +723 -723
  102. package/skills/brandkit/SKILL.md +798 -798
  103. package/skills/brutalist-skill/SKILL.md +93 -92
  104. package/skills/caveman/README.md +68 -0
  105. package/skills/caveman/SKILL.md +73 -38
  106. package/skills/claude-collaborator/SKILL.md +24 -44
  107. package/skills/clean-code/SKILL.md +152 -0
  108. package/skills/cloudflare-security-audit/AI-AND-LLM.md +83 -83
  109. package/skills/cloudflare-security-audit/ATTACK-CLASSES.md +130 -130
  110. package/skills/cloudflare-security-audit/CLIENT-SIDE.md +83 -83
  111. package/skills/cloudflare-security-audit/CLOUD-AND-DEPLOYMENT.md +86 -86
  112. package/skills/cloudflare-security-audit/DATA-ISOLATION-AND-LIFECYCLE.md +84 -84
  113. package/skills/cloudflare-security-audit/DESKTOP-MOBILE-AND-LOCAL-IPC.md +89 -89
  114. package/skills/cloudflare-security-audit/HUNTING.md +251 -251
  115. package/skills/cloudflare-security-audit/MEMORY-SAFETY-AND-BINARY.md +101 -101
  116. package/skills/cloudflare-security-audit/PROTOCOLS-RPC-AND-MESSAGING.md +81 -81
  117. package/skills/cloudflare-security-audit/RECONNAISSANCE.md +156 -156
  118. package/skills/cloudflare-security-audit/RESOURCE-EXHAUSTION-AND-AVAILABILITY.md +78 -78
  119. package/skills/cloudflare-security-audit/SKILL.md +192 -192
  120. package/skills/cloudflare-security-audit/SUPPLY-CHAIN-AND-RELEASE.md +73 -73
  121. package/skills/cloudflare-security-audit/VALIDATION-AND-REPORTING.md +186 -186
  122. package/skills/cloudflare-security-audit/WEB-PROTOCOL-AND-AUTH.md +105 -105
  123. package/skills/cloudflare-security-audit/report-schema.json +461 -461
  124. package/skills/cloudflare-security-audit/validate-coverage-ledger.cjs +872 -872
  125. package/skills/cloudflare-security-audit/validate-coverage-ledger.test.cjs +740 -740
  126. package/skills/cloudflare-security-audit/validate-findings.cjs +773 -773
  127. package/skills/cloudflare-security-audit/validate-findings.test.cjs +652 -652
  128. package/skills/codebase-design/DEEPENING.md +37 -0
  129. package/skills/codebase-design/DESIGN-IT-TWICE.md +44 -0
  130. package/skills/codebase-design/SKILL.md +114 -0
  131. package/skills/codex-collaborator/SKILL.md +24 -45
  132. package/skills/communication-doctrine/SKILL.md +89 -0
  133. package/skills/diagnosing-superpowers/SKILL.md +1 -1
  134. package/skills/diagnosing-superpowers/references/github-issues.md +3 -3
  135. package/skills/diagnosing-superpowers/templates/issue.md +23 -4
  136. package/skills/domain-modeling/ADR-FORMAT.md +47 -0
  137. package/skills/domain-modeling/GLOSSARY-FORMAT.md +60 -0
  138. package/skills/domain-modeling/SKILL.md +74 -0
  139. package/skills/executing-plans/SKILL.md +6 -56
  140. package/skills/executing-plans/scripts/task-done +52 -52
  141. package/skills/executing-plans/scripts/task-start +28 -28
  142. package/skills/gemini-collaborator/SKILL.md +24 -56
  143. package/skills/grill-me/SKILL.md +65 -0
  144. package/skills/handoff/SKILL.md +64 -0
  145. package/skills/herdr/SKILL.md +243 -0
  146. package/skills/image-to-code-skill/SKILL.md +1228 -1228
  147. package/skills/imagegen-frontend-mobile/SKILL.md +1465 -1465
  148. package/skills/imagegen-frontend-web/SKILL.md +987 -987
  149. package/skills/improve-codebase-architecture/HTML-REPORT.md +123 -0
  150. package/skills/improve-codebase-architecture/SKILL.md +71 -0
  151. package/skills/karpathy-guidelines/SKILL.md +67 -67
  152. package/skills/mcp-engineering/SKILL.md +74 -0
  153. package/skills/minimalist-skill/SKILL.md +87 -85
  154. package/skills/output-skill/SKILL.md +49 -49
  155. package/skills/owasp-security/reference/config-and-supply-chain.md +346 -344
  156. package/skills/owasp-security/reference/languages.md +378 -372
  157. package/skills/owasp-security/reference/owasp-report.md +1144 -1140
  158. package/skills/owasp-security/reference/review-checklist.md +134 -132
  159. package/skills/ponytail/SKILL.md +36 -52
  160. package/skills/postgres-best-practices/SKILL.md +30 -52
  161. package/skills/postgres-best-practices/references/backup-restore.md +372 -0
  162. package/skills/postgres-best-practices/references/bulk-loading.md +315 -0
  163. package/skills/postgres-best-practices/references/connection-pooling.md +310 -0
  164. package/skills/postgres-best-practices/references/hot-standby.md +221 -0
  165. package/skills/postgres-best-practices/references/indexing.md +318 -0
  166. package/skills/postgres-best-practices/references/logical-replication.md +610 -0
  167. package/skills/postgres-best-practices/references/major-version-upgrades.md +334 -0
  168. package/skills/postgres-best-practices/references/performance-diagnostics.md +553 -0
  169. package/skills/postgres-best-practices/references/query-optimization.md +294 -0
  170. package/skills/postgres-best-practices/references/query-patterns.md +566 -0
  171. package/skills/postgres-best-practices/references/schema-design.md +362 -0
  172. package/skills/postgres-best-practices/references/security-roles.md +489 -0
  173. package/skills/postgres-best-practices/references/transaction-isolation.md +344 -0
  174. package/skills/progressive-disclosure/SKILL.md +68 -0
  175. package/skills/pstack-discipline/SKILL.md +40 -0
  176. package/skills/receiving-code-review/SKILL.md +2 -23
  177. package/skills/requesting-code-review/SKILL.md +7 -36
  178. package/skills/soft-skill/SKILL.md +99 -98
  179. package/skills/stitch-skill/DESIGN.md +121 -121
  180. package/skills/stitch-skill/SKILL.md +185 -184
  181. package/skills/strix-security/SKILL.md +54 -53
  182. package/skills/subagent-driven-development/SKILL.md +35 -264
  183. package/skills/subagent-driven-development/references/batching.md +11 -0
  184. package/skills/subagent-driven-development/references/cannot-verify.md +10 -0
  185. package/skills/subagent-driven-development/references/final-review.md +47 -0
  186. package/skills/subagent-driven-development/references/fix-loop.md +77 -0
  187. package/skills/subagent-driven-development/references/handling-reports.md +15 -0
  188. package/skills/subagent-driven-development/references/preflight.md +26 -0
  189. package/skills/subagent-driven-development/references/resuming.md +12 -0
  190. package/skills/subagent-driven-development/scripts/review-package +53 -53
  191. package/skills/subagent-driven-development/scripts/sdd-workspace +87 -82
  192. package/skills/subagent-driven-development/scripts/task-brief +43 -43
  193. package/skills/systematic-debugging/SKILL.md +283 -306
  194. package/skills/taste-skill/SKILL.md +542 -1206
  195. package/skills/taste-skill/references/app-screens.md +1199 -0
  196. package/skills/taste-skill/references/colour.md +141 -0
  197. package/skills/taste-skill/references/copy.md +177 -0
  198. package/skills/taste-skill/references/critique.md +182 -0
  199. package/skills/taste-skill/references/imagery.md +791 -0
  200. package/skills/taste-skill/references/layout.md +292 -0
  201. package/skills/taste-skill/references/motion.md +980 -0
  202. package/skills/taste-skill/references/research.md +356 -0
  203. package/skills/taste-skill/references/scenes.md +174 -0
  204. package/skills/taste-skill/references/tells.md +115 -0
  205. package/skills/taste-skill/references/type.md +170 -0
  206. package/skills/test-driven-development/SKILL.md +330 -337
  207. package/skills/thermo/SKILL.md +67 -0
  208. package/skills/threat-modeling/SKILL.md +55 -0
  209. package/skills/to-spec/SKILL.md +75 -0
  210. package/skills/to-tickets/SKILL.md +105 -0
  211. package/skills/trailofbits-audit-context/SKILL.md +72 -72
  212. package/skills/trailofbits-insecure-defaults/commands/audit.md +35 -0
  213. package/skills/trailofbits-insecure-defaults/references/debug-features.json +13 -13
  214. package/skills/trailofbits-insecure-defaults/references/debug-features.md +75 -75
  215. package/skills/trailofbits-insecure-defaults/references/default-credentials.json +12 -12
  216. package/skills/trailofbits-insecure-defaults/references/default-credentials.md +76 -76
  217. package/skills/trailofbits-insecure-defaults/references/fail-open-security.json +11 -11
  218. package/skills/trailofbits-insecure-defaults/references/fail-open-security.md +70 -70
  219. package/skills/trailofbits-insecure-defaults/references/fallback-secrets.json +11 -11
  220. package/skills/trailofbits-insecure-defaults/references/fallback-secrets.md +70 -70
  221. package/skills/trailofbits-insecure-defaults/references/permissive-access.json +13 -13
  222. package/skills/trailofbits-insecure-defaults/references/permissive-access.md +62 -62
  223. package/skills/trailofbits-insecure-defaults/references/weak-crypto.json +13 -13
  224. package/skills/trailofbits-insecure-defaults/references/weak-crypto.md +71 -71
  225. package/skills/trailofbits-triage-brocards/SKILL.md +208 -208
  226. package/skills/verification-before-completion/SKILL.md +0 -14
  227. package/skills/wayfinder/SKILL.md +128 -0
  228. package/skills/writing-plans/SKILL.md +11 -15
  229. package/skills/writing-skills/SKILL.md +21 -303
  230. package/skills/writing-skills/references/CLAUDE_MD_TESTING.md +189 -0
  231. package/skills/writing-skills/references/anthropic-best-practices.md +1150 -0
  232. package/skills/writing-skills/references/bulletproofing.md +80 -0
  233. package/skills/writing-skills/references/discovery.md +201 -0
  234. package/skills/writing-skills/references/flowcharts.md +37 -0
  235. package/skills/writing-skills/references/graphviz-conventions.dot +172 -0
  236. package/skills/writing-skills/references/persuasion-principles.md +187 -0
  237. package/skills/writing-skills/references/testing-skills-with-subagents.md +384 -0
  238. package/tools/{claude-bridge.ps1 → archive/claude-bridge.ps1} +10 -7
  239. package/tools/{codex-bridge.ps1 → archive/codex-bridge.ps1} +1 -1
  240. package/tools/{gemini-bridge.ps1 → archive/gemini-bridge.ps1} +12 -19
  241. package/skills/gpt-tasteskill/SKILL.md +0 -74
  242. package/skills/taste-skill-v1/SKILL.md +0 -226
  243. /package/tools/{claude-bridge.cmd → archive/claude-bridge.cmd} +0 -0
  244. /package/tools/{claude-bridge.sh → archive/claude-bridge.sh} +0 -0
  245. /package/tools/{codex-bridge.cmd → archive/codex-bridge.cmd} +0 -0
  246. /package/tools/{codex-bridge.sh → archive/codex-bridge.sh} +0 -0
  247. /package/tools/{codexcli-bridge.cmd → archive/codexcli-bridge.cmd} +0 -0
  248. /package/tools/{codexcli-bridge.ps1 → archive/codexcli-bridge.ps1} +0 -0
  249. /package/tools/{gemini-bridge.cmd → archive/gemini-bridge.cmd} +0 -0
  250. /package/tools/{gemini-bridge.sh → archive/gemini-bridge.sh} +0 -0
@@ -0,0 +1,167 @@
1
+ 'use strict';
2
+
3
+ const fs = require('node:fs');
4
+ const path = require('node:path');
5
+
6
+ /**
7
+ * Synchronizes skill and suite count references across all repository files:
8
+ * config/skills.json, config/profiles.json, docs/SKILLS.md, README.md,
9
+ * README.pt-BR.md, and setup.mjs.
10
+ *
11
+ * Single Source of Truth: The actual count of entries in config/skills.json ("skills" and "suites").
12
+ *
13
+ * @param {string} rootDir Repository root directory
14
+ * @param {boolean} dryRun If true, computes changes without writing to disk
15
+ * @returns {{ skillCount: number, suiteCount: number, modified: boolean }}
16
+ */
17
+ function syncCatalogCounts(rootDir, dryRun = false) {
18
+ const skillsConfigPath = path.join(rootDir, 'config', 'skills.json');
19
+ if (!fs.existsSync(skillsConfigPath)) return null;
20
+
21
+ try {
22
+ const rawCatalog = fs.readFileSync(skillsConfigPath, 'utf8');
23
+ const catalog = JSON.parse(rawCatalog);
24
+ const skillCount = Object.keys(catalog.skills || {}).length;
25
+ const suiteCount = Object.keys(catalog.suites || {}).length;
26
+ const multiSuites = Object.values(catalog.suites || {}).filter(s => s.type === 'Multi-Skill Suite');
27
+ const multiSuiteCount = multiSuites.length;
28
+ const multiModuleCount = multiSuites.reduce((acc, s) => acc + (s.modules ? s.modules.length : 1), 0);
29
+ const standaloneCount = suiteCount - multiSuiteCount;
30
+ const agentsDir = path.join(rootDir, 'agents');
31
+ const agentCount = fs.existsSync(agentsDir)
32
+ ? fs.readdirSync(agentsDir).filter(f => f.endsWith('.md')).length
33
+ : 10;
34
+
35
+ let modified = false;
36
+
37
+ // 1. Sync config/skills.json total counts
38
+ if (catalog.totalModules !== skillCount || catalog.totalSuites !== suiteCount) {
39
+ catalog.totalModules = skillCount;
40
+ catalog.totalSuites = suiteCount;
41
+ if (!dryRun) {
42
+ fs.writeFileSync(skillsConfigPath, JSON.stringify(catalog, null, 2) + '\n', 'utf8');
43
+ }
44
+ modified = true;
45
+ }
46
+
47
+ // 2. Sync config/profiles.json
48
+ const profilesPath = path.join(rootDir, 'config', 'profiles.json');
49
+ if (fs.existsSync(profilesPath)) {
50
+ const rawProfiles = fs.readFileSync(profilesPath, 'utf8');
51
+ const profiles = JSON.parse(rawProfiles);
52
+ if (profiles.profiles && profiles.profiles.full) {
53
+ const expectedDesc = `Complete ${skillCount}-skill suite & ${agentCount} predefined agents: Process, Anti-Slop, Design, Security, Hygiene, and Cross-Agent Bridges.`;
54
+ if (profiles.profiles.full.description !== expectedDesc) {
55
+ profiles.profiles.full.description = expectedDesc;
56
+ if (!dryRun) {
57
+ fs.writeFileSync(profilesPath, JSON.stringify(profiles, null, 2) + '\n', 'utf8');
58
+ }
59
+ modified = true;
60
+ }
61
+ }
62
+ }
63
+
64
+ // 3. Sync docs/SKILLS.md
65
+ const docsSkillsPath = path.join(rootDir, 'docs', 'SKILLS.md');
66
+ if (fs.existsSync(docsSkillsPath)) {
67
+ let content = fs.readFileSync(docsSkillsPath, 'utf8');
68
+ const regex = /Heimdall's \*\*\d+ Primary Toolkits & Suites \(\d+ modular capabilities\)\*\*/g;
69
+ const targetStr = `Heimdall's **${suiteCount} Primary Toolkits & Suites (${skillCount} modular capabilities)**`;
70
+ if (regex.test(content) && !content.includes(targetStr)) {
71
+ content = content.replace(regex, targetStr);
72
+ if (!dryRun) fs.writeFileSync(docsSkillsPath, content, 'utf8');
73
+ modified = true;
74
+ }
75
+ }
76
+
77
+ // 4. Sync README.md
78
+ const readmePath = path.join(rootDir, 'README.md');
79
+ if (fs.existsSync(readmePath)) {
80
+ let content = fs.readFileSync(readmePath, 'utf8');
81
+ const orig = content;
82
+
83
+ content = content.replace(/skills-\d+%20toolkits%20%28\d+%20modules%29/g, `skills-${suiteCount}%20toolkits%20%28${skillCount}%20modules%29`);
84
+ content = content.replace(/Skills: \d+ Toolkits \(\d+ Modules\)/g, `Skills: ${suiteCount} Toolkits (${skillCount} Modules)`);
85
+ content = content.replace(/#skill-inventory-\d+-modules-across-\d+-toolkits/g, `#skill-inventory-${skillCount}-modules-across-${suiteCount}-toolkits`);
86
+ content = content.replace(/<a id="skill-inventory-\d+-modules-across-\d+-toolkits"><\/a>/g, `<a id="skill-inventory-${skillCount}-modules-across-${suiteCount}-toolkits"></a>`);
87
+ content = content.replace(/### Skill Inventory \(\d+ Modules Across \d+ Toolkits\)/g, `### Skill Inventory (${skillCount} Modules Across ${suiteCount} Toolkits)`);
88
+ content = content.replace(/\*\*\d+ modular skills\*\*/g, `**${skillCount} modular skills**`);
89
+ content = content.replace(/\* \*\*Modular Skills\*\*:\s*\d+\s*task-activated capabilities/g, `* **Modular Skills**: ${skillCount} task-activated capabilities`);
90
+ content = content.replace(/(\|\s*`skills\/`\s*\|\s*`~\/\.<tool>\/skills\/`\s*\|\s*)\d+(\s*domain toolkits)/g, `$1${skillCount}$2`);
91
+ content = content.replace(/(\|\s*\*\*`full`\*\*\s*\*\(Default\)\*\s*\|\s*)\d+(\s*\|\s*)\d+(\s*\|)/g, `$1${skillCount}$2${agentCount}$3`);
92
+ content = content.replace(/agents-\d+%20predefined/g, `agents-${agentCount}%20predefined`);
93
+ content = content.replace(/alt="Agents: \d+ Predefined"/g, `alt="Agents: ${agentCount} Predefined"`);
94
+ content = content.replace(/#\d+-predefined-agent-personas/g, `#${agentCount}-predefined-agent-personas`);
95
+ content = content.replace(/<a id="\d+-predefined-agent-personas"><\/a>/g, `<a id="${agentCount}-predefined-agent-personas"></a>`);
96
+ content = content.replace(/### \d+ Predefined Agent Personas/g, `### ${agentCount} Predefined Agent Personas`);
97
+ content = content.replace(/synchronizes \*\*\d+ specialized agent personas\*\*/g, `synchronizes **${agentCount} specialized agent personas**`);
98
+ content = content.replace(/\* \*\*Specialized Agent Personas\*\*:\s*\d+\s*predefined roles/g, `* **Specialized Agent Personas**: ${agentCount} predefined roles`);
99
+ content = content.replace(/(\|\s*`agents\/`\s*\|\s*`~\/\.<tool>\/agents\/`\s*\|\s*)\d+(\s*specialized agent persona)/g, `$1${agentCount}$2`);
100
+ content = content.replace(/(Heimdall organizes capabilities into \*\*)\d+(\s*Core Multi-Skill Suites \()\d+(\s*modules\)\*\* and \*\*)\d+(\s*Standalone Toolkits \()\d+(\s*modules\)\*\*)/g, `$1${multiSuiteCount}$2${multiModuleCount}$3${standaloneCount}$4${standaloneCount}$5`);
101
+ content = content.replace(/(#### Core Multi-Skill Suites \()\d+(\s*Suites \/ \s*)\d+(\s*Modules\))/g, `$1${multiSuiteCount}$2${multiModuleCount}$3`);
102
+ content = content.replace(/(#### Standalone Toolkits \()\d+(\s*Curated Toolkits \/ \s*)\d+(\s*Modules\))/g, `$1${standaloneCount}$2${standaloneCount}$3`);
103
+
104
+ if (content !== orig) {
105
+ if (!dryRun) fs.writeFileSync(readmePath, content, 'utf8');
106
+ modified = true;
107
+ }
108
+ }
109
+
110
+ // 5. Sync README.pt-BR.md
111
+ const readmePtPath = path.join(rootDir, 'README.pt-BR.md');
112
+ if (fs.existsSync(readmePtPath)) {
113
+ let content = fs.readFileSync(readmePtPath, 'utf8');
114
+ const orig = content;
115
+
116
+ content = content.replace(/skills-\d+%20toolkits%20%28\d+%20m%C3%B3dulos%29/g, `skills-${suiteCount}%20toolkits%20%28${skillCount}%20m%C3%B3dulos%29`);
117
+ content = content.replace(/Skills: \d+ Toolkits \(\d+ Módulos\)/g, `Skills: ${suiteCount} Toolkits (${skillCount} Módulos)`);
118
+ content = content.replace(/#inventario-de-skills-\d+-modulos-em-\d+-toolkits/g, `#inventario-de-skills-${skillCount}-modulos-em-${suiteCount}-toolkits`);
119
+ content = content.replace(/<a id="inventario-de-skills-\d+-modulos-em-\d+-toolkits"><\/a>/g, `<a id="inventario-de-skills-${skillCount}-modulos-em-${suiteCount}-toolkits"></a>`);
120
+ content = content.replace(/### Inventário de Skills \(\d+ Módulos em \d+ Toolkits\)/g, `### Inventário de Skills (${skillCount} Módulos em ${suiteCount} Toolkits)`);
121
+ content = content.replace(/\*\*\d+ skills modulares\*\*/g, `**${skillCount} skills modulares**`);
122
+ content = content.replace(/\* \*\*Skills Modulares\*\*:\s*\d+\s*capacidades/g, `* **Skills Modulares**: ${skillCount} capacidades`);
123
+ content = content.replace(/(\|\s*`skills\/`\s*\|\s*`~\/\.<ferramenta>\/skills\/`\s*\|\s*)\d+(\s*toolkits de domínio)/g, `$1${skillCount}$2`);
124
+ content = content.replace(/(\|\s*\*\*`full`\*\*\s*\*\(Padrão\)\*\s*\|\s*)\d+(\s*\|\s*)\d+(\s*\|)/g, `$1${skillCount}$2${agentCount}$3`);
125
+ content = content.replace(/agents-\d+%20predefinidos/g, `agents-${agentCount}%20predefinidos`);
126
+ content = content.replace(/alt="Agentes: \d+ Predefinidos"/g, `alt="Agentes: ${agentCount} Predefinidos"`);
127
+ content = content.replace(/#\d+-personas-de-agentes-predefinidas/g, `#${agentCount}-personas-de-agentes-predefinidas`);
128
+ content = content.replace(/<a id="\d+-personas-de-agentes-predefinidas"><\/a>/g, `<a id="${agentCount}-personas-de-agentes-predefinidas"></a>`);
129
+ content = content.replace(/### \d+ Personas de Agentes Predefinidas/g, `### ${agentCount} Personas de Agentes Predefinidas`);
130
+ content = content.replace(/sincroniza \*\*\d+ personas de agentes especializados\*\*/g, `sincroniza **${agentCount} personas de agentes especializados**`);
131
+ content = content.replace(/\* \*\*Personas de Agentes Especializados\*\*:\s*\d+\s*papéis predefinidos/g, `* **Personas de Agentes Especializados**: ${agentCount} papéis predefinidos`);
132
+ content = content.replace(/(\|\s*`agents\/`\s*\|\s*`~\/\.<ferramenta>\/agents\/`\s*\|\s*)\d+(\s*definições de personas)/g, `$1${agentCount}$2`);
133
+ content = content.replace(/(O Heimdall organiza as capacidades em \*\*)\d+(\s*Suítes Multi-Skill Principais \()\d+(\s*módulos\)\*\* e \*\*)\d+(\s*Toolkits Independentes \()\d+(\s*módulos\)\*\*)/g, `$1${multiSuiteCount}$2${multiModuleCount}$3${standaloneCount}$4${standaloneCount}$5`);
134
+ content = content.replace(/(#### Suítes Multi-Skill Principais \()\d+(\s*Suítes \/ \s*)\d+(\s*Módulos\))/g, `$1${multiSuiteCount}$2${multiModuleCount}$3`);
135
+ content = content.replace(/(#### Toolkits Independentes \()\d+(\s*Toolkits Curados \/ \s*)\d+(\s*Módulos\))/g, `$1${standaloneCount}$2${standaloneCount}$3`);
136
+
137
+ if (content !== orig) {
138
+ if (!dryRun) fs.writeFileSync(readmePtPath, content, 'utf8');
139
+ modified = true;
140
+ }
141
+ }
142
+
143
+ // 6. Sync setup.mjs
144
+ const setupMjsPath = path.join(rootDir, 'setup.mjs');
145
+ if (fs.existsSync(setupMjsPath)) {
146
+ let content = fs.readFileSync(setupMjsPath, 'utf8');
147
+ const orig = content;
148
+
149
+ content = content.replace(/Skill profile tier: full \(\d+\)/g, `Skill profile tier: full (${skillCount})`);
150
+ content = content.replace(/All \d+ curated skills/g, `All ${skillCount} curated skills`);
151
+
152
+ if (content !== orig) {
153
+ if (!dryRun) fs.writeFileSync(setupMjsPath, content, 'utf8');
154
+ modified = true;
155
+ }
156
+ }
157
+
158
+ return { skillCount, suiteCount, modified };
159
+ } catch (err) {
160
+ console.error('Error during catalog count synchronization:', err);
161
+ return null;
162
+ }
163
+ }
164
+
165
+ module.exports = {
166
+ syncCatalogCounts
167
+ };
@@ -0,0 +1,57 @@
1
+ 'use strict';
2
+
3
+ const fs = require('node:fs');
4
+ const path = require('node:path');
5
+
6
+ /**
7
+ * Updates Hermes Agent's config.yaml to set model context_length to maximum allowable tokens.
8
+ * Performs surgical in-place replacement preserving all comments, indentation, and structure.
9
+ */
10
+ function updateHermesConfigContext(hermesDir, modelContextMap, dryRun = false) {
11
+ const configPath = path.join(hermesDir, 'config.yaml');
12
+ if (!fs.existsSync(configPath)) return false;
13
+
14
+ try {
15
+ let content = fs.readFileSync(configPath, 'utf8');
16
+ let modified = false;
17
+
18
+ // Fix base_url if it's missing the /v1 suffix (Hermes requires /v1 for model discovery)
19
+ const baseUrlRegex = /(base_url:[ \t]*["']https:\/\/ghostcli\.cloud)(["'])/g;
20
+ if (baseUrlRegex.test(content)) {
21
+ content = content.replace(baseUrlRegex, '$1/v1$2');
22
+ modified = true;
23
+ }
24
+
25
+ for (const [modelId, maxTokens] of Object.entries(modelContextMap)) {
26
+ if (!maxTokens) continue;
27
+
28
+ // Escape dots or special chars in modelId (e.g. claude-fable-5.1)
29
+ const escapedModel = modelId.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
30
+
31
+ // Match pattern like:
32
+ // claude-opus-5-5:
33
+ // context_length: 256000
34
+ const regex = new RegExp(`(${escapedModel}:[\\r\\n]+(?:[ \\t]+.*[\\r\\n]+)*?[ \\t]+context_length:[ \\t]*)(\\d+)`, 'm');
35
+ const match = content.match(regex);
36
+ if (match) {
37
+ const currentTokens = parseInt(match[2], 10);
38
+ if (currentTokens < maxTokens) {
39
+ content = content.replace(regex, `$1${maxTokens}`);
40
+ modified = true;
41
+ }
42
+ }
43
+ }
44
+
45
+ if (modified && !dryRun) {
46
+ fs.writeFileSync(configPath, content, 'utf8');
47
+ }
48
+
49
+ return modified;
50
+ } catch {
51
+ return false;
52
+ }
53
+ }
54
+
55
+ module.exports = {
56
+ updateHermesConfigContext
57
+ };
@@ -0,0 +1,123 @@
1
+ 'use strict';
2
+
3
+ /**
4
+ * Authoritative Canonical Context Mappings (Max Capacity)
5
+ * Derived from playbooks/06-model-registry-matrix.md
6
+ */
7
+ const CANONICAL_MODEL_CONTEXTS = {
8
+ // Google Gemini Direct
9
+ 'gemini-4': 2097152,
10
+ 'gemini-4-argon': 2097152,
11
+ 'argon': 2097152,
12
+ 'gemini-3.1-pro': 2097152,
13
+ 'gemini-3.8-flash': 1048576,
14
+
15
+ // GhostCLI / Custom Proxies (Max extended capacity)
16
+ 'claude-opus-5-5': 1000000,
17
+ 'claude-sonnet-5': 1000000,
18
+ 'claude-fable-5.1': 1000000,
19
+ 'z-ai/glm-5.3': 1000000,
20
+ 'glm-5.3': 1000000,
21
+ 'gpt-6-astra': 1000000,
22
+ 'astra': 1000000
23
+ };
24
+
25
+ /**
26
+ * Normalizes token numbers into an integer token count and human-readable label.
27
+ */
28
+ function normalizeContextTokens(raw) {
29
+ let tokens = 0;
30
+ if (typeof raw === 'number') {
31
+ tokens = Math.round(raw);
32
+ } else if (typeof raw === 'string') {
33
+ const trimmed = raw.trim().toUpperCase();
34
+ if (trimmed.endsWith('M')) {
35
+ const num = parseFloat(trimmed.replace('M', ''));
36
+ tokens = Math.round(num * 1000000);
37
+ } else if (trimmed.endsWith('K')) {
38
+ const num = parseFloat(trimmed.replace('K', ''));
39
+ tokens = Math.round(num * 1000);
40
+ } else {
41
+ tokens = parseInt(trimmed, 10) || 0;
42
+ }
43
+ }
44
+
45
+ if (tokens <= 0) {
46
+ tokens = 131072; // 128K baseline default
47
+ }
48
+
49
+ let label = '';
50
+ if (tokens >= 1900000) {
51
+ label = '2M';
52
+ } else if (tokens >= 950000) {
53
+ label = '1M';
54
+ } else if (tokens === 131072 || (tokens >= 125000 && tokens <= 135000)) {
55
+ label = '128K';
56
+ } else if (tokens === 262144 || (tokens >= 250000 && tokens <= 265000)) {
57
+ label = '256K';
58
+ } else {
59
+ label = `${Math.round(tokens / 1000)}K`;
60
+ }
61
+
62
+ return { tokens, label };
63
+ }
64
+
65
+ /**
66
+ * Resolves the maximum context window for a model.
67
+ * Prioritizes maximum allowable context (e.g. 1M extended capacity for Claude 5.5/5),
68
+ * falling back to canonical matrices when remote API does not specify it.
69
+ */
70
+ function resolveModelMaxContext(model, options = {}) {
71
+ const prioritizeMax = options.prioritizeMax !== false;
72
+ const modelId = typeof model === 'string' ? model : (model?.id || model?.slug || '');
73
+ const cleanId = modelId.toLowerCase().trim();
74
+
75
+ const canonicalTokens = CANONICAL_MODEL_CONTEXTS[cleanId] ||
76
+ CANONICAL_MODEL_CONTEXTS[cleanId.split('/').pop()] ||
77
+ null;
78
+
79
+ let rawContext = null;
80
+ if (typeof model === 'object' && model !== null) {
81
+ rawContext = model.context_window || model.max_context_tokens || model.context;
82
+ }
83
+
84
+ // If user requests maximum context and canonical defines an extended limit (e.g. 1M vs 256K)
85
+ if (prioritizeMax && canonicalTokens) {
86
+ return normalizeContextTokens(canonicalTokens);
87
+ }
88
+
89
+ if (rawContext) {
90
+ return normalizeContextTokens(rawContext);
91
+ }
92
+
93
+ if (canonicalTokens) {
94
+ return normalizeContextTokens(canonicalTokens);
95
+ }
96
+
97
+ return normalizeContextTokens(131072); // 128K safe fallback
98
+ }
99
+
100
+ /**
101
+ * Resolves the live /v1/models endpoint URL when a custom proxy/vendor endpoint is configured.
102
+ * Returns null when only official 1P endpoints (Anthropic, OpenAI, Google OAuth) are active.
103
+ */
104
+ function resolveCustomModelsEndpoint(endpoints = {}) {
105
+ const candidates = [endpoints.claude, endpoints.codex];
106
+ for (const raw of candidates) {
107
+ if (!raw || typeof raw !== 'string' || !raw.startsWith('http')) continue;
108
+ if (raw.includes('api.anthropic.com') || raw.includes('api.openai.com')) continue;
109
+ if (raw.includes('ghostcli.cloud')) {
110
+ return 'https://ghostcli.cloud/v1/models';
111
+ }
112
+ const base = raw.replace(/\/+$/, '');
113
+ return base.endsWith('/v1') ? `${base}/models` : (base.endsWith('/models') ? base : `${base}/v1/models`);
114
+ }
115
+ return null;
116
+ }
117
+
118
+ module.exports = {
119
+ CANONICAL_MODEL_CONTEXTS,
120
+ normalizeContextTokens,
121
+ resolveModelMaxContext,
122
+ resolveCustomModelsEndpoint
123
+ };
@@ -0,0 +1,94 @@
1
+ 'use strict';
2
+
3
+ const fs = require('node:fs');
4
+ const path = require('node:path');
5
+ const os = require('node:os');
6
+
7
+ const EXCLUDED_PATTERNS = [
8
+ '\\windows\\',
9
+ '\\program files\\',
10
+ '\\program files (x86)\\',
11
+ '\\programdata\\',
12
+ '/usr/sbin',
13
+ '/sbin',
14
+ '\\powershell',
15
+ 'jdk',
16
+ 'jre',
17
+ 'javapath',
18
+ 'oracle',
19
+ 'antigravity-cli',
20
+ '\\appdata\\local\\programs\\',
21
+ '\\appdata\\local\\microsoft\\windowsapps',
22
+ '\\appdata\\local\\agy\\',
23
+ '\\appdata\\local\\hermes\\',
24
+ '\\.codex\\packages\\',
25
+ '\\git\\cmd',
26
+ '\\git\\bin',
27
+ '\\git\\usr\\bin',
28
+ '\\nodejs',
29
+ '\\dotnet'
30
+ ];
31
+
32
+ function isExcludedPath(lowerPath) {
33
+ const normalized = lowerPath.replace(/\//g, '\\');
34
+ return EXCLUDED_PATTERNS.some(pattern => normalized.includes(pattern) || lowerPath.includes(pattern));
35
+ }
36
+
37
+ function scoreCandidate(resolvedPath) {
38
+ const lower = resolvedPath.toLowerCase().replace(/\//g, '\\');
39
+ let score = 0;
40
+
41
+ try {
42
+ const files = fs.readdirSync(resolvedPath);
43
+ if (files.some(f => f === 'heimdall.ps1' || f === 'heimdall.cmd' || f === 'claude-bridge.ps1' || f === 'gemini-bridge.ps1')) {
44
+ score += 100;
45
+ }
46
+ } catch {}
47
+
48
+ if (lower.endsWith('\\tools') || lower.includes('\\tools\\')) score += 50;
49
+ if (lower.includes('heimdall')) score += 40;
50
+ if (lower.endsWith('\\.local\\bin')) score += 30;
51
+ if (lower.includes('\\apps\\')) score += 20;
52
+
53
+ return score;
54
+ }
55
+
56
+ function detectPathCandidates(pathEnv = process.env.PATH || '', userHome = os.homedir()) {
57
+ const rawDirs = pathEnv.split(path.delimiter).map(d => d.trim()).filter(Boolean);
58
+ const candidates = [];
59
+ const seen = new Set();
60
+
61
+ for (const raw of rawDirs) {
62
+ try {
63
+ const resolved = path.resolve(raw);
64
+ const lower = resolved.toLowerCase();
65
+ if (seen.has(lower)) continue;
66
+ seen.add(lower);
67
+
68
+ if (fs.existsSync(resolved) && !isExcludedPath(lower)) {
69
+ const isToolLike = lower.includes('tool') ||
70
+ lower.includes('bin') ||
71
+ lower.includes('.local') ||
72
+ lower.includes('apps') ||
73
+ lower.includes('npm') ||
74
+ lower.includes('cargo') ||
75
+ lower.includes('heimdall');
76
+ if (isToolLike) {
77
+ candidates.push(resolved);
78
+ }
79
+ }
80
+ } catch {}
81
+ }
82
+
83
+ candidates.sort((a, b) => scoreCandidate(b) - scoreCandidate(a));
84
+
85
+ if (candidates.length === 0) {
86
+ candidates.push(path.join(userHome, '.heimdall', 'bin'));
87
+ }
88
+
89
+ return candidates;
90
+ }
91
+
92
+ module.exports = {
93
+ detectPathCandidates
94
+ };
package/package.json CHANGED
@@ -1,11 +1,11 @@
1
1
  {
2
2
  "name": "heimdall-agent",
3
- "version": "1.0.0",
3
+ "version": "1.2.0",
4
4
  "description": "Autonomous multi-agent engineering sentinel & bootstrapper. Synchronizes specialized agent personas, curated skills, and universal doctrine across Google Antigravity, Claude Code, OpenAI Codex CLI, Hermes Agent, OpenClaw, and Claude Desktop.",
5
5
  "type": "module",
6
6
  "bin": {
7
- "heimdall": "./setup.mjs",
8
- "heimdall-agent": "./setup.mjs"
7
+ "heimdall": "setup.mjs",
8
+ "heimdall-agent": "setup.mjs"
9
9
  },
10
10
  "files": [
11
11
  "setup.mjs",
@@ -16,14 +16,18 @@
16
16
  "commands",
17
17
  "hooks",
18
18
  "tools",
19
+ "lib",
19
20
  "config",
20
21
  "docs",
21
22
  "README.md",
22
23
  "LICENSE"
23
24
  ],
24
25
  "scripts": {
26
+ "test": "node --test test/*.test.mjs",
25
27
  "setup": "node setup.mjs",
26
28
  "audit": "node setup.mjs --audit",
29
+ "sync": "node setup.mjs sync",
30
+ "sync-models": "node setup.mjs sync-models",
27
31
  "uninstall": "node setup.mjs --uninstall",
28
32
  "minimal": "node setup.mjs --profile minimal",
29
33
  "full": "node setup.mjs --profile full"
@@ -23,19 +23,36 @@ Before generating any code, creating plans, or taking action on any user request
23
23
  - **Tier 3: Architectural**: Subsystem addition, schema migration, auth boundary, or multi-component flow. Full Google EGM Pipeline (Artifact-First design spec in `docs/designs/<feature>.md` + 4-stage Goldfish review: Zoom Out, Comprehension, Critic, Readiness).
24
24
  - Never assume missing requirements. Uncover implicit user assumptions upfront.
25
25
 
26
- 2. **The 3-Point Questioning Rule**:
27
- - Ask at least 2–3 probing questions about:
28
- a) Non-obvious edge cases, error states, and boundary conditions.
29
- b) Data flow, persistence, and concurrency/race concerns.
30
- c) The exact definition of success and acceptance criteria.
26
+ 2. **The Design Tree Frontier & Questioning Protocol**:
27
+ - **Autonomous Fact-Finding First**: Inspect files, configs, and existing helpers before asking. Never ask the human questions the repository already answers.
28
+ - **Frontier Rounds**: Ask only questions whose prerequisites are settled now. If Question B depends on Question A's answer, defer Question B to the next round.
29
+ - **The "Yes-to-Approve" Triage Format**: Formulate each question with an explicit recommendation so the user can accept by replying *"yes"* or providing a 1-line tweak.
31
30
 
32
31
  3. **Present 2 Concrete Architectural Alternatives**:
33
32
  - Offer Approach A (minimal, lighter, faster) vs. Approach B (robust, extensible).
34
33
  - Detail the explicit tradeoffs of each.
35
34
  - Declare your professional recommendation with clear reasoning.
35
+ - **ADR Synchronization**: For Tier 3 architectural decisions, record settled choices in `docs/adr/YYYY-MM-DD-<title>.md`.
36
36
 
37
37
  4. **Hard Gate**:
38
- - MANDATORY VISIBLE OUTPUT: Output the Scope, Probing Questions, and Alternatives explicitly in user-visible chat markdown. Never swallow them in internal thinking/scratchpads or output a bare "awaiting answers" message.
38
+ - MANDATORY VISIBLE OUTPUT (ANTI-PATTERN BAN): NEVER keep the questions or alternatives inside internal thinking/scratchpads. NEVER output a bare "awaiting answers..." blocker message. You MUST render the Scope, Frontier Questions, and Alternatives explicitly in user-visible chat markdown using this exact template:
39
+ ```markdown
40
+ ### 1. Scope Classification
41
+ - **Scope**: [Spike / Bounded / Architectural]
42
+
43
+ ### 2. Frontier Questions (Yes-to-Approve Format)
44
+ ❓ **Q1 - [Decision Title]**: [Context, edge cases, and options]
45
+ ➡️ **Recommended**: [Explicit recommendation + rationale]
46
+
47
+ ---
48
+
49
+ ❓ **Q2 - [Decision Title]**: [Context, limits, boundary conditions]
50
+ ➡️ **Recommended**: [Explicit recommendation + rationale]
51
+
52
+ ### 3. Concrete Alternatives
53
+ - **Alternative 1**: [Description + architectural trade-offs]
54
+ - **Alternative 2**: [Description + architectural trade-offs]
55
+ ```
39
56
  - STOP and wait for the user to answer and select an approach ONLY AFTER rendering the questions in full.
40
57
  - Only after receiving explicit alignment may you proceed to planning or implementation.
41
58
  ```
@@ -19,13 +19,14 @@
19
19
  - Implement the minimal fix until the test turns green.
20
20
 
21
21
  ## 3. Deep Verification (Never Accept Shallow Checkboxes)
22
- - Verification is NOT a single unit test or a superficial DOM row count.
22
+ - STRICT ZERO DEV-SERVER RULE: NEVER spin up or run a development server (`npm run dev`, `vite`, `next dev`, `live-server`, `python manage.py runserver`, etc.) to test, verify, or make things work. All verification commands must be terminating, non-interactive CLI executions (`npm test`, `npm run build`, `npm run typecheck`, `pytest`, `oxlint`, etc.).
23
23
  - In UI applications (e.g. Playwright):
24
+ - Run tests strictly against pre-built static artifacts or against a pre-existing server already launched by the user outside the agent session. Never spawn dev servers from an agent session.
24
25
  - Always assert visible non-zero bounding box (`expect(element).toBeVisible()`).
25
26
  - Verify state transitions, loading skeletons, and error toast lifecycles.
26
27
  - Verify layout integrity at standard desktop and mobile viewports.
27
28
  - In API applications:
28
29
  - Test negative payloads (null, malformed, unauthorized).
29
30
  - Verify database transaction rollbacks and audit logs.
30
- - Never claim work is complete without displaying verifiable command output.
31
+ - Never claim work is complete without displaying verifiable command output from terminating runs.
31
32
  ```
@@ -16,11 +16,19 @@ When reviewing code, pull requests, or git diffs, assume that edge cases and def
16
16
  - **"No Glazing" Rule**: Eliminate sycophancy. Never use validating adjectives like "brilliant," "great," "smart," "perfect," or "spot-on." Ban apologies ("I apologize"). Lead with what is wrong, missing, or risky.
17
17
  - **Plain-English Standard**: Plain, direct, jargon-free technical English. No ungrounded promotional adjectives or buzzwords.
18
18
 
19
- ## 2. Two-Tier Review Trigger
20
- - **Tier 1 (Bounded & Routine Tasks)**: Single-pass adversarial critique targeting edge cases, security, and anti-slop code hygiene.
21
- - **Tier 2 (Architectural & High-Stakes Tasks)**: Mandatory **5-round convergence loop** with a structured findings ledger.
19
+ ## 2. 3-Tier Review & Handoff Policy
20
+ - **Tier 1 (Spikes & Local Fixes < 50 LOC)**:
21
+ - **Zero Review Ceremony**. Author verifies empirically via terminating automated tests (`npm test`, `pytest`).
22
+ - No peer model review or handoff document required.
23
+ - **Tier 2 (Bounded Features & Subsystems)**:
24
+ - **Single Peer Reviewer Gate**. One peer model (e.g. Claude implements -> Gemini reviews; or vice-versa) to prevent self-review blindness. Multiple reviewers are NOT needed.
25
+ - **Lean Handoff**: Feed the reviewer using the `handoff` skill (pointer to spec, target branch, and diff) to strictly maintain Goldfish blinding without leaking conversational bias.
26
+ - Single-pass adversarial critique targeting edge cases, security, and anti-slop code hygiene.
27
+ - **Tier 3 (Architectural, Auth, Schema Migrations & High-Stakes)**:
28
+ - **Multi-Model Consensus & Full Handoff**. Seeded with a formal `handoff` document referencing ADRs (`docs/adr/`) and specifications (`docs/designs/`).
29
+ - Mandatory **5-round convergence loop** with a structured findings ledger across multiple peer models.
22
30
 
23
- ## 3. The 5-Round Convergence Ledger Protocol
31
+ ## 3. The 5-Round Convergence Ledger Protocol (Tier 3)
24
32
  For Tier 2 reviews, all findings must be tracked in an authoritative ledger:
25
33
 
26
34
  ```markdown
@@ -34,9 +42,9 @@ For Tier 2 reviews, all findings must be tracked in an authoritative ledger:
34
42
  4. If round returns `"No findings"` AND all previous items are Resolved/Rebutted -> **Clean Exit**.
35
43
  5. If 5 rounds are reached with open Blockers -> **Halt and Escalate** to the user with the complete ledger. Never commit unverified code.
36
44
 
37
- ## 4. Adaptive Execution Engine (Bridge vs. Same-Model Fallback)
38
- - **Primary Route (Cross-Model Bridge)**: If multi-model bridge scripts (`claude-bridge.ps1`, `gemini-bridge.ps1`, `codex-bridge.ps1`) and active credentials exist in the user's environment, dispatch an independent model as the Goldfish reviewer.
39
- - **Graceful Fallback (Same-Model Stateless Goldfish)**: If bridge tools or credentials are absent, fire a fresh, isolated child subagent on the current harness and model with zero conversational context. The stateless Goldfish discipline is strictly preserved.
45
+ ## 4. Adaptive Execution Engine (Herdr Multiplexing vs. Same-Model Fallback)
46
+ - **Primary Route in Herdr (Native Herdr Agent)**: When running inside Herdr (`$env:HERDR_ENV = "1"`), orchestrate the Goldfish reviewer directly via the `herdr` skill (`herdr agent start reviewer --kind <claude|codex|agy> --pane <id>` and `herdr agent prompt reviewer "..." --wait`). Re-use live idle agents first.
47
+ - **Graceful Fallback (Same-Model Stateless Goldfish)**: If outside Herdr or peer agents are unavailable, fire a fresh, isolated child subagent on the current harness and model with zero conversational context. The stateless Goldfish discipline is strictly preserved.
40
48
 
41
49
  ## 5. Adversarial Scrutiny & Silent Failure Hunter Checklist
42
50
  - [ ] **Empty Catch Blocks**: Does any `catch (e) {}` or `.catch(() => [])` swallow exceptions without logging, tracing, or propagation?