rungate 0.2.0 → 0.3.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 (282) hide show
  1. package/bin/rungate.ts +70 -0
  2. package/lib/aes-calculator.ts +66 -0
  3. package/lib/agent-audit.ts +139 -0
  4. package/lib/agent-brief-validation.ts +359 -0
  5. package/lib/agents-md-refs.ts +90 -0
  6. package/lib/bash-file-read.ts +197 -0
  7. package/lib/behavioral-cache.ts +78 -0
  8. package/lib/branch-cleanup.ts +234 -0
  9. package/lib/brief-context-parser.ts +35 -0
  10. package/lib/canary.ts +117 -0
  11. package/lib/check-registry.ts +226 -0
  12. package/lib/ci-checkout.ts +400 -0
  13. package/lib/cli-commands.ts +137 -0
  14. package/lib/compliance-backfill.ts +220 -0
  15. package/lib/compliance-report.ts +504 -0
  16. package/lib/compliance.ts +361 -0
  17. package/lib/config-loader.ts +255 -0
  18. package/lib/conformity.ts +1818 -131
  19. package/lib/container-provenance.ts +230 -0
  20. package/lib/create-brief.ts +150 -0
  21. package/lib/create-sc.ts +272 -0
  22. package/lib/deep-merge.ts +69 -0
  23. package/lib/dev-liveness.ts +214 -0
  24. package/lib/directive-extractor.ts +210 -0
  25. package/lib/distribution-standing.ts +113 -0
  26. package/lib/doc-hygiene.ts +238 -0
  27. package/lib/eval-criteria.ts +6 -0
  28. package/lib/evidence-portability.ts +123 -0
  29. package/lib/evidence-prevalidator.ts +390 -0
  30. package/lib/evidence-required.ts +150 -0
  31. package/lib/evidence-satisfiability.ts +288 -0
  32. package/lib/frontmatter.ts +163 -0
  33. package/lib/gap-scanner.ts +348 -0
  34. package/lib/gate-enforcement.ts +366 -0
  35. package/lib/generators/agent-briefs.ts +136 -0
  36. package/lib/generators/agents-md.ts +506 -0
  37. package/lib/generators/code-map.ts +60 -0
  38. package/lib/generators/types.ts +184 -0
  39. package/lib/git-ref-normalizer.ts +107 -0
  40. package/lib/github.ts +539 -0
  41. package/lib/harness-identity.ts +63 -0
  42. package/lib/hill-climb.ts +164 -0
  43. package/lib/instruction-effectiveness.ts +131 -0
  44. package/lib/issue-closure-audit.ts +225 -0
  45. package/lib/issue-create-override.ts +343 -0
  46. package/lib/js-top-level-code.ts +250 -0
  47. package/lib/liveness-contradiction.ts +149 -0
  48. package/lib/organize.ts +505 -0
  49. package/lib/paths.ts +197 -6
  50. package/lib/post-fix-verify.ts +157 -0
  51. package/lib/prior-branch.ts +489 -0
  52. package/lib/project-state-shape.ts +166 -0
  53. package/lib/promote-outputs.ts +156 -0
  54. package/lib/prove-label-gate.ts +35 -0
  55. package/lib/reachability.ts +302 -0
  56. package/lib/release-preflight.ts +186 -0
  57. package/lib/rule-health-pipeline.ts +264 -0
  58. package/lib/rule-health-trend.ts +161 -0
  59. package/lib/rule-provenance.ts +149 -0
  60. package/lib/rule-registry.ts +128 -0
  61. package/lib/rungate-schema.ts +114 -4
  62. package/lib/sc-claim-forms.ts +179 -0
  63. package/lib/sc-cover.ts +150 -0
  64. package/lib/sc-guard.ts +157 -0
  65. package/lib/sc-ids.ts +344 -0
  66. package/lib/scaffold/defaults.ts +165 -0
  67. package/lib/scaffold/managed-workflow.ts +370 -0
  68. package/lib/scaffold/owned-files.ts +265 -0
  69. package/lib/scaffold/steps.ts +2680 -0
  70. package/lib/scanner.ts +701 -0
  71. package/lib/screenshot-upload.ts +73 -0
  72. package/lib/secret-patterns.ts +112 -0
  73. package/lib/security-verdict.ts +616 -0
  74. package/lib/signal-phrases.ts +1 -0
  75. package/lib/spec-change-conformity.ts +80 -0
  76. package/lib/spec-files.ts +62 -0
  77. package/lib/spec-registry.ts +133 -0
  78. package/lib/spec-updater.ts +96 -0
  79. package/lib/stale-cleanup.ts +224 -0
  80. package/lib/stale-issue-scanner.ts +36 -0
  81. package/lib/strip-js-comments.ts +269 -0
  82. package/lib/suite-measurement.ts +228 -0
  83. package/lib/task-completion-checks.ts +177 -0
  84. package/lib/test-suite-lock.ts +1136 -0
  85. package/lib/transcript-checker.ts +1140 -0
  86. package/lib/validators/spec-validators.ts +171 -0
  87. package/lib/verdict-capture.ts +73 -0
  88. package/lib/verified-push.ts +358 -0
  89. package/lib/workflow-security.ts +174 -0
  90. package/lib/worktree-cleanup.ts +250 -0
  91. package/lib/worktree-collect.ts +283 -0
  92. package/lib/worktree-isolation.ts +82 -0
  93. package/package.json +36 -3
  94. package/prompts/ac-adversary.md +14 -2
  95. package/prompts/aditi.md +5 -0
  96. package/prompts/blast-radius.md +5 -0
  97. package/prompts/container-verify.md +5 -0
  98. package/prompts/discovery.md +4 -0
  99. package/prompts/environment.md +5 -0
  100. package/prompts/evidence-hierarchy.md +5 -0
  101. package/prompts/evidence-validator.md +11 -0
  102. package/prompts/marcus.md +5 -0
  103. package/prompts/prevention.md +5 -0
  104. package/prompts/prove-reproducer.md +12 -0
  105. package/prompts/quinn-decision-tree.md +5 -0
  106. package/prompts/quinn-ui-brief.md +5 -0
  107. package/prompts/quinn.md +5 -0
  108. package/prompts/rca.md +5 -0
  109. package/prompts/read-before-write.md +4 -0
  110. package/prompts/regression.md +5 -0
  111. package/prompts/serena.md +5 -0
  112. package/scripts/audit-specs.ts +464 -0
  113. package/scripts/convert-spec.ts +293 -0
  114. package/scripts/create-sc.ts +92 -0
  115. package/scripts/create-spec.ts +166 -0
  116. package/scripts/extract-constraints.ts +4 -3
  117. package/scripts/generate-code-map.ts +1 -1
  118. package/scripts/scaffold-project.ts +138 -1426
  119. package/scripts/sync-spec-tests.ts +211 -126
  120. package/.claude/agents/aditi.md +0 -47
  121. package/.claude/agents/marcus.md +0 -50
  122. package/.claude/agents/quinn.md +0 -58
  123. package/.claude/agents/rook.md +0 -47
  124. package/.claude/agents/serena.md +0 -46
  125. package/.claude/rungate.json +0 -11
  126. package/.fallowrc.json +0 -28
  127. package/.github/copilot-instructions.md +0 -20
  128. package/.rungate/conformity-findings.json +0 -648
  129. package/AGENTS.md +0 -106
  130. package/CODE-MAP.md +0 -50
  131. package/HARNESS.md +0 -88
  132. package/bun.lock +0 -26
  133. package/bunfig.toml +0 -2
  134. package/config/brief-policies.json +0 -28
  135. package/config/ceremony-profiles.json +0 -212
  136. package/config/consumer-cascade-map.json +0 -24
  137. package/config/doc-cascade-map.json +0 -24
  138. package/config/eval.json +0 -84
  139. package/config/profiles/account-plan.yaml +0 -36
  140. package/config/profiles/campaign.yaml +0 -94
  141. package/config/prove-evidence.schema.json +0 -65
  142. package/config/spec-policies.json +0 -36
  143. package/config/workflow-schema.json +0 -281
  144. package/gates/SCHEMA-GUIDE.md +0 -121
  145. package/gates/ac-quality.test.ts +0 -106
  146. package/gates/adversarial.test.ts +0 -274
  147. package/gates/brief-assembler.test.ts +0 -429
  148. package/gates/brief-assembler.ts +0 -334
  149. package/gates/bunfig.toml +0 -2
  150. package/gates/chain.test.ts +0 -91
  151. package/gates/e2e-smoke.test.ts +0 -234
  152. package/gates/error-classifier.test.ts +0 -249
  153. package/gates/error-classifier.ts +0 -89
  154. package/gates/orchestrator.test.ts +0 -950
  155. package/gates/orchestrator.ts +0 -569
  156. package/gates/preload.ts +0 -77
  157. package/gates/prompts/ac-adversary.md +0 -20
  158. package/gates/prompts/evidence-validator.md +0 -22
  159. package/gates/prompts/prove-reproducer.md +0 -53
  160. package/gates/prove.test.ts +0 -164
  161. package/gates/run-gate.ts +0 -936
  162. package/gates/schema-parity.test.ts +0 -197
  163. package/gates/schema.ts +0 -362
  164. package/gates/self-heal.test.ts +0 -511
  165. package/gates/self-heal.ts +0 -121
  166. package/gates/ship-orchestrator.test.ts +0 -379
  167. package/gates/ship-orchestrator.ts +0 -363
  168. package/gates/test-fixtures/broken-no-environments.json +0 -60
  169. package/gates/test-fixtures/valid-standard.json +0 -54
  170. package/gates/test-utils.ts +0 -43
  171. package/gates/witness.ts +0 -220
  172. package/gates/workflow.test.ts +0 -1053
  173. package/hooks/AgentBriefGuard.hook.ts +0 -586
  174. package/hooks/AgentVerdictCapture.hook.ts +0 -134
  175. package/hooks/AutoVerifyGate.hook.ts +0 -76
  176. package/hooks/GateEnforcement.hook.ts +0 -273
  177. package/hooks/IssueCloseGuard.hook.ts +0 -116
  178. package/hooks/MergeGuard.hook.ts +0 -55
  179. package/hooks/StaleTTLCleanup.hook.ts +0 -133
  180. package/hooks/VerifyPhaseLock.hook.ts +0 -81
  181. package/hooks/WorkflowStateGuard.hook.ts +0 -37
  182. package/hooks/lib/agentDetection.ts +0 -70
  183. package/hooks/lib/findWorkflow.ts +0 -101
  184. package/hooks/lib/parseStdin.ts +0 -37
  185. package/hooks/lib/paths.ts +0 -111
  186. package/hooks/lib/utils.ts +0 -81
  187. package/reference/migration-manifest.json +0 -554
  188. package/reference/prompts/agent-aditi.md +0 -38
  189. package/reference/prompts/agent-marcus.md +0 -38
  190. package/reference/prompts/agent-quinn.md +0 -38
  191. package/reference/prompts/agent-rook.md +0 -37
  192. package/reference/prompts/agent-serena.md +0 -37
  193. package/reference/prompts/council-skill.md +0 -170
  194. package/reference/prompts/goal-skill.md +0 -235
  195. package/reference/prompts/prove-skill.md +0 -283
  196. package/reference/prompts/quinn-standard.md +0 -246
  197. package/reference/prompts/ship-convergence.md +0 -65
  198. package/reference/prompts/ship-escalation.md +0 -43
  199. package/reference/prompts/ship-iteration.md +0 -382
  200. package/reference/prompts/ship-pending-patches.md +0 -246
  201. package/reference/prompts/ship-reference.md +0 -250
  202. package/reference/prompts/ship-skill.md +0 -347
  203. package/reference/prompts/ship-templates.md +0 -215
  204. package/reference/scripts/batch-status.sh +0 -68
  205. package/reference/scripts/chain-compat-check.sh +0 -67
  206. package/reference/scripts/context-audit.sh +0 -314
  207. package/reference/scripts/dead-export-check.sh +0 -61
  208. package/reference/scripts/generate-qc-tables.sh +0 -92
  209. package/reference/scripts/harness-init.sh +0 -111
  210. package/reference/scripts/pai-054-baseline-check.sh +0 -40
  211. package/reference/scripts/prove-smoke-test.sh +0 -112
  212. package/reference/scripts/setup-keychain-salt.sh +0 -12
  213. package/reference/scripts/skill-optimizer-friday.sh +0 -88
  214. package/reference/scripts/skill-qc-test.sh +0 -351
  215. package/reference/scripts/skill-synthesize-tonight.sh +0 -66
  216. package/reference/specs/HARNESS-EXTRACTION-SPEC.md +0 -263
  217. package/reference/specs/harness-v3-bash-deletion-plan.md +0 -65
  218. package/reference/specs/harness-v3-migration-plan.md +0 -188
  219. package/scripts/decision-reconcile.sh +0 -74
  220. package/scripts/decision-reconcile.ts +0 -152
  221. package/scripts/git-hooks/pre-commit +0 -76
  222. package/scripts/git-hooks/pre-push +0 -271
  223. package/scripts/harness-skill-check.sh +0 -52
  224. package/scripts/lib/gap-emit.sh +0 -65
  225. package/scripts/lib/jq-update.sh +0 -30
  226. package/scripts/lib/resolve-slug.sh +0 -30
  227. package/scripts/lib/verify-spec-compliance.sh +0 -102
  228. package/scripts/prove-backfill.sh +0 -87
  229. package/scripts/scaffold-rungate-config.ts +0 -91
  230. package/scripts/self-containment-check.sh +0 -109
  231. package/scripts/skill-qc-validator.sh +0 -402
  232. package/scripts/slug-resolver.sh +0 -14
  233. package/specs/BOOTSTRAP-DATA-FLOW-SPEC.md +0 -2493
  234. package/specs/BOOTSTRAP-TEST-PLAN.md +0 -571
  235. package/specs/HARNESS-GATES.md +0 -256
  236. package/specs/HARNESS-SKILL-CHAIN.md +0 -286
  237. package/specs/HARNESS-SKILL-CONTRACT.md +0 -93
  238. package/specs/HARNESS-STANDARD.md +0 -488
  239. package/specs/SPEC-TEMPLATE.md +0 -53
  240. package/specs/bootstrap-data-flow.png +0 -0
  241. package/specs/harness-automation-matrix.md +0 -314
  242. package/specs/harness-automation-matrix.rules.json +0 -64
  243. package/test/anti.test.ts +0 -80
  244. package/test/contract-negative.test.ts +0 -86
  245. package/test/contract.test.ts +0 -158
  246. package/test/external-deps.test.ts +0 -48
  247. package/test/fixtures/golden-project/.env.example +0 -3
  248. package/test/fixtures/golden-project/Makefile +0 -7
  249. package/test/fixtures/golden-project/docs/adr/ADR-001-framework.md +0 -23
  250. package/test/fixtures/golden-project/docs/setup-guide.md +0 -10
  251. package/test/fixtures/golden-project/package.json +0 -10
  252. package/test/fixtures/golden-project/specs/api-spec.md +0 -20
  253. package/test/fixtures/golden-project/src/auth.ts +0 -8
  254. package/test/fixtures/golden-project/src/db.ts +0 -11
  255. package/test/fixtures/golden-project/src/index.ts +0 -19
  256. package/test/fixtures/golden-project/src/utils/format.ts +0 -3
  257. package/test/fixtures/golden-project/test/auth.test.ts +0 -15
  258. package/test/fixtures/golden-project/tsconfig.json +0 -12
  259. package/test/meta-sc-coverage.test.ts +0 -159
  260. package/test/phase-0.test.ts +0 -846
  261. package/test/phase-1.test.ts +0 -617
  262. package/test/phase-2.test.ts +0 -620
  263. package/test/phase-3.test.ts +0 -99
  264. package/test/scaffold-conformity.test.ts +0 -8
  265. package/test/schema-canary.test.ts +0 -51
  266. package/test/spec-compliance-auto.test.ts +0 -64
  267. package/test/spec-compliance.test.ts +0 -295
  268. package/test/spec-discovery.test.ts +0 -68
  269. package/test/spec-drift.test.ts +0 -5
  270. package/test/structure.test.ts +0 -165
  271. package/test/unit/agent-brief-guard-ship.test.ts +0 -293
  272. package/test/unit/extract-constraints.test.ts +0 -145
  273. package/test/unit/issue-close-guard.test.ts +0 -204
  274. package/test/unit/scaffold-project.test.ts +0 -417
  275. package/test/unit/skill-cooccurrence.test.ts +0 -177
  276. package/test/unit/skill-sequence-logger.test.ts +0 -244
  277. package/test/unit/workflow-state-guard.test.ts +0 -95
  278. package/workflows/batch-ship.js +0 -295
  279. package/workflows/council.js +0 -481
  280. package/workflows/prove.js +0 -560
  281. package/workflows/ship.js +0 -789
  282. package/workflows/verify.js +0 -236
