gcf-aif-ext 0.10.2 → 0.11.1

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/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,
@@ -245,6 +245,8 @@ export function validateUntil(body) {
245
245
  const errors = [];
246
246
  const lines = String(body).split('\n');
247
247
  lines.forEach((line, i) => {
248
+ // A quoted line (an inbox entry's text in an item's note:) holds no annotation of its own.
249
+ if (line.startsWith('>')) return;
248
250
  for (const m of line.matchAll(/\[until:[^\]]*\]/g)) {
249
251
  if (!UNTIL_OK.test(m[0]))
250
252
  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,7 +35,7 @@ import {
35
35
  revertDelta,
36
36
  knownIssueOf,
37
37
  } from './live.js';
38
- import { dropInbox } from './inbox.js';
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';
@@ -926,8 +926,18 @@ function newItemText(spec, gate, since) {
926
926
  ...optionalFields(spec, gate, since),
927
927
  created: spec.date ?? today(),
928
928
  };
929
+ // `note`: the rest of the inbox entry it came from, quoted: a line of it that reads `key:`
930
+ // must not open a section of the item.
931
+ // An entry of one line leaves no note.
932
+ const quoted = spec.note
933
+ ? spec.note
934
+ .split('\n')
935
+ .map((l) => (l ? `> ${l}` : '>'))
936
+ .join('\n')
937
+ : '';
929
938
  const body =
930
- `\nintent:\n- ${title ?? 'TBD: what this item changes'}\n` +
939
+ `\nintent:\n- ${title || 'TBD: what this item changes'}\n` +
940
+ (quoted ? `\nnote:\n${quoted}\n` : '') +
931
941
  (type === 'bug' ? '\nrepro:\n- TBD: the steps that show the bug\n' : '');
932
942
 
933
943
  return serialize(data, body);
@@ -1012,6 +1022,50 @@ async function setDependsUnlocked(projectDir, id, { add = [], remove = [], commi
1012
1022
  return { id, depends, hash };
1013
1023
  }
1014
1024
 
1025
+ // An attachment is a picture or a file the operator gave the item (a chat image, a reference).
1026
+ const ATTACH_MAX = 10 * 1024 * 1024;
1027
+
1028
+ /**
1029
+ * Copy `file` into `gcf/work/<id>/attachments/` under its own name (`-2`, `-3`… on a clash)
1030
+ * and commit it alone, `gcf(attach)`. A running item takes it too: the file is new, the item's
1031
+ * own file is not touched; but the commit gate refuses while `gcf/` has uncommitted changes
1032
+ * (a main-mode session's live: delta, an item made and not committed). A link or a file over
1033
+ * 10 MB is refused.
1034
+ */
1035
+ async function attachItemUnlocked(projectDir, id, file, { commit = true } = {}) {
1036
+ const ledger = await buildLedger(projectDir);
1037
+ if (!ledger.item(id)) throw new Error(`${id} is not a work item`);
1038
+ const st = lstatOr(file);
1039
+ if (!st?.isFile()) throw new Error(`${file} is not a file (a link is refused)`);
1040
+ if (st.size > ATTACH_MAX) throw new Error(`${file} is over 10 MB`);
1041
+ const dir = path.join(gcfOf(projectDir), 'work', id, 'attachments');
1042
+ const { name, ext } = path.parse(file);
1043
+ let to = path.join(dir, `${name}${ext}`);
1044
+ for (let n = 2; existsSync(to); n++) to = path.join(dir, `${name}-${n}${ext}`);
1045
+ const hash = await commitMove(projectDir, `gcf(attach): ${id}`, {
1046
+ files: [to],
1047
+ mutate: async () => {
1048
+ await mkdir(dir, { recursive: true });
1049
+ await copyFile(file, to);
1050
+ },
1051
+ commit,
1052
+ });
1053
+
1054
+ return { id, file: path.relative(projectDir, to).replaceAll('\\', '/'), hash };
1055
+ }
1056
+
1057
+ function lstatOr(file) {
1058
+ try {
1059
+ return lstatSync(file);
1060
+ } catch {
1061
+ return null;
1062
+ }
1063
+ }
1064
+
1065
+ /** @type {typeof attachItemUnlocked} */
1066
+ export const attachItem = (projectDir, id, file, opts = {}) =>
1067
+ locked(projectDir, opts.commit ?? true, () => attachItemUnlocked(projectDir, id, file, opts));
1068
+
1015
1069
  /**
1016
1070
  * A new work item in ready (or blocked), no commit. A design unit enters work through `take`,
1017
1071
  * not here: its body is the unit's slots. `from` erases the inbox entry it came from.
@@ -1025,8 +1079,10 @@ async function newItemUnlocked(projectDir, spec) {
1025
1079
  throw new Error(`reopens names ${spec.reopens}, which has not ended`);
1026
1080
  const file = path.join(root, 'work', `${spec.id}.md`);
1027
1081
  if (existsSync(file)) throw new Error(`gcf/work/${spec.id}.md already exists`);
1082
+ const take = await takeEntry(projectDir, root, spec);
1083
+ const item = { ...spec, title: take.title, note: take.note };
1028
1084
 
1029
- const writes = [[file, newItemText(spec, gate, headHash(projectDir))]];
1085
+ const writes = [[file, newItemText(item, gate, headHash(projectDir))]];
1030
1086
  if (spec.parent) {
1031
1087
  const p = ledger.item(spec.parent);
1032
1088
  if (!p || p.data.type !== 'feature')
@@ -1036,14 +1092,12 @@ async function newItemUnlocked(projectDir, spec) {
1036
1092
  }
1037
1093
 
1038
1094
  // `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
1095
  const hash = await commitMove(projectDir, `gcf(item): ${spec.id}`, {
1042
- files: [...writes.map((w) => w[0]), ...inbox],
1043
- inputs: inbox,
1096
+ files: [...writes.map((w) => w[0]), ...take.files],
1097
+ inputs: take.inputs,
1044
1098
  mutate: async () => {
1045
1099
  for (const [f, text] of writes) await atomicWrite(f, text);
1046
- if (spec.from) await dropInbox(root, spec.from);
1100
+ await take.apply();
1047
1101
  },
1048
1102
  commit: spec.commit ?? false,
1049
1103
  });
@@ -1051,6 +1105,50 @@ async function newItemUnlocked(projectDir, spec) {
1051
1105
  return { item: `gcf/work/${spec.id}.md`, hash };
1052
1106
  }
1053
1107
 
1108
+ /**
1109
+ * The inbox entry an item comes from (`--from`): its title for the item's unless one is given,
1110
+ * the rest of its text for the item's `note:` (the whole text when the title is another), its
1111
+ * pictures moved into the item's attachments with the links to them. Refused on a `work/`
1112
+ * branch, whose gcf/ state is main's. Entries not committed yet ride along with a committed
1113
+ * one: raw input. No `from`: nothing to take.
1114
+ */
1115
+ async function takeEntry(projectDir, root, spec) {
1116
+ if (!spec.from)
1117
+ return { title: spec.title, note: undefined, files: [], inputs: [], apply: async () => {} };
1118
+ if (onWorkBranch(projectDir))
1119
+ throw new Error('an inbox entry is taken on main: a work/ branch records no inbox move');
1120
+ const pictures = path.join(root, 'work', spec.id, 'attachments');
1121
+ // An empty folder a failed try left behind holds nothing to overwrite.
1122
+ if (existsSync(pictures) && readdirSync(pictures).length)
1123
+ throw new Error(`gcf/work/${spec.id}/attachments/ already exists`);
1124
+ const take = await planTake(root, spec.from, pictures);
1125
+ const { title: own, text } = take.entry;
1126
+ const relink = (s) => s.replaceAll(`${spec.from}/attachments/`, `${spec.id}/attachments/`);
1127
+ // The entry's own title, given back as it is (a board's "→ item"), counts as the same one.
1128
+ // A blank --title is none: the entry's own goes.
1129
+ const given = spec.title?.trim() ? spec.title : undefined;
1130
+ const same = given === undefined || given === own || given === relink(own);
1131
+ const title = relink(given ?? own);
1132
+ const lines = text.split('\n');
1133
+ const first = lines.findIndex((l) => l.trim());
1134
+ const rest = same
1135
+ ? lines
1136
+ .slice(first + 1)
1137
+ .join('\n')
1138
+ .trim()
1139
+ : text;
1140
+ const note = relink(rest);
1141
+ const loose = spec.commit ? untrackedEntries(projectDir) : [];
1142
+
1143
+ return {
1144
+ ...take,
1145
+ title,
1146
+ note,
1147
+ files: [...take.files, ...loose],
1148
+ inputs: [...take.inputs, ...loose],
1149
+ };
1150
+ }
1151
+
1054
1152
  /** @type {typeof submitItemUnlocked} */
1055
1153
  export const submitItem = (projectDir, id, opts = {}) =>
1056
1154
  locked(projectDir, opts.commit ?? true, () => submitItemUnlocked(projectDir, id, opts));
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "gcf-aif-ext",
3
- "version": "0.10.2",
3
+ "version": "0.11.1",
4
4
  "description": "Game Context Framework for AI Factory",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: gcf-triage
3
- description: Triage gcf/inbox.md - 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 "разбери инбокс".
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.md`, read through `ai-factory gcf inbox --json`
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.md` by hand: `ai-factory gcf item new --from`, `ai-factory gcf inbox tag` and `ai-factory gcf inbox drop` own its lines
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. 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>`
31
- 8. 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>`
32
- 9. a duplicate or noise: run `ai-factory gcf inbox drop <in-id>`
33
- 10. 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
34
- 11. report what each entry became and how many entries remain
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,7 +6,8 @@ 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>]`, and the gcf-triage skill sorts it later; a text that starts with a hyphen goes as `inbox add --text="<text>"`
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`
@@ -14,7 +15,7 @@ gcf_work:
14
15
  - `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
16
  - 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
17
  - 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:`, 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
+ - 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
19
  - a design question only the human can answer becomes a D1 record in `gcf/open-questions.md`
19
20
  - 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
21
  - 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,6 +23,7 @@ gcf_work:
22
23
  - `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
24
  - 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
25
  - 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
26
+ - 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
27
  - 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
28
  - 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
29
  - 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`)
@@ -29,7 +31,7 @@ gcf_work:
29
31
  - 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>"`
30
32
 
31
33
  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
34
+ - 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
35
  - do not give a verdict or a decision: `verdict` and `decide` belong to the human, through the gcf-verdict skill
34
36
  - do not answer a `TBD` of a design unit yourself: ask the human and offer your draft as the proposed answer
35
37
  - do not run `ai-factory gcf phase next`: the phase moves on the human's word only
@@ -40,6 +42,6 @@ gcf_forbidden:
40
42
 
41
43
  gcf_skills:
42
44
  - 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.md`
45
+ - gcf-card puts work into `gcf/work/`, and gcf-triage sorts the entries of `gcf/inbox/`
44
46
  - gcf-verdict records the human's verdict or decision, and gcf-audit reports the health of `gcf/`
45
47
  - gcf-debate stresses the design, gcf-adopt puts existing code on GCF, and gcf-init sets up `gcf/` and revises the pillars
@@ -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: