gcf-aif-ext 0.4.1 → 0.5.0

package/lib/phase.js

@@ -0,0 +1,228 @@
+// Phases (Methodology §10): the project's stage decides which item types it takes, and each
+// stage has exit criteria. The current phase is `phase:` in the LIVE.md frontmatter, the first
+// phase while it is absent; the set comes from code, and `phases:` in gcf/config.yml replaces it.
+// Only the operator moves the phase on: `phase next`, against unmet criteria with a reason.
+import path from 'node:path';
+import { readConfig } from './gcf-paths.js';
+import { readLiveStrict, writeLive, liveFile } from './live.js';
+import { buildLedger } from './ledger.js';
+import { ITEM_TYPES } from './validate-item.js';
+import { commitMove } from './unit-ops.js';
+
+const ALL = ITEM_TYPES;
+const SOFT = ['mechanic', 'resource'];
+
+/**
+ * @typedef {{name: string, accepts: string[], with_reopens: string[], exit: string[],
+ *   milestone?: string}} Phase
+ */
+
+/** @type {Phase[]} */
+export const DEFAULT_PHASES = [
+  // Final assets are not requested in a prototype (§5.6): placeholders need no item.
+  {
+    name: 'prototype',
+    accepts: ALL.filter((t) => t !== 'asset'),
+    with_reopens: [],
+    exit: ['mechanic-kept'],
+  },
+  {
+    name: 'vertical-slice',
+    accepts: ALL,
+    with_reopens: [],
+    exit: ['milestone-done', 'no-placeholders'],
+  },
+  { name: 'alpha', accepts: ALL, with_reopens: [], exit: ['features-done'] },
+  {
+    name: 'beta',
+    accepts: ['bug', 'perf', 'content', 'asset', 'release'],
+    with_reopens: SOFT,
+    exit: ['no-open-bugs'],
+  },
+  { name: 'release', accepts: ['bug', 'release'], with_reopens: [], exit: ['release-done'] },
+  { name: 'live', accepts: ['bug', 'content', 'perf', 'release'], with_reopens: SOFT, exit: [] },
+];
+
+const finished = ['unplayed', 'parked'];
+const milestoneOf = (phase) => phase.milestone ?? phase.name;
+
+/**
+ * Exit criteria: `true` met, `false` not, `null` for one only the operator can see. Each gets
+ * the ledger, LIVE.md and the phase, and returns `[met, detail]`.
+ */
+const CRITERIA = {
+  'mechanic-kept': (ledger) => {
+    const kept = ledger.ids().filter((id) => ledger.where(id).terminal.includes('collapsed'));
+
+    return [
+      kept.length > 0,
+      kept.length ? `kept: ${kept.join(', ')}` : 'no mechanic or resource kept yet',
+    ];
+  },
+  // An ended item leaves no file, so "nothing open" cannot tell a done milestone from one never
+  // tagged: the operator reads that case, the code only names what is still open.
+  'milestone-done': (ledger, live, phase) => {
+    const m = milestoneOf(phase);
+    const open = [
+      ...ledger.design.flatMap((d) => d.units).filter((u) => u.header.milestone === m),
+      ...ledger.items
+        .filter((c) => c.data.milestone === m && !finished.includes(c.data.status))
+        .map((c) => ({ id: c.data.id })),
+    ].map((x) => x.id);
+
+    return open.length
+      ? [false, `milestone ${m} still open: ${open.join(', ')}`]
+      : [null, `nothing open carries milestone ${m}: check by hand it is done, not untagged`];
+  },
+  // Feature complete: a live feature of this milestone, or one with no milestone at all, is open.
+  'features-done': (ledger, live, phase) => {
+    const m = milestoneOf(phase);
+    const open = ledger.items
+      .filter((c) => c.data.type === 'feature' && [m, null, undefined].includes(c.data.milestone))
+      .map((c) => c.data.id);
+
+    return [
+      !open.length,
+      open.length ? `features open: ${open.join(', ')}` : `no feature of ${m} or untagged open`,
+    ];
+  },
+  'no-open-bugs': (ledger) => {
+    const open = ledger.items
+      .filter(
+        (c) =>
+          c.data.type === 'bug' &&
+          ['critical', 'high'].includes(c.data.severity) &&
+          c.data.status !== 'parked',
+      )
+      .map((c) => c.data.id);
+
+    return [
+      !open.length,
+      open.length ? `critical/high bugs open: ${open.join(', ')}` : 'no critical or high bug open',
+    ];
+  },
+  // Only a release shipped in this phase: a demo shipped in alpha does not end the release phase.
+  'release-done': (ledger, live) => {
+    const r = live.release;
+    const ours = Boolean(r) && (r.phase ?? null) === live.phase;
+
+    return [
+      ours,
+      ours
+        ? `released ${r.version} to ${r.channel}`
+        : 'no release of this phase in LIVE.md: its release item has not ended yet',
+    ];
+  },
+  'no-placeholders': () => [null, 'check by hand: the slice holds no placeholder'],
+};
+export const CRITERIA_NAMES = Object.keys(CRITERIA);
+
+const isList = (v, of) => Array.isArray(v) && v.every((x) => of.includes(x));
+const isSlug = (v) => typeof v === 'string' && /^[a-z0-9]+(-[a-z0-9]+)*$/.test(v);
+
+/** The phases of a project: `phases:` of gcf/config.yml, checked, or the default set. */
+export function phasesOf(config) {
+  const list = config.phases;
+  if (list === undefined) return DEFAULT_PHASES;
+  const bad = (msg) => new Error(`gcf/config.yml phases: ${msg}`);
+  if (!Array.isArray(list) || !list.length) throw bad('a non-empty list of phases');
+  const names = list.map((p) => p?.name);
+  const twice = names.find((n, i) => names.indexOf(n) !== i);
+  if (twice !== undefined) throw bad(`${twice} is listed twice`);
+
+  return list.map((p, i) => {
+    const name = p?.name;
+    if (!isSlug(name)) throw bad(`entry ${i + 1} needs a slug name`);
+    if (p.milestone !== undefined && !isSlug(p.milestone))
+      throw bad(`${name}: milestone is a milestone name`);
+    const accepts = p.accepts === 'all' ? ALL : p.accepts;
+    if (!isList(accepts, ALL)) throw bad(`${name}: accepts is all or a list of ${ALL.join(', ')}`);
+    const withReopens = p.with_reopens ?? [];
+    if (!isList(withReopens, ALL)) throw bad(`${name}: with_reopens is a list of item types`);
+    const exit = p.exit ?? [];
+    if (!isList(exit, CRITERIA_NAMES))
+      throw bad(`${name}: exit is a list of ${CRITERIA_NAMES.join(', ')}`);
+
+    return {
+      name,
+      accepts,
+      with_reopens: withReopens,
+      exit,
+      ...(p.milestone ? { milestone: p.milestone } : {}),
+    };
+  });
+}
+
+/** The phases, the current one and LIVE.md. A `phase:` the set does not name is an error. */
+async function load(projectDir) {
+  const root = path.join(path.resolve(projectDir), 'gcf');
+  const phases = phasesOf(await readConfig(root));
+  const live = await readLiveStrict(root);
+  const at = live.phase === null ? 0 : phases.findIndex((p) => p.name === live.phase);
+  if (at < 0) {
+    const names = phases.map((p) => p.name).join(', ');
+    throw new Error(`LIVE.md phase ${live.phase} is not a phase of the project (${names})`);
+  }
+
+  return { root, phases, at, live };
+}
+
+/** Refuse a new item of `type` the current phase does not take. */
+export async function refuseByPhase(projectDir, type, reopens = null) {
+  const { phases, at } = await load(projectDir);
+  const phase = phases[at];
+  if (phase.accepts.includes(type) || (reopens && phase.with_reopens.includes(type))) return;
+  const takes = phase.with_reopens.length
+    ? `${phase.accepts.join(', ')}; ${phase.with_reopens.join(', ')} only with reopens`
+    : phase.accepts.join(', ');
+  throw new Error(
+    `phase ${phase.name} takes no ${type} item (it takes ${takes}) — the operator moves the ` +
+      'phase on with gcf phase next',
+  );
+}
+
+/** `gcf phase`: the current phase, what it takes, its exit criteria and the next phase. */
+export async function phaseStatus(projectDir) {
+  const { phases, at, live } = await load(projectDir);
+  const phase = phases[at];
+  const ledger = await buildLedger(projectDir);
+  const criteria = phase.exit.map((name) => {
+    const [met, detail] = CRITERIA[name](ledger, live, phase);
+
+    return { name, met, detail };
+  });
+
+  return {
+    phase: phase.name,
+    accepts: phase.accepts,
+    with_reopens: phase.with_reopens,
+    criteria,
+    next: phases[at + 1]?.name ?? null,
+    ready: criteria.every((c) => c.met !== false),
+  };
+}
+
+/**
+ * The operator moves the phase on, commit `gcf(phase): <from> → <to>`. An unmet criterion needs
+ * `reason`, which the commit carries; the move itself is the operator's word on one that only
+ * the operator can check.
+ */
+export async function nextPhase(projectDir, { reason = '', commit = true } = {}) {
+  const status = await phaseStatus(projectDir);
+  if (!status.next) throw new Error(`${status.phase} is the last phase`);
+  const unmet = status.criteria.filter((c) => c.met === false);
+  if (unmet.length && !reason.trim())
+    throw new Error(
+      `${status.phase} exit criteria not met (${unmet.map((c) => c.detail).join('; ')}) — ` +
+        'move on anyway with --reason "<why>"',
+    );
+  const { root, live } = await load(projectDir);
+  const tail = `${status.phase} → ${status.next}${reason.trim() ? `: ${reason.trim()}` : ''}`;
+  const hash = await commitMove(projectDir, `gcf(phase): ${tail}`, {
+    files: [liveFile(root)],
+    mutate: () => writeLive(root, { ...live, phase: status.next }),
+    commit,
+  });
+
+  return { from: status.phase, to: status.next, forced: unmet.map((c) => c.name), hash };
+}

