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.
- package/bin/rungate.ts +70 -0
- package/lib/aes-calculator.ts +66 -0
- package/lib/agent-audit.ts +139 -0
- package/lib/agent-brief-validation.ts +359 -0
- package/lib/agents-md-refs.ts +90 -0
- package/lib/bash-file-read.ts +197 -0
- package/lib/behavioral-cache.ts +78 -0
- package/lib/branch-cleanup.ts +234 -0
- package/lib/brief-context-parser.ts +35 -0
- package/lib/canary.ts +117 -0
- package/lib/check-registry.ts +226 -0
- package/lib/ci-checkout.ts +400 -0
- package/lib/cli-commands.ts +137 -0
- package/lib/compliance-backfill.ts +220 -0
- package/lib/compliance-report.ts +504 -0
- package/lib/compliance.ts +361 -0
- package/lib/config-loader.ts +255 -0
- package/lib/conformity.ts +1818 -131
- package/lib/container-provenance.ts +230 -0
- package/lib/create-brief.ts +150 -0
- package/lib/create-sc.ts +272 -0
- package/lib/deep-merge.ts +69 -0
- package/lib/dev-liveness.ts +214 -0
- package/lib/directive-extractor.ts +210 -0
- package/lib/distribution-standing.ts +113 -0
- package/lib/doc-hygiene.ts +238 -0
- package/lib/eval-criteria.ts +6 -0
- package/lib/evidence-portability.ts +123 -0
- package/lib/evidence-prevalidator.ts +390 -0
- package/lib/evidence-required.ts +150 -0
- package/lib/evidence-satisfiability.ts +288 -0
- package/lib/frontmatter.ts +163 -0
- package/lib/gap-scanner.ts +348 -0
- package/lib/gate-enforcement.ts +366 -0
- package/lib/generators/agent-briefs.ts +136 -0
- package/lib/generators/agents-md.ts +506 -0
- package/lib/generators/code-map.ts +60 -0
- package/lib/generators/types.ts +184 -0
- package/lib/git-ref-normalizer.ts +107 -0
- package/lib/github.ts +539 -0
- package/lib/harness-identity.ts +63 -0
- package/lib/hill-climb.ts +164 -0
- package/lib/instruction-effectiveness.ts +131 -0
- package/lib/issue-closure-audit.ts +225 -0
- package/lib/issue-create-override.ts +343 -0
- package/lib/js-top-level-code.ts +250 -0
- package/lib/liveness-contradiction.ts +149 -0
- package/lib/organize.ts +505 -0
- package/lib/paths.ts +197 -6
- package/lib/post-fix-verify.ts +157 -0
- package/lib/prior-branch.ts +489 -0
- package/lib/project-state-shape.ts +166 -0
- package/lib/promote-outputs.ts +156 -0
- package/lib/prove-label-gate.ts +35 -0
- package/lib/reachability.ts +302 -0
- package/lib/release-preflight.ts +186 -0
- package/lib/rule-health-pipeline.ts +264 -0
- package/lib/rule-health-trend.ts +161 -0
- package/lib/rule-provenance.ts +149 -0
- package/lib/rule-registry.ts +128 -0
- package/lib/rungate-schema.ts +114 -4
- package/lib/sc-claim-forms.ts +179 -0
- package/lib/sc-cover.ts +150 -0
- package/lib/sc-guard.ts +157 -0
- package/lib/sc-ids.ts +344 -0
- package/lib/scaffold/defaults.ts +165 -0
- package/lib/scaffold/managed-workflow.ts +370 -0
- package/lib/scaffold/owned-files.ts +265 -0
- package/lib/scaffold/steps.ts +2680 -0
- package/lib/scanner.ts +701 -0
- package/lib/screenshot-upload.ts +73 -0
- package/lib/secret-patterns.ts +112 -0
- package/lib/security-verdict.ts +616 -0
- package/lib/signal-phrases.ts +1 -0
- package/lib/spec-change-conformity.ts +80 -0
- package/lib/spec-files.ts +62 -0
- package/lib/spec-registry.ts +133 -0
- package/lib/spec-updater.ts +96 -0
- package/lib/stale-cleanup.ts +224 -0
- package/lib/stale-issue-scanner.ts +36 -0
- package/lib/strip-js-comments.ts +269 -0
- package/lib/suite-measurement.ts +228 -0
- package/lib/task-completion-checks.ts +177 -0
- package/lib/test-suite-lock.ts +1136 -0
- package/lib/transcript-checker.ts +1140 -0
- package/lib/validators/spec-validators.ts +171 -0
- package/lib/verdict-capture.ts +73 -0
- package/lib/verified-push.ts +358 -0
- package/lib/workflow-security.ts +174 -0
- package/lib/worktree-cleanup.ts +250 -0
- package/lib/worktree-collect.ts +283 -0
- package/lib/worktree-isolation.ts +82 -0
- package/package.json +24 -2
- package/prompts/ac-adversary.md +14 -2
- package/prompts/aditi.md +5 -0
- package/prompts/blast-radius.md +5 -0
- package/prompts/container-verify.md +5 -0
- package/prompts/discovery.md +4 -0
- package/prompts/environment.md +5 -0
- package/prompts/evidence-hierarchy.md +5 -0
- package/prompts/evidence-validator.md +11 -0
- package/prompts/marcus.md +5 -0
- package/prompts/prevention.md +5 -0
- package/prompts/prove-reproducer.md +12 -0
- package/prompts/quinn-decision-tree.md +5 -0
- package/prompts/quinn-ui-brief.md +5 -0
- package/prompts/quinn.md +5 -0
- package/prompts/rca.md +5 -0
- package/prompts/read-before-write.md +4 -0
- package/prompts/regression.md +5 -0
- package/prompts/serena.md +5 -0
- package/scripts/audit-specs.ts +464 -0
- package/scripts/convert-spec.ts +293 -0
- package/scripts/create-sc.ts +92 -0
- package/scripts/create-spec.ts +166 -0
- package/scripts/extract-constraints.ts +4 -3
- package/scripts/generate-code-map.ts +1 -1
- package/scripts/scaffold-project.ts +138 -1426
- 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
|
+
}
|
package/lib/organize.ts
ADDED
|
@@ -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
|
+
}
|