rungate 0.2.1 → 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 (119) 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 +24 -2
  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
@@ -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
+ }