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
@@ -0,0 +1,149 @@
1
+ /**
2
+ * A run cannot have collected evidence from a server it never managed to
3
+ * find (#346).
4
+ *
5
+ * #304 relaxed a refusal, correctly. The prove gate used to `process.exit(1)`
6
+ * when `dev.apiBase` was set and the server did not answer — but the health
7
+ * route is now read from config and no consumer sets `dev.healthPath` yet, so
8
+ * reporting DOWN for a server whose route cannot be looked up is a false FAIL
9
+ * on a healthy server. #345 then made the reading durable: `UP` / `DOWN` /
10
+ * `UNMEASURED` per tier, written to `workflow-state.json` and
11
+ * `prove-input.json`.
12
+ *
13
+ * **And nothing read it.** A control replaced by an unread field is still a
14
+ * control removed, which is #213's shape exactly: recorded, never consumed.
15
+ *
16
+ * ## The refusal that is actually correct
17
+ *
18
+ * Not "FAIL if liveness is UNMEASURED" — that reinstates the false FAIL this
19
+ * whole sequence exists to remove, and it would fire on every consumer on
20
+ * their next run.
21
+ *
22
+ * The honest refusal is a **contradiction**: a run must not claim it
23
+ * collected server-dependent OUTCOME evidence while reporting that liveness
24
+ * was never measured. If the evidence really came from a running server then
25
+ * the server was reachable, and the consumer can configure the path. If
26
+ * liveness is UNMEASURED and the evidence is nonetheless marked collected,
27
+ * one of the two statements is untrue — and this check does not need to know
28
+ * which to know that the run should not pass.
29
+ *
30
+ * It cannot false-FAIL a healthy server, because it only fires when evidence
31
+ * is *claimed* without measurement. A project with an unconfigured health
32
+ * path and no server-dependent evidence sails through exactly as it does
33
+ * today; that relaxation has to survive, and a test holds it.
34
+ *
35
+ * ## Deliberately narrow
36
+ *
37
+ * Only `UNMEASURED` fires, not `DOWN`. DOWN is a measurement — the route was
38
+ * configured and the probe ran — and the prod tier records it while only
39
+ * warning, by design. Widening this to DOWN is a bigger behaviour change than
40
+ * #346 asked for and would need its own blast-radius measurement.
41
+ *
42
+ * Likewise, a run with NO liveness entries at all is a project that declares
43
+ * no server, which is a different situation from one that tried to look and
44
+ * could not. This stays silent there.
45
+ */
46
+
47
+ /**
48
+ * Where a health route is declared, if it is declared anywhere this can see.
49
+ *
50
+ * #346 asked the scaffold to write `dev.healthPath` so the UNMEASURED
51
+ * population shrinks to projects that genuinely have no health endpoint.
52
+ * Writing a conventional default would do that and would be wrong:
53
+ * `DevSchema.healthPath` says "No default. A probe that guesses a path
54
+ * reports DOWN for a server that is up", and a guess the scaffold writes
55
+ * into the consumer's config is still a guess — one the harness can then
56
+ * point at the consumer and blame.
57
+ *
58
+ * So the route is looked for in the source, and the answer is `null` when it
59
+ * is not there. A detector that returns null is not a failure; it is the
60
+ * measurement, and UNMEASURED downstream then means "this project has no
61
+ * health endpoint we could locate" rather than "nobody looked".
62
+ */
63
+ export const HEALTH_ROUTE_PATTERNS: readonly RegExp[] = [
64
+ // Express/Hono/Fastify: app.get("/api/health", …)
65
+ /\.(?:get|all)\(\s*["'`](\/[A-Za-z0-9_\-./]*health[A-Za-z0-9_\-./]*)["'`]/i,
66
+ // Route tables / OpenAPI-ish: path: "/healthz"
67
+ /\bpath\s*:\s*["'`](\/[A-Za-z0-9_\-./]*health[A-Za-z0-9_\-./]*)["'`]/i,
68
+ // Next-style file routing emitted as a literal
69
+ /["'`](\/api\/[A-Za-z0-9_\-./]*health[A-Za-z0-9_\-./]*)["'`]/i,
70
+ ];
71
+
72
+ /** Evidence methods that cannot produce a result without a running server. */
73
+ export const SERVER_DEPENDENT_METHODS = [
74
+ "PLAYWRIGHT",
75
+ "SCREENSHOT",
76
+ "CURL_CHECK",
77
+ "api",
78
+ "screenshot",
79
+ ] as const;
80
+
81
+ /** Evidence payload kinds that could only have come off the wire. */
82
+ export const SERVER_DEPENDENT_EVIDENCE = ["api-response", "screenshot"] as const;
83
+
84
+ /** Find a declared health route in one file's text, or null. */
85
+ export function healthPathIn(source: string): string | null {
86
+ for (const re of HEALTH_ROUTE_PATTERNS) {
87
+ const m = re.exec(source);
88
+ if (m) return m[1];
89
+ }
90
+ return null;
91
+ }
92
+
93
+ export interface LivenessReading {
94
+ tier: string;
95
+ status: string;
96
+ detail?: string;
97
+ }
98
+
99
+ export interface EvidenceClaim {
100
+ id: string;
101
+ type?: string;
102
+ evidenceMethod?: { type?: string } | null;
103
+ evidence?: { type?: string } | null;
104
+ }
105
+
106
+ /** Did this AC claim it collected something only a live server produces? */
107
+ export function claimsServerEvidence(ac: EvidenceClaim): boolean {
108
+ if (ac.type !== "OUTCOME") return false;
109
+ // Evidence must actually be present. An OUTCOME AC that merely DECLARES a
110
+ // playwright method has claimed nothing yet — it is a plan, and planning to
111
+ // use a server you have not found is not a contradiction.
112
+ if (!ac.evidence) return false;
113
+ const method = ac.evidenceMethod?.type;
114
+ const payload = ac.evidence?.type;
115
+ return (
116
+ (method !== undefined && (SERVER_DEPENDENT_METHODS as readonly string[]).includes(method)) ||
117
+ (payload !== undefined && (SERVER_DEPENDENT_EVIDENCE as readonly string[]).includes(payload))
118
+ );
119
+ }
120
+
121
+ /**
122
+ * Every contradiction between the liveness record and the evidence claims.
123
+ *
124
+ * One exported violations-returning function, per
125
+ * `.claude/rules/checks-must-be-able-to-fail.md`: the single binding a test
126
+ * can short-circuit to `return []` and count the red.
127
+ */
128
+ export function livenessEvidenceContradictions(
129
+ acs: EvidenceClaim[],
130
+ liveness: LivenessReading[],
131
+ ): string[] {
132
+ const unmeasured = liveness.filter(l => l.status === "UNMEASURED");
133
+ if (unmeasured.length === 0) return [];
134
+ // A tier that came back UP means a server WAS found, and the evidence has
135
+ // somewhere it could have come from. Only a run that measured nothing
136
+ // anywhere is contradicted by claiming it measured something.
137
+ if (liveness.some(l => l.status === "UP")) return [];
138
+
139
+ const claiming = acs.filter(claimsServerEvidence);
140
+ if (claiming.length === 0) return [];
141
+
142
+ const tiers = unmeasured.map(l => l.tier).join(", ");
143
+ return claiming.map(
144
+ ac =>
145
+ `${ac.id}: claims collected ${ac.evidence?.type ?? ac.evidenceMethod?.type} evidence, ` +
146
+ `which requires a running server, but liveness is UNMEASURED for ${tiers} — ` +
147
+ `either the evidence did not come from a server or the server was reachable and its health path can be configured`,
148
+ );
149
+ }
@@ -0,0 +1,505 @@
1
+ /**
2
+ * organize.ts — Project organization tool
3
+ *
4
+ * Scans a project for unorganized markdown files, classifies them using
5
+ * frontmatter, filename patterns, and content heuristics, and proposes
6
+ * (or executes) moves into the correct directories.
7
+ *
8
+ * Directories: specs/, docs/research/, docs/adr/, docs/council/, docs/guides/, reference/
9
+ */
10
+ import {
11
+ existsSync,
12
+ readFileSync,
13
+ writeFileSync,
14
+ readdirSync,
15
+ renameSync,
16
+ mkdirSync,
17
+ lstatSync,
18
+ readlinkSync,
19
+ symlinkSync,
20
+ unlinkSync,
21
+ } from "fs";
22
+ import { join, relative, dirname, basename } from "path";
23
+ import { loadComplianceConfig, type OrganizeExternalSource } from "./config-loader.js";
24
+
25
+ // ── Types ────────────────────────────────────────────────────────
26
+
27
+ export interface UnorganizedCandidate {
28
+ /** Relative path from project root */
29
+ source: string;
30
+ /** Raw file content */
31
+ content: string;
32
+ }
33
+
34
+ export interface ClassificationResult {
35
+ /** Target directory (e.g. "specs", "docs/research", "docs/adr", "docs/council", "docs/guides", "reference") */
36
+ targetDir: string;
37
+ /** Human-readable classification label */
38
+ classification: string;
39
+ /** Why this classification was chosen */
40
+ reasoning: string;
41
+ /** Confidence score 0-1 */
42
+ confidence: number;
43
+ }
44
+
45
+ export interface OrganizeProposal {
46
+ /** Relative source path */
47
+ source: string;
48
+ /** Relative target path */
49
+ target: string;
50
+ /** Classification label */
51
+ classification: string;
52
+ /** Reasoning for the classification */
53
+ reasoning: string;
54
+ /** Confidence 0-1 */
55
+ confidence: number;
56
+ }
57
+
58
+ export interface OrganizeOptions {
59
+ /** If true, execute moves. If false, only return proposals */
60
+ apply?: boolean;
61
+ /** If true, only return proposals without executing */
62
+ dryRun?: boolean;
63
+ /** Path to the harness project root (for loading compliance.json config) */
64
+ harnessRoot?: string;
65
+ }
66
+
67
+ // ── Well-known root files to skip ────────────────────────────────
68
+
69
+ const WELL_KNOWN_ROOT_FILES = new Set([
70
+ "AGENTS.md",
71
+ "README.md",
72
+ "CLAUDE.md",
73
+ "CHANGELOG.md",
74
+ "CODE-MAP.md",
75
+ "PROJECT-STATE.md",
76
+ "CONTRIBUTING.md",
77
+ "LICENSE.md",
78
+ "ARCHITECTURE.md",
79
+ "PRINCIPLES.md",
80
+ "MODEL.md",
81
+ "HARNESS.md",
82
+ "SECURITY.md",
83
+ "CODE_OF_CONDUCT.md",
84
+ ]);
85
+
86
+ // ── Standard directories ─────────────────────────────────────────
87
+
88
+ const STANDARD_DIRS = ["specs", "docs/research", "docs/adr", "docs/council", "docs/guides", "reference"];
89
+
90
+ // ── Classification doc-type to directory mapping ─────────────────
91
+
92
+ const DOC_TYPE_MAP: Record<string, string> = {
93
+ spec: "specs",
94
+ adr: "docs/adr",
95
+ research: "docs/research",
96
+ council: "docs/council",
97
+ guide: "docs/guides",
98
+ reference: "reference",
99
+ };
100
+
101
+ // ── Scan for unorganized files ───────────────────────────────────
102
+
103
+ export function scanUnorganized(root: string, fileTypes: string[] = [".md"]): UnorganizedCandidate[] {
104
+ const candidates: UnorganizedCandidate[] = [];
105
+
106
+ try {
107
+ for (const f of readdirSync(root)) {
108
+ const ext = f.substring(f.lastIndexOf(".")).toLowerCase();
109
+ if (!fileTypes.includes(ext)) continue;
110
+ if (WELL_KNOWN_ROOT_FILES.has(f)) continue;
111
+ const fullPath = join(root, f);
112
+ try {
113
+ if (lstatSync(fullPath).isDirectory()) continue;
114
+ if (ext === ".md") {
115
+ const content = readFileSync(fullPath, "utf-8");
116
+ candidates.push({ source: f, content });
117
+ } else {
118
+ candidates.push({ source: f, content: "" });
119
+ }
120
+ } catch {}
121
+ }
122
+ } catch {}
123
+
124
+ return candidates;
125
+ }
126
+
127
+ // ── Classify a single document ───────────────────────────────────
128
+
129
+ export function classifyDocument(
130
+ filename: string,
131
+ content: string,
132
+ artifactClassification: Record<string, string> = {},
133
+ ): ClassificationResult {
134
+ // 0. Non-markdown files: classify by extension from config
135
+ const ext = filename.substring(filename.lastIndexOf(".")).toLowerCase();
136
+ if (ext !== ".md" && artifactClassification[ext]) {
137
+ return {
138
+ targetDir: artifactClassification[ext],
139
+ classification: "artifact",
140
+ reasoning: `non-markdown file type ${ext} classified as ${artifactClassification[ext]} by config`,
141
+ confidence: 0.85,
142
+ };
143
+ }
144
+
145
+ // 1. Check frontmatter doc-type (highest confidence)
146
+ const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
147
+ if (fmMatch) {
148
+ const docTypeMatch = fmMatch[1].match(/doc-type:\s*(\S+)/);
149
+ if (docTypeMatch) {
150
+ const docType = docTypeMatch[1].trim();
151
+ const targetDir = DOC_TYPE_MAP[docType];
152
+ if (targetDir) {
153
+ return {
154
+ targetDir,
155
+ classification: docType,
156
+ reasoning: `frontmatter doc-type: ${docType}`,
157
+ confidence: 0.95,
158
+ };
159
+ }
160
+ }
161
+ }
162
+
163
+ // 2. Check filename patterns (high confidence)
164
+ const nameUpper = filename.toUpperCase();
165
+
166
+ if (/^ADR[-_]\d+/i.test(filename)) {
167
+ return {
168
+ targetDir: "docs/adr",
169
+ classification: "adr",
170
+ reasoning: `filename matches ADR pattern: ${filename}`,
171
+ confidence: 0.9,
172
+ };
173
+ }
174
+
175
+ if (nameUpper.includes("SPEC") && !nameUpper.includes("INSPECT")) {
176
+ return {
177
+ targetDir: "specs",
178
+ classification: "spec",
179
+ reasoning: `filename contains 'spec': ${filename}`,
180
+ confidence: 0.85,
181
+ };
182
+ }
183
+
184
+ if (nameUpper.includes("RESEARCH") || nameUpper.includes("EVAL") || nameUpper.includes("FINDINGS")) {
185
+ return {
186
+ targetDir: "docs/research",
187
+ classification: "research",
188
+ reasoning: `filename suggests research: ${filename}`,
189
+ confidence: 0.8,
190
+ };
191
+ }
192
+
193
+ if (nameUpper.includes("GUIDE") || nameUpper.includes("SETUP") || nameUpper.includes("ONBOARDING")) {
194
+ return {
195
+ targetDir: "docs/guides",
196
+ classification: "guide",
197
+ reasoning: `filename suggests guide: ${filename}`,
198
+ confidence: 0.8,
199
+ };
200
+ }
201
+
202
+ if (nameUpper.includes("COUNCIL") || nameUpper.includes("DEBATE") || nameUpper.includes("SYNTHESIS")) {
203
+ return {
204
+ targetDir: "docs/council",
205
+ classification: "council",
206
+ reasoning: `filename suggests council: ${filename}`,
207
+ confidence: 0.8,
208
+ };
209
+ }
210
+
211
+ // 3. Content heuristics (medium confidence)
212
+ const contentLower = content.toLowerCase();
213
+
214
+ // ADR heuristics: Decision + Status/Context/Consequences
215
+ if (
216
+ contentLower.includes("## decision") &&
217
+ (contentLower.includes("## status") || contentLower.includes("## context") || contentLower.includes("## consequences"))
218
+ ) {
219
+ return {
220
+ targetDir: "docs/adr",
221
+ classification: "adr",
222
+ reasoning: "content structure matches ADR pattern (Decision/Status/Context sections)",
223
+ confidence: 0.7,
224
+ };
225
+ }
226
+
227
+ // Spec heuristics: Success Criteria or Acceptance Criteria
228
+ if (contentLower.includes("success criteria") || contentLower.includes("acceptance criteria")) {
229
+ return {
230
+ targetDir: "specs",
231
+ classification: "spec",
232
+ reasoning: "content contains success/acceptance criteria sections",
233
+ confidence: 0.7,
234
+ };
235
+ }
236
+
237
+ // Research heuristics: Findings/Recommendation/Evaluation/Analysis
238
+ const researchSignals = ["## findings", "## recommendation", "## evaluation", "## analysis", "competitor", "evaluated"];
239
+ const researchHits = researchSignals.filter((s) => contentLower.includes(s)).length;
240
+ if (researchHits >= 2) {
241
+ return {
242
+ targetDir: "docs/research",
243
+ classification: "research",
244
+ reasoning: `content has ${researchHits} research signals (findings, recommendation, evaluation, etc.)`,
245
+ confidence: 0.65,
246
+ };
247
+ }
248
+
249
+ // Reference/deprecated heuristics
250
+ if (
251
+ contentLower.includes("deprecated") ||
252
+ contentLower.includes("no longer in use") ||
253
+ contentLower.includes("historical reference") ||
254
+ contentLower.includes("archived") ||
255
+ contentLower.includes("superseded")
256
+ ) {
257
+ return {
258
+ targetDir: "reference",
259
+ classification: "reference",
260
+ reasoning: "content indicates deprecated/historical document",
261
+ confidence: 0.6,
262
+ };
263
+ }
264
+
265
+ // Guide heuristics: step-by-step, how to, getting started
266
+ if (
267
+ contentLower.includes("step-by-step") ||
268
+ contentLower.includes("getting started") ||
269
+ contentLower.includes("## prerequisites") ||
270
+ contentLower.includes("## installation")
271
+ ) {
272
+ return {
273
+ targetDir: "docs/guides",
274
+ classification: "guide",
275
+ reasoning: "content structure suggests a guide (step-by-step, prerequisites, etc.)",
276
+ confidence: 0.6,
277
+ };
278
+ }
279
+
280
+ // Default: reference (lowest confidence)
281
+ return {
282
+ targetDir: "reference",
283
+ classification: "unclassified",
284
+ reasoning: "no strong signals detected, defaulting to reference",
285
+ confidence: 0.3,
286
+ };
287
+ }
288
+
289
+ // ── Main organize function ───────────────────────────────────────
290
+
291
+ export function organizeProject(root: string, options: OrganizeOptions = {}): OrganizeProposal[] {
292
+ const complianceConfig = options.harnessRoot
293
+ ? loadComplianceConfig(options.harnessRoot)
294
+ : null;
295
+ const organizeConfig = complianceConfig?.organize;
296
+ const fileTypes = organizeConfig?.fileTypes || [".md"];
297
+ const artifactClassification = organizeConfig?.artifactClassification || {};
298
+
299
+ const candidates = scanUnorganized(root, fileTypes);
300
+ const proposals: OrganizeProposal[] = [];
301
+
302
+ for (const candidate of candidates) {
303
+ const classification = classifyDocument(candidate.source, candidate.content, artifactClassification);
304
+
305
+ const currentDir = dirname(candidate.source);
306
+ if (currentDir === classification.targetDir) continue;
307
+
308
+ const targetPath = join(classification.targetDir, basename(candidate.source));
309
+
310
+ proposals.push({
311
+ source: candidate.source,
312
+ target: targetPath,
313
+ classification: classification.classification,
314
+ reasoning: classification.reasoning,
315
+ confidence: classification.confidence,
316
+ });
317
+ }
318
+
319
+ // Scan external sources from config
320
+ if (organizeConfig?.externalSources) {
321
+ const externalProposals = scanExternalSources(root, organizeConfig.externalSources);
322
+ proposals.push(...externalProposals);
323
+ }
324
+
325
+ if (options.apply && !options.dryRun) {
326
+ executeProposals(root, proposals);
327
+ }
328
+
329
+ return proposals;
330
+ }
331
+
332
+ // ── External source scanning ────────────────────────────────────
333
+
334
+ function scanExternalSources(projectRoot: string, sources: OrganizeExternalSource[]): OrganizeProposal[] {
335
+ const proposals: OrganizeProposal[] = [];
336
+ const projectName = basename(projectRoot).toLowerCase();
337
+
338
+ for (const source of sources) {
339
+ const expandedPath = source.path.replace("~", process.env.HOME || "");
340
+ if (!existsSync(expandedPath)) continue;
341
+ if (source.target === null) continue;
342
+
343
+ if (lstatSync(expandedPath).isDirectory()) {
344
+ try {
345
+ for (const entry of readdirSync(expandedPath)) {
346
+ const entryPath = join(expandedPath, entry);
347
+ if (!lstatSync(entryPath).isDirectory() && !entry.endsWith(".md")) continue;
348
+
349
+ let matches = false;
350
+ if (source.matchBy === "project-name") {
351
+ matches = entry.toLowerCase().includes(projectName) ||
352
+ (lstatSync(entryPath).isDirectory() && readdirSync(entryPath).some(f =>
353
+ f.toLowerCase().includes(projectName)));
354
+ } else if (source.matchBy === "content-reference") {
355
+ if (entry.endsWith(".md")) {
356
+ try {
357
+ const content = readFileSync(entryPath, "utf-8");
358
+ matches = content.toLowerCase().includes(projectName);
359
+ } catch {}
360
+ }
361
+ }
362
+
363
+ if (matches) {
364
+ const targetPath = join(source.target, entry);
365
+ const targetFull = join(projectRoot, targetPath);
366
+ if (existsSync(targetFull)) continue;
367
+
368
+ proposals.push({
369
+ source: entryPath,
370
+ target: targetPath,
371
+ classification: source.type,
372
+ reasoning: `external ${source.type} matched by ${source.matchBy} in ${source.path}`,
373
+ confidence: 0.7,
374
+ });
375
+ }
376
+ }
377
+ } catch {}
378
+ }
379
+ }
380
+
381
+ return proposals;
382
+ }
383
+
384
+ // ── Execute proposals (move files) ───────────────────────────────
385
+
386
+ function executeProposals(root: string, proposals: OrganizeProposal[]): void {
387
+ const moveMap = new Map<string, string>();
388
+
389
+ for (const proposal of proposals) {
390
+ const isAbsolute = proposal.source.startsWith("/");
391
+ const srcPath = isAbsolute ? proposal.source : join(root, proposal.source);
392
+ const tgtPath = join(root, proposal.target);
393
+
394
+ if (!existsSync(srcPath)) continue;
395
+
396
+ const tgtDir = dirname(tgtPath);
397
+ if (!existsSync(tgtDir)) {
398
+ mkdirSync(tgtDir, { recursive: true });
399
+ }
400
+
401
+ if (isAbsolute) {
402
+ // External source: create symlink, don't move
403
+ if (!existsSync(tgtPath)) {
404
+ symlinkSync(srcPath, tgtPath);
405
+ }
406
+ } else if (lstatSync(srcPath).isSymbolicLink()) {
407
+ const linkTarget = readlinkSync(srcPath);
408
+ unlinkSync(srcPath);
409
+ symlinkSync(linkTarget, tgtPath);
410
+ } else {
411
+ renameSync(srcPath, tgtPath);
412
+ }
413
+
414
+ moveMap.set(proposal.source, proposal.target);
415
+ }
416
+
417
+ // Update internal references in all moved files
418
+ updateInternalReferences(root, moveMap);
419
+
420
+ // Update AGENTS.md docs-routing
421
+ updateDocsRouting(root, proposals);
422
+ }
423
+
424
+ // ── Update internal markdown references ──────────────────────────
425
+
426
+ function updateInternalReferences(root: string, moveMap: Map<string, string>): void {
427
+ if (moveMap.size === 0) return;
428
+
429
+ // For each moved file, update any markdown links that reference other moved files
430
+ for (const [, newPath] of moveMap) {
431
+ const fullPath = join(root, newPath);
432
+ if (!existsSync(fullPath)) continue;
433
+
434
+ // Skip symlinks for content modification
435
+ if (lstatSync(fullPath).isSymbolicLink()) continue;
436
+
437
+ let content = readFileSync(fullPath, "utf-8");
438
+ let changed = false;
439
+
440
+ for (const [oldSource, newTarget] of moveMap) {
441
+ // Skip self-references
442
+ if (newPath === newTarget && oldSource === newPath) continue;
443
+
444
+ // Calculate old relative reference from old location to old source
445
+ const oldRelative = `./${oldSource}`;
446
+ // Calculate new relative reference from new location to new target
447
+ const newDir = dirname(newPath);
448
+ const newRelative = relative(newDir, newTarget) || basename(newTarget);
449
+ const newRelativeFormatted = newRelative.startsWith("..") ? newRelative : `./${newRelative}`;
450
+
451
+ if (content.includes(oldRelative)) {
452
+ content = content.replace(new RegExp(escapeRegex(oldRelative), "g"), newRelativeFormatted);
453
+ changed = true;
454
+ }
455
+
456
+ // Also check bare filename references like (AUTH-SPEC.md) in link syntax
457
+ const bareOldName = basename(oldSource);
458
+ const linkPattern = new RegExp(`\\]\\(${escapeRegex(bareOldName)}\\)`, "g");
459
+ if (linkPattern.test(content)) {
460
+ content = content.replace(linkPattern, `](${newRelativeFormatted})`);
461
+ changed = true;
462
+ }
463
+ }
464
+
465
+ if (changed) {
466
+ writeFileSync(fullPath, content);
467
+ }
468
+ }
469
+ }
470
+
471
+ function escapeRegex(str: string): string {
472
+ return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
473
+ }
474
+
475
+ // ── Update AGENTS.md docs-routing table ──────────────────────────
476
+
477
+ export function updateDocsRouting(root: string, proposals: OrganizeProposal[]): void {
478
+ const agentsPath = join(root, "AGENTS.md");
479
+ if (!existsSync(agentsPath)) return;
480
+ if (proposals.length === 0) return;
481
+
482
+ let content = readFileSync(agentsPath, "utf-8");
483
+
484
+ // Find the Documentation Routing table
485
+ const tablePattern = /(\| I need to understand\.\.\. \| Read \|\n\|[-|]+\|\n)((?:\|[^\n]+\|\n)*)/;
486
+ const match = content.match(tablePattern);
487
+ if (!match) return;
488
+
489
+ const existingTable = match[2];
490
+ const newRows: string[] = [];
491
+
492
+ for (const proposal of proposals) {
493
+ // Skip if already in table
494
+ if (existingTable.includes(proposal.target)) continue;
495
+
496
+ const label = basename(proposal.target, ".md").replace(/-/g, " ");
497
+ newRows.push(`| ${label} | ${proposal.target} |`);
498
+ }
499
+
500
+ if (newRows.length === 0) return;
501
+
502
+ const updatedTable = match[1] + existingTable + newRows.join("\n") + "\n";
503
+ content = content.replace(tablePattern, updatedTable);
504
+ writeFileSync(agentsPath, content);
505
+ }