gcf-aif-ext 0.10.2 → 0.12.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 +23 -4
- package/commands/gcf.js +140 -60
- package/extension.json +3 -2
- package/lib/agent-permissions.js +125 -20
- package/lib/audit-core.js +46 -6
- package/lib/board.js +6 -2
- package/lib/config-set.js +28 -2
- package/lib/context.js +24 -1
- package/lib/domain.js +81 -5
- package/lib/gcf-paths.js +26 -2
- package/lib/git.js +11 -2
- package/lib/inbox.js +265 -108
- package/lib/index-gen.js +7 -4
- package/lib/integrate.js +45 -8
- package/lib/lessons.js +31 -15
- package/lib/plan-check.js +22 -13
- package/lib/safe-path.js +2 -1
- package/lib/transitions.js +2 -0
- package/lib/unit-ops.js +1 -1
- package/lib/validate-item.js +7 -1
- package/lib/work-ops.js +141 -14
- package/package.json +1 -1
- package/skills/gcf-chat/SKILL.md +40 -0
- package/skills/gcf-triage/SKILL.md +10 -8
- package/templates/agents-block.md +12 -4
- package/templates/config.yml +7 -0
package/lib/lessons.js
CHANGED
|
@@ -7,7 +7,7 @@ import { readFile } from 'node:fs/promises';
|
|
|
7
7
|
import path from 'node:path';
|
|
8
8
|
import { uiLanguage } from './aif-config.js';
|
|
9
9
|
import { readRawConfig } from './gcf-paths.js';
|
|
10
|
-
import {
|
|
10
|
+
import { planAdd } from './inbox.js';
|
|
11
11
|
import { isValidId } from './id.js';
|
|
12
12
|
|
|
13
13
|
export const KINDS = ['tool', 'rules', 'framework', 'template', 'other'];
|
|
@@ -104,30 +104,46 @@ export async function lessonsPrompt(projectDir, id, { reply = 'cli' } = {}) {
|
|
|
104
104
|
/** A lesson as the agent gave it, checked: `{kind, text, where}`. */
|
|
105
105
|
function lessonOf(raw, i) {
|
|
106
106
|
const kind = KINDS.includes(raw?.kind) ? raw.kind : 'other';
|
|
107
|
-
const text = String(raw?.text ?? '')
|
|
108
|
-
.replace(/\s+/g, ' ')
|
|
109
|
-
.trim();
|
|
107
|
+
const text = String(raw?.text ?? '').trim();
|
|
110
108
|
if (!text) throw new Error(`lesson ${i + 1} has no text`);
|
|
111
109
|
const where = raw?.where ? String(raw.where).replace(/\s+/g, ' ').trim() : '';
|
|
112
110
|
|
|
113
|
-
// An
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
return { kind, text: full };
|
|
111
|
+
// An entry holds lines: the place it is about goes on the last one.
|
|
112
|
+
return { kind, text: where ? `${text}\n\n${where}` : text };
|
|
117
113
|
}
|
|
118
114
|
|
|
119
115
|
/**
|
|
120
|
-
*
|
|
121
|
-
* KINDS reads as other
|
|
116
|
+
* The plan that records `lessons` of item `id` as inbox entries; `{kind, text, where?}` each, a
|
|
117
|
+
* kind outside KINDS reads as other: the entries, their files, and how to write them.
|
|
122
118
|
*/
|
|
123
|
-
export
|
|
119
|
+
export function planLessons(root, id, lessons, now = new Date().toISOString()) {
|
|
124
120
|
if (!isValidId(id)) throw new Error(`${id} is not an item id`);
|
|
125
121
|
if (!Array.isArray(lessons)) throw new Error('lessons must be a JSON array');
|
|
126
|
-
const
|
|
127
|
-
const
|
|
128
|
-
|
|
122
|
+
const taken = new Set();
|
|
123
|
+
const plans = lessons.map(lessonOf).map((l, i) => {
|
|
124
|
+
// A millisecond apart: the inbox lists them in the order the agent gave them.
|
|
125
|
+
const at = new Date(Date.parse(now) + i).toISOString();
|
|
126
|
+
const p = planAdd(root, l.text, `lesson:${l.kind}:${id}`, { now: at, taken });
|
|
127
|
+
taken.add(p.entry.id);
|
|
128
|
+
|
|
129
|
+
return p;
|
|
130
|
+
});
|
|
131
|
+
|
|
132
|
+
return {
|
|
133
|
+
entries: plans.map((p) => p.entry),
|
|
134
|
+
files: plans.flatMap((p) => p.files),
|
|
135
|
+
apply: async () => {
|
|
136
|
+
for (const p of plans) await p.apply();
|
|
137
|
+
},
|
|
138
|
+
};
|
|
139
|
+
}
|
|
140
|
+
|
|
141
|
+
/** Record `lessons` of item `id` as inbox entries at once (planLessons); returns the entries. */
|
|
142
|
+
export async function addLessons(root, id, lessons) {
|
|
143
|
+
const plan = planLessons(root, id, lessons);
|
|
144
|
+
await plan.apply();
|
|
129
145
|
|
|
130
|
-
return
|
|
146
|
+
return plan.entries;
|
|
131
147
|
}
|
|
132
148
|
|
|
133
149
|
/** The lessons of a JSON file: an array, as the harness writes it. */
|
package/lib/plan-check.js
CHANGED
|
@@ -1,27 +1,36 @@
|
|
|
1
1
|
// `gcf plan check <id>` (Methodology §5.2.1): the deterministic check after each improve pass —
|
|
2
2
|
// the plan exists, it holds task checkboxes, and the item's readset fits the context budget.
|
|
3
3
|
// Whether the plan is any good is the improve passes' job; this only says it is usable.
|
|
4
|
-
import {
|
|
5
|
-
import { existsSync } from 'node:fs';
|
|
4
|
+
import { existsSync, readFileSync } from 'node:fs';
|
|
6
5
|
import path from 'node:path';
|
|
7
6
|
import { buildLedger } from './ledger.js';
|
|
8
7
|
import { buildContext } from './context.js';
|
|
9
8
|
|
|
9
|
+
/**
|
|
10
|
+
* An item's plan and its task checkboxes: `{plan, tasks, done}`, `tasks` null when there is no
|
|
11
|
+
* plan file. `data` is the item's frontmatter.
|
|
12
|
+
*/
|
|
13
|
+
export function planTicks(projectDir, data) {
|
|
14
|
+
const plan = data.plan ?? `.ai-factory/plans/${data.id}.md`;
|
|
15
|
+
const file = path.resolve(projectDir, plan);
|
|
16
|
+
if (!existsSync(file)) return { plan, tasks: null, done: 0 };
|
|
17
|
+
const text = readFileSync(file, 'utf8');
|
|
18
|
+
|
|
19
|
+
return {
|
|
20
|
+
plan,
|
|
21
|
+
tasks: (text.match(/^\s*- \[[ xX]\] /gm) ?? []).length,
|
|
22
|
+
done: (text.match(/^\s*- \[[xX]\] /gm) ?? []).length,
|
|
23
|
+
};
|
|
24
|
+
}
|
|
25
|
+
|
|
10
26
|
export async function planCheck(projectDir, id) {
|
|
11
27
|
const item = (await buildLedger(projectDir)).item(id);
|
|
12
28
|
if (!item) throw new Error(`${id} is not a work item of gcf/work/`);
|
|
13
|
-
const plan = item.data
|
|
14
|
-
const
|
|
29
|
+
const { plan, tasks: found, done } = planTicks(projectDir, { ...item.data, id });
|
|
30
|
+
const tasks = found ?? 0;
|
|
15
31
|
const problems = [];
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
if (!existsSync(file)) problems.push(`no plan at ${plan}`);
|
|
19
|
-
else {
|
|
20
|
-
const text = await readFile(file, 'utf8');
|
|
21
|
-
tasks = (text.match(/^\s*- \[[ xX]\] /gm) ?? []).length;
|
|
22
|
-
done = (text.match(/^\s*- \[[xX]\] /gm) ?? []).length;
|
|
23
|
-
if (!tasks) problems.push(`${plan} has no task checkboxes (- [ ] …)`);
|
|
24
|
-
}
|
|
32
|
+
if (found === null) problems.push(`no plan at ${plan}`);
|
|
33
|
+
else if (!tasks) problems.push(`${plan} has no task checkboxes (- [ ] …)`);
|
|
25
34
|
|
|
26
35
|
const ctx = await buildContext(projectDir, id);
|
|
27
36
|
if (ctx.over_budget)
|
package/lib/safe-path.js
CHANGED
|
@@ -62,7 +62,8 @@ export async function withFileRollback(files, action, { gitCwd = null } = {}) {
|
|
|
62
62
|
const index = gitCwd ? snapshotIndex(gitCwd, unique) : null;
|
|
63
63
|
for (const file of unique) {
|
|
64
64
|
try {
|
|
65
|
-
|
|
65
|
+
// Bytes, not text: a picture comes back as it was.
|
|
66
|
+
snapshots.push([file, await readFile(file)]);
|
|
66
67
|
} catch (err) {
|
|
67
68
|
if (err.code !== 'ENOENT') throw err;
|
|
68
69
|
snapshots.push([file, null]);
|
package/lib/transitions.js
CHANGED
|
@@ -30,6 +30,8 @@ const FROM = {
|
|
|
30
30
|
drop: STORED,
|
|
31
31
|
// What it waits for may change at any status; the core refuses an unknown id and a cycle.
|
|
32
32
|
depends: STORED,
|
|
33
|
+
// A file given to the item (a chat image) changes no status.
|
|
34
|
+
attach: STORED,
|
|
33
35
|
};
|
|
34
36
|
|
|
35
37
|
/** Every move an item may be offered, in the board's order. */
|
package/lib/unit-ops.js
CHANGED
|
@@ -233,7 +233,7 @@ function uncommitted(projectDir, file) {
|
|
|
233
233
|
* @param {{files: string[], mutate: () => Promise<void>, commit: boolean, inputs?: string[]}} move
|
|
234
234
|
*/
|
|
235
235
|
/** A worktree of the integrator (Methodology §7): its gcf/ state is main's to move. */
|
|
236
|
-
const onWorkBranch = (projectDir) =>
|
|
236
|
+
export const onWorkBranch = (projectDir) =>
|
|
237
237
|
/^work\//.test(
|
|
238
238
|
spawnSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], {
|
|
239
239
|
cwd: projectDir,
|
package/lib/validate-item.js
CHANGED
|
@@ -77,7 +77,11 @@ const isSlug = (v) => typeof v === 'string' && SLUG.test(v);
|
|
|
77
77
|
const slugList = (v) => Array.isArray(v) && v.every(isSlug);
|
|
78
78
|
const isText = (v) => typeof v === 'string' && v.trim().length > 0;
|
|
79
79
|
const nullable = (check) => (v) => v === null || v === undefined || check(v);
|
|
80
|
-
|
|
80
|
+
// The exact form (fix D): an agent read the old message and guessed its way to the shape.
|
|
81
|
+
const LIVE_SHAPE =
|
|
82
|
+
'live must be {none: "<why it changes no capability>"} or {changes: [{id: <capability ' +
|
|
83
|
+
'slug>, change: added | modified | removed, summary: "<at most two sentences>"}]} with at ' +
|
|
84
|
+
'least one change; summary is not needed for removed';
|
|
81
85
|
|
|
82
86
|
/** At most two sentences and 250 characters: a table of contents, not a description. */
|
|
83
87
|
export function summaryProblem(s) {
|
|
@@ -245,6 +249,8 @@ export function validateUntil(body) {
|
|
|
245
249
|
const errors = [];
|
|
246
250
|
const lines = String(body).split('\n');
|
|
247
251
|
lines.forEach((line, i) => {
|
|
252
|
+
// A quoted line (an inbox entry's text in an item's note:) holds no annotation of its own.
|
|
253
|
+
if (line.startsWith('>')) return;
|
|
248
254
|
for (const m of line.matchAll(/\[until:[^\]]*\]/g)) {
|
|
249
255
|
if (!UNTIL_OK.test(m[0]))
|
|
250
256
|
errors.push(
|
package/lib/work-ops.js
CHANGED
|
@@ -3,8 +3,8 @@
|
|
|
3
3
|
// that carries every file it touched: the item, history or graveyard, LIVE.md, the systems
|
|
4
4
|
// docs, the parent feature, a removal item, the archived plan. Atomic: a refused commit rolls
|
|
5
5
|
// every file back.
|
|
6
|
-
import { readFile, unlink } from 'node:fs/promises';
|
|
7
|
-
import { existsSync } from 'node:fs';
|
|
6
|
+
import { copyFile, mkdir, readFile, unlink } from 'node:fs/promises';
|
|
7
|
+
import { existsSync, lstatSync, readdirSync } from 'node:fs';
|
|
8
8
|
import { spawnSync } from 'node:child_process';
|
|
9
9
|
import { createHash } from 'node:crypto';
|
|
10
10
|
import path from 'node:path';
|
|
@@ -15,7 +15,7 @@ import { atomicWrite, resolveInside } from './safe-path.js';
|
|
|
15
15
|
import { allowedFrom, decisionFits, FEATURE_ONLY, fromOf } from './transitions.js';
|
|
16
16
|
import { ITEM_TYPES, DEFAULT_GATE, GATES, SEVERITIES, UNIT_ITEM_TYPES } from './validate-item.js';
|
|
17
17
|
import { isValidId } from './id.js';
|
|
18
|
-
import { commitMove, addConstraints } from './unit-ops.js';
|
|
18
|
+
import { commitMove, addConstraints, onWorkBranch } from './unit-ops.js';
|
|
19
19
|
import { openSystemDoc, upsertBlock } from './systems-doc.js';
|
|
20
20
|
import {
|
|
21
21
|
collapseLines,
|
|
@@ -35,12 +35,13 @@ import {
|
|
|
35
35
|
revertDelta,
|
|
36
36
|
knownIssueOf,
|
|
37
37
|
} from './live.js';
|
|
38
|
-
import {
|
|
38
|
+
import { planTake, untrackedEntries } from './inbox.js';
|
|
39
39
|
import { cycleMessage, dependsGraph, pathTo } from './design-check.js';
|
|
40
40
|
import { refuseByPhase } from './phase.js';
|
|
41
41
|
import { locked, runHolder } from './main-lock.js';
|
|
42
42
|
import { dropAgentSession, ownsMark, releaseSession, sessionActive } from './session-mark.js';
|
|
43
43
|
import { dropStamp, unverifiedProblem } from './verify-stamp.js';
|
|
44
|
+
import { planTicks } from './plan-check.js';
|
|
44
45
|
|
|
45
46
|
/**
|
|
46
47
|
* Options of a committed move; each move reads the ones it needs.
|
|
@@ -263,8 +264,27 @@ function verifyGateProblem(projectDir, id, type) {
|
|
|
263
264
|
}
|
|
264
265
|
}
|
|
265
266
|
|
|
266
|
-
/**
|
|
267
|
-
|
|
267
|
+
/**
|
|
268
|
+
* `close` and `submit` (AD-50), from a command and from the integrator alike: every task of the
|
|
269
|
+
* item's plan ticked, unless the human says why not (`unticked`, written into the move's
|
|
270
|
+
* commit). An item with no plan and a feature are not checked; the check trusts the ticks, not
|
|
271
|
+
* the agent's words. The integrator turns the refusal into a block.
|
|
272
|
+
*/
|
|
273
|
+
function needTicked(m, opts) {
|
|
274
|
+
if (opts.unticked || m.item.data.type === 'feature') return;
|
|
275
|
+
const id = String(m.item.data.id);
|
|
276
|
+
const { tasks, done } = planTicks(m.projectDir, { ...m.item.data, id });
|
|
277
|
+
if (tasks !== null && done < tasks)
|
|
278
|
+
throw new Error(
|
|
279
|
+
`${id}: plan tasks not ticked: ${tasks - done} of ${tasks} — tick what is done, or block ` +
|
|
280
|
+
'the item',
|
|
281
|
+
);
|
|
282
|
+
}
|
|
283
|
+
|
|
284
|
+
/** The commit's tail of a move made without a green verify, or with tasks left unticked. */
|
|
285
|
+
const unverifiedTail = (opts) =>
|
|
286
|
+
(opts.unverified ? ` (unverified: ${opts.unverified})` : '') +
|
|
287
|
+
(opts.unticked ? ` (unticked: ${opts.unticked})` : '');
|
|
268
288
|
|
|
269
289
|
const writeItem = (item, data, body = item.body) => atomicWrite(item.file, serialize(data, body));
|
|
270
290
|
|
|
@@ -511,6 +531,7 @@ async function submitItemUnlocked(projectDir, id, opts = {}) {
|
|
|
511
531
|
if (m.item.data.gate === 'auto')
|
|
512
532
|
throw new Error(`${id} has gate auto: nobody waits for it — close it with gcf close ${id}`);
|
|
513
533
|
refuseOpenDepends(m, 'submit', { waiting: true });
|
|
534
|
+
needTicked(m, opts);
|
|
514
535
|
needVerified(m, opts);
|
|
515
536
|
const status = m.item.data.gate === 'verdict' ? 'awaiting-verdict' : 'awaiting-decision';
|
|
516
537
|
const data = { ...without(m.item.data, 'blocked'), status, since: headHash(projectDir) };
|
|
@@ -587,6 +608,7 @@ async function closeItemUnlocked(projectDir, id, opts = {}) {
|
|
|
587
608
|
if (m.item.data.gate !== 'auto')
|
|
588
609
|
throw new Error(`${id} has gate ${m.item.data.gate}: submit it, the operator closes it`);
|
|
589
610
|
refuseOpenDepends(m, 'close');
|
|
611
|
+
needTicked(m, opts);
|
|
590
612
|
needVerified(m, opts);
|
|
591
613
|
if (unplayed) closeUnplayed(m);
|
|
592
614
|
else await closeEnding(m, constraints);
|
|
@@ -926,8 +948,18 @@ function newItemText(spec, gate, since) {
|
|
|
926
948
|
...optionalFields(spec, gate, since),
|
|
927
949
|
created: spec.date ?? today(),
|
|
928
950
|
};
|
|
951
|
+
// `note`: the rest of the inbox entry it came from, quoted: a line of it that reads `key:`
|
|
952
|
+
// must not open a section of the item.
|
|
953
|
+
// An entry of one line leaves no note.
|
|
954
|
+
const quoted = spec.note
|
|
955
|
+
? spec.note
|
|
956
|
+
.split('\n')
|
|
957
|
+
.map((l) => (l ? `> ${l}` : '>'))
|
|
958
|
+
.join('\n')
|
|
959
|
+
: '';
|
|
929
960
|
const body =
|
|
930
|
-
`\nintent:\n- ${title
|
|
961
|
+
`\nintent:\n- ${title || 'TBD: what this item changes'}\n` +
|
|
962
|
+
(quoted ? `\nnote:\n${quoted}\n` : '') +
|
|
931
963
|
(type === 'bug' ? '\nrepro:\n- TBD: the steps that show the bug\n' : '');
|
|
932
964
|
|
|
933
965
|
return serialize(data, body);
|
|
@@ -1012,10 +1044,57 @@ async function setDependsUnlocked(projectDir, id, { add = [], remove = [], commi
|
|
|
1012
1044
|
return { id, depends, hash };
|
|
1013
1045
|
}
|
|
1014
1046
|
|
|
1047
|
+
// An attachment is a picture or a file the operator gave the item (a chat image, a reference).
|
|
1048
|
+
const ATTACH_MAX = 10 * 1024 * 1024;
|
|
1049
|
+
|
|
1050
|
+
/**
|
|
1051
|
+
* Copy `file` into `gcf/work/<id>/attachments/` under its own name (`-2`, `-3`… on a clash)
|
|
1052
|
+
* and commit it alone, `gcf(attach)`. A running item takes it too: the file is new, the item's
|
|
1053
|
+
* own file is not touched; but the commit gate refuses while `gcf/` has uncommitted changes
|
|
1054
|
+
* (a main-mode session's live: delta, an item made and not committed). A link or a file over
|
|
1055
|
+
* 10 MB is refused.
|
|
1056
|
+
*/
|
|
1057
|
+
async function attachItemUnlocked(projectDir, id, file, { commit = true } = {}) {
|
|
1058
|
+
const ledger = await buildLedger(projectDir);
|
|
1059
|
+
if (!ledger.item(id)) throw new Error(`${id} is not a work item`);
|
|
1060
|
+
const st = lstatOr(file);
|
|
1061
|
+
if (!st?.isFile()) throw new Error(`${file} is not a file (a link is refused)`);
|
|
1062
|
+
if (st.size > ATTACH_MAX) throw new Error(`${file} is over 10 MB`);
|
|
1063
|
+
const dir = path.join(gcfOf(projectDir), 'work', id, 'attachments');
|
|
1064
|
+
const { name, ext } = path.parse(file);
|
|
1065
|
+
let to = path.join(dir, `${name}${ext}`);
|
|
1066
|
+
for (let n = 2; existsSync(to); n++) to = path.join(dir, `${name}-${n}${ext}`);
|
|
1067
|
+
const hash = await commitMove(projectDir, `gcf(attach): ${id}`, {
|
|
1068
|
+
files: [to],
|
|
1069
|
+
mutate: async () => {
|
|
1070
|
+
await mkdir(dir, { recursive: true });
|
|
1071
|
+
await copyFile(file, to);
|
|
1072
|
+
},
|
|
1073
|
+
commit,
|
|
1074
|
+
});
|
|
1075
|
+
|
|
1076
|
+
return { id, file: path.relative(projectDir, to).replaceAll('\\', '/'), hash };
|
|
1077
|
+
}
|
|
1078
|
+
|
|
1079
|
+
function lstatOr(file) {
|
|
1080
|
+
try {
|
|
1081
|
+
return lstatSync(file);
|
|
1082
|
+
} catch {
|
|
1083
|
+
return null;
|
|
1084
|
+
}
|
|
1085
|
+
}
|
|
1086
|
+
|
|
1087
|
+
/** @type {typeof attachItemUnlocked} */
|
|
1088
|
+
export const attachItem = (projectDir, id, file, opts = {}) =>
|
|
1089
|
+
locked(projectDir, opts.commit ?? true, () => attachItemUnlocked(projectDir, id, file, opts));
|
|
1090
|
+
|
|
1015
1091
|
/**
|
|
1016
1092
|
* A new work item in ready (or blocked), no commit. A design unit enters work through `take`,
|
|
1017
1093
|
* not here: its body is the unit's slots. `from` erases the inbox entry it came from.
|
|
1018
1094
|
*/
|
|
1095
|
+
/** The longest note a new item takes (AD-39): a proposal's, or the operator's. */
|
|
1096
|
+
export const NOTE_MAX = 4000;
|
|
1097
|
+
|
|
1019
1098
|
async function newItemUnlocked(projectDir, spec) {
|
|
1020
1099
|
const root = gcfOf(projectDir);
|
|
1021
1100
|
const ledger = await buildLedger(projectDir);
|
|
@@ -1025,8 +1104,14 @@ async function newItemUnlocked(projectDir, spec) {
|
|
|
1025
1104
|
throw new Error(`reopens names ${spec.reopens}, which has not ended`);
|
|
1026
1105
|
const file = path.join(root, 'work', `${spec.id}.md`);
|
|
1027
1106
|
if (existsSync(file)) throw new Error(`gcf/work/${spec.id}.md already exists`);
|
|
1028
|
-
|
|
1029
|
-
|
|
1107
|
+
if (spec.note !== undefined && spec.note.length > NOTE_MAX)
|
|
1108
|
+
throw new Error(`the note is ${spec.note.length} characters: up to ${NOTE_MAX}`);
|
|
1109
|
+
const take = await takeEntry(projectDir, root, spec);
|
|
1110
|
+
// The note given first, then what the inbox entry it comes from says.
|
|
1111
|
+
const note = [spec.note, take.note].filter((x) => x?.trim()).join('\n\n') || undefined;
|
|
1112
|
+
const item = { ...spec, title: take.title, note };
|
|
1113
|
+
|
|
1114
|
+
const writes = [[file, newItemText(item, gate, headHash(projectDir))]];
|
|
1030
1115
|
if (spec.parent) {
|
|
1031
1116
|
const p = ledger.item(spec.parent);
|
|
1032
1117
|
if (!p || p.data.type !== 'feature')
|
|
@@ -1036,14 +1121,12 @@ async function newItemUnlocked(projectDir, spec) {
|
|
|
1036
1121
|
}
|
|
1037
1122
|
|
|
1038
1123
|
// `commit` is for a caller with no console to commit from, a board: a run starts from HEAD.
|
|
1039
|
-
// The inbox is raw input (merge=union): lines added without a commit ride along with it.
|
|
1040
|
-
const inbox = spec.from ? [path.join(root, 'inbox.md')] : [];
|
|
1041
1124
|
const hash = await commitMove(projectDir, `gcf(item): ${spec.id}`, {
|
|
1042
|
-
files: [...writes.map((w) => w[0]), ...
|
|
1043
|
-
inputs:
|
|
1125
|
+
files: [...writes.map((w) => w[0]), ...take.files],
|
|
1126
|
+
inputs: take.inputs,
|
|
1044
1127
|
mutate: async () => {
|
|
1045
1128
|
for (const [f, text] of writes) await atomicWrite(f, text);
|
|
1046
|
-
|
|
1129
|
+
await take.apply();
|
|
1047
1130
|
},
|
|
1048
1131
|
commit: spec.commit ?? false,
|
|
1049
1132
|
});
|
|
@@ -1051,6 +1134,50 @@ async function newItemUnlocked(projectDir, spec) {
|
|
|
1051
1134
|
return { item: `gcf/work/${spec.id}.md`, hash };
|
|
1052
1135
|
}
|
|
1053
1136
|
|
|
1137
|
+
/**
|
|
1138
|
+
* The inbox entry an item comes from (`--from`): its title for the item's unless one is given,
|
|
1139
|
+
* the rest of its text for the item's `note:` (the whole text when the title is another), its
|
|
1140
|
+
* pictures moved into the item's attachments with the links to them. Refused on a `work/`
|
|
1141
|
+
* branch, whose gcf/ state is main's. Entries not committed yet ride along with a committed
|
|
1142
|
+
* one: raw input. No `from`: nothing to take.
|
|
1143
|
+
*/
|
|
1144
|
+
async function takeEntry(projectDir, root, spec) {
|
|
1145
|
+
if (!spec.from)
|
|
1146
|
+
return { title: spec.title, note: undefined, files: [], inputs: [], apply: async () => {} };
|
|
1147
|
+
if (onWorkBranch(projectDir))
|
|
1148
|
+
throw new Error('an inbox entry is taken on main: a work/ branch records no inbox move');
|
|
1149
|
+
const pictures = path.join(root, 'work', spec.id, 'attachments');
|
|
1150
|
+
// An empty folder a failed try left behind holds nothing to overwrite.
|
|
1151
|
+
if (existsSync(pictures) && readdirSync(pictures).length)
|
|
1152
|
+
throw new Error(`gcf/work/${spec.id}/attachments/ already exists`);
|
|
1153
|
+
const take = await planTake(root, spec.from, pictures);
|
|
1154
|
+
const { title: own, text } = take.entry;
|
|
1155
|
+
const relink = (s) => s.replaceAll(`${spec.from}/attachments/`, `${spec.id}/attachments/`);
|
|
1156
|
+
// The entry's own title, given back as it is (a board's "→ item"), counts as the same one.
|
|
1157
|
+
// A blank --title is none: the entry's own goes.
|
|
1158
|
+
const given = spec.title?.trim() ? spec.title : undefined;
|
|
1159
|
+
const same = given === undefined || given === own || given === relink(own);
|
|
1160
|
+
const title = relink(given ?? own);
|
|
1161
|
+
const lines = text.split('\n');
|
|
1162
|
+
const first = lines.findIndex((l) => l.trim());
|
|
1163
|
+
const rest = same
|
|
1164
|
+
? lines
|
|
1165
|
+
.slice(first + 1)
|
|
1166
|
+
.join('\n')
|
|
1167
|
+
.trim()
|
|
1168
|
+
: text;
|
|
1169
|
+
const note = relink(rest);
|
|
1170
|
+
const loose = spec.commit ? untrackedEntries(projectDir) : [];
|
|
1171
|
+
|
|
1172
|
+
return {
|
|
1173
|
+
...take,
|
|
1174
|
+
title,
|
|
1175
|
+
note,
|
|
1176
|
+
files: [...take.files, ...loose],
|
|
1177
|
+
inputs: [...take.inputs, ...loose],
|
|
1178
|
+
};
|
|
1179
|
+
}
|
|
1180
|
+
|
|
1054
1181
|
/** @type {typeof submitItemUnlocked} */
|
|
1055
1182
|
export const submitItem = (projectDir, id, opts = {}) =>
|
|
1056
1183
|
locked(projectDir, opts.commit ?? true, () => submitItemUnlocked(projectDir, id, opts));
|
package/package.json
CHANGED
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: gcf-chat
|
|
3
|
+
description: Talk with the human about the GCF project in the board's project chat - answer questions from gcf/ and the runs, propose new work items, make the moves the human approves. Use when the session is a project chat thread of the board, or the user says "/gcf-chat".
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
mode: human gate
|
|
7
|
+
|
|
8
|
+
purpose:
|
|
9
|
+
- answer the human's questions about the game, its design, its work items and its runs from what `gcf/` and the run files say
|
|
10
|
+
- turn a bug, an idea or a task the talk finds into a proposed work item the human accepts with one click
|
|
11
|
+
- make a move the human asks for through its `ai-factory gcf` command, which the chat shows the human as a card first
|
|
12
|
+
|
|
13
|
+
inputs:
|
|
14
|
+
- the human's messages, one turn each
|
|
15
|
+
- 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
|
|
16
|
+
|
|
17
|
+
preconditions:
|
|
18
|
+
- `gcf/` exists and `ai-factory gcf board --json` runs
|
|
19
|
+
- the board started this session: a project chat asks the human before each change
|
|
20
|
+
|
|
21
|
+
forbidden_behaviors:
|
|
22
|
+
- do not make the human's moves: `verdict`, `decide`, `question answer`, `unblock`, `phase next`, `pillar`, `permissions`, `config set`, `hooks-install`; the rules refuse them to any agent
|
|
23
|
+
- do not run `ai-factory gcf-harness run|stop|chat|init` or `ai-factory extension`: the rules refuse them; name the board's button instead
|
|
24
|
+
- do not make a new item with `ai-factory gcf item new`: propose it with the `propose_item_new` tool of the `gcf` MCP server, and the human's click makes it
|
|
25
|
+
- do not write code or edit files to fix what the talk finds: a fix is a work item, and its run builds it
|
|
26
|
+
- do not answer from memory what a file says: read the file, then answer
|
|
27
|
+
- do not ask again for a move the human refused: say what it would have done and leave it
|
|
28
|
+
- do not read the board's own folder: it holds the human's token
|
|
29
|
+
|
|
30
|
+
workflow:
|
|
31
|
+
1. read `gcf/INDEX.md`, then run `ai-factory gcf board --json` for the phase, the items by status and the inbox
|
|
32
|
+
2. a thread bound to an item: read the item's file, its plan, its run's log and run chat first, the paths the context file names, before the first answer
|
|
33
|
+
3. answer the question from the files you read, with the paths that say it; for the runs' numbers run `ai-factory gcf-harness metrics` when the project has the harness
|
|
34
|
+
4. a bug, an idea or a task that is new work: call `propose_item_new` with its id, type, title, subsystems and a note of what its run should know; note length <= 4000 characters
|
|
35
|
+
5. a raw thought that is not work yet: propose to put it in the inbox with `ai-factory gcf inbox add`
|
|
36
|
+
6. a move the human asks for: run its `ai-factory gcf` command; the human approves it on the card, or refuses it
|
|
37
|
+
7. say in one line what changed, or that nothing did
|
|
38
|
+
|
|
39
|
+
invocation:
|
|
40
|
+
- run at the start of a project chat thread the board opens, and when the user types `/gcf-chat`
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: gcf-triage
|
|
3
|
-
description: Triage gcf/inbox
|
|
3
|
+
description: Triage the gcf/inbox/ entries - playtest notes, CI failures, the agent's ideas and requests - into work items, tunes, ideas for the design, or noise, with the human approving each call. Use after a playtest session or when the user says "разбери инбокс".
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
mode: human gate
|
|
@@ -9,7 +9,7 @@ purpose:
|
|
|
9
9
|
- turn raw input into decided work: each inbox entry becomes a work item, a tune note, a design unit, a graveyard line, or nothing - and leaves the inbox
|
|
10
10
|
|
|
11
11
|
inputs:
|
|
12
|
-
- `gcf/inbox
|
|
12
|
+
- `gcf/inbox/in-<id>.md`, one file an entry, read through `ai-factory gcf inbox --json`: each entry has a `title` (its first line) and a `text` that may run several lines
|
|
13
13
|
|
|
14
14
|
preconditions:
|
|
15
15
|
- `gcf/` exists and the inbox holds entries
|
|
@@ -18,7 +18,8 @@ forbidden_behaviors:
|
|
|
18
18
|
- do not create an item or erase an entry without the human's yes: the agent proposes, the human approves
|
|
19
19
|
- do not turn a feel complaint into a bug: "jump feels floaty" is a tune of the item that owns the jump, a bug is behaviour that breaks a rule or a test
|
|
20
20
|
- do not open a second item for something `gcf/graveyard.md` already buried: name the line and ask whether the reason still holds
|
|
21
|
-
- do not edit `gcf/inbox
|
|
21
|
+
- do not edit or delete a file in `gcf/inbox/` by hand: `ai-factory gcf item new --from`, `ai-factory gcf inbox tag` and `ai-factory gcf inbox drop` own the entries
|
|
22
|
+
- do not triage on a `work/` branch: `inbox tag`, `inbox drop` and `item new --from` refuse there; triage on main
|
|
22
23
|
|
|
23
24
|
workflow:
|
|
24
25
|
1. run `ai-factory gcf inbox --json`; read `gcf/LIVE.md` and `gcf/INDEX.md` to know what exists and what is in work
|
|
@@ -27,11 +28,12 @@ workflow:
|
|
|
27
28
|
4. for each entry propose one call with its fields: a bug gets type `bug`, severity and a repro; a tune names the item and the note; an idea names the subsystem; a duplicate names the item it repeats
|
|
28
29
|
5. present the calls to the human, calls per message <= 5, and apply only the approved ones
|
|
29
30
|
6. a bug or other work: run `ai-factory gcf item new <id> --type <type> [--severity <level>] --from <in-id>`, then write its `intent:` and `repro:`
|
|
30
|
-
7.
|
|
31
|
-
8. an
|
|
32
|
-
9.
|
|
33
|
-
10.
|
|
34
|
-
11.
|
|
31
|
+
7. `--from` without `--title` makes the entry's title the item's title and puts the rest of its text in a `note:` block, its pictures in `gcf/work/<id>/attachments/`; with your own `--title` the whole text goes into `note:`
|
|
32
|
+
8. a tune of an item waiting for its verdict or unplayed: leave the entry in the inbox, the note's only copy, until `/gcf-verdict <id> tune --note` records it and drops it; a tune of a kept mechanic is new work with `--reopens <id>`
|
|
33
|
+
9. an idea for the design: write a unit with `TBD` slots in `gcf/design/<system>.md` and its backlog line, then run `ai-factory gcf inbox drop <in-id>`
|
|
34
|
+
10. a duplicate or noise: run `ai-factory gcf inbox drop <in-id>`
|
|
35
|
+
11. an entry the human keeps for later (an idea, a note): tag it with the tag the human names, `ai-factory gcf inbox tag <in-id> --add <tags>`, and leave it in the inbox
|
|
36
|
+
12. report what each entry became and how many entries remain
|
|
35
37
|
|
|
36
38
|
invocation:
|
|
37
39
|
- run after a playtest session, after a CI run that added entries, or when the user asks to triage
|
|
@@ -6,15 +6,18 @@ gcf_context:
|
|
|
6
6
|
|
|
7
7
|
gcf_work:
|
|
8
8
|
- every piece of work is one work item `gcf/work/<id>.md`: find the item before writing code for a feature, a bug or a tech task, or create it with the gcf-card skill
|
|
9
|
-
- a raw idea, a playtest note or a CI finding that is not work yet goes to `ai-factory gcf inbox add "<text>" [--tags <a,b>]
|
|
9
|
+
- a raw idea, a playtest note or a CI finding that is not work yet goes to `ai-factory gcf inbox add "<text>" [--tags <a,b>]` (an entry `gcf/inbox/in-<id>.md`), and the gcf-triage skill sorts it later; a text that starts with a hyphen goes as `inbox add --text="<text>"`
|
|
10
|
+
- a text of several lines (its first line becomes the title) goes through stdin: `ai-factory gcf inbox add --text-file - <<'EOF'`, the lines, then `EOF`
|
|
10
11
|
- before planning an item, run `ai-factory gcf context <id>` and read only the files it lists under `gcf/`
|
|
11
12
|
- 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
|
|
12
13
|
- a question about how the runs go (the share that reached their move, cost, plan checks, DoD attempts, guard firings) is answered by `ai-factory gcf-harness metrics`
|
|
13
14
|
- after the code, write the item's `live:` delta and run `ai-factory gcf verify <id>`: fix what it reports and run it again until every check is green, at most `dod_attempts` of `gcf/config.yml` red runs; still red: block the item with the diagnosis
|
|
15
|
+
- the `live:` delta is YAML in the item's frontmatter, one of two forms: `live: {none: "<why it changes no capability>"}`, or `live:` with `changes:`, a list of `{id: <capability slug>, change: added | modified | removed, summary: "<at most two sentences>"}` (a removed one needs no summary)
|
|
16
|
+
- before `submit` or `close`, tick every task of the item's plan that is done, the verify and the review included: both refuse a plan with unticked tasks; `--unticked "<why>"` is the human's call, never the agent's
|
|
14
17
|
- `submit` and `close` refuse code that changed since its last green `gcf verify`: run it again after any fix; `--unverified "<why>"` is the human's call, never the agent's
|
|
15
18
|
- then end the work on the item with its command: `ai-factory gcf submit <id>` for gate verdict or decision, `ai-factory gcf close <id>` for gate auto
|
|
16
19
|
- work that cannot go on: run `ai-factory gcf block <id> --reason "<why or the question>"`
|
|
17
|
-
- in a worktree on branch `work/<id>` change no `gcf/` file but the item's `live
|
|
20
|
+
- in a worktree on branch `work/<id>` change no `gcf/` file but the item's `live:` and new inbox entries, commit all, then run `ai-factory gcf verify <id> --mark`: `ai-factory gcf integrate` in the main checkout merges it and records the move
|
|
18
21
|
- a design question only the human can answer becomes a D1 record in `gcf/open-questions.md`
|
|
19
22
|
- a word added to a `not:` of `gcf/glossary.md` leaves `gcf/design/` and every item but an unplayed one in the same commit: `ai-factory gcf design check` names each hit as M4
|
|
20
23
|
- the human plays from `ai-factory gcf playtest session`; each free note from that play goes to `ai-factory gcf inbox add --source playtest "<note>"`
|
|
@@ -22,14 +25,18 @@ gcf_work:
|
|
|
22
25
|
- `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
|
|
23
26
|
- an item the human wants run on a given model or effort gets `item new <id> --model <m> --effort <e>`: the harness run passes both to the agent
|
|
24
27
|
- ready items run in `priority:` order, lower first: rank a set of items with `ai-factory gcf prioritize <id> <id> …`, and put an id in `depends` only when the item uses that one's data or code: `ai-factory gcf depends <id> --add <ids>` or `--remove <ids>`, never a hand edit
|
|
28
|
+
- a picture or file the human gives an item goes to `ai-factory gcf item attach <id> --file <path>` (its `gcf/work/<id>/attachments/`, committed); read an item's attachments before you plan it
|
|
25
29
|
- write what the human reads (a question, an assumption, a block reason, an inbox entry, a lesson, a report, an item's `title:`) in `language.ui` of `.ai-factory/config.yaml`, and the body of an item that is not a design unit in its `language.artifacts`
|
|
26
30
|
- write in English whatever lands in a checked document: `gcf/design/`, `gcf/systems/`, `gcf/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; an answer that moves into a unit's slot goes there in English
|
|
27
31
|
- never 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:`, `plan did not converge:`, `waits for`)
|
|
28
32
|
- 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`
|
|
29
33
|
- a pillar changes only on the human's word: `ai-factory gcf pillar rename <from> <to>`, or `ai-factory gcf pillar retire <id> --reason "<why>"`
|
|
34
|
+
- a new item's `--note "<text>"` (or `--note-file -` for several lines) says what its run should know, up to 4000 characters
|
|
35
|
+
- in the project chat (the gcf-chat skill) a new item is proposed with the `propose_item_new` tool of the `gcf` MCP server, not made with `item new`: the human's click makes it
|
|
36
|
+
- a chat thread bound to an item reads the item's file, its plan, its run's log and run chat first (the paths its context names), answers the question, and only then proposes a move
|
|
30
37
|
|
|
31
38
|
gcf_forbidden:
|
|
32
|
-
- do not edit `status:`, `frozen:`, `gcf/LIVE.md`, `gcf/history.md`, `gcf/graveyard.md` or `gcf/INDEX.md` by hand: the commands own them
|
|
39
|
+
- 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
|
|
33
40
|
- do not give a verdict or a decision: `verdict` and `decide` belong to the human, through the gcf-verdict skill
|
|
34
41
|
- do not answer a `TBD` of a design unit yourself: ask the human and offer your draft as the proposed answer
|
|
35
42
|
- do not run `ai-factory gcf phase next`: the phase moves on the human's word only
|
|
@@ -40,6 +47,7 @@ gcf_forbidden:
|
|
|
40
47
|
|
|
41
48
|
gcf_skills:
|
|
42
49
|
- gcf-vision starts a game that has no design yet, and gcf-ingest imports a GDD into `gcf/design/`
|
|
43
|
-
- gcf-card puts work into `gcf/work/`, and gcf-triage sorts `gcf/inbox
|
|
50
|
+
- gcf-card puts work into `gcf/work/`, and gcf-triage sorts the entries of `gcf/inbox/`
|
|
44
51
|
- gcf-verdict records the human's verdict or decision, and gcf-audit reports the health of `gcf/`
|
|
45
52
|
- gcf-debate stresses the design, gcf-adopt puts existing code on GCF, and gcf-init sets up `gcf/` and revises the pillars
|
|
53
|
+
- gcf-chat is the board's project chat: answers from `gcf/` and the runs, proposals of new items, the moves the human approves
|
package/templates/config.yml
CHANGED
|
@@ -18,6 +18,13 @@ dod_timeout_min: 60
|
|
|
18
18
|
context_handoff_pct: 60
|
|
19
19
|
context_window: 0
|
|
20
20
|
auto_compact_pct: 0
|
|
21
|
+
# The chat of a board's agent run (Harness-PRD §10): what the agent asks you by a question card
|
|
22
|
+
# (d1: only your decisions; all: every question of substance; none: nothing, it decides) and the
|
|
23
|
+
# minutes a question waits before the agent takes its default (0: nobody watches, as for a night
|
|
24
|
+
# run; a main run's whole queue waits with it). Uncomment to change:
|
|
25
|
+
# chat:
|
|
26
|
+
# ask: d1
|
|
27
|
+
# answer_timeout_min: 15
|
|
21
28
|
# Lessons (Methodology §5.2.2): at the end of each session on an item its agent says what got in
|
|
22
29
|
# its way, into the inbox. `ai-factory gcf lessons prompt <id>` prints the questions. Uncomment to
|
|
23
30
|
# turn them off, to ask what the project's template should learn, or to add questions:
|