gcf-aif-ext 0.32.0 → 0.34.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/README.md +19 -1
- package/commands/gcf.js +76 -37
- package/extension.json +1 -1
- package/injections/plan-context.md +3 -0
- package/lib/audit-core.js +72 -127
- package/lib/board.js +12 -8
- package/lib/commit-files.js +1 -0
- package/lib/commit-move.js +1 -0
- package/lib/context.js +29 -16
- package/lib/d2-states.js +208 -0
- package/lib/design-parts.js +37 -7
- package/lib/git.js +26 -5
- package/lib/main-lock.js +195 -3
- package/lib/play.js +21 -20
- package/lib/session-mark.js +2 -1
- package/lib/systems-doc.js +60 -13
- package/lib/work-ops.js +3 -2
- package/package.json +1 -1
- package/skills/gcf-audit/SKILL.md +10 -5
- package/skills/gcf-card/SKILL.md +12 -10
- package/skills/gcf-verdict/SKILL.md +7 -5
- package/templates/agents-block.md +9 -0
package/lib/context.js
CHANGED
|
@@ -2,7 +2,9 @@ import { mkdir, readFile, readdir } from 'node:fs/promises';
|
|
|
2
2
|
import { existsSync } from 'node:fs';
|
|
3
3
|
import path from 'node:path';
|
|
4
4
|
import { listItems, listSystems, readConfig, tokensEst } from './gcf-paths.js';
|
|
5
|
-
import {
|
|
5
|
+
import { buildLedger } from './ledger.js';
|
|
6
|
+
import { provenanceOf } from './design.js';
|
|
7
|
+
import { d2States, verdictMatchers } from './d2-states.js';
|
|
6
8
|
import { atomicWrite } from './safe-path.js';
|
|
7
9
|
import { ownerOf } from './session-mark.js';
|
|
8
10
|
|
|
@@ -20,7 +22,7 @@ export async function writeReadset(projectDir, ctx, env = process.env) {
|
|
|
20
22
|
/**
|
|
21
23
|
* Readset assembly — the whole command is deterministic (GCF-PRD §9.1, §10.1):
|
|
22
24
|
* PILLARS + LIVE.md + touched systems + the item + its parent + its depends + graveyard tag hits +
|
|
23
|
-
* D2 assumptions whose sys overlaps. Never over_budget-throws: the caller gates.
|
|
25
|
+
* D2 assumptions whose sys overlaps or the item cites. Never over_budget-throws: the caller gates.
|
|
24
26
|
*/
|
|
25
27
|
export async function buildContext(projectDir, itemId) {
|
|
26
28
|
const root = path.join(path.resolve(projectDir), 'gcf');
|
|
@@ -34,7 +36,7 @@ export async function buildContext(projectDir, itemId) {
|
|
|
34
36
|
const itemText =
|
|
35
37
|
`${item.data.id} ${item.data.title ?? ''} ${systems.join(' ')} ${item.body}`.toLowerCase();
|
|
36
38
|
const graveyard_hits = await graveyardHits(root, itemText);
|
|
37
|
-
const d2 = await d2Assumptions(
|
|
39
|
+
const { d2, fired } = await d2Assumptions(projectDir, config, item, systems);
|
|
38
40
|
|
|
39
41
|
const extraTokens = tokensEst(graveyard_hits.join('\n')) + tokensEst(d2.join('\n'));
|
|
40
42
|
const total_tokens_est = files.reduce((sum, f) => sum + f.tokens_est, 0) + extraTokens;
|
|
@@ -44,6 +46,8 @@ export async function buildContext(projectDir, itemId) {
|
|
|
44
46
|
files,
|
|
45
47
|
graveyard_hits,
|
|
46
48
|
d2,
|
|
49
|
+
// The ids in d2 whose trigger fired with no answer: the human's call now (GCF-PRD §7.3).
|
|
50
|
+
d2_fired: fired,
|
|
47
51
|
total_tokens_est,
|
|
48
52
|
budget: config.context_budget,
|
|
49
53
|
over_budget: total_tokens_est > config.context_budget,
|
|
@@ -111,18 +115,27 @@ async function graveyardHits(root, itemText) {
|
|
|
111
115
|
return hits;
|
|
112
116
|
}
|
|
113
117
|
|
|
114
|
-
/**
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
118
|
+
/**
|
|
119
|
+
* D2 assumptions whose sys: overlaps the item's systems (GCF-PRD §9.1), and the ones the item
|
|
120
|
+
* cites as `assumed: q-NNN` whatever their sys:; `fired`, the unanswered ones whose until: fired.
|
|
121
|
+
*/
|
|
122
|
+
async function d2Assumptions(projectDir, config, item, systems) {
|
|
123
|
+
const file = path.join(path.resolve(projectDir), 'gcf', 'open-questions.md');
|
|
124
|
+
const text = existsSync(file) ? await readFile(file, 'utf8') : '';
|
|
125
|
+
// The ledger reads every design doc: built only when a D2 can fire by a verdict.
|
|
126
|
+
if (!/^\s*class:\s*D2\b/m.test(text)) return { d2: [], fired: [] };
|
|
127
|
+
const ledger = /verdict\(/.test(text) ? await buildLedger(projectDir) : null;
|
|
128
|
+
const states = await d2States(projectDir, {
|
|
129
|
+
fired: verdictMatchers(projectDir, ledger, ledger?.items ?? []),
|
|
130
|
+
limit: config.question_stale_after_commits,
|
|
131
|
+
});
|
|
132
|
+
const cited = new Set(provenanceOf(item.body).map((r) => r.assumed));
|
|
133
|
+
const picked = states.filter(
|
|
134
|
+
(q) => q.d2 && (cited.has(q.id) || systems.some((s) => (q.sys ?? '').includes(s))),
|
|
135
|
+
);
|
|
124
136
|
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
.
|
|
137
|
+
return {
|
|
138
|
+
d2: picked.map((q) => q.text),
|
|
139
|
+
fired: picked.filter((q) => q.status === 'stale').map((q) => q.id),
|
|
140
|
+
};
|
|
128
141
|
}
|
package/lib/d2-states.js
ADDED
|
@@ -0,0 +1,208 @@
|
|
|
1
|
+
// The state and age of each record of gcf/open-questions.md, and whether an until trigger fired
|
|
2
|
+
// (GCF-PRD §7.3, §7.4): the audit, the board and the readset read them alike. It imports no
|
|
3
|
+
// work-ops.js: context.js reads it, and audit-core → work-ops → plan-check → context is a cycle.
|
|
4
|
+
import { readFile } from 'node:fs/promises';
|
|
5
|
+
import { existsSync } from 'node:fs';
|
|
6
|
+
import path from 'node:path';
|
|
7
|
+
import { spawnSync } from 'node:child_process';
|
|
8
|
+
import { fieldOf } from './question-fields.js';
|
|
9
|
+
|
|
10
|
+
export function git(args, cwd) {
|
|
11
|
+
// A blame of a long file overflows the 1 MiB default, and an overflow reads as a git failure.
|
|
12
|
+
const res = spawnSync('git', args, {
|
|
13
|
+
windowsHide: true,
|
|
14
|
+
cwd,
|
|
15
|
+
encoding: 'utf8',
|
|
16
|
+
maxBuffer: 64 * 1024 * 1024,
|
|
17
|
+
});
|
|
18
|
+
|
|
19
|
+
return res.status === 0 ? res.stdout.trim() : null;
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
export const UNTIL_RE =
|
|
23
|
+
/\[until:\s*(verdict\([a-z0-9-]+\)|retune\([a-z0-9-]+\)|manual\([^)]*\))\]/g;
|
|
24
|
+
const D2_UNTIL_RE = /^(verdict\([a-z0-9-]+\)|retune\([a-z0-9-]+\)|manual\([^)]*\))/;
|
|
25
|
+
// The two markers GCF writes itself (systems-doc.js purposeLines, gcf-adopt): no human's manual().
|
|
26
|
+
export const PLACEHOLDER_RE = /\[until:\s*manual\((?:purpose of|first verdict touching) [^)]+\)\]/;
|
|
27
|
+
const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
|
|
28
|
+
// An uncommitted line blames to the all-zero hash: it is new, not old.
|
|
29
|
+
const isUncommitted = (hash) => /^0+$/.test(hash);
|
|
30
|
+
|
|
31
|
+
/**
|
|
32
|
+
* Each line of `rel` with the commit that last changed it beyond whitespace (-w: a respaced or
|
|
33
|
+
* re-ended CRLF/LF line keeps the commit that wrote it), or null for an untracked file or
|
|
34
|
+
* outside a repository.
|
|
35
|
+
*/
|
|
36
|
+
export function blameLines(projectDir, rel) {
|
|
37
|
+
const blame = git(['blame', '-w', '--porcelain', '--', rel], projectDir);
|
|
38
|
+
if (blame === null) return null;
|
|
39
|
+
const lines = [];
|
|
40
|
+
let hash = '';
|
|
41
|
+
for (const line of blame.split('\n')) {
|
|
42
|
+
const head = line.match(/^([0-9a-f]{40,64}) \d+ \d+/);
|
|
43
|
+
if (head) hash = head[1];
|
|
44
|
+
else if (line.startsWith('\t')) lines.push({ hash, text: line.slice(1).replace(/\r$/, '') });
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
return lines;
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
/** Commits since `hash`, memoized; null when the ref no longer resolves. */
|
|
51
|
+
function commitsSince(projectDir) {
|
|
52
|
+
const ages = new Map();
|
|
53
|
+
|
|
54
|
+
return (hash) => {
|
|
55
|
+
if (!ages.has(hash)) {
|
|
56
|
+
const raw = git(['rev-list', '--count', `${hash}..HEAD`], projectDir);
|
|
57
|
+
// Number(null) is 0, "fresh" — the one answer that must never be guessed.
|
|
58
|
+
ages.set(hash, raw === null ? null : Number(raw));
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
return ages.get(hash);
|
|
62
|
+
};
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
/**
|
|
66
|
+
* Whether a verdict fired. `verdict(id)` reads the files, as the ledger does (GCF-PRD §5.8): a
|
|
67
|
+
* keep or kill left a history or graveyard line, a tune left the item's tune_count. `retune(sys,
|
|
68
|
+
* birth)` reads the tune verdicts' subjects after `birth`, the commit that wrote the record: a
|
|
69
|
+
* tune before it is the one the record already knows. An uncommitted record is new, so open.
|
|
70
|
+
* With no birth (no blame: no repository, an untracked file) it guesses as before: an item of
|
|
71
|
+
* the subsystem with a tune_count, or any tune in the log.
|
|
72
|
+
*/
|
|
73
|
+
export function verdictMatchers(projectDir, ledger, items) {
|
|
74
|
+
const tuned = items.filter((c) => (c.data.tune_count ?? 0) > 0);
|
|
75
|
+
const logs = new Map();
|
|
76
|
+
const verdictLog = (birth) => {
|
|
77
|
+
if (!logs.has(birth)) {
|
|
78
|
+
const range = birth ? [`${birth}..HEAD`] : [];
|
|
79
|
+
const args = ['log', '--basic-regexp', '--grep', '^gcf(verdict):', '--format=%s', ...range];
|
|
80
|
+
logs.set(birth, git(args, projectDir) ?? '');
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
return logs.get(birth);
|
|
84
|
+
};
|
|
85
|
+
|
|
86
|
+
// `tune <id> → <sys>,<sys>` and maybe ` (played on: …)` (work-ops.js verdictItemUnlocked).
|
|
87
|
+
const tuneOf = (system) =>
|
|
88
|
+
new RegExp(`^gcf\\(verdict\\): tune .*→ (?:\\S*,)?${escapeRe(system)}(?:,| \\(|$)`, 'm');
|
|
89
|
+
|
|
90
|
+
return {
|
|
91
|
+
verdict: (id) =>
|
|
92
|
+
ledger.where(id).terminal.some((t) => t !== 'done') || tuned.some((c) => c.data.id === id),
|
|
93
|
+
/** @param {string} system @param {string} [birth] */
|
|
94
|
+
retune: (system, birth) => {
|
|
95
|
+
if (birth) return !isUncommitted(birth) && tuneOf(system).test(verdictLog(birth));
|
|
96
|
+
|
|
97
|
+
return (
|
|
98
|
+
tuned.some((c) => (c.data.system ?? []).includes(system)) ||
|
|
99
|
+
tuneOf(system).test(verdictLog(birth))
|
|
100
|
+
);
|
|
101
|
+
},
|
|
102
|
+
};
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
/**
|
|
106
|
+
* A question as the board and its Design screen show it: an unanswered D2 whose trigger fired
|
|
107
|
+
* (`fired`), or of `manual(...)` or no trigger past the age limit (`aged`, `commits` its age), is
|
|
108
|
+
* the Operator's decision now (Until-Records-Plan d3). An agent writes every question record:
|
|
109
|
+
* its origin is one.
|
|
110
|
+
*/
|
|
111
|
+
export function questionRow(q, state) {
|
|
112
|
+
const fired = state?.status === 'stale';
|
|
113
|
+
const aged = Boolean(state?.d2 && state.aged);
|
|
114
|
+
const decision = /^D1\b/.test(q.class ?? '') || fired || aged;
|
|
115
|
+
|
|
116
|
+
return {
|
|
117
|
+
...q,
|
|
118
|
+
category: decision ? 'decision' : 'assumption',
|
|
119
|
+
origin: 'agent',
|
|
120
|
+
fired,
|
|
121
|
+
aged,
|
|
122
|
+
...(aged && { commits: state.commits }),
|
|
123
|
+
};
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
/** `stale` (fired), `open` or `manual`; `birth` as for retune. */
|
|
127
|
+
export function untilStatus(trigger, fired, birth) {
|
|
128
|
+
if (trigger.startsWith('verdict(')) {
|
|
129
|
+
return fired.verdict(trigger.slice(8, -1)) ? 'stale' : 'open';
|
|
130
|
+
}
|
|
131
|
+
|
|
132
|
+
if (trigger.startsWith('retune(')) {
|
|
133
|
+
return fired.retune(trigger.slice(7, -1), birth) ? 'stale' : 'open';
|
|
134
|
+
}
|
|
135
|
+
|
|
136
|
+
return 'manual';
|
|
137
|
+
}
|
|
138
|
+
|
|
139
|
+
/**
|
|
140
|
+
* Every record of open-questions.md with its state: `trigger` a D2's until (null for a D1 or
|
|
141
|
+
* none); `status` a D2's `answered`, `stale`, `open` or `manual` (null for a D1 or no trigger);
|
|
142
|
+
* `commits` since the commit that wrote its `- id:` line (undefined with no such commit: an
|
|
143
|
+
* uncommitted record, no blame; null when that commit no longer resolves); `aged` an unanswered
|
|
144
|
+
* record the human owes past `limit` commits — a D1, or a D2 with `manual(...)` or no trigger
|
|
145
|
+
* (GCF-PRD §7.4): an acting D2 waits for its trigger, a fired one is a stale until record.
|
|
146
|
+
* shortcut: a blame, a git log and a rev-list per call, the board's included; cache by HEAD
|
|
147
|
+
* when the board's refresh feels it.
|
|
148
|
+
*/
|
|
149
|
+
export async function d2States(projectDir, { fired, limit }) {
|
|
150
|
+
const file = path.join(path.resolve(projectDir), 'gcf', 'open-questions.md');
|
|
151
|
+
if (!existsSync(file)) return [];
|
|
152
|
+
const text = noBom(await readFile(file, 'utf8')).replace(/\r\n/g, '\n');
|
|
153
|
+
const at = { fired, limit, births: birthsOf(projectDir), since: commitsSince(projectDir) };
|
|
154
|
+
|
|
155
|
+
return text.split(/\n(?=- id:)/).flatMap((rec) => {
|
|
156
|
+
const id = rec.match(/^- id:\s*(\S+)/)?.[1];
|
|
157
|
+
|
|
158
|
+
return id ? [recordState(id, rec, at)] : [];
|
|
159
|
+
});
|
|
160
|
+
}
|
|
161
|
+
|
|
162
|
+
const BOM = String.fromCharCode(0xfeff);
|
|
163
|
+
const noBom = (s) => (s.startsWith(BOM) ? s.slice(1) : s);
|
|
164
|
+
|
|
165
|
+
/** The commit that wrote each record's `- id:` line, or null without a blame. */
|
|
166
|
+
function birthsOf(projectDir) {
|
|
167
|
+
const blamed = blameLines(projectDir, 'gcf/open-questions.md');
|
|
168
|
+
if (!blamed) return null;
|
|
169
|
+
const births = new Map();
|
|
170
|
+
for (const { hash, text } of blamed) {
|
|
171
|
+
const id = noBom(text).match(/^- id:\s*(\S+)/)?.[1];
|
|
172
|
+
if (id) births.set(id, hash);
|
|
173
|
+
}
|
|
174
|
+
|
|
175
|
+
return births;
|
|
176
|
+
}
|
|
177
|
+
|
|
178
|
+
function recordState(id, rec, { fired, limit, births, since }) {
|
|
179
|
+
const d2 = /^D2\b/.test(fieldOf(rec, 'class') ?? '');
|
|
180
|
+
const answered = Boolean(fieldOf(rec, 'answer'));
|
|
181
|
+
const trigger = d2 ? triggerOf(rec) : null;
|
|
182
|
+
// No blame: no birth, retune as before; a record the blame does not show is uncommitted.
|
|
183
|
+
const birth = births ? (births.get(id) ?? '0') : undefined;
|
|
184
|
+
const status = statusOf({ d2, answered, trigger }, fired, birth);
|
|
185
|
+
const commits = birth && !isUncommitted(birth) ? since(birth) : undefined;
|
|
186
|
+
const owed = !answered && (!trigger || status === 'manual');
|
|
187
|
+
|
|
188
|
+
return {
|
|
189
|
+
id,
|
|
190
|
+
d2,
|
|
191
|
+
trigger,
|
|
192
|
+
status,
|
|
193
|
+
commits,
|
|
194
|
+
aged: owed && isOld(commits, limit),
|
|
195
|
+
sys: fieldOf(rec, 'sys'),
|
|
196
|
+
text: rec.trim(),
|
|
197
|
+
};
|
|
198
|
+
}
|
|
199
|
+
|
|
200
|
+
const triggerOf = (rec) => fieldOf(rec, 'until')?.match(D2_UNTIL_RE)?.[1] ?? null;
|
|
201
|
+
// No commit to age from is fresh; a commit that no longer resolves is never guessed fresh.
|
|
202
|
+
const isOld = (commits, limit) => commits !== undefined && (commits === null || commits > limit);
|
|
203
|
+
|
|
204
|
+
function statusOf({ d2, answered, trigger }, fired, birth) {
|
|
205
|
+
if (d2 && answered) return 'answered';
|
|
206
|
+
|
|
207
|
+
return trigger ? untilStatus(trigger, fired, birth) : null;
|
|
208
|
+
}
|
package/lib/design-parts.js
CHANGED
|
@@ -44,7 +44,7 @@ import { buildLedger } from './ledger.js';
|
|
|
44
44
|
import { deriveId } from './id.js';
|
|
45
45
|
import { renamePillar } from './pillars.js';
|
|
46
46
|
import { dirtyPaths, restoreFromHead } from './git.js';
|
|
47
|
-
import { blocksOf, putBlock } from './systems-doc.js';
|
|
47
|
+
import { blocksOf, fillPurpose, purposeTarget, putBlock } from './systems-doc.js';
|
|
48
48
|
|
|
49
49
|
// The work stage writes these blocks: a unit in design/ has not reached them.
|
|
50
50
|
const WORK_ONLY = ['contract', 'interactions', 'tuning', 'notes'];
|
|
@@ -556,6 +556,27 @@ const noteOf = (p) =>
|
|
|
556
556
|
// Nothing of the bundle applied: no commit to make.
|
|
557
557
|
class NothingApplied extends Error {}
|
|
558
558
|
|
|
559
|
+
/**
|
|
560
|
+
* The subsystems of the design/<s>.md among `files` whose systems doc still waits on its purpose
|
|
561
|
+
* and gets it from this move (fillPurpose), each with that doc. `parts`: a bundle's, whose system
|
|
562
|
+
* part is the purpose the move is about to write.
|
|
563
|
+
* @param {string} root
|
|
564
|
+
* @param {string[]} files
|
|
565
|
+
* @param {{kind: string, name: string, text: string}[]} [parts]
|
|
566
|
+
*/
|
|
567
|
+
async function purposeFills(root, files, parts = []) {
|
|
568
|
+
const fills = new Map();
|
|
569
|
+
for (const f of files) {
|
|
570
|
+
const s = path.basename(f, '.md');
|
|
571
|
+
if (path.dirname(f) !== path.join(root, 'design') || !SLUG_RE.test(s) || fills.has(s)) continue;
|
|
572
|
+
const part = parts.find((p) => p.kind === 'system' && p.name === s);
|
|
573
|
+
const doc = await purposeTarget(root, s, part?.text);
|
|
574
|
+
if (doc) fills.set(s, doc);
|
|
575
|
+
}
|
|
576
|
+
|
|
577
|
+
return fills;
|
|
578
|
+
}
|
|
579
|
+
|
|
559
580
|
/**
|
|
560
581
|
* Bring `text` in through the import and commit what it wrote. `strict`: a part the import
|
|
561
582
|
* reports refuses the whole move. Files with changes not recorded yet refuse it up front: the
|
|
@@ -573,8 +594,9 @@ async function bundleMove(
|
|
|
573
594
|
{ key, items = [], strict = false, draft = false, commit = true },
|
|
574
595
|
) {
|
|
575
596
|
const root = path.join(path.resolve(projectDir), 'gcf');
|
|
597
|
+
const { parts } = parseBundle(text);
|
|
576
598
|
// Only the names a write may take (bundle.js validName): no other path gets staged.
|
|
577
|
-
const files =
|
|
599
|
+
const files = parts.flatMap((p) => {
|
|
578
600
|
if (p.kind === 'doc')
|
|
579
601
|
return Object.hasOwn(DOC_FILES, p.name) ? [path.join(root, DOC_FILES[p.name])] : [];
|
|
580
602
|
const sys = p.kind === 'system' ? p.name : p.system;
|
|
@@ -583,7 +605,8 @@ async function bundleMove(
|
|
|
583
605
|
? [path.join(root, 'design', `${sys}.md`)]
|
|
584
606
|
: [];
|
|
585
607
|
});
|
|
586
|
-
const
|
|
608
|
+
const fills = await purposeFills(root, files, parts);
|
|
609
|
+
const touched = [...new Set([...files, path.join(root, 'backlog.md'), ...fills.values()])];
|
|
587
610
|
const rel = (f) => path.relative(path.resolve(projectDir), f).replaceAll('\\', '/');
|
|
588
611
|
// A form's save over an agent's draft of its own file takes the draft along (decision 35): the
|
|
589
612
|
// operator saw it in the form. Another file's changes would ride along unseen.
|
|
@@ -611,6 +634,7 @@ async function bundleMove(
|
|
|
611
634
|
if (strict && refused.length)
|
|
612
635
|
throw new Error(refused.map((p) => `${p.outcome} ${p.part}: ${noteOf(p)}`).join('\n'));
|
|
613
636
|
if (!result.applied.length) throw new NothingApplied();
|
|
637
|
+
for (const s of fills.keys()) await fillPurpose(root, s);
|
|
614
638
|
},
|
|
615
639
|
});
|
|
616
640
|
|
|
@@ -690,16 +714,21 @@ async function commitUnlocked(projectDir, { message = null, commit = true } = {}
|
|
|
690
714
|
}
|
|
691
715
|
|
|
692
716
|
const abs = files.map((f) => path.join(path.resolve(projectDir), f));
|
|
717
|
+
const root = path.join(path.resolve(projectDir), 'gcf');
|
|
718
|
+
const fills = await purposeFills(root, abs);
|
|
693
719
|
const why = oneLine(message) || 'record the design';
|
|
694
720
|
const hash = await commitMove(projectDir, `gcf(design): ${why}`, {
|
|
695
|
-
files: abs,
|
|
721
|
+
files: [...abs, ...fills.values()],
|
|
696
722
|
inputs: abs,
|
|
697
|
-
mutate: async () => {
|
|
723
|
+
mutate: async () => {
|
|
724
|
+
for (const s of fills.keys()) await fillPurpose(root, s);
|
|
725
|
+
},
|
|
698
726
|
commit,
|
|
699
727
|
key: 'design-commit',
|
|
700
728
|
});
|
|
729
|
+
const rel = (f) => path.relative(path.resolve(projectDir), f).replaceAll('\\', '/');
|
|
701
730
|
|
|
702
|
-
return { files, hash };
|
|
731
|
+
return { files: [...files, ...[...fills.values()].map(rel)], hash };
|
|
703
732
|
}
|
|
704
733
|
|
|
705
734
|
// What an agent's draft writes (decision 35), and so what `design discard` may take back: not an
|
|
@@ -760,7 +789,8 @@ export async function designState(projectDir, { report, questions, items }) {
|
|
|
760
789
|
const units = new Set(report.units.map((u) => u.id));
|
|
761
790
|
const sources = await sourcesOf(root);
|
|
762
791
|
const asked = questions.filter((q) => isDesignQuestion(q, units));
|
|
763
|
-
|
|
792
|
+
// The board's rows (d2-states.js questionRow): a fired or aged D2 waits on the Operator too.
|
|
793
|
+
const open = asked.filter((q) => q.category === 'decision' && !q.answer);
|
|
764
794
|
const pillars = recordsIn(pillarsText, 'pillars').map((p) => ({
|
|
765
795
|
id: p.id ?? null,
|
|
766
796
|
// The few words the operator knows it by (decision 34); an old file has none.
|
package/lib/git.js
CHANGED
|
@@ -119,7 +119,18 @@ export const GATE_SCOPE = [
|
|
|
119
119
|
export function dirtyGcf(projectDir, skip = []) {
|
|
120
120
|
const res = spawnSync(
|
|
121
121
|
'git',
|
|
122
|
-
|
|
122
|
+
// No index.lock: a move waiting behind a run asks this each second, and would break its commit.
|
|
123
|
+
[
|
|
124
|
+
'--no-optional-locks',
|
|
125
|
+
'-c',
|
|
126
|
+
'core.quotePath=false',
|
|
127
|
+
'status',
|
|
128
|
+
'--porcelain',
|
|
129
|
+
'-z',
|
|
130
|
+
'-uall',
|
|
131
|
+
'--',
|
|
132
|
+
...GATE_SCOPE,
|
|
133
|
+
],
|
|
123
134
|
{ windowsHide: true, cwd: projectDir, encoding: 'utf8' },
|
|
124
135
|
);
|
|
125
136
|
if (res.status !== 0) return [];
|
|
@@ -152,12 +163,16 @@ export function dirtyGcf(projectDir, skip = []) {
|
|
|
152
163
|
|
|
153
164
|
/**
|
|
154
165
|
* The refusal of a move that uncommitted gcf/ edits stop: `dirty` with `paths` (dirtyGcf) when
|
|
155
|
-
* there are any, so a board offers to show, commit or discard them; else the words alone.
|
|
166
|
+
* there are any, so a board offers to show, commit or discard them; else the words alone. `move`
|
|
167
|
+
* names the move it stops: one that waits behind a main run says it (lib/main-lock.js).
|
|
156
168
|
* @param {string[]} paths
|
|
157
169
|
* @param {string} message
|
|
170
|
+
* @param {{message: string, items?: string[]}} move
|
|
158
171
|
*/
|
|
159
|
-
export const dirtyRefusal = (paths, message) =>
|
|
160
|
-
paths.length ? refusal('dirty', { paths }, message) : new Error(message)
|
|
172
|
+
export const dirtyRefusal = (paths, message, move) =>
|
|
173
|
+
Object.assign(paths.length ? refusal('dirty', { paths }, message) : new Error(message), {
|
|
174
|
+
move: { ...move, items: move.items ?? [] },
|
|
175
|
+
});
|
|
161
176
|
|
|
162
177
|
/** A path from the project with `/`, from an absolute one or one already relative. */
|
|
163
178
|
const relOf = (projectDir, p) =>
|
|
@@ -288,7 +303,12 @@ export function commitPaths(projectDir, message, paths, move = {}) {
|
|
|
288
303
|
// nothing: no pathspec.
|
|
289
304
|
const real = paths.filter((p) => existsSync(p) || inHead(projectDir, p));
|
|
290
305
|
|
|
291
|
-
|
|
306
|
+
try {
|
|
307
|
+
return commitOnly(projectDir, message, real, ['-m', message, ...moveTrailers(move)]);
|
|
308
|
+
} catch (e) {
|
|
309
|
+
if (e.move) e.move.items = move.items ?? [];
|
|
310
|
+
throw e;
|
|
311
|
+
}
|
|
292
312
|
}
|
|
293
313
|
|
|
294
314
|
/**
|
|
@@ -327,6 +347,7 @@ export function commitOnly(projectDir, message, paths, msg) {
|
|
|
327
347
|
loose,
|
|
328
348
|
`cannot record ${message} while gcf/ holds uncommitted changes: ${loose.join(', ')} — ` +
|
|
329
349
|
'commit or discard them, then try again',
|
|
350
|
+
{ message },
|
|
330
351
|
);
|
|
331
352
|
}
|
|
332
353
|
|
package/lib/main-lock.js
CHANGED
|
@@ -4,13 +4,28 @@
|
|
|
4
4
|
// holds it across the merge and the move it records.
|
|
5
5
|
import { AsyncLocalStorage } from 'node:async_hooks';
|
|
6
6
|
import { link, mkdir, readFile, stat, unlink, writeFile } from 'node:fs/promises';
|
|
7
|
-
import {
|
|
7
|
+
import {
|
|
8
|
+
existsSync,
|
|
9
|
+
mkdirSync,
|
|
10
|
+
readdirSync,
|
|
11
|
+
readFileSync,
|
|
12
|
+
renameSync,
|
|
13
|
+
rmSync,
|
|
14
|
+
writeFileSync,
|
|
15
|
+
} from 'node:fs';
|
|
8
16
|
import { randomUUID } from 'node:crypto';
|
|
9
17
|
import path from 'node:path';
|
|
18
|
+
// Not `process.stdin.isTTY`: reading it opens stdin, which may keep a piped command alive.
|
|
19
|
+
import { isatty } from 'node:tty';
|
|
20
|
+
import { dirtyGcf, moveBy } from './git.js';
|
|
21
|
+
import { refusal } from './refusal.js';
|
|
10
22
|
|
|
11
23
|
const chain = new AsyncLocalStorage();
|
|
12
24
|
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
|
|
13
25
|
|
|
26
|
+
/** How often a move waiting behind a main run looks at gcf/, and how long a claim yields to one. */
|
|
27
|
+
export const waitTiming = { pollMs: 1000, yieldMs: 5000 };
|
|
28
|
+
|
|
14
29
|
export const lockFile = (projectDir) =>
|
|
15
30
|
path.join(path.resolve(projectDir), '.gcf-session', 'main.lock');
|
|
16
31
|
|
|
@@ -179,10 +194,187 @@ async function clearStale(file, text) {
|
|
|
179
194
|
* @returns {Promise<T>}
|
|
180
195
|
*/
|
|
181
196
|
export async function withMainLock(projectDir, fn, { waitMs = 60000 } = {}) {
|
|
182
|
-
const file = lockFile(projectDir);
|
|
183
197
|
const held = chain.getStore() ?? new Set();
|
|
184
|
-
if (held.has(
|
|
198
|
+
if (held.has(lockFile(projectDir))) return fn();
|
|
199
|
+
const once = () => holding(projectDir, held, fn, waitMs);
|
|
200
|
+
if (!mayWait()) return once();
|
|
201
|
+
|
|
202
|
+
// The operator's move stopped by a main run's gcf/ edits waits for them, without the lock (the
|
|
203
|
+
// run's own moves need it), then goes again from its first read (docs/Main-Run-Moves-Plan.md).
|
|
204
|
+
const wait = waiter(projectDir);
|
|
205
|
+
try {
|
|
206
|
+
for (;;) {
|
|
207
|
+
try {
|
|
208
|
+
return await once();
|
|
209
|
+
} catch (e) {
|
|
210
|
+
await wait(e);
|
|
211
|
+
}
|
|
212
|
+
}
|
|
213
|
+
} finally {
|
|
214
|
+
wait.end();
|
|
215
|
+
}
|
|
216
|
+
}
|
|
217
|
+
|
|
218
|
+
/**
|
|
219
|
+
* Only the operator waits, from a terminal or a board that knows its move (`GCF_MOVE_TAG`): a
|
|
220
|
+
* session's or a script's command is killed by its caller's timeout, maybe mid-commit.
|
|
221
|
+
*/
|
|
222
|
+
const mayWait = () => moveBy() === 'operator' && (isatty(0) || Boolean(process.env.GCF_MOVE_TAG));
|
|
223
|
+
|
|
224
|
+
const TOKEN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
|
|
225
|
+
|
|
226
|
+
/**
|
|
227
|
+
* The card a live main run works now; null with none, or when the lock holds the token of a
|
|
228
|
+
* build, a push or a play: their edits are no run's that a commit of it would clear.
|
|
229
|
+
*/
|
|
230
|
+
function mainRunCard(projectDir) {
|
|
231
|
+
try {
|
|
232
|
+
const file = path.join(path.resolve(projectDir), '.gcf-session', 'runs', `${MAIN_RUN}.lock`);
|
|
233
|
+
const [pid, item] = readFileSync(file, 'utf8')
|
|
234
|
+
.split('\n')
|
|
235
|
+
.map((s) => s.trim());
|
|
236
|
+
const n = Number(pid);
|
|
237
|
+
|
|
238
|
+
return item && !TOKEN.test(item) && n > 0 && n !== process.pid && alive(n) ? item : null;
|
|
239
|
+
} catch {
|
|
240
|
+
return null;
|
|
241
|
+
}
|
|
242
|
+
}
|
|
185
243
|
|
|
244
|
+
const waitingDir = (projectDir) => path.join(path.resolve(projectDir), '.gcf-session', 'waiting');
|
|
245
|
+
|
|
246
|
+
/**
|
|
247
|
+
* The records of moves waiting behind a main run (`.gcf-session/waiting/<pid>.json`), each with
|
|
248
|
+
* its `pid` and `file`. A record whose process died is left over: it is removed, not listed.
|
|
249
|
+
* @returns {Array<{pid: number, file: string, message?: string, items?: string[],
|
|
250
|
+
* tag?: string | null, behind?: string, paths?: string[], cancel?: string, going?: boolean}>}
|
|
251
|
+
*/
|
|
252
|
+
export function liveWaiting(projectDir) {
|
|
253
|
+
const dir = waitingDir(projectDir);
|
|
254
|
+
let names;
|
|
255
|
+
try {
|
|
256
|
+
names = readdirSync(dir);
|
|
257
|
+
} catch {
|
|
258
|
+
return [];
|
|
259
|
+
}
|
|
260
|
+
|
|
261
|
+
return names.flatMap((name) => {
|
|
262
|
+
const pid = Number(/^(\d+)\.json$/.exec(name)?.[1]);
|
|
263
|
+
if (!pid) return [];
|
|
264
|
+
const file = path.join(dir, name);
|
|
265
|
+
if (!alive(pid)) {
|
|
266
|
+
rmSync(file, { force: true });
|
|
267
|
+
|
|
268
|
+
return [];
|
|
269
|
+
}
|
|
270
|
+
|
|
271
|
+
try {
|
|
272
|
+
return [{ ...JSON.parse(readFileSync(file, 'utf8')), pid, file }];
|
|
273
|
+
} catch {
|
|
274
|
+
return [];
|
|
275
|
+
}
|
|
276
|
+
});
|
|
277
|
+
}
|
|
278
|
+
|
|
279
|
+
/**
|
|
280
|
+
* The wait of one move: `wait(e)` rethrows a failure that is no main run's `dirty` refusal;
|
|
281
|
+
* else it keeps its record, tells once, and resolves when the refusal's paths are clean. It
|
|
282
|
+
* rethrows the refusal when the run is gone, and refuses on a cancel file. Its record says
|
|
283
|
+
* `going` once the paths cleared and the move goes again. `wait.end()` removes the record and
|
|
284
|
+
* the cancel file, on every way out of the move.
|
|
285
|
+
*/
|
|
286
|
+
function waiter(projectDir) {
|
|
287
|
+
const dir = waitingDir(projectDir);
|
|
288
|
+
const record = path.join(dir, `${process.pid}.json`);
|
|
289
|
+
const cancel = process.env.GCF_MOVE_CANCEL || path.join(dir, `${process.pid}.cancel`);
|
|
290
|
+
let told = false;
|
|
291
|
+
|
|
292
|
+
/** @param {any} e */
|
|
293
|
+
const wait = async (e) => {
|
|
294
|
+
const card = e?.refusal?.code === 'dirty' ? mainRunCard(projectDir) : null;
|
|
295
|
+
if (!card) throw e;
|
|
296
|
+
const { paths } = e.refusal;
|
|
297
|
+
const { message = 'the move', items = [] } = e.move ?? {};
|
|
298
|
+
const tag = process.env.GCF_MOVE_TAG || null;
|
|
299
|
+
const keep = (going = false) => {
|
|
300
|
+
// Whole or not at all: a reader never parses half a record.
|
|
301
|
+
writeFileSync(
|
|
302
|
+
`${record}.tmp`,
|
|
303
|
+
JSON.stringify({ message, items, tag, behind: card, paths, cancel, going }),
|
|
304
|
+
);
|
|
305
|
+
renameSync(`${record}.tmp`, record);
|
|
306
|
+
};
|
|
307
|
+
|
|
308
|
+
mkdirSync(dir, { recursive: true });
|
|
309
|
+
if (!told) {
|
|
310
|
+
// A cancel a dead move of this pid left behind is no cancel of this one.
|
|
311
|
+
rmSync(cancel, { force: true });
|
|
312
|
+
}
|
|
313
|
+
|
|
314
|
+
keep();
|
|
315
|
+
if (!told) {
|
|
316
|
+
told = true;
|
|
317
|
+
process.stderr.write(
|
|
318
|
+
`${message} waits: the run of ${card} holds gcf/ edits (${paths.join(', ')}); it goes ` +
|
|
319
|
+
'when they are committed. Nothing is written while it waits.\n' +
|
|
320
|
+
`gcf-waiting: ${JSON.stringify({ behind: card, paths })}\n`,
|
|
321
|
+
);
|
|
322
|
+
}
|
|
323
|
+
|
|
324
|
+
if (!(await cleared(card, paths, message))) throw e;
|
|
325
|
+
// It goes again: a Cancel from now on comes too late (the board answers "already recorded").
|
|
326
|
+
keep(true);
|
|
327
|
+
};
|
|
328
|
+
|
|
329
|
+
/** True once `paths` are clean, false when the run is gone with them still dirty. */
|
|
330
|
+
const cleared = async (card, paths, message) => {
|
|
331
|
+
// shortcut: one `git status` a second per waiting move, cheap for a few; watch gcf/ when
|
|
332
|
+
// many moves wait at once.
|
|
333
|
+
for (;;) {
|
|
334
|
+
await sleep(waitTiming.pollMs);
|
|
335
|
+
if (existsSync(cancel)) {
|
|
336
|
+
rmSync(cancel, { force: true });
|
|
337
|
+
throw refusal(
|
|
338
|
+
'cancelled',
|
|
339
|
+
{},
|
|
340
|
+
`${message}: cancelled while it waited behind the run of ${card} — nothing was recorded`,
|
|
341
|
+
);
|
|
342
|
+
}
|
|
343
|
+
|
|
344
|
+
const dirty = new Set(dirtyGcf(projectDir));
|
|
345
|
+
if (!paths.some((p) => dirty.has(p))) return true;
|
|
346
|
+
// Gone with its edits left: they are no run's now, and today's refusal names them.
|
|
347
|
+
if (!mainRunCard(projectDir)) return false;
|
|
348
|
+
}
|
|
349
|
+
};
|
|
350
|
+
|
|
351
|
+
// A cancel that came as it went is no cancel of a later move under the same pid.
|
|
352
|
+
wait.end = () => {
|
|
353
|
+
rmSync(record, { force: true });
|
|
354
|
+
rmSync(cancel, { force: true });
|
|
355
|
+
};
|
|
356
|
+
|
|
357
|
+
return wait;
|
|
358
|
+
}
|
|
359
|
+
|
|
360
|
+
/**
|
|
361
|
+
* A card's claim lets a waiting move go first (docs/Main-Run-Moves-Plan.md d4): after a run's
|
|
362
|
+
* last commit gcf/ is clean, and a claim would soil it again before the move's next look. Only
|
|
363
|
+
* when every waiting move's paths are clean already, and for `waitTiming.yieldMs` at most.
|
|
364
|
+
*/
|
|
365
|
+
export async function yieldToWaiting(projectDir) {
|
|
366
|
+
const waits = liveWaiting(projectDir);
|
|
367
|
+
if (!waits.length) return;
|
|
368
|
+
const dirty = new Set(dirtyGcf(projectDir));
|
|
369
|
+
if (waits.some((w) => (w.paths ?? []).some((p) => dirty.has(p)))) return;
|
|
370
|
+
const until = Date.now() + waitTiming.yieldMs;
|
|
371
|
+
while (Date.now() < until && waits.some((w) => existsSync(w.file) && alive(w.pid)))
|
|
372
|
+
await sleep(100);
|
|
373
|
+
}
|
|
374
|
+
|
|
375
|
+
/** Take the main lock, run `fn` under it, let it go. */
|
|
376
|
+
async function holding(projectDir, held, fn, waitMs) {
|
|
377
|
+
const file = lockFile(projectDir);
|
|
186
378
|
await mkdir(path.dirname(file), { recursive: true });
|
|
187
379
|
const token = randomUUID();
|
|
188
380
|
const until = Date.now() + waitMs;
|