@pareto4/pp-core 1.21.1 → 1.23.1

package/scripts/live-runs/scenarios.cjs

@@ -0,0 +1,326 @@
+'use strict';
+
+/**
+ * scenarios.cjs - Phase 44 REACH-02 scenarios S1-S3 (D-05, D-07, D-08).
+ *
+ * Each scenario is a fixed starting project plus fixed user turns written in a
+ * business user's plain words, kept next to the harness so a run is repeatable.
+ *
+ *   S1  a discovery session that hits a tool error. The error is real: the notes
+ *       for session 2 are generated from the real session templates with exactly
+ *       one section left empty, so the installed build's own `discovery
+ *       session-check 2` fails with its catalogued business text (D-07). No mocks.
+ *   S2  a subagent returns. Discovery spawns no subagents, so S2 runs `/pp-quick`,
+ *       the cheapest business-reachable workflow that spawns pp-core agents
+ *       (`pp-planner`, then `pp-executor`). `/pp-verify-work` gap closure is
+ *       walked by a person, not run unattended.
+ *   S3  the early-question line deferred from Phase 40: `/pp-new-project` in an
+ *       empty repo, where the first question must already be in plain wording.
+ *
+ * `fixtureCheck` runs offline and says whether a project really is the starting
+ * point the scenario needs, so a fixture that fails for the wrong reason is caught
+ * before a run spends money.
+ */
+
+const { execFileSync, spawnSync } = require('node:child_process');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { installEnv } = require('./scratch-project.cjs');
+const { withoutGitRepoEnv } = require('./driver.cjs');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+const WORKFLOW_PATH = path.join(REPO_ROOT, 'pp-core', 'workflows', 'discovery-sprint.md');
+const COMPILED_CHECK = path.join(REPO_ROOT, 'pp-core', 'bin', 'lib', 'discovery-session-check.cjs');
+const DISCOVERY_DIR = path.join('.planning', 'discovery');
+const FIXTURE_DAY = '2026-11-02';
+const FIXTURE_LATER_DAY = '2026-11-03';
+
+const pad = (n) => String(n).padStart(2, '0');
+
+/** The compiled session-check, or a plain instruction when the library is not built yet. */
+function sessionCheckLib() {
+  try {
+    return require(COMPILED_CHECK);
+  } catch (err) {
+    if (err && err.code === 'MODULE_NOT_FOUND') throw new Error('run npm run build:lib first (the discovery session check is not built)');
+    throw err;
+  }
+}
+
+/** The `_progress.md` schema, as the discovery workflow writes it (its Bootstrap Templates code block). */
+function progressSchema() {
+  const text = fs.readFileSync(WORKFLOW_PATH, 'utf8');
+  const marker = text.indexOf('**`.planning/discovery/_progress.md`**');
+  if (marker < 0) throw new Error('scenarios: the _progress.md schema was not found in discovery-sprint.md');
+  const open = text.indexOf('```markdown\n', marker);
+  const close = text.indexOf('\n```', open + 12);
+  if (open < 0 || close < 0) throw new Error('scenarios: the _progress.md schema block is not closed in discovery-sprint.md');
+  return text.slice(open + '```markdown\n'.length, close);
+}
+
+/** One row per session 1-13 from the schema: { n, name, category }. */
+function sessionRows() {
+  const rows = [];
+  for (const l of progressSchema().split('\n')) {
+    const m = /^\| (\d+) \| (.+?) \| (.+?) \| Not Started \|/.exec(l);
+    if (m) rows.push({ n: Number(m[1]), name: m[2], category: m[3] });
+  }
+  if (rows.length !== 13) throw new Error(`scenarios: expected 13 session rows in the schema, found ${rows.length}`);
+  return rows;
+}
+
+/**
+ * The tracker text in the schema's shape. `rows` maps a session number to Completed,
+ * In Progress or Not Started (default); started and completed rows get fixed dates.
+ */
+function progressFile({ project, client, rows = {} }) {
+  const status = (n) => rows[n] || 'Not Started';
+  const lines = progressSchema().split('\n').map((l) => {
+    const m = /^\| (\d+) \| (.+?) \| (.+?) \| Not Started \|/.exec(l);
+    if (!m) return l;
+    const n = Number(m[1]);
+    const s = status(n);
+    const started = s === 'Not Started' ? '' : FIXTURE_DAY;
+    const completed = s === 'Completed' ? FIXTURE_LATER_DAY : '';
+    const score = s === 'Completed' ? '100' : '';
+    return `| ${n} | ${m[2]} | ${m[3]} | ${s} | ${started} | ${completed} | ${score} | 0 | 0 | |`;
+  });
+  const count = (s) => Object.keys(rows).filter((k) => rows[k] === s).length;
+  const done = count('Completed');
+  const doing = count('In Progress');
+  const text = lines.join('\n')
+    .replaceAll('[PROJECT_NAME]', project)
+    .replaceAll('[CLIENT_NAME]', client)
+    .replaceAll("[today's date]", FIXTURE_LATER_DAY)
+    .replace('**Overall Status:** Not Started', `**Overall Status:** ${doing + done > 0 ? 'In Progress' : 'Not Started'}`)
+    .replace('- **Completed:** 0/13', `- **Completed:** ${done}/13`)
+    .replace('- **In Progress:** 0/13', `- **In Progress:** ${doing}/13`)
+    .replace('- **Not Started:** 13/13', `- **Not Started:** ${13 - done - doing}/13`);
+  return text.endsWith('\n') ? text : `${text}\n`;
+}
+
+const TABLE_PHRASES = Object.freeze([
+  'Taking an order by phone', 'The shop owner', 'Every morning', 'Notes in a paper diary', 'About ten minutes',
+  'Often a little late', 'Two people', 'A shared spreadsheet', 'Mostly fine', 'Needs a tidy up',
+]);
+const PROSE = 'Harbour Flowers is a small flower shop that takes orders by phone and writes them in a paper diary.';
+
+/**
+ * Session notes built from the real template, the way a facilitator would fill them:
+ * a table gets its header, a separator and one row of short plain phrases, prose gets
+ * one plain sentence. A title in `blank` is left as the template leaves it (a table keeps
+ * its header and one row of empty cells, prose gets nothing), so the real check reports
+ * that section as empty and nothing else.
+ */
+function sessionNotes(n, { status = 'Completed', blank = [] } = {}) {
+  const { requiredSectionsOf, SESSIONS_DIR } = sessionCheckLib();
+  const file = fs.readdirSync(SESSIONS_DIR).find((f) => f.startsWith(`${pad(n)}-`));
+  if (!file) throw new Error(`scenarios: no session template for session ${n}`);
+  const template = fs.readFileSync(path.join(SESSIONS_DIR, file), 'utf8');
+  const heading = /^### Session \d+: (.+)$/m.exec(template);
+  const title = heading ? heading[1].trim() : `Session ${n}`;
+  const row = sessionRows().find((r) => r.n === n);
+  const category = row ? row.category : 'Business Functional';
+
+  let cell = 0;
+  const body = requiredSectionsOf(template).map((r) => {
+    if (r.kind === 'table') {
+      const head = `| ${r.header.join(' | ')} |`;
+      const sep = `|${r.header.map(() => '---').join('|')}|`;
+      // A blank table is the template's own untouched table: its header and one row of empty cells.
+      if (blank.includes(r.title)) return `**${r.title}**\n\n${head}\n${sep}\n|${r.header.map(() => '  ').join('|')}|\n`;
+      const cells = r.header.map(() => TABLE_PHRASES[cell++ % TABLE_PHRASES.length]);
+      return `**${r.title}**\n\n${head}\n${sep}\n| ${cells.join(' | ')} |\n`;
+    }
+    if (blank.includes(r.title)) return `**${r.title}**\n`;
+    return `**${r.title}**\n\n${PROSE}\n`;
+  }).join('\n');
+
+  const front = [
+    '---',
+    `session: ${n}`,
+    `title: "${title}"`,
+    `category: "${category}"`,
+    `status: "${status}"`,
+    `started_date: "${FIXTURE_DAY}"`,
+    ...(status === 'Completed' ? [`completed_date: "${FIXTURE_LATER_DAY}"`] : []),
+    `completeness_score: ${status === 'Completed' ? 100 : 80}`,
+    '---',
+  ].join('\n');
+  return `${front}\n\n# Session ${n} — ${title}\n\n${body}\n`;
+}
+
+function write(projectDir, rel, content) {
+  const abs = path.join(projectDir, rel);
+  fs.mkdirSync(path.dirname(abs), { recursive: true });
+  fs.writeFileSync(abs, content);
+}
+
+const S1_BLANK = 'Pain Points Register';
+
+function s1Fixture(projectDir) {
+  write(projectDir, path.join(DISCOVERY_DIR, '_progress.md'), progressFile({
+    project: 'Harbour Flowers',
+    client: 'Harbour Flowers Ltd',
+    rows: { 1: 'Completed', 2: 'In Progress' },
+  }));
+  write(projectDir, path.join(DISCOVERY_DIR, 'session-01.md'), sessionNotes(1, { status: 'Completed' }));
+  write(projectDir, path.join(DISCOVERY_DIR, 'session-02.md'), sessionNotes(2, { status: 'In Progress', blank: [S1_BLANK] }));
+}
+
+/** Run the installed build's own session check on session 2 and say whether it fails for exactly the planted reason. */
+function s1FixtureCheck(projectDir, { personHome }) {
+  const tools = path.join(projectDir, '.claude', 'pp-core', 'bin', 'pp-tools.cjs');
+  if (!fs.existsSync(tools)) return { ok: false, detail: `the installed pp-tools is missing at ${tools}` };
+  const env = installEnv(personHome);
+  env.PP_AUDIENCE = 'business';
+  const res = spawnSync(process.execPath, [tools, 'discovery', 'session-check', '2'], { cwd: projectDir, env, encoding: 'utf8', timeout: 60000 });
+  const out = `${res.stdout || ''}${res.stderr || ''}`;
+  const refs = out.match(/Ref: discovery\.session\.[a-z_]+/g) || [];
+  const failedOnce = out.split('Ref: discovery_session_check_failed').length - 1 === 1;
+  const ok = res.status !== 0 && failedOnce && refs.length === 1 && refs[0] === 'Ref: discovery.session.empty_section' && out.includes(S1_BLANK);
+  // The catalogued business text follows the JSON report (on the same line, as the CLI prints it).
+  const from = out.indexOf('Your discovery notes');
+  const head = out.slice(from < 0 ? 0 : from).trim().split('\n').slice(0, 12).join('\n');
+  return { ok, detail: ok ? head : `expected exactly one empty section (${S1_BLANK}); exit ${res.status}\n${head}` };
+}
+
+function s2Fixture(projectDir) {
+  write(projectDir, path.join('.planning', 'PROJECT.md'), [
+    '# Harbour Flowers website',
+    '',
+    '## What this is',
+    '',
+    'A small website for Harbour Flowers, a flower shop. It tells customers when the shop is open and how to order.',
+    '',
+    '## Core value',
+    '',
+    'A customer can find the opening hours and place an order without phoning the shop.',
+    '',
+    '## Requirements',
+    '',
+    '- Show the opening hours on their own page.',
+    '- Show how to order.',
+    '',
+  ].join('\n'));
+  write(projectDir, path.join('.planning', 'ROADMAP.md'), [
+    '# Roadmap: Harbour Flowers website',
+    '',
+    '## Overview',
+    '',
+    'One small step: a page with the shop opening hours.',
+    '',
+    '## Phases',
+    '',
+    '- [ ] **Phase 1: Opening hours page** - Customers can see when the shop is open',
+    '',
+    '## Phase Details',
+    '',
+    '### Phase 1: Opening hours page',
+    '**Goal**: Customers can see when the shop is open.',
+    '**Depends on**: Nothing (first phase)',
+    '**Plans**: TBD',
+    '',
+  ].join('\n'));
+  write(projectDir, path.join('.planning', 'STATE.md'), [
+    '# Project State',
+    '',
+    '## Project Reference',
+    '',
+    'See: .planning/PROJECT.md',
+    '',
+    '**Core value:** A customer can find the opening hours and place an order without phoning the shop.',
+    '**Current focus:** Opening hours page',
+    '',
+    '## Current Position',
+    '',
+    'Phase: 1 of 1 (Opening hours page)',
+    'Plan: 0 of 0 in current phase',
+    'Status: Ready to plan',
+    `Last activity: ${FIXTURE_DAY} — Project set up`,
+    '',
+    'Progress: [░░░░░░░░░░] 0%',
+    '',
+    '## Accumulated Context',
+    '',
+    '### Decisions',
+    '',
+    'None yet.',
+    '',
+    '### Pending Todos',
+    '',
+    'None yet.',
+    '',
+    '### Blockers/Concerns',
+    '',
+    'None yet.',
+    '',
+    '## Session Continuity',
+    '',
+    `Last session: ${FIXTURE_DAY}`,
+    'Stopped at: Project set up',
+    'Resume file: None',
+    '',
+  ].join('\n'));
+}
+
+/** git in the scratch project, never steered at another repository by an inherited GIT_DIR. */
+const gitOut = (cwd, args) => execFileSync('git', args, { cwd, env: withoutGitRepoEnv(process.env), encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+
+function s2FixtureCheck(projectDir) {
+  const problems = [];
+  try {
+    if (gitOut(projectDir, ['rev-list', '--count', 'HEAD']) !== '1') problems.push('the repo does not hold exactly one commit');
+    if (gitOut(projectDir, ['status', '--porcelain']) !== '') problems.push('the working tree is not clean');
+  } catch (err) {
+    problems.push(`git failed: ${String(err.message).split('\n')[0]}`);
+  }
+  if (!fs.existsSync(path.join(projectDir, '.planning', 'ROADMAP.md'))) problems.push('.planning/ROADMAP.md is missing');
+  return { ok: problems.length === 0, detail: problems.length === 0 ? 'one commit, clean tree, roadmap present' : problems.join('; ') };
+}
+
+function s3FixtureCheck(projectDir) {
+  const problems = [];
+  if (fs.existsSync(path.join(projectDir, '.planning'))) problems.push('a .planning directory exists');
+  const head = spawnSync('git', ['rev-parse', '--verify', '-q', 'HEAD'], { cwd: projectDir, env: withoutGitRepoEnv(process.env), encoding: 'utf8' });
+  if (head.status === 0) problems.push('the repo already has a commit');
+  return { ok: problems.length === 0, detail: problems.length === 0 ? 'empty repo, no planning folder, no commit' : problems.join('; ') };
+}
+
+const freeze = (s) => Object.freeze({ ...s, turns: Object.freeze([...s.turns]) });
+
+const SCENARIOS = Object.freeze({
+  s1: freeze({
+    id: 's1',
+    title: 'A discovery session that hits a tool error',
+    command: 'pp-discovery',
+    audience: 'business',
+    initialCommit: false,
+    turns: ['/pp-discovery 2', 'That is everything for this session. Please finish it.'],
+    fixture: s1Fixture,
+    fixtureCheck: s1FixtureCheck,
+  }),
+  s2: freeze({
+    id: 's2',
+    title: 'A subagent returns',
+    command: 'pp-quick',
+    audience: 'business',
+    initialCommit: true,
+    turns: ['/pp-quick add a file called thanks.txt that says Thank you for your order'],
+    fixture: s2Fixture,
+    fixtureCheck: s2FixtureCheck,
+  }),
+  s3: freeze({
+    id: 's3',
+    title: 'The first question before any setup call',
+    command: 'pp-new-project',
+    audience: 'business',
+    initialCommit: false,
+    turns: ['/pp-new-project'],
+    fixture: () => {},
+    fixtureCheck: s3FixtureCheck,
+  }),
+});
+
+module.exports = { SCENARIOS, sessionNotes, progressFile };

package/scripts/live-runs/scratch-project.cjs

@@ -0,0 +1,132 @@
+'use strict';
+
+/**
+ * scratch-project.cjs - Phase 44 throwaway project with this build installed locally (D-01).
+ *
+ * Shared by the live runs and the walk setup, so both exercise the same install.
+ * The global install is an older version, so only a project-local install exercises
+ * this milestone's code (a project-local install answers first). The build refuses to
+ * continue unless the installed audience reference is byte-equal to the repo copy and
+ * the scenario's command file is there: a run on a missing or global install proves
+ * nothing (Pitfalls 1 and 2).
+ *
+ * The scratch repo has the throwaway identity and no remote, ever.
+ */
+
+const { execFileSync } = require('node:child_process');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const { CLAUDE_ENV_SCRUB_RE, GIT_IDENTITY, gitIdentityEnv, withoutGitRepoEnv } = require('./driver.cjs');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+const LABEL_RE = /^[a-z0-9-]{1,32}$/;
+const INSTALL_TIMEOUT_MS = 120000;
+const AUDIENCE_REF = path.join('pp-core', 'references', 'audience.md');
+
+/**
+ * The env the installer runs in: no audience, no config dir, no session markers and no
+ * GIT_DIR-style pointer at another repository; the person home is the temp one.
+ */
+function installEnv(personHome, baseEnv = process.env) {
+  const env = withoutGitRepoEnv(baseEnv);
+  delete env.PP_AUDIENCE;
+  delete env.CLAUDE_CONFIG_DIR;
+  for (const key of Object.keys(env)) {
+    if (CLAUDE_ENV_SCRUB_RE.test(key)) delete env[key];
+  }
+  env.GSD_HOME = personHome;
+  return env;
+}
+
+/** Throw unless this build, not another one, is what the project has installed. */
+function assertLocalInstall(projectDir, { repoRoot = REPO_ROOT, commands = [] } = {}) {
+  const installed = path.join(projectDir, '.claude', AUDIENCE_REF);
+  const original = path.join(repoRoot, AUDIENCE_REF);
+  if (!fs.existsSync(installed)) throw new Error(`local install check: ${installed} is missing (audience.md)`);
+  if (!fs.readFileSync(installed).equals(fs.readFileSync(original))) {
+    throw new Error(`local install check: the installed audience.md differs from ${original}; the project does not hold this build`);
+  }
+  for (const command of commands) {
+    const file = path.join(projectDir, '.claude', 'commands', `${command}.md`);
+    if (!fs.existsSync(file)) throw new Error(`local install check: command file ${command}.md is not installed under ${path.dirname(file)}`);
+  }
+}
+
+const git = (cwd, args, env) => execFileSync('git', args, { cwd, env, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+
+function removeDir(dir) {
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+/**
+ * Build a scratch project: a git repo with the throwaway identity and no remote,
+ * the scenario's fixture, this build installed locally (with the audience saved in
+ * the temp person home), the install verified, and an optional starting commit.
+ * `.claude/` is kept out of the repo through .git/info/exclude so the model's own
+ * `git status` and commits see only the project's files.
+ */
+function createScratchProject({ label, audience, fixture, initialCommit = false, commands = [], repoRoot = REPO_ROOT, tmpRoot, dir } = {}) {
+  if (typeof label !== 'string' || !LABEL_RE.test(label)) {
+    throw new Error(`createScratchProject: label must be 1-32 lowercase letters, digits or hyphens, got ${JSON.stringify(label)}`);
+  }
+  const root = tmpRoot || os.tmpdir();
+  let projectDir;
+  let madeProject = false;
+  if (dir) {
+    if (fs.existsSync(dir) && fs.readdirSync(dir).length > 0) throw new Error(`createScratchProject: ${dir} must be empty`);
+    madeProject = !fs.existsSync(dir);
+    fs.mkdirSync(dir, { recursive: true });
+    projectDir = dir;
+  } else {
+    projectDir = fs.mkdtempSync(path.join(root, `pp-live-${label}-`));
+    madeProject = true;
+  }
+  const personHome = fs.mkdtempSync(path.join(root, 'pp-live-home-'));
+
+  const cleanup = () => {
+    if (madeProject) removeDir(projectDir);
+    else if (fs.existsSync(projectDir)) for (const name of fs.readdirSync(projectDir)) removeDir(path.join(projectDir, name));
+    removeDir(personHome);
+  };
+
+  try {
+    const identity = { ...withoutGitRepoEnv(process.env), ...gitIdentityEnv() };
+    git(projectDir, ['-c', 'init.defaultBranch=main', 'init', '-q'], identity);
+    git(projectDir, ['config', 'user.name', GIT_IDENTITY.name], identity);
+    git(projectDir, ['config', 'user.email', GIT_IDENTITY.email], identity);
+    git(projectDir, ['config', 'commit.gpgsign', 'false'], identity);
+    fs.appendFileSync(path.join(projectDir, '.git', 'info', 'exclude'), '.claude/\n');
+
+    if (fixture) fixture(projectDir, { repoRoot });
+
+    const installArgs = [path.join(repoRoot, 'bin', 'install.js'), '--claude', '--local'];
+    if (audience) installArgs.push('--audience', audience);
+    try {
+      execFileSync(process.execPath, installArgs, {
+        cwd: projectDir,
+        env: installEnv(personHome),
+        encoding: 'utf8',
+        timeout: INSTALL_TIMEOUT_MS,
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+    } catch (err) {
+      const tail = String(err.stderr || err.stdout || err.message).trim().split('\n').slice(-8).join('\n');
+      throw new Error(`createScratchProject: the local install failed\n${tail}`);
+    }
+    assertLocalInstall(projectDir, { repoRoot, commands });
+
+    if (initialCommit) {
+      git(projectDir, ['add', '-A'], identity);
+      git(projectDir, ['commit', '-q', '-m', 'Starting point'], identity);
+    }
+  } catch (err) {
+    cleanup();
+    throw err;
+  }
+
+  return { projectDir, personHome, cleanup };
+}
+
+module.exports = { REPO_ROOT, createScratchProject, assertLocalInstall, installEnv };