cabloy 5.1.213 → 5.1.215

package/repo-agent-governance/tests/governance.test.mjs

@@ -147,6 +147,23 @@ test('governance adoption creates state and is idempotent', () => {
   });
 });
 
+test('evidence commands are distributed through both governance reconciliation paths', () => {
+  const packageJson = JSON.parse(readFileSync(resolve(ROOT_DIR, 'package.json'), 'utf8'));
+  const bootstrap = readFileSync(resolve(ROOT_DIR, 'scripts/bootstrapAgentGovernance.mjs'), 'utf8');
+  const upgrade = readFileSync(resolve(ROOT_DIR, 'scripts/upgrade.ts'), 'utf8');
+  const bootstrapList = bootstrap.match(/const GOVERNANCE_SCRIPT_NAMES = \[([\s\S]*?)\];/)[1];
+  const upgradeList = upgrade.match(/const governanceScripts = \[([\s\S]*?)\];/)[1];
+  for (const mode of ['sanitize', 'check']) {
+    const name = `evidence:${mode}`;
+    assert.equal(
+      packageJson.scripts[name],
+      `node repo-agent-governance/tools/evidence-paths/sanitize.mjs ${mode}`,
+    );
+    assert.ok(bootstrapList.includes(`'${name}'`));
+    assert.ok(upgradeList.includes(`'${name}'`));
+  }
+});
+
 test('initializer adopts canonical adapters for a fresh transition package', () => {
   withFixture(root => {
     const scriptsDirectory = resolve(root, 'scripts');
@@ -179,6 +196,8 @@ test('initializer preserves a legacy-customized adapter during a staged upgrade'
     writeFileSync(resolve(root, 'CLAUDE.md'), 'legacy project customization\n');
     const projectPackage = JSON.parse(readFileSync(resolve(ROOT_DIR, 'package.json'), 'utf8'));
     delete projectPackage.scripts['spec:check'];
+    delete projectPackage.scripts['evidence:sanitize'];
+    projectPackage.scripts['evidence:check'] = 'node obsolete-evidence-check.mjs';
     projectPackage.scripts['project:custom'] = 'node project-owned.mjs';
     writeFileSync(resolve(root, 'package.json'), JSON.stringify(projectPackage));
 
@@ -207,6 +226,12 @@ test('initializer preserves a legacy-customized adapter during a staged upgrade'
       updatedPackage.scripts['spec:check'],
       'node ./repo-agent-governance/tools/spec-audit/audit.mjs',
     );
+    for (const mode of ['sanitize', 'check']) {
+      assert.equal(
+        updatedPackage.scripts[`evidence:${mode}`],
+        `node repo-agent-governance/tools/evidence-paths/sanitize.mjs ${mode}`,
+      );
+    }
     assert.equal(updatedPackage.scripts['project:custom'], 'node project-owned.mjs');
   });
 });

package/repo-agent-governance/tools/evidence-paths/sanitize.mjs

@@ -0,0 +1,549 @@
+import { constants, realpathSync } from 'node:fs';
+import { lstat, open, readdir } from 'node:fs/promises';
+import { homedir, tmpdir } from 'node:os';
+import { basename, join, parse, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const DEFAULT_REPO_ROOT = resolve(fileURLToPath(import.meta.url), '../../../..');
+export const LINE_LIMIT = 1024 * 1024;
+export const FILE_LIMIT = 8 * 1024 * 1024;
+
+class SafeError extends Error {
+  constructor(code) {
+    super(code);
+    this.code = code;
+  }
+}
+
+function fail(code) {
+  throw new SafeError(code);
+}
+
+function rootInfo(value) {
+  if (
+    typeof value !== 'string' ||
+    Array.from(value).some(char => char.codePointAt(0) < 32 || char.codePointAt(0) === 127)
+  ) {
+    fail('INVALID_ROOT');
+  }
+  const windows = /^[A-Za-z]:[/\\]/u.test(value) || /^\\\\[^\\]+\\[^\\]+/u.test(value);
+  if (!windows && !value.startsWith('/')) fail('INVALID_ROOT');
+  let root = windows ? value.replaceAll('\\', '/') : value;
+  root = root.replace(/\/+$/u, '');
+  // Volume roots would turn a bounded recognizer into a universal slash matcher.
+  if (
+    !root ||
+    /^[A-Za-z]:$/u.test(root) ||
+    root.split('/').some(part => part === '.' || part === '..')
+  ) {
+    fail('INVALID_ROOT');
+  }
+  return { root, windows, key: windows ? root.toLowerCase() : root };
+}
+
+function escapeRegex(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
+}
+
+function rootPattern(info) {
+  const pieces = info.root.split('/').map(escapeRegex);
+  // A separator may be native, forward-slash, or a JSON-escaped backslash.
+  return pieces.join(info.windows ? '(?:\\\\{1,2}|/)' : '/');
+}
+
+function nativeRoots() {
+  const roots = [];
+  for (const value of [homedir(), tmpdir()]) {
+    if (!value) continue;
+    roots.push(value);
+    try {
+      roots.push(realpathSync(value));
+    } catch {
+      // Lexical coverage remains available when a native root does not exist.
+    }
+  }
+  return roots;
+}
+
+function pathEnd(text, start, quoted) {
+  let end = start;
+  while (end < text.length) {
+    const char = text[end];
+    if (/[\r\n\t"'`<>(){}[\]|,;!?]/u.test(char) || (!quoted && /\s/u.test(char))) break;
+    // Preserve stack line/column suffixes (and keep other colon-delimited prose out).
+    if (char === ':') break;
+    end++;
+  }
+  // Sentence punctuation is not part of an unquoted path token.
+  if (!quoted) {
+    while (end > start && text[end - 1] === '.') end--;
+  }
+  return end;
+}
+
+function boundary(text, index) {
+  return index === 0 || !/[\p{L}\p{N}_./\\%~@+\->]/u.test(text[index - 1]);
+}
+
+function normalizeTail(value, windows) {
+  return windows ? value.replace(/\\{1,2}/gu, '/') : value;
+}
+
+/** Shared, bounded recognition. No universal absolute-path detection is attempted. */
+export function createMatcher({ repoRoot = DEFAULT_REPO_ROOT, maps = [] } = {}) {
+  const explicit = [];
+  const seen = new Map();
+  function add(value, alias, privateRoot = false) {
+    const info = rootInfo(value);
+    const prior = seen.get(info.key);
+    if (prior) {
+      if (!privateRoot && prior.alias !== alias) fail('CONFLICTING_ROOT');
+      return;
+    }
+    const entry = { ...info, alias, privateRoot };
+    entry.regex = new RegExp(rootPattern(info), info.windows ? 'iy' : 'y');
+    explicit.push(entry);
+    seen.set(info.key, entry);
+  }
+  add(repoRoot, null);
+  if (!Array.isArray(maps)) fail('INVALID_MAP');
+  for (const map of maps) {
+    if (!map || typeof map.alias !== 'string') fail('INVALID_MAP');
+    const alias = map.alias.replace(/^<([A-Z][A-Z0-9_]*)>$/u, '$1');
+    if (!/^[A-Z][A-Z0-9_]*$/u.test(alias)) fail('INVALID_ALIAS');
+    add(map.root, alias);
+  }
+  for (const root of nativeRoots()) add(root, 'PRIVATE_PATH', true);
+  explicit.sort(
+    (a, b) => b.root.length - a.root.length || Number(a.privateRoot) - Number(b.privateRoot),
+  );
+
+  const sep = '(?:\\\\{1,2}|/)';
+  const account = '[^/\\\\\\s"\'`<>(){}[\\]|,;:!?]+(?: [^/\\\\\\s"\'`<>(){}[\\]|,;:!?]+)*';
+  const known = [
+    new RegExp(`/(?:Users|home)/${account}`, 'y'),
+    /\/(?:private\/)?tmp/y,
+    /\/(?:private\/)?var\/folders/y,
+    new RegExp(`[A-Z]:${sep}(?:Users${sep}${account}|(?:Windows${sep})?Temp)`, 'iy'),
+    // UNC is a filesystem convention; forward-slash protocol-relative URLs are not.
+    /\\{2,4}[^\\/\s"'`<>(){}[\]|,;:!?]+\\{1,2}[^\\/\s"'`<>(){}[\]|,;:!?]+/y,
+  ];
+
+  function recognizeAt(text, start, quoted = false) {
+    for (const entry of explicit) {
+      entry.regex.lastIndex = start;
+      const match = entry.regex.exec(text);
+      if (!match) continue;
+      const after = start + match[0].length;
+      if (after < text.length && !/[/\\\s"'`<>(){}[\]|,;:!?]/u.test(text[after])) continue;
+      const end = pathEnd(text, after, quoted);
+      const tail = normalizeTail(text.slice(after, end), entry.windows).replace(/^\/+|\/+$/gu, '');
+      const replacement =
+        entry.privateRoot || tail.split('/').some(part => part === '.' || part === '..')
+          ? '<PRIVATE_PATH>'
+          : entry.alias
+            ? `<${entry.alias}>${tail ? `/${sanitize(tail)}` : ''}`
+            : tail
+              ? sanitize(tail)
+              : '.';
+      return { end, replacement };
+    }
+    for (const regex of known) {
+      regex.lastIndex = start;
+      const match = regex.exec(text);
+      if (!match) continue;
+      const after = start + match[0].length;
+      if (after < text.length && !/[/\\\s"'`<>(){}[\]|,;:!?]/u.test(text[after])) continue;
+      return { end: pathEnd(text, after, quoted), replacement: '<PRIVATE_PATH>' };
+    }
+    return null;
+  }
+
+  function find(text) {
+    if (typeof text !== 'string') fail('INVALID_TEXT');
+    const matches = [];
+    // Skip non-file URLs as units, including their paths, query strings and fragments.
+    const urls = /[A-Za-z][A-Za-z0-9+.-]{0,31}:\/\/[^\s"'`<>(){}[\]|]+/gu;
+    const protectedUrls = [...text.matchAll(urls)];
+    let urlIndex = 0;
+    for (let index = 0; index < text.length; index++) {
+      const url = protectedUrls[urlIndex];
+      if (url && index === url.index) {
+        urlIndex++;
+        if (/^file:\/\//iu.test(url[0]) && boundary(text, index)) {
+          try {
+            const parsed = new URL(url[0]);
+            let local = decodeURIComponent(parsed.pathname);
+            if (parsed.hostname && parsed.hostname !== 'localhost') {
+              local = `\\\\${parsed.hostname}${local.replaceAll('/', '\\')}`;
+            } else if (/^\/[A-Za-z]:\//u.test(local)) {
+              local = local.slice(1);
+            }
+            const found = recognizeAt(local, 0, true);
+            matches.push({
+              start: index,
+              end: index + url[0].length,
+              replacement: found ? found.replacement + local.slice(found.end) : '<PRIVATE_PATH>',
+            });
+          } catch {
+            // Malformed file URLs are not safe to partially decode or echo.
+            matches.push({
+              start: index,
+              end: index + url[0].length,
+              replacement: '<PRIVATE_PATH>',
+            });
+          }
+        }
+        index += url[0].length - 1;
+        continue;
+      }
+      if (!boundary(text, index)) continue;
+      const quoted = index > 0 && /["'`]/u.test(text[index - 1]);
+      const found = recognizeAt(text, index, quoted);
+      if (found) {
+        matches.push({ start: index, ...found });
+        index = found.end - 1;
+      }
+    }
+    return matches;
+  }
+
+  function sanitize(text) {
+    let result = '';
+    let offset = 0;
+    for (const match of find(text)) {
+      result += text.slice(offset, match.start) + match.replacement;
+      offset = match.end;
+    }
+    return result + text.slice(offset);
+  }
+  return Object.freeze({ find, sanitize });
+}
+
+function decode(bytes) {
+  try {
+    return new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes);
+  } catch {
+    fail('INVALID_UTF8');
+  }
+}
+
+async function write(output, text) {
+  try {
+    await new Promise((resolveWrite, reject) => {
+      output.write(text, error => (error ? reject(error) : resolveWrite()));
+    });
+  } catch {
+    fail('OUTPUT_ERROR');
+  }
+}
+
+/** Emits only fully validated, sanitized lines; preceding successful lines may remain on failure. */
+export async function sanitizeStream(input, output, { matcher = createMatcher() } = {}) {
+  let outputFailed = false;
+  const onError = () => {
+    outputFailed = true;
+  };
+  output.on('error', onError);
+  let parts = [];
+  let length = 0;
+  try {
+    for await (const chunk of input) {
+      if (outputFailed) fail('OUTPUT_ERROR');
+      // Buffer input is required so upstream decoding cannot hide invalid UTF-8.
+      if (!(chunk instanceof Uint8Array)) fail('INVALID_INPUT');
+      const bytes = Buffer.from(chunk.buffer, chunk.byteOffset, chunk.byteLength);
+      let start = 0;
+      while (start < bytes.length) {
+        const newline = bytes.indexOf(10, start);
+        const end = newline < 0 ? bytes.length : newline;
+        length += end - start;
+        if (length > LINE_LIMIT) fail('LINE_LIMIT');
+        parts.push(bytes.subarray(start, end));
+        if (newline < 0) break;
+        const line = Buffer.concat(parts, length);
+        if (binary(line)) fail('BINARY');
+        const text = decode(line);
+        await write(output, `${matcher.sanitize(text)}\n`);
+        parts = [];
+        length = 0;
+        start = newline + 1;
+      }
+    }
+    if (length) {
+      const line = Buffer.concat(parts, length);
+      if (binary(line)) fail('BINARY');
+      await write(output, matcher.sanitize(decode(line)));
+    }
+    if (outputFailed) fail('OUTPUT_ERROR');
+  } catch (error) {
+    if (error instanceof SafeError) throw error;
+    fail('INPUT_ERROR');
+  } finally {
+    output.off('error', onError);
+  }
+}
+
+function safeFilename(value, matcher) {
+  return matcher
+    .sanitize(value)
+    .replace(
+      /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}:\\]/gu,
+      char => `\\u${char.codePointAt(0).toString(16).padStart(4, '0')}`,
+    );
+}
+
+function binary(bytes) {
+  return bytes.some(
+    byte => byte === 0 || byte === 127 || (byte < 32 && ![9, 10, 12, 13].includes(byte)),
+  );
+}
+
+async function ancestorExclusion(path) {
+  const root = parse(path).root;
+  let current = root;
+  // resolve() normalizes native separators; POSIX backslashes remain literal filename characters.
+  for (const part of path.slice(root.length).split(sep)) {
+    if (!part) continue;
+    if (part.startsWith('.env')) return 'ENV_EXCLUDED';
+    current = join(current, part);
+    try {
+      if ((await lstat(current)).isSymbolicLink()) return 'SYMLINK_EXCLUDED';
+    } catch {
+      return 'UNREADABLE';
+    }
+  }
+  return null;
+}
+
+/** Read-only, explicit scopes. Incomplete takes precedence over findings. */
+export async function checkPaths(scopes, { matcher = createMatcher() } = {}) {
+  if (
+    !Array.isArray(scopes) ||
+    !scopes.length ||
+    scopes.some(scope => typeof scope !== 'string' || !scope)
+  ) {
+    fail('INVALID_SCOPE');
+  }
+  const diagnostics = [];
+  let incomplete = false;
+  let findings = false;
+  function report(label, line, code) {
+    diagnostics.push(`${label}:${line} ${code}`);
+    if (code === 'PATH_FOUND') findings = true;
+    else incomplete = true;
+  }
+  async function scan(path, label) {
+    if (basename(path).startsWith('.env')) {
+      report(label, 0, 'ENV_EXCLUDED');
+      return;
+    }
+    let stat;
+    try {
+      stat = await lstat(path);
+    } catch {
+      report(label, 0, 'UNREADABLE');
+      return;
+    }
+    if (stat.isSymbolicLink()) {
+      report(label, 0, 'SYMLINK_EXCLUDED');
+      return;
+    }
+    if (stat.isDirectory()) {
+      let entries;
+      try {
+        entries = await readdir(path);
+      } catch {
+        report(label, 0, 'UNREADABLE');
+        return;
+      }
+      entries.sort();
+      for (const entry of entries)
+        await scan(join(path, entry), `${label}/${safeFilename(entry, matcher)}`);
+      return;
+    }
+    if (!stat.isFile()) {
+      report(label, 0, 'SPECIAL_EXCLUDED');
+      return;
+    }
+    if (stat.size > FILE_LIMIT) {
+      report(label, 0, 'SIZE_LIMIT');
+      return;
+    }
+    // POSIX mode-000 files remain unreadable even for privileged runners; Windows relies on open/ACL errors.
+    if (process.platform !== 'win32' && (stat.mode & 0o444) === 0) {
+      report(label, 0, 'UNREADABLE');
+      return;
+    }
+    let handle;
+    let bytes;
+    try {
+      handle = await open(
+        path,
+        constants.O_RDONLY | (constants.O_NOFOLLOW || 0) | (constants.O_NONBLOCK || 0),
+      );
+      const opened = await handle.stat();
+      if (!opened.isFile() || opened.ino !== stat.ino || opened.dev !== stat.dev)
+        fail('UNREADABLE');
+      const chunks = [];
+      let size = 0;
+      while (true) {
+        const buffer = Buffer.alloc(64 * 1024);
+        const { bytesRead } = await handle.read(buffer, 0, buffer.length, null);
+        if (!bytesRead) break;
+        size += bytesRead;
+        if (size > FILE_LIMIT) fail('SIZE_LIMIT');
+        chunks.push(buffer.subarray(0, bytesRead));
+      }
+      bytes = Buffer.concat(chunks, size);
+    } catch (error) {
+      report(label, 0, error instanceof SafeError ? error.code : 'UNREADABLE');
+      return;
+    } finally {
+      if (handle) await handle.close().catch(() => {});
+    }
+    if (binary(bytes)) {
+      report(label, 0, 'BINARY');
+      return;
+    }
+    let text;
+    try {
+      text = decode(bytes);
+    } catch {
+      report(label, 0, 'INVALID_UTF8');
+      return;
+    }
+    const lines = text.split('\n');
+    if (lines.some(line => Buffer.byteLength(line) > LINE_LIMIT)) {
+      report(label, 0, 'LINE_LIMIT');
+      return;
+    }
+    for (let index = 0; index < lines.length; index++) {
+      if (matcher.find(lines[index]).length) report(label, index + 1, 'PATH_FOUND');
+    }
+  }
+  // Input order defines stable scope IDs; each directory is visited in lexical order.
+  for (const [index, scope] of scopes.entries()) {
+    const path = resolve(scope);
+    const label = `scope-${index + 1}`;
+    const exclusion = await ancestorExclusion(path);
+    if (exclusion) {
+      report(label, 0, exclusion);
+    } else {
+      let directory = false;
+      try {
+        directory = (await lstat(path)).isDirectory();
+      } catch {
+        /* scan reports safely */
+      }
+      await scan(path, directory ? label : `${label}/${safeFilename(basename(path), matcher)}`);
+    }
+  }
+  return { status: incomplete ? 2 : findings ? 1 : 0, diagnostics };
+}
+
+const HELP = `Usage:
+  node sanitize.mjs sanitize [--repo-root ROOT] [--map ROOT=ALIAS ...]
+  node sanitize.mjs check [--repo-root ROOT] [--map ROOT=ALIAS ...] -- FILE_OR_DIR ...
+
+sanitize reads raw UTF-8 stdin and writes sanitized stdout only. It never runs commands,
+opens input files, writes files, or spools raw input. check is read-only and scans only
+explicit scopes, recursively in sorted order, without extension filtering.
+ROOT must be an absolute Unix, drive-qualified Windows, or backslash UNC path (not a
+volume root). ALIAS is NAME or <NAME>, matching [A-Z][A-Z0-9_]*. Repeat --map to add
+roots. Longest root wins; conflicting replacements for the same root are rejected.
+The default repo root is resolved from this tool's location, not the working directory.
+Checkout paths become repo-relative (root becomes .); maps become <ALIAS>/suffix.
+Native os home/temp roots (lexical and realpath), /Users/name, /home/name, /tmp,
+/private/tmp, /var/folders, /private/var/folders, Windows Users/Temp conventions and
+backslash UNC paths become <PRIVATE_PATH> for the complete recognized path token.
+Native/forward/JSON-escaped Windows separators and file:// URLs are supported.
+Quote path tokens containing spaces; explicit root spaces and account-name spaces
+are also recognized. Unquoted tokens end at whitespace or common prose delimiters.
+Stack :line:column suffixes are preserved. Non-file URLs, unrelated API/container
+paths and unknown absolute roots are left unchanged: this is NOT a universal secret
+scanner. Use explicit maps for other local roots; inspect output before publication.
+UTF-8 decoding is fatal, with a 1 MiB byte limit per line (including CR, excluding LF).
+NUL, DEL and non-text C0 controls are rejected; tab, LF, form feed and CR are allowed.
+Only complete validated lines are emitted; earlier sanitized lines may survive failure.
+check limits each file to 8 MiB, treats NUL/non-text controls as binary, and reports only
+scope-N/relative-filename:line CODE, never source lines or absolute scan roots.
+Symlinks (including scope ancestors), special files, .env* files/directories, unreadable,
+binary, invalid UTF-8 and over-limit files make checking incomplete. Scope trees must
+remain stable while scanning; this is not an adversarial filesystem snapshot.
+Exit status: sanitize 0 success / 2 error; check 0 clean / 1 findings / 2 incomplete/error.
+Options must precede --; check requires -- and at least one explicit scope.
+`;
+
+export async function runCli(
+  args,
+  { input = process.stdin, output = process.stdout, error = process.stderr } = {},
+) {
+  let outputFailed = false;
+  const onError = () => {
+    outputFailed = true;
+  };
+  output.on('error', onError);
+  // Diagnostics must themselves tolerate a closed stderr, without a raw exception stack.
+  const ignoreError = () => {};
+  error.on('error', ignoreError);
+  try {
+    if (args.length === 1 && args[0] === '--help') {
+      await write(output, HELP);
+      return 0;
+    }
+    const [command, ...rest] = args;
+    if (!['sanitize', 'check'].includes(command)) fail('INVALID_USAGE');
+    if (rest.length === 1 && rest[0] === '--help') {
+      await write(output, HELP);
+      return 0;
+    }
+    const options = { maps: [] };
+    let scopes;
+    for (let index = 0; index < rest.length; index++) {
+      const arg = rest[index];
+      if (arg === '--' && command === 'check') {
+        scopes = rest.slice(index + 1);
+        break;
+      }
+      if (!['--repo-root', '--map'].includes(arg) || index + 1 >= rest.length)
+        fail('INVALID_USAGE');
+      const value = rest[++index];
+      if (arg === '--repo-root') {
+        if (options.repoRoot !== undefined) fail('INVALID_USAGE');
+        options.repoRoot = value;
+      } else {
+        const equal = value.lastIndexOf('=');
+        if (equal <= 0) fail('INVALID_MAP');
+        options.maps.push({ root: value.slice(0, equal), alias: value.slice(equal + 1) });
+      }
+    }
+    const matcher = createMatcher(options);
+    if (command === 'sanitize') {
+      await sanitizeStream(input, output, { matcher });
+      return 0;
+    }
+    if (!scopes?.length) fail('INVALID_SCOPE');
+    const result = await checkPaths(scopes, { matcher });
+    for (const diagnostic of result.diagnostics) await write(output, `${diagnostic}\n`);
+    if (outputFailed) fail('OUTPUT_ERROR');
+    return result.status;
+  } catch (caught) {
+    const code = caught instanceof SafeError ? caught.code : 'INTERNAL_ERROR';
+    try {
+      await write(error, `evidence-paths: ${code}\n`);
+    } catch {
+      /* no unsafe fallback */
+    }
+    return 2;
+  } finally {
+    output.off('error', onError);
+    error.off('error', ignoreError);
+  }
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  runCli(process.argv.slice(2)).then(status => {
+    process.exitCode = status;
+  });
+}

package/repo-docs/ai/ai-spec-driven-development.md

@@ -73,6 +73,18 @@ Before source work begins, an **execution dossier** makes the unit explicit: tar
 
 This structure lets a team pause, review, or transfer work without treating an unfinished implementation as verified. See [Execute an Approved Cabloy Specification Increment](/ai/playbook-spec-execution) for the readiness gates, routing rules, evidence protocol, and handoff format.
 
+## Converge planning into implementation
+
+Planning should resolve the material blockers of the next bounded increment, not specify every future detail before any code is written. Keep a finite blocker/exit checklist in the existing owning records: the unresolved decision, why it blocks this increment, its decision owner, and the condition that closes it. Separate deferrable details and later increments; batch related decisions instead of turning each clarification into another preparation and review cycle.
+
+Before adding a planning pass, explain which blocker or material uncertainty it addresses, what new fact or decision value it should provide, and how it ends. If the next pass only restates an accepted direction without a justified new approach to the remaining blockers, report stalled convergence and recommend a concrete decision, bounded feasibility check, or scope disposition. A larger document or another review is not delivery progress by itself.
+
+Blockers follow actual dependencies, not the whole suite by default. A blocked identity integration does not necessarily block an independent capability whose own contracts, dependencies, safety boundary, and verification plan are ready. Conversely, a frontend change that depends on an unresolved response contract cannot bypass that dependency by calling itself an independent increment. Surface a meaningful, independently verifiable candidate for approval when available; if none exists, state why. Foundation-only work is useful only when it has explicit integration value and checks, not merely an empty scaffold presented as feature completion.
+
+Planning is sufficient for an increment when its material contracts, dependencies, scope, safety constraints, and verification plan are settled. At that point, request any missing execution approval or proceed within valid existing approval. Reuse an unchanged approved dossier after checking current revision, worktree attribution, and evidence applicability; a skill handoff, resumed session, or ordinary implementation substep is not a reason to request the same permission again. Material changes, newly observed risks, and the approval's own conditions can require renewed approval; prior approval never covers unrelated tasks or unapproved external/destructive operations.
+
+This is not a fixed limit on planning rounds or a relaxation of security requirements. Preserve mandatory reviews, predecessor proof, and any specifically required pre-implementation qualification. The new implementation's runtime ATP proof normally follows implementation; it must not become an impossible prerequisite to writing that implementation. Evidence and release gates still control later verification and release claims. A genuine new risk can reopen planning, but the return should name the affected blocker and its exit condition rather than restart open-ended refinement.
+
 ## Contract Loop is complementary
 
 [Contract Loop](/fullstack/contract-loop-playbook) is Cabloy's bidirectional Vona↔Zova synchronization model. It determines where fullstack contract truth lives, which generated handoff must be refreshed, and how to recover from forward-chain, reverse-chain, consumer, or local-dependency drift.

package/repo-docs/ai/playbook-spec-execution.md

@@ -102,11 +102,29 @@ The execution workflow supplies the approved dossier and preserves the boundary;
 Use the narrowest approved check first, then follow the linked ATP procedures and applicable release gates.
 
 1. run the scoped verification specified by the increment
-2. retain observed evidence using the suite's existing convention
-3. redact secrets, credentials, raw tokens, customer data, and provider identifiers
+2. sanitize machine-local paths and review secrets, credentials, raw tokens, customer data, and provider identifiers **before** durable retention or sharing
+3. retain only reviewed, redacted observed evidence using the suite's existing convention
 4. record failures, waivers, invalidation, and supersession rather than erasing history
 5. update evidence before updating derived progress
 
+For path-bearing output, combine producer stdout/stderr before sanitizing; do not save a raw intermediate log or use `tee` ahead of the sanitizer. For example, in Bash, using a new output filename (do not enable `set -e` before capturing a known failing verification result):
+
+```bash
+set -o pipefail
+set -o noclobber
+npm run --silent test:agent-governance 2>&1 | npm run --silent evidence:sanitize > evidence.pending.txt
+stage_status=( "${PIPESTATUS[@]}" )
+printf 'producer_exit=%s sanitizer_exit=%s\n' "${stage_status[0]}" "${stage_status[1]}"
+# Only check/retain the artifact if sanitizer_exit is 0; preserve producer failure.
+if [ "${stage_status[1]}" -eq 0 ]; then
+  npm run --silent evidence:check -- -- evidence.pending.txt
+fi
+```
+
+Choose the producer from the approved verification scope; this example does not authorize unrelated tests. Evaluate both producer and sanitizer statuses before accepting the artifact. `pipefail` catches upstream failure, but exact per-stage exit codes require immediately capturing Bash `PIPESTATUS` or Zsh `pipestatus` before another command. A failed sanitizer may leave partial sanitized output; do not accept it as evidence. A clean path check cannot turn a failed test into a pass. This pipeline is Bash-specific; Windows/PowerShell requires deliberate UTF-8 handling and separate native process statuses. See [Windows and PowerShell](/reference/repo-scripts#windows-and-powershell) rather than reusing Bash/Zsh syntax.
+
+The sanitizer preserves checkout-relative locations and uses aliases for external roots. It does not automatically intercept terminal/tool output, recognize every absolute path, remove secrets, or certify safe publication. Review remaining sensitive data separately. Preserve original failures, diagnostic meaning and source hashes; label sanitized historical diffs as path-redacted, not byte-exact/apply-ready. See [Evidence path sanitization](/reference/repo-scripts#evidence-path-sanitization) for mappings, supported coverage and incomplete-scan behavior.
+
 Use status precisely:
 
 - `in-progress` — approved work or verification has actually begun

package/repo-docs/backend/migration-and-changes.md

@@ -173,6 +173,8 @@ This is valuable because shared baseline data becomes part of the structured ver
 
 Vona invokes `seed()` while the application starts in test mode (`npm run test` or managed E2E), and during an explicit `npm run db:reset` in dev mode. In **Cabloy Basic and Cabloy Start**, ordinary `npm run dev` and `npm run dev:one` only reuse existing managed disposable databases and never seed; a missing required database makes startup fail with an instruction to run `npm run db:reset`. Framework upgrades do not reset existing development data or repeat its seeds. Use `seed()` for durable baseline fixtures shared by tests or for freshly prepared local development data. Seeding follows instance initialization on a newly created or recreated disposable database; `seed()` is not a repeatable, same-database data-import mechanism. See [Managed development database preparation](#managed-development-database-preparation) for the explicit reset lifecycle.
 
+In **Cabloy Basic and Cabloy Start**, automatic `seed()` execution is limited to the default instance (`''`). These records are convenience fixtures for test/dev use, not required business initialization data. Reset still migrates and initializes configured isolated targets such as `isolateTest`, but does not seed them: they can exercise multi-instance behavior without shared test fixtures. Use `init()` for initialization required by each instance.
+
 Treat shared `seed()` records as read-only in ordinary tests. A scenario that needs different state must create independent, test-owned data and clean it up in `finally`; it must not mutate or delete the shared baseline. `seed()` remains distinct from `init()`: use `init()` for instance-aware initialization data and reserve `seed()` for baseline data in test runs or explicit development resets.
 
 ## Version changes across the generated backend thread
@@ -217,7 +219,9 @@ When `database.testDatabase: true` enables framework-managed disposable dev data
 1. **Check every required target:** both shared and statically configured isolate database targets must exist. If any required target is missing, startup fails promptly with an instruction to run `npm run db:reset`; it does not create the target, perform creation-time Redis cleanup, or seed as a fallback.
 2. **Reuse existing databases:** keep their data without database creation, creation-time Redis cleanup, or module seeding. Ordinary startup is not a fixture refresh, an implicit reset, or recovery for a partial reset. Non-disposable databases are outside this managed reset path.
 
-An explicit `npm run db:reset` owns preparation in a single process. It requires `database.testDatabase: true` and a connection outside the disposable database. It clears validated application-owned Redis state with `clearAllData()`, drops and recreates the managed disposable dev databases, runs migrations and instance initialization, then invokes the owning modules' `seed()` hooks.
+An explicit `npm run db:reset` owns preparation in a single process. It requires `database.testDatabase: true` and a connection outside the disposable database. It clears validated application-owned Redis state with `clearAllData()`, drops and recreates the managed disposable dev databases, and runs migrations. It then completes each instance's non-after startups and initialization in sequence. Only the default instance runs the owning modules' `seed()` hooks, after its initialization and before consuming its creation bookkeeping and setting its readiness flag; isolated instances initialize and become ready without seeding.
+
+Reset skips all instance and application startups with `after: true`: schedule loading, runtime JSON generation, development tips, queue-worker preloading, and HTTP listening are runtime-server work, not reset prerequisites. Put required data preparation in migrations, `init()`, `seed()`, or non-after startups. Normal dev startup still runs after-startups; independent framework lifecycle hooks and reset's application teardown remain intact. See [Backend Startup Guide](/backend/startup-guide#app-startup-and-instance-startup-in-practice) for the phase boundary.
 
 **Stop the development server and any other processes using the same database and Redis namespace first.** There is no file-based preparation lock; concurrent dev/dev and dev/reset against the same database and Redis namespace are unsupported. The reset command disables its own listener, but that does not protect a concurrently running server or queue worker. Never reset development data you need to keep.