gcf-aif-ext 0.8.0 → 0.10.0

package/lib/domain.js

@@ -0,0 +1,370 @@
+// The GCF domain of the board read (Board-PRD decision 16): what a board shows and offers for a
+// GCF project, as data. Its columns, its blocks (phase, WIP, playtest, inbox…), the fields of an
+// item, every move's form with the `ai-factory` words it runs, the terms of its Help. A board
+// draws these and builds each command from `args` and `fields`; it hard-codes none of them.
+import { ITEM_MOVES, STORED } from './transitions.js';
+import { DEFAULT_GATE, GATES, ITEM_TYPES, SEVERITIES, UNIT_ITEM_TYPES } from './validate-item.js';
+import { SOURCES } from './inbox.js';
+
+// The status a run starts from; the order of its column is the run order.
+export const RUNS_FROM = 'ready';
+
+// The board's words for each stored status: a column's label and tooltip.
+const COLUMN_TEXT = {
+  ready: ['ready', 'Waits for a run; the order here is the run order'],
+  blocked: ['blocked', 'Stopped: waits for an answer, an asset or a fix of a failed check'],
+  'awaiting-verdict': ['awaiting verdict', 'Built; waits for a playtest and a keep, tune or kill'],
+  'awaiting-decision': ['awaiting decision', 'Waits for the operator to decide: go, no, close…'],
+  unplayed: ['unplayed', 'Closed without a playtest; waits for one'],
+  parked: ['parked', 'A bug kept as a known issue; unblock takes it back to ready'],
+};
+
+const GATE_HELP = {
+  verdict: 'Closed by a playtest: keep, tune or kill',
+  auto: 'Closed by the run itself when its checks are green; no playtest',
+  decision: 'Closed by the operator: go, no, close or continue',
+};
+
+// The form of each move for a board: the `ai-factory` words with `{id}` for its target and
+// `{ids}` for a list of items, and the fields the operator fills. A field goes as
+// `--<flag or key>=<value>`; a list repeats it; `ids` and `tags` go as one comma list;
+// `remove` is `--remove` / `--no-remove`, or the command's own rule when left empty; `slug` is
+// the target id the operator types (`{id}`); a field with `when` goes only while another field
+// holds one of those values.
+const REASON = { key: 'reason', label: 'Reason', kind: 'longtext', required: true };
+const OPTIONAL_REASON = { ...REASON, required: false };
+const REMOVE = { key: 'remove', label: 'Removal item for its code', kind: 'remove' };
+const CONSTRAINT = { key: 'constraint', label: 'Constraint lines', kind: 'list' };
+// close and submit need a green gcf verify of the code as it is now; the operator may say why
+// they go without one, and the reason goes into the move's commit.
+const UNVERIFIED = {
+  key: 'unverified',
+  label: 'No green gcf verify? Why it goes anyway',
+  kind: 'text',
+};
+
+const verdict = (v, help, fields, danger) => ({
+  label: v,
+  help,
+  args: ['gcf', 'verdict', '{id}', v],
+  fields,
+  ...(danger && { danger }),
+});
+const decide = (choice, help, fields = [], danger) => ({
+  label: choice,
+  help,
+  args: ['gcf', 'decide', '{id}', choice],
+  fields,
+  ...(danger && { danger }),
+});
+const text = (key, label, extra = {}) => ({ key, label, kind: 'text', ...extra });
+
+// An item's moves (§4.1), offered by `items[].moves`.
+const ITEM_SPECS = {
+  submit: {
+    label: 'submit',
+    help: 'Built: on to awaiting verdict or awaiting decision, by its gate',
+    args: ['gcf', 'submit', '{id}'],
+    fields: [UNVERIFIED],
+    rare: true,
+  },
+  close: {
+    label: 'close',
+    help: 'Done, gate auto: to history; a mechanic or a resource waits unplayed',
+    args: ['gcf', 'close', '{id}'],
+    fields: [CONSTRAINT, UNVERIFIED],
+    rare: true,
+  },
+  'verdict:keep': verdict('keep', 'Played and kept: it goes to history', [
+    { key: 'note', label: 'Note', kind: 'text' },
+    CONSTRAINT,
+  ]),
+  'verdict:tune': verdict('tune', 'Played; needs a change: back to ready with the note', [
+    { key: 'note', label: 'What to change', kind: 'longtext', required: true },
+  ]),
+  'verdict:kill': verdict(
+    'kill',
+    'Played and rejected: it goes to the graveyard',
+    [{ key: 'note', label: 'Why', kind: 'longtext' }, REMOVE],
+    true,
+  ),
+  'decide:go': decide('go', 'Approved: it goes to history as decided'),
+  'decide:no': decide(
+    'no',
+    'Not doing it: it goes to the graveyard',
+    [OPTIONAL_REASON, REMOVE],
+    true,
+  ),
+  'decide:wontfix': decide(
+    'wontfix',
+    'A bug left as it is: it goes to the graveyard',
+    [OPTIONAL_REASON, REMOVE],
+    true,
+  ),
+  'decide:known': decide('known', 'A bug kept as a known issue: it goes to parked'),
+  'decide:close': decide('close', 'The feature is done: it goes to history'),
+  'decide:continue': decide('continue', 'The feature goes on: back to ready for more children'),
+  'decide:kill': decide(
+    'kill',
+    'The feature is dropped: it goes to the graveyard with its live children',
+    [OPTIONAL_REASON],
+    true,
+  ),
+  block: {
+    label: 'block',
+    help: 'Stop it until the operator answers',
+    args: ['gcf', 'block', '{id}'],
+    fields: [REASON],
+  },
+  unblock: {
+    label: 'unblock',
+    help: 'The answer is given: back to ready (a feature with a dead child: to a decision)',
+    args: ['gcf', 'unblock', '{id}'],
+    fields: [{ key: 'note', label: 'Answer or "file: <path>"', kind: 'longtext' }],
+    drag: RUNS_FROM,
+  },
+  drop: {
+    label: 'drop',
+    help: 'Off the board into the graveyard, from any status',
+    args: ['gcf', 'drop', '{id}'],
+    fields: [REASON, { key: 'tags', label: 'Graveyard tags', kind: 'text' }, REMOVE],
+    danger: true,
+    rare: true,
+    drag: 'graveyard',
+  },
+  depends: {
+    label: 'depends',
+    help: 'The items it waits for: a run starts only after they are played',
+    args: ['gcf', 'depends', '{id}'],
+    fields: [
+      { key: 'add', label: 'Add: ids it waits for', kind: 'ids' },
+      { key: 'remove', label: 'Remove: ids it no longer waits for', kind: 'ids' },
+    ],
+    rare: true,
+  },
+};
+
+// The agent's move: a session of the gcf-run skill builds the item, driven by the harness.
+const RUN = {
+  kind: 'agent',
+  label: 'run',
+  help: 'An agent session builds it: plan, code, the checks, then submit or close',
+  skill: 'gcf-run',
+  args: [],
+  fields: [],
+};
+
+// The new item form (`gcf item new`): work that is not a design unit; a design unit enters work
+// through the gcf-card skill and take.
+const NEW_ITEM = {
+  label: 'create',
+  help: 'A new work item, committed; the core refuses a type the phase does not take',
+  args: ['gcf', 'item', 'new', '{id}', '--commit'],
+  fields: [
+    { key: 'id', label: 'Id (lowercase-hyphen slug)', kind: 'slug', required: true },
+    {
+      key: 'type',
+      label: 'Type',
+      kind: 'choice',
+      required: true,
+      default: 'tech',
+      options: ITEM_TYPES.filter((t) => !UNIT_ITEM_TYPES.includes(t)).map((t) => ({
+        value: t,
+        label: t,
+        help: `gate ${DEFAULT_GATE[t]} by default`,
+      })),
+    },
+    {
+      key: 'gate',
+      label: 'Gate',
+      kind: 'choice',
+      options: [
+        { value: '', label: 'by type' },
+        ...GATES.map((g) => ({ value: g, label: g, help: GATE_HELP[g] })),
+      ],
+    },
+    {
+      key: 'severity',
+      label: 'Severity',
+      kind: 'choice',
+      required: true,
+      options: SEVERITIES.map((s) => ({ value: s, label: s })),
+      when: { key: 'type', is: ['bug'] },
+    },
+    text('release', 'Version', { required: true, when: { key: 'type', is: ['release'] } }),
+    text('channel', 'Channel', { required: true, when: { key: 'type', is: ['release'] } }),
+    text('title', 'Title: one line, what it gives'),
+    text('system', 'Subsystems, comma-separated'),
+    text('depends', 'Depends on ids, comma-separated'),
+    text('parent', 'Parent feature id'),
+    text('milestone', 'Milestone'),
+    text('blocked', 'Start blocked: why (e.g. "file needed")'),
+    text('model', 'Model of its run (e.g. opus)'),
+    text('effort', 'Effort of its run (e.g. high)'),
+    // The inbox entry it comes from: the form fills it, the operator does not.
+    text('from', 'From inbox entry', { hidden: true }),
+  ],
+};
+
+// The moves of the domain's blocks: the phase, the inbox, the questions, the run order.
+const BLOCK_SPECS = {
+  'item-new': NEW_ITEM,
+  'phase-next': {
+    label: 'move on',
+    help: 'On to the next phase; against an unmet criterion only with a reason',
+    args: ['gcf', 'phase', 'next'],
+    fields: [
+      { key: 'reason', label: 'Reason (needed when a criterion is not met)', kind: 'longtext' },
+    ],
+  },
+  'inbox-add': {
+    label: 'add',
+    help: 'A raw note for triage: an idea, a playtest note, a CI finding',
+    args: ['gcf', 'inbox', 'add', '--commit'],
+    fields: [
+      { key: 'text', label: 'Text', kind: 'text', required: true },
+      {
+        key: 'source',
+        label: 'Source',
+        kind: 'choice',
+        default: 'operator',
+        options: SOURCES.map((s) => ({ value: s, label: s })),
+      },
+      { key: 'tags', label: 'Tags', kind: 'tags' },
+    ],
+  },
+  'inbox-drop': {
+    label: 'erase',
+    help: 'Noise: the entry is erased, nothing is made of it',
+    args: ['gcf', 'inbox', 'drop', '{id}', '--commit'],
+    fields: [],
+    danger: true,
+  },
+  'inbox-tag': {
+    label: 'tag',
+    help: 'Sort the entry: tags added and removed',
+    args: ['gcf', 'inbox', 'tag', '{id}', '--commit'],
+    fields: [
+      { key: 'add', label: 'Add tags', kind: 'tags' },
+      { key: 'remove', label: 'Remove tags', kind: 'tags' },
+    ],
+  },
+  'question-answer': {
+    label: 'answer',
+    help: 'The answer goes into the record; the next agent on its units puts it in place',
+    args: ['gcf', 'question', 'answer', '{id}'],
+    fields: [{ key: 'text', label: 'Answer', kind: 'text', required: true }],
+  },
+  prioritize: {
+    label: 'prioritize',
+    help: 'The run order: ranks 1, 2, 3… in one commit',
+    args: ['gcf', 'prioritize', '{ids}'],
+    fields: [],
+  },
+};
+
+// The item fields a board shows: on the card (`card`), in the drawer (all that have a value).
+const GATE_FIELD_OPTIONS = GATES.map((g) => ({ value: g, label: g, help: GATE_HELP[g] }));
+const FIELDS = [
+  { key: 'priority', label: 'priority', kind: 'rank', help: 'Rank: lower runs sooner', card: true },
+  { key: 'type', label: 'type', kind: 'text', card: true, badge: true },
+  {
+    key: 'gate',
+    label: 'gate',
+    kind: 'choice',
+    options: GATE_FIELD_OPTIONS,
+    help: 'Who closes it',
+    card: true,
+    badge: true,
+  },
+  { key: 'severity', label: 'severity', kind: 'text', card: true, badge: true },
+  { key: 'model', label: 'model', kind: 'text', card: true },
+  { key: 'effort', label: 'effort', kind: 'text' },
+  { key: 'tune_count', label: 'tune', kind: 'text', help: 'Tune verdicts so far', card: true },
+  {
+    key: 'waits_for',
+    label: 'waits for',
+    kind: 'ids',
+    help: 'The run gate refuses it until these are played',
+    card: true,
+  },
+  { key: 'depends', label: 'depends', kind: 'ids' },
+  { key: 'needed_by', label: 'needed by', kind: 'ids', help: 'The items that wait for this one' },
+  { key: 'system', label: 'system', kind: 'list' },
+  { key: 'parent', label: 'parent', kind: 'text' },
+  { key: 'children', label: 'children', kind: 'ids' },
+  { key: 'milestone', label: 'milestone', kind: 'text' },
+  { key: 'blocked', label: 'blocked', kind: 'longtext', help: 'Why it stopped', card: true },
+];
+
+// The words of its Help (Board-PRD decision 17): what the board's terms mean in GCF.
+const TERMS = [
+  ['item', 'One piece of work in gcf/work/: a file with its type, gate and status'],
+  ['gate', 'Who closes an item: a verdict (playtest), auto (its checks) or a decision'],
+  ...GATES.map((g) => [`gate: ${g}`, GATE_HELP[g]]),
+  [
+    'feature',
+    'A parent item: when its children are done, the operator decides: close, continue or kill',
+  ],
+  ['design unit', 'A mechanic, resource, rule, constraint or entity of gcf/design/'],
+  ['phase', 'The stage of the project (prototype, vertical slice…): the types it takes'],
+  ['WIP', 'Items built and waiting for a verdict; at the limit new verdict work stops'],
+  ['verify', 'The DoD: the project test and build commands, green on the code as it is'],
+  ['inbox', 'Raw input waiting for triage: it becomes an item or is erased'],
+  ['lesson', 'An inbox entry an agent session left: what got in its way'],
+  ['D1', 'A question only the operator answers; it blocks the units it names'],
+  ['D2', 'An assumption the agent made and works with; it comes back when its trigger fires'],
+  ['unplayed', 'Closed by its checks without a playtest; it waits for one'],
+  ['history', 'What was accepted: history.md'],
+  ['graveyard', 'What was killed or dropped, with the reason: graveyard.md'],
+].map(([term, help]) => ({ term, help }));
+
+const SECTIONS = {
+  phase: { next: 'phase-next' },
+  release: {},
+  wip: { help: 'Items awaiting a verdict / wip_built_limit' },
+  inbox: { add: 'inbox-add', drop: 'inbox-drop', tag: 'inbox-tag' },
+  questions: { answer: 'question-answer' },
+  lessons: {},
+  playtest: {
+    waits: ['awaiting-verdict', 'unplayed'],
+    verdicts: ['verdict:keep', 'verdict:tune', 'verdict:kill'],
+  },
+  history: { label: 'Accepted' },
+  graveyard: { label: 'Graveyard' },
+};
+
+// The extension whose CLI drives agent runs (run, next, stop, metrics with --json).
+const HARNESS = { extension: 'gcf-harness-aif-ext', cli: 'gcf-harness' };
+
+/** Whether the project's AI Factory extensions include the harness (`extensions` of the read). */
+export const hasHarness = (extensions) => Object.hasOwn(extensions ?? {}, HARNESS.extension);
+
+/**
+ * The GCF domain of the board read. `extensions` are the project's AI Factory extensions: the
+ * agent's move, and the runner that drives it, only with the harness.
+ */
+export function domainOf(extensions = {}) {
+  const harness = hasHarness(extensions);
+
+  return {
+    kind: 'gcf',
+    runs_from: RUNS_FROM,
+    harness: harness ? HARNESS.cli : null,
+    columns: STORED.map((status) => ({
+      status,
+      label: COLUMN_TEXT[status][0],
+      help: COLUMN_TEXT[status][1],
+    })),
+    moves: {
+      ...(harness && { run: RUN }),
+      ...Object.fromEntries(ITEM_MOVES.map((m) => [m, ITEM_SPECS[m]])),
+      ...BLOCK_SPECS,
+    },
+    fields: FIELDS,
+    terms: TERMS,
+    sections: SECTIONS,
+    new_item: 'item-new',
+    rank: 'prioritize',
+  };
+}

