rungate 0.2.0 → 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- 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 +36 -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/.claude/agents/aditi.md +0 -47
- package/.claude/agents/marcus.md +0 -50
- package/.claude/agents/quinn.md +0 -58
- package/.claude/agents/rook.md +0 -47
- package/.claude/agents/serena.md +0 -46
- package/.claude/rungate.json +0 -11
- package/.fallowrc.json +0 -28
- package/.github/copilot-instructions.md +0 -20
- package/.rungate/conformity-findings.json +0 -648
- package/AGENTS.md +0 -106
- package/CODE-MAP.md +0 -50
- package/HARNESS.md +0 -88
- package/bun.lock +0 -26
- package/bunfig.toml +0 -2
- package/config/brief-policies.json +0 -28
- package/config/ceremony-profiles.json +0 -212
- package/config/consumer-cascade-map.json +0 -24
- package/config/doc-cascade-map.json +0 -24
- package/config/eval.json +0 -84
- package/config/profiles/account-plan.yaml +0 -36
- package/config/profiles/campaign.yaml +0 -94
- package/config/prove-evidence.schema.json +0 -65
- package/config/spec-policies.json +0 -36
- package/config/workflow-schema.json +0 -281
- package/gates/SCHEMA-GUIDE.md +0 -121
- package/gates/ac-quality.test.ts +0 -106
- package/gates/adversarial.test.ts +0 -274
- package/gates/brief-assembler.test.ts +0 -429
- package/gates/brief-assembler.ts +0 -334
- package/gates/bunfig.toml +0 -2
- package/gates/chain.test.ts +0 -91
- package/gates/e2e-smoke.test.ts +0 -234
- package/gates/error-classifier.test.ts +0 -249
- package/gates/error-classifier.ts +0 -89
- package/gates/orchestrator.test.ts +0 -950
- package/gates/orchestrator.ts +0 -569
- package/gates/preload.ts +0 -77
- package/gates/prompts/ac-adversary.md +0 -20
- package/gates/prompts/evidence-validator.md +0 -22
- package/gates/prompts/prove-reproducer.md +0 -53
- package/gates/prove.test.ts +0 -164
- package/gates/run-gate.ts +0 -936
- package/gates/schema-parity.test.ts +0 -197
- package/gates/schema.ts +0 -362
- package/gates/self-heal.test.ts +0 -511
- package/gates/self-heal.ts +0 -121
- package/gates/ship-orchestrator.test.ts +0 -379
- package/gates/ship-orchestrator.ts +0 -363
- package/gates/test-fixtures/broken-no-environments.json +0 -60
- package/gates/test-fixtures/valid-standard.json +0 -54
- package/gates/test-utils.ts +0 -43
- package/gates/witness.ts +0 -220
- package/gates/workflow.test.ts +0 -1053
- package/hooks/AgentBriefGuard.hook.ts +0 -586
- package/hooks/AgentVerdictCapture.hook.ts +0 -134
- package/hooks/AutoVerifyGate.hook.ts +0 -76
- package/hooks/GateEnforcement.hook.ts +0 -273
- package/hooks/IssueCloseGuard.hook.ts +0 -116
- package/hooks/MergeGuard.hook.ts +0 -55
- package/hooks/StaleTTLCleanup.hook.ts +0 -133
- package/hooks/VerifyPhaseLock.hook.ts +0 -81
- package/hooks/WorkflowStateGuard.hook.ts +0 -37
- package/hooks/lib/agentDetection.ts +0 -70
- package/hooks/lib/findWorkflow.ts +0 -101
- package/hooks/lib/parseStdin.ts +0 -37
- package/hooks/lib/paths.ts +0 -111
- package/hooks/lib/utils.ts +0 -81
- package/reference/migration-manifest.json +0 -554
- package/reference/prompts/agent-aditi.md +0 -38
- package/reference/prompts/agent-marcus.md +0 -38
- package/reference/prompts/agent-quinn.md +0 -38
- package/reference/prompts/agent-rook.md +0 -37
- package/reference/prompts/agent-serena.md +0 -37
- package/reference/prompts/council-skill.md +0 -170
- package/reference/prompts/goal-skill.md +0 -235
- package/reference/prompts/prove-skill.md +0 -283
- package/reference/prompts/quinn-standard.md +0 -246
- package/reference/prompts/ship-convergence.md +0 -65
- package/reference/prompts/ship-escalation.md +0 -43
- package/reference/prompts/ship-iteration.md +0 -382
- package/reference/prompts/ship-pending-patches.md +0 -246
- package/reference/prompts/ship-reference.md +0 -250
- package/reference/prompts/ship-skill.md +0 -347
- package/reference/prompts/ship-templates.md +0 -215
- package/reference/scripts/batch-status.sh +0 -68
- package/reference/scripts/chain-compat-check.sh +0 -67
- package/reference/scripts/context-audit.sh +0 -314
- package/reference/scripts/dead-export-check.sh +0 -61
- package/reference/scripts/generate-qc-tables.sh +0 -92
- package/reference/scripts/harness-init.sh +0 -111
- package/reference/scripts/pai-054-baseline-check.sh +0 -40
- package/reference/scripts/prove-smoke-test.sh +0 -112
- package/reference/scripts/setup-keychain-salt.sh +0 -12
- package/reference/scripts/skill-optimizer-friday.sh +0 -88
- package/reference/scripts/skill-qc-test.sh +0 -351
- package/reference/scripts/skill-synthesize-tonight.sh +0 -66
- package/reference/specs/HARNESS-EXTRACTION-SPEC.md +0 -263
- package/reference/specs/harness-v3-bash-deletion-plan.md +0 -65
- package/reference/specs/harness-v3-migration-plan.md +0 -188
- package/scripts/decision-reconcile.sh +0 -74
- package/scripts/decision-reconcile.ts +0 -152
- package/scripts/git-hooks/pre-commit +0 -76
- package/scripts/git-hooks/pre-push +0 -271
- package/scripts/harness-skill-check.sh +0 -52
- package/scripts/lib/gap-emit.sh +0 -65
- package/scripts/lib/jq-update.sh +0 -30
- package/scripts/lib/resolve-slug.sh +0 -30
- package/scripts/lib/verify-spec-compliance.sh +0 -102
- package/scripts/prove-backfill.sh +0 -87
- package/scripts/scaffold-rungate-config.ts +0 -91
- package/scripts/self-containment-check.sh +0 -109
- package/scripts/skill-qc-validator.sh +0 -402
- package/scripts/slug-resolver.sh +0 -14
- package/specs/BOOTSTRAP-DATA-FLOW-SPEC.md +0 -2493
- package/specs/BOOTSTRAP-TEST-PLAN.md +0 -571
- package/specs/HARNESS-GATES.md +0 -256
- package/specs/HARNESS-SKILL-CHAIN.md +0 -286
- package/specs/HARNESS-SKILL-CONTRACT.md +0 -93
- package/specs/HARNESS-STANDARD.md +0 -488
- package/specs/SPEC-TEMPLATE.md +0 -53
- package/specs/bootstrap-data-flow.png +0 -0
- package/specs/harness-automation-matrix.md +0 -314
- package/specs/harness-automation-matrix.rules.json +0 -64
- package/test/anti.test.ts +0 -80
- package/test/contract-negative.test.ts +0 -86
- package/test/contract.test.ts +0 -158
- package/test/external-deps.test.ts +0 -48
- package/test/fixtures/golden-project/.env.example +0 -3
- package/test/fixtures/golden-project/Makefile +0 -7
- package/test/fixtures/golden-project/docs/adr/ADR-001-framework.md +0 -23
- package/test/fixtures/golden-project/docs/setup-guide.md +0 -10
- package/test/fixtures/golden-project/package.json +0 -10
- package/test/fixtures/golden-project/specs/api-spec.md +0 -20
- package/test/fixtures/golden-project/src/auth.ts +0 -8
- package/test/fixtures/golden-project/src/db.ts +0 -11
- package/test/fixtures/golden-project/src/index.ts +0 -19
- package/test/fixtures/golden-project/src/utils/format.ts +0 -3
- package/test/fixtures/golden-project/test/auth.test.ts +0 -15
- package/test/fixtures/golden-project/tsconfig.json +0 -12
- package/test/meta-sc-coverage.test.ts +0 -159
- package/test/phase-0.test.ts +0 -846
- package/test/phase-1.test.ts +0 -617
- package/test/phase-2.test.ts +0 -620
- package/test/phase-3.test.ts +0 -99
- package/test/scaffold-conformity.test.ts +0 -8
- package/test/schema-canary.test.ts +0 -51
- package/test/spec-compliance-auto.test.ts +0 -64
- package/test/spec-compliance.test.ts +0 -295
- package/test/spec-discovery.test.ts +0 -68
- package/test/spec-drift.test.ts +0 -5
- package/test/structure.test.ts +0 -165
- package/test/unit/agent-brief-guard-ship.test.ts +0 -293
- package/test/unit/extract-constraints.test.ts +0 -145
- package/test/unit/issue-close-guard.test.ts +0 -204
- package/test/unit/scaffold-project.test.ts +0 -417
- package/test/unit/skill-cooccurrence.test.ts +0 -177
- package/test/unit/skill-sequence-logger.test.ts +0 -244
- package/test/unit/workflow-state-guard.test.ts +0 -95
- package/workflows/batch-ship.js +0 -295
- package/workflows/council.js +0 -481
- package/workflows/prove.js +0 -560
- package/workflows/ship.js +0 -789
- package/workflows/verify.js +0 -236
|
@@ -0,0 +1,370 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* managed-workflow.ts — deciding what a re-scaffold is allowed to do to a
|
|
3
|
+
* workflow file a consumer has since edited (#216).
|
|
4
|
+
*
|
|
5
|
+
* `createCiWorkflows` ended in two unconditional `writeFileSync` calls, and
|
|
6
|
+
* re-scaffolding is the documented way both to onboard a consumer AND to
|
|
7
|
+
* update one. So every update destroyed whatever the consumer had added to
|
|
8
|
+
* `.github/workflows/ci.yml`. That is the whole of SUCCESS.md claim 5 — the
|
|
9
|
+
* harness works on a repo that is not this one — and it could not be claimed
|
|
10
|
+
* while the first real consumer's build would be deleted by the second run.
|
|
11
|
+
*
|
|
12
|
+
* ## The one hard problem
|
|
13
|
+
*
|
|
14
|
+
* Given a file on disk and a freshly generated one, the harness has to tell
|
|
15
|
+
* three things apart:
|
|
16
|
+
*
|
|
17
|
+
* a. content the harness wrote and is now regenerating differently
|
|
18
|
+
* (a config change: a shorter branch list, a different bun version)
|
|
19
|
+
* b. content the consumer added that the harness can carry over (a job)
|
|
20
|
+
* c. content the consumer added that the harness CANNOT carry over (a step
|
|
21
|
+
* inside a job the harness owns, a hand-written file predating rungate)
|
|
22
|
+
*
|
|
23
|
+
* Text comparison alone cannot separate (a) from (c): both look like "a line
|
|
24
|
+
* that was there and is not in the new output". So the harness records what it
|
|
25
|
+
* wrote. Every file it writes carries
|
|
26
|
+
*
|
|
27
|
+
* # rungate-managed-sha256: <hex>
|
|
28
|
+
*
|
|
29
|
+
* over the harness-authored region with the marker line removed. On the next
|
|
30
|
+
* run that region is reconstructed out of the file on disk and re-hashed. A
|
|
31
|
+
* match proves the harness authored every line of it, so those lines may be
|
|
32
|
+
* replaced freely — that is case (a). No match, or no marker at all, means the
|
|
33
|
+
* harness can prove nothing, and anything it would drop is treated as the
|
|
34
|
+
* consumer's — case (c), which is refused rather than written.
|
|
35
|
+
*
|
|
36
|
+
* Case (b) is the merge: consumer-only jobs and consumer-only top-level keys
|
|
37
|
+
* are carried into the new output verbatim.
|
|
38
|
+
*
|
|
39
|
+
* ## Deliberately fail-closed
|
|
40
|
+
*
|
|
41
|
+
* When the harness cannot prove it wrote something, it refuses. A consumer
|
|
42
|
+
* whose ci.yml predates rungate gets a refusal on first scaffold rather than a
|
|
43
|
+
* replaced build, and `--force` is the only thing that overrides it. A refusal
|
|
44
|
+
* a consumer has to read is cheap; a deleted deploy job is not.
|
|
45
|
+
*/
|
|
46
|
+
import { createHash } from "crypto";
|
|
47
|
+
|
|
48
|
+
/** Prefix of the single line recording what the harness authored. */
|
|
49
|
+
export const MANAGED_MARKER_PREFIX = "# rungate-managed-sha256: ";
|
|
50
|
+
|
|
51
|
+
/** A top-level YAML key at column zero. Block scalars are always indented. */
|
|
52
|
+
const TOP_LEVEL_KEY = /^([A-Za-z_][A-Za-z0-9_.\-]*):(?:\s|$)/;
|
|
53
|
+
|
|
54
|
+
export type ManagedWriteVerb = "CREATED" | "UPDATED" | "REPLACED" | "SKIP" | "REFUSED";
|
|
55
|
+
|
|
56
|
+
export interface ManagedWritePlan {
|
|
57
|
+
verb: ManagedWriteVerb;
|
|
58
|
+
/** Bytes to write. Meaningless for SKIP and REFUSED — nothing is written. */
|
|
59
|
+
content: string;
|
|
60
|
+
/** Lines in the proposed content minus lines in the file on disk. 0 for a new file. */
|
|
61
|
+
lineDelta: number;
|
|
62
|
+
/** Jobs in the file on disk holding content the write would lose. */
|
|
63
|
+
atRiskJobs: string[];
|
|
64
|
+
/** Non-blank lines the write would lose and the harness cannot prove it wrote. */
|
|
65
|
+
lostLines: string[];
|
|
66
|
+
/** Populated only when verb === "REFUSED". Names the jobs and the line delta. */
|
|
67
|
+
refusal: string | null;
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
interface Section {
|
|
71
|
+
key: string;
|
|
72
|
+
lines: string[];
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
interface JobBlock {
|
|
76
|
+
name: string;
|
|
77
|
+
lines: string[];
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
// ── reading the shape of a workflow file ───────────────────────────────────
|
|
81
|
+
|
|
82
|
+
function splitTopLevel(text: string): Section[] {
|
|
83
|
+
const out: Section[] = [];
|
|
84
|
+
let cur: Section = { key: "", lines: [] };
|
|
85
|
+
for (const line of text.split("\n")) {
|
|
86
|
+
const m = TOP_LEVEL_KEY.exec(line);
|
|
87
|
+
if (m) {
|
|
88
|
+
if (cur.key !== "" || cur.lines.length > 0) out.push(cur);
|
|
89
|
+
cur = { key: m[1], lines: [line] };
|
|
90
|
+
} else {
|
|
91
|
+
cur.lines.push(line);
|
|
92
|
+
}
|
|
93
|
+
}
|
|
94
|
+
out.push(cur);
|
|
95
|
+
return out;
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
/**
|
|
99
|
+
* Split a `jobs:` section into its header and one block per job.
|
|
100
|
+
*
|
|
101
|
+
* A job starts at the shallowest indentation in the section, which is how YAML
|
|
102
|
+
* mapping keys work. Each block keeps every line up to the next job — blank
|
|
103
|
+
* lines included — so putting the blocks back together is byte-exact.
|
|
104
|
+
*/
|
|
105
|
+
function parseJobsSection(lines: string[]): { head: string[]; jobs: JobBlock[] } {
|
|
106
|
+
const body = lines.slice(1);
|
|
107
|
+
let base = -1;
|
|
108
|
+
for (const l of body) {
|
|
109
|
+
if (l.trim() === "") continue;
|
|
110
|
+
// Comments do not set the indentation of a YAML mapping, and a consumer's
|
|
111
|
+
// trailing `# note` at column zero lands in this section because it is not
|
|
112
|
+
// a top-level key. Letting it set `base` to 0 made every job fail the
|
|
113
|
+
// `indent === base` test, so the whole mapping was read as section head
|
|
114
|
+
// and the merge dropped every consumer job — caught by the loss count
|
|
115
|
+
// rather than written, but a silent destruction one refusal away.
|
|
116
|
+
if (l.trimStart().startsWith("#")) continue;
|
|
117
|
+
const indent = l.length - l.trimStart().length;
|
|
118
|
+
if (base < 0 || indent < base) base = indent;
|
|
119
|
+
}
|
|
120
|
+
const isJobStart = (l: string) =>
|
|
121
|
+
base >= 0 &&
|
|
122
|
+
l.length - l.trimStart().length === base &&
|
|
123
|
+
/^[A-Za-z0-9_.\-]+:\s*(#.*)?$/.test(l.trim());
|
|
124
|
+
|
|
125
|
+
const head = [lines[0]];
|
|
126
|
+
const jobs: JobBlock[] = [];
|
|
127
|
+
for (const l of body) {
|
|
128
|
+
if (isJobStart(l)) {
|
|
129
|
+
jobs.push({ name: l.trim().replace(/:.*$/, ""), lines: [l] });
|
|
130
|
+
} else if (jobs.length === 0) {
|
|
131
|
+
head.push(l);
|
|
132
|
+
} else {
|
|
133
|
+
jobs[jobs.length - 1].lines.push(l);
|
|
134
|
+
}
|
|
135
|
+
}
|
|
136
|
+
return { head, jobs };
|
|
137
|
+
}
|
|
138
|
+
|
|
139
|
+
/** Split trailing blank lines off a block. */
|
|
140
|
+
function splitTrailingBlanks(lines: string[]): [string[], string[]] {
|
|
141
|
+
let end = lines.length;
|
|
142
|
+
while (end > 0 && lines[end - 1].trim() === "") end--;
|
|
143
|
+
return [lines.slice(0, end), lines.slice(end)];
|
|
144
|
+
}
|
|
145
|
+
|
|
146
|
+
function jobsSectionOf(sections: Section[]): Section | undefined {
|
|
147
|
+
return sections.find(s => s.key === "jobs");
|
|
148
|
+
}
|
|
149
|
+
|
|
150
|
+
/** Every job name in a workflow file, in file order. */
|
|
151
|
+
export function jobNames(text: string): string[] {
|
|
152
|
+
const jobs = jobsSectionOf(splitTopLevel(text));
|
|
153
|
+
return jobs ? parseJobsSection(jobs.lines).jobs.map(j => j.name) : [];
|
|
154
|
+
}
|
|
155
|
+
|
|
156
|
+
// ── the merge ──────────────────────────────────────────────────────────────
|
|
157
|
+
|
|
158
|
+
function mergeJobsSection(before: Section, generated: Section): string[] {
|
|
159
|
+
const g = parseJobsSection(generated.lines);
|
|
160
|
+
const b = parseJobsSection(before.lines);
|
|
161
|
+
const generatedNames = new Set(g.jobs.map(j => j.name));
|
|
162
|
+
const extra = b.jobs.filter(j => !generatedNames.has(j.name));
|
|
163
|
+
if (extra.length === 0) return generated.lines;
|
|
164
|
+
|
|
165
|
+
const [content, trailing] = splitTrailingBlanks(g.jobs.flatMap(j => j.lines));
|
|
166
|
+
const carried = extra.flatMap(j => splitTrailingBlanks(j.lines)[0]);
|
|
167
|
+
return [...g.head, ...content, ...carried, ...trailing];
|
|
168
|
+
}
|
|
169
|
+
|
|
170
|
+
/**
|
|
171
|
+
* The newly generated file with everything the harness did not author carried
|
|
172
|
+
* across: consumer-only jobs appended to the jobs mapping, consumer-only
|
|
173
|
+
* top-level keys appended to the file.
|
|
174
|
+
*/
|
|
175
|
+
export function mergeManagedWorkflow(before: string, generated: string): string {
|
|
176
|
+
const b = splitTopLevel(before);
|
|
177
|
+
const g = splitTopLevel(generated);
|
|
178
|
+
const generatedKeys = new Set(g.map(s => s.key));
|
|
179
|
+
const beforeJobs = jobsSectionOf(b);
|
|
180
|
+
const beforeByKey = new Map(b.filter(s => s.key !== "").map(s => [s.key, s] as const));
|
|
181
|
+
|
|
182
|
+
const out: string[] = [];
|
|
183
|
+
for (const section of g) {
|
|
184
|
+
// The ownership rule, and the only one this file needs to state:
|
|
185
|
+
//
|
|
186
|
+
// the harness owns the JOBS it generates, and its own preamble.
|
|
187
|
+
// every other top-level key belongs to the consumer, if the consumer
|
|
188
|
+
// already has one.
|
|
189
|
+
//
|
|
190
|
+
// The generated `on:` is a default for a file that does not exist yet, not
|
|
191
|
+
// a claim on one that does. Replacing a consumer's `on:` wholesale is how
|
|
192
|
+
// DailyBriefDashboard lost its `workflow_dispatch` trigger and its
|
|
193
|
+
// `paths-ignore` list to a write that reported success — and a consumer's
|
|
194
|
+
// trailing comments live in the section of the key above them, so this is
|
|
195
|
+
// also what keeps those.
|
|
196
|
+
if (section.key === "jobs" && beforeJobs) out.push(...mergeJobsSection(beforeJobs, section));
|
|
197
|
+
else if (section.key !== "" && beforeByKey.has(section.key)) {
|
|
198
|
+
out.push(...beforeByKey.get(section.key)!.lines);
|
|
199
|
+
} else out.push(...section.lines);
|
|
200
|
+
}
|
|
201
|
+
|
|
202
|
+
const extraSections = b.filter(s => s.key !== "" && !generatedKeys.has(s.key));
|
|
203
|
+
if (extraSections.length > 0) {
|
|
204
|
+
while (out.length > 0 && out[out.length - 1].trim() === "") out.pop();
|
|
205
|
+
for (const section of extraSections) {
|
|
206
|
+
out.push("");
|
|
207
|
+
out.push(...splitTrailingBlanks(section.lines)[0]);
|
|
208
|
+
}
|
|
209
|
+
out.push("");
|
|
210
|
+
}
|
|
211
|
+
return out.join("\n");
|
|
212
|
+
}
|
|
213
|
+
|
|
214
|
+
/**
|
|
215
|
+
* Reconstruct, out of the file on disk, the region a previous harness run
|
|
216
|
+
* wrote — the exact inverse of `mergeManagedWorkflow`. Consumer-only jobs and
|
|
217
|
+
* consumer-only top-level keys are dropped; nothing else is touched.
|
|
218
|
+
*/
|
|
219
|
+
export function harnessRegion(before: string, generated: string): string {
|
|
220
|
+
const b = splitTopLevel(before);
|
|
221
|
+
const g = splitTopLevel(generated);
|
|
222
|
+
const generatedKeys = new Set(g.map(s => s.key));
|
|
223
|
+
const generatedJobNames = new Set(jobNames(generated));
|
|
224
|
+
|
|
225
|
+
const out: string[] = [];
|
|
226
|
+
for (const section of b) {
|
|
227
|
+
if (section.key !== "" && !generatedKeys.has(section.key)) continue;
|
|
228
|
+
if (section.key !== "jobs") {
|
|
229
|
+
out.push(...section.lines);
|
|
230
|
+
continue;
|
|
231
|
+
}
|
|
232
|
+
const parsed = parseJobsSection(section.lines);
|
|
233
|
+
const [, trailing] = splitTrailingBlanks(parsed.jobs.flatMap(j => j.lines));
|
|
234
|
+
const kept = parsed.jobs
|
|
235
|
+
.filter(j => generatedJobNames.has(j.name))
|
|
236
|
+
.flatMap(j => splitTrailingBlanks(j.lines)[0]);
|
|
237
|
+
out.push(...parsed.head, ...kept, ...trailing);
|
|
238
|
+
}
|
|
239
|
+
return out.join("\n");
|
|
240
|
+
}
|
|
241
|
+
|
|
242
|
+
// ── the marker ─────────────────────────────────────────────────────────────
|
|
243
|
+
|
|
244
|
+
function stripMarker(text: string): { body: string; marker: string | null } {
|
|
245
|
+
const lines = text.split("\n");
|
|
246
|
+
const at = lines.findIndex(l => l.startsWith(MANAGED_MARKER_PREFIX));
|
|
247
|
+
if (at < 0) return { body: text, marker: null };
|
|
248
|
+
const marker = lines[at].slice(MANAGED_MARKER_PREFIX.length).trim();
|
|
249
|
+
lines.splice(at, 1);
|
|
250
|
+
return { body: lines.join("\n"), marker };
|
|
251
|
+
}
|
|
252
|
+
|
|
253
|
+
function stampMarker(body: string, authored: string): string {
|
|
254
|
+
const sha = createHash("sha256").update(authored).digest("hex");
|
|
255
|
+
return `${MANAGED_MARKER_PREFIX}${sha}\n${body}`;
|
|
256
|
+
}
|
|
257
|
+
|
|
258
|
+
// ── measuring what a write would lose ──────────────────────────────────────
|
|
259
|
+
|
|
260
|
+
function nonBlank(text: string): string[] {
|
|
261
|
+
return text.split("\n").map(l => l.trim()).filter(l => l !== "");
|
|
262
|
+
}
|
|
263
|
+
|
|
264
|
+
/** Lines of `from` that `minus` does not account for, counting duplicates. */
|
|
265
|
+
function multisetSubtract(from: string[], minus: string[]): string[] {
|
|
266
|
+
const counts = new Map<string, number>();
|
|
267
|
+
for (const l of minus) counts.set(l, (counts.get(l) ?? 0) + 1);
|
|
268
|
+
const out: string[] = [];
|
|
269
|
+
for (const l of from) {
|
|
270
|
+
const n = counts.get(l) ?? 0;
|
|
271
|
+
if (n > 0) counts.set(l, n - 1);
|
|
272
|
+
else out.push(l);
|
|
273
|
+
}
|
|
274
|
+
return out;
|
|
275
|
+
}
|
|
276
|
+
|
|
277
|
+
/** Which jobs in `text` contain any of `lines`. */
|
|
278
|
+
function jobsHolding(text: string, lines: string[]): string[] {
|
|
279
|
+
const wanted = new Set(lines);
|
|
280
|
+
const jobs = jobsSectionOf(splitTopLevel(text));
|
|
281
|
+
if (!jobs) return [];
|
|
282
|
+
return parseJobsSection(jobs.lines)
|
|
283
|
+
.jobs.filter(j => j.lines.some(l => wanted.has(l.trim())))
|
|
284
|
+
.map(j => j.name);
|
|
285
|
+
}
|
|
286
|
+
|
|
287
|
+
// ── the decision ───────────────────────────────────────────────────────────
|
|
288
|
+
|
|
289
|
+
/**
|
|
290
|
+
* Decide what writing `generated` over `before` should do.
|
|
291
|
+
*
|
|
292
|
+
* `before` is the file on disk, or null when there is none. Nothing here
|
|
293
|
+
* touches the filesystem: the caller writes `plan.content` and reports
|
|
294
|
+
* `plan.verb`, which is why the verb is a measurement of the two contents
|
|
295
|
+
* rather than a guess from whether the path existed.
|
|
296
|
+
*/
|
|
297
|
+
export function planManagedWrite(
|
|
298
|
+
before: string | null,
|
|
299
|
+
generated: string,
|
|
300
|
+
opts: { force?: boolean } = {},
|
|
301
|
+
): ManagedWritePlan {
|
|
302
|
+
const clean = stripMarker(generated).body;
|
|
303
|
+
|
|
304
|
+
if (before === null) {
|
|
305
|
+
return {
|
|
306
|
+
verb: "CREATED",
|
|
307
|
+
content: stampMarker(clean, clean),
|
|
308
|
+
lineDelta: 0,
|
|
309
|
+
atRiskJobs: [],
|
|
310
|
+
lostLines: [],
|
|
311
|
+
refusal: null,
|
|
312
|
+
};
|
|
313
|
+
}
|
|
314
|
+
|
|
315
|
+
const { body: beforeBody, marker } = stripMarker(before);
|
|
316
|
+
const force = opts.force === true;
|
|
317
|
+
const merged = force ? clean : mergeManagedWorkflow(beforeBody, clean);
|
|
318
|
+
const content = stampMarker(merged, clean);
|
|
319
|
+
const lineDelta = content.split("\n").length - before.split("\n").length;
|
|
320
|
+
|
|
321
|
+
if (content === before) {
|
|
322
|
+
return { verb: "SKIP", content, lineDelta: 0, atRiskJobs: [], lostLines: [], refusal: null };
|
|
323
|
+
}
|
|
324
|
+
|
|
325
|
+
// Lines the harness can prove it wrote are free to change. Everything else
|
|
326
|
+
// that the write would drop belongs to the consumer.
|
|
327
|
+
//
|
|
328
|
+
// Scoping the whitelist to the REGION rather than to the whole file is not
|
|
329
|
+
// independently observable today, and saying so is cheaper than implying a
|
|
330
|
+
// guard that is not there (.claude/rules/checks-must-be-able-to-fail.md):
|
|
331
|
+
// widening it to `nonBlank(beforeBody)` leaves all 39 tests green, because a
|
|
332
|
+
// verified marker means the merge carried every consumer line, so
|
|
333
|
+
// `before \ merged` holds nothing but harness lines anyway. The narrow form
|
|
334
|
+
// is what stays correct if the merge ever stops carrying something, and the
|
|
335
|
+
// extraction it depends on IS pinned — mutating `harnessRegion` to return
|
|
336
|
+
// its input turns 3 red.
|
|
337
|
+
const region = harnessRegion(beforeBody, clean);
|
|
338
|
+
const provable =
|
|
339
|
+
marker !== null && createHash("sha256").update(region).digest("hex") === marker ? nonBlank(region) : [];
|
|
340
|
+
const lostLines = multisetSubtract(
|
|
341
|
+
multisetSubtract(nonBlank(beforeBody), nonBlank(merged)),
|
|
342
|
+
provable,
|
|
343
|
+
);
|
|
344
|
+
const atRiskJobs = jobsHolding(beforeBody, lostLines);
|
|
345
|
+
|
|
346
|
+
if (lostLines.length > 0 && !force) {
|
|
347
|
+
const where = atRiskJobs.length > 0 ? `job(s) ${atRiskJobs.join(", ")}` : "content outside any job";
|
|
348
|
+
return {
|
|
349
|
+
verb: "REFUSED",
|
|
350
|
+
content,
|
|
351
|
+
lineDelta,
|
|
352
|
+
atRiskJobs,
|
|
353
|
+
lostLines,
|
|
354
|
+
refusal:
|
|
355
|
+
`${lostLines.length} line(s) the harness did not author would be lost from ${where} ` +
|
|
356
|
+
`(${before.split("\n").length} -> ${content.split("\n").length} lines, ${lineDelta >= 0 ? "+" : ""}${lineDelta}). ` +
|
|
357
|
+
`Re-run with --force to overwrite, or move the content into a job the harness does not generate.`,
|
|
358
|
+
};
|
|
359
|
+
}
|
|
360
|
+
|
|
361
|
+
const removing = lostLines.length > 0 || lineDelta < 0;
|
|
362
|
+
return {
|
|
363
|
+
verb: removing ? "REPLACED" : "UPDATED",
|
|
364
|
+
content,
|
|
365
|
+
lineDelta,
|
|
366
|
+
atRiskJobs,
|
|
367
|
+
lostLines,
|
|
368
|
+
refusal: null,
|
|
369
|
+
};
|
|
370
|
+
}
|
|
@@ -0,0 +1,265 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Which files the scaffold owns, and how it writes each one (#208).
|
|
3
|
+
*
|
|
4
|
+
* `.claude/rules/harness-managed.md` says of five file classes:
|
|
5
|
+
*
|
|
6
|
+
* > These files are managed by rungate and **regenerated on re-scaffold**.
|
|
7
|
+
* > Do not edit them directly.
|
|
8
|
+
*
|
|
9
|
+
* That is an ownership claim, and a maintainer who believes it correctly
|
|
10
|
+
* declines to hand-edit a brief or a workflow and waits for a re-scaffold to
|
|
11
|
+
* deliver improvements. So it has to be true.
|
|
12
|
+
*
|
|
13
|
+
* **It was true for four of the five.** Measured on this tree:
|
|
14
|
+
*
|
|
15
|
+
* | claimed file | what re-scaffold actually did |
|
|
16
|
+
* |---|---|
|
|
17
|
+
* | `.github/workflows/ci.yml` | regenerated, job-preserving — correct |
|
|
18
|
+
* | `.github/workflows/gates.yml` | the same — correct |
|
|
19
|
+
* | `.claude/agents/*.md` | rewritten every run — correct |
|
|
20
|
+
* | `CODE-MAP.md` | rewritten, with a freshness skip — correct |
|
|
21
|
+
* | `test/scaffold-conformity.test.ts` | **skipped forever** |
|
|
22
|
+
*
|
|
23
|
+
* The last one went through `safeWrite`, which returns early on
|
|
24
|
+
* `existsSync`. Create-if-absent wearing the word "regenerated". The run
|
|
25
|
+
* reported `SKIP: … (already exists)`, which is indistinguishable from
|
|
26
|
+
* "already current" to anyone reading the log, and the claim converted a
|
|
27
|
+
* fixable staleness into a permanent one.
|
|
28
|
+
*
|
|
29
|
+
* So the issue's framing — *every* `safeWrite` file drifts — is right about
|
|
30
|
+
* the mechanism and overcounts the damage: of the five `safeWrite` call
|
|
31
|
+
* sites only one is a file the harness claims to own. Two are files it does
|
|
32
|
+
* not claim (`.github/copilot-instructions.md`, `specs/WORKFLOW-DEFINITION.md`),
|
|
33
|
+
* and two must NEVER be rewritten (below). Stated plainly because a fix
|
|
34
|
+
* scoped to the claim is a different change from a fix scoped to the helper.
|
|
35
|
+
*
|
|
36
|
+
* ## Why this file exists rather than a tighter `safeWrite`
|
|
37
|
+
*
|
|
38
|
+
* The defect is not that one helper returns early. It is that **ownership
|
|
39
|
+
* was prose**. A table in a doc cannot be iterated, so nothing could notice
|
|
40
|
+
* that one of its rows described behaviour the code did not have. Here the
|
|
41
|
+
* declaration is data, the generator reads it, and a test reconciles it
|
|
42
|
+
* against the doc in both directions.
|
|
43
|
+
*
|
|
44
|
+
* ## `project-state.json` and `PROJECT-STATE.md` are create-only, on purpose
|
|
45
|
+
*
|
|
46
|
+
* They look like scaffold artifacts and are listed here so that nothing
|
|
47
|
+
* "tidies" them into the regenerated set later. They are **DA-owned** (#296):
|
|
48
|
+
* a single shared state document that four parallel worktrees would each
|
|
49
|
+
* overwrite with their own version. On 2026-10-11 run `wf_0b15a933-b2b` lost
|
|
50
|
+
* four worktrees and 2,565 lines of validated work to exactly that. The
|
|
51
|
+
* scaffold seeds them once and never touches them again.
|
|
52
|
+
*/
|
|
53
|
+
|
|
54
|
+
import { createHash } from "crypto";
|
|
55
|
+
|
|
56
|
+
/** How the generator writes one owned file. */
|
|
57
|
+
export type WriteStrategy =
|
|
58
|
+
/** Rewritten every run. Reported CHANGED only when the bytes differ. */
|
|
59
|
+
| "regenerate"
|
|
60
|
+
/** Rewritten every run, but hand-edits are preserved and reported (#370). */
|
|
61
|
+
| "provenance"
|
|
62
|
+
/** The harness owns named jobs inside a file a consumer also writes to. */
|
|
63
|
+
| "job-preserving"
|
|
64
|
+
/** Seeded once and never rewritten. Someone else owns the content. */
|
|
65
|
+
| "create-only";
|
|
66
|
+
|
|
67
|
+
export interface OwnedFile {
|
|
68
|
+
/** Repo-relative path, or a `*` class for a directory of generated files. */
|
|
69
|
+
path: string;
|
|
70
|
+
strategy: WriteStrategy;
|
|
71
|
+
/** What to change INSTEAD of editing the file. */
|
|
72
|
+
customize: string;
|
|
73
|
+
/** The thing not to do. */
|
|
74
|
+
avoid: string;
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
/**
|
|
78
|
+
* The declared set. This list and the table in
|
|
79
|
+
* `.claude/rules/harness-managed.md` are reconciled in both directions by
|
|
80
|
+
* `test/scaffold-ownership.test.ts`, so a row cannot describe behaviour the
|
|
81
|
+
* code does not have — which is the whole of #208.
|
|
82
|
+
*/
|
|
83
|
+
export const OWNED_FILES: OwnedFile[] = [
|
|
84
|
+
{
|
|
85
|
+
path: ".github/workflows/ci.yml",
|
|
86
|
+
strategy: "job-preserving",
|
|
87
|
+
customize: "Set `ci` fields in `.claude/rungate/config.json`; add your own jobs alongside the generated `test` job",
|
|
88
|
+
avoid: "Don't edit the generated `test` job",
|
|
89
|
+
},
|
|
90
|
+
{
|
|
91
|
+
path: ".github/workflows/gates.yml",
|
|
92
|
+
strategy: "job-preserving",
|
|
93
|
+
customize: "Settings from `.claude/rungate/config.json`; add your own jobs alongside the generated `gates` job",
|
|
94
|
+
avoid: "Don't edit the generated `gates` job",
|
|
95
|
+
},
|
|
96
|
+
{
|
|
97
|
+
path: ".claude/agents/*.md",
|
|
98
|
+
strategy: "regenerate",
|
|
99
|
+
customize: "Settings from `.claude/rungate/roles.json`",
|
|
100
|
+
avoid: "Don't edit briefs",
|
|
101
|
+
},
|
|
102
|
+
{
|
|
103
|
+
path: ".claude/rules/*.md",
|
|
104
|
+
strategy: "provenance",
|
|
105
|
+
customize: "Edit freely — a hand-edited rule is preserved and reported (#370)",
|
|
106
|
+
avoid: "Don't expect edits to survive if you also delete the `generated-sha` marker",
|
|
107
|
+
},
|
|
108
|
+
{
|
|
109
|
+
path: "test/scaffold-conformity.test.ts",
|
|
110
|
+
strategy: "regenerate",
|
|
111
|
+
customize: "Runs automatically",
|
|
112
|
+
avoid: "Don't edit",
|
|
113
|
+
},
|
|
114
|
+
{
|
|
115
|
+
path: "CODE-MAP.md",
|
|
116
|
+
strategy: "regenerate",
|
|
117
|
+
customize: "Auto-generated from code scan",
|
|
118
|
+
avoid: "Don't edit",
|
|
119
|
+
},
|
|
120
|
+
{
|
|
121
|
+
path: "project-state.json",
|
|
122
|
+
strategy: "create-only",
|
|
123
|
+
customize: "DA-owned (#296) — seeded once, then yours",
|
|
124
|
+
avoid: "Don't expect re-scaffold to update it; an agent in a worktree must never write it",
|
|
125
|
+
},
|
|
126
|
+
{
|
|
127
|
+
path: "PROJECT-STATE.md",
|
|
128
|
+
strategy: "create-only",
|
|
129
|
+
customize: "DA-owned (#296) — generated from project-state.json by the DA",
|
|
130
|
+
avoid: "Don't edit directly; don't expect re-scaffold to update it",
|
|
131
|
+
},
|
|
132
|
+
];
|
|
133
|
+
|
|
134
|
+
/**
|
|
135
|
+
* The markdown table for `.claude/rules/harness-managed.md`, generated.
|
|
136
|
+
*
|
|
137
|
+
* #208 in one function. The old table was hand-written prose, so nothing
|
|
138
|
+
* could notice that one of its rows described behaviour the code did not
|
|
139
|
+
* have. Generating it means a row cannot exist without an entry here, and
|
|
140
|
+
* `test/scaffold-ownership.test.ts` reconciles the shipped file against
|
|
141
|
+
* this output in both directions so the generated table cannot drift from
|
|
142
|
+
* the one on disk either.
|
|
143
|
+
*
|
|
144
|
+
* The strategy column is new and is the part that would have caught the
|
|
145
|
+
* defect: "managed" was doing too much work as a single word.
|
|
146
|
+
*/
|
|
147
|
+
export function ownedFilesTable(): string {
|
|
148
|
+
const rows = OWNED_FILES.map(
|
|
149
|
+
f => `| \`${f.path}\` | ${f.strategy} | ${f.customize} | ${f.avoid} |`,
|
|
150
|
+
);
|
|
151
|
+
return [
|
|
152
|
+
"| File | Strategy | How to customize | What NOT to do |",
|
|
153
|
+
"|------|----------|-----------------|----------------|",
|
|
154
|
+
...rows,
|
|
155
|
+
].join("\n");
|
|
156
|
+
}
|
|
157
|
+
|
|
158
|
+
/** The action prefix for an owned file the generator declined to overwrite. */
|
|
159
|
+
export const SCAFFOLD_REFUSE = "PRESERVED";
|
|
160
|
+
|
|
161
|
+
/**
|
|
162
|
+
* Whether what is on disk already is byte-for-byte what we would write.
|
|
163
|
+
*
|
|
164
|
+
* The point of #208's SC-671: `0 changed` has to be a MEASUREMENT. The old
|
|
165
|
+
* report said `SKIP (already exists)`, which is produced by not looking.
|
|
166
|
+
* This is produced by looking and finding no difference, and the two are
|
|
167
|
+
* only indistinguishable to someone reading the summary line.
|
|
168
|
+
*/
|
|
169
|
+
export function bytesIdentical(existing: string | null, generated: string): boolean {
|
|
170
|
+
return existing !== null && existing === generated;
|
|
171
|
+
}
|
|
172
|
+
|
|
173
|
+
/**
|
|
174
|
+
* The provenance marker for a file whose comment syntax is `//`.
|
|
175
|
+
*
|
|
176
|
+
* The frontmatter form in `lib/rule-provenance.ts` is the same idea and
|
|
177
|
+
* cannot be reused verbatim: a TypeScript file has no `---` block. Both
|
|
178
|
+
* stamp a digest of the body the generator wrote, so the next run can ask
|
|
179
|
+
* "has anyone touched this since?" with nothing that can desync from the
|
|
180
|
+
* tree it describes.
|
|
181
|
+
*/
|
|
182
|
+
const MARKER = /^\/\/ generated-sha: ([0-9a-f]{16})\n/;
|
|
183
|
+
|
|
184
|
+
export function commentBody(text: string): string {
|
|
185
|
+
return text.replace(MARKER, "");
|
|
186
|
+
}
|
|
187
|
+
|
|
188
|
+
export function commentSha(text: string): string {
|
|
189
|
+
return createHash("sha256").update(commentBody(text)).digest("hex").slice(0, 16);
|
|
190
|
+
}
|
|
191
|
+
|
|
192
|
+
export function declaredCommentSha(text: string): string | null {
|
|
193
|
+
const m = MARKER.exec(text);
|
|
194
|
+
return m ? m[1] : null;
|
|
195
|
+
}
|
|
196
|
+
|
|
197
|
+
export function stampComment(generated: string): string {
|
|
198
|
+
const body = commentBody(generated);
|
|
199
|
+
return `// generated-sha: ${commentSha(body)}\n${body}`;
|
|
200
|
+
}
|
|
201
|
+
|
|
202
|
+
export interface WriteDecision {
|
|
203
|
+
action: "create" | "unchanged" | "changed" | "preserve";
|
|
204
|
+
reason: string;
|
|
205
|
+
/** The bytes to write. Absent for `unchanged` and `preserve`. */
|
|
206
|
+
content?: string;
|
|
207
|
+
}
|
|
208
|
+
|
|
209
|
+
/**
|
|
210
|
+
* The single place that decides what happens to one owned file.
|
|
211
|
+
*
|
|
212
|
+
* One exported function, so there is one binding to mutate. The four
|
|
213
|
+
* strategies answer the same question differently and all of them have to
|
|
214
|
+
* route through here, or the declaration above becomes documentation again.
|
|
215
|
+
*
|
|
216
|
+
* **AC-5 asked for the hand-edit policy to be chosen and justified, not
|
|
217
|
+
* resolved implicitly. It is: preserve and report.** #370 already answered
|
|
218
|
+
* this exact question for `.claude/rules/*.md` and chose the same, for the
|
|
219
|
+
* same reason — silently overwriting a human's work is the opposite failure
|
|
220
|
+
* from silently skipping, and it is the worse one, because the skipped file
|
|
221
|
+
* is still on disk and the overwritten one is gone. A second answer here
|
|
222
|
+
* would mean the harness destroyed work in one directory and refused to in
|
|
223
|
+
* another, with nothing stating which was which.
|
|
224
|
+
*
|
|
225
|
+
* `create-only` is not a weaker `regenerate`; it is a different owner. It
|
|
226
|
+
* never reports a hand-edit, because there is no edit to report — the
|
|
227
|
+
* content was never the harness's.
|
|
228
|
+
*/
|
|
229
|
+
export function decideOwnedWrite(
|
|
230
|
+
strategy: WriteStrategy,
|
|
231
|
+
existing: string | null,
|
|
232
|
+
generated: string,
|
|
233
|
+
): WriteDecision {
|
|
234
|
+
if (existing === null) {
|
|
235
|
+
return {
|
|
236
|
+
action: "create",
|
|
237
|
+
reason: "no such file",
|
|
238
|
+
content: strategy === "provenance" ? stampComment(generated) : generated,
|
|
239
|
+
};
|
|
240
|
+
}
|
|
241
|
+
|
|
242
|
+
if (strategy === "create-only") {
|
|
243
|
+
return { action: "unchanged", reason: "seeded once; its content is not the harness's" };
|
|
244
|
+
}
|
|
245
|
+
|
|
246
|
+
if (strategy === "provenance") {
|
|
247
|
+
const stamped = stampComment(generated);
|
|
248
|
+
if (bytesIdentical(existing, stamped)) {
|
|
249
|
+
return { action: "unchanged", reason: "identical to generator output" };
|
|
250
|
+
}
|
|
251
|
+
const declared = declaredCommentSha(existing);
|
|
252
|
+
if (declared === null) {
|
|
253
|
+
return { action: "preserve", reason: "hand-authored — no harness provenance marker" };
|
|
254
|
+
}
|
|
255
|
+
if (declared !== commentSha(existing)) {
|
|
256
|
+
return { action: "preserve", reason: "hand-edited since the harness wrote it" };
|
|
257
|
+
}
|
|
258
|
+
return { action: "changed", reason: "harness-written and untouched since", content: stamped };
|
|
259
|
+
}
|
|
260
|
+
|
|
261
|
+
if (bytesIdentical(existing, generated)) {
|
|
262
|
+
return { action: "unchanged", reason: "regenerated output is byte-identical" };
|
|
263
|
+
}
|
|
264
|
+
return { action: "changed", reason: "regenerated output differs", content: generated };
|
|
265
|
+
}
|