@pareto4/pp-core 1.17.1 → 1.19.0

package/scripts/gen-practice-arithmetic-contract.cjs

@@ -1,412 +0,0 @@
-#!/usr/bin/env node
-/**
- * Inject the canonical practice-verdict arithmetic contract into every
- * instruction surface that states it.
- *
- * WHY THIS EXISTS. Phase 6 verification took seven passes and found eight gaps.
- * Every one had the same root cause: one contract restated in English on five
- * surfaces, with nothing keeping the copies true. Two of the gaps were defects
- * introduced while repairing another.
- *
- * WHY GENERATION AND NOT AN `@`-INCLUDE — checked, not assumed, because
- * ignoring the delivering surface is exactly what produced three of those
- * misses. `agents/pp-vault-reviewer.md` and
- * `pp-core/references/verifier-practice-verdicts.md` carry no `@`-includes; the
- * text must be physically present for the agent reading them. And
- * `steps/verifier-practice-payload.md` is interpolated VERBATIM into
- * pp-verifier's prompt (execute-phase.md:1358 -> :1382), so an `@` line there
- * would reach the agent as literal text. Physical copies are required, so this
- * follows the repo's existing answer for required-but-must-not-drift copies:
- * `gen-capability-registry`, `gen-platform-bindings-schema --check`.
- *
- * NOT A TARGET: `pp-core/templates/VAULT-REVIEW.md`. Its prose is a worked
- * sample the agent ADAPTS, not normative text — verified by diffing the
- * template against an artifact a reviewer actually wrote, where the wording
- * legitimately differs. It stays guarded mechanically instead, by the
- * arithmetic sweep in `tests/vault-review.test.cjs`.
- *
- * THE UNIT OF GOVERNANCE IS THE FILE, NOT THE REGION (06-16, gap G10).
- * Verification pass 8 reproduced the hole this originally left: it replaced
- * `verifier-practice-verdicts.md:98-100` — thirty lines ABOVE that file's own
- * generated block, outside every marker — with the contract's exact inverse,
- * and `--check`, `lint:ci` and the suite all stayed green. Marker-region
- * equality says nothing about the rest of the file, and an agent reads a file
- * linearly, so the hand-written copy is the one it meets first.
- *
- * So `--check` also runs a RESIDUE SCAN: for each target, the text outside its
- * region is scanned for the contract's load-bearing needles. The needle list is
- * NOT hardcoded here — it lives in a second marker region in the same single
- * source, so the guard cannot drift from the contract it guards. One file owns
- * both the canonical text and what counts as restating it.
- *
- * THE SCAN GOVERNS TEXT, NOT LINE BREAKS (06-17, W13). It runs the needles
- * twice: once per raw line, and once over joined normalised windows, reporting
- * the second as its own class only where no single line in the window matches.
- * Verification pass 9 measured why: the per-line pass alone was defeated by an
- * ordinary markdown wrap, using nothing but the needles' own phrases. See
- * `scanResidue`.
- *
- * `--write` deliberately does NOT scan. Generation injects; it must never
- * delete a surface's prose on the strength of a regex.
- *
- * Usage: --write (inject) | --check (exit 1 on drift OR residue, for lint:ci)
- *
- * Exit codes use `process.exitCode` + `return`, never `process.exit()`: the
- * repo's `n/no-process-exit` rule forbids the latter, and the lint scripts here
- * already use this form.
- */
-const fs = require('fs');
-const path = require('path');
-const crypto = require('crypto');
-
-const ROOT = path.join(__dirname, '..');
-const SOURCE = path.join(ROOT, 'pp-core', 'references', 'practice-arithmetic-contract.md');
-const ALLOWLIST = path.join(ROOT, 'scripts', 'practice-arithmetic-contract.allow.json');
-const S_START = '<!-- gen:practice-arithmetic-contract:source:start -->';
-const S_END = '<!-- gen:practice-arithmetic-contract:source:end -->';
-const N_START = '<!-- gen:practice-arithmetic-contract:needles:start -->';
-const N_END = '<!-- gen:practice-arithmetic-contract:needles:end -->';
-const START = '<!-- gen:practice-arithmetic-contract:start -->';
-const END = '<!-- gen:practice-arithmetic-contract:end -->';
-
-/** The four INSTRUCTION surfaces. The template is deliberately absent (see above). */
-const TARGETS = [
-  'pp-core/workflows/vault-review.md',
-  'agents/pp-vault-reviewer.md',
-  'pp-core/references/verifier-practice-verdicts.md',
-  'pp-core/workflows/execute-phase/steps/verifier-practice-payload.md',
-];
-
-function readCanonical() {
-  const text = fs.readFileSync(SOURCE, 'utf-8');
-  const a = text.indexOf(S_START);
-  const b = text.indexOf(S_END);
-  if (a === -1 || b === -1 || b < a) {
-    throw new Error(`${SOURCE}: source markers missing or inverted — cannot generate`);
-  }
-  const body = text.slice(a + S_START.length, b).trim();
-  if (!body) throw new Error(`${SOURCE}: canonical block is empty — refusing to blank every target`);
-  return body;
-}
-
-/**
- * The residue needles, read from the SAME source file as the canonical text and
- * with the SAME empty-block refusal. A needle line is `- ` + a backtick-quoted
- * regex source + ` — ` + why it is load-bearing; the description may itself
- * contain backticks, so only the FIRST backtick span is the pattern.
- *
- * A non-blank line that does not parse is a hard error. A silently skipped
- * needle is a guard that has quietly stopped guarding, which is the whole class
- * this file exists to end.
- */
-function readNeedles() {
-  const text = fs.readFileSync(SOURCE, 'utf-8');
-  const a = text.indexOf(N_START);
-  const b = text.indexOf(N_END);
-  if (a === -1 || b === -1 || b < a) {
-    throw new Error(`${SOURCE}: needle markers missing or inverted — cannot scan for residue`);
-  }
-  const body = text.slice(a + N_START.length, b).trim();
-  if (!body) throw new Error(`${SOURCE}: the needle list is empty — refusing to scan for nothing`);
-
-  const needles = [];
-  for (const raw of body.split(/\r?\n/)) {
-    const line = raw.trim();
-    if (!line) continue;
-    const m = /^-\s+`([^`]+)`\s+—\s+(\S.*)$/.exec(line);
-    if (!m) {
-      throw new Error(
-        `${SOURCE}: unparseable needle line — expected "- \`<regex>\` — <why>", got:\n  ${line}`,
-      );
-    }
-    let re;
-    try {
-      re = new RegExp(m[1], 'i');
-    } catch (err) {
-      throw new Error(`${SOURCE}: needle \`${m[1]}\` is not a valid regex — ${err.message}`);
-    }
-    needles.push({ source: m[1], re, why: m[2] });
-  }
-  if (!needles.length) throw new Error(`${SOURCE}: the needle list parsed to zero needles`);
-  return needles;
-}
-
-const sha256 = (s) => crypto.createHash('sha256').update(s, 'utf-8').digest('hex');
-
-/**
- * Allowlist entries are keyed by target path and hash the EXACT allowed line.
- * Content-hashing is `06-02`'s mechanism for the protected `pp-vault-audit`
- * sites: editing an allowed line breaks its entry, so an allowance can never
- * quietly widen to cover text nobody justified. A `reason` is mandatory.
- *
- * An ABSENT allowlist means nothing is allowed — the fail-closed direction.
- */
-function readAllowlist() {
-  if (!fs.existsSync(ALLOWLIST)) return {};
-  const raw = JSON.parse(fs.readFileSync(ALLOWLIST, 'utf-8'));
-  const out = {};
-  for (const [file, entries] of Object.entries(raw)) {
-    if (file.startsWith('//')) continue; // a comment key, never a path
-    if (!TARGETS.includes(file)) {
-      throw new Error(
-        `${ALLOWLIST}: "${file}" is not one of the generated targets. ` +
-          'A stale key means the allowlist outlived the file it excused — re-justify or delete it.',
-      );
-    }
-    if (!Array.isArray(entries)) throw new Error(`${ALLOWLIST}: "${file}" must map to an array`);
-    for (const e of entries) {
-      if (!/^[0-9a-f]{64}$/.test(String(e && e.sha256))) {
-        throw new Error(`${ALLOWLIST}: "${file}" has an entry without a 64-hex sha256`);
-      }
-      if (!String((e && e.reason) || '').trim()) {
-        throw new Error(
-          `${ALLOWLIST}: "${file}" entry ${e.sha256.slice(0, 12)} has no reason. ` +
-            'An unjustified allowance is a rubber stamp; state why the line is not a restatement.',
-        );
-      }
-    }
-    out[file] = entries;
-  }
-  return out;
-}
-
-/**
- * Adjacent non-blank lines outside the region, joined with a single space and
- * whitespace-collapsed. A markdown paragraph is one window.
- *
- * Joining a whole run rather than sliding a 2-line window is not a wider net:
- * the needles are contiguous phrases, so the only adjacencies a join creates
- * are the ones at line boundaries — exactly the adjacencies the wrap destroyed.
- * A run simply also covers a phrase a reflow spread over three lines.
- */
-function normalisedWindows(lines, inRegion) {
-  const windows = [];
-  let run = [];
-  const flush = () => {
-    // A one-line run says nothing the per-line pass did not already say.
-    if (run.length > 1) windows.push(run);
-    run = [];
-  };
-  lines.forEach((line, i) => {
-    if (inRegion(i) || !line.trim()) {
-      flush();
-      return;
-    }
-    run.push({ line, i });
-  });
-  flush();
-  return windows;
-}
-
-/**
- * Scan one target's text OUTSIDE its generated region. Returns findings and the
- * set of allowlist hashes this file actually used, so an entry that matches no
- * line can be reported as rotted rather than sitting there looking like cover.
- *
- * TWO PASSES, and the second is additive (06-17, W13).
- *
- * The first tests each raw LINE, which is what shipped and what the three
- * allowlist entries hash. Verification pass 9 measured its ceiling: an ordinary
- * markdown wrap defeats every multi-word needle, including the needles' OWN
- * literal phrases — `two count` ending a line and `populations` opening the
- * next scanned clean, while the same words on one line failed naming all four.
- * The guard governed line breaks where it must govern text. Pass 9 probed all
- * four targets and found 0 live instances, so this was latent coverage rather
- * than residue at HEAD; the trigger, though, is an accidental prose reflow and
- * the direction of failure is silent.
- *
- * So the second pass runs the same needles over joined normalised WINDOWS, and
- * reports a hit only when the needle matches the window and matches NO single
- * line within it. That makes a wrap-only match its own named class instead of
- * folding it into the per-line one, and it leaves per-line semantics — and
- * therefore the existing allowlist hashes — exactly as they were.
- *
- * A wrap-only finding is allowlistable like any other, but its hash is of the
- * JOINED NORMALISED WINDOW, not of a raw line, and `--check` prints that exact
- * text beside the hash so nobody has to reconstruct it. That digest is stable
- * under a reflow of the same words, which is the right behaviour: what somebody
- * justified is the sentence, not where its line breaks happened to fall.
- */
-function scanResidue(file, needles, allowed) {
-  const abs = path.join(ROOT, file);
-  // Split on /\r?\n/, not '\n': the allowlist hashes the EXACT line, so a
-  // CRLF checkout must not produce a different digest for the same text.
-  const lines = fs.readFileSync(abs, 'utf-8').split(/\r?\n/);
-  const a = lines.findIndex((l) => l.includes(START));
-  const b = lines.findIndex((l) => l.includes(END));
-  const inRegion = (i) => a !== -1 && b >= a && i >= a && i <= b;
-
-  const allowedHashes = new Map((allowed[file] || []).map((e) => [e.sha256, e.reason]));
-  const used = new Set();
-  const findings = [];
-  const wrapped = [];
-
-  lines.forEach((line, i) => {
-    if (inRegion(i)) return;
-    const hits = needles.filter((n) => n.re.test(line));
-    if (!hits.length) return;
-    const h = sha256(line);
-    if (allowedHashes.has(h)) {
-      used.add(h);
-      return;
-    }
-    findings.push({ file, line: i + 1, text: line, hits: hits.map((n) => n.source), sha256: h });
-  });
-
-  for (const run of normalisedWindows(lines, inRegion)) {
-    const text = run
-      .map((r) => r.line.trim())
-      .join(' ')
-      .replace(/\s+/g, ' ');
-    // `n.re.test(r.line)` against the RAW line, exactly as the first pass tests
-    // it, so "wrap-only" means precisely "the first pass could not have seen
-    // this" — including when the first pass saw it and the allowlist excused it.
-    const hits = needles.filter((n) => n.re.test(text) && !run.some((r) => n.re.test(r.line)));
-    if (!hits.length) continue;
-    const h = sha256(text);
-    if (allowedHashes.has(h)) {
-      used.add(h);
-      continue;
-    }
-    wrapped.push({
-      file,
-      line: run[0].i + 1,
-      endLine: run[run.length - 1].i + 1,
-      text,
-      hits: hits.map((n) => n.source),
-      sha256: h,
-    });
-  }
-
-  const unused = [...allowedHashes.keys()].filter((h) => !used.has(h));
-  return { findings, wrapped, unused };
-}
-
-function apply(file, canonical, { write }) {
-  const abs = path.join(ROOT, file);
-  const text = fs.readFileSync(abs, 'utf-8');
-  const a = text.indexOf(START);
-  const b = text.indexOf(END);
-  if (a === -1 || b === -1) {
-    return { file, status: 'missing-markers' };
-  }
-  if (b < a) return { file, status: 'inverted-markers' };
-
-  const desired = `${START}\n${canonical}\n${END}`;
-  const current = text.slice(a, b + END.length);
-  if (current === desired) return { file, status: 'unchanged' };
-  if (write) {
-    fs.writeFileSync(abs, text.slice(0, a) + desired + text.slice(b + END.length), 'utf-8');
-    return { file, status: 'transformed' };
-  }
-  return { file, status: 'drifted' };
-}
-
-function main() {
-  const write = process.argv.includes('--write');
-  const check = process.argv.includes('--check');
-  if (write === check) {
-    console.error('usage: gen-practice-arithmetic-contract.cjs (--write | --check)');
-    process.exitCode = 2;
-    return;
-  }
-
-  const canonical = readCanonical();
-  const results = TARGETS.map((f) => apply(f, canonical, { write }));
-
-  const bad = results.filter((r) => r.status !== 'unchanged' && r.status !== 'transformed');
-  for (const r of bad) console.error(`  ${r.status}: ${r.file}`);
-
-  if (check) {
-    if (bad.length) {
-      console.error(
-        `\nFAIL: ${bad.length} surface(s) drifted from ${path.relative(ROOT, SOURCE)}.\n` +
-          'Edit that file, then run: npm run gen:practice-arithmetic-contract',
-      );
-      process.exitCode = 1;
-      return;
-    }
-
-    // The residue scan. Region equality is necessary and not sufficient: a
-    // surface can restate the contract by hand ANYWHERE ELSE in the same file,
-    // where the region comparison never looks. That is G10.
-    const needles = readNeedles();
-    const allowed = readAllowlist();
-    const findings = [];
-    const wrapped = [];
-    const rotted = [];
-    for (const file of TARGETS) {
-      const r = scanResidue(file, needles, allowed);
-      findings.push(...r.findings);
-      wrapped.push(...r.wrapped);
-      for (const h of r.unused) rotted.push({ file, sha256: h });
-    }
-
-    if (findings.length || wrapped.length) {
-      console.error(
-        `\nFAIL: ${findings.length + wrapped.length} hand-written restatement(s) of the contract, OUTSIDE the generated region:\n`,
-      );
-      for (const f of findings) {
-        console.error(`  residue: ${f.file}:${f.line}  [${f.hits.join(', ')}]`);
-        console.error(`    ${f.text.trim()}`);
-      }
-      // Named as its own class: the phrase is only visible once the lines are
-      // joined, so the line number is a RANGE and the hash below is of the
-      // joined text, not of any line you can see in the file (06-17, W13).
-      for (const f of wrapped) {
-        console.error(`  wrapped residue: ${f.file}:${f.line}-${f.endLine}  [${f.hits.join(', ')}]`);
-        console.error(`    ${f.text}`);
-      }
-      console.error(
-        '\nREMEDY: replace the sentence with a POINTER to the generated block in the same file\n' +
-          '("§7 states the rule; it is not restated here"), keeping only what the canonical block\n' +
-          'does not say — a per-tier destination, for instance. The facts stay physically present\n' +
-          'in the file, in the generated block the agent also reads.\n' +
-          `If the line genuinely restates nothing, allowlist it in ${path.relative(ROOT, ALLOWLIST)}\n` +
-          'with its sha256 and a stated reason:\n',
-      );
-      for (const f of findings) console.error(`  "${f.file}": [{ "sha256": "${f.sha256}", "reason": "…" }]`);
-      if (wrapped.length) {
-        console.error(
-          '\nA WRAPPED finding is hashed over the JOINED, whitespace-collapsed text printed above —\n' +
-            'not over any single line of the file. The digest therefore survives a reflow of the same\n' +
-            'words, because what an allowance justifies is the sentence, not its line breaks:\n',
-        );
-        for (const f of wrapped) console.error(`  "${f.file}": [{ "sha256": "${f.sha256}", "reason": "…" }]`);
-      }
-      process.exitCode = 1;
-      return;
-    }
-
-    if (rotted.length) {
-      console.error(
-        `\nFAIL: ${rotted.length} allowlist entr(ies) match no line or window in their file:\n`,
-      );
-      for (const r of rotted) console.error(`  rotted: ${r.file}  ${r.sha256}`);
-      console.error(
-        '\nThe allowed line was edited or removed. Re-justify the new line or delete the entry —\n' +
-          'an allowance nobody can point at is exactly the rubber stamp content-hashing prevents.',
-      );
-      process.exitCode = 1;
-      return;
-    }
-
-    const allowCount = Object.values(allowed).reduce((n, e) => n + e.length, 0);
-    console.log(
-      `ok practice-arithmetic-contract: ${results.length} surface(s) match the source; ` +
-        `no residue outside the regions, per line or across a wrap (${needles.length} needles, ` +
-        `${allowCount} allowlisted).`,
-    );
-    return;
-  }
-
-  const t = results.filter((r) => r.status === 'transformed').length;
-  const u = results.filter((r) => r.status === 'unchanged').length;
-  if (bad.length) {
-    process.exitCode = 1;
-    return;
-  }
-  console.log(`Done. ${t} transformed, ${u} unchanged.`);
-}
-
-main();