package/lib/playtest-list.js

@@ -1,4 +1,24 @@
-import { listItems, scalarOf } from './gcf-paths.js';
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { listItems, scalarOf, readConfig, firstBullet } from './gcf-paths.js';
+import { recordsOf } from './verdict-fs.js';
+import { runDod } from './verify.js';
+
+const ENVELOPE = /^\S+\.\.\S+ /;
+
+/** What the play should feel: a mechanic's feel envelopes, a resource's rate envelopes. */
+function feelOf(body) {
+  const feel = recordsOf(body, 'feel')
+    .filter((r) => r.name && r.envelope)
+    .map((r) => `${r.name}: ${r.envelope}`);
+  const rates = ['sources', 'sinks'].flatMap((key) =>
+    recordsOf(body, key)
+      .filter((r) => r.name && ENVELOPE.test(`${r.rate} `))
+      .map((r) => `${r.name} rate: ${r.rate}`),
+  );
+
+  return [...feel, ...rates];
+}
 
 /**
  * Playtest list (Methodology §5.3): every item waiting for its verdict, and every unplayed one,
@@ -13,5 +33,44 @@ export async function playtestList(root) {
       status: c.data.status,
       system: c.data.system ?? [],
       question: scalarOf(c.body, 'miss_criterion') || '(miss_criterion is empty)',
+      reach: recordsOf(c.body, 'behavior')
+        .map((r) => r.input)
+        .filter(Boolean),
+      feel: feelOf(c.body),
+      intent: firstBullet(c.body, 'intent') || null,
     }));
 }
+
+const git = (projectDir, args) => {
+  const res = spawnSync('git', args, { cwd: projectDir, encoding: 'utf8' });
+
+  return res.status === 0 ? res.stdout.trim() : null;
+};
+
+/**
+ * `playtest session` (Methodology §5.3): one build of main and the checklist of everything that
+ * waits for play, grouped by subsystem — built from the items on every call, no file of its own.
+ * `build` runs the project's `dod.build` first.
+ */
+export async function playtestSession(
+  projectDir,
+  { build = false, stdio = ['ignore', 2, 2] } = {},
+) {
+  const root = path.join(path.resolve(projectDir), 'gcf');
+  const items = (await playtestList(root)).sort(
+    (a, b) => (a.system[0] ?? '').localeCompare(b.system[0] ?? '') || a.id.localeCompare(b.id),
+  );
+  // gcf/.metrics changes on every audit and context run: it does not make the build differ.
+  const dirty = git(projectDir, ['status', '--porcelain', '--', '.', ':(exclude)gcf/.metrics']);
+  const session = {
+    branch: git(projectDir, ['rev-parse', '--abbrev-ref', 'HEAD']),
+    commit: git(projectDir, ['rev-parse', '--short', 'HEAD']),
+    // No commit (no repository, or none yet): the build is unknown, not clean.
+    dirty: dirty === null ? null : Boolean(dirty),
+    build: null,
+    items,
+  };
+  if (build) session.build = runDod(projectDir, await readConfig(root), 'build', stdio);
+
+  return session;
+}

