@pareto4/pp-core 1.13.0 → 1.17.1

package/scripts/gen-capability-registry.cjs

@@ -568,6 +568,18 @@ function validateFeatureBody(cap) {
     }
   }
 
+  // Quick 261015-ect (QD-13): requiresPlatformBindings, optional. When present it
+  // must be a boolean; the loop resolver drops every hook of a capability that
+  // declares `true` on a project with no .platform-bindings.json. Which
+  // capabilities MUST declare it is a cross-capability rule
+  // (validatePlatformBindingsField).
+  if (cap.requiresPlatformBindings !== undefined && typeof cap.requiresPlatformBindings !== 'boolean') {
+    errors.push(
+      'capability "' + (cap.id || '(unknown)') + '" requiresPlatformBindings must be a boolean (got: ' +
+      JSON.stringify(cap.requiresPlatformBindings) + ')',
+    );
+  }
+
   return errors;
 }
 
@@ -1204,17 +1216,6 @@ function validateGate(gate, prefix) {
     if (count !== 1) {
       errors.push(prefix + '.check must have exactly one of: query, predicate, agentVerdict');
     }
-    // check.args: literal tokens `loop run-gates` appends after the phase — query gates only,
-    // at most 8, each a flag or a plain word (the runner refuses anything else at run time too).
-    if (Object.prototype.hasOwnProperty.call(gate.check, 'args')) {
-      const a = gate.check.args;
-      if (!hasQuery) {
-        errors.push(prefix + '.check.args is only valid beside check.query');
-      } else if (!Array.isArray(a) || a.length > 8
-        || !a.every((t) => typeof t === 'string' && /^(?:--[a-z][a-z0-9-]*|[a-z0-9][a-z0-9._-]*)$/i.test(t))) {
-        errors.push(prefix + '.check.args must be an array of at most 8 flags (--name) or plain words');
-      }
-    }
     // agentVerdict forces blocking: false (advisory only)
     if (hasAgentVerdict && gate.blocking === true) {
       errors.push(
@@ -1330,6 +1331,177 @@ function validateAgainstContract(cap, capId, knownAgentIds) {
   return errors;
 }
 
+/**
+ * Phase 15 D-02: validate the per-hook `vaultMode` filter field.
+ *
+ * The pure loop resolver evaluates `vaultMode` against an injected mode value
+ * and never emits it, so an unknown or misplaced value must be refused HERE,
+ * at generation, never interpreted at runtime. Three rules, each reported on
+ * its own:
+ *   (a) the field is allowed on contributions and gates only (a step is
+ *       refused);
+ *   (b) the value must be a string in the vault capability's declared
+ *       `config["vault.mode"].values`. That enum declaration is the ONE owner of
+ *       the closed set; it is read here, never restated. With no vault
+ *       capability, or no such values array, there is no closed set and every
+ *       `vaultMode` is refused (fail closed);
+ *   (c) the declaring capability must be `vault` or list `vault` in `requires`,
+ *       so a filtered hook can only exist where the vault gate's closure holds.
+ *
+ * Presence is own-property presence, so a JSON `null` is refused under (b).
+ *
+ * @param {Map<string, object>} capMap
+ * @returns {string[]} error strings; empty = all pass
+ */
+function validateVaultModeField(capMap) {
+  const errors = [];
+  const vaultCap = capMap.get('vault');
+  const modeDecl = vaultCap && vaultCap.config && typeof vaultCap.config === 'object'
+    ? vaultCap.config['vault.mode']
+    : undefined;
+  const allowed = modeDecl && Array.isArray(modeDecl.values)
+    ? modeDecl.values.filter((v) => typeof v === 'string')
+    : null;
+  const KINDS = [['steps', 'step'], ['contributions', 'contribution'], ['gates', 'gate']];
+  for (const [capId, cap] of capMap) {
+    if (!cap || typeof cap !== 'object') continue;
+    const prefix = 'capability "' + capId + '"';
+    const requiresVault = Array.isArray(cap.requires) && cap.requires.includes('vault');
+    for (const [arrKey, kind] of KINDS) {
+      const arr = Array.isArray(cap[arrKey]) ? cap[arrKey] : [];
+      for (const hook of arr) {
+        if (!hook || typeof hook !== 'object') continue;
+        if (!Object.prototype.hasOwnProperty.call(hook, 'vaultMode')) continue;
+        const where = prefix + ' ' + kind + ' at point "' + String(hook.point) + '"';
+        const value = hook.vaultMode;
+        if (kind === 'step') {
+          errors.push(where + ': vaultMode is allowed on contributions and gates only');
+        }
+        if (allowed === null) {
+          errors.push(
+            where + ': vaultMode ' + JSON.stringify(value) + ' cannot be checked: the vault capability ' +
+            'declares no "vault.mode" values, which own the closed set',
+          );
+        } else if (typeof value !== 'string' || !allowed.includes(value)) {
+          errors.push(
+            where + ': vaultMode ' + JSON.stringify(value) + ' is not one of [' + allowed.join(', ') +
+            '] (the closed set owned by the vault capability\'s "vault.mode" values)',
+          );
+        }
+        if (capId !== 'vault' && !requiresVault) {
+          errors.push(
+            where + ': vaultMode is allowed only on the "vault" capability or a capability that ' +
+            'lists "vault" in requires',
+          );
+        }
+      }
+    }
+  }
+  return errors;
+}
+
+/**
+ * Quick 261015-ect (QD-13): the vault-family rule for `requiresPlatformBindings`,
+ * the mirror of the vaultMode rule (c) above. A capability that is `vault` or
+ * lists `vault` in `requires` MUST declare the field, so a vault-family
+ * capability added later cannot render hooks on a project the vault does not
+ * govern by forgetting it. A capability outside the family may declare it too.
+ *
+ * @param {Map<string, object>} capMap
+ * @returns {string[]} error strings; empty = all pass
+ */
+function validatePlatformBindingsField(capMap) {
+  const errors = [];
+  for (const [capId, cap] of capMap) {
+    if (!cap || typeof cap !== 'object') continue;
+    const requiresVault = Array.isArray(cap.requires) && cap.requires.includes('vault');
+    if (capId !== 'vault' && !requiresVault) continue;
+    if (!Object.prototype.hasOwnProperty.call(cap, 'requiresPlatformBindings')) {
+      errors.push(
+        'capability "' + capId + '" is vault or requires vault and must declare requiresPlatformBindings, ' +
+        'so a vault-family capability cannot render hooks on a project the vault does not govern',
+      );
+    }
+  }
+  return errors;
+}
+
+/**
+ * Phase 16 D-19: the per-hook seal field's name. The resolver reads it as
+ * `SEAL_FIELD` from capability-state; this generator cannot require that module
+ * (its load graph reaches surface.cjs and config-loader.cjs, which read the
+ * very registry this script regenerates), so the literal is restated here and
+ * pinned equal to `SEAL_FIELD` by tests/capability-registry.test.cjs.
+ */
+const SEAL_FIELD_NAME = 'onRecordedArtifacts';
+
+/**
+ * Phase 16 D-19 / D-25 / D-26: validate the per-hook seal field.
+ *
+ * A gate carrying the field renders for an enabled, config-inactive capability
+ * over recorded vault artifacts, bypassing the capability's active check and
+ * its `when` (D-18). That is a widening of render behaviour, so the field is
+ * closed HERE, at generation, to exactly the shape the two shipped seal gates
+ * have. Six rules, each reported on its own:
+ *   (a) gates only (a step or contribution carrying it is refused);
+ *   (b) the value is literal `true` (`"true"`, `1`, `null`, `false` refused);
+ *   (c) the declaring capability lists `vault` in `requires` and is not `vault`
+ *       itself (D-26: with the vault off the injected mode is null, so both
+ *       modes' filtered gates pass and sealing the vault capability too would
+ *       dispatch `check vault.trace` twice);
+ *   (d) the gate also carries `vaultMode` (the resolver filters by mode BEFORE
+ *       the predicate, research C-1);
+ *   (e) the gate is `blocking: true`;
+ *   (f) the point is `ship:pre` (D-21: the requirement's block point; a seal at
+ *       verify:post would halt execute-phase on a switch set on purpose).
+ *
+ * Presence is own-property presence.
+ *
+ * @param {Map<string, object>} capMap
+ * @returns {string[]} error strings; empty = all pass
+ */
+function validateSealField(capMap) {
+  const errors = [];
+  const KINDS = [['steps', 'step'], ['contributions', 'contribution'], ['gates', 'gate']];
+  for (const [capId, cap] of capMap) {
+    if (!cap || typeof cap !== 'object') continue;
+    const prefix = 'capability "' + capId + '"';
+    const requiresVault = Array.isArray(cap.requires) && cap.requires.includes('vault');
+    for (const [arrKey, kind] of KINDS) {
+      const arr = Array.isArray(cap[arrKey]) ? cap[arrKey] : [];
+      for (const hook of arr) {
+        if (!hook || typeof hook !== 'object') continue;
+        if (!Object.prototype.hasOwnProperty.call(hook, SEAL_FIELD_NAME)) continue;
+        const where = prefix + ' ' + kind + ' at point "' + String(hook.point) + '"';
+        const value = hook[SEAL_FIELD_NAME];
+        if (kind !== 'gate') {
+          errors.push(where + ': ' + SEAL_FIELD_NAME + ' is allowed on gates only');
+          continue;
+        }
+        if (value !== true) {
+          errors.push(where + ': ' + SEAL_FIELD_NAME + ' must be literal true (got ' + JSON.stringify(value) + ')');
+        }
+        if (capId === 'vault' || !requiresVault) {
+          errors.push(
+            where + ': ' + SEAL_FIELD_NAME + ' is allowed only on a capability that lists "vault" in requires ' +
+            'and is not "vault" itself',
+          );
+        }
+        if (!Object.prototype.hasOwnProperty.call(hook, 'vaultMode')) {
+          errors.push(where + ': a gate carrying ' + SEAL_FIELD_NAME + ' must also carry vaultMode');
+        }
+        if (hook.blocking !== true) {
+          errors.push(where + ': a gate carrying ' + SEAL_FIELD_NAME + ' must be blocking: true');
+        }
+        if (hook.point !== 'ship:pre') {
+          errors.push(where + ': ' + SEAL_FIELD_NAME + ' is allowed only at point "ship:pre"');
+        }
+      }
+    }
+  }
+  return errors;
+}
+
 /**
  * C1+C2: Global consumes-satisfiability validation.
  *
@@ -1490,6 +1662,18 @@ const TIER_RANK = { core: 0, standard: 1, full: 2 };
 function validateCrossCapability(capMap, centralKeys) {
   const errors = [];
 
+  // Phase 15 D-02: the per-hook vaultMode filter field (needs capMap to read the
+  // vault capability's closed value set and every capability's `requires`).
+  errors.push(...validateVaultModeField(capMap));
+
+  // Phase 16 D-19: the per-hook seal field (needs capMap for every capability's
+  // `requires`).
+  errors.push(...validateSealField(capMap));
+
+  // Quick 261015-ect (QD-13): every vault-family capability declares
+  // requiresPlatformBindings (needs capMap for every capability's `requires`).
+  errors.push(...validatePlatformBindingsField(capMap));
+
   // Ownership: one owner per skill stem + agent name
   const skillOwner = new Map(); // skill → capId
   const agentOwner = new Map(); // agent → capId
@@ -2657,6 +2841,10 @@ module.exports = {
   validateAgainstContract,
   validateConsumesGlobal,
   validateCrossCapability,
+  validateVaultModeField,
+  validateSealField,
+  validatePlatformBindingsField,
+  SEAL_FIELD_NAME,
   classifyCrossErrors,
   loadCentralConfigKeys,
   loadAndValidate,

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

@@ -0,0 +1,412 @@
+#!/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();