package/scripts/practice-arithmetic-contract.allow.json

@@ -1,35 +0,0 @@
-{
-  "//": [
-    "Lines that carry a residue needle but restate NO fact the canonical block states.",
-    "Read by scripts/gen-practice-arithmetic-contract.cjs --check. Keys starting with // are comments.",
-    "sha256 is of the EXACT allowed line. Editing that line breaks its entry and forces re-justification;",
-    "an entry matching no line in its file fails as rotted. A reason is mandatory.",
-    "A WRAPPED finding — one visible only once adjacent lines are joined — is hashed over the joined,",
-    "whitespace-collapsed window text that --check prints beside it, not over any single line of the",
-    "file. That digest survives a reflow of the same words, because what an allowance justifies is the",
-    "sentence and not where its line breaks fell. All three entries below are per-LINE. 06-17, W13.",
-    "Every entry below is the same shape: a payload-KEY INVENTORY, where `derivedCounts` /",
-    "`derivedRateLine` are named as things the CLI hands the agent, and the very next clause points at",
-    "the generated contract block rather than saying what they mean. Naming a key is not restating a",
-    "contract. Keep this file as close to empty as the prose allows.",
-    "06-16, gap G10."
-  ],
-  "pp-core/workflows/vault-review.md": [
-    {
-      "sha256": "1766709dca03a214fb8fa5496fe6b2aef06fc1b02e67832a6048eeac78e29d6a",
-      "reason": "Section 4 is the inventory of what REVIEW_PAYLOAD carries; this line names the two keys and its own continuation says what they describe is stated once in the contract block carried into the spawn prompt below. It states nothing itself."
-    }
-  ],
-  "agents/pp-vault-reviewer.md": [
-    {
-      "sha256": "1fac53fb5988ab5278f2a262f1564b5dbef830531ec0a82f7200c9b940b45b8d",
-      "reason": "The left cell of the supplied-fact table, where the key name IS the row's subject. The right cell is a pointer to the contract block twelve lines below, in the same <derived_facts> element."
-    }
-  ],
-  "pp-core/references/verifier-practice-verdicts.md": [
-    {
-      "sha256": "52872e6f4b821944e026667c5bd48a3c2319f6876e805e8721865cbf6eb27816",
-      "reason": "Section 6's inventory of what the check vault-review arm hands the verifier. The sentence that follows it points at section 7 and says explicitly that the rule is not restated here."
-    }
-  ]
-}

