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
|
@@ -0,0 +1,366 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Gate enforcement logic — extracted from GateEnforcement.hook.ts
|
|
3
|
+
*
|
|
4
|
+
* Deep module: exports enforcement decision logic, workflow gate failure
|
|
5
|
+
* scanning, and signal logging. The hook file is a thin trigger that
|
|
6
|
+
* delegates all logic here.
|
|
7
|
+
*
|
|
8
|
+
* Issue: #544
|
|
9
|
+
*/
|
|
10
|
+
|
|
11
|
+
import {
|
|
12
|
+
appendFileSync,
|
|
13
|
+
existsSync,
|
|
14
|
+
mkdirSync,
|
|
15
|
+
readFileSync,
|
|
16
|
+
readdirSync,
|
|
17
|
+
unlinkSync,
|
|
18
|
+
writeFileSync,
|
|
19
|
+
} from 'fs';
|
|
20
|
+
import { checkDocHygiene } from './doc-hygiene';
|
|
21
|
+
|
|
22
|
+
export interface GateFailure {
|
|
23
|
+
check: string;
|
|
24
|
+
detail: string;
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
export interface WorkflowGateFailure {
|
|
28
|
+
gate: string;
|
|
29
|
+
issue: number;
|
|
30
|
+
slug: string;
|
|
31
|
+
failures: GateFailure[];
|
|
32
|
+
hasOutcomeAcFailure: boolean;
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
export interface GatePending {
|
|
36
|
+
session_id: string;
|
|
37
|
+
gate: string;
|
|
38
|
+
issue: number;
|
|
39
|
+
slug: string;
|
|
40
|
+
failures: GateFailure[];
|
|
41
|
+
strike_count: number;
|
|
42
|
+
max_strikes: number;
|
|
43
|
+
outcome_ac_failure: boolean;
|
|
44
|
+
created_at: string;
|
|
45
|
+
expires_ts: number;
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
export type EnforcementAction = 'block' | 'nag' | 'pass';
|
|
49
|
+
|
|
50
|
+
export interface EnforcementDecision {
|
|
51
|
+
action: EnforcementAction;
|
|
52
|
+
decision?: string;
|
|
53
|
+
reason?: string;
|
|
54
|
+
reminder?: string;
|
|
55
|
+
newStrikeCount: number;
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
/**
|
|
59
|
+
* Format gate failures into human-readable text.
|
|
60
|
+
*/
|
|
61
|
+
export function formatFailures(failures: GateFailure[]): string {
|
|
62
|
+
return failures.map(f => ` - ${f.check}: ${f.detail}`).join('\n');
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
/**
|
|
66
|
+
* Scan workflow-state.json files under workDir for active gate failures.
|
|
67
|
+
* Returns the first failure found (scope > verify > ship priority).
|
|
68
|
+
* Checks both direct children and nested subdirectories.
|
|
69
|
+
*/
|
|
70
|
+
export function findWorkflowGateFailure(workDir: string): WorkflowGateFailure | null {
|
|
71
|
+
if (!existsSync(workDir)) return null;
|
|
72
|
+
|
|
73
|
+
try {
|
|
74
|
+
const dirs = readdirSync(workDir, { withFileTypes: true })
|
|
75
|
+
.filter(d => d.isDirectory());
|
|
76
|
+
|
|
77
|
+
for (const d of dirs) {
|
|
78
|
+
// Level 1: direct children
|
|
79
|
+
const result = checkWorkflowFile(`${workDir}/${d.name}/workflow-state.json`, d.name);
|
|
80
|
+
if (result) return result;
|
|
81
|
+
|
|
82
|
+
// Level 2: nested subdirectories
|
|
83
|
+
try {
|
|
84
|
+
const subDirs = readdirSync(`${workDir}/${d.name}`, { withFileTypes: true })
|
|
85
|
+
.filter(sd => sd.isDirectory());
|
|
86
|
+
for (const sd of subDirs) {
|
|
87
|
+
const nestedResult = checkWorkflowFile(
|
|
88
|
+
`${workDir}/${d.name}/${sd.name}/workflow-state.json`,
|
|
89
|
+
`${d.name}/${sd.name}`,
|
|
90
|
+
);
|
|
91
|
+
if (nestedResult) return nestedResult;
|
|
92
|
+
}
|
|
93
|
+
} catch { /* skip */ }
|
|
94
|
+
}
|
|
95
|
+
} catch { /* skip */ }
|
|
96
|
+
|
|
97
|
+
return null;
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
/**
|
|
101
|
+
* Check a single workflow-state.json file for gate failures.
|
|
102
|
+
*/
|
|
103
|
+
function checkWorkflowFile(wfPath: string, slug: string): WorkflowGateFailure | null {
|
|
104
|
+
if (!existsSync(wfPath)) return null;
|
|
105
|
+
|
|
106
|
+
try {
|
|
107
|
+
const wf = JSON.parse(readFileSync(wfPath, 'utf-8'));
|
|
108
|
+
if (wf.phase === 'DONE') return null;
|
|
109
|
+
|
|
110
|
+
const gates = wf.gates || {};
|
|
111
|
+
for (const gateName of ['scope', 'verify', 'ship']) {
|
|
112
|
+
const gate = gates[gateName];
|
|
113
|
+
if (gate?.result === 'FAIL' && Array.isArray(gate.failures) && gate.failures.length > 0) {
|
|
114
|
+
const acs = Array.isArray(wf.acs) ? wf.acs : [];
|
|
115
|
+
const hasOutcomeAcFailure = acs.some(
|
|
116
|
+
(ac: { type?: string; verdict?: string }) => ac.type === 'OUTCOME' && ac.verdict === 'FAIL',
|
|
117
|
+
);
|
|
118
|
+
return {
|
|
119
|
+
gate: gateName,
|
|
120
|
+
issue: wf.issue,
|
|
121
|
+
slug: wf.slug || slug,
|
|
122
|
+
failures: gate.failures.map(
|
|
123
|
+
(f: { check?: string; id?: string; detail?: string; message?: string }) => ({
|
|
124
|
+
check: f.check || f.id || 'unknown',
|
|
125
|
+
detail: f.detail || f.message || JSON.stringify(f),
|
|
126
|
+
}),
|
|
127
|
+
),
|
|
128
|
+
hasOutcomeAcFailure,
|
|
129
|
+
};
|
|
130
|
+
}
|
|
131
|
+
}
|
|
132
|
+
} catch { /* skip malformed */ }
|
|
133
|
+
|
|
134
|
+
return null;
|
|
135
|
+
}
|
|
136
|
+
|
|
137
|
+
/**
|
|
138
|
+
* Determine the enforcement action (block/nag/pass) for a given gate state and tool call.
|
|
139
|
+
*/
|
|
140
|
+
export function makeEnforcementDecision(pending: GatePending, toolName: string): EnforcementDecision {
|
|
141
|
+
const isSkillCall = toolName === 'Skill';
|
|
142
|
+
const failureText = formatFailures(pending.failures);
|
|
143
|
+
|
|
144
|
+
// OUTCOME AC failure -> immediate block on Skill calls
|
|
145
|
+
if (pending.outcome_ac_failure && isSkillCall) {
|
|
146
|
+
return {
|
|
147
|
+
action: 'block',
|
|
148
|
+
decision: 'block',
|
|
149
|
+
reason: `OUTCOME AC failed — must fix before proceeding. Gate: ${pending.gate}, issue #${pending.issue}.\n${failureText}`,
|
|
150
|
+
newStrikeCount: pending.strike_count,
|
|
151
|
+
};
|
|
152
|
+
}
|
|
153
|
+
|
|
154
|
+
// Strike-based block on Skill calls
|
|
155
|
+
if (isSkillCall && pending.strike_count >= pending.max_strikes) {
|
|
156
|
+
return {
|
|
157
|
+
action: 'block',
|
|
158
|
+
decision: 'block',
|
|
159
|
+
reason: `Gate blocked after ${pending.strike_count} strikes: ${pending.gate} (issue #${pending.issue}).\n${failureText}\nFix the failures or post skip-reason to the issue.`,
|
|
160
|
+
newStrikeCount: pending.strike_count,
|
|
161
|
+
};
|
|
162
|
+
}
|
|
163
|
+
|
|
164
|
+
// Nag — only count strikes for Skill calls
|
|
165
|
+
const newStrikeCount = isSkillCall ? pending.strike_count + 1 : pending.strike_count;
|
|
166
|
+
|
|
167
|
+
const reminder = [
|
|
168
|
+
'<system-reminder>',
|
|
169
|
+
`⚠️ GATE FAIL (${pending.gate}): issue #${pending.issue}`,
|
|
170
|
+
failureText,
|
|
171
|
+
`Strike ${newStrikeCount}/${pending.max_strikes}. Fix before proceeding or post skip-reason to issue.`,
|
|
172
|
+
'</system-reminder>',
|
|
173
|
+
].join('\n');
|
|
174
|
+
|
|
175
|
+
return {
|
|
176
|
+
action: 'nag',
|
|
177
|
+
reminder,
|
|
178
|
+
newStrikeCount,
|
|
179
|
+
};
|
|
180
|
+
}
|
|
181
|
+
|
|
182
|
+
/**
|
|
183
|
+
* Load cached strike count from gate-pending.json if it matches the current failure.
|
|
184
|
+
*/
|
|
185
|
+
export function loadStrikeCount(pendingFile: string, issue: number, gate: string): number {
|
|
186
|
+
if (!existsSync(pendingFile)) return 0;
|
|
187
|
+
try {
|
|
188
|
+
const cached = JSON.parse(readFileSync(pendingFile, 'utf-8'));
|
|
189
|
+
if (cached.issue === issue && cached.gate === gate) {
|
|
190
|
+
return cached.strike_count || 0;
|
|
191
|
+
}
|
|
192
|
+
} catch {}
|
|
193
|
+
return 0;
|
|
194
|
+
}
|
|
195
|
+
|
|
196
|
+
/**
|
|
197
|
+
* Build a GatePending object from a workflow gate failure and session context.
|
|
198
|
+
*/
|
|
199
|
+
export function buildGatePending(
|
|
200
|
+
wfFailure: WorkflowGateFailure,
|
|
201
|
+
sessionId: string,
|
|
202
|
+
strikeCount: number,
|
|
203
|
+
): GatePending {
|
|
204
|
+
return {
|
|
205
|
+
session_id: sessionId,
|
|
206
|
+
gate: wfFailure.gate,
|
|
207
|
+
issue: wfFailure.issue,
|
|
208
|
+
slug: wfFailure.slug,
|
|
209
|
+
failures: wfFailure.failures,
|
|
210
|
+
strike_count: strikeCount,
|
|
211
|
+
max_strikes: 3,
|
|
212
|
+
outcome_ac_failure: wfFailure.hasOutcomeAcFailure,
|
|
213
|
+
created_at: new Date().toISOString(),
|
|
214
|
+
expires_ts: Date.now() + (4 * 60 * 60 * 1000),
|
|
215
|
+
};
|
|
216
|
+
}
|
|
217
|
+
|
|
218
|
+
/**
|
|
219
|
+
* Log an enforcement signal event to the signals file.
|
|
220
|
+
*
|
|
221
|
+
* SC-504: appendFileSync creates the file if absent — the previous
|
|
222
|
+
* existence guard silently dropped signals on first write.
|
|
223
|
+
*/
|
|
224
|
+
export function logSignal(signalsDir: string, signalsFile: string, event: Record<string, unknown>): void {
|
|
225
|
+
try {
|
|
226
|
+
if (!existsSync(signalsDir)) mkdirSync(signalsDir, { recursive: true });
|
|
227
|
+
appendFileSync(signalsFile, JSON.stringify(event) + '\n', 'utf-8');
|
|
228
|
+
} catch (err) {
|
|
229
|
+
console.error(`[GateEnforcement] Signal log write failed: ${err}`);
|
|
230
|
+
}
|
|
231
|
+
}
|
|
232
|
+
|
|
233
|
+
/**
|
|
234
|
+
* Everything the hook needs from its environment. Passed in rather than
|
|
235
|
+
* read from module scope so the whole decision path is callable from a test.
|
|
236
|
+
*/
|
|
237
|
+
export interface GateEnforcementInput {
|
|
238
|
+
/** Directory holding the per-issue workflow-state.json files. */
|
|
239
|
+
workDir: string;
|
|
240
|
+
/** Directory for the signals log; created on demand. */
|
|
241
|
+
signalsDir: string;
|
|
242
|
+
/** Signals JSONL path. */
|
|
243
|
+
signalsFile: string;
|
|
244
|
+
/** gate-pending.json path — the strike counter's home. */
|
|
245
|
+
pendingFile: string;
|
|
246
|
+
/** Project root, scanned for doc-hygiene findings (SC-508). */
|
|
247
|
+
projectRoot: string;
|
|
248
|
+
sessionId: string;
|
|
249
|
+
toolName: string;
|
|
250
|
+
}
|
|
251
|
+
|
|
252
|
+
export interface GateEnforcementResult {
|
|
253
|
+
/** What the hook should print on stdout, or null to stay silent. */
|
|
254
|
+
stdout: string | null;
|
|
255
|
+
action: EnforcementAction;
|
|
256
|
+
}
|
|
257
|
+
|
|
258
|
+
/**
|
|
259
|
+
* The whole GateEnforcement decision, extracted from the hook (SC-369).
|
|
260
|
+
*
|
|
261
|
+
* The hook is now a trigger: parse stdin, call this, print, exit 0. Keeping
|
|
262
|
+
* the logic here is what makes it reachable by test/gate-enforcement.test.ts
|
|
263
|
+
* without simulating a PreToolUse payload.
|
|
264
|
+
*/
|
|
265
|
+
/**
|
|
266
|
+
* One emitter for both enforcement outcomes, so a block and a nag cannot drift
|
|
267
|
+
* into different event shapes. `reason` is attributed only for a block: a nag
|
|
268
|
+
* has no reason, and emitting one anyway would make every nag look like a
|
|
269
|
+
* near-block in the signal history.
|
|
270
|
+
*/
|
|
271
|
+
export function logEnforcementSignal(
|
|
272
|
+
signalsDir: string,
|
|
273
|
+
signalsFile: string,
|
|
274
|
+
pending: GatePending,
|
|
275
|
+
tool: string,
|
|
276
|
+
action: 'block' | 'nag',
|
|
277
|
+
strike: number,
|
|
278
|
+
): void {
|
|
279
|
+
logSignal(signalsDir, signalsFile, {
|
|
280
|
+
ts: new Date().toISOString(),
|
|
281
|
+
type: 'gate_enforcement',
|
|
282
|
+
gate: pending.gate,
|
|
283
|
+
issue: pending.issue,
|
|
284
|
+
strike,
|
|
285
|
+
tool,
|
|
286
|
+
action,
|
|
287
|
+
...(action === 'block'
|
|
288
|
+
? { reason: pending.outcome_ac_failure ? 'outcome_ac_failure' : 'max_strikes' }
|
|
289
|
+
: {}),
|
|
290
|
+
});
|
|
291
|
+
}
|
|
292
|
+
|
|
293
|
+
export function runGateEnforcement(input: GateEnforcementInput): GateEnforcementResult {
|
|
294
|
+
const wfFailure = findWorkflowGateFailure(input.workDir);
|
|
295
|
+
if (!wfFailure) {
|
|
296
|
+
if (existsSync(input.pendingFile)) {
|
|
297
|
+
try {
|
|
298
|
+
unlinkSync(input.pendingFile);
|
|
299
|
+
} catch (err) {
|
|
300
|
+
console.error(`[GateEnforcement] Could not clear ${input.pendingFile}: ${err}`);
|
|
301
|
+
}
|
|
302
|
+
}
|
|
303
|
+
return { stdout: null, action: 'pass' };
|
|
304
|
+
}
|
|
305
|
+
|
|
306
|
+
const strikeCount = loadStrikeCount(input.pendingFile, wfFailure.issue, wfFailure.gate);
|
|
307
|
+
const pending = buildGatePending(wfFailure, input.sessionId, strikeCount);
|
|
308
|
+
const decision = makeEnforcementDecision(pending, input.toolName);
|
|
309
|
+
|
|
310
|
+
if (decision.action === 'block') {
|
|
311
|
+
logEnforcementSignal(
|
|
312
|
+
input.signalsDir, input.signalsFile, pending, input.toolName, 'block', pending.strike_count,
|
|
313
|
+
);
|
|
314
|
+
return {
|
|
315
|
+
stdout: JSON.stringify({ decision: 'block', reason: decision.reason }),
|
|
316
|
+
action: 'block',
|
|
317
|
+
};
|
|
318
|
+
}
|
|
319
|
+
|
|
320
|
+
if (input.toolName === 'Skill') {
|
|
321
|
+
try {
|
|
322
|
+
writeFileSync(
|
|
323
|
+
input.pendingFile,
|
|
324
|
+
JSON.stringify({ ...pending, strike_count: decision.newStrikeCount }, null, 2),
|
|
325
|
+
'utf-8',
|
|
326
|
+
);
|
|
327
|
+
} catch (err) {
|
|
328
|
+
console.error(`[GateEnforcement] Strike count write failed: ${err}`);
|
|
329
|
+
}
|
|
330
|
+
}
|
|
331
|
+
|
|
332
|
+
logEnforcementSignal(
|
|
333
|
+
input.signalsDir, input.signalsFile, pending, input.toolName, 'nag', decision.newStrikeCount,
|
|
334
|
+
);
|
|
335
|
+
logDocHygieneSignals(input.signalsDir, input.signalsFile, input.projectRoot);
|
|
336
|
+
|
|
337
|
+
return { stdout: decision.reminder ?? null, action: 'nag' };
|
|
338
|
+
}
|
|
339
|
+
|
|
340
|
+
/**
|
|
341
|
+
* SC-508: doc-hygiene findings ride along as signals for promotion tracking.
|
|
342
|
+
* Best-effort by design — a hygiene scan failure must not block a tool call —
|
|
343
|
+
* but it says so on stderr rather than vanishing.
|
|
344
|
+
*/
|
|
345
|
+
export function logDocHygieneSignals(
|
|
346
|
+
signalsDir: string,
|
|
347
|
+
signalsFile: string,
|
|
348
|
+
projectRoot: string,
|
|
349
|
+
check: typeof checkDocHygiene = checkDocHygiene,
|
|
350
|
+
): number {
|
|
351
|
+
try {
|
|
352
|
+
const result = check(projectRoot);
|
|
353
|
+
if (result.pass) return 0;
|
|
354
|
+
for (const finding of result.findings) {
|
|
355
|
+
logSignal(signalsDir, signalsFile, {
|
|
356
|
+
ts: new Date().toISOString(), type: 'doc-hygiene',
|
|
357
|
+
checkId: finding.checkId, file: finding.file,
|
|
358
|
+
level: finding.level, message: finding.message,
|
|
359
|
+
});
|
|
360
|
+
}
|
|
361
|
+
return result.findings.length;
|
|
362
|
+
} catch (err) {
|
|
363
|
+
console.error(`[GateEnforcement] doc-hygiene signal sweep skipped: ${err}`);
|
|
364
|
+
return 0;
|
|
365
|
+
}
|
|
366
|
+
}
|
|
@@ -0,0 +1,136 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Agent briefs generator — reads template files from templates/agent-briefs/
|
|
3
|
+
* and fills variables from ProjectScan data.
|
|
4
|
+
*
|
|
5
|
+
* Extracted from scaffold-project.ts per SCAFFOLD-DECOMPOSITION-SPEC (D-2)
|
|
6
|
+
* and AGENT-BRIEF-TEMPLATE-SPEC (SC-348).
|
|
7
|
+
*/
|
|
8
|
+
import { existsSync, readFileSync, readdirSync } from "fs";
|
|
9
|
+
import { join, dirname } from "path";
|
|
10
|
+
import type { ProjectScan, AgentMeta } from "./types";
|
|
11
|
+
import { buildAgentMeta, DEFAULT_AGENT_META } from "../create-brief";
|
|
12
|
+
|
|
13
|
+
/**
|
|
14
|
+
* Resolve the templates directory. Checks:
|
|
15
|
+
* 1. Explicit harnessTemplatesDir from scan
|
|
16
|
+
* 2. Relative to this file's location (lib/generators/ -> ../../templates/agent-briefs/)
|
|
17
|
+
*/
|
|
18
|
+
function resolveTemplatesDir(scan: ProjectScan): string {
|
|
19
|
+
if (scan.harnessTemplatesDir && existsSync(scan.harnessTemplatesDir)) {
|
|
20
|
+
return scan.harnessTemplatesDir;
|
|
21
|
+
}
|
|
22
|
+
// Default: relative to this module (lib/generators/../../templates/agent-briefs/)
|
|
23
|
+
const fallback = join(dirname(dirname(__dirname)), "templates", "agent-briefs");
|
|
24
|
+
return fallback;
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
/**
|
|
28
|
+
* Generate all agent briefs from templates/agent-briefs/ templates.
|
|
29
|
+
*
|
|
30
|
+
* Returns a record mapping agent name to generated brief content.
|
|
31
|
+
* Does NOT write files — caller decides where to write.
|
|
32
|
+
*/
|
|
33
|
+
export function generateAgentBriefs(scan: ProjectScan): Record<string, string> {
|
|
34
|
+
const templatesDir = resolveTemplatesDir(scan);
|
|
35
|
+
const result: Record<string, string> = {};
|
|
36
|
+
|
|
37
|
+
if (!existsSync(templatesDir)) {
|
|
38
|
+
return result;
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
// Load shared rules partial
|
|
42
|
+
const sharedRulesPath = join(templatesDir, "_shared.md");
|
|
43
|
+
let sharedRules = existsSync(sharedRulesPath)
|
|
44
|
+
? readFileSync(sharedRulesPath, "utf-8").trim()
|
|
45
|
+
: "";
|
|
46
|
+
// Strip frontmatter from partials
|
|
47
|
+
sharedRules = sharedRules.replace(/^---[\s\S]*?---\n*/, "");
|
|
48
|
+
|
|
49
|
+
// Build project identity section
|
|
50
|
+
const identitySection = scan.identity
|
|
51
|
+
? `## Project\n\n${scan.identity}\n`
|
|
52
|
+
: "";
|
|
53
|
+
|
|
54
|
+
// Build source dirs list
|
|
55
|
+
const dirList = scan.sourceDirs.length > 0
|
|
56
|
+
? scan.sourceDirs.map(d => `- \`${d}/\``).join("\n")
|
|
57
|
+
: "";
|
|
58
|
+
|
|
59
|
+
// Build consumer note
|
|
60
|
+
const consumerNote = scan.consumers.length > 0
|
|
61
|
+
? `\n## Consumers (${scan.consumers.length})\n\n${scan.consumers.map(c => `- ${c}`).join("\n")}\n\nCheck cascade impact when modifying shared modules.\n`
|
|
62
|
+
: "";
|
|
63
|
+
|
|
64
|
+
// Harness config shortcuts
|
|
65
|
+
const harness = scan.harnessConfig;
|
|
66
|
+
const devUi = harness?.dev?.uiBase || null;
|
|
67
|
+
const devApi = harness?.dev?.apiBase || null;
|
|
68
|
+
const testCmd = harness?.dev?.testCmd || scan.testCmd || "bun test";
|
|
69
|
+
const typeCheck = harness?.dev?.typeCheck || "bunx tsc --noEmit";
|
|
70
|
+
const pages = harness?.pages || {};
|
|
71
|
+
const pagesTable = Object.keys(pages).length > 0
|
|
72
|
+
? "### Pages Map\n\n| Path | Page |\n|------|------|\n" +
|
|
73
|
+
Object.entries(pages).map(([k, v]) => `| ${v} | ${k} |`).join("\n")
|
|
74
|
+
: "";
|
|
75
|
+
|
|
76
|
+
// Agent metadata: config > scan > defaults (AC-4: no hardcoded meta in this file)
|
|
77
|
+
const harnessAgentMeta = buildAgentMeta(harness);
|
|
78
|
+
const agentMeta: Record<string, AgentMeta> = { ...DEFAULT_AGENT_META, ...harnessAgentMeta, ...(scan.agentMeta || {}) };
|
|
79
|
+
|
|
80
|
+
// Discover template files (excludes _shared.md partial)
|
|
81
|
+
const templateFiles = readdirSync(templatesDir)
|
|
82
|
+
.filter(f => f.endsWith(".md") && !f.startsWith("_"));
|
|
83
|
+
|
|
84
|
+
for (const templateFile of templateFiles) {
|
|
85
|
+
const agentName = templateFile.replace(".md", "");
|
|
86
|
+
const templatePath = join(templatesDir, templateFile);
|
|
87
|
+
|
|
88
|
+
let content = readFileSync(templatePath, "utf-8");
|
|
89
|
+
// Strip any hook-injected frontmatter from template
|
|
90
|
+
content = content.replace(/^---[\s\S]*?---\n*/, "");
|
|
91
|
+
|
|
92
|
+
// Apply variable substitution
|
|
93
|
+
content = content.replace(/\$\{PROJECT_IDENTITY\}/g, identitySection);
|
|
94
|
+
content = content.replace(/\$\{SHARED_RULES\}/g, sharedRules);
|
|
95
|
+
content = content.replace(/\$\{SOURCE_DIRS\}/g, dirList);
|
|
96
|
+
content = content.replace(/\$\{CONSUMERS\}/g, consumerNote);
|
|
97
|
+
content = content.replace(/\$\{PROMPT_PREFIX\}/g, scan.promptPrefix);
|
|
98
|
+
content = content.replace(/\$\{DEV_UI_LINE\}/g, devUi ? `- **Dev UI:** ${devUi}` : "- **Dev UI:** not configured — check .claude/rungate/config.json");
|
|
99
|
+
content = content.replace(/\$\{DEV_API_LINE\}/g, devApi ? `- **Dev API:** ${devApi}` : "- **Dev API:** not configured — check .claude/rungate/config.json");
|
|
100
|
+
content = content.replace(/\$\{PAGES_TABLE\}/g, pagesTable);
|
|
101
|
+
content = content.replace(/\$\{TEST_CMD\}/g, testCmd);
|
|
102
|
+
content = content.replace(/\$\{TYPE_CHECK\}/g, typeCheck);
|
|
103
|
+
|
|
104
|
+
// Prepend frontmatter with agent metadata
|
|
105
|
+
const meta = agentMeta[agentName];
|
|
106
|
+
if (meta) {
|
|
107
|
+
let fm = `---\nname: ${agentName}\ndescription: ${meta.description}\ntools: ${meta.tools}\nmodel: ${meta.model}`;
|
|
108
|
+
if (meta.memory) fm += `\nmemory: ${meta.memory}`;
|
|
109
|
+
if (meta.maxTurns) fm += `\nmaxTurns: ${meta.maxTurns}`;
|
|
110
|
+
if (meta.effort) fm += `\neffort: ${meta.effort}`;
|
|
111
|
+
if (meta.isolation) fm += `\nisolation: ${meta.isolation}`;
|
|
112
|
+
if (meta.omitClaudeMd) fm += `\nomitClaudeMd: true`;
|
|
113
|
+
if (meta.disallowedTools?.length) fm += `\ndisallowedTools: [${meta.disallowedTools.join(", ")}]`;
|
|
114
|
+
if (meta.hooks) fm += `\nhooks:\n${JSON.stringify(meta.hooks, null, 2).split("\n").map((l, i) => i === 0 ? "" : ` ${l}`).filter(Boolean).join("\n")}`;
|
|
115
|
+
if (meta.tiers) {
|
|
116
|
+
fm += `\ntiers:`;
|
|
117
|
+
for (const [tier, sections] of Object.entries(meta.tiers)) {
|
|
118
|
+
fm += `\n ${tier}: [${sections.map(s => `'${s}'`).join(", ")}]`;
|
|
119
|
+
}
|
|
120
|
+
}
|
|
121
|
+
fm += `\n---\n\n`;
|
|
122
|
+
content = fm + content;
|
|
123
|
+
}
|
|
124
|
+
|
|
125
|
+
// Append prompt routing section if available
|
|
126
|
+
const prompts = scan.promptRouting[agentName] || [];
|
|
127
|
+
if (prompts.length > 0) {
|
|
128
|
+
content += `\n## Reference (read when needed)\n\n| Prompt | When to Read |\n|--------|-------------|\n`;
|
|
129
|
+
content += prompts.map(p => `| ${p.file} | ${p.when} |`).join("\n") + "\n";
|
|
130
|
+
}
|
|
131
|
+
|
|
132
|
+
result[agentName] = content;
|
|
133
|
+
}
|
|
134
|
+
|
|
135
|
+
return result;
|
|
136
|
+
}
|