package/lib/unit-ops.js

@@ -15,6 +15,8 @@ import { operationInProgress, commitPaths } from './git.js';
 import { upsertBlock, openSystemDoc } from './systems-doc.js';
 import { buryLine, recordLine } from './verdict-fs.js';
 import { DEFAULT_GATE } from './validate-item.js';
+import { refuseByPhase } from './phase.js';
+import { withMainLock } from './main-lock.js';
 
 /** A design file's text without the `## <id>` section. */
 export function removeUnit(text, id) {
@@ -150,6 +152,8 @@ export async function takeUnits(
   const ledger = await buildLedger(projectDir);
   const units = ids.map((id) => designUnitOf(ledger, id));
   refuseUnready(units, (await designCheck(projectDir)).units);
+  for (const u of units) await refuseByPhase(projectDir, u.header.type, u.header.reopens ?? null);
+  if (feature && !ledger.item(feature)) await refuseByPhase(projectDir, 'feature');
   const writes = units.map((unit) => ({
     file: path.join(root, 'work', `${unit.id}.md`),
     text: serialize(unitItemData(unit, today, feature), `\n${unit.body.trim()}\n`),
@@ -206,7 +210,28 @@ function uncommitted(projectDir, file) {
  * @param {string} message
  * @param {{files: string[], mutate: () => Promise<void>, commit: boolean, inputs?: string[]}} move
  */
-export async function commitMove(projectDir, message, { files, mutate, commit, inputs = [] }) {
+/** A worktree of the integrator (Methodology §7): its gcf/ state is main's to move. */
+const onWorkBranch = (projectDir) =>
+  /^work\//.test(
+    spawnSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], {
+      cwd: projectDir,
+      encoding: 'utf8',
+    }).stdout?.trim() ?? '',
+  );
+
+export async function commitMove(projectDir, message, move) {
+  // A move that commits holds the main lock while it writes and commits (Methodology §7).
+  return move.commit
+    ? withMainLock(projectDir, () => record(projectDir, message, move))
+    : record(projectDir, message, move);
+}
+
+async function record(projectDir, message, { files, mutate, commit, inputs = [] }) {
+  if (commit && onWorkBranch(projectDir))
+    throw new Error(
+      `cannot record ${message} on a work/ branch: a worktree records no move — the run ` +
+        'leaves .gcf-session/outcome.json, and the main checkout records it',
+    );
   const busy = commit ? operationInProgress(projectDir) : null;
   if (busy) throw new Error(`cannot record ${message} while ${busy} is in progress`);
   const dirty = commit

package/lib/validate-item.js

@@ -65,6 +65,8 @@ const FIELDS = [
   'live',
   'model',
   'effort',
+  'version',
+  'channel',
   'created',
 ];
 const REQUIRED = ['schema', 'id', 'type', 'gate', 'status', 'created'];
@@ -154,6 +156,10 @@ const RULES = {
   live: (v) => liveProblem(v) ?? true,
   model: (v) => nullable(isText)(v) || 'model must be text or null',
   effort: (v) => nullable(isText)(v) || 'effort must be text or null',
+  version: (v) =>
+    nullable((x) => typeof x === 'string' && /^\S+$/.test(x))(v) ||
+    'version must be one word of text (quote a number: "1.0")',
+  channel: (v) => nullable(isSlug)(v) || 'channel must be a slug, e.g. steam',
   created: (v) => /^\d{4}-\d{2}-\d{2}$/.test(dateStr(v)) || 'created must be YYYY-MM-DD',
 };
 
@@ -214,6 +220,10 @@ const CROSS = [
   ],
   [(d) => isUnit(d) && d.source === undefined, 'a design-unit item keeps its source:'],
   [(d) => Boolean(d.parent) && d.parent === d.id, 'an item cannot be its own parent'],
+  [
+    (d) => d.type !== 'release' && Boolean(d.version || d.channel),
+    'version and channel belong to a release',
+  ],
 ];
 
 /** Validate work item frontmatter. Returns a list of one-line errors (empty = valid). */

package/lib/verdict-fs.js

@@ -12,7 +12,8 @@ import { blockLines, upsertBlock, removeLines, openSystemDoc } from './systems-d
 const ENVELOPE = /^\S+\.\.\S+ /;
 const real = (lines) => lines.filter((l) => !/^- none\b/.test(l));
 
-function recordsOf(body, key) {
+/** The records of a `key:` block, each as `{field: value}`. */
+export function recordsOf(body, key) {
   const { lines, sections } = parseBlocks(body);
   const at = sections.find((s) => s.key === key && !s.value);
 

package/lib/verify.js

@@ -0,0 +1,72 @@
+// `gcf verify <id>` (Methodology §6): the auto-DoD checks code can run — the GCF checks of the
+// pre-commit gate, the item's live: delta against LIVE.md, then the project's `dod.build` and
+// `dod.test`. The second-agent review is the run's job; the attempt count lives in the run.
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { readConfig } from './gcf-paths.js';
+import { readLive, applyDelta } from './live.js';
+import { gateProblems } from './gate.js';
+import { unplayedCloseProblem } from './work-ops.js';
+
+/** Run a `dod.<key>` command in the project; `none` says the project has no such step. */
+export function runDod(projectDir, config, key, stdio) {
+  if (config.dod !== undefined && (typeof config.dod !== 'object' || Array.isArray(config.dod)))
+    return { name: key, ok: false, problems: ['dod in gcf/config.yml must map test: and build:'] };
+  const cmd = config.dod?.[key];
+  if (cmd === 'none') return { name: key, ok: true, problems: [], skipped: true };
+  if (typeof cmd !== 'string' || !cmd.trim())
+    return {
+      name: key,
+      ok: false,
+      problems: [`dod.${key} is not set in gcf/config.yml — the project's command, or none`],
+    };
+  // shortcut: no timeout, a command that waits for input hangs the run; add one when it bites.
+  const res = spawnSync(cmd, { cwd: projectDir, shell: true, stdio });
+  const ok = res.status === 0;
+  const why = res.error ? res.error.message : `exit ${res.status ?? res.signal}`;
+
+  return { name: key, ok, problems: ok ? [] : [`dod.${key} failed (${why}): ${cmd}`] };
+}
+
+/**
+ * Why the item's `live:` delta would fail its end against this checkout's LIVE.md: it does not
+ * apply, or an unplayed close could not take it back.
+ */
+export async function deltaProblems(projectDir, item) {
+  const problems = [];
+  try {
+    const root = path.join(path.resolve(projectDir), 'gcf');
+    applyDelta((await readLive(root)).capabilities, item.data.live, String(item.data.id));
+  } catch (e) {
+    problems.push(e.message);
+  }
+
+  const unplayed = unplayedCloseProblem(item);
+  if (unplayed) problems.push(unplayed);
+
+  return problems;
+}
+
+/**
+ * Every DoD check over item `id`, each run even when an earlier one failed: one attempt sees
+ * all it has to fix. The commands' own output goes to `stdio` (stderr by default).
+ */
+export async function verifyItem(projectDir, id, { stdio = ['ignore', 2, 2] } = {}) {
+  const { problems, ledger } = await gateProblems(projectDir);
+  const item = ledger.item(id);
+  if (!item) throw new Error(`${id} is not a work item of gcf/work/`);
+  if (item.data.status !== 'ready')
+    throw new Error(`${id} is ${item.data.status}: the DoD runs on a ready item, before its move`);
+
+  const root = path.join(path.resolve(projectDir), 'gcf');
+  const live = await deltaProblems(projectDir, item);
+  const config = await readConfig(root);
+  const checks = [
+    { name: 'gcf', ok: !problems.length, problems },
+    { name: 'live', ok: !live.length, problems: live },
+    runDod(projectDir, config, 'build', stdio),
+    runDod(projectDir, config, 'test', stdio),
+  ];
+
+  return { id, checks, ok: checks.every((c) => c.ok) };
+}

package/lib/work-ops.js

@@ -26,8 +26,16 @@ import {
   buryLine,
   recordLine,
 } from './verdict-fs.js';
-import { readLive, writeLive, liveFile, applyDelta, revertDelta, knownIssueOf } from './live.js';
+import {
+  readLiveStrict,
+  writeLive,
+  liveFile,
+  applyDelta,
+  revertDelta,
+  knownIssueOf,
+} from './live.js';
 import { dropInbox } from './inbox.js';
+import { refuseByPhase } from './phase.js';
 
 /**
  * Options of a committed move; each move reads the ones it needs.
@@ -149,7 +157,7 @@ async function begin(projectDir, id, move) {
     run: async () => {
       for (const s of steps) await s();
       if (!liveOps.length) return;
-      let live = await readLive(root);
+      let live = await readLiveStrict(root);
       for (const op of liveOps) live = op(live);
       await writeLive(root, live);
     },
@@ -259,6 +267,7 @@ const detailOf = (item, archived) =>
  */
 function endToHistory(m, item, event, { applyLive = true } = {}) {
   const id = String(item.data.id);
+  if (item.data.type === 'release') recordRelease(m, item);
   m.touch(path.join(m.root, 'history.md'));
   m.step(() => recordLine(m.root, id, event));
   const archived = archivePlan(m, item);
@@ -271,6 +280,24 @@ function endToHistory(m, item, event, { applyLive = true } = {}) {
   m.step(() => unlink(item.file));
 }
 
+/**
+ * A release item that ends writes the `release:` block of LIVE.md (Methodology §13): its
+ * version, channel and the date; the previous release stays only in history.md.
+ */
+function recordRelease(m, item) {
+  const { id, version, channel } = item.data;
+  if (!version || !channel)
+    throw new Error(`${id} is a release: write its version: and channel: before it ends`);
+  // The item file leaves in this commit: the gate never sees a hand-edited version: here.
+  if (typeof version !== 'string' || !/^\S+$/.test(version) || !isValidId(channel))
+    throw new Error(`${id}: version: is one quoted word ("1.10"), channel: a slug (steam)`);
+  // The phase it shipped in: the release phase exits on a release of its own (Methodology §10).
+  m.live((l) => ({
+    ...l,
+    release: { version, channel, date: today(), ...(l.phase ? { phase: l.phase } : {}) },
+  }));
+}
+
 /** A fresh id from `base`: base, base-2, base-3 … — ids are never reused. */
 function freshId(ledger, base) {
   let id = base;
@@ -392,6 +419,17 @@ export async function submitItem(projectDir, id, opts = {}) {
   return { id, status, hash: await finish(m, 'submit', id, commit) };
 }
 
+/** Why a soft gate-auto item cannot close unplayed, or null: only an `added` comes back out. */
+export function unplayedCloseProblem(item) {
+  if (!SOFT.includes(item.data.type) || item.data.gate !== 'auto') return null;
+  if (!(item.data.live?.changes ?? []).some((c) => c.change !== 'added')) return null;
+
+  return (
+    `${item.data.id}: an unplayed close can only add capabilities (a modified or removed one ` +
+    'cannot be taken back) — set gate: verdict and submit it'
+  );
+}
+
 /**
  * A soft unit closed without a playtest (Methodology §5.4): its lines go into its systems docs,
  * its capability into LIVE.md, and the file stays unplayed with its body frozen by hash — that
@@ -400,11 +438,8 @@ export async function submitItem(projectDir, id, opts = {}) {
 function closeUnplayed(m) {
   const { item } = m;
   const id = String(item.data.id);
-  if ((item.data.live?.changes ?? []).some((c) => c.change !== 'added'))
-    throw new Error(
-      `${id}: an unplayed close can only add capabilities (a modified or removed one cannot be ` +
-        'taken back) — set gate: verdict and submit it',
-    );
+  const refused = unplayedCloseProblem(item);
+  if (refused) throw new Error(refused);
   const systems = item.data.system ?? [];
   m.touch(...systemFiles(m.root, systems));
   m.step(async () => {
@@ -654,6 +689,19 @@ export async function dropItem(projectDir, id, opts = {}) {
   return { id, hash: await finish(m, 'drop', id, commit), removal };
 }
 
+/** The version and channel of a new item: well-formed, and only on a release. */
+function checkRelease(spec) {
+  const { type, version, channel } = spec;
+  if (version !== undefined && !/^\S+$/.test(version))
+    throw new Error('--release is one word, e.g. 1.2.0');
+  if (spec.milestone !== undefined && !isValidId(spec.milestone))
+    throw new Error('--milestone is a milestone name of game.md');
+  if (channel !== undefined && !isValidId(channel))
+    throw new Error('--channel is a lowercase hyphen slug, e.g. steam');
+  if ((version || channel) && type !== 'release')
+    throw new Error('--release and --channel belong to a release item');
+}
+
 /** Refuse a spec `item new` cannot honour; returns the gate the item gets. */
 function checkNew(ledger, spec) {
   const { id, type, gate, severity } = spec;
@@ -667,6 +715,7 @@ function checkNew(ledger, spec) {
   if (type === 'feature' && g !== 'auto') throw new Error('a feature always has gate auto');
   if (type === 'bug' && !SEVERITIES.includes(severity))
     throw new Error(`a bug needs --severity ${SEVERITIES.join('|')}`);
+  checkRelease(spec);
 
   return g;
 }
@@ -678,6 +727,7 @@ const NO_CAPABILITY = {
   spike: 'a spike answers a question, its code never ships',
   asset: 'an asset dresses a capability, it adds none',
   perf: 'a budget met changes no capability',
+  release: 'a release ships what is built, it adds no capability',
 };
 
 /** The `live:` a new item starts with, or null when its author owes one. */
@@ -699,6 +749,9 @@ function optionalFields(spec, gate, since) {
     ...(reopens ? { reopens } : {}),
     ...(gate === 'verdict' ? { tune_count: 0 } : {}),
     ...(type === 'bug' ? { severity } : {}),
+    ...(spec.milestone ? { milestone: spec.milestone } : {}),
+    ...(spec.version ? { version: spec.version } : {}),
+    ...(spec.channel ? { channel: spec.channel } : {}),
     ...(live ? { live } : {}),
   };
 }
@@ -732,6 +785,7 @@ export async function newItem(projectDir, spec) {
   const root = gcfOf(projectDir);
   const ledger = await buildLedger(projectDir);
   const gate = checkNew(ledger, spec);
+  await refuseByPhase(projectDir, spec.type, spec.reopens);
   if (spec.reopens && !ledger.where(spec.reopens).terminal.length)
     throw new Error(`reopens names ${spec.reopens}, which has not ended`);
   const file = path.join(root, 'work', `${spec.id}.md`);

package/package.json

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

package/schemas/item.schema.json

@@ -100,6 +100,10 @@
     },
     "model": { "$ref": "#/definitions/textOrNull" },
     "effort": { "$ref": "#/definitions/textOrNull" },
+    "version": {
+      "anyOf": [{ "type": "null" }, { "type": "string", "pattern": "^\\S+$" }]
+    },
+    "channel": { "$ref": "#/definitions/slugOrNull" },
     "created": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }
   }
 }

package/skills/gcf-card/SKILL.md

@@ -31,8 +31,8 @@ outputs:
 
 workflow:
 1. for a free-text design idea: ask "into work now, or park it?"; write a unit in the matching `gcf/design/<system>.md` with `source: manual` and `TBD` slots, append `- <id>` to `gcf/backlog.md`, and on "park" stop here
-2. for non-design work: pick the type - tech, bug, spike, asset, content, perf, release - and propose the gate its type gives; the human may flip it (`--gate auto` is "no playtest")
-3. a bug needs `--severity` and a `repro:` the human confirms
+2. for non-design work: pick the type - tech, bug, spike, asset, content, perf, release - among those `ai-factory gcf phase` says the phase takes, and propose the gate its type gives; the human may flip it (`--gate auto` is "no playtest")
+3. a bug needs `--severity` and a `repro:` the human confirms; a release needs `--release <version> --channel <name>` from the human
 4. run `ai-factory gcf item new <id> --type <type> [--gate <gate>] [--parent <feature>] [--title "<line>"]`, add `--from <in-id>` when it comes from the inbox, `--blocked "file needed"` for a final asset; then write `intent:` and `live:` and stop
 5. for a design unit: run `ai-factory gcf where <id>`; the id must be a single unit of `gcf/design/`; read its section from the file the command names
 6. for a unit with `flags: impl?` ask the human first whether the mechanic already ships; on "yes" run `ai-factory gcf drop <id> --reason "already ships"` and stop

package/skills/gcf-verdict/SKILL.md

@@ -21,7 +21,7 @@ forbidden_behaviors:
 - do not edit systems docs, `LIVE.md`, history or graveyard by hand: the commands own them
 
 workflow:
-1. with no arguments: run `ai-factory gcf playtest` and stop - that list, awaiting-verdict and unplayed items, is the session's playtest sheet
+1. with no arguments: run `ai-factory gcf playtest session` and stop - its build line and checklist of awaiting-verdict and unplayed items are the session's playtest sheet
 2. read the item; for a verdict ask the human the miss_criterion question and record the answer in one line
 3. for `tune` at the tune limit (`tune_limit` in `gcf/config.yml`, 3 by default): the command refuses; the way out is a kill, and a redesigned envelope becomes a new item with `reopens: <id>`
 4. for `keep` of a design-unit item still awaiting its verdict: compress it first - the collapse copies lines verbatim, 1 line per behavior record, refusal and boundary