@@ -1,586 +0,0 @@
1
- #!/usr/bin/env bun
2
- /**
3
- * AgentBriefGuard.hook.ts — PreToolUse on Agent
4
- *
5
- * TRIGGER: PreToolUse (matcher: Agent)
6
- *
7
- * PURPOSE:
8
- * Validate that every named agent spawn uses the brief template from
9
- * BRIEF-TEMPLATES.md, has bypassPermissions mode, and gets sizing-aware
10
- * max_turns. Also inject single-attempt constraint.
11
- *
12
- * BYPASS (evaluated before name detection — exit 0 if any match):
13
- * B1. Council: prompt contains "council" (case-insensitive) → skip all validation
14
- * B2. Research: prompt contains "research|investigate|audit" AND lacks
15
- * implementation markers (## Task + ## Verify) → skip all validation
16
- * B3. No active ship: .ship-active absent or stale (>4h) → skip all validation
17
- * EXCEPTION: Engineer (Marcus) never bypasses — falls through to Check 3
18
- *
19
- * CHECKS (only reached during active ship with non-bypassed agents):
20
- * 1. bypassPermissions: BLOCK if mode !== "bypassPermissions"
21
- * 2. Template markers: BLOCK (Engineer) or WARN (others) if missing required markers
22
- * 3. Ship-active marker (Engineer only): BLOCK if no valid .ship-active in ~/.rungate/
23
- * 4. max_turns: WARN if not set (inject reminder)
24
- * 5. Single-attempt constraint: inject system-reminder
25
- * 6. Brief content policies: WARN if prompt missing required content patterns (from brief-policies.json)
26
- *
27
- * Named agents (matched via subagent_type or tool_input.name):
28
- * - Marcus / Engineer: ## Context, ## Task, ## Verify, ## Report back
29
- * - Quinn / QATester: ## Context, ## Environment, ## What to test, ## Report back
30
- * - Rook / Pentester: ## Context, ## Files changed this session, ## Report back
31
- * - Serena / Architect: ## Context, ## Decision needed, ## Report back
32
- * - Aditi / Designer: ## Context, ## Task, ## Design direction
33
- *
34
- * For non-named agents → exit 0 silently.
35
- *
36
- * INPUT:
37
- * - stdin: PreToolUse JSON payload { tool_name, tool_input }
38
- *
39
- * OUTPUT:
40
- * - stdout: JSON block decision OR system-reminder injection
41
- * - stderr: status messages
42
- * - exit(0): always
43
- */
44
-
45
- import {
46
- appendFileSync,
47
- existsSync,
48
- mkdirSync,
49
- readdirSync,
50
- readFileSync,
51
- statSync,
52
- } from 'fs';
53
- import { join } from 'path';
54
- import { BASE_DIR, WORK_DIR } from './lib/paths';
55
- import { parseHookInput } from './lib/parseStdin';
56
-
57
- const SIGNALS_DIR = join(BASE_DIR, 'MEMORY', 'LEARNING', 'SIGNALS');
58
- const SIGNALS_FILE = join(SIGNALS_DIR, 'signals.jsonl');
59
-
60
- // Named agent definitions: name patterns → required template markers
61
- interface AgentDef {
62
- names: string[]; // case-insensitive patterns to match in tool_input.name
63
- subagentTypes: string[]; // subagent_type values to match
64
- markers: string[]; // required template section headers
65
- label: string; // display name for logs/messages
66
- }
67
-
68
- const NAMED_AGENTS: AgentDef[] = [
69
- {
70
- names: ['marcus', 'engineer'],
71
- subagentTypes: ['Engineer'],
72
- markers: ['## Context', '## Task', '## Verify', '## Report back'],
73
- label: 'Marcus',
74
- },
75
- {
76
- names: ['quinn', 'qatester', 'qa tester'],
77
- subagentTypes: ['QATester'],
78
- markers: ['## Context', '## Environment', '## What to test', '## Report back'],
79
- label: 'Quinn',
80
- },
81
- {
82
- names: ['rook', 'pentester'],
83
- subagentTypes: ['Pentester'],
84
- markers: ['## Context', '## Files changed this session', '## Report back'],
85
- label: 'Rook',
86
- },
87
- {
88
- names: ['serena', 'architect'],
89
- subagentTypes: ['Architect'],
90
- markers: ['## Context', '## Decision needed', '## Report back'],
91
- label: 'Serena',
92
- },
93
- {
94
- names: ['aditi', 'designer'],
95
- subagentTypes: ['Designer'],
96
- markers: ['## Context', '## Task', '## Design direction'],
97
- label: 'Aditi',
98
- },
99
- ];
100
-
101
- // Sizing → max_turns mapping
102
- const SIZE_MAX_TURNS: Record<string, number> = {
103
- XS: 20,
104
- S: 30,
105
- M: 50,
106
- L: 75,
107
- };
108
- const DEFAULT_MAX_TURNS = 30;
109
-
110
- interface HookInput {
111
- tool_name?: string;
112
- tool_input?: {
113
- prompt?: string;
114
- description?: string;
115
- mode?: string;
116
- model?: string;
117
- subagent_type?: string;
118
- max_turns?: number;
119
- run_in_background?: boolean;
120
- isolation?: string;
121
- name?: string;
122
- [k: string]: unknown;
123
- };
124
- }
125
-
126
-
127
- function logSignal(event: Record<string, unknown>): void {
128
- try {
129
- if (!existsSync(SIGNALS_DIR)) mkdirSync(SIGNALS_DIR, { recursive: true });
130
- if (existsSync(SIGNALS_FILE)) {
131
- appendFileSync(SIGNALS_FILE, JSON.stringify(event) + '\n', 'utf-8');
132
- }
133
- } catch (err) {
134
- console.error(`[AgentBriefGuard] Signal log write failed: ${err}`);
135
- }
136
- }
137
-
138
- /**
139
- * Detect which named agent (if any) is being spawned.
140
- * Checks subagent_type first, then matches name patterns against tool_input.name only.
141
- */
142
- function detectAgent(input: HookInput): AgentDef | null {
143
- const toolInput = input.tool_input || {};
144
- const subagentType = (toolInput.subagent_type || '').trim();
145
- const agentName = (toolInput.name || '').toLowerCase();
146
-
147
- for (const agent of NAMED_AGENTS) {
148
- // Check subagent_type first (most reliable)
149
- if (subagentType && agent.subagentTypes.includes(subagentType)) {
150
- return agent;
151
- }
152
- // Fall back to name pattern matching in tool_input.name only
153
- if (agentName) {
154
- for (const name of agent.names) {
155
- if (agentName.includes(name.toLowerCase())) {
156
- return agent;
157
- }
158
- }
159
- }
160
- }
161
- return null;
162
- }
163
-
164
- /**
165
- * Find the most recent checkpoint and extract sizing.
166
- * Looks for **Size:** or ## Sizing in CHECKPOINT.md files.
167
- */
168
- function findSizingFromCheckpoint(): string | null {
169
- try {
170
- if (!existsSync(WORK_DIR)) return null;
171
-
172
- // Get subdirectories sorted by mtime (most recent first)
173
- const entries = readdirSync(WORK_DIR)
174
- .map(name => {
175
- const full = join(WORK_DIR, name);
176
- try {
177
- const stat = statSync(full);
178
- return { name, mtime: stat.mtimeMs, isDir: stat.isDirectory() };
179
- } catch (err) {
180
- console.error(`[brief-guard] statSync failed for ${full}: ${err}`);
181
- return null;
182
- }
183
- })
184
- .filter((e): e is NonNullable<typeof e> => e !== null && e.isDir)
185
- .sort((a, b) => b.mtime - a.mtime);
186
-
187
- // Check up to 5 most recent directories for a checkpoint with sizing
188
- for (const entry of entries.slice(0, 5)) {
189
- const checkpointPath = join(WORK_DIR, entry.name, 'CHECKPOINT.md');
190
- if (!existsSync(checkpointPath)) continue;
191
-
192
- try {
193
- const content = readFileSync(checkpointPath, 'utf-8');
194
- // Match **Size:** XS/S/M/L or ## Sizing ... XS/S/M/L
195
- const sizeMatch = content.match(/\*\*Size:\*\*\s*(XS|S|M|L)\b/i)
196
- || content.match(/##\s*Sizing[\s\S]*?\b(XS|S|M|L)\b/i);
197
- if (sizeMatch) {
198
- return sizeMatch[1].toUpperCase();
199
- }
200
- } catch (err) {
201
- console.error(`[brief-guard] checkpoint read failed for ${checkpointPath}: ${err}`);
202
- continue;
203
- }
204
- }
205
- return null;
206
- } catch (err) {
207
- console.error(`[brief-guard] findSizingFromCheckpoint failed: ${err}`);
208
- return null;
209
- }
210
- }
211
-
212
- // Ship-active marker TTL: 4 hours in milliseconds
213
- const SHIP_MARKER_TTL_MS = 4 * 60 * 60 * 1000;
214
-
215
- interface ShipMarker {
216
- issue: number;
217
- ts: string;
218
- }
219
-
220
- /**
221
- * Scan ~/.rungate/ directories for .ship-active marker files.
222
- * Returns the most recent valid marker, or null if none found.
223
- */
224
- function checkShipActive(): ShipMarker | null {
225
- if (!existsSync(WORK_DIR)) return null;
226
-
227
- const markers: ShipMarker[] = [];
228
-
229
- try {
230
- const entries = readdirSync(WORK_DIR, { withFileTypes: true });
231
- for (const entry of entries) {
232
- if (!entry.isDirectory()) continue;
233
- const markerPath = join(WORK_DIR, entry.name, '.ship-active');
234
- if (!existsSync(markerPath)) continue;
235
-
236
- try {
237
- const raw = readFileSync(markerPath, 'utf-8').trim();
238
- if (!raw.startsWith('{')) {
239
- console.error(`[brief-guard] marker not JSON object at ${markerPath}: starts with "${raw.slice(0, 20)}"`);
240
- continue;
241
- }
242
- const parsed = JSON.parse(raw) as ShipMarker;
243
- if (parsed.issue && parsed.ts) {
244
- markers.push(parsed);
245
- }
246
- } catch (err) {
247
- console.error(`[brief-guard] malformed marker at ${markerPath}: ${err}`);
248
- }
249
- }
250
-
251
- // Nested scan for 2-level slugs (e.g., pai/352/)
252
- for (const entry of entries) {
253
- if (!entry.isDirectory()) continue;
254
- try {
255
- const subEntries = readdirSync(join(WORK_DIR, entry.name), { withFileTypes: true });
256
- for (const sub of subEntries) {
257
- if (!sub.isDirectory()) continue;
258
- const nestedMarkerPath = join(WORK_DIR, entry.name, sub.name, '.ship-active');
259
- if (!existsSync(nestedMarkerPath)) continue;
260
- try {
261
- const raw = readFileSync(nestedMarkerPath, 'utf-8').trim();
262
- if (!raw.startsWith('{')) {
263
- console.error(`[brief-guard] nested marker not JSON object at ${nestedMarkerPath}: starts with "${raw.slice(0, 20)}"`);
264
- continue;
265
- }
266
- const parsed = JSON.parse(raw) as ShipMarker;
267
- if (parsed.issue && parsed.ts) markers.push(parsed);
268
- } catch (err) {
269
- console.error(`[brief-guard] malformed nested marker at ${nestedMarkerPath}: ${err}`);
270
- }
271
- }
272
- } catch (err) {
273
- console.error(`[brief-guard] nested scan failed for ${join(WORK_DIR, entry.name)}: ${err}`);
274
- }
275
- }
276
- } catch (err) {
277
- console.error(`[brief-guard] checkShipActive scan failed: ${err}`);
278
- return null;
279
- }
280
-
281
- if (markers.length === 0) return null;
282
-
283
- // Return most recent by ts field
284
- markers.sort((a, b) => new Date(b.ts).getTime() - new Date(a.ts).getTime());
285
- return markers[0];
286
- }
287
-
288
- function checkWorkflowState(): ShipMarker | null {
289
- if (!existsSync(WORK_DIR)) return null;
290
- const BUILD_PHASES = ['BUILD', 'VERIFY', 'SHIP', 'DONE'];
291
- try {
292
- const entries = readdirSync(WORK_DIR, { withFileTypes: true });
293
- for (const entry of entries) {
294
- if (!entry.isDirectory()) continue;
295
- const wfPath = join(WORK_DIR, entry.name, 'workflow-state.json');
296
- if (!existsSync(wfPath)) continue;
297
- try {
298
- const raw = readFileSync(wfPath, 'utf-8').trim();
299
- if (!raw.startsWith('{')) continue;
300
- const wf = JSON.parse(raw);
301
- if (wf.issue && wf.phase && BUILD_PHASES.includes(wf.phase)) {
302
- return { issue: wf.issue, ts: new Date().toISOString() };
303
- }
304
- } catch { /* skip malformed */ }
305
- }
306
- } catch { /* skip scan errors */ }
307
- return null;
308
- }
309
-
310
-
311
- /**
312
- * Validate brief content against policies from brief-policies.json.
313
- * Returns list of missing content field names. Empty = all present.
314
- */
315
- function validateBriefPolicies(agent: AgentDef, prompt: string): string[] {
316
- const policyPath = join(BASE_DIR, 'skills', 'ship', 'brief-policies.json');
317
- if (!existsSync(policyPath)) return [];
318
-
319
- try {
320
- const raw = readFileSync(policyPath, 'utf-8').trim();
321
- if (!raw.startsWith('{')) {
322
- console.error(`[brief-guard] brief-policies.json not JSON object: starts with "${raw.slice(0, 20)}"`);
323
- return [];
324
- }
325
- const policies = JSON.parse(raw);
326
- const agentKey = agent.label.toLowerCase();
327
- const policy = policies.policies?.[agentKey];
328
- if (!policy?.requiredPatterns) return [];
329
-
330
- const missing: string[] = [];
331
- for (const req of policy.requiredPatterns) {
332
- const regex = new RegExp(req.pattern, 'i');
333
- if (!regex.test(prompt)) {
334
- missing.push(req.name);
335
- }
336
- }
337
- return missing;
338
- } catch (err) {
339
- console.error(`[brief-guard] validateBriefPolicies failed: ${err}`);
340
- return [];
341
- }
342
- }
343
-
344
- async function main() {
345
- const input = await parseHookInput();
346
- if (!input) process.exit(0);
347
-
348
- try {
349
- // Only process Agent tool calls
350
- if (input.tool_name !== 'Agent') {
351
- process.exit(0);
352
- }
353
-
354
- const toolInput = input.tool_input || {};
355
-
356
- // === Early bypass checks (before name detection) ===
357
- // These prevent council, research, and non-ship agents from being
358
- // blocked by the specialist name detection that follows.
359
- // Order: council → research → ship-active → then name detection.
360
- const rawPrompt = toolInput.prompt || '';
361
-
362
- // Bypass 1: Council agents — never need brief templates
363
- if (/\bcouncil\b/i.test(rawPrompt)) {
364
- console.error('[AgentBriefGuard] Bypass — council agent detected');
365
- process.exit(0);
366
- }
367
-
368
- // Bypass 2: Research/investigate/audit agents without implementation markers
369
- // If prompt has implementation brief markers (## Task + ## Verify), it's an
370
- // implementation agent that happens to mention research — don't bypass.
371
- const isResearchAgent = /\b(research|investigate|audit)\b/i.test(rawPrompt);
372
- const hasImplementationMarkers = rawPrompt.includes('## Task') && rawPrompt.includes('## Verify');
373
- if (isResearchAgent && !hasImplementationMarkers) {
374
- console.error('[AgentBriefGuard] Bypass — research/investigate/audit agent (no implementation markers)');
375
- process.exit(0);
376
- }
377
-
378
- // === Name detection (moved before Bypass 3 so Engineer check works) ===
379
- const agent = detectAgent(input);
380
-
381
- // Bypass 3: No active ship session → no brief validation needed
382
- // Brief templates are only enforced during active ship workflows.
383
- // EXCEPTION: Engineer (Marcus) agents NEVER bypass — they must always
384
- // reach Check 3 which blocks direct spawns without an active ship session.
385
- const earlyShipMarker = checkShipActive();
386
- const shipIsActive = earlyShipMarker
387
- && (Date.now() - new Date(earlyShipMarker.ts).getTime()) <= SHIP_MARKER_TTL_MS;
388
- if (!shipIsActive && agent?.label !== 'Marcus') {
389
- console.error('[AgentBriefGuard] Bypass — no active ship session');
390
- process.exit(0);
391
- }
392
-
393
- // Non-named agent → exit silently
394
- if (!agent) {
395
- process.exit(0);
396
- }
397
-
398
- const prompt = rawPrompt;
399
- const outputs: string[] = [];
400
-
401
- // Check 1: bypassPermissions
402
- const hasBypass = toolInput.mode === 'bypassPermissions';
403
- if (!hasBypass) {
404
- const decision = {
405
- decision: 'block',
406
- reason: `${agent.label} agent must use mode: "bypassPermissions". Current mode: "${toolInput.mode || 'not set'}". Without bypassPermissions, the agent hangs on permission prompts nobody sees. Add mode: "bypassPermissions" to the Agent call.`,
407
- };
408
- console.log(JSON.stringify(decision));
409
-
410
- logSignal({
411
- ts: new Date().toISOString(),
412
- type: 'agent_spawn',
413
- agent: agent.label.toLowerCase(),
414
- has_template: false,
415
- has_bypass: false,
416
- blocked: true,
417
- block_reason: 'missing_bypass_permissions',
418
- });
419
-
420
- console.error(`[AgentBriefGuard] BLOCKED ${agent.label} — missing bypassPermissions`);
421
- process.exit(0);
422
- }
423
-
424
- // Check 2: Template markers
425
- const isEngineer = agent.label === 'Marcus';
426
- const missingMarkers = agent.markers.filter(
427
- marker => !prompt.includes(marker)
428
- );
429
- if (missingMarkers.length > 0) {
430
- if (isEngineer) {
431
- // Engineer: hard BLOCK — template is mandatory
432
- const decision = {
433
- decision: 'block',
434
- reason: `${agent.label} brief doesn't use template from BRIEF-TEMPLATES.md. Missing required markers: ${missingMarkers.join(', ')}. Read BRIEF-TEMPLATES.md (in harness repo) and use the ${agent.label} template.`,
435
- };
436
- console.log(JSON.stringify(decision));
437
-
438
- logSignal({
439
- ts: new Date().toISOString(),
440
- type: 'agent_spawn',
441
- agent: agent.label.toLowerCase(),
442
- has_template: false,
443
- has_bypass: true,
444
- blocked: true,
445
- block_reason: 'missing_template_markers',
446
- missing_markers: missingMarkers,
447
- });
448
-
449
- console.error(
450
- `[AgentBriefGuard] BLOCKED ${agent.label} — missing template markers: ${missingMarkers.join(', ')}`
451
- );
452
- process.exit(0);
453
- } else {
454
- // Non-Engineer: advisory WARN — template recommended, not required
455
- console.error(
456
- `[AgentBriefGuard] WARN ${agent.label} — missing template markers (advisory): ${missingMarkers.join(', ')}`
457
- );
458
- const advisory = [
459
- '<system-reminder>',
460
- `ADVISORY: ${agent.label} brief is missing recommended template markers from BRIEF-TEMPLATES.md: ${missingMarkers.join(', ')}. Using the template improves agent output quality. Read BRIEF-TEMPLATES.md (in harness repo) for the ${agent.label} template.`,
461
- '</system-reminder>',
462
- ].join('\n');
463
- console.log(advisory);
464
-
465
- logSignal({
466
- ts: new Date().toISOString(),
467
- type: 'agent_spawn_advisory',
468
- agent: agent.label.toLowerCase(),
469
- has_template: false,
470
- has_bypass: true,
471
- blocked: false,
472
- advisory_reason: 'missing_template_markers',
473
- missing_markers: missingMarkers,
474
- });
475
- }
476
- }
477
-
478
- // Check 3: Ship-active marker (Engineer only)
479
- // Marcus must be spawned through ship — direct spawns bypass SCOPE.
480
- if (isEngineer) {
481
- const shipMarker = checkShipActive() || checkWorkflowState();
482
- const isStale = shipMarker
483
- ? (Date.now() - new Date(shipMarker.ts).getTime()) > SHIP_MARKER_TTL_MS
484
- : true;
485
-
486
- if (!shipMarker || isStale) {
487
- const decision = {
488
- decision: 'block',
489
- reason: `Engineer (Marcus) requires an active ship session. No .ship-active marker found in ~/.rungate/. Run Skill('ship') first — ship writes the marker during SCOPE. Direct Engineer spawns bypass SCOPE (templates, ACs, DISCOVERY, sizing) and produce incomplete gate artifacts.`,
490
- };
491
- console.log(JSON.stringify(decision));
492
-
493
- logSignal({
494
- ts: new Date().toISOString(),
495
- type: 'agent_spawn',
496
- agent: agent.label.toLowerCase(),
497
- has_template: true,
498
- has_bypass: true,
499
- blocked: true,
500
- block_reason: 'no_ship_session',
501
- stale_marker: shipMarker ? true : false,
502
- });
503
-
504
- console.error(
505
- `[AgentBriefGuard] BLOCKED ${agent.label} — no_ship_session${shipMarker ? ' (stale marker)' : ''}`
506
- );
507
- process.exit(0);
508
- }
509
- }
510
-
511
- // Check 6: Brief content policy validation (WARN only, never blocks)
512
- const policyMissing = validateBriefPolicies(agent, prompt);
513
- if (policyMissing.length > 0) {
514
- console.error(
515
- `[AgentBriefGuard] BRIEF CONTENT WARN: ${agent.label} brief missing: ${policyMissing.join(', ')}`
516
- );
517
- outputs.push(
518
- `BRIEF CONTENT WARN: ${agent.label} brief missing: ${policyMissing.join(', ')}. See BRIEF-TEMPLATES/${agent.label.toLowerCase()}.md for required content.`
519
- );
520
-
521
- logSignal({
522
- ts: new Date().toISOString(),
523
- type: 'agent_spawn_content_warn',
524
- agent: agent.label.toLowerCase(),
525
- missing_content: policyMissing,
526
- blocked: false,
527
- });
528
- }
529
-
530
- // All checks passed — inject advisory and single-attempt constraint
531
-
532
- // Check 4: max_turns advisory
533
- const sizing = findSizingFromCheckpoint();
534
- const recommendedMaxTurns = sizing
535
- ? SIZE_MAX_TURNS[sizing] || DEFAULT_MAX_TURNS
536
- : DEFAULT_MAX_TURNS;
537
-
538
- if (!toolInput.max_turns) {
539
- outputs.push(
540
- `NOTE: No max_turns set for ${agent.label}. ` +
541
- `Recommended: ${recommendedMaxTurns} (sizing: ${sizing || 'unknown'}).`
542
- );
543
- }
544
-
545
- // Check 5: Single-attempt constraint
546
- outputs.push(
547
- `SCOPE CONSTRAINT: Try to resolve errors within a few attempts. If you encounter a persistent error you cannot fix:`,
548
- `1. STOP — do not attempt 10+ different approaches`,
549
- `2. Report back: what you tried, the exact error, your hypothesis`,
550
- `3. Do NOT work around errors silently — surface them`
551
- );
552
-
553
- if (outputs.length > 0) {
554
- const reminder = [
555
- '<system-reminder>',
556
- ...outputs,
557
- '</system-reminder>',
558
- ].join('\n');
559
- console.log(reminder);
560
- }
561
-
562
- // Log successful spawn
563
- logSignal({
564
- ts: new Date().toISOString(),
565
- type: 'agent_spawn',
566
- agent: agent.label.toLowerCase(),
567
- has_template: true,
568
- has_bypass: true,
569
- max_turns: toolInput.max_turns || null,
570
- recommended_max_turns: recommendedMaxTurns,
571
- sizing: sizing || 'unknown',
572
- blocked: false,
573
- });
574
-
575
- console.error(
576
- `[AgentBriefGuard] ${agent.label} spawn validated — template OK, bypass OK, sizing: ${sizing || 'unknown'}`
577
- );
578
-
579
- process.exit(0);
580
- } catch (err) {
581
- console.error(`[AgentBriefGuard] Error: ${err}`);
582
- process.exit(0);
583
- }
584
- }
585
-
586
- main();