package/scripts/record-vault-mode-golden.cjs

@@ -1,89 +0,0 @@
-#!/usr/bin/env node
-'use strict';
-
-/**
- * scripts/record-vault-mode-golden.cjs — the vault-mode golden recorder
- * (Vault Assurance v1.2, phase 13; MODE-01, PARK-04; D-01).
- *
- *   --write   record every enablement cell (key absent — the canonical
- *             recording), normalise, and write tests/fixtures/vault-mode-golden/<cell>.json
- *   --check   record the same and compare against the committed files; print
- *             every differing path and exit 1 on any difference
- *
- * Neither or both flags: usage, exit 2. No path argument: the golden directory
- * is the harness's `GOLDEN_DIR`, so the recorder and the test cannot disagree
- * about where the goldens live.
- *
- * A THIN CLI. Every fixture, capture, normalisation and comparison rule lives in
- * the shared harness module required below, which the golden test requires too.
- * This script is never run by the test suite: a re-record is a deliberate,
- * reviewable re-baseline (D-01), and it must run on a tree whose practices-mode
- * behaviour is the one being pinned.
- */
-
-const fs = require('node:fs');
-const path = require('node:path');
-const harness = require('../tests/helpers/vault-mode-golden-harness.cjs');
-
-const ROOT = path.resolve(__dirname, '..');
-const USAGE = 'usage: record-vault-mode-golden.cjs (--write | --check)';
-
-function describeDiff(d) {
-  const at = d.firstDiffAt === undefined ? '' : ` (first differing byte at ${d.firstDiffAt})`;
-  const show = (v) => (v === undefined ? '<absent>' : JSON.stringify(v).slice(0, 200));
-  return `  ${d.path}${at}\n    expected: ${show(d.expected)}\n    actual:   ${show(d.actual)}`;
-}
-
-function main() {
-  const write = process.argv.includes('--write');
-  const check = process.argv.includes('--check');
-  if (write === check) {
-    console.error(USAGE);
-    process.exitCode = 2;
-    return;
-  }
-
-  let failed = 0;
-  for (const cell of harness.ENABLEMENT_CELLS) {
-    const raw = harness.recordCell({ cell: cell.name, modeKey: harness.KEY_CONFIGS.absent });
-    const normalised = harness.normaliseRecording(raw);
-    const count = Object.keys(normalised.commands).length;
-    const dropped = Object.entries(raw.meta.droppedHookCounts)
-      .map(([id, n]) => `${id}=${n}`)
-      .join(' ');
-    const target = harness.goldenPathFor(cell.name);
-    const rel = path.relative(ROOT, target);
-    console.log(`${cell.name}: ${count} commands recorded (render-hooks projection dropped: ${dropped})`);
-
-    if (write) {
-      fs.mkdirSync(path.dirname(target), { recursive: true });
-      fs.writeFileSync(target, harness.serialise(normalised), 'utf8');
-      console.log(`  wrote ${rel}`);
-      continue;
-    }
-
-    let expected;
-    try {
-      expected = JSON.parse(fs.readFileSync(target, 'utf8'));
-    } catch (e) {
-      console.error(`  FAIL: ${rel} could not be read as JSON (${e.message})`);
-      failed++;
-      continue;
-    }
-    const { equal, diffs } = harness.compareRecordings(expected, normalised);
-    if (equal) {
-      console.log(`  matches ${rel}`);
-    } else {
-      failed++;
-      console.error(`  FAIL: ${rel} differs at ${diffs.length} path(s):`);
-      for (const d of diffs) console.error(describeDiff(d));
-    }
-  }
-
-  if (check && failed > 0) {
-    console.error(`\nFAIL: ${failed} golden cell(s) differ from a fresh recording.`);
-    process.exitCode = 1;
-  }
-}
-
-main();