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
package/bin/rungate.ts ADDED
@@ -0,0 +1,70 @@
1
+ #!/usr/bin/env bun
2
+ /**
3
+ * The `rungate` command (#363).
4
+ *
5
+ * `AGENTS.md` published `bunx rungate create-spec` to every scaffolded
6
+ * project and `package.json` declared no `bin`, so the documented consumer
7
+ * interface did not exist. This is it.
8
+ *
9
+ * Deliberately thin: the command table is `lib/cli-commands.ts`, so the three
10
+ * things that must agree — what dispatches, what ships, what the generator
11
+ * publishes — read from one place instead of three.
12
+ */
13
+ import { existsSync } from "fs";
14
+ import { dirname, join, resolve } from "path";
15
+ import { fileURLToPath } from "url";
16
+ import { CLI_COMMANDS, helpText } from "../lib/cli-commands";
17
+
18
+ const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
19
+
20
+ const [name, ...rest] = process.argv.slice(2);
21
+
22
+ if (!name || name === "--help" || name === "-h" || name === "help") {
23
+ console.log(helpText());
24
+ process.exit(name ? 0 : 1);
25
+ }
26
+
27
+ if (name === "--version" || name === "-v") {
28
+ const pkg = await import(join(PACKAGE_ROOT, "package.json"), { with: { type: "json" } });
29
+ console.log((pkg.default ?? pkg).version);
30
+ process.exit(0);
31
+ }
32
+
33
+ const command = CLI_COMMANDS[name];
34
+ if (!command) {
35
+ console.error(`rungate: unknown command "${name}"\n`);
36
+ console.error(helpText());
37
+ process.exit(1);
38
+ }
39
+
40
+ const script = join(PACKAGE_ROOT, command.script);
41
+ if (!existsSync(script)) {
42
+ // Reachable only from an installed package whose `files` lost the script.
43
+ // Named rather than swallowed: "command does nothing" is the failure #363
44
+ // is about, and a missing file must not look like a successful run.
45
+ console.error(
46
+ `rungate: "${name}" is registered but ${command.script} is not in this ` +
47
+ `installation. The package's "files" field and lib/cli-commands.ts ` +
48
+ `disagree — see test/cli-contract.test.ts, which exists to stop this.`,
49
+ );
50
+ process.exit(1);
51
+ }
52
+
53
+ // Default the project root to where the USER is, not to where the package
54
+ // is. `scripts/create-spec.ts` ends with
55
+ // `const root = projectRoot ?? join(import.meta.dir, "..")` — right for
56
+ // `bun scripts/create-spec.ts` in this repo, and wrong for every consumer:
57
+ // `bunx rungate create-spec "Title"` would write into
58
+ // `node_modules/rungate/specs/` and print `Created specs/TITLE-SPEC.md`, so
59
+ // the command reports success and the consumer's project is untouched.
60
+ // Only added when the caller did not say otherwise, and only for commands
61
+ // that accept the flag — a script that does not would read it as a
62
+ // positional argument.
63
+ const needsRoot = command.projectRootFlag && !rest.includes("--project-root");
64
+ const args = needsRoot ? [...rest, "--project-root", process.cwd()] : rest;
65
+
66
+ // Each script reads process.argv at the top level and none guards on
67
+ // import.meta.main, so the import IS the invocation. Rewrite argv first so
68
+ // the script sees its own arguments and not the subcommand name.
69
+ process.argv = [process.argv[0], script, ...args];
70
+ await import(script);
@@ -0,0 +1,66 @@
1
+ /**
2
+ * Centralized Agent Efficiency Score (AES) calculator.
3
+ *
4
+ * Computes a weighted composite score from five component metrics:
5
+ * compliance, file efficiency, deliverable ratio, test discipline,
6
+ * and context discipline.
7
+ */
8
+
9
+ /** Input scores for AES calculation (each 0-100). */
10
+ export interface AESInput {
11
+ compliance: number;
12
+ fileEfficiency: number;
13
+ deliverableRatio: number;
14
+ testDiscipline: number;
15
+ contextDiscipline: number;
16
+ }
17
+
18
+ /** Result of an AES calculation. */
19
+ export interface AESResult {
20
+ score: number;
21
+ grade: string;
22
+ components: AESInput;
23
+ }
24
+
25
+ /** Weight assigned to each AES component. Weights sum to 1.0. */
26
+ export const AES_WEIGHTS: Readonly<AESInput> = {
27
+ compliance: 0.3,
28
+ fileEfficiency: 0.25,
29
+ deliverableRatio: 0.25,
30
+ testDiscipline: 0.1,
31
+ contextDiscipline: 0.1,
32
+ } as const;
33
+
34
+ /**
35
+ * Compute grade from a numeric score.
36
+ * A >= 90, B >= 75, C >= 60, D >= 40, F < 40.
37
+ */
38
+ function gradeFromScore(score: number): string {
39
+ if (score >= 90) return 'A';
40
+ if (score >= 75) return 'B';
41
+ if (score >= 60) return 'C';
42
+ if (score >= 40) return 'D';
43
+ return 'F';
44
+ }
45
+
46
+ /**
47
+ * Calculate the Agent Efficiency Score (AES) from component scores.
48
+ *
49
+ * Formula: compliance*0.3 + fileEfficiency*0.25 + deliverableRatio*0.25
50
+ * + testDiscipline*0.1 + contextDiscipline*0.1
51
+ */
52
+ export function calculateAES(input: AESInput): AESResult {
53
+ const score = Math.round(
54
+ input.compliance * AES_WEIGHTS.compliance +
55
+ input.fileEfficiency * AES_WEIGHTS.fileEfficiency +
56
+ input.deliverableRatio * AES_WEIGHTS.deliverableRatio +
57
+ input.testDiscipline * AES_WEIGHTS.testDiscipline +
58
+ input.contextDiscipline * AES_WEIGHTS.contextDiscipline,
59
+ );
60
+
61
+ return {
62
+ score,
63
+ grade: gradeFromScore(score),
64
+ components: input,
65
+ };
66
+ }
@@ -0,0 +1,139 @@
1
+ /**
2
+ * Agent transcript auditing logic
3
+ *
4
+ * Provides audit functionality for agent transcripts, extracting this logic
5
+ * from hooks for testability (per Hook Architecture Spec D-2).
6
+ *
7
+ * Used by: AgentVerdictCapture.hook.ts
8
+ */
9
+
10
+ import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
11
+ import { join } from 'path';
12
+ import { auditAgent, type Role } from '../scripts/audit-transcript';
13
+ import { writeCache, type BehavioralCache } from './behavioral-cache';
14
+
15
+ export interface AgentAuditResult {
16
+ role: Role;
17
+ score: number;
18
+ grade: string;
19
+ totalCalls: number;
20
+ rules: Array<{
21
+ id: string;
22
+ rule: string;
23
+ verdict: 'FOLLOWED' | 'IGNORED';
24
+ evidence: string;
25
+ weight: number;
26
+ }>;
27
+ timestamp: string;
28
+ }
29
+
30
+ /**
31
+ * Map hook agent role to audit role.
32
+ * DA orchestrates and should be graded against DA criteria.
33
+ */
34
+ export function mapRoleToAuditRole(role: string): Role {
35
+ if (role === 'quinn') return 'quinn';
36
+ if (role === 'marcus') return 'marcus';
37
+ // DA, rook, and other roles use DA criteria
38
+ return 'da';
39
+ }
40
+
41
+ /**
42
+ * Run transcript audit for an agent.
43
+ * Returns audit results or null if audit fails or transcript missing.
44
+ * Non-blocking — catches all errors.
45
+ */
46
+ export function runAgentAudit(
47
+ transcriptPath: string | undefined,
48
+ role: string,
49
+ ): AgentAuditResult | null {
50
+ if (!transcriptPath || !existsSync(transcriptPath)) {
51
+ return null;
52
+ }
53
+
54
+ try {
55
+ const auditRole = mapRoleToAuditRole(role);
56
+ const audit = auditAgent(transcriptPath, auditRole);
57
+
58
+ return {
59
+ role: audit.role,
60
+ score: audit.score,
61
+ grade: audit.grade,
62
+ totalCalls: audit.totalCalls,
63
+ rules: audit.rules.map(r => ({
64
+ id: r.id,
65
+ rule: r.rule,
66
+ verdict: r.verdict,
67
+ evidence: r.evidence,
68
+ weight: r.weight,
69
+ })),
70
+ timestamp: new Date().toISOString(),
71
+ };
72
+ } catch (error) {
73
+ // Non-blocking — log and return null
74
+ return null;
75
+ }
76
+ }
77
+
78
+ /**
79
+ * Populate behavioral-results cache from audit criteria results.
80
+ * Maps SC IDs to audit criterion verdicts via behavioral-sc-map.json.
81
+ * Non-blocking — catches all errors.
82
+ *
83
+ * Issue: #544 — extracted from AgentVerdictCapture.hook.ts
84
+ */
85
+ export function populateBehavioralCache(
86
+ auditResult: AgentAuditResult & { criteria?: Array<{ id: string; verdict: string; evidence: string }> },
87
+ projectRoot: string,
88
+ ): number {
89
+ try {
90
+ const mapPath = join(projectRoot, 'config', 'behavioral-sc-map.json');
91
+ if (!existsSync(mapPath)) return 0;
92
+
93
+ const scMap: Record<string, { criterionId: string }> = JSON.parse(readFileSync(mapPath, 'utf-8'));
94
+ const criteriaResults = auditResult.criteria || [];
95
+ const criterionMap = new Map<string, { id: string; verdict: string; evidence: string }>();
96
+ for (const r of criteriaResults) criterionMap.set(r.id, r);
97
+
98
+ const cacheData: BehavioralCache = {};
99
+ const now = new Date().toISOString();
100
+ for (const [scId, mapping] of Object.entries(scMap)) {
101
+ const result = criterionMap.get(mapping.criterionId);
102
+ if (result) {
103
+ cacheData[scId] = {
104
+ passed: result.verdict === 'FOLLOWED',
105
+ evidence: `${result.id}: ${result.evidence}`,
106
+ timestamp: now,
107
+ };
108
+ }
109
+ }
110
+
111
+ if (Object.keys(cacheData).length > 0) {
112
+ const cachePath = join(projectRoot, '.rungate', 'behavioral-results.json');
113
+ writeCache(cachePath, cacheData);
114
+ return Object.keys(cacheData).length;
115
+ }
116
+ } catch {
117
+ // Non-blocking
118
+ }
119
+ return 0;
120
+ }
121
+
122
+ /**
123
+ * Write AgentAuditResult to .rungate/audit-compliance.json.
124
+ * Creates the .rungate directory if it does not exist.
125
+ * Overwrites any previous audit-compliance.json with the new result.
126
+ *
127
+ * AC-1: writeAuditComplianceJSON export
128
+ */
129
+ export function writeAuditComplianceJSON(
130
+ result: AgentAuditResult,
131
+ projectRoot: string,
132
+ ): void {
133
+ const rungateDir = join(projectRoot, '.rungate');
134
+ if (!existsSync(rungateDir)) {
135
+ mkdirSync(rungateDir, { recursive: true });
136
+ }
137
+ const outPath = join(rungateDir, 'audit-compliance.json');
138
+ writeFileSync(outPath, JSON.stringify(result, null, 2));
139
+ }
@@ -0,0 +1,359 @@
1
+ /**
2
+ * Agent brief validation logic — extracted from AgentBriefGuard.hook.ts
3
+ *
4
+ * Deep module: contains agent definitions, ship-active detection,
5
+ * sizing lookup, brief policy validation, and the full validation pipeline.
6
+ * The hook file is a thin trigger that delegates here.
7
+ *
8
+ * Issue: #544
9
+ */
10
+
11
+ import {
12
+ appendFileSync,
13
+ existsSync,
14
+ mkdirSync,
15
+ readdirSync,
16
+ readFileSync,
17
+ statSync,
18
+ } from 'fs';
19
+ import { join } from 'path';
20
+
21
+ // --- Interfaces ---
22
+
23
+ export interface AgentDef {
24
+ names: string[];
25
+ subagentTypes: string[];
26
+ markers: string[];
27
+ label: string;
28
+ }
29
+
30
+ export interface ShipMarker {
31
+ issue: number;
32
+ ts: string;
33
+ }
34
+
35
+ export interface BriefValidationInput {
36
+ tool_name?: string;
37
+ tool_input?: {
38
+ prompt?: string;
39
+ description?: string;
40
+ mode?: string;
41
+ model?: string;
42
+ subagent_type?: string;
43
+ max_turns?: number;
44
+ run_in_background?: boolean;
45
+ isolation?: string;
46
+ name?: string;
47
+ [k: string]: unknown;
48
+ };
49
+ }
50
+
51
+ export type ValidationAction = 'pass' | 'block' | 'exit';
52
+
53
+ export interface ValidationResult {
54
+ action: ValidationAction;
55
+ blockReason?: string;
56
+ outputs: string[];
57
+ signalEvents: Record<string, unknown>[];
58
+ agent?: AgentDef;
59
+ sizing?: string | null;
60
+ recommendedMaxTurns?: number;
61
+ }
62
+
63
+ // --- Constants ---
64
+
65
+ const NAMED_AGENTS: AgentDef[] = [
66
+ {
67
+ names: ['marcus', 'engineer'],
68
+ subagentTypes: ['Engineer'],
69
+ markers: ['## Context', '## Task', '## Verify', '## Report back'],
70
+ label: 'Marcus',
71
+ },
72
+ {
73
+ names: ['quinn', 'qatester', 'qa tester'],
74
+ subagentTypes: ['QATester'],
75
+ markers: ['## Context', '## Environment', '## What to test', '## Report back'],
76
+ label: 'Quinn',
77
+ },
78
+ {
79
+ names: ['rook', 'pentester'],
80
+ subagentTypes: ['Pentester'],
81
+ markers: ['## Context', '## Files changed this session', '## Report back'],
82
+ label: 'Rook',
83
+ },
84
+ {
85
+ names: ['serena', 'architect'],
86
+ subagentTypes: ['Architect'],
87
+ markers: ['## Context', '## Decision needed', '## Report back'],
88
+ label: 'Serena',
89
+ },
90
+ {
91
+ names: ['aditi', 'designer'],
92
+ subagentTypes: ['Designer'],
93
+ markers: ['## Context', '## Task', '## Design direction'],
94
+ label: 'Aditi',
95
+ },
96
+ ];
97
+
98
+ const SIZE_MAX_TURNS: Record<string, number> = { XS: 20, S: 30, M: 50, L: 75 };
99
+ const DEFAULT_MAX_TURNS = 30;
100
+ const SHIP_MARKER_TTL_MS = 4 * 60 * 60 * 1000;
101
+
102
+ // --- Helper Functions ---
103
+
104
+ function detectAgentDef(input: BriefValidationInput): AgentDef | null {
105
+ const toolInput = input.tool_input || {};
106
+ const subagentType = (toolInput.subagent_type || '').trim();
107
+ const agentName = (toolInput.name || '').toLowerCase();
108
+
109
+ for (const agent of NAMED_AGENTS) {
110
+ if (subagentType && agent.subagentTypes.includes(subagentType)) return agent;
111
+ if (agentName) {
112
+ for (const name of agent.names) {
113
+ if (agentName.includes(name.toLowerCase())) return agent;
114
+ }
115
+ }
116
+ }
117
+ return null;
118
+ }
119
+
120
+ function checkShipActive(workDir: string): ShipMarker | null {
121
+ if (!existsSync(workDir)) return null;
122
+ const markers: ShipMarker[] = [];
123
+
124
+ try {
125
+ const entries = readdirSync(workDir, { withFileTypes: true });
126
+ for (const entry of entries) {
127
+ if (!entry.isDirectory()) continue;
128
+ const markerPath = join(workDir, entry.name, '.ship-active');
129
+ if (existsSync(markerPath)) {
130
+ try {
131
+ const raw = readFileSync(markerPath, 'utf-8').trim();
132
+ if (!raw.startsWith('{')) continue;
133
+ const parsed = JSON.parse(raw) as ShipMarker;
134
+ if (parsed.issue && parsed.ts) markers.push(parsed);
135
+ } catch {}
136
+ }
137
+ // Nested scan for 2-level slugs
138
+ try {
139
+ const subs = readdirSync(join(workDir, entry.name), { withFileTypes: true });
140
+ for (const sub of subs) {
141
+ if (!sub.isDirectory()) continue;
142
+ const nested = join(workDir, entry.name, sub.name, '.ship-active');
143
+ if (!existsSync(nested)) continue;
144
+ try {
145
+ const raw = readFileSync(nested, 'utf-8').trim();
146
+ if (!raw.startsWith('{')) continue;
147
+ const parsed = JSON.parse(raw) as ShipMarker;
148
+ if (parsed.issue && parsed.ts) markers.push(parsed);
149
+ } catch {}
150
+ }
151
+ } catch {}
152
+ }
153
+ } catch { return null; }
154
+
155
+ if (markers.length === 0) return null;
156
+ markers.sort((a, b) => new Date(b.ts).getTime() - new Date(a.ts).getTime());
157
+ return markers[0];
158
+ }
159
+
160
+ function checkWorkflowState(workDir: string): ShipMarker | null {
161
+ if (!existsSync(workDir)) return null;
162
+ const BUILD_PHASES = ['BUILD', 'VERIFY', 'SHIP', 'DONE'];
163
+ try {
164
+ const entries = readdirSync(workDir, { withFileTypes: true });
165
+ for (const entry of entries) {
166
+ if (!entry.isDirectory()) continue;
167
+ const wfPath = join(workDir, entry.name, 'workflow-state.json');
168
+ if (!existsSync(wfPath)) continue;
169
+ try {
170
+ const raw = readFileSync(wfPath, 'utf-8').trim();
171
+ if (!raw.startsWith('{')) continue;
172
+ const wf = JSON.parse(raw);
173
+ if (wf.issue && wf.phase && BUILD_PHASES.includes(wf.phase)) {
174
+ return { issue: wf.issue, ts: new Date().toISOString() };
175
+ }
176
+ } catch {}
177
+ }
178
+ } catch {}
179
+ return null;
180
+ }
181
+
182
+ function findSizingFromCheckpoint(workDir: string): string | null {
183
+ try {
184
+ if (!existsSync(workDir)) return null;
185
+ const entries = readdirSync(workDir)
186
+ .map(name => {
187
+ const full = join(workDir, name);
188
+ try {
189
+ const stat = statSync(full);
190
+ return { name, mtime: stat.mtimeMs, isDir: stat.isDirectory() };
191
+ } catch { return null; }
192
+ })
193
+ .filter((e): e is NonNullable<typeof e> => e !== null && e.isDir)
194
+ .sort((a, b) => b.mtime - a.mtime);
195
+
196
+ for (const entry of entries.slice(0, 5)) {
197
+ const cp = join(workDir, entry.name, 'CHECKPOINT.md');
198
+ if (!existsSync(cp)) continue;
199
+ try {
200
+ const content = readFileSync(cp, 'utf-8');
201
+ const match = content.match(/\*\*Size:\*\*\s*(XS|S|M|L)\b/i)
202
+ || content.match(/##\s*Sizing[\s\S]*?\b(XS|S|M|L)\b/i);
203
+ if (match) return match[1].toUpperCase();
204
+ } catch { continue; }
205
+ }
206
+ return null;
207
+ } catch { return null; }
208
+ }
209
+
210
+ function validateBriefPolicies(baseDir: string, agent: AgentDef, prompt: string): string[] {
211
+ const policyPath = join(baseDir, 'skills', 'ship', 'brief-policies.json');
212
+ if (!existsSync(policyPath)) return [];
213
+ try {
214
+ const raw = readFileSync(policyPath, 'utf-8').trim();
215
+ if (!raw.startsWith('{')) return [];
216
+ const policies = JSON.parse(raw);
217
+ const policy = policies.policies?.[agent.label.toLowerCase()];
218
+ if (!policy?.requiredPatterns) return [];
219
+ const missing: string[] = [];
220
+ for (const req of policy.requiredPatterns) {
221
+ if (!new RegExp(req.pattern, 'i').test(prompt)) missing.push(req.name);
222
+ }
223
+ return missing;
224
+ } catch { return []; }
225
+ }
226
+
227
+ // --- Signal Logging ---
228
+
229
+ export function logBriefSignal(baseDir: string, event: Record<string, unknown>): void {
230
+ try {
231
+ const signalsDir = join(baseDir, 'MEMORY', 'LEARNING', 'SIGNALS');
232
+ const signalsFile = join(signalsDir, 'signals.jsonl');
233
+ if (!existsSync(signalsDir)) mkdirSync(signalsDir, { recursive: true });
234
+ if (existsSync(signalsFile)) {
235
+ appendFileSync(signalsFile, JSON.stringify(event) + '\n', 'utf-8');
236
+ }
237
+ } catch {}
238
+ }
239
+
240
+ // --- Validation Pipeline ---
241
+
242
+ export function validateAgentBrief(
243
+ input: BriefValidationInput,
244
+ workDir: string,
245
+ baseDir: string,
246
+ ): ValidationResult {
247
+ const toolInput = input.tool_input || {};
248
+ const rawPrompt = toolInput.prompt || '';
249
+ const outputs: string[] = [];
250
+ const signalEvents: Record<string, unknown>[] = [];
251
+
252
+ // Bypass 1: Council
253
+ if (/\bcouncil\b/i.test(rawPrompt)) return { action: 'exit', outputs, signalEvents };
254
+
255
+ // Bypass 2: Research without implementation markers
256
+ if (/\b(research|investigate|audit)\b/i.test(rawPrompt) &&
257
+ !(rawPrompt.includes('## Task') && rawPrompt.includes('## Verify'))) {
258
+ return { action: 'exit', outputs, signalEvents };
259
+ }
260
+
261
+ const agent = detectAgentDef(input);
262
+ const earlyShipMarker = checkShipActive(workDir);
263
+ const shipIsActive = earlyShipMarker &&
264
+ (Date.now() - new Date(earlyShipMarker.ts).getTime()) <= SHIP_MARKER_TTL_MS;
265
+
266
+ // Bypass 3: No active ship (except Engineer)
267
+ if (!shipIsActive && agent?.label !== 'Marcus') return { action: 'exit', outputs, signalEvents };
268
+ if (!agent) return { action: 'exit', outputs, signalEvents };
269
+
270
+ // Check 1: bypassPermissions
271
+ if (toolInput.mode !== 'bypassPermissions') {
272
+ signalEvents.push({
273
+ ts: new Date().toISOString(), type: 'agent_spawn',
274
+ agent: agent.label.toLowerCase(), blocked: true, block_reason: 'missing_bypass_permissions',
275
+ });
276
+ return {
277
+ action: 'block', agent,
278
+ blockReason: `${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.`,
279
+ outputs, signalEvents,
280
+ };
281
+ }
282
+
283
+ // Check 2: Template markers
284
+ const isEngineer = agent.label === 'Marcus';
285
+ const missingMarkers = agent.markers.filter(m => !rawPrompt.includes(m));
286
+ if (missingMarkers.length > 0) {
287
+ if (isEngineer) {
288
+ signalEvents.push({
289
+ ts: new Date().toISOString(), type: 'agent_spawn',
290
+ agent: agent.label.toLowerCase(), blocked: true,
291
+ block_reason: 'missing_template_markers', missing_markers: missingMarkers,
292
+ });
293
+ return {
294
+ action: 'block', agent,
295
+ blockReason: `${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.`,
296
+ outputs, signalEvents,
297
+ };
298
+ }
299
+ outputs.push(
300
+ `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.`
301
+ );
302
+ signalEvents.push({
303
+ ts: new Date().toISOString(), type: 'agent_spawn_advisory',
304
+ agent: agent.label.toLowerCase(), blocked: false,
305
+ advisory_reason: 'missing_template_markers', missing_markers: missingMarkers,
306
+ });
307
+ }
308
+
309
+ // Check 3: Ship-active (Engineer only)
310
+ if (isEngineer) {
311
+ const shipMarker = checkShipActive(workDir) || checkWorkflowState(workDir);
312
+ const isStale = shipMarker ? (Date.now() - new Date(shipMarker.ts).getTime()) > SHIP_MARKER_TTL_MS : true;
313
+ if (!shipMarker || isStale) {
314
+ signalEvents.push({
315
+ ts: new Date().toISOString(), type: 'agent_spawn',
316
+ agent: agent.label.toLowerCase(), blocked: true, block_reason: 'no_ship_session',
317
+ });
318
+ return {
319
+ action: 'block', agent,
320
+ blockReason: `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.`,
321
+ outputs, signalEvents,
322
+ };
323
+ }
324
+ }
325
+
326
+ // Check 6: Brief content policies
327
+ const policyMissing = validateBriefPolicies(baseDir, agent, rawPrompt);
328
+ if (policyMissing.length > 0) {
329
+ outputs.push(`BRIEF CONTENT WARN: ${agent.label} brief missing: ${policyMissing.join(', ')}. See BRIEF-TEMPLATES/${agent.label.toLowerCase()}.md for required content.`);
330
+ signalEvents.push({
331
+ ts: new Date().toISOString(), type: 'agent_spawn_content_warn',
332
+ agent: agent.label.toLowerCase(), missing_content: policyMissing, blocked: false,
333
+ });
334
+ }
335
+
336
+ // Check 4: max_turns advisory
337
+ const sizing = findSizingFromCheckpoint(workDir);
338
+ const recommendedMaxTurns = sizing ? SIZE_MAX_TURNS[sizing] || DEFAULT_MAX_TURNS : DEFAULT_MAX_TURNS;
339
+ if (!toolInput.max_turns) {
340
+ outputs.push(`NOTE: No max_turns set for ${agent.label}. Recommended: ${recommendedMaxTurns} (sizing: ${sizing || 'unknown'}).`);
341
+ }
342
+
343
+ // Check 5: Single-attempt constraint
344
+ outputs.push(
345
+ `SCOPE CONSTRAINT: Try to resolve errors within a few attempts. If you encounter a persistent error you cannot fix:`,
346
+ `1. STOP — do not attempt 10+ different approaches`,
347
+ `2. Report back: what you tried, the exact error, your hypothesis`,
348
+ `3. Do NOT work around errors silently — surface them`,
349
+ );
350
+
351
+ signalEvents.push({
352
+ ts: new Date().toISOString(), type: 'agent_spawn',
353
+ agent: agent.label.toLowerCase(), has_template: true, has_bypass: true,
354
+ max_turns: toolInput.max_turns || null, recommended_max_turns: recommendedMaxTurns,
355
+ sizing: sizing || 'unknown', blocked: false,
356
+ });
357
+
358
+ return { action: 'pass', agent, outputs, signalEvents, sizing, recommendedMaxTurns };
359
+ }