gcf-aif-ext 0.7.5 → 0.7.7

package/README.md

@@ -50,6 +50,17 @@ Updating preserves `gcf/`, `cnlp.config.json` and the pre-commit hook. Run `ai-f
 
 On Windows, run `extension add` and `extension update` from PowerShell or cmd, not Git Bash: the installer unpacks with `tar`, and Git Bash's GNU tar reads `C:\…` as a remote host (`Cannot connect to C: resolve failed`). The Windows `tar.exe` handles it.
 
+### 0.7.7
+
+- `ai-factory gcf config [--json]` lists the human's settings of `gcf/config.yml` with what each means; `gcf config set <key> --value=<v>` sets one, checked by the rules a read applies, the comments kept, one `gcf(config)` commit. An empty number goes back to its default. `gcf board --json` carries them as `settings`.
+- `gcf board --json` questions also carry `assumed`, `until`, `sys`, `lens` and `sections`: a D2 shows what it assumed and when it comes back, and every record where it came from.
+
+### 0.7.6
+
+- `ai-factory gcf permissions [--on <group>] [--off <group>] [--deny <rule>] [--undeny <rule>]` — what agent runs may not do: deny groups and the human's own rules in the `agent:` section of `gcf/config.yml`, one `gcf(permissions)` commit; with no change it lists them. On by default: `git-destroy`, `mass-delete`, `publish`, `human-moves`, `guards`; off: `secrets`, `outside`, `processes`. `agent.groups` keeps only the human's choices (`secrets: true`): a group it does not name keeps its default, so one a later version adds comes on. `git push` is in none. `gcf board --json` carries `agent` (`groups`, `deny_extra`, the resolved `deny`, `allow`).
+- New `config.yml` keys for harness runs: `context_handoff_pct` (60; 0 turns the handoff off), `context_window` (0: the model's) and `auto_compact_pct` (0: the agent's default; at least the handoff share + 15). `gcf board --json` carries them as `context`; a kept session that handed over reads `resume: {ended: 'handoff', handoffs}`.
+- The AGENTS.md block tells the agent that the permissions are the human's.
+
 ### 0.7.1
 
 - `gcf board --json`: a ready item's worktree with no run lock and no session mark is a run that stopped (a timeout, a stop, a crash), not a run: the item reads `running: false`, `resumable: true`, and keeps its moves; its next run resumes the worktree. An agent session the harness kept (`.gcf-session/runs/<id>.agent.json`) makes a ready item `resumable` too, in either run mode, and shows as `resume: {ended, resets?}` (null without one).

package/commands/gcf.js

@@ -977,6 +977,62 @@ function registerBoard(gcf) {
         ].join('\n'),
       );
     });
+  const config = gcf
+    .command('config')
+    .description("The human's settings of gcf/config.yml: list them, or set one (commit)")
+    // A misspelt subcommand would read as a stray word and list the settings, as if set.
+    .allowExcessArguments(false)
+    .option('--json', 'machine output')
+    .action(async (o) => {
+      const { gcfRoot, readConfig, readRawConfig } = await lib('gcf-paths');
+      await readConfig(gcfRoot()); // a config the rules refuse says so here
+      const list = (await lib('config-set')).settingsOf(await readRawConfig(gcfRoot()));
+      out(o.json, list, (x) =>
+        x.map((s) => `${s.key}: ${s.value ?? '-'}  # ${s.label}`).join('\n'),
+      );
+    });
+  config
+    .command('set <key>')
+    .description('Set one key; an empty --value= takes a number back to its default')
+    // The value only through --value: `set plan_passes 7` must not read as a reset. A value
+    // may start with a hyphen (a command's flag); as `--value=<text>` it stays one value.
+    .allowExcessArguments(false)
+    .requiredOption('--value <value>', 'the new value; empty (--value=) for the default')
+    .option('--no-commit', 'skip the commit (tests only)')
+    .action(async (key, o) => {
+      const r = await (
+        await lib('config-set')
+      ).setConfig(process.cwd(), key, o.value, {
+        commit: o.commit,
+      });
+      const now = `${r.key}: ${r.value ?? 'default'}`;
+      console.log(r.unchanged ? `${now} (unchanged)` : `${now}${shortHash(r.hash)}`);
+    });
+  const many = (v, prev = []) => [...prev, v];
+  gcf
+    .command('permissions')
+    .description("What agent runs may not do: deny groups and custom rules (the human's; commit)")
+    .option('--on <group>', 'turn a deny group on (repeatable)', many)
+    .option('--off <group>', 'turn a deny group off (repeatable)', many)
+    .option('--deny <rule>', 'add a custom deny rule, like Bash(cmd*) (repeatable)', many)
+    .option('--undeny <rule>', 'remove a custom deny rule (repeatable)', many)
+    .option('--json', 'machine output')
+    .option('--no-commit', 'skip the commit (tests only)')
+    .action(async (o) => {
+      const perms = await lib('agent-permissions');
+      const { gcfRoot, readConfig } = await lib('gcf-paths');
+      const change = [o.on, o.off, o.deny, o.undeny].some(Boolean);
+      const r = change
+        ? await perms.setPermissions(process.cwd(), o, { commit: o.commit })
+        : perms.agentOf(await readConfig(gcfRoot()));
+      out(o.json, r, (x) =>
+        [
+          ...x.groups.map((g) => `${g.on ? '[x]' : '[ ]'} ${g.id}: ${g.label}`),
+          ...x.deny_extra.map((d) => `deny: ${d}`),
+          ...(x.hash ? [`committed${shortHash(x.hash)}`] : []),
+        ].join('\n'),
+      );
+    });
 }
 
 function registerIntegrate(gcf) {

package/extension.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://raw.githubusercontent.com/lee-to/ai-factory/2.x/schemas/extension.schema.json",
   "name": "gcf-aif-ext",
-  "version": "0.7.5",
+  "version": "0.7.7",
   "description": "Game Context Framework for AI Factory",
   "skills": [
     "skills/gcf-init",

package/lib/agent-permissions.js

@@ -0,0 +1,244 @@
+// What a headless agent run may not do (Harness-PRD §7). The run allows everything else
+// (`--permission-mode bypassPermissions`): a deny rule holds in every mode. The groups guard
+// the edge cases only — what git cannot undo, what leaves the machine, the human's own moves
+// and the guards themselves. `git push` is not one of them: a feature ends tested and pushed.
+// Deny rules match the command as written, so they catch accidents, not a determined
+// rewording; the gcf-run skill makes a refusal a stop.
+import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import YAML from 'yaml';
+import { commitMove } from './unit-ops.js';
+import { atomicWrite } from './safe-path.js';
+import { gcfRoot } from './gcf-paths.js';
+
+// A shell command pattern turns into a rule for both shell tools: on Windows the agent runs
+// commands through PowerShell, which Bash rules do not cover.
+const shell = (...patterns) => patterns.flatMap((p) => [`Bash(${p})`, `PowerShell(${p})`]);
+const files = (tools, ...globs) => globs.flatMap((g) => tools.map((t) => `${t}(${g})`));
+
+/** @type {{ id: string, label: string, on: boolean, rules: string[] }[]} */
+export const DENY_GROUPS = [
+  {
+    id: 'git-destroy',
+    label: 'git history and uncommitted work: reset --hard, clean, stash, force push',
+    on: true,
+    rules: shell(
+      'git reset --hard*',
+      'git clean*',
+      'git stash*',
+      'git branch -D*',
+      'git filter-branch*',
+      'git update-ref -d*',
+      'git push*--force*',
+      'git push -f*',
+      'git push -uf*',
+      'git push * -f',
+      'git push * -f *',
+      'git push *+*',
+      'git push*--mirror*',
+      'git push*--delete*',
+      'git checkout .',
+      'git checkout -- .',
+      'git restore .',
+      'git restore -- .',
+    ),
+  },
+  {
+    id: 'mass-delete',
+    label: 'recursive delete: rm -r, Remove-Item -Recurse, rd /s',
+    on: true,
+    rules: shell(
+      'rm -r*',
+      'rm -R*',
+      'rm -fr*',
+      'rm -fR*',
+      'rm -f -r*',
+      'rm --recursive*',
+      'Remove-Item*-Recurse*',
+      'Remove-Item* -r',
+      'Remove-Item* -r *',
+      'rmdir /s*',
+      'rd /s*',
+      'del /s*',
+      'cmd /c rd /s*',
+      'cmd /c rmdir /s*',
+      'cmd /c del /s*',
+    ),
+  },
+  {
+    id: 'publish',
+    label: 'publishing: npm publish, stage, unpublish, deprecate; docker push',
+    on: true,
+    rules: shell('npm publish*', 'npm stage*', 'npm unpublish*', 'npm deprecate*', 'docker push*'),
+  },
+  {
+    id: 'human-moves',
+    label:
+      "the human's GCF moves: verdict, decide, answer, unblock, phase, pillars, settings, permissions, setup",
+    on: true,
+    rules: shell(
+      'ai-factory gcf verdict*',
+      'ai-factory gcf decide*',
+      'ai-factory gcf question answer*',
+      'ai-factory gcf unblock*',
+      'ai-factory gcf phase next*',
+      'ai-factory gcf pillar*',
+      'ai-factory gcf permissions*',
+      'ai-factory gcf config set*',
+      'ai-factory gcf hooks-install*',
+      'ai-factory gcf-harness init*',
+      'ai-factory gcf-harness run*',
+      'ai-factory gcf-harness stop*',
+      'ai-factory extension*',
+    ),
+  },
+  {
+    id: 'guards',
+    label: 'the guards: .claude/, extension code, gcf/LIVE.md, gcf/.metrics/, the run files',
+    on: true,
+    rules: files(
+      ['Edit', 'Write'],
+      '.claude/**',
+      '.ai-factory/extensions/**',
+      'gcf/LIVE.md',
+      'gcf/.metrics/**',
+      '.gcf-session/runs/**',
+      '.gcf-session/handoff.json',
+    ),
+  },
+  {
+    id: 'secrets',
+    label: 'reading secrets: ~/.npmrc, ~/.ssh, ~/.claude.json, .env',
+    on: false,
+    rules: files(['Read'], '~/.npmrc', '~/.ssh/**', '~/.claude.json', '**/.env'),
+  },
+  {
+    id: 'outside',
+    label:
+      'changes outside the project: global installs, git config --global, setx, registry, shutdown',
+    on: false,
+    rules: shell(
+      'npm i -g*',
+      'npm install -g*',
+      'npm install --global*',
+      'git config --global*',
+      'setx*',
+      'reg add*',
+      'reg delete*',
+      'shutdown*',
+      'Restart-Computer*',
+      'Stop-Computer*',
+    ),
+  },
+  {
+    id: 'processes',
+    label: 'killing processes: taskkill, Stop-Process, kill',
+    on: false,
+    rules: shell('taskkill*', 'Stop-Process*', 'kill *', 'pkill*'),
+  },
+];
+
+const GROUP_IDS = DENY_GROUPS.map((g) => g.id);
+// A permission rule: a tool name, optionally with a specifier — `Bash(npm test*)`, `Read`.
+const RULE_RE = /^[A-Za-z_][\w-]*(\(.+\))?$/;
+const known = (x) => GROUP_IDS.includes(x);
+const rule = (x) => typeof x === 'string' && RULE_RE.test(x);
+
+function rules(agent, key) {
+  const v = agent[key] ?? [];
+  if (!Array.isArray(v) || !v.every(rule))
+    throw new Error(`gcf/config.yml: agent.${key} must be a list of rules like Bash(cmd*) or Read`);
+
+  return v;
+}
+
+/**
+ * The groups the human chose: `agent.groups` maps a group id to true or false. A group it does
+ * not name keeps its default, so a group a later version adds on comes on in every project.
+ */
+function choices(agent) {
+  const g = agent.groups ?? {};
+  if (typeof g !== 'object' || Array.isArray(g))
+    throw new Error('gcf/config.yml: agent.groups must map a group id to true or false');
+  for (const [id, on] of Object.entries(g))
+    if (!known(id) || typeof on !== 'boolean')
+      throw new Error(
+        `gcf/config.yml: agent.groups.${id} must be true or false, for one of ${GROUP_IDS.join(' | ')}`,
+      );
+
+  return g;
+}
+
+/**
+ * The `agent:` section resolved: each group on or off, the deny rules the run gets, the extra
+ * allow rules (for an agent run without bypass). No section: the default groups.
+ */
+export function agentOf(config) {
+  const agent = config.agent ?? {};
+  if (typeof agent !== 'object' || Array.isArray(agent))
+    throw new Error('gcf/config.yml: agent must be a mapping');
+  const chosen = choices(agent);
+  const extra = rules(agent, 'deny');
+  const allow = rules(agent, 'allow');
+  const groups = DENY_GROUPS.map((g) => ({ id: g.id, label: g.label, on: chosen[g.id] ?? g.on }));
+  const deny = [
+    ...new Set([...DENY_GROUPS.filter((g, i) => groups[i].on).flatMap((g) => g.rules), ...extra]),
+  ];
+
+  return { groups, deny_extra: extra, deny, allow };
+}
+
+/** Refuse a change that names no group, a group twice, a bad rule, or a rule it cannot remove. */
+function checkChange(change, current) {
+  const on = change.on ?? [];
+  const off = change.off ?? [];
+  for (const id of [...on, ...off])
+    if (!known(id)) throw new Error(`no permission group ${id}: ${GROUP_IDS.join(' | ')}`);
+  const both = on.find((id) => off.includes(id));
+  if (both) throw new Error(`${both} is turned on and off at once`);
+  for (const r of [...(change.deny ?? []), ...(change.undeny ?? [])])
+    if (!rule(r)) throw new Error(`not a permission rule: ${r}`);
+  const missing = (change.undeny ?? []).find((r) => !current.deny_extra.includes(r));
+  if (missing) throw new Error(`${missing} is not one of your own deny rules: turn its group off`);
+}
+
+/**
+ * Turn groups on or off, add or remove a custom rule; commit gcf(permissions). Only the
+ * `agent:` section changes: the rest of config.yml keeps its keys and comments. The file is
+ * read under the move's lock, so two changes at once both land.
+ */
+export async function setPermissions(projectDir, change, { commit = true } = {}) {
+  const file = path.join(gcfRoot(projectDir), 'config.yml');
+  let result;
+  const hash = await commitMove(projectDir, 'gcf(permissions): agent deny rules', {
+    files: [file],
+    mutate: async () => {
+      const doc = YAML.parseDocument(existsSync(file) ? await readFile(file, 'utf8') : '');
+      if (doc.errors.length) throw new Error(`gcf/config.yml: ${doc.errors[0].message}`);
+      if (!YAML.isMap(doc.contents)) doc.contents = doc.createNode({});
+      // A blank `agent:` (or one holding only comments) is no map yet.
+      const agent = doc.get('agent', true);
+      if (agent != null && !YAML.isMap(agent) && !(YAML.isScalar(agent) && agent.value == null))
+        throw new Error('gcf/config.yml: agent must be a mapping');
+      if (!YAML.isMap(agent)) doc.set('agent', doc.createNode({}));
+      const groups = doc.getIn(['agent', 'groups'], true);
+      if (groups != null && !YAML.isMap(groups) && !(YAML.isScalar(groups) && groups.value == null))
+        throw new Error('gcf/config.yml: agent.groups must map a group id to true or false');
+      if (!YAML.isMap(groups)) doc.setIn(['agent', 'groups'], doc.createNode({}));
+      const current = agentOf({ agent: doc.toJS().agent });
+      checkChange(change, current);
+      for (const id of change.on ?? []) doc.setIn(['agent', 'groups', id], true);
+      for (const id of change.off ?? []) doc.setIn(['agent', 'groups', id], false);
+      const deny = [...new Set([...current.deny_extra, ...(change.deny ?? [])])].filter(
+        (r) => !change.undeny?.includes(r),
+      );
+      doc.setIn(['agent', 'deny'], doc.createNode(deny, { flow: true }));
+      result = agentOf({ agent: doc.toJS().agent });
+      await atomicWrite(file, doc.toString());
+    },
+    commit,
+  });
+
+  return { ...result, hash };
+}

package/lib/board.js

@@ -4,7 +4,7 @@ import { readFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { buildLedger } from './ledger.js';
-import { readConfig } from './gcf-paths.js';
+import { readConfig, readRawConfig } from './gcf-paths.js';
 import { readLive } from './live.js';
 import { listInbox } from './inbox.js';
 import { phaseStatus } from './phase.js';
@@ -16,6 +16,8 @@ import { ITEM_TYPES } from './validate-item.js';
 import { movesOf } from './transitions.js';
 import { listQuestions } from './questions.js';
 import { sessionActive } from './session-mark.js';
+import { agentOf } from './agent-permissions.js';
+import { settingsOf } from './config-set.js';
 
 // The version of the JSON below (Methodology §11): a board refuses one it does not know. Bump it
 // when a field changes meaning or goes away; a new field does not bump it.
@@ -128,11 +130,13 @@ async function resumeOf(projectDir, id) {
   try {
     const file = path.join(projectDir, '.gcf-session', 'runs', `${id}.agent.json`);
     const rec = JSON.parse(await readFile(file, 'utf8'));
-    if (typeof rec?.session_id !== 'string') return null;
+    // A handoff needs no session: the next run starts a fresh one from the plan.
+    if (typeof rec?.session_id !== 'string' && rec?.ended !== 'handoff') return null;
 
     return {
       ended: String(rec.ended ?? ''),
       ...(rec.resets ? { resets: String(rec.resets) } : {}),
+      ...(rec.handoffs ? { handoffs: Number(rec.handoffs) } : {}),
     };
   } catch {
     return null;
@@ -227,6 +231,15 @@ export async function board(projectDir) {
   return {
     schema: BOARD_SCHEMA,
     run_mode: config.run_mode,
+    // What the harness hands its agent runs (Harness-PRD §7): the deny rules and the context limits.
+    agent: agentOf(config),
+    // The human's settings of config.yml, each with its value and default (`gcf config set`).
+    settings: settingsOf(await readRawConfig(root)),
+    context: {
+      handoff_pct: config.context_handoff_pct,
+      window: config.context_window,
+      compact_pct: config.auto_compact_pct,
+    },
     phase: await phaseOf(projectDir),
     // A malformed block reads with fields missing (live check names it): null, not absent.
     release: releaseOf(live.release),

package/lib/config-set.js

@@ -0,0 +1,167 @@
+// `gcf config set` (GCF-PRD §12.4): the human's settings of gcf/config.yml, one key at a time,
+// so a board edits them through the core and never writes the file itself. A change is checked
+// by the same rules a read applies before it is written; the rest of the file keeps its keys
+// and comments. `phases:` and `agent:` have their own commands and are not set here.
+import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import YAML from 'yaml';
+import { commitMove } from './unit-ops.js';
+import { atomicWrite } from './safe-path.js';
+import { configOf, DEFAULT_CONFIG, gcfRoot, RUN_MODES } from './gcf-paths.js';
+
+/** @typedef {'number' | 'share' | 'mode' | 'command'} Kind */
+
+// Thrown inside the move to leave without a write or a commit.
+const NO_CHANGE = new Error('no change');
+
+/** @type {{ key: string, kind: Kind, label: string }[]} */
+export const SETTINGS = [
+  {
+    key: 'run_mode',
+    kind: 'mode',
+    label:
+      'how a run drives an item: worktree (several at once) or main (one at a time in the project folder)',
+  },
+  { key: 'dod.test', kind: 'command', label: "the project's test command for the DoD, or none" },
+  { key: 'dod.build', kind: 'command', label: "the project's build command for the DoD, or none" },
+  {
+    key: 'plan_passes',
+    kind: 'number',
+    label: 'improve passes a plan may take before the item blocks',
+  },
+  { key: 'dod_attempts', kind: 'number', label: 'DoD attempts before the item blocks' },
+  {
+    key: 'wip_built_limit',
+    kind: 'number',
+    label: 'items waiting for a verdict before new verdict work stops',
+  },
+  {
+    key: 'context_handoff_pct',
+    kind: 'share',
+    label:
+      'share of the context window at which a session hands its item to a fresh one (0: never)',
+  },
+  { key: 'context_window', kind: 'number', label: "context window in tokens (0: the model's)" },
+  {
+    key: 'auto_compact_pct',
+    kind: 'share',
+    label: 'share at which the agent compacts (0: its default; at least the handoff share + 15)',
+  },
+  { key: 'tune_limit', kind: 'number', label: 'tune verdicts an item may take' },
+  { key: 'unplayed_warn_after', kind: 'number', label: 'unplayed items before the audit warns' },
+  {
+    key: 'built_stale_after_commits',
+    kind: 'number',
+    label: 'commits after which a waiting or blocked item is stale',
+  },
+  {
+    key: 'question_stale_after_commits',
+    kind: 'number',
+    label: 'commits after which an open question is stale',
+  },
+  { key: 'context_budget', kind: 'number', label: "token budget of an item's readset" },
+  { key: 'pillars_budget', kind: 'number', label: 'token budget of PILLARS.md' },
+  {
+    key: 'envelope_default_spread',
+    kind: 'number',
+    label: 'default spread of a feel envelope around a GDD number (0.3: ±30%)',
+  },
+];
+
+const BY_KEY = new Map(SETTINGS.map((s) => [s.key, s]));
+
+/**
+ * Each setting with what the file sets (null: not set, the default holds) and its default:
+ * what a settings screen shows. `raw` is the parsed config.yml, before the defaults.
+ */
+export function settingsOf(raw) {
+  return SETTINGS.map((s) => {
+    const [head, sub] = s.key.split('.');
+    const parent = raw?.[head];
+    const value = sub
+      ? parent && typeof parent === 'object'
+        ? (parent[sub] ?? null)
+        : null
+      : (parent ?? null);
+    const def = sub ? null : head === 'run_mode' ? 'worktree' : (DEFAULT_CONFIG[head] ?? null);
+
+    return { ...s, value, default: def };
+  });
+}
+
+/** The value of `text` for a setting of `kind`; an empty number goes back to its default. */
+function valueOf(setting, text) {
+  const t = String(text ?? '').trim();
+  if (setting.kind === 'command') {
+    if (!t) throw new Error(`${setting.key}: name the command, or none`);
+
+    return t;
+  }
+  if (setting.kind === 'mode') {
+    if (!RUN_MODES.includes(t)) throw new Error(`run_mode must be ${RUN_MODES.join(' | ')}`);
+
+    return t;
+  }
+  if (!t) return null;
+  // Plain decimals only: Number() would also take 0x10, 1e3 and 0b1.
+  if (!/^\d+(\.\d+)?$/.test(t)) throw new Error(`${setting.key} must be a number, got ${t}`);
+  const n = Number(t);
+  if (!Number.isFinite(n)) throw new Error(`${setting.key} must be a number, got ${t}`);
+
+  return n;
+}
+
+/**
+ * Set one key of gcf/config.yml and commit gcf(config); a number set to nothing goes back to
+ * its default. The file is read and checked under the move's lock.
+ */
+export async function setConfig(projectDir, key, text, { commit = true } = {}) {
+  const setting = BY_KEY.get(key);
+  if (!setting) throw new Error(`no setting ${key}: ${SETTINGS.map((s) => s.key).join(' | ')}`);
+  const value = valueOf(setting, text);
+  const file = path.join(gcfRoot(projectDir), 'config.yml');
+  const keys = key.split('.');
+  let raw;
+  // A change that changes nothing (the same value, a reset of a key not set) commits nothing.
+  let unchanged = false;
+  const hash = await commitMove(projectDir, `gcf(config): ${key}`, {
+    files: [file],
+    mutate: async () => {
+      const text = existsSync(file) ? await readFile(file, 'utf8') : '';
+      const doc = YAML.parseDocument(text);
+      if (doc.errors.length) throw new Error(`gcf/config.yml: ${doc.errors[0].message}`);
+      if (!YAML.isMap(doc.contents)) doc.contents = doc.createNode({});
+      // A blank parent (`dod:` with nothing under it) is no map yet.
+      if (keys.length > 1) {
+        const parent = doc.get(keys[0], true);
+        if (
+          parent != null &&
+          !YAML.isMap(parent) &&
+          !(YAML.isScalar(parent) && parent.value == null)
+        )
+          throw new Error(`gcf/config.yml: ${keys[0]} must map its keys`);
+        if (!YAML.isMap(parent)) doc.set(keys[0], doc.createNode({}));
+      }
+      if (value === null) doc.deleteIn(keys);
+      else doc.setIn(keys, value);
+      raw = doc.toJS();
+      configOf(raw);
+      const out = doc.toString();
+      // The values, not the text: YAML's output may differ in form (a final newline, `{}`).
+      if (isDeepStrictEqual(YAML.parse(text) ?? {}, raw ?? {})) {
+        unchanged = true;
+        throw NO_CHANGE;
+      }
+      await atomicWrite(file, out);
+    },
+    commit,
+  }).catch((e) => {
+    if (e !== NO_CHANGE) throw e;
+
+    return null;
+  });
+
+  return { key, value, unchanged, settings: settingsOf(raw), hash };
+}

package/lib/gcf-paths.js

@@ -4,7 +4,7 @@ import path from 'node:path';
 import YAML from 'yaml';
 import { parse } from './frontmatter.js';
 
-const DEFAULT_CONFIG = {
+export const DEFAULT_CONFIG = {
   schema: 1,
   built_stale_after_commits: 5,
   tune_limit: 3,
@@ -16,8 +16,16 @@ const DEFAULT_CONFIG = {
   unplayed_warn_after: 5,
   plan_passes: 5,
   dod_attempts: 2,
+  // A run hands its item to a fresh session at this share of the context window (0: never);
+  // the window comes from the model unless context_window sets it (Harness-PRD §7).
+  context_handoff_pct: 60,
+  context_window: 0,
+  // CLAUDE_AUTOCOMPACT_PCT_OVERRIDE for the run (0: the agent's own default).
+  auto_compact_pct: 0,
 };
 
+const PCT_KEYS = ['context_handoff_pct', 'auto_compact_pct'];
+
 /** `gcf/` lives at the repository root (GCF-PRD §5.1). Throws when absent. */
 export function gcfRoot(projectDir = process.cwd()) {
   const root = path.join(path.resolve(projectDir), 'gcf');
@@ -40,17 +48,24 @@ function runModeOf(v = 'worktree') {
 
 /** @returns {Promise<Record<string, any>>} */
 export async function readConfig(root) {
-  const config = await readNumbers(root);
-
-  return { ...config, run_mode: runModeOf(config.run_mode) };
+  return configOf(await readRawConfig(root));
 }
 
-/** @returns {Promise<Record<string, any>>} */
-async function readNumbers(root) {
+/** config.yml as the file has it, before the defaults: `{}` when there is none. */
+export async function readRawConfig(root) {
   const file = path.join(root, 'config.yml');
-  if (!existsSync(file)) return { ...DEFAULT_CONFIG };
-  const parsed = YAML.parse(await readFile(file, 'utf8')) ?? {};
-  if (typeof parsed !== 'object' || Array.isArray(parsed))
+
+  return existsSync(file) ? (YAML.parse(await readFile(file, 'utf8')) ?? {}) : {};
+}
+
+/**
+ * The config a parsed config.yml gives, checked: defaults for what it does not set, every limit
+ * a non-negative number, the shares 0-100, the run mode one of RUN_MODES. Throws on the first
+ * key that breaks a rule. `gcf config set` checks a change with it before it writes.
+ * @returns {Record<string, any>}
+ */
+export function configOf(parsed) {
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
     throw new Error('gcf/config.yml must be a key: value mapping');
   // A blank `key:` parses as null and means "not set", like an absent key.
   const config = {
@@ -66,8 +81,18 @@ async function readNumbers(root) {
       );
     }
   }
+  for (const key of PCT_KEYS)
+    if (config[key] > 100)
+      throw new Error(`gcf/config.yml: ${key} is a share of the window, 0-100, got ${config[key]}`);
+  // A compaction before the handoff threshold shrinks the context the handoff waits for.
+  const { auto_compact_pct: compact, context_handoff_pct: handoff } = config;
+  if (compact && handoff && compact < handoff + 15)
+    throw new Error(
+      `gcf/config.yml: auto_compact_pct ${compact} must be at least context_handoff_pct + 15 ` +
+        `(${handoff + 15}), or the compaction comes before the handoff`,
+    );
 
-  return config;
+  return { ...config, run_mode: runModeOf(config.run_mode) };
 }
 
 /** Token estimate: ceil(chars/4). Stability over accuracy (GCF-PRD §9.1). */

package/lib/questions.js

@@ -8,7 +8,20 @@ import path from 'node:path';
 import { atomicWrite } from './safe-path.js';
 import { commitMove } from './unit-ops.js';
 
-const FIELDS = ['class', 'question', 'proposed', 'blocks', 'answer'];
+// A D2 carries its assumption and the trigger that brings it back; `lens`, `sections` and `sys`
+// say where a record came from: an import names its lens and the GDD sections.
+const FIELDS = [
+  'class',
+  'question',
+  'proposed',
+  'blocks',
+  'answer',
+  'assumed',
+  'until',
+  'sys',
+  'lens',
+  'sections',
+];
 
 const fileOf = (root) => path.join(root, 'open-questions.md');
 

package/package.json

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

package/templates/agents-block.md

@@ -28,6 +28,8 @@ gcf_forbidden:
 - do not give a verdict or a decision: `verdict` and `decide` belong to the human, through the gcf-verdict skill
 - 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 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
 

package/templates/config.yml

@@ -9,6 +9,14 @@ envelope_default_spread: 0.3
 unplayed_warn_after: 5
 plan_passes: 5
 dod_attempts: 2
+# Agent runs (Harness-PRD §7): the share of the context window at which a run hands its item
+# to a fresh session (0: never), the window when the model's is unknown (0: the model's), and
+# the agent's auto-compaction share (0: its default; at least the handoff share + 15).
+context_handoff_pct: 60
+context_window: 0
+auto_compact_pct: 0
+# What agent runs may not do lives in an `agent:` section that `ai-factory gcf permissions`
+# and the board write; without it the default deny groups hold.
 # The project's own commands for the auto DoD (Methodology §6); the engine does not matter.
 # gcf verify fails on an empty one; `none` says the project has no such step.
 # Phases (Methodology §10) come from code; a `phases:` list here replaces the whole set.