gcf-aif-ext 0.24.0 → 0.26.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/GLOSSARY.md +12 -0
- package/README.md +5 -2
- package/commands/gcf.js +202 -24
- package/extension.json +1 -1
- package/lib/agent-permissions.js +28 -2
- package/lib/board.js +35 -10
- package/lib/config-set.js +29 -0
- package/lib/domain.js +94 -0
- package/lib/integrate.js +12 -6
- package/lib/main-lock.js +24 -0
- package/lib/plan-check.js +117 -6
- package/lib/play.js +1022 -0
- package/lib/playtest-list.js +9 -12
- package/lib/safe-path.js +1 -1
- package/lib/transitions.js +8 -1
- package/lib/validate-item.js +26 -0
- package/lib/verify.js +7 -7
- package/lib/work-ops.js +85 -6
- package/package.json +1 -1
- package/schemas/item.schema.json +12 -0
- package/skills/gcf-adopt/SKILL.md +2 -1
- package/skills/gcf-chat/SKILL.md +6 -3
- package/skills/gcf-verdict/SKILL.md +4 -0
- package/templates/agents-block.md +17 -2
- package/templates/config.yml +19 -0
package/lib/playtest-list.js
CHANGED
|
@@ -3,9 +3,9 @@ import { existsSync } from 'node:fs';
|
|
|
3
3
|
import { readFile } from 'node:fs/promises';
|
|
4
4
|
import path from 'node:path';
|
|
5
5
|
import { gameMilestones } from './design-check.js';
|
|
6
|
-
import { listItems, scalarOf,
|
|
6
|
+
import { listItems, scalarOf, firstBullet } from './gcf-paths.js';
|
|
7
|
+
import { buildOf, linksOf } from './play.js';
|
|
7
8
|
import { recordsOf } from './verdict-fs.js';
|
|
8
|
-
import { runDod } from './verify.js';
|
|
9
9
|
|
|
10
10
|
const ENVELOPE = /^\S+\.\.\S+ /;
|
|
11
11
|
|
|
@@ -50,11 +50,12 @@ export async function platformsOf(root) {
|
|
|
50
50
|
|
|
51
51
|
/**
|
|
52
52
|
* Playtest list (Methodology §5.3): every item waiting for its verdict, and every unplayed one,
|
|
53
|
-
* with the question the play must answer, its milestone
|
|
54
|
-
*
|
|
53
|
+
* with the question the play must answer, its milestone, where to play it (`play_on`, else every
|
|
54
|
+
* line of `platforms`) and its build (lib/play.js), null while it has none.
|
|
55
55
|
*/
|
|
56
56
|
export async function playtestList(root) {
|
|
57
57
|
const platforms = await platformsOf(root);
|
|
58
|
+
const links = linksOf(path.dirname(root));
|
|
58
59
|
|
|
59
60
|
return (await listItems(root))
|
|
60
61
|
.filter((c) => ['awaiting-verdict', 'unplayed'].includes(c.data.status))
|
|
@@ -65,6 +66,7 @@ export async function playtestList(root) {
|
|
|
65
66
|
system: c.data.system ?? [],
|
|
66
67
|
milestone: c.data.milestone ?? null,
|
|
67
68
|
play_on: c.data.play_on ?? platforms,
|
|
69
|
+
build: buildOf(path.dirname(root), String(c.data.id), c.data.status, links),
|
|
68
70
|
question: scalarOf(c.body, 'miss_criterion') || '(miss_criterion is empty)',
|
|
69
71
|
reach: recordsOf(c.body, 'behavior')
|
|
70
72
|
.map((r) => r.input)
|
|
@@ -94,14 +96,11 @@ const git = (projectDir, args) => {
|
|
|
94
96
|
};
|
|
95
97
|
|
|
96
98
|
/**
|
|
97
|
-
* `playtest session` (Methodology §5.3):
|
|
99
|
+
* `playtest session` (Methodology §5.3): where main stands and the checklist of everything that
|
|
98
100
|
* waits for play, grouped by subsystem — built from the items on every call, no file of its own.
|
|
99
|
-
*
|
|
101
|
+
* Each item names its own build (lib/play.js).
|
|
100
102
|
*/
|
|
101
|
-
export async function playtestSession(
|
|
102
|
-
projectDir,
|
|
103
|
-
{ build = false, stdio = ['ignore', 2, 2] } = {},
|
|
104
|
-
) {
|
|
103
|
+
export async function playtestSession(projectDir) {
|
|
105
104
|
const root = path.join(path.resolve(projectDir), 'gcf');
|
|
106
105
|
const milestones = (await gameMilestones(root)) ?? [];
|
|
107
106
|
// Milestones in game.md's order, then the items with none (or one game.md no longer has).
|
|
@@ -132,7 +131,6 @@ export async function playtestSession(
|
|
|
132
131
|
commit: git(projectDir, ['rev-parse', '--short', 'HEAD']),
|
|
133
132
|
// No commit (no repository, or none yet): the build is unknown, not clean.
|
|
134
133
|
dirty: dirty === null ? null : Boolean(dirty),
|
|
135
|
-
build: /** @type {Awaited<ReturnType<typeof runDod>> | null} */ (null),
|
|
136
134
|
// Each milestone with something to play: its goal, the question its play answers, and how
|
|
137
135
|
// much of it is still being built or blocked.
|
|
138
136
|
milestones: milestones
|
|
@@ -152,7 +150,6 @@ export async function playtestSession(
|
|
|
152
150
|
items,
|
|
153
151
|
decisions: await decisionList(root),
|
|
154
152
|
};
|
|
155
|
-
if (build) session.build = await runDod(projectDir, await readConfig(root), 'build', stdio);
|
|
156
153
|
|
|
157
154
|
return session;
|
|
158
155
|
}
|
package/lib/safe-path.js
CHANGED
|
@@ -32,7 +32,7 @@ const BUSY = new Set(['EPERM', 'EACCES', 'EBUSY']);
|
|
|
32
32
|
// The board's writeAtomicSync budget: a scan of a fresh file often outlasts 200 ms.
|
|
33
33
|
const RENAME_TRIES = 10;
|
|
34
34
|
|
|
35
|
-
async function renameRetrying(from, to) {
|
|
35
|
+
export async function renameRetrying(from, to) {
|
|
36
36
|
for (let attempt = 1; ; attempt++) {
|
|
37
37
|
try {
|
|
38
38
|
return await rename(from, to);
|
package/lib/transitions.js
CHANGED
|
@@ -40,6 +40,10 @@ const FROM = {
|
|
|
40
40
|
gates: STORED,
|
|
41
41
|
// Nor a fix of its text; only an unplayed body is frozen (§5.4).
|
|
42
42
|
amend: STORED.filter((s) => s !== 'unplayed'),
|
|
43
|
+
// Planning that does not converge (Hold-Plan d16): the run stalls it, the operator decides.
|
|
44
|
+
plan_stall: ['ready'],
|
|
45
|
+
plan_more: ['blocked'],
|
|
46
|
+
plan_accept: ['blocked'],
|
|
43
47
|
};
|
|
44
48
|
|
|
45
49
|
/** Every move an item may be offered, in the board's order. */
|
|
@@ -62,10 +66,13 @@ export const decisionFits = (choice, type) =>
|
|
|
62
66
|
(!BUG_ONLY.includes(choice) || type === 'bug');
|
|
63
67
|
|
|
64
68
|
/** Whether a move fits the item beyond its status: its gate for submit and close, its type. */
|
|
65
|
-
function fits(move, { type, gate }) {
|
|
69
|
+
function fits(move, { type, gate, stall }) {
|
|
66
70
|
const [cmd, arg] = move.split(':');
|
|
67
71
|
if (cmd === 'submit') return gate !== 'auto';
|
|
68
72
|
if (cmd === 'close') return gate === 'auto';
|
|
73
|
+
// The run's stall is no move a board offers; the operator's answers only to a stall.
|
|
74
|
+
if (cmd === 'plan_stall') return false;
|
|
75
|
+
if (cmd === 'plan_more' || cmd === 'plan_accept') return Boolean(stall);
|
|
69
76
|
|
|
70
77
|
return cmd !== 'decide' || decisionFits(arg, type);
|
|
71
78
|
}
|
package/lib/validate-item.js
CHANGED
|
@@ -68,6 +68,8 @@ const FIELDS = [
|
|
|
68
68
|
'priority',
|
|
69
69
|
'plan',
|
|
70
70
|
'tune_count',
|
|
71
|
+
'plan_cycle',
|
|
72
|
+
'stall',
|
|
71
73
|
'severity',
|
|
72
74
|
'blocked',
|
|
73
75
|
'since',
|
|
@@ -120,6 +122,28 @@ function changeProblem(c) {
|
|
|
120
122
|
}
|
|
121
123
|
|
|
122
124
|
/** A live: delta (Methodology §8): `{none: <why>}` or `{changes: [{id, change, summary}]}`. */
|
|
125
|
+
/**
|
|
126
|
+
* What is wrong with an item's `stall:` (Hold-Plan d16), or null: `{passes, reason?, more?,
|
|
127
|
+
* accepted?}`, the blocking counts of each pass, the operator's extra passes or their yes.
|
|
128
|
+
*/
|
|
129
|
+
function stallProblem(v) {
|
|
130
|
+
const count = (n) => Number.isInteger(n) && n >= 0;
|
|
131
|
+
const keys = { passes: (x) => Array.isArray(x) && x.every(count) };
|
|
132
|
+
const optional = {
|
|
133
|
+
reason: (x) => typeof x === 'string',
|
|
134
|
+
more: (x) => count(x) && x >= 1,
|
|
135
|
+
accepted: (x) => x === true,
|
|
136
|
+
};
|
|
137
|
+
const ok =
|
|
138
|
+
v !== null &&
|
|
139
|
+
typeof v === 'object' &&
|
|
140
|
+
!Array.isArray(v) &&
|
|
141
|
+
keys.passes(v.passes) &&
|
|
142
|
+
Object.entries(v).every(([k, x]) => k === 'passes' || optional[k]?.(x));
|
|
143
|
+
|
|
144
|
+
return ok ? null : 'stall must be {passes: [counts], reason?, more?: n >= 1, accepted?: true}';
|
|
145
|
+
}
|
|
146
|
+
|
|
123
147
|
export function liveProblem(v) {
|
|
124
148
|
if (v === null || v === undefined) return null;
|
|
125
149
|
if (typeof v !== 'object' || Array.isArray(v)) return LIVE_SHAPE;
|
|
@@ -169,6 +193,8 @@ const RULES = {
|
|
|
169
193
|
'priority must be a rank, an integer >= 1 (lower runs sooner), or null',
|
|
170
194
|
plan: (v) => nullable(isText)(v) || 'plan must be a path or null',
|
|
171
195
|
tune_count: (v) => (Number.isInteger(v) && v >= 0) || 'tune_count must be an integer >= 0',
|
|
196
|
+
plan_cycle: (v) => (Number.isInteger(v) && v >= 1) || 'plan_cycle must be an integer >= 1',
|
|
197
|
+
stall: (v) => stallProblem(v) ?? true,
|
|
172
198
|
severity: (v) =>
|
|
173
199
|
nullable((x) => SEVERITIES.includes(x))(v) || `severity must be ${SEVERITIES.join(' | ')}`,
|
|
174
200
|
blocked: (v) => nullable(isText)(v) || 'blocked must be text or null',
|
package/lib/verify.js
CHANGED
|
@@ -51,7 +51,7 @@ const signal = (p, sig) => {
|
|
|
51
51
|
* shortcut: a grandchild whose parent exited before the walk is init's and is not found; a
|
|
52
52
|
* process group of its own per command would catch it, at the cost of the harness's group kill.
|
|
53
53
|
*/
|
|
54
|
-
function killTree(pid) {
|
|
54
|
+
export function killTree(pid) {
|
|
55
55
|
if (process.platform === 'win32') {
|
|
56
56
|
spawnSync('taskkill', ['/pid', String(pid), '/T', '/F'], { stdio: 'ignore' });
|
|
57
57
|
|
|
@@ -81,7 +81,7 @@ function stopChildren(doomed) {
|
|
|
81
81
|
* Run `cmd` in a shell; past `ms` (0: never) it is killed with its whole tree. `exit`, not
|
|
82
82
|
* `close`: a helper the command left running may hold the inherited stdio open.
|
|
83
83
|
*/
|
|
84
|
-
function runCommand(cmd, cwd, stdio, ms) {
|
|
84
|
+
export function runCommand(cmd, cwd, stdio, ms) {
|
|
85
85
|
return new Promise((resolve) => {
|
|
86
86
|
const child = spawn(cmd, { cwd, shell: true, stdio });
|
|
87
87
|
let timedOut = false;
|
|
@@ -118,7 +118,7 @@ export async function runDod(projectDir, config, key, stdio) {
|
|
|
118
118
|
// stdin is closed; a command that never ends (a hung engine, a watch mode) meets the timeout.
|
|
119
119
|
const minutes = config.dod_timeout_min ?? 0;
|
|
120
120
|
const problem = failureOf(
|
|
121
|
-
key
|
|
121
|
+
`dod.${key}`,
|
|
122
122
|
cmd,
|
|
123
123
|
minutes,
|
|
124
124
|
await runCommand(cmd, projectDir, stdio, minutes * 60000),
|
|
@@ -127,14 +127,14 @@ export async function runDod(projectDir, config, key, stdio) {
|
|
|
127
127
|
return { name: key, ok: !problem, problems: problem ? [problem] : [] };
|
|
128
128
|
}
|
|
129
129
|
|
|
130
|
-
/** Why a finished
|
|
131
|
-
function failureOf(
|
|
130
|
+
/** Why a finished command of the project's failed, or null when it passed. */
|
|
131
|
+
export function failureOf(name, cmd, minutes, res) {
|
|
132
132
|
if (res.timedOut)
|
|
133
|
-
return
|
|
133
|
+
return `${name} timed out after ${minutes} min (dod_timeout_min), killed: ${cmd}`;
|
|
134
134
|
if (res.status === 0) return null;
|
|
135
135
|
const why = res.error ? res.error.message : `exit ${res.status ?? res.signal}`;
|
|
136
136
|
|
|
137
|
-
return
|
|
137
|
+
return `${name} failed (${why}): ${cmd}`;
|
|
138
138
|
}
|
|
139
139
|
|
|
140
140
|
/**
|
package/lib/work-ops.js
CHANGED
|
@@ -56,6 +56,7 @@ import {
|
|
|
56
56
|
import { verdictDeferred } from './gates.js';
|
|
57
57
|
import { appendQuestions, questionsFile } from './questions.js';
|
|
58
58
|
import { refusal } from './refusal.js';
|
|
59
|
+
import { releaseBuild } from './play.js';
|
|
59
60
|
|
|
60
61
|
/**
|
|
61
62
|
* Options of a committed move; each move reads the ones it needs.
|
|
@@ -273,10 +274,16 @@ async function finish(m, key, tail, commit) {
|
|
|
273
274
|
// Its work is committed: what still lies loose is no longer the card's to carry.
|
|
274
275
|
if (move === 'submit' || move === 'close') leaveFolder(m.projectDir, String(m.item.data.id));
|
|
275
276
|
for (const fn of m.ran) fn();
|
|
277
|
+
// Its play has ended: the player stops and the snapshot goes. It never undoes the move.
|
|
278
|
+
if (move === 'verdict' || move === 'drop')
|
|
279
|
+
m.buildLeft = releaseBuild(m.projectDir, String(m.item.data.id));
|
|
276
280
|
|
|
277
281
|
return hash;
|
|
278
282
|
}
|
|
279
283
|
|
|
284
|
+
/** A snapshot its move could not delete: the report names it, a later sweep repeats it. */
|
|
285
|
+
const buildLeft = (m) => (m.buildLeft ? { build_left: m.buildLeft } : {});
|
|
286
|
+
|
|
280
287
|
/** A card's work waits on its branch: it has to come back before it can be judged. */
|
|
281
288
|
function needInFolder(m, item = m.item) {
|
|
282
289
|
const id = String(item.data.id);
|
|
@@ -869,7 +876,7 @@ async function tune(m, note) {
|
|
|
869
876
|
if (item.data.status === 'unplayed') unplay(m, item);
|
|
870
877
|
const body = note ? await upsertItemNote(item, 'tuning', note) : item.body;
|
|
871
878
|
const data = {
|
|
872
|
-
...without(item.data, 'frozen'),
|
|
879
|
+
...newCycle(without(item.data, 'frozen')),
|
|
873
880
|
status: 'ready',
|
|
874
881
|
tune_count: tunes + 1,
|
|
875
882
|
since: null,
|
|
@@ -877,6 +884,15 @@ async function tune(m, note) {
|
|
|
877
884
|
m.step(() => writeItem(item, data, body));
|
|
878
885
|
}
|
|
879
886
|
|
|
887
|
+
/**
|
|
888
|
+
* The card back to planning (Hold-Plan d12): a new planning cycle, so the passes before it no
|
|
889
|
+
* longer count, and the operator's answer to an old stall goes with them.
|
|
890
|
+
*/
|
|
891
|
+
const newCycle = (data) => ({
|
|
892
|
+
...without(data, 'stall'),
|
|
893
|
+
plan_cycle: Number(data.plan_cycle ?? 0) + 1,
|
|
894
|
+
});
|
|
895
|
+
|
|
880
896
|
/** keep | tune | kill on an item waiting for its verdict or unplayed (Methodology §5.4).
|
|
881
897
|
* @param {MoveOpts} [opts]
|
|
882
898
|
*/
|
|
@@ -894,7 +910,7 @@ async function verdictItemUnlocked(projectDir, id, verdict, opts = {}) {
|
|
|
894
910
|
const tail = `${verdict} ${id} → ${systems.join(',')}${played}`;
|
|
895
911
|
const hash = await finish(m, `verdict:${verdict}`, tail, commit);
|
|
896
912
|
|
|
897
|
-
return { verdict, id, systems, hash, removal };
|
|
913
|
+
return { verdict, id, systems, hash, removal, ...buildLeft(m) };
|
|
898
914
|
}
|
|
899
915
|
|
|
900
916
|
// What a milestone's keep may write: gcf/ as the gate reads it (no .metrics, which audit and
|
|
@@ -1018,8 +1034,9 @@ async function keepMilestoneUnlocked(projectDir, name, opts = {}) {
|
|
|
1018
1034
|
const message = `gcf(verdict): keep ${name} → ${order.join(', ')}${played}`;
|
|
1019
1035
|
const hash = commitPaths(projectDir, message, files, { key: 'verdict:keep', items: order });
|
|
1020
1036
|
for (const id of order) clearCard(projectDir, id);
|
|
1037
|
+
const left = order.map((id) => releaseBuild(projectDir, id)).filter(Boolean);
|
|
1021
1038
|
|
|
1022
|
-
return { milestone: name, ids: order, hash };
|
|
1039
|
+
return { milestone: name, ids: order, hash, ...(left.length ? { build_left: left } : {}) };
|
|
1023
1040
|
} catch (e) {
|
|
1024
1041
|
// Nothing kept: what the keep wrote back to HEAD (staged or not); the pack's own files keep
|
|
1025
1042
|
// the operator's edits on disk and in the index as they were.
|
|
@@ -1154,7 +1171,7 @@ async function unblockItemUnlocked(projectDir, id, opts = {}) {
|
|
|
1154
1171
|
const childDied = / child \S+ died/.test(String(m.item.data.blocked ?? ''));
|
|
1155
1172
|
const waits = m.item.data.type === 'feature' && childDied;
|
|
1156
1173
|
const data = {
|
|
1157
|
-
...without(m.item.data, 'blocked'),
|
|
1174
|
+
...newCycle(without(m.item.data, 'blocked')),
|
|
1158
1175
|
status: waits ? 'awaiting-decision' : 'ready',
|
|
1159
1176
|
since: waits ? headHash(projectDir) : null,
|
|
1160
1177
|
};
|
|
@@ -1283,12 +1300,66 @@ async function amendItemUnlocked(projectDir, id, opts = {}) {
|
|
|
1283
1300
|
if (dryRun) return { id, base: amendBase(m.item), title, text: amendableText(body), changes };
|
|
1284
1301
|
refuseAmendPointless(m.item, { asked, base: opts.base, changes, entry });
|
|
1285
1302
|
if (entry) carryEntry(m, entry, commit);
|
|
1286
|
-
const data = asked.title ? { ...m.item.data, title } : m.item.data;
|
|
1303
|
+
const data = newCycle(asked.title ? { ...m.item.data, title } : m.item.data);
|
|
1287
1304
|
m.step(() => writeItem(m.item, data, body));
|
|
1288
1305
|
|
|
1289
1306
|
return { id, changes, hash: await finish(m, 'amend', id, commit) };
|
|
1290
1307
|
}
|
|
1291
1308
|
|
|
1309
|
+
/**
|
|
1310
|
+
* The run's stop of planning that does not converge (Hold-Plan d16): blocked, with the blocking
|
|
1311
|
+
* counts of its passes kept in `stall`, for the operator's "more passes" or "implement as is".
|
|
1312
|
+
* @param {string} projectDir
|
|
1313
|
+
* @param {string} id
|
|
1314
|
+
* @param {{passes: number[], reason?: string, commit?: boolean}} opts
|
|
1315
|
+
*/
|
|
1316
|
+
async function stallItemUnlocked(projectDir, id, { passes, reason = '', commit = true }) {
|
|
1317
|
+
if (
|
|
1318
|
+
!Array.isArray(passes) ||
|
|
1319
|
+
!passes.length ||
|
|
1320
|
+
!passes.every((n) => Number.isInteger(n) && n >= 0)
|
|
1321
|
+
)
|
|
1322
|
+
throw new Error('--passes is the blocking count of each pass, e.g. 7,3,2,1');
|
|
1323
|
+
const m = await begin(projectDir, id, 'plan_stall');
|
|
1324
|
+
const why = String(reason).trim();
|
|
1325
|
+
// The operator's extra passes of this cycle stay: a second stall counts past them (review 3).
|
|
1326
|
+
const more = m.item.data.stall?.more;
|
|
1327
|
+
const stall = { passes, ...(why ? { reason: why } : {}), ...(more ? { more } : {}) };
|
|
1328
|
+
const blocked = `planning does not converge · ${passes.join(', ')}${why ? `: ${why}` : ''}`;
|
|
1329
|
+
const data = { ...m.item.data, status: 'blocked', blocked, since: headHash(projectDir), stall };
|
|
1330
|
+
m.step(() => writeItem(m.item, data));
|
|
1331
|
+
|
|
1332
|
+
return { id, stall, hash: await finish(m, 'plan_stall', id, commit) };
|
|
1333
|
+
}
|
|
1334
|
+
|
|
1335
|
+
/**
|
|
1336
|
+
* The operator's answer to a stall (Hold-Plan d16): `more` passes past the limit, or `accept`
|
|
1337
|
+
* the plan as it is; the card goes back to ready, its stall kept with the answer.
|
|
1338
|
+
* @param {string} projectDir
|
|
1339
|
+
* @param {string} id
|
|
1340
|
+
* @param {{more?: number, accept?: boolean, commit?: boolean}} opts
|
|
1341
|
+
*/
|
|
1342
|
+
async function answerStallUnlocked(projectDir, id, { more, accept = false, commit = true }) {
|
|
1343
|
+
const move = accept ? 'plan_accept' : 'plan_more';
|
|
1344
|
+
if (!accept && !(Number.isInteger(more) && more >= 1))
|
|
1345
|
+
throw new Error('more passes: a number, 1 or more');
|
|
1346
|
+
const m = await begin(projectDir, id, move);
|
|
1347
|
+
const stall = m.item.data.stall;
|
|
1348
|
+
if (!stall) throw new Error(`${id} is not stalled in planning: nothing to answer`);
|
|
1349
|
+
const answered = accept
|
|
1350
|
+
? { ...stall, accepted: true }
|
|
1351
|
+
: { ...stall, more: Number(stall.more ?? 0) + more };
|
|
1352
|
+
const data = {
|
|
1353
|
+
...without(m.item.data, 'blocked'),
|
|
1354
|
+
status: 'ready',
|
|
1355
|
+
since: null,
|
|
1356
|
+
stall: answered,
|
|
1357
|
+
};
|
|
1358
|
+
m.step(() => writeItem(m.item, data));
|
|
1359
|
+
|
|
1360
|
+
return { id, stall: answered, hash: await finish(m, move, id, commit) };
|
|
1361
|
+
}
|
|
1362
|
+
|
|
1292
1363
|
/** What a fix asks for, trimmed: a blank field is none, an over-long or broken one refused. */
|
|
1293
1364
|
function amendAsked(opts) {
|
|
1294
1365
|
const [text, add, title, from] = [opts.text, opts.add, opts.title, opts.from].map((v) =>
|
|
@@ -1352,7 +1423,9 @@ async function dropItemUnlocked(projectDir, id, opts = {}) {
|
|
|
1352
1423
|
: codeInMain(projectDir, m.item);
|
|
1353
1424
|
const removal = endToGraveyard(m, m.item, { reason, tags, removal: remove ?? shipped });
|
|
1354
1425
|
|
|
1355
|
-
|
|
1426
|
+
const hash = await finish(m, 'drop', id, commit);
|
|
1427
|
+
|
|
1428
|
+
return { id, hash, removal, ...buildLeft(m) };
|
|
1356
1429
|
}
|
|
1357
1430
|
|
|
1358
1431
|
/** The version and channel of a new item: well-formed, and only on a release. */
|
|
@@ -1909,6 +1982,12 @@ export const decideItem = (projectDir, id, choice, opts = {}) =>
|
|
|
1909
1982
|
/** @type {typeof blockItemUnlocked} */
|
|
1910
1983
|
export const blockItem = (projectDir, id, opts = {}) =>
|
|
1911
1984
|
locked(projectDir, opts.commit ?? true, () => blockItemUnlocked(projectDir, id, opts));
|
|
1985
|
+
/** @type {typeof stallItemUnlocked} */
|
|
1986
|
+
export const stallItem = (projectDir, id, opts) =>
|
|
1987
|
+
locked(projectDir, opts.commit ?? true, () => stallItemUnlocked(projectDir, id, opts));
|
|
1988
|
+
/** @type {typeof answerStallUnlocked} */
|
|
1989
|
+
export const answerStall = (projectDir, id, opts) =>
|
|
1990
|
+
locked(projectDir, opts.commit ?? true, () => answerStallUnlocked(projectDir, id, opts));
|
|
1912
1991
|
/** @type {typeof unblockItemUnlocked} */
|
|
1913
1992
|
export const unblockItem = (projectDir, id, opts = {}) =>
|
|
1914
1993
|
locked(projectDir, opts.commit ?? true, () => unblockItemUnlocked(projectDir, id, opts));
|
package/package.json
CHANGED
package/schemas/item.schema.json
CHANGED
|
@@ -55,6 +55,18 @@
|
|
|
55
55
|
"parallel": { "enum": ["ok", "serial"] },
|
|
56
56
|
"plan": { "$ref": "#/definitions/textOrNull" },
|
|
57
57
|
"tune_count": { "type": "integer", "minimum": 0 },
|
|
58
|
+
"plan_cycle": { "type": "integer", "minimum": 1 },
|
|
59
|
+
"stall": {
|
|
60
|
+
"type": "object",
|
|
61
|
+
"additionalProperties": false,
|
|
62
|
+
"required": ["passes"],
|
|
63
|
+
"properties": {
|
|
64
|
+
"passes": { "type": "array", "items": { "type": "integer", "minimum": 0 } },
|
|
65
|
+
"reason": { "type": "string" },
|
|
66
|
+
"more": { "type": "integer", "minimum": 1 },
|
|
67
|
+
"accepted": { "const": true }
|
|
68
|
+
}
|
|
69
|
+
},
|
|
58
70
|
"severity": {
|
|
59
71
|
"anyOf": [{ "type": "null" }, { "enum": ["critical", "high", "medium", "low"] }]
|
|
60
72
|
},
|
|
@@ -35,7 +35,8 @@ workflow:
|
|
|
35
35
|
9. draft `PILLARS.md` by the interview in the `gcf-init` skill, steps 4..8, and do not restate that interview here
|
|
36
36
|
10. run `npx --yes cnlp-kit check` (it covers the systems docs and PILLARS of `cnlp.config.json` and `GLOSSARY.md`, not design units), then `ai-factory gcf lint` over each new systems doc, then `ai-factory gcf index`
|
|
37
37
|
11. ask the human to run `ai-factory gcf hooks-install`; when it refuses over a foreign pre-commit, hand them the chain line it prints
|
|
38
|
-
12.
|
|
38
|
+
12. when the project says how its game builds and starts, ask the human to record it with `ai-factory gcf playtest setup`: an output folder git ignores, and a target per place to play
|
|
39
|
+
13. state the next step: an old design document goes through `/gcf-ingest` into `gcf/design/`, new work starts at `/gcf-card`
|
|
39
40
|
|
|
40
41
|
invocation:
|
|
41
42
|
- run once, when a project that already has code adopts GCF
|
package/skills/gcf-chat/SKILL.md
CHANGED
|
@@ -14,7 +14,7 @@ purpose:
|
|
|
14
14
|
|
|
15
15
|
inputs:
|
|
16
16
|
- the human's messages, one turn each
|
|
17
|
-
- the thread's context file when the thread is bound to an item: the paths of the item's file, its plan, its run's log and run chat, its commits
|
|
17
|
+
- the thread's context file when the thread is bound to an item: the paths of the item's file, its plan, its run's log and run chat, its commits, its build to play
|
|
18
18
|
|
|
19
19
|
preconditions:
|
|
20
20
|
- `gcf/` exists and `ai-factory gcf board --json` runs
|
|
@@ -38,6 +38,7 @@ forbidden_behaviors:
|
|
|
38
38
|
- do not answer from memory what a file says: read the file, then answer
|
|
39
39
|
- do not ask again for a move the human refused: say what it would have done and leave it
|
|
40
40
|
- do not read the board's own folder: it holds the human's token
|
|
41
|
+
- do not ask the human to build or start the game by hand, and do not say another agent did the work: the context file says whether a build exists and what opens it
|
|
41
42
|
|
|
42
43
|
workflow:
|
|
43
44
|
1. read `gcf/INDEX.md`, then run `ai-factory gcf board --json` for the phase, the items by status and the inbox
|
|
@@ -52,8 +53,10 @@ workflow:
|
|
|
52
53
|
10. a move the human asks for, or one the talk shows is due, that has a `propose_<move>` tool: call it with the `id` of the item, inbox entry or question it acts on, and say why in one line; name an item by its title with the id in brackets
|
|
53
54
|
11. a kill, a no or a wontfix: its reason is the human's words; the graveyard keeps it, and the move does not go without it
|
|
54
55
|
12. an open D1 question the talk answers: call `propose_question_answer` with its id and the human's words, or your draft when the human asks for one
|
|
55
|
-
13.
|
|
56
|
-
14.
|
|
56
|
+
13. an item to play: say from the context file whether its build exists, of which commit, and where it plays; call `propose_play` with its `id` and a `target`: the human's click starts it and opens it, and the verdict stops it
|
|
57
|
+
14. the context file says no `play:` is set up and the project's `AGENTS.md` says how the game builds and starts: call `propose_play_setup` with those commands; say what is missing when it does not say
|
|
58
|
+
15. another move the human asks for: run its `ai-factory gcf` command; the human approves it on the card, or refuses it
|
|
59
|
+
16. say in one line what changed, or that nothing did
|
|
57
60
|
|
|
58
61
|
invocation:
|
|
59
62
|
- run at the start of a project chat thread the board opens, and when the user types `/gcf-chat`
|
|
@@ -21,6 +21,10 @@ forbidden_behaviors:
|
|
|
21
21
|
- do not run `keep` when the human has not answered the item's miss_criterion question
|
|
22
22
|
- do not hold a keep for a play condition: the human decides where to play; remind once of a line of `platforms` not played, then take the answer
|
|
23
23
|
- do not edit systems docs, `LIVE.md`, history or graveyard by hand: the commands own them
|
|
24
|
+
- do not stop the player or delete the card's build: the verdict does both, and a build other cards on the same code hold stays for them
|
|
25
|
+
- `build_left` in the verdict's report names a build a held file kept; a later `ai-factory gcf playtest status` removes it
|
|
26
|
+
- do not answer that the human cannot play for want of a build: the card's Play button builds it first
|
|
27
|
+
- when the human asks for a build, run `ai-factory gcf playtest build <id>`, or `--main` for the checkout as it is
|
|
24
28
|
- a tune note triage left in the inbox for the item goes into `--note`; after the verdict run `ai-factory gcf inbox drop <in-id>`, not before
|
|
25
29
|
|
|
26
30
|
workflow:
|
|
@@ -18,6 +18,9 @@ gcf_work:
|
|
|
18
18
|
- before planning an item, run `ai-factory gcf context <id>` and read only the files it lists under `gcf/`
|
|
19
19
|
- an item's plan is in the plan form: blocks `context:`, `decisions:` (records `id`, `pick`, `why`), `tasks:` (`- [ ] t1 <action> (d1)`), `pillar_check:`, `verification:`, one idea a line
|
|
20
20
|
- `ai-factory gcf plan check <id>` lists the plan's form problems as `format:` lines: fix them, they never block
|
|
21
|
+
- record each improve pass of a plan with `ai-factory gcf plan pass <id> --blocking <n> --polish <m> --json`; its verdict decides: continue, converged or stalled
|
|
22
|
+
- a `stalled` verdict: `ai-factory gcf plan stall <id> --passes <counts>` blocks the card; `gcf plan more` and `gcf plan accept` answer it, and they are the human's
|
|
23
|
+
- a harness run plans in one session and implements in a fresh one (`GCF_RUN_PHASE`); in your own terminal stop after planning unless the human asked for `--through`
|
|
21
24
|
- drive a ready item with the gcf-run skill when the project has gcf-harness-aif-ext and the agent is Claude Code (a batch at once: `ai-factory gcf-harness run <ids...>`), otherwise with aif-plan and aif-implement
|
|
22
25
|
- answer a question about how the runs go (the share that reached their move, cost, plan checks, DoD attempts, guard firings) with `ai-factory gcf-harness metrics`
|
|
23
26
|
- answer a question about past runs (an item's results, what it ran on, its cost, the part of its log a run wrote) with `ai-factory gcf-harness runs [--item <id>] --json`
|
|
@@ -37,6 +40,14 @@ gcf_work:
|
|
|
37
40
|
- `ai-factory gcf design check` names each hit of an avoided word in design and items as M4, `npx --yes cnlp-kit check` the rest
|
|
38
41
|
- an `avoid:` lists only a word wrong in every document: a word with another use stays out, a phrase ("tile hand") beats a bare word
|
|
39
42
|
- the human plays from `ai-factory gcf playtest session`; each free note from that play goes to `ai-factory gcf inbox add --category playtest "<note>"`, in the human's words
|
|
43
|
+
- with `play:` in `gcf/config.yml` the harness builds a card that waits for its verdict at the end of its run, into `.gcf-session/snaps/`, where later work does not touch it
|
|
44
|
+
- a build is one per code: cards on the same code share it, and a verdict removes it only when no other card holds it
|
|
45
|
+
- the board's Play button builds the card when it has no build yet, then starts it on a target of `play:`; the card's verdict stops its player
|
|
46
|
+
- Play main does the same for the checkout as it is, hand edits too; `ai-factory gcf playtest status` names the targets and the running player
|
|
47
|
+
- how the game builds and starts is the human's to accept: find it in the project (this file, its build and serve scripts) and propose it with `propose_play_setup`
|
|
48
|
+
- do not ask the human for the build or start commands: the project holds them
|
|
49
|
+
- a project with no command that builds into a folder git ignores, or none that starts it from there, gets a tech card from you that adds both and names them here
|
|
50
|
+
- do not answer that the game cannot be built: offer the card's button with `propose_play`, or the checkout's with `propose_play_main`
|
|
40
51
|
- a release item carries `version:` and `channel:` (`item new --title "<title>" --type release --release <v> --channel <c>`): its end writes the `release:` block of `gcf/LIVE.md`
|
|
41
52
|
- `item new` and `take` refuse a type the current phase does not take: run `ai-factory gcf phase` and bring the refusal to the human
|
|
42
53
|
- an item's milestone (`item new --milestone <name>`) is a `name` of the `milestones` in `gcf/game.md`, as a unit's: `item new` refuses another; a new milestone is a change of the vision, for the human (the gcf-vision skill)
|
|
@@ -46,6 +57,8 @@ gcf_work:
|
|
|
46
57
|
- the lines of `platforms` in `gcf/game.md` are where the human can play the game; an item may narrow them in `play_on:`; they are a hint for the human, never a condition of a move
|
|
47
58
|
- the stops that wait for the human are the `gates:` of `gcf/config.yml` (`milestone`, `verdict`, `decision`, `question`) and each card's `skip_gates:`, both the human's (`config set`, `item gates`); the core applies them itself
|
|
48
59
|
- the board's autopilot starts the runs and the card sessions (`ai-factory gcf-harness card`) by itself and stops when a milestone is built for the human to play; an agent starts neither
|
|
60
|
+
- `ai-factory gcf-harness hold <id>` and `hold --project` are the human's: a held session hands over at its next call, and an agent holds nothing
|
|
61
|
+
- the queue and the autopilot stand at the quota's reserve (`quota_reserve_pct` of `~/.gcf/settings.json`); the human's own Run does not
|
|
49
62
|
- an item the human wants run on a given model or effort gets `item new --title "<title>" --model <m> --effort <e>`: the harness run passes both to the agent
|
|
50
63
|
- an existing item changes with `ai-factory gcf item agent <id> --model <m> --effort <e>` (`default` takes one off), never a hand edit; its next run takes them
|
|
51
64
|
- an item without its own runs on the project's `agent.model` and `agent.effort` of `gcf/config.yml`, a setting of the human, and without those on opus, effort high
|
|
@@ -65,7 +78,7 @@ gcf_work:
|
|
|
65
78
|
- write the body of an item that is not a design unit in `language.artifacts` of `.ai-factory/config.yaml`
|
|
66
79
|
- write in English whatever lands in a checked document: `gcf/design/`, `gcf/systems/`, `GLOSSARY.md`, `gcf/PILLARS.md`, `gcf/LIVE.md`, the body of a design unit's item but its `tuning:` and `notes:`, an item's `live:` summary
|
|
67
80
|
- an answer that moves into a unit's slot goes there in English
|
|
68
|
-
- do not translate keys, statuses, ids, commands, `TBD`, `answer: q-NNN`, `## Handoff`, a `quote:` (it is verbatim from the GDD) or the fixed start of a block reason (`needs permission:`, `
|
|
81
|
+
- do not translate keys, statuses, ids, commands, `TBD`, `answer: q-NNN`, `## Handoff`, a `quote:` (it is verbatim from the GDD) or the fixed start of a block reason (`needs permission:`, `planning does not converge`, `waits for`)
|
|
69
82
|
- a D1 record that carries the human's `answer:` goes into the slot of each unit it blocks, with `answer: q-NNN`, and then leaves `gcf/open-questions.md`
|
|
70
83
|
- a pillar changes only on the human's word; its short `name:` is what the human knows it by, and its id comes from the name
|
|
71
84
|
- a new name saved with `design save` renames the id in every file that cites it
|
|
@@ -97,7 +110,9 @@ gcf_forbidden:
|
|
|
97
110
|
- do not edit `status:`, `frozen:`, `gcf/LIVE.md`, `gcf/history.md`, `gcf/graveyard.md`, `gcf/inbox/` or `gcf/INDEX.md` by hand: the commands own them
|
|
98
111
|
- do not give a verdict: `verdict` belongs to the human, through the gcf-verdict skill; nor a decision, but `go` or `no` of the spike you drive when the gates say `decision: agent`
|
|
99
112
|
- the core refuses the human's moves to a harness run and a board chat: bring the move to the human, or block the item with the question
|
|
100
|
-
- those moves are `verdict`, `decide`, `drop` of a work item, `unblock`, `item amend`, `question answer`, `config set`, `permissions`, `phase next`, `pillar`, `hooks-install`, `edits commit`, `edits discard`, `changes commit`
|
|
113
|
+
- those moves are `verdict`, `decide`, `drop` of a work item, `unblock`, `item amend`, `question answer`, `config set`, `playtest setup`, `permissions`, `phase next`, `pillar`, `hooks-install`, `edits commit`, `edits discard`, `changes commit`
|
|
114
|
+
- a run's agent does not build the game to play nor start a player: the harness builds it at the run's end, and `dod.build` only checks the code
|
|
115
|
+
- in the project chat, when the human asks for a build, run `ai-factory gcf playtest build <id>` or `ai-factory gcf playtest build --main` yourself
|
|
101
116
|
- do not answer a `TBD` of a design unit yourself: ask the human and offer your draft as the proposed answer
|
|
102
117
|
- do not run `ai-factory gcf phase next`: the phase moves on the human's word only
|
|
103
118
|
- do not change what agent runs may do: `ai-factory gcf permissions`, its deny groups and the board's YOLO belong to the human
|
package/templates/config.yml
CHANGED
|
@@ -25,6 +25,14 @@ auto_compact_pct: 0
|
|
|
25
25
|
# chat:
|
|
26
26
|
# ask: d1
|
|
27
27
|
# answer_timeout_min: 15
|
|
28
|
+
# The plan's improve passes (Hold-Plan d17): when a pass still finds blocking issues, pass `at`
|
|
29
|
+
# goes to an outside reviewer, read-only (Codex CLI); without it, or when it fails, Claude makes
|
|
30
|
+
# the pass. Uncomment to change (agent: none turns it off):
|
|
31
|
+
# plan_review:
|
|
32
|
+
# agent: codex
|
|
33
|
+
# model: gpt-6-astra
|
|
34
|
+
# effort: medium
|
|
35
|
+
# at: 3
|
|
28
36
|
# Lessons (Methodology §5.2.2): at the end of each session on an item its agent says what got in
|
|
29
37
|
# its way, into the inbox. `ai-factory gcf lessons prompt <id>` prints the questions. Uncomment to
|
|
30
38
|
# turn them off, to ask what the project's template should learn, or to add questions:
|
|
@@ -45,3 +53,14 @@ auto_compact_pct: 0
|
|
|
45
53
|
dod:
|
|
46
54
|
test:
|
|
47
55
|
build:
|
|
56
|
+
# How to build and start the game to play a finished card (ai-factory gcf playtest setup): a build
|
|
57
|
+
# a card keeps for itself until its verdict. `output` is git-ignored, inside the project; `{dir}`
|
|
58
|
+
# is that card's build, `{port}` a free port, `{lan}` this machine's address.
|
|
59
|
+
# A name with a space in it: "{dir}/My Game.exe".
|
|
60
|
+
# play:
|
|
61
|
+
# build: <the command that builds the game>
|
|
62
|
+
# output: <the folder it builds into>
|
|
63
|
+
# targets:
|
|
64
|
+
# browser:
|
|
65
|
+
# start: <a command that serves {dir} on {port}>
|
|
66
|
+
# open: http://localhost:{port}
|