rungate 0.2.1 → 0.4.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/brief-precedence.ts +114 -0
- package/lib/canary.ts +117 -0
- package/lib/check-registry.ts +226 -0
- package/lib/ci-checkout.ts +426 -0
- package/lib/cli-commands.ts +137 -0
- package/lib/compliance-backfill.ts +232 -0
- package/lib/compliance-report.ts +605 -0
- package/lib/compliance.ts +361 -0
- package/lib/config-loader.ts +255 -0
- package/lib/config-readers.ts +86 -0
- package/lib/conformity.ts +2161 -137
- package/lib/container-provenance.ts +230 -0
- package/lib/create-brief.ts +150 -0
- package/lib/create-sc.ts +267 -0
- package/lib/decomposition-waves.ts +197 -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-check-audit.ts +190 -0
- package/lib/gate-enforcement.ts +366 -0
- package/lib/generators/agent-briefs.ts +136 -0
- package/lib/generators/agents-md.ts +511 -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/issue-extraction.ts +368 -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/phase2-decomposition.ts +270 -0
- package/lib/post-fix-verify.ts +157 -0
- package/lib/prior-branch.ts +512 -0
- package/lib/project-state-shape.ts +166 -0
- package/lib/promote-outputs.ts +156 -0
- package/lib/prove-label-gate.ts +128 -0
- package/lib/reachability.ts +302 -0
- package/lib/release-preflight.ts +288 -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 +127 -5
- 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/pre-push-hook.ts +165 -0
- package/lib/scaffold/steps.ts +2621 -0
- package/lib/scanner.ts +701 -0
- package/lib/scope-denylist.ts +258 -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 +224 -0
- package/lib/test-suite-lock.ts +1136 -0
- package/lib/transcript-checker.ts +1140 -0
- package/lib/typescript-project.ts +233 -0
- package/lib/validators/spec-validators.ts +171 -0
- package/lib/verdict-capture.ts +73 -0
- package/lib/verified-push.ts +535 -0
- package/lib/workflow-security.ts +174 -0
- package/lib/worktree-cleanup.ts +432 -0
- package/lib/worktree-collect.ts +283 -0
- package/lib/worktree-isolation.ts +82 -0
- package/lib/worktree-repo.ts +300 -0
- package/package.json +27 -3
- 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
package/lib/paths.ts
CHANGED
|
@@ -1,15 +1,178 @@
|
|
|
1
|
-
import { join, resolve } from "path";
|
|
2
|
-
import {
|
|
1
|
+
import { dirname, join, resolve } from "path";
|
|
2
|
+
import { spawnSync } from "child_process";
|
|
3
|
+
import { chmodSync, existsSync, mkdirSync, realpathSync, statSync, writeFileSync } from "fs";
|
|
4
|
+
import { randomBytes } from "crypto";
|
|
5
|
+
import { homedir } from "os";
|
|
3
6
|
|
|
4
|
-
|
|
7
|
+
/**
|
|
8
|
+
* Every refusal in this file routes through `refuse()`, and `refuse()` is the
|
|
9
|
+
* only reader of this constant, which appears exactly once. `test/harness-root.test.ts`
|
|
10
|
+
* builds a mutant copy of this module with it set to `0` and asserts the mutant
|
|
11
|
+
* does NOT refuse on inputs the real module rejects — the positive control
|
|
12
|
+
* required by .claude/rules/checks-must-be-able-to-fail.md. Inlining a `throw`
|
|
13
|
+
* anywhere below would bypass that control, so don't.
|
|
14
|
+
*/
|
|
15
|
+
export const REFUSE_IMPLICIT_ROOT = 1;
|
|
16
|
+
|
|
17
|
+
function refuse(message: string): void {
|
|
18
|
+
if (REFUSE_IMPLICIT_ROOT) throw new Error(message);
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
/** `file:line` of the frame that called into this module, for refusal messages. */
|
|
22
|
+
function callSite(): string {
|
|
23
|
+
const frames = (new Error().stack || "").split("\n").slice(1);
|
|
24
|
+
for (const f of frames) {
|
|
25
|
+
if (f.includes("lib/paths.ts")) continue;
|
|
26
|
+
const m = f.match(/\(?([^()\s]+:\d+:\d+)\)?\s*$/);
|
|
27
|
+
if (m) return m[1];
|
|
28
|
+
}
|
|
29
|
+
return "unknown caller";
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
const FIXES =
|
|
33
|
+
"Either set HARNESS_ROOT to the root of the run, " +
|
|
34
|
+
"or pass the root you mean explicitly: harnessRootFor(root).";
|
|
35
|
+
|
|
36
|
+
/**
|
|
37
|
+
* The harness root the CALLER means, stated rather than inferred (#105).
|
|
38
|
+
*
|
|
39
|
+
* Use this from anything that is about to EXECUTE or WRITE — `gate-executor`
|
|
40
|
+
* spawning `bun scripts/sync-spec-tests.ts`, which regenerates files in the
|
|
41
|
+
* tree it is pointed at. For those, "whichever tree this module happens to sit
|
|
42
|
+
* in" is not a default, it is a coin flip between the run's root and the
|
|
43
|
+
* worktree the agent is editing, and the losing side gets written to.
|
|
44
|
+
*/
|
|
45
|
+
export function harnessRootFor(root: string): string {
|
|
46
|
+
if (!root || !root.trim()) {
|
|
47
|
+
throw new Error(
|
|
48
|
+
`harnessRootFor() was given an empty root at ${callSite()}. ` +
|
|
49
|
+
"An explicit root is the caller naming the tree it means; there is no tree to fall back to.",
|
|
50
|
+
);
|
|
51
|
+
}
|
|
52
|
+
return resolve(root);
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
export interface ImplicitRootOptions {
|
|
56
|
+
/** Overrides the inferred `file:line` in refusal messages. */
|
|
57
|
+
caller?: string;
|
|
58
|
+
/**
|
|
59
|
+
* Set by callers whose resolved root will serve reads of harness-owned
|
|
60
|
+
* STATIC files — briefs, rules, templates, specs, generated tests.
|
|
61
|
+
*
|
|
62
|
+
* A dirty implicit root is refused for these. That combination is the exact
|
|
63
|
+
* failure this module exists to stop: nobody said which tree to use, the tree
|
|
64
|
+
* guessed has uncommitted edits, so the file being READ and the file under
|
|
65
|
+
* TEST are two different versions of the same path — and the read succeeds,
|
|
66
|
+
* which is why it was never visible.
|
|
67
|
+
*/
|
|
68
|
+
staticReads?: boolean;
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
function isDirty(root: string): boolean {
|
|
72
|
+
const r = spawnSync("git", ["-C", root, "status", "--porcelain"], {
|
|
73
|
+
encoding: "utf-8",
|
|
74
|
+
timeout: 5000,
|
|
75
|
+
});
|
|
76
|
+
// Not a repo, or git unavailable: nothing to disagree about, so not dirty.
|
|
77
|
+
if (r.status !== 0) return false;
|
|
78
|
+
return (r.stdout || "").trim().length > 0;
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
/**
|
|
82
|
+
* The harness root inferred from the environment.
|
|
83
|
+
*
|
|
84
|
+
* Resolution order, with no fourth step on purpose: `HARNESS_ROOT`, then the
|
|
85
|
+
* tree this module sits in if it carries the `HARNESS.md` marker, then a
|
|
86
|
+
* refusal. The deleted fourth step was `join(process.env.HOME, ".claude")` —
|
|
87
|
+
* a path that almost always exists, so a misconfigured run, an agent in a
|
|
88
|
+
* worktree and a correct run all read happily from it and only one of them was
|
|
89
|
+
* reading the tree under test. A refusal names the call site; a successful read
|
|
90
|
+
* from the wrong tree names nothing.
|
|
91
|
+
*/
|
|
92
|
+
export function harnessRoot(opts: ImplicitRootOptions = {}): string {
|
|
5
93
|
if (process.env.HARNESS_ROOT) return process.env.HARNESS_ROOT;
|
|
94
|
+
const caller = opts.caller || callSite();
|
|
6
95
|
const repoRoot = resolve(import.meta.dir, "..");
|
|
7
|
-
|
|
8
|
-
|
|
96
|
+
|
|
97
|
+
if (!existsSync(join(repoRoot, "HARNESS.md"))) {
|
|
98
|
+
refuse(
|
|
99
|
+
`harnessRoot() cannot tell which harness tree ${caller} means: ` +
|
|
100
|
+
`HARNESS_ROOT is unset and ${repoRoot} carries no HARNESS.md marker. ${FIXES}`,
|
|
101
|
+
);
|
|
102
|
+
return repoRoot; // unreachable unless the refusal has been mutated out
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
if (opts.staticReads && isDirty(repoRoot)) {
|
|
106
|
+
refuse(
|
|
107
|
+
`harnessRoot() refuses to serve reads of harness-owned files to ${caller} ` +
|
|
108
|
+
`from ${repoRoot}: no root was given, and the tree it guessed has uncommitted ` +
|
|
109
|
+
`changes — so the file read and the file under test are different versions. ${FIXES}`,
|
|
110
|
+
);
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
return repoRoot;
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
/**
|
|
117
|
+
* The MAIN repository root containing `dir`, or null if `dir` is not in a repo
|
|
118
|
+
* (#68).
|
|
119
|
+
*
|
|
120
|
+
* SessionStart hooks were calling `process.cwd()` and treating it as the
|
|
121
|
+
* project root. A session opened in `~` therefore skipped worktree cleanup
|
|
122
|
+
* entirely while still reporting "no stale files found", and sessions started
|
|
123
|
+
* in `~/.claude` created a stray worktree tree at `~/.claude/.claude/worktrees`
|
|
124
|
+
* with 16 entries in it. Cleanup ran or didn't based on where a terminal
|
|
125
|
+
* happened to be.
|
|
126
|
+
*
|
|
127
|
+
* `--git-common-dir`, not `--show-toplevel`: from inside a LINKED WORKTREE,
|
|
128
|
+
* `--show-toplevel` returns that worktree. `.claude/worktrees/` lives in the
|
|
129
|
+
* main checkout, so resolving to the worktree would make cleanup look at a
|
|
130
|
+
* directory that is never there — failing silently in the exact situation the
|
|
131
|
+
* cleanup exists to handle. `--git-common-dir` always points at the main
|
|
132
|
+
* repo's `.git`, from a worktree or not.
|
|
133
|
+
*/
|
|
134
|
+
export function repoRootFrom(dir: string): string | null {
|
|
135
|
+
const r = spawnSync("git", ["-C", dir, "rev-parse", "--git-common-dir"], {
|
|
136
|
+
encoding: "utf-8",
|
|
137
|
+
timeout: 5000,
|
|
138
|
+
});
|
|
139
|
+
if (r.status !== 0) return null;
|
|
140
|
+
const gitDir = r.stdout.trim();
|
|
141
|
+
if (!gitDir) return null;
|
|
142
|
+
// Relative when `dir` is already the repo root (".git"); absolute otherwise.
|
|
143
|
+
const repo = dirname(resolve(dir, gitDir));
|
|
144
|
+
// Always hand back a real path. Git returns an absolute, symlink-resolved
|
|
145
|
+
// path from inside a worktree but a bare relative ".git" from the root, so
|
|
146
|
+
// without this the same repo resolves to "/var/..." or "/private/var/..."
|
|
147
|
+
// depending on which directory you asked from. Callers compare these to
|
|
148
|
+
// decide whether to DELETE a worktree, so a string mismatch is not cosmetic.
|
|
149
|
+
try {
|
|
150
|
+
return realpathSync(repo);
|
|
151
|
+
} catch {
|
|
152
|
+
return repo;
|
|
153
|
+
}
|
|
154
|
+
}
|
|
155
|
+
|
|
156
|
+
/**
|
|
157
|
+
* `~/.claude`, named rather than spelled inline (#105).
|
|
158
|
+
*
|
|
159
|
+
* This directory is PAI's actual install location, so for `paiRoot()` it is the
|
|
160
|
+
* right answer. It was ALSO the last line of `harnessRoot()`, where it was the
|
|
161
|
+
* wrong answer — and the two were the same anonymous expression, which is how a
|
|
162
|
+
* harness read ended up pointed at PAI's tree with nothing in the output saying
|
|
163
|
+
* so. Giving the concept one name and one caller makes that confusion a visible
|
|
164
|
+
* edit instead of a copied line.
|
|
165
|
+
*/
|
|
166
|
+
function paiHomeDir(): string {
|
|
167
|
+
// `homedir()` rather than `process.env.HOME || ""`: the old spelling degraded
|
|
168
|
+
// to the RELATIVE path ".claude" when HOME was unset, which resolves against
|
|
169
|
+
// the cwd — another way to read a plausible directory that is not the one
|
|
170
|
+
// meant. It still honours $HOME, which is what the paiRoot probe asserts.
|
|
171
|
+
return join(homedir(), ".claude");
|
|
9
172
|
}
|
|
10
173
|
|
|
11
174
|
export function paiRoot(): string {
|
|
12
|
-
return process.env.PAI_ROOT ||
|
|
175
|
+
return process.env.PAI_ROOT || paiHomeDir();
|
|
13
176
|
}
|
|
14
177
|
|
|
15
178
|
export function workDir(slug: string): string {
|
|
@@ -21,3 +184,31 @@ export function workDir(slug: string): string {
|
|
|
21
184
|
export function gateSaltPath(): string {
|
|
22
185
|
return join(harnessRoot(), "gates", ".gate-salt");
|
|
23
186
|
}
|
|
187
|
+
|
|
188
|
+
/**
|
|
189
|
+
* Return the gate salt path, minting the salt if it does not exist yet.
|
|
190
|
+
*
|
|
191
|
+
* The salt is gitignored, so a fresh checkout has none. Creation used to live
|
|
192
|
+
* inline in `generateHmac` (gates/orchestrator.ts), which made every other
|
|
193
|
+
* reader depend on that one function having run first: `gates/adversarial.test.ts`
|
|
194
|
+
* read the salt directly and threw ENOENT unless `gates/orchestrator.test.ts`
|
|
195
|
+
* happened to execute earlier in the same run. Eight tests were passing on
|
|
196
|
+
* readdir order, which is not alphabetical on ext4 — they would have flipped
|
|
197
|
+
* red on an unrelated commit, and the diff would have explained nothing.
|
|
198
|
+
*
|
|
199
|
+
* Deliberately NOT used by `gates/witness.ts`: verification must fail when the
|
|
200
|
+
* salt is missing rather than quietly mint a new one and validate against it.
|
|
201
|
+
*/
|
|
202
|
+
export function ensureGateSalt(): string {
|
|
203
|
+
const path = gateSaltPath();
|
|
204
|
+
if (!existsSync(path)) {
|
|
205
|
+
mkdirSync(dirname(path), { recursive: true });
|
|
206
|
+
// mode at creation: writeFileSync-then-chmod leaves the salt world-readable
|
|
207
|
+
// for a moment, and a readable salt is a forgeable gate witness.
|
|
208
|
+
writeFileSync(path, randomBytes(32).toString("hex") + "\n", { mode: 0o600 });
|
|
209
|
+
}
|
|
210
|
+
// Re-assert the mode even when the file already existed: a salt readable by
|
|
211
|
+
// other users is a forgeable gate witness.
|
|
212
|
+
if ((statSync(path).mode & 0o777) !== 0o600) chmodSync(path, 0o600);
|
|
213
|
+
return path;
|
|
214
|
+
}
|
|
@@ -0,0 +1,270 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The Phase 2 issue has to carry the ACs it was given (#79).
|
|
3
|
+
*
|
|
4
|
+
* When discovery produces more than `MAX_ACS_PER_ISSUE` ACs, `workflows/
|
|
5
|
+
* ship.js` asks an agent to group them and open a sub-issue for each group
|
|
6
|
+
* after the first. The agent returns a STRUCTURED list — `{number, phase,
|
|
7
|
+
* acIds}` — and separately writes the issue BODY as free prose. Nothing
|
|
8
|
+
* compared the two.
|
|
9
|
+
*
|
|
10
|
+
* On #70 they disagreed completely. The structured list said:
|
|
11
|
+
*
|
|
12
|
+
* AC-7 a greenfield scaffold writes a roles.json with at least three
|
|
13
|
+
* agent role entries that survive a read-back
|
|
14
|
+
* AC-8 hook registrations stored in hooks.json drive consumer hook
|
|
15
|
+
* deployment under the directory layout
|
|
16
|
+
* AC-9 the existing scaffold and scanner test files still pass
|
|
17
|
+
*
|
|
18
|
+
* and the body of #75 described AC-7/8/9 as doc-path cleanup — a restatement
|
|
19
|
+
* of AC-5, which was already in Phase 1. Both halves are internally
|
|
20
|
+
* plausible: the ids line up, the spec cited is real, the line numbers are
|
|
21
|
+
* real. A human or an agent picking up #75 reads the prose, not the list, so
|
|
22
|
+
* the deferral would have re-fixed Phase 1's work, shipped it as complete,
|
|
23
|
+
* and closed the parent while `roles.json` and `hooks.json` went on being
|
|
24
|
+
* written empty for every greenfield consumer — the defect that opened #70.
|
|
25
|
+
*
|
|
26
|
+
* That is scope loss that LOOKS COMPLETE. The sub-issue exists, is linked to
|
|
27
|
+
* its parent, and has well-formed ACs. Nothing is visibly missing, which is
|
|
28
|
+
* why the fix has to be a comparison rather than a better prompt.
|
|
29
|
+
*
|
|
30
|
+
* WHAT THIS MODULE REFUSES, AND WHY EACH ONE IS SEPARATE
|
|
31
|
+
*
|
|
32
|
+
* `decompositionRefusal` reads the structure alone; `phase2BodyViolations`
|
|
33
|
+
* reads a body against the ACs it is supposed to carry. They are separate
|
|
34
|
+
* because they fail separately: a grouping can be sound and the body still
|
|
35
|
+
* describe something else (#70's case), and a body can quote its ACs
|
|
36
|
+
* perfectly while the grouping has silently dropped one.
|
|
37
|
+
*
|
|
38
|
+
* Every refusal here is a refusal rather than a repair. A decomposition the
|
|
39
|
+
* harness "fixes" is an acceptance criterion nobody reviewed, which is the
|
|
40
|
+
* #217 lesson one layer up.
|
|
41
|
+
*/
|
|
42
|
+
|
|
43
|
+
/** An AC as discovery produced it. `statement` is the text that must survive. */
|
|
44
|
+
export interface DecomposedAc {
|
|
45
|
+
id: string;
|
|
46
|
+
statement: string;
|
|
47
|
+
specElement?: string;
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
/** One group the decompose agent proposed. `number` is set once it exists. */
|
|
51
|
+
export interface SubIssuePlan {
|
|
52
|
+
number?: number;
|
|
53
|
+
phase?: string;
|
|
54
|
+
acIds?: string[];
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
/**
|
|
58
|
+
* Everything wrong with a proposed decomposition, or an empty list.
|
|
59
|
+
*
|
|
60
|
+
* Returns a LIST, not a boolean or a first error: a decomposition that drops
|
|
61
|
+
* one AC and duplicates another has two problems, and reporting one of them
|
|
62
|
+
* invites a second round that discovers the other.
|
|
63
|
+
*/
|
|
64
|
+
export function decompositionRefusal(
|
|
65
|
+
allAcs: readonly DecomposedAc[] | null | undefined,
|
|
66
|
+
phase1AcIds: readonly string[] | null | undefined,
|
|
67
|
+
subIssues: readonly SubIssuePlan[] | null | undefined,
|
|
68
|
+
): string[] {
|
|
69
|
+
const acs = Array.isArray(allAcs) ? allAcs : [];
|
|
70
|
+
const phase1 = Array.isArray(phase1AcIds) ? phase1AcIds : [];
|
|
71
|
+
const groups = Array.isArray(subIssues) ? subIssues : [];
|
|
72
|
+
const out: string[] = [];
|
|
73
|
+
|
|
74
|
+
if (acs.length === 0) return ["decomposition was asked for with no ACs to decompose"];
|
|
75
|
+
|
|
76
|
+
const known = new Set<string>();
|
|
77
|
+
for (const ac of acs) {
|
|
78
|
+
if (ac?.id) known.add(ac.id);
|
|
79
|
+
if (ac?.specElement) for (const s of ac.specElement.split(",")) known.add(s.trim());
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
// Phase 1 holding nothing is not a decomposition, it is a deferral of the
|
|
83
|
+
// whole issue — and it reads as success because sub-issues were created.
|
|
84
|
+
if (phase1.length === 0) out.push("no AC was kept for Phase 1 — the whole issue was deferred");
|
|
85
|
+
|
|
86
|
+
for (const id of phase1) {
|
|
87
|
+
if (!known.has(id)) out.push(`Phase 1 keeps ${id}, which discovery never produced`);
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
/** Which groups claim each id — the shape both duplicate cases need. */
|
|
91
|
+
const claimedBy = new Map<string, string[]>();
|
|
92
|
+
for (const [i, g] of groups.entries()) {
|
|
93
|
+
const label = g?.number ? `#${g.number}` : (g?.phase || `group ${i + 1}`);
|
|
94
|
+
const ids = Array.isArray(g?.acIds) ? g.acIds : [];
|
|
95
|
+
if (ids.length === 0) out.push(`${label} was created carrying no ACs`);
|
|
96
|
+
for (const id of ids) {
|
|
97
|
+
if (!known.has(id)) out.push(`${label} claims ${id}, which discovery never produced`);
|
|
98
|
+
claimedBy.set(id, [...(claimedBy.get(id) ?? []), label]);
|
|
99
|
+
}
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
// AC-3. The #70 failure mode exactly: a deferred AC that restates one
|
|
103
|
+
// already being shipped. Flagged, never written.
|
|
104
|
+
const phase1Set = new Set(phase1);
|
|
105
|
+
for (const [id, labels] of claimedBy) {
|
|
106
|
+
if (phase1Set.has(id)) {
|
|
107
|
+
out.push(`${id} is in Phase 1 AND deferred to ${labels.join(" and ")} — a deferral that duplicates shipped work`);
|
|
108
|
+
}
|
|
109
|
+
if (labels.length > 1) {
|
|
110
|
+
out.push(`${id} is claimed by ${labels.join(" and ")} — two phases cannot both own one AC`);
|
|
111
|
+
}
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
// The silent half. An AC in neither Phase 1 nor any sub-issue has been
|
|
115
|
+
// dropped, and every count the run prints still adds up.
|
|
116
|
+
for (const ac of acs) {
|
|
117
|
+
const ids: string[] = [ac.id, ...(ac.specElement ? ac.specElement.split(",").map((s: string) => s.trim()) : [])].filter(Boolean);
|
|
118
|
+
const placed = ids.some(id => phase1Set.has(id) || claimedBy.has(id));
|
|
119
|
+
if (!placed) out.push(`${ac.id} was neither kept nor deferred — it is gone, and nothing else would say so`);
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
return out;
|
|
123
|
+
}
|
|
124
|
+
|
|
125
|
+
/**
|
|
126
|
+
* The ACs one group owns, in discovery's order.
|
|
127
|
+
*
|
|
128
|
+
* One function, so the body comparison and the issue that was created cannot
|
|
129
|
+
* disagree about which ACs belong to a group. Matches on `id` or on any
|
|
130
|
+
* comma-separated `specElement`, because the decompose agent returns either
|
|
131
|
+
* — the same tolerance `workflows/ship.js` already applies when it filters
|
|
132
|
+
* Phase 1, and splitting it in two is how the two would drift.
|
|
133
|
+
*/
|
|
134
|
+
export function acsForGroup(
|
|
135
|
+
acs: readonly DecomposedAc[] | null | undefined,
|
|
136
|
+
group: SubIssuePlan | null | undefined,
|
|
137
|
+
): DecomposedAc[] {
|
|
138
|
+
const ids = new Set<string>(Array.isArray(group?.acIds) ? group!.acIds : []);
|
|
139
|
+
if (ids.size === 0) return [];
|
|
140
|
+
// Annotated because `Array.isArray` narrows a `readonly T[]` to `any[]`,
|
|
141
|
+
// and an `any` here would silently turn every field access below into an
|
|
142
|
+
// unchecked one.
|
|
143
|
+
const list: readonly DecomposedAc[] = Array.isArray(acs) ? acs : [];
|
|
144
|
+
return list.filter(ac => {
|
|
145
|
+
if (ids.has(ac.id)) return true;
|
|
146
|
+
if (!ac.specElement) return false;
|
|
147
|
+
return ac.specElement.split(",").some((s: string) => ids.has(s.trim()));
|
|
148
|
+
});
|
|
149
|
+
}
|
|
150
|
+
|
|
151
|
+
/**
|
|
152
|
+
* Wrap a string so a POSIX shell passes it through untouched.
|
|
153
|
+
*
|
|
154
|
+
* AC statements routinely contain backticks, double quotes and `$`. A
|
|
155
|
+
* single-quoted shell word is literal for every character except `'`, which
|
|
156
|
+
* is closed, escaped and reopened. This is the only quoting in the data path
|
|
157
|
+
* and it exists because the reference copy of the statements must reach disk
|
|
158
|
+
* WITHOUT passing through the model — a model that reworded both the body
|
|
159
|
+
* and the thing the body is compared against would pass any comparison.
|
|
160
|
+
*/
|
|
161
|
+
export function shellSingleQuote(value: string): string {
|
|
162
|
+
return `'${String(value).replace(/'/g, `'\\''`)}'`;
|
|
163
|
+
}
|
|
164
|
+
|
|
165
|
+
/**
|
|
166
|
+
* The AC list as it appears in the decompose prompt.
|
|
167
|
+
*
|
|
168
|
+
* The prompt used to list no ACs at all, so the agent wrote each sub-issue
|
|
169
|
+
* body by reconstructing the scope from memory — which is exactly how #75's
|
|
170
|
+
* body came to describe Phase 1's work. The statements are now in front of
|
|
171
|
+
* it, verbatim, in the form it is asked to copy.
|
|
172
|
+
*/
|
|
173
|
+
export function acListBlock(acs: readonly DecomposedAc[]): string {
|
|
174
|
+
return acs.map(ac => `- [ ] ${ac.id}: ${ac.statement}`).join("\n");
|
|
175
|
+
}
|
|
176
|
+
|
|
177
|
+
/**
|
|
178
|
+
* The command that writes the comparison's reference copy of the ACs.
|
|
179
|
+
*
|
|
180
|
+
* Emitted into the prompt for the agent to run verbatim, the way every other
|
|
181
|
+
* `bun -e` in this workflow is. The payload is the harness's own validated
|
|
182
|
+
* discovery output, shell-quoted here rather than composed by the model.
|
|
183
|
+
*/
|
|
184
|
+
export function phase2AcsCommand(harnessRoot: string, workDir: string, acs: readonly DecomposedAc[]): string {
|
|
185
|
+
const payload = JSON.stringify(acs.map(a => ({ id: a.id, statement: a.statement, specElement: a.specElement })));
|
|
186
|
+
return (
|
|
187
|
+
`cd ${harnessRoot} && bun -e 'require("fs").writeFileSync(process.argv[1], process.argv[2])' ` +
|
|
188
|
+
`${workDir}/phase2-acs.json ${shellSingleQuote(payload)}`
|
|
189
|
+
);
|
|
190
|
+
}
|
|
191
|
+
|
|
192
|
+
/** The heading the comparison reads under. Must match what the prompt asks for. */
|
|
193
|
+
export const SC_HEADING = "## Success Criteria";
|
|
194
|
+
|
|
195
|
+
/**
|
|
196
|
+
* Normalise for comparison WITHOUT making the comparison meaningless.
|
|
197
|
+
*
|
|
198
|
+
* Markdown wraps, so a statement written across two lines is the same
|
|
199
|
+
* statement; collapsing runs of whitespace is therefore required rather than
|
|
200
|
+
* lenient. Nothing else is touched — not case, not punctuation, not the
|
|
201
|
+
* backticks around an identifier. A looser comparison here is how a body
|
|
202
|
+
* that paraphrases its AC would start passing, which is the whole defect.
|
|
203
|
+
*/
|
|
204
|
+
function normalise(text: string): string {
|
|
205
|
+
return text.replace(/\s+/g, " ").trim();
|
|
206
|
+
}
|
|
207
|
+
|
|
208
|
+
/**
|
|
209
|
+
* Everything wrong with a Phase 2 body, given the ACs it is supposed to carry.
|
|
210
|
+
*
|
|
211
|
+
* Covers #79 AC-1 (same ids) and AC-2 (statements verbatim, by string
|
|
212
|
+
* equality after whitespace collapsing). The id check alone would have passed
|
|
213
|
+
* #75 — its body listed AC-7, AC-8 and AC-9 — so the statement check is the
|
|
214
|
+
* load-bearing half and the id check is there for the case where a body
|
|
215
|
+
* silently carries one fewer.
|
|
216
|
+
*/
|
|
217
|
+
export function phase2BodyViolations(
|
|
218
|
+
body: string | null | undefined,
|
|
219
|
+
acs: readonly DecomposedAc[] | null | undefined,
|
|
220
|
+
): string[] {
|
|
221
|
+
const text = typeof body === "string" ? body : "";
|
|
222
|
+
const expected = Array.isArray(acs) ? acs : [];
|
|
223
|
+
const out: string[] = [];
|
|
224
|
+
|
|
225
|
+
if (expected.length === 0) return ["no ACs were supplied to compare the body against"];
|
|
226
|
+
if (normalise(text) === "") return ["the issue body is empty"];
|
|
227
|
+
|
|
228
|
+
const headingAt = text.indexOf(SC_HEADING);
|
|
229
|
+
if (headingAt < 0) {
|
|
230
|
+
return [`the body has no "${SC_HEADING}" section, so there is nothing to compare the AC list against`];
|
|
231
|
+
}
|
|
232
|
+
// Everything from the heading to the next H2, which is the section the
|
|
233
|
+
// prompt asks for. Reading the WHOLE body would let an AC id mentioned in
|
|
234
|
+
// passing somewhere else satisfy the check.
|
|
235
|
+
const rest = text.slice(headingAt + SC_HEADING.length);
|
|
236
|
+
const nextH2 = rest.search(/^## /m);
|
|
237
|
+
const section = nextH2 < 0 ? rest : rest.slice(0, nextH2);
|
|
238
|
+
const flat = normalise(section);
|
|
239
|
+
|
|
240
|
+
for (const ac of expected) {
|
|
241
|
+
if (!new RegExp(`(^|[^A-Za-z0-9-])${ac.id}([^A-Za-z0-9-]|$)`).test(flat)) {
|
|
242
|
+
out.push(`${ac.id} is in the deferred list and not in the body's ${SC_HEADING} section`);
|
|
243
|
+
continue;
|
|
244
|
+
}
|
|
245
|
+
const statement = normalise(ac.statement ?? "");
|
|
246
|
+
if (statement === "") {
|
|
247
|
+
out.push(`${ac.id} has no statement in discovery, so the body cannot be checked against it`);
|
|
248
|
+
continue;
|
|
249
|
+
}
|
|
250
|
+
if (!flat.includes(statement)) {
|
|
251
|
+
out.push(
|
|
252
|
+
`${ac.id}'s statement is not carried verbatim. discovery: "${statement}" — ` +
|
|
253
|
+
`the body describes something else, which is #70's defect: the ids lined up and the work did not`,
|
|
254
|
+
);
|
|
255
|
+
}
|
|
256
|
+
}
|
|
257
|
+
|
|
258
|
+
// The other direction. A body carrying an id that was never deferred to it
|
|
259
|
+
// is the #75 shape read from the body's side: plausible, well-formed, and
|
|
260
|
+
// about different work.
|
|
261
|
+
const expectedIds = new Set(expected.map(a => a.id));
|
|
262
|
+
for (const found of flat.matchAll(/(?:^|[^A-Za-z0-9-])(AC-\d+)(?![A-Za-z0-9-])/g)) {
|
|
263
|
+
const id = found[1]!;
|
|
264
|
+
if (!expectedIds.has(id)) {
|
|
265
|
+
out.push(`the body's ${SC_HEADING} section lists ${id}, which was not deferred to this issue`);
|
|
266
|
+
}
|
|
267
|
+
}
|
|
268
|
+
|
|
269
|
+
return out;
|
|
270
|
+
}
|
|
@@ -0,0 +1,157 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Post-fix verification for ship-and-heal workflow.
|
|
3
|
+
*
|
|
4
|
+
* After a conformity fix is applied, verifies that the ROOT CAUSE was fixed
|
|
5
|
+
* (generator/template updated) not just the symptom (generated output file).
|
|
6
|
+
*
|
|
7
|
+
* Ref: Ship-and-heal post-fix verification (PROJECT-STATE P1)
|
|
8
|
+
*/
|
|
9
|
+
|
|
10
|
+
import { spawnSync } from 'child_process';
|
|
11
|
+
|
|
12
|
+
export interface PostFixResult {
|
|
13
|
+
/** Overall assessment */
|
|
14
|
+
status: 'DURABLE' | 'WARN_NON_DURABLE' | 'UNKNOWN';
|
|
15
|
+
/** Files changed that are generators/templates */
|
|
16
|
+
generatorFilesChanged: string[];
|
|
17
|
+
/** Files changed that are generated outputs */
|
|
18
|
+
generatedFilesChanged: string[];
|
|
19
|
+
/** Files changed that are neither (normal source) */
|
|
20
|
+
otherFilesChanged: string[];
|
|
21
|
+
/** Human-readable message */
|
|
22
|
+
message: string;
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
/**
|
|
26
|
+
* Known generator/template file patterns.
|
|
27
|
+
* These are the SOURCE files that produce generated output.
|
|
28
|
+
*/
|
|
29
|
+
const GENERATOR_PATTERNS = [
|
|
30
|
+
'scripts/scaffold-project.ts',
|
|
31
|
+
'templates/',
|
|
32
|
+
'specs/', // Specs generate conformity tests
|
|
33
|
+
] as const;
|
|
34
|
+
|
|
35
|
+
/**
|
|
36
|
+
* Known generated output file patterns.
|
|
37
|
+
* These files are PRODUCED by running scaffold-project.ts.
|
|
38
|
+
*/
|
|
39
|
+
const GENERATED_PATTERNS = [
|
|
40
|
+
'.claude/agents/',
|
|
41
|
+
'CODE-MAP.md',
|
|
42
|
+
'test/scaffold-conformity.test.ts',
|
|
43
|
+
'.github/workflows/ci.yml',
|
|
44
|
+
'.github/workflows/gates.yml',
|
|
45
|
+
] as const;
|
|
46
|
+
|
|
47
|
+
/**
|
|
48
|
+
* Classify a file path as generator, generated, or other.
|
|
49
|
+
*/
|
|
50
|
+
function classifyFile(filePath: string): 'generator' | 'generated' | 'other' {
|
|
51
|
+
// Check generator patterns
|
|
52
|
+
for (const pattern of GENERATOR_PATTERNS) {
|
|
53
|
+
if (filePath.includes(pattern)) {
|
|
54
|
+
return 'generator';
|
|
55
|
+
}
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
// Check generated patterns
|
|
59
|
+
for (const pattern of GENERATED_PATTERNS) {
|
|
60
|
+
if (filePath.includes(pattern)) {
|
|
61
|
+
return 'generated';
|
|
62
|
+
}
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
return 'other';
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
/**
|
|
69
|
+
* Verify that a fix touched generator files, not just generated output.
|
|
70
|
+
*
|
|
71
|
+
* @param changedFiles - List of file paths that were changed during the fix
|
|
72
|
+
* @returns Analysis of what was changed and whether the fix is durable
|
|
73
|
+
*
|
|
74
|
+
* @example
|
|
75
|
+
* const result = verifyPostFix([
|
|
76
|
+
* '.claude/agents/marcus.md',
|
|
77
|
+
* 'templates/agent-briefs/marcus.md'
|
|
78
|
+
* ]);
|
|
79
|
+
* if (result.status === 'WARN_NON_DURABLE') {
|
|
80
|
+
* console.warn(result.message);
|
|
81
|
+
* }
|
|
82
|
+
*/
|
|
83
|
+
export function verifyPostFix(changedFiles: string[]): PostFixResult {
|
|
84
|
+
const generatorFilesChanged: string[] = [];
|
|
85
|
+
const generatedFilesChanged: string[] = [];
|
|
86
|
+
const otherFilesChanged: string[] = [];
|
|
87
|
+
|
|
88
|
+
// Classify each changed file
|
|
89
|
+
for (const file of changedFiles) {
|
|
90
|
+
const classification = classifyFile(file);
|
|
91
|
+
switch (classification) {
|
|
92
|
+
case 'generator':
|
|
93
|
+
generatorFilesChanged.push(file);
|
|
94
|
+
break;
|
|
95
|
+
case 'generated':
|
|
96
|
+
generatedFilesChanged.push(file);
|
|
97
|
+
break;
|
|
98
|
+
case 'other':
|
|
99
|
+
otherFilesChanged.push(file);
|
|
100
|
+
break;
|
|
101
|
+
}
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
// Determine status
|
|
105
|
+
let status: PostFixResult['status'];
|
|
106
|
+
let message: string;
|
|
107
|
+
|
|
108
|
+
if (generatedFilesChanged.length > 0 && generatorFilesChanged.length === 0) {
|
|
109
|
+
// WARN: Only generated files were changed, no generator files
|
|
110
|
+
status = 'WARN_NON_DURABLE';
|
|
111
|
+
message = `Fix may not be durable — ${generatedFilesChanged.length} generated file(s) changed but no generator/template files updated. Next scaffold run will regenerate the broken version.`;
|
|
112
|
+
} else if (generatorFilesChanged.length > 0) {
|
|
113
|
+
// DURABLE: Generator files were changed
|
|
114
|
+
status = 'DURABLE';
|
|
115
|
+
message = `Fix is durable — ${generatorFilesChanged.length} generator/template file(s) updated.`;
|
|
116
|
+
} else if (changedFiles.length === 0) {
|
|
117
|
+
// UNKNOWN: No files changed
|
|
118
|
+
status = 'UNKNOWN';
|
|
119
|
+
message = 'No files changed during fix.';
|
|
120
|
+
} else {
|
|
121
|
+
// UNKNOWN: Only "other" files changed (not generator or generated)
|
|
122
|
+
status = 'UNKNOWN';
|
|
123
|
+
message = `${otherFilesChanged.length} source file(s) changed. Not scaffold-related.`;
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
return {
|
|
127
|
+
status,
|
|
128
|
+
generatorFilesChanged,
|
|
129
|
+
generatedFilesChanged,
|
|
130
|
+
otherFilesChanged,
|
|
131
|
+
message,
|
|
132
|
+
};
|
|
133
|
+
}
|
|
134
|
+
|
|
135
|
+
/**
|
|
136
|
+
* Get list of changed files from git diff.
|
|
137
|
+
*
|
|
138
|
+
* @param cwd - Working directory (project root)
|
|
139
|
+
* @param baseRef - Base ref to compare against (default: HEAD)
|
|
140
|
+
* @returns Array of file paths changed
|
|
141
|
+
*/
|
|
142
|
+
export function getChangedFiles(cwd: string, baseRef: string = 'HEAD'): string[] {
|
|
143
|
+
// Get changed files since baseRef (unstaged + staged)
|
|
144
|
+
const result = spawnSync('git', ['diff', '--name-only', baseRef], {
|
|
145
|
+
cwd,
|
|
146
|
+
encoding: 'utf-8',
|
|
147
|
+
});
|
|
148
|
+
|
|
149
|
+
if (result.status !== 0) {
|
|
150
|
+
return [];
|
|
151
|
+
}
|
|
152
|
+
|
|
153
|
+
return result.stdout
|
|
154
|
+
.split('\n')
|
|
155
|
+
.map(line => line.trim())
|
|
156
|
+
.filter(line => line.length > 0);
|
|
157
|
+
}
|