mirror of
https://github.com/garrytan/gstack.git
synced 2026-11-20 23:23:26 +01:00
feat(autoplan): generated DRIVER.md, the compact entry for a parent driving gstack-autoplan
autoplan/DRIVER.md (from autoplan/DRIVER.md.tmpl) is what a parent agent on any host reads instead of autoplan/SKILL.md: phase order and scope flags, the next/submit/ answer/revise/export loop with the plan-specified submit --record/--attest/ --unavailable, revise --incorporates/--withdraw and next --scaffold, the reviewer RESULT FORMAT, the gate grammar including all as-is, the run files, the result codes and the coordinator contract, every list rendered from code (117 lines). gen:skill-docs emits it as a Claude asset, so normal, out-dir and dry-run inventories and the freshness check cover it. gstack-autoplan --help and the first next print DRIVER: <root>/autoplan/DRIVER.md, resolved through an install root's recorded .source-path (new lib/source-root.ts) (field wave item 13). Intentional pin change: test/gen-skill-docs-checks.test.ts asset inventory gains autoplan/DRIVER.md. Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
This commit is contained in:
1 parent
2f65e8a810
commit
17f69f4dae
12 files changed
+410
-4
No files matched your search
@@ -0,0 +1,111 @@
|
||||
/**
|
||||
* Field wave item 13: autoplan/DRIVER.md is the compact, host-neutral entry a
|
||||
* parent agent reads to drive /autoplan through `gstack-autoplan`. It is
|
||||
* generated from autoplan/DRIVER.md.tmpl by resolvers that read the code
|
||||
* (phase order, scope flags, run files, RESULT FORMAT, result codes, the
|
||||
* coordinator contract), stays under 160 lines with no harness vocabulary,
|
||||
* is in the generator's normal, out-dir and dry-run inventories, and is
|
||||
* found from an installed root through its recorded `.source-path`.
|
||||
*/
|
||||
import { afterAll, describe, expect, test } from 'bun:test';
|
||||
import { spawnSync } from 'node:child_process';
|
||||
import * as fs from 'node:fs';
|
||||
import * as path from 'node:path';
|
||||
import { FILES } from '../lib/autoplan-state';
|
||||
import { PHASES, RESULT_FORMAT } from '../lib/autoplan-prompts';
|
||||
import { SCOPE_FLAG_TOKENS } from '../lib/autoplan-scope';
|
||||
import { COORDINATOR_CONTRACT } from '../lib/coordinator-contract';
|
||||
import { parseReply, type GateList } from '../lib/gate-list';
|
||||
import { resolveSourceRoot } from '../lib/source-root';
|
||||
import { AUTOPLAN_DRIVER_COMMANDS, DRIVER_CODES, GATE_REPLY_FORMS } from '../scripts/resolvers/autoplan-driver';
|
||||
import { runGeneration } from '../scripts/gen-skill-docs';
|
||||
import { capyHost } from './helpers/capy-host';
|
||||
import { AUTOPLAN, ROOT, SMALL_PLAN, env } from './helpers/autoplan-run-fixture';
|
||||
|
||||
const DRIVER = path.join(ROOT, 'autoplan', 'DRIVER.md');
|
||||
const doc = fs.readFileSync(DRIVER, 'utf8');
|
||||
const host = capyHost();
|
||||
afterAll(() => host.cleanup());
|
||||
const hostEnv = () => env({ ...host.env, GSTACK_STATE_ROOT: host.stateRoot, GSTACK_HOME: host.stateRoot });
|
||||
/** Flags the field-wave plan specifies for lane B-core's commands (submit --record, revise, next --scaffold); they reach --help when PR B integrates. */
|
||||
const PLAN_SPECIFIED_FLAGS = new Set(['--record', '--attest', '--unavailable', '--failed', '--scaffold', '--incorporates', '--withdraw']);
|
||||
|
||||
describe('autoplan/DRIVER.md content comes from the code', () => {
|
||||
test('phase order, scope flags, run files, RESULT FORMAT, result codes and the coordinator contract are rendered', () => {
|
||||
expect(doc).toContain(`Order: ${PHASES.join(' → ')}.`);
|
||||
for (const flag of SCOPE_FLAG_TOKENS) expect(doc).toContain(`\`${flag}\``);
|
||||
for (const file of Object.values(FILES)) expect(doc).toContain(`\`${file}\``);
|
||||
expect(doc).toContain(RESULT_FORMAT('<phase>', '<snapshot sha256>', '<result file>').replace(/^\n---\n/, '').trimEnd());
|
||||
for (const code of DRIVER_CODES) expect(doc).toMatch(new RegExp(`^- \`${code}\`: \\S`, 'm'));
|
||||
expect(doc).toContain(COORDINATOR_CONTRACT);
|
||||
for (const c of AUTOPLAN_DRIVER_COMMANDS) expect(doc).toContain(`- \`${c.cmd}\``);
|
||||
for (const f of GATE_REPLY_FORMS) expect(doc).toContain(`- \`${f.reply}\`: `);
|
||||
});
|
||||
|
||||
test('the plan-specified commands and the amendment interlock are present', () => {
|
||||
for (const token of ['submit --out <dir> --phase <p> --voice native|outside --record', '--attest "<reason>"', '--unavailable|--failed',
|
||||
'revise --out <dir> --plan <plan v2> --incorporates <decision ids>', '--withdraw <decision id>', '[--scaffold]', '`--no-dx`', '`all as-is`', 'PLAN_AMEND_PENDING', 'APPLY:']) {
|
||||
expect(doc).toContain(token);
|
||||
}
|
||||
});
|
||||
|
||||
test('at most 160 lines and no harness vocabulary', () => {
|
||||
expect(doc.split('\n').length).toBeLessThanOrEqual(160);
|
||||
for (const term of ['PreToolUse', 'PostToolUse', 'SessionStart', 'AskUserQuestion', 'Skill tool']) expect(doc).not.toContain(term);
|
||||
});
|
||||
|
||||
test('every flag it names is in gstack-autoplan --help or is a plan-specified B-core flag, and the gate forms parse', () => {
|
||||
const help = spawnSync('bun', [AUTOPLAN, '--help'], { cwd: ROOT, env: hostEnv(), encoding: 'utf8', timeout: 30_000 }).stdout;
|
||||
const commands = AUTOPLAN_DRIVER_COMMANDS.map(c => c.cmd).join(' ');
|
||||
for (const flag of new Set(commands.match(/--[a-z][a-z-]*/g)!)) {
|
||||
expect(help.includes(flag) || PLAN_SPECIFIED_FLAGS.has(flag), flag).toBe(true);
|
||||
}
|
||||
const gate: GateList = { schema_version: 1, run: 'r', gate_rev: 1, items: ['d3', 'uc1'].map(id => ({ id, title: id, recommended: 'a', kind: 'auto' as const, options: [{ key: 'a', text: 'keep' }, { key: 'b', text: 'change' }] })) };
|
||||
for (const f of GATE_REPLY_FORMS.filter(f => f.reply !== 'all as-is')) expect(parseReply(f.reply, gate, 1).valid, f.reply).toBe(true);
|
||||
expect(parseReply('yes', gate, 1).valid).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
describe('where a parent finds it', () => {
|
||||
test('gstack-autoplan --help prints DRIVER: <root>/autoplan/DRIVER.md', () => {
|
||||
const r = spawnSync('bun', [AUTOPLAN, '--help'], { cwd: ROOT, env: hostEnv(), encoding: 'utf8', timeout: 30_000 });
|
||||
expect(r.stdout.split('\n')).toContain(`DRIVER: ${DRIVER}`);
|
||||
});
|
||||
|
||||
test('the first next prints the DRIVER line once', () => {
|
||||
const dir = path.join(host.base, 'first-next');
|
||||
fs.mkdirSync(dir, { recursive: true });
|
||||
fs.writeFileSync(path.join(dir, 'plan.md'), SMALL_PLAN);
|
||||
const out = path.join(dir, 'run');
|
||||
const first = spawnSync('bun', [AUTOPLAN, 'next', '--out', out, '--plan', path.join(dir, 'plan.md'), '--no-ui'], { cwd: ROOT, env: hostEnv(), encoding: 'utf8', timeout: 120_000 });
|
||||
expect(first.status, first.stderr).toBe(0);
|
||||
expect(first.stdout.split('\n').filter(l => l.startsWith('DRIVER: '))).toEqual([`DRIVER: ${DRIVER}`]);
|
||||
const again = spawnSync('bun', [AUTOPLAN, 'next', '--out', out], { cwd: ROOT, env: hostEnv(), encoding: 'utf8', timeout: 120_000 });
|
||||
expect(again.stdout).not.toContain('DRIVER: ');
|
||||
});
|
||||
|
||||
test('an installed copy root resolves DRIVER.md through its recorded .source-path; a stale record falls back to the root', () => {
|
||||
const root = path.join(host.base, 'install-root');
|
||||
fs.mkdirSync(path.join(root, 'bin'), { recursive: true });
|
||||
fs.cpSync(path.join(ROOT, 'lib'), path.join(root, 'lib'), { recursive: true });
|
||||
fs.copyFileSync(AUTOPLAN, path.join(root, 'bin', 'gstack-autoplan'));
|
||||
fs.writeFileSync(path.join(root, '.source-path'), `${ROOT}\n`);
|
||||
const help = spawnSync('bun', [path.join(root, 'bin', 'gstack-autoplan'), '--help'], { cwd: host.base, env: hostEnv(), encoding: 'utf8', timeout: 30_000 });
|
||||
expect(help.stdout.split('\n')).toContain(`DRIVER: ${DRIVER}`);
|
||||
expect(resolveSourceRoot(root)).toBe(ROOT);
|
||||
fs.writeFileSync(path.join(root, '.source-path'), `${path.join(host.base, 'gone')}\n`);
|
||||
expect(resolveSourceRoot(root)).toBe(root);
|
||||
});
|
||||
});
|
||||
|
||||
describe('generator inventory', () => {
|
||||
test('normal, out-dir and dry-run generation all carry autoplan/DRIVER.md, and the committed file is fresh', async () => {
|
||||
const outDir = path.join(host.base, 'render');
|
||||
const written = await runGeneration({ host: 'claude', outputRoot: outDir, contentLinkRoot: null });
|
||||
expect(written.artifacts).toContainEqual({ relativePath: 'autoplan/DRIVER.md', kind: 'asset', host: 'claude' });
|
||||
expect(fs.readFileSync(path.join(outDir, 'autoplan', 'DRIVER.md'), 'utf8')).toBe(doc);
|
||||
const dry = await runGeneration({ host: 'claude', dryRun: true });
|
||||
expect(dry.artifacts).toContainEqual({ relativePath: 'autoplan/DRIVER.md', kind: 'asset', host: 'claude' });
|
||||
expect(dry.diagnostics.filter(d => d.relativePath === 'autoplan/DRIVER.md')).toEqual([]);
|
||||
}, 120_000);
|
||||
});
|
||||
+3
-1
@@ -104,7 +104,9 @@
|
||||
{ "file": "lib/pregate/checks/strays.ts", "movedFrom": "(new: pre-gate check, C8)" },
|
||||
{ "file": "lib/pregate/checks/literals.ts", "movedFrom": "(new: pre-gate check, C8)" },
|
||||
{ "file": "lib/pregate/checks/lanes.ts", "movedFrom": "(new: pre-gate check with the pipefail runner and requires-remote obligations, C8)" },
|
||||
{ "file": "lib/autoplan-scope.ts", "movedFrom": "(new: UI evidence from rendered surfaces and the plan scope marker, shared by the runner and the snapshot tool, field wave B2c)" }
|
||||
{ "file": "lib/autoplan-scope.ts", "movedFrom": "(new: UI evidence from rendered surfaces and the plan scope marker, shared by the runner and the snapshot tool, field wave B2c)" },
|
||||
{ "file": "lib/source-root.ts", "movedFrom": "(new: the source checkout behind an install root, from its recorded .source-path, field wave B2e)" },
|
||||
{ "file": "scripts/resolvers/autoplan-driver.ts", "movedFrom": "(new: renders autoplan/DRIVER.md from the runner's constants, field wave B2e)" }
|
||||
],
|
||||
"residualFiles": [
|
||||
{ "file": "scripts/test-free-shards.ts", "maxLines": 2361, "reason": "free lane policy after the shard engine took spawn, sandbox, logs, seeds and flags" },
|
||||
|
||||
@@ -46,6 +46,7 @@ describe('generator artifact and dry-run contract', () => {
|
||||
expect(generated.artifacts.filter(a => a.kind === 'asset').sort((a, b) => a.relativePath.localeCompare(b.relativePath))).toEqual([
|
||||
{ relativePath: 'review/design-checklist.md', kind: 'asset', host: 'claude' },
|
||||
{ relativePath: 'lib/dom-dump.js', kind: 'asset', host: 'claude' },
|
||||
{ relativePath: 'autoplan/DRIVER.md', kind: 'asset', host: 'claude' },
|
||||
...ALL_HOST_NAMES.filter(host => includesSkill(getHostConfig(host), 'qa')).map(host => ({
|
||||
relativePath: host === 'claude' ? 'qa/templates/functional-report-template.md'
|
||||
: `${getHostConfig(host).hostSubdir}/skills/gstack-qa/templates/functional-report-template.md`,
|
||||
|
||||
Reference in new issue
Block a user