pincer-workflow 0.6.0 → 1.0.0

package/bin/pincer.js

@@ -1,13 +1,15 @@
 #!/usr/bin/env node
-// pincer — installer for the PINCER workflow (Plan · Investigate · Narrow · Code · Evaluate · Release)
+// pincer — installer for PINCER, the harness builder
+// (blueprint · plan · narrow · code · evaluate · release · status)
 //
-//   npx pincer-workflow init      install into the current repo (asks which platform)
-//   npx pincer-workflow update    refresh an existing install, preserving local edits
+//   npx pincer-workflow init      install the kit into the current repo (asks which platforms)
+//   npx pincer-workflow update    refresh an install, preserving local edits; regenerate the project copies
 //   npx pincer-workflow doctor    check the health of an install
 //
-// No dependencies by design. The kit is markdown files; this tool only copies
-// them carefully: it never overwrites a file you edited — you get a *.new file
-// and a warning instead.
+// No dependencies by design. The kit is markdown plus a small Node core; this tool
+// copies it carefully and never overwrites a file you edited: you get a *.new file
+// and a warning instead. The install ends with one next step: run the blueprint,
+// which interviews you and writes the agreement the other stages read.
 
 import fs from 'node:fs';
 import path from 'node:path';
@@ -16,67 +18,81 @@ import readline from 'node:readline';
 import { fileURLToPath } from 'node:url';
 import { createRequire } from 'node:module';
 
-const TEMPLATE = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'template');
+const HERE = fileURLToPath(import.meta.url);
+const TEMPLATE = path.join(path.dirname(HERE), '..', 'template');
 const VERSION = createRequire(import.meta.url)('../package.json').version;