package/lib/transitions.js

@@ -1,13 +1,14 @@
 // Methodology §4. A work item FILE carries one of the stored statuses; `running` and `verify` are
 // read from the run (worktree + session), never written. A terminal move deletes the file and
 // writes a history or graveyard line in the same commit, so no terminal status is ever stored.
+// The order is the board's column order.
 export const STORED = [
   'ready',
+  'blocked',
   'awaiting-verdict',
   'awaiting-decision',
-  'blocked',
-  'parked',
   'unplayed',
+  'parked',
 ];
 
 // The status each command takes an item from (§4.1). `drop` leaves from any stored status.
@@ -27,8 +28,13 @@ const FROM = {
   block: ['ready'],
   unblock: ['blocked', 'parked'],
   drop: STORED,
+  // What it waits for may change at any status; the core refuses an unknown id and a cycle.
+  depends: STORED,
 };
 
+/** Every move an item may be offered, in the board's order. */
+export const ITEM_MOVES = Object.keys(FROM);
+
 /** True when `move` (`close`, `verdict:keep`, …) may start from `status`. */
 export function allowedFrom(move, status) {
   return (FROM[move] ?? []).includes(status);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gcf-aif-ext",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Game Context Framework for AI Factory",
   "type": "module",
   "license": "MIT",

package/templates/agents-block.md

@@ -34,7 +34,7 @@ gcf_forbidden:
 - do not answer a `TBD` of a design unit yourself: ask the human and offer your draft as the proposed answer
 - do not run `ai-factory gcf phase next`: the phase moves on the human's word only
 - do not change what agent runs may do: `ai-factory gcf permissions` and its deny groups belong to the human
-- do not change a setting of `gcf/config.yml`: `ai-factory gcf config set` belongs to the human
+- do not change a setting of `gcf/config.yml` or the `language` of `.ai-factory/config.yaml`: `ai-factory gcf config set` belongs to the human
 - do not reuse an ended id: rework gets a new id with `reopens: <old id>`
 - do not commit past the gate with `--no-verify`: a refused commit names what to fix