-const MANIFEST = '.pincer.json';
-const MANIFEST_SCHEMA = 2;
-
-// The playbooks, subagent rubrics and PRD/ticket templates under .claude/ are
-// the canonical kit and are read by every platform's adapter (the Codex skills
-// and Copilot prompts point at them), so they ship everywhere; only Claude
-// Code's own wiring (CLAUDE.md, settings.json, hooks) is platform-specific.
-const PLATFORM_ROOTS = {
-  common: ['AGENTS.md', 'docs/release-checklist.md', 'docs/dry-run-checklist.md', 'docs/runtime-contracts.md', 'scripts/sync-prompts.sh', 'scripts/pincer-ticket.sh', 'scripts/pincer-status.sh', 'scripts/pincer-evidence.cjs', 'scripts/pincer-runtime.cjs', 'scripts/pincer-runtime', '.claude/commands', '.claude/agents', '.claude/references'],
+const requireAbsolute = createRequire(import.meta.url);
+export const MANIFEST = '.pincer.json';
+export const MANIFEST_SCHEMA = 3;
+// Baselines recorded under these schemas were written by this installer and can be trusted.
+const TRUSTED_SCHEMAS = [2, MANIFEST_SCHEMA];
+export const PLATFORMS = ['claude', 'codex', 'copilot'];
+
+// The .claude tree is the canonical, editable project copy and every platform's
+// adapter points at it, so it ships everywhere; only Claude Code's own wiring
+// (CLAUDE.md, settings.json, hooks) is platform-specific. Only the two always-on
+// stages ship generated; the blueprint generates the stages it switches on.
+export const PLATFORM_ROOTS = {
+  common: [
+    'AGENTS.md', 'docs/engine.md', 'docs/release-checklist.md',
+    'scripts/pincer-ticket.sh', 'scripts/pincer-status.sh', 'scripts/pincer-evidence.cjs', 'scripts/pincer-blueprint.cjs', 'scripts/sync-prompts.sh', 'scripts/pincer',
+    '.claude/pincer/library', '.claude/skills/pincer-blueprint', '.claude/skills/pincer-status', '.claude/commands/pincer-blueprint.md', '.claude/commands/pincer-status.md',
+  ],
   claude: ['CLAUDE.md', '.claude/settings.json', '.claude/hooks'],
-  codex: ['.codex', '.agents'],
-  copilot: ['.github'],
+  codex: ['.codex/README.md', '.agents/skills/pincer-blueprint', '.agents/skills/pincer-status'],
+  copilot: ['.github/copilot-instructions.md', '.github/prompts/pincer-blueprint.prompt.md', '.github/prompts/pincer-status.prompt.md'],
 };
-const EXECUTABLES = ['scripts/sync-prompts.sh', 'scripts/pincer-ticket.sh', 'scripts/pincer-status.sh', '.claude/hooks/block-dangerous.sh', '.claude/hooks/ticket-guard.sh'];
-const GITIGNORE_LINES = ['.env', '.env.*', '!.env.example'];
-// The runtime's local state (attempts, locks, backups) is never tracked.
-const RUNTIME_IGNORE = '.pincer/';
+export const EXECUTABLES = ['scripts/sync-prompts.sh', 'scripts/pincer-ticket.sh', 'scripts/pincer-status.sh', 'scripts/pincer-blueprint.cjs', 'scripts/pincer-evidence.cjs', '.claude/hooks/block-dangerous.sh', '.claude/hooks/ticket-guard.sh'];
+export const GITIGNORE_LINES = ['.env', '.env.*', '!.env.example'];
+// Files an earlier kit installed that this version no longer ships. Never deleted
+// here; doctor names them when neither the manifest nor the generator claims them.
+const OBSOLETE = [
+  'scripts/pincer-runtime.cjs', 'scripts/pincer-runtime', 'scripts/pincer-ticket-lib.sh', 'docs/runtime-contracts.md', 'docs/dry-run-checklist.md', '.claude/references',
+  '.claude/commands/pincer-plan.md', '.claude/commands/pincer-narrow.md', '.claude/commands/pincer-code.md', '.claude/commands/pincer-evaluate.md', '.claude/commands/pincer-release.md',
+];
 
 const sha = (buf) => crypto.createHash('sha256').update(buf).digest('hex');
+const isPlainObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
 
 function walk(root, rel = '') {
   const abs = path.join(root, rel);
   if (!fs.statSync(abs).isDirectory()) return [rel];
-  return fs
-    .readdirSync(abs)
-    .filter((n) => n !== '.DS_Store')
-    .flatMap((n) => walk(root, rel ? path.join(rel, n) : n));
+  return fs.readdirSync(abs).filter((n) => n !== '.DS_Store').flatMap((n) => walk(root, rel ? path.join(rel, n) : n));
 }
 
-function filesFor(platforms) {
+export function filesFor(platforms) {
   const roots = [...PLATFORM_ROOTS.common, ...platforms.flatMap((p) => PLATFORM_ROOTS[p])];
   return roots.flatMap((r) => walk(TEMPLATE, r)).sort();
 }
 
+function fail(msg) {
+  console.error(`pincer: ${msg}`);
+  process.exit(1);
+}
+
 function readManifest(dir) {
   const p = path.join(dir, MANIFEST);
   if (!fs.existsSync(p)) return null;
-  try {
-    const data = JSON.parse(fs.readFileSync(p, 'utf8'));
-    if (!data || !Array.isArray(data.platforms) || !data.platforms.length ||
-        !data.platforms.every(p => ['claude', 'codex', 'copilot'].includes(p)) ||
-        !data.files || typeof data.files !== 'object' || Array.isArray(data.files) ||
-        Object.keys(data.files).some(p => path.isAbsolute(p) || p.split(/[\\/]/).includes('..')) ||
-        (data.schema !== undefined && data.schema !== MANIFEST_SCHEMA)) {
-      fail(`${MANIFEST} has an unsupported or invalid schema — restore a valid manifest before updating.`);
-    }
-    return data;
-  } catch {
-    fail(`${MANIFEST} exists but is not valid JSON — fix or remove it first.`);
-  }
+  let data;
+  try { data = JSON.parse(fs.readFileSync(p, 'utf8')); } catch { fail(`${MANIFEST} exists but is not valid JSON — fix or remove it first.`); }
+  const unsafe = (f) => path.isAbsolute(f) || /^[A-Za-z]:/.test(f) || f.split(/[\\/]/).includes('..');
+  const invalid = !data || typeof data !== 'object' || Array.isArray(data)
+    || !Array.isArray(data.platforms) || !data.platforms.length || !data.platforms.every((x) => PLATFORMS.includes(x))
+    || !data.files || typeof data.files !== 'object' || Array.isArray(data.files)
+    || Object.keys(data.files).some(unsafe)
+    || (data.generated !== undefined && (!isPlainObject(data.generated) || Object.keys(data.generated).some(unsafe)))
+    || (data.schema !== undefined && !TRUSTED_SCHEMAS.includes(data.schema));
+  if (invalid) fail(`${MANIFEST} has an unsupported or invalid schema — restore a valid manifest before updating.`);
+  return data;
 }
 
-function writeManifest(dir, platforms, hashes) {
-  const data = { schema: MANIFEST_SCHEMA, version: VERSION, platforms, files: hashes };
+function writeManifest(dir, platforms, hashes, generated) {
+  const data = { schema: MANIFEST_SCHEMA, version: VERSION, platforms, files: hashes, generated: isPlainObject(generated) ? generated : {} };
   fs.writeFileSync(path.join(dir, MANIFEST), JSON.stringify(data, null, 2) + '\n');
 }
 
-// Preserve in-progress merges too. Reuse an identical proposal, never replace
-// a different existing sidecar (including one left by an earlier release).
+// Preserve in-progress merges too. Reuse an identical proposal, never replace a
+// different existing sidecar (including one left by an earlier release).
 function writeProposal(dest, content) {
   const base = dest + '.new';
   let proposal = base;
@@ -90,91 +106,135 @@ function writeProposal(dest, content) {
   return proposal;
 }
 
-// Copies template files into dir. `baseline` (manifest hashes) tells an update
-// which existing files are unmodified and therefore safe to refresh.
-function install(dir, platforms, baseline) {
+// Copies the template files into dir. `baseline` (the manifest's hashes) tells an
+// update which existing files are unmodified and therefore safe to refresh.
+function install(dir, platforms, baseline, generated) {
   const results = { written: [], skipped: [], conflicted: [] };
   const hashes = {};
-
   for (const rel of filesFor(platforms)) {
     const src = fs.readFileSync(path.join(TEMPLATE, rel));
     const dest = path.join(dir, rel);
     hashes[rel] = sha(src);
-
     if (!fs.existsSync(dest)) {
       fs.mkdirSync(path.dirname(dest), { recursive: true });
       fs.writeFileSync(dest, src);
       results.written.push(rel);
       continue;
     }
-
     const current = fs.readFileSync(dest);
     if (sha(current) === sha(src)) {
       results.skipped.push(rel);
     } else if (baseline && baseline[rel] === sha(current)) {
-      // untouched since install — safe to refresh with the new template version
-      fs.writeFileSync(dest, src);
+      fs.writeFileSync(dest, src); // untouched since install: safe to refresh
       results.written.push(rel);
     } else {
       const proposal = writeProposal(dest, src);
-      // Only a version actually installed by us grants overwrite permission.
-      // null means we have never established a trusted upstream baseline.
+      // Only a version this installer wrote grants overwrite permission later;
+      // null means no trusted upstream baseline was ever established.
       hashes[rel] = baseline?.[rel] ?? null;
       results.conflicted.push({ rel, proposal: path.relative(dir, proposal) });
     }
   }
-
   for (const rel of EXECUTABLES) {
     const p = path.join(dir, rel);
     if (fs.existsSync(p)) fs.chmodSync(p, 0o755);
   }
-
   ensureGitignore(dir);
-  writeManifest(dir, platforms, hashes);
+  writeManifest(dir, platforms, hashes, generated);
   return results;
 }
 
 function ensureGitignore(dir) {
   const p = path.join(dir, '.gitignore');
-  let existing = fs.existsSync(p) ? fs.readFileSync(p, 'utf8') : '';
+  const existing = fs.existsSync(p) ? fs.readFileSync(p, 'utf8') : '';
   const have = new Set(existing.split('\n').map((l) => l.trim()));
   const missing = GITIGNORE_LINES.filter((l) => !have.has(l));
-  if (missing.length) {
-    const lead = existing && !existing.endsWith('\n') ? '\n' : '';
-    fs.appendFileSync(p, `${lead}${existing ? '\n' : ''}# secrets (added by pincer init)\n${missing.join('\n')}\n`);
-    existing = fs.readFileSync(p, 'utf8');
-  }
-  if (![RUNTIME_IGNORE, '/.pincer/', '.pincer'].some((l) => have.has(l))) {
-    const lead = existing && !existing.endsWith('\n') ? '\n' : '';
-    fs.appendFileSync(p, `${lead}${existing ? '\n' : ''}# pincer runtime state (added by pincer init)\n${RUNTIME_IGNORE}\n`);
-  }
+  if (!missing.length) return;
+  const lead = existing && !existing.endsWith('\n') ? '\n' : '';
+  fs.appendFileSync(p, `${lead}${existing ? '\n' : ''}# secrets (added by pincer init)\n${missing.join('\n')}\n`);
 }
 
 function report({ written, skipped, conflicted }) {
   if (written.length) console.log(`  wrote    ${written.length} file(s)`);
   if (skipped.length) console.log(`  skipped  ${skipped.length} file(s) already up to date`);
-  for (const { rel, proposal } of conflicted) {
-    console.log(`  CONFLICT ${rel} — local content preserved; the new version is at ${proposal}`);
+  for (const { rel, proposal } of conflicted) console.log(`  CONFLICT ${rel} — local content preserved; the new version is at ${proposal}`);
+  if (conflicted.length) console.log('\n  Review and merge each reported proposal, then remove the resolved sidecars.');
+}
+
+// The installed engine, loaded from the project so an update uses the version it just wrote.
+function installedEngine(dir) {
+  let models = null;
+  try { models = requireAbsolute(path.join(dir, 'scripts/pincer/models.cjs')); } catch { models = null; } // absent before 1.1
+  return {
+    harness: requireAbsolute(path.join(dir, 'scripts/pincer/harness.cjs')),
+    generate: requireAbsolute(path.join(dir, 'scripts/pincer/generate.cjs')),
+    models,
+  };
+}
+// What the library or its table could not provide, as one sentence.
+function missingText(name) {
+  if (name === 'models.json') return 'the library has no models.json; run pincer update';
+  if (name.startsWith('models.json:')) return `${name} — fix the library table; after an update the upstream copy is beside it as models.json.new`;
+  if (name.startsWith('models/')) { const [platform, tier] = name.slice('models/'.length).split('/'); return `the library table has no ${platform} value for tier ${tier}; set models.map.${platform}.${tier} in harness.json`; }
+  if (name.startsWith('agents/')) return `the library has no agent ${name.slice('agents/'.length)}`;
+  return `the library has no stage ${name}`;
+}
+// The tiers in use and what each installed platform will run them on.
+function reportModels(dir, engine, harness, platforms, check) {
+  const { models } = engine;
+  if (!models) { check(false, 'models checked', 'could not load scripts/pincer/models.cjs — run: pincer update'); return; }
+  const library = engine.generate.libraryDir(dir);
+  const read = models.readTable(library);
+  if (!read.ok) {
+    if (read.missing) check(false, 'library has models.json', 'run: pincer update');
+    else check(false, 'library table readable', `${read.problem} — fix it; after an update the upstream copy is beside it as models.json.new`);
+    return;
   }
-  if (conflicted.length) {
-    console.log('\n  Review and merge each reported proposal, then remove the resolved sidecars.');
+  const table = models.overlay(read.table, harness.models.map);
+  const eff = models.effective(harness, library);
+  const inUse = new Set([...Object.values(eff.stages), ...Object.values(eff.agents)].map((entry) => entry.tier).filter((tier) => tier && tier !== 'inherit'));
+  const tiers = engine.harness.MAP_TIERS.filter((tier) => inUse.has(tier));
+  if (!tiers.length) console.log("  models  no tier in use; the session's model everywhere");
+  for (const platform of tiers.length ? platforms : []) {
+    const pairs = tiers.map((tier) => [tier, models.modelFor(table, platform, tier)]);
+    console.log(`  models  ${platform}: ${pairs.filter(([, value]) => value).map(([tier, value]) => `${tier}=${value}`).join(', ')}`);
+    for (const [tier, value] of pairs) if (!value) check(false, `tier ${tier} has a ${platform} value`, `set models.map.${platform}.${tier} in harness.json or update the kit`);
   }
+  if (platforms.includes('codex') && fs.existsSync(path.join(dir, '.codex/agents'))) console.log('  note  Codex loads .codex/ only in a trusted project');
 }
 
-function nextSteps(platforms) {
-  console.log('\nNext steps:');
-  if (platforms.includes('claude')) {
-    console.log('  Claude Code   start `claude` in this repo and run /pincer-plan <brief>');
-  }
-  if (platforms.includes('codex')) {
-    console.log('  Codex CLI     start `codex` in this repo and type $pincer-plan <brief>  (skills load from .agents/skills/; posture notes in .codex/README.md)');
+// With an agreement in place the project's stage copies come from the library just
+// installed; the generator keeps edited copies and leaves .new sidecars beside them.
+function regenerate(dir) {
+  let engine;
+  try { engine = installedEngine(dir); } catch (error) { console.log(`  note  could not load the installed engine (${error.message}); run scripts/sync-prompts.sh yourself`); return; }
+  const loaded = engine.harness.load(dir);
+  if (!loaded.ok) {
+    console.log(loaded.missing
+      ? '  note  no harness.json yet — run /pincer-blueprint; it generates the project copies of the stages it switches on'
+      : `  note  harness.json: ${loaded.message} — fix it, then run scripts/sync-prompts.sh to regenerate the project copies`);
+    return;
   }
-  if (platforms.includes('copilot')) {
-    console.log('  Copilot       enable "chat.promptFiles": true in VS Code settings, then /pincer-plan in chat');
+  let result;
+  try { result = engine.generate.generate(dir, { harness: loaded.harness }); } catch (error) {
+    console.log(`  note  ${error.message} — fix the library file, then run scripts/sync-prompts.sh to regenerate the project copies`);
+    return;
   }
-  console.log('  All rules live in AGENTS.md — fill in its Conventions section once you know the stack.');
-  const statusCmd = platforms.every((p) => p === 'codex') ? '$pincer-status' : platforms.includes('codex') ? '/pincer-status, $pincer-status on Codex' : '/pincer-status';
-  console.log(`  Any session     scripts/pincer-status.sh shows where the workflow stands (also ${statusCmd})`);
+  for (const rel of result.written) console.log(`  generated ${rel}`);
+  for (const rel of result.conflicted) console.log(`  kept ${rel} (edited; fresh copy in ${rel}.new)`);
+  for (const rel of result.retained) console.log(`  kept ${rel} (edited; not removed)`);
+  for (const rel of result.removed) console.log(`  removed ${rel}`);
+  for (const rel of result.unsafe) console.log(`  note  ignored unsafe baseline path ${rel} in ${MANIFEST}`);
+  for (const name of result.missing) console.log(`  note  ${missingText(name)}`);
+  console.log(`  generated: ${result.written.length} written, ${result.skipped.length} unchanged, ${result.conflicted.length} kept, ${result.removed.length} removed`);
+}
+
+function nextSteps(platforms) {
+  console.log('\nNext: run the blueprint. It looks at the repository, interviews you, and writes the agreement (harness.json and the top of AGENTS.md).');
+  if (platforms.includes('claude')) console.log('  Claude Code   start `claude` in this repo and run /pincer-blueprint');
+  if (platforms.includes('codex')) console.log('  Codex CLI     start `codex` in this repo and type $pincer-blueprint  (skills load from .agents/skills/; posture notes in .codex/README.md)');
+  if (platforms.includes('copilot')) console.log('  Copilot       enable "chat.promptFiles": true in VS Code settings, then /pincer-blueprint in chat');
+  console.log('  Any session   scripts/pincer-status.sh shows where the work stands and the next command');
 }
 
 async function askPlatforms() {
@@ -183,7 +243,7 @@ async function askPlatforms() {
   console.log('Which platform(s) do you use?\n  1) Claude Code\n  2) Codex CLI\n  3) GitHub Copilot\n  4) all of them');
   const answer = (await q('Choose [1-4, default 4]: ')).trim() || '4';
   rl.close();
-  const map = { 1: ['claude'], 2: ['codex'], 3: ['copilot'], 4: ['claude', 'codex', 'copilot'] };
+  const map = { 1: ['claude'], 2: ['codex'], 3: ['copilot'], 4: [...PLATFORMS] };
   return map[answer] || fail(`invalid choice: ${answer}`);
 }
 
@@ -191,25 +251,18 @@ function parsePlatformFlag(args) {
   const i = args.indexOf('--platform');
   if (i === -1) return null;
   const value = args[i + 1] || '';
-  if (value === 'all') return ['claude', 'codex', 'copilot'];
+  if (value === 'all') return [...PLATFORMS];
   const list = value.split(',').map((s) => s.trim());
-  if (list.every((p) => ['claude', 'codex', 'copilot'].includes(p)) && list.length) return list;
+  if (list.length && list.every((p) => PLATFORMS.includes(p))) return [...new Set(list)];
   fail(`--platform must be claude, codex, copilot (comma-separated) or all — got "${value}"`);
 }
 
-function fail(msg) {
-  console.error(`pincer: ${msg}`);
-  process.exit(1);
-}
-
 async function cmdInit(args) {
   const dir = process.cwd();
-  if (readManifest(dir)) {
-    fail(`this repo already has PINCER installed (${MANIFEST} exists) — use \`pincer update\`.`);
-  }
-  const platforms = parsePlatformFlag(args) || (process.stdin.isTTY ? await askPlatforms() : ['claude', 'codex', 'copilot']);
+  if (readManifest(dir)) fail(`this repo already has PINCER installed (${MANIFEST} exists) — use \`pincer update\`.`);
+  const platforms = parsePlatformFlag(args) || (process.stdin.isTTY ? await askPlatforms() : [...PLATFORMS]);
   console.log(`\nInstalling PINCER v${VERSION} for: ${platforms.join(', ')}\n`);
-  report(install(dir, platforms, null));
+  report(install(dir, platforms, null, {}));
   nextSteps(platforms);
 }
 
@@ -218,17 +271,19 @@ async function cmdUpdate() {
   const manifest = readManifest(dir);
   if (!manifest) fail(`no ${MANIFEST} here — run \`pincer init\` first.`);
   console.log(`\nUpdating PINCER ${manifest.version} -> ${VERSION} for: ${manifest.platforms.join(', ')}\n`);
-  // v1 manifests could adopt a local edit as their baseline. There is no safe
-  // way to distinguish those from upstream files after the fact.
-  const baseline = manifest.schema === MANIFEST_SCHEMA ? manifest.files : null;
+  // A manifest without a schema could have adopted a local edit as its baseline;
+  // there is no safe way to tell those from upstream files after the fact.
+  const baseline = TRUSTED_SCHEMAS.includes(manifest.schema) ? manifest.files : null;
   if (!baseline) console.log('  Legacy baselines are untrusted; differing files will be preserved for review.');
-  report(install(dir, manifest.platforms, baseline));
+  report(install(dir, manifest.platforms, baseline, manifest.generated));
+  regenerate(dir);
 }
 
 function cmdDoctor() {
   const dir = process.cwd();
   const manifest = readManifest(dir);
   if (!manifest) fail(`no ${MANIFEST} here — run \`pincer init\` first.`);
+  const generated = isPlainObject(manifest.generated) ? manifest.generated : {};
   let problems = 0;
   const check = (ok, label, hint) => {
     console.log(`  ${ok ? 'ok  ' : 'FAIL'}  ${label}${ok || !hint ? '' : ` — ${hint}`}`);
@@ -238,78 +293,40 @@ function cmdDoctor() {
   console.log(`\nPINCER doctor (installed ${manifest.version}, this tool ${VERSION})\n`);
   const missing = Object.keys(manifest.files).filter((rel) => !fs.existsSync(path.join(dir, rel)));
   check(missing.length === 0, 'all installed files present', `missing: ${missing.join(', ')}`);
-
   for (const rel of EXECUTABLES) {
     const p = path.join(dir, rel);
-    if (!fs.existsSync(p)) continue;
-    check(!!(fs.statSync(p).mode & 0o100), `${rel} is executable`, `run: chmod +x ${rel}`);
-  }
-
-  const gi = fs.existsSync(path.join(dir, '.gitignore')) ? fs.readFileSync(path.join(dir, '.gitignore'), 'utf8') : '';
-  check(GITIGNORE_LINES.every((l) => gi.split('\n').map((s) => s.trim()).includes(l)),
-    '.gitignore covers .env files', 'add: .env / .env.* / !.env.example');
-  if (![RUNTIME_IGNORE, '/.pincer/', '.pincer'].some((l) => gi.split('\n').map((s) => s.trim()).includes(l))) {
-    console.log(`  note  .gitignore does not list ${RUNTIME_IGNORE} (runtime state); \`pincer update\`, \`register\` or \`migrate --apply\` adds it`);
+    if (fs.existsSync(p)) check(!!(fs.statSync(p).mode & 0o100), `${rel} is executable`, `run: chmod +x ${rel}`);
   }
-
+  const gi = fs.existsSync(path.join(dir, '.gitignore')) ? fs.readFileSync(path.join(dir, '.gitignore'), 'utf8').split('\n').map((s) => s.trim()) : [];
+  check(GITIGNORE_LINES.every((l) => gi.includes(l)), '.gitignore covers .env files', 'add: .env / .env.* / !.env.example');
   const stale = fs.existsSync(TEMPLATE) && manifest.version !== VERSION;
   check(!stale, `install is current (v${manifest.version})`, 'run: pincer update');
 
-  // The runtime ships with every layout; a project with legacy receipts and no
-  // change binding can migrate explicitly (never silently here).
-  const runtimeFiles = Object.keys(manifest.files).filter((rel) => rel === 'scripts/pincer-runtime.cjs' || rel.startsWith('scripts/pincer-runtime/'));
-  if (runtimeFiles.length) {
-    const missingRuntime = runtimeFiles.filter((rel) => !fs.existsSync(path.join(dir, rel)));
-    check(missingRuntime.length === 0, 'runtime files present', `missing: ${missingRuntime.join(', ')} — run: pincer update`);
-  }
-  // Files an earlier kit installed that this version no longer ships stay on disk
-  // (the installer never deletes); name them so they can be removed by hand.
-  const OBSOLETE = ['scripts/pincer-ticket-lib.sh'];
-  const obsolete = OBSOLETE.filter((rel) => fs.existsSync(path.join(dir, rel)) && !(rel in manifest.files));
-  if (obsolete.length) console.log(`  note  obsolete kit file(s) from an earlier version, safe to delete: ${obsolete.join(', ')}`);
-
-  const ticketsDir = path.join(dir, 'tickets');
-  const legacyReceipts = fs.existsSync(ticketsDir)
-    ? fs.readdirSync(ticketsDir).filter((n) => /^T-\d+.*\.md$/.test(n)).filter((n) => /^(verified|last_check):/m.test(fs.readFileSync(path.join(ticketsDir, n), 'utf8')))
-    : [];
-  const bindingsDir = path.join(dir, '.prd', 'changes');
-  const bindingFiles = fs.existsSync(bindingsDir) ? fs.readdirSync(bindingsDir).filter((n) => n.endsWith('.json')) : [];
-  const hasBinding = bindingFiles.length > 0;
-  // A v0.5.0 binding (schema 1) converts explicitly into a schema 2 change record; doctor only reports it.
-  const oldBindings = bindingFiles.filter((n) => { try { return JSON.parse(fs.readFileSync(path.join(bindingsDir, n), 'utf8')).schema === 1; } catch { return false; } });
-  for (const n of oldBindings) {
-    let prd = '.prd/prd-vN.md';
-    try { prd = JSON.parse(fs.readFileSync(path.join(bindingsDir, n), 'utf8')).prd || prd; } catch { /* reported above by the runtime */ }
-    console.log(`  note  migration to change records available: .prd/changes/${n} is a v0.5.0 binding (schema 1) — preview with: node scripts/pincer-runtime.cjs migrate --preview --prd ${prd}`);
-  }
-  // A schema 2 change record beside an authored coverage map can adopt strict coverage explicitly; doctor only reports it.
-  for (const n of bindingFiles) {
-    let doc = null;
-    try { doc = JSON.parse(fs.readFileSync(path.join(bindingsDir, n), 'utf8')); } catch { doc = null; }
-    if (!doc || doc.schema !== 2) continue;
-    const id = n.replace(/\.json$/, '');
-    if (fs.existsSync(path.join(dir, '.prd', 'coverage', `${id}.json`))) console.log(`  note  strict coverage adoption available: .prd/coverage/${id}.json exists and .prd/changes/${n} is a schema 2 record — preview with: node scripts/pincer-runtime.cjs coverage adopt --preview --change ${id}`);
-  }
-  if (legacyReceipts.length && !hasBinding) {
-    const prdDir = path.join(dir, '.prd');
-    const prds = fs.existsSync(prdDir) ? fs.readdirSync(prdDir).map((n) => n.match(/^prd-v(\d+)\.md$/)).filter(Boolean).map((m) => Number(m[1])) : [];
-    const latest = prds.length ? `.prd/prd-v${Math.max(...prds)}.md` : '.prd/prd-vN.md';
-    console.log(`  note  migration available: ${legacyReceipts.length} ticket(s) carry legacy receipts and no change binding exists — preview with: node scripts/pincer-runtime.cjs migrate --preview --prd ${latest}`);
+  // The agreement, checked with the engine this install carries.
+  if (!fs.existsSync(path.join(dir, 'harness.json'))) {
+    console.log('  note  no harness.json yet — run /pincer-blueprint');
+  } else {
+    try {
+      const engine = installedEngine(dir);
+      const loaded = engine.harness.load(dir);
+      check(loaded.ok, loaded.ok ? 'harness.json valid' : `harness.json: ${loaded.message}`);
+      if (loaded.ok) reportModels(dir, engine, loaded.harness, manifest.platforms, check);
+    } catch (error) {
+      check(false, 'harness.json checked', `could not load scripts/pincer/harness.cjs (${error.message}) — run: pincer update`);
+    }
   }
 
+  const obsolete = OBSOLETE.filter((rel) => fs.existsSync(path.join(dir, rel)) && !(rel in manifest.files) && !(rel in generated));
+  if (obsolete.length) console.log(`  note  obsolete kit file(s) from an earlier version, safe to delete: ${obsolete.join(', ')}`);
   const edited = Object.entries(manifest.files)
     .filter(([rel, h]) => fs.existsSync(path.join(dir, rel)) && sha(fs.readFileSync(path.join(dir, rel))) !== h)
     .map(([rel]) => rel);
-  if (edited.length) {
-    console.log(`  note  locally edited (kept as-is on update): ${edited.join(', ')}`);
-  }
+  if (edited.length) console.log(`  note  locally edited (kept as-is on update): ${edited.join(', ')}`);
 
-  const leftovers = [...new Set([...walk(TEMPLATE), ...Object.keys(manifest.files)])].flatMap(rel => {
+  const leftovers = [...new Set([...walk(TEMPLATE), ...Object.keys(manifest.files), ...Object.keys(generated)])].flatMap((rel) => {
     const parent = path.dirname(path.join(dir, rel));
     const base = path.basename(rel) + '.new';
-    return fs.existsSync(parent) ? fs.readdirSync(parent)
-      .filter(name => name === base || name.startsWith(base + '.'))
-      .map(name => path.join(parent, name)) : [];
+    return fs.existsSync(parent) ? fs.readdirSync(parent).filter((name) => name === base || name.startsWith(base + '.')).map((name) => path.join(parent, name)) : [];
   });
   check(leftovers.length === 0, 'no unmerged *.new files', leftovers.map((p) => path.relative(dir, p)).join(', '));
 
@@ -317,18 +334,24 @@ function cmdDoctor() {
   process.exit(problems ? 1 : 0);
 }
 
-const [cmd, ...rest] = process.argv.slice(2);
-if (cmd === 'init') await cmdInit(rest);
-else if (cmd === 'update') await cmdUpdate();
-else if (cmd === 'doctor') cmdDoctor();
-else {
-  console.log(`pincer-workflow v${VERSION} — PRD-driven agentic delivery workflow
+function usage() {
+  console.log(`pincer-workflow v${VERSION} — a harness builder for AI coding agents
 
 Usage:
   npx pincer-workflow init [--platform claude|codex|copilot|all]
   npx pincer-workflow update
   npx pincer-workflow doctor
 
-Docs: https://github.com/orchestratedbyalex/pincer-workflow`);
-  process.exit(cmd ? 1 : 0);
+After init, run the blueprint (/pincer-blueprint or $pincer-blueprint): it writes the
+agreement the other stages read. Docs: https://github.com/orchestratedbyalex/pincer-workflow`);
+}
+
+// Run the command only when this file is the program, not when a test imports it.
+const invoked = process.argv[1] && (() => { try { return fs.realpathSync(process.argv[1]) === fs.realpathSync(HERE); } catch { return false; } })();
+if (invoked) {
+  const [cmd, ...rest] = process.argv.slice(2);
+  if (cmd === 'init') await cmdInit(rest);
+  else if (cmd === 'update') await cmdUpdate();
+  else if (cmd === 'doctor') cmdDoctor();
+  else { usage(); process.exit(cmd ? 1 : 0); }
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pincer-workflow",
-  "version": "0.6.0",
-  "description": "PINCER — a PRD-driven agentic delivery workflow for Claude Code, Codex CLI, and GitHub Copilot. Plan · Investigate · Narrow · Code · Evaluate · Release.",
+  "version": "1.0.0",
+  "description": "PINCER \u2014 a harness builder for AI coding agents. It looks at your project, interviews you, writes the project agreement, and runs the pipeline that agreement describes. Claude Code, Codex CLI and GitHub Copilot.",
   "bin": {
     "pincer": "bin/pincer.js"
   },
@@ -14,7 +14,8 @@
     "node": ">=22"
   },
   "scripts": {
-    "test": "node test/smoke.test.js && node test/installer.test.js && node test/ticket.test.js && node test/validation.test.js && node test/verification.test.js && node test/behavioral-verification.test.js && node test/evidence.test.js && node test/candidate.test.js && node test/recovery.test.js && node test/hooks.test.js && node test/runtime-parse.test.js && node test/coverage-inventory.test.js && node test/coverage-map.test.js && node test/coverage-agreement.test.js && node test/coverage-adoption.test.js && node test/coverage-readiness.test.js && node test/coverage-impact.test.js && node test/coverage-checks.test.js && node test/coverage-evidence.test.js && node test/coverage-reports.test.js && node test/runtime-identity.test.js && node test/change-registry.test.js && node test/change-selection.test.js && node test/change-agreement.test.js && node test/change-authorization.test.js && node test/change-lifecycle.test.js && node test/change-command-gates.test.js && node test/change-evidence-context.test.js && node test/change-evaluations.test.js && node test/change-resume.test.js && node test/change-trial-record.test.js && node test/change-review-packet.test.js && node test/runtime-state.test.js && node test/change-transactions.test.js && node test/runtime-status.test.js && node test/runtime-output.test.js && node test/runtime-runner.test.js && node test/runtime-lifecycle.test.js && node test/runtime-migrate.test.js && node test/change-migration.test.js && node test/runtime-evidence.test.js && node test/workflow.test.js && node test/contracts.test.js && node test/change-contracts.test.js && node test/coverage-contracts.test.js && node test/distribution.test.js && node test/change-distribution.test.js && node test/coverage-distribution.test.js && node test/delivery-benchmark.test.js && node test/coverage-trial-record.test.js && node test/coverage-review-packet.test.js"
+    "test": "node test/run.js",
+    "generate": "node template/scripts/pincer/cli.cjs --root template generate --harness test/fixtures/always-on.harness.json --platform all --overwrite"
   },
   "keywords": [
     "claude-code",

package/template/.agents/skills/pincer-blueprint/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: pincer-blueprint
+description: "Look at the project, interview the person, write the harness agreement (harness.json and the top of AGENTS.md) and generate the project's stage copies"
+---
+<!-- Generated by scripts/pincer/cli.cjs generate from .claude/skills/pincer-blueprint/SKILL.md — edit the project copy, not this file -->
+
+# Blueprint
+
+The first stage and the only one that writes the agreement. It is always on. It
+reads the repository, decides greenfield or brownfield and says why, interviews
+the person one question at a time through the six sections, writes `harness.json`
+and the agreement at the top of `AGENTS.md`, and generates the project's copies of
+the stages it switched on. Scripts do the reading and the writing so they can be
+tested; the session does the asking.
+
+Rules for the whole interview: one question at a time. Options listed, the
+recommended one first, each explained in a sentence. Every answer recon could
+pre-fill is presented as "I see X; is that right?", never assumed. `open` is always
+an allowed answer and is written as open, never guessed. Record what the person
+says; add no tool, step or role they did not choose.
+
+## Reads
+- `harness.json`, if present: this is a re-run (see the last paragraph of Steps).
+- The recon report from `node scripts/pincer-blueprint.cjs recon --json --network`:
+  `kind`, `reasons`, `facts`, `prefill`, `unavailable`.
+- `AGENTS.md` as it stands: the standing rules and the conventions below the markers stay.
+- The formats under `.claude/skills/pincer-blueprint/formats/`:
+  `.claude/skills/pincer-blueprint/formats/harness.md` (every field of `harness.json`)
+  and `.claude/skills/pincer-blueprint/formats/roster-rules.md` (how the roster follows the answers).
+- The prompts under `.claude/skills/pincer-blueprint/prompts/`, one per question, named in the steps.
+- `the text that follows the `$pincer-blueprint` mention, if any (when omitted, use the skill's documented default)`: notes the person gave up front. Treat them as pre-filled answers to confirm, not as answers.
+
+## Steps
+1. [session] Run `scripts/pincer-status.sh --stage blueprint` (always `on`; the plain report also says whether `harness.json` exists), then `node scripts/pincer-blueprint.cjs recon --json --network` and read the whole result: `kind`, `reasons`, `facts`, `prefill`, `unavailable`.
+2. [session] State the kind and the reasons in one paragraph with `.claude/skills/pincer-blueprint/prompts/confirm-kind.md`, naming what recon could not see. Ask the person to confirm or correct. Their word wins over recon.
+3. [session] Interview, one section at a time and one question at a time, in this order, each with its prompt: Systems (`.claude/skills/pincer-blueprint/prompts/q-systems.md`), Current pipeline (`.claude/skills/pincer-blueprint/prompts/q-pipeline.md`), Handoff artifacts (`.claude/skills/pincer-blueprint/prompts/q-handoffs.md`), Simplify (`.claude/skills/pincer-blueprint/prompts/q-simplify.md`), Responsibility (`.claude/skills/pincer-blueprint/prompts/q-responsibility.md`), Repo (`.claude/skills/pincer-blueprint/prompts/q-repo.md`). Fill each prompt's slots from recon and from earlier answers before asking.
+4. [session] Propose the roster from the answers and recon by applying `.claude/skills/pincer-blueprint/formats/roster-rules.md`; ask the person to confirm with `.claude/skills/pincer-blueprint/prompts/q-roster.md`.
+5. [session] Propose the model tier per role from the "Model tiers" section of `.claude/skills/pincer-blueprint/formats/roster-rules.md` and ask the person to confirm with `.claude/skills/pincer-blueprint/prompts/q-models.md`; record the answers under `models`.
+6. [session] Write the answers as `harness.json` in the shape `.claude/skills/pincer-blueprint/formats/harness.md` describes: start from recon's `prefill`, put every unanswered item in `open`, then run `node scripts/pincer-blueprint.cjs write`. On validation problems, fix the file and run it again. Never hand-edit `AGENTS.md` between the markers.
+7. [session] Show the agreement from `AGENTS.md` (the text between the markers) and ask for corrections. Apply them to `harness.json` and run `write` again. One round.
+8. [session] Name the first job with `.claude/skills/pincer-blueprint/prompts/first-job.md`: brownfield, the smallest real change that recon or the open items point at; greenfield, the setup job. Put it in `firstJob`, run `write` again, and say that the first run through the pipeline is the trace to revisit this agreement with.
+9. [session] Print the output of `scripts/pincer-status.sh` and stop. The next command is on its last line.
+
+Re-run: when `harness.json` already exists, run recon, list what differs between the
+file and what recon sees (kind, remote, CI, checks, people, merge style), ask only
+about those and about anything the person wants to change, then continue from step 6.
+When the file has no `models` key, propose the tiers once (step 5); otherwise ask only
+when the person wants to change them.
+
+## Checks
+- `node scripts/pincer-blueprint.cjs write` exits 0 and prints `wrote harness.json` and `wrote AGENTS.md`.
+- The agreement between the markers has the six headings in order and names the project.
+- Every pre-filled answer was confirmed or corrected by the person; no cell was invented to look complete. `open` is the honest cell.
+- `scripts/pincer-status.sh` prints the project's name and a `Stages:` line that matches what was agreed.
+
+## Writes
+- `harness.json` at the repository root, through `write`.
+- The agreement between the markers at the top of `AGENTS.md`, through `write`; nothing below the end marker.
+- The project copies of the stages that are on under `.claude/skills/pincer-<stage>/`, their commands, and the Codex and Copilot files for the installed platforms, through `write`.
+- Nothing else. No CI workflow, no branch protection, no tool configuration: those belong to the first job when the person chose them.
+
+## Without subagents
+This stage dispatches no agents and runs the same everywhere. The scripts need no
+platform feature: `node scripts/pincer-blueprint.cjs` and `scripts/pincer-status.sh`
+run in any shell. On a platform without slash commands, read this file and follow it.
+
+## When this stage is off
+Never. Blueprint is always on; `harness.json` cannot switch it off (the validator
+rejects a `stages.blueprint` entry). Without an agreement every other stage refuses
+with `no agreement yet: run $pincer-blueprint`, and status points here.