@plainconceptsplatform/workflows 1.11.0 → 1.13.0

package/loops/templates/platform-template/scripts/check-platform-conformance.mjs

@@ -1,21 +1,28 @@
 #!/usr/bin/env node
 // Managed by @plainconceptsplatform/workflows. Source: loops/templates/platform-template/scripts/check-platform-conformance.mjs. Update with `workflows update --force`; consumer edits may be overwritten.
-// The .platform/manifest paths change only in a template sync (a pull request that moves `_commit` in
-// .copier-answers.yml) or under an unexpired .platform/exceptions.yml entry. Conflict markers in a
-// manifest file and expired exceptions fail too. Offline; without .copier-answers.yml it passes silently.
+// Keeps the paths a platform contract (.platform/contract.yml) marks as `owned` equal to the template
+// they come from. A pull request may change them only in a template sync (it changes `sync.marker` or
+// moves `sync.version`) or under an unexpired exception; conflict markers and expired exceptions fail.
+// With --compare, owned files are also compared with `source.url` at the recorded version.
+// Without a contract it passes silently. .copier-answers.yml + .platform/manifest is read as one.
 //
-// Usage: node scripts/check-platform-conformance.mjs [--base <git ref>]   (no --base: markers and exceptions only)
+// Usage: node scripts/check-platform-conformance.mjs [--base <git ref>] [--compare]
+//        node scripts/check-platform-conformance.mjs --contract   (key=value lines for $GITHUB_OUTPUT)
 
 import { execFileSync } from 'node:child_process';
-import { existsSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, join } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
-const ANSWERS = '.copier-answers.yml';
-const MANIFEST = '.platform/manifest';
-const EXCEPTIONS = '.platform/exceptions.yml';
+export const CONTRACT = '.platform/contract.yml';
+const LEGACY_ANSWERS = '.copier-answers.yml';
+const LEGACY_MANIFEST = '.platform/manifest';
+const DEFAULT_EXCEPTIONS = '.platform/exceptions.yml';
 const CONFLICT_MARKER = /^(?:<{7}|>{7})(?: |$)/m;
 
+export class ContractError extends Error {}
+
 // gitwildmatch, the .gitignore syntax: a pattern with no inner slash matches at any depth, `**`
 // crosses directories, and a match on a directory covers everything below it.
 export function globToRegExp(glob) {
@@ -40,13 +47,12 @@ export function globToRegExp(glob) {
       }
     } else re += c.replace(/[.+^${}()|\\]/g, '\\$&');
   }
-  // nosemgrep: javascript.lang.security.audit.detect-non-literal-regexp.detect-non-literal-regexp — the glob comes from the committed manifest and every metacharacter outside a class is escaped
+  // nosemgrep: javascript.lang.security.audit.detect-non-literal-regexp.detect-non-literal-regexp — the glob comes from the committed contract and every metacharacter outside a class is escaped
   return new RegExp(`^${anchored ? '' : '(?:.*/)?'}${re}(?:/.*)?$`);
 }
 
-export function parseManifest(text) {
-  return text
-    .split(/\r?\n/)
+export function parsePatterns(globs) {
+  return globs
     .map((line) => line.trim())
     .filter((line) => line !== '' && !line.startsWith('#'))
     .map((line) => {
@@ -56,8 +62,10 @@ export function parseManifest(text) {
     });
 }
 
+export const parseManifest = (text) => parsePatterns(text.split(/\r?\n/));
+
 // The last pattern that matches decides, as in .gitignore.
-export function inManifest(patterns, path) {
+export function isOwned(patterns, path) {
   let matched = false;
   for (const { negate, regex } of patterns) if (regex.test(path)) matched = !negate;
   return matched;
@@ -70,15 +78,179 @@ const unquote = (value) => {
   return v.replace(/\s+#.*$/, '');
 };
 
-// The subset of YAML .platform/exceptions.yml uses: one `exceptions:` list of flat mappings.
-export function parseExceptions(text) {
+function stripComment(line) {
+  let quote = '';
+  for (let i = 0; i < line.length; i++) {
+    const c = line[i];
+    if (quote) {
+      if (c === quote) quote = '';
+    } else if (c === '"' || c === "'") quote = c;
+    else if (c === '#' && (i === 0 || /\s/.test(line[i - 1]))) return line.slice(0, i);
+  }
+  return line;
+}
+
+function scalar(raw, at) {
+  const text = raw.trim();
+  if (/^[|>][+-]?$/.test(text) || /^[&*!{]/.test(text)) throw new ContractError(`${at}: "${text}" is not supported; write the value on one line`);
+  if (text.startsWith('[')) {
+    if (!text.endsWith(']')) throw new ContractError(`${at}: unclosed "["`);
+    const inner = text.slice(1, -1).trim();
+    return inner === '' ? [] : (inner.match(/"[^"]*"|'[^']*'|[^,]+/g) ?? []).map((item) => scalar(item, at));
+  }
+  if (/^["']/.test(text)) return unquote(text);
+  if (/^-?\d+$/.test(text)) return Number(text);
+  if (text === 'true' || text === 'false') return text === 'true';
+  if (text === '' || text === '~' || text === 'null') return null;
+  return text;
+}
+
+// The YAML a contract needs: nested mappings, block and flow lists of scalars, quotes and comments.
+export function parseYamlSubset(text, file) {
+  const lines = [];
+  text.split(/\r?\n/).forEach((raw, index) => {
+    const content = stripComment(raw).replace(/\s+$/, '');
+    if (content.trim() === '' || /^---\s*$/.test(content)) return;
+    if (/^\s*\t/.test(raw)) throw new ContractError(`${file}:${index + 1}: indent with spaces, not tabs`);
+    lines.push({ indent: content.length - content.trimStart().length, text: content.trim(), at: `${file}:${index + 1}` });
+  });
+  let next = 0;
+  const isItem = (line) => line.text === '-' || line.text.startsWith('- ');
+  const block = (indent) => {
+    if (isItem(lines[next])) {
+      const list = [];
+      while (next < lines.length && lines[next].indent === indent && isItem(lines[next])) {
+        const { text, at } = lines[next++];
+        if (text === '-') throw new ContractError(`${at}: a list item must be a value on the same line`);
+        list.push(scalar(text.slice(2), at));
+      }
+      return list;
+    }
+    const map = {};
+    while (next < lines.length && lines[next].indent === indent && !isItem(lines[next])) {
+      const { text, at } = lines[next++];
+      const pair = text.match(/^([A-Za-z_][\w-]*):(?:\s+(.*))?$/);
+      if (!pair) throw new ContractError(`${at}: cannot read "${text}"; expected "key: value"`);
+      const following = lines[next];
+      const nested = following && (following.indent > indent || (following.indent === indent && isItem(following)));
+      if (pair[2] !== undefined) map[pair[1]] = scalar(pair[2], at);
+      else map[pair[1]] = nested ? block(following.indent) : null;
+    }
+    return map;
+  };
+  if (lines.length === 0) return {};
+  if (lines[0].indent !== 0 || isItem(lines[0])) throw new ContractError(`${lines[0].at}: the file must be a mapping of top-level keys`);
+  const root = block(0);
+  if (next < lines.length) throw new ContractError(`${lines[next].at}: unexpected indentation`);
+  return root;
+}
+
+const isText = (value) => typeof value === 'string' && value.trim() !== '';
+const isMapping = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const repositoryName = (url) => basename(url.replace(/\.git$/, '').replace(/\/+$/, '')) || url;
+
+export function validateContract(data, file = CONTRACT) {
+  const fail = (field, problem) => {
+    throw new ContractError(`${file}: ${field} ${problem}`);
+  };
+  if (!isMapping(data)) fail('the file', 'must be a YAML mapping');
+  if (data.version === undefined || data.version === null) fail('version', 'is required (version: 1)');
+  if (data.version !== 1) fail('version', `${JSON.stringify(data.version)} is not supported; this guard reads version 1`);
+  if (!isMapping(data.source)) fail('source', 'is required: a mapping with at least url');
+  if (!isText(data.source.url)) fail('source.url', 'is required: where the shared code lives');
+  for (const key of ['name', 'changes']) {
+    if (data.source[key] != null && !isText(data.source[key])) fail(`source.${key}`, 'must be text');
+  }
+  if (!Array.isArray(data.owned) || data.owned.length === 0) fail('owned', 'is required: a list of repository-relative globs');
+  data.owned.forEach((glob, index) => isText(glob) || fail(`owned[${index}]`, 'must be a glob'));
+  if (data.exceptions != null && !isText(data.exceptions)) fail('exceptions', 'must be a repository-relative path');
+  const sync = data.sync ?? {};
+  if (!isMapping(sync)) fail('sync', 'must be a mapping');
+  for (const key of ['marker', 'update']) if (sync[key] != null && !isText(sync[key])) fail(`sync.${key}`, 'must be text');
+  if (sync.version != null) {
+    if (!isMapping(sync.version)) fail('sync.version', 'must be a mapping with file and key');
+    for (const key of ['file', 'key']) if (!isText(sync.version[key])) fail(`sync.version.${key}`, 'is required');
+  }
+  return {
+    version: 1,
+    source: { name: data.source.name ?? repositoryName(data.source.url), url: data.source.url, changes: data.source.changes ?? data.source.url },
+    owned: data.owned,
+    exceptions: data.exceptions ?? DEFAULT_EXCEPTIONS,
+    sync: { marker: sync.marker ?? undefined, version: sync.version ?? undefined, update: sync.update ?? undefined },
+    file,
+  };
+}
+
+// What harness 3.7.0 and workflows 1.11.0 read before the contract existed.
+export function legacyContract(answers, manifest) {
+  const source = topLevelValue(answers, '_src_path');
+  if (!source) throw new ContractError(`${LEGACY_ANSWERS}: _src_path is required to read it as a platform contract`);
+  const url = source.replace(/^git\+/, '').replace(/^gh:/, 'https://github.com/').replace(/^gl:/, 'https://gitlab.com/');
+  return {
+    version: 1,
+    source: { name: repositoryName(url), url, changes: url },
+    owned: manifest.split(/\r?\n/),
+    exceptions: DEFAULT_EXCEPTIONS,
+    sync: {
+      marker: LEGACY_ANSWERS,
+      version: { file: LEGACY_ANSWERS, key: '_commit' },
+      update: 'copier update --trust --defaults --conflict inline',
+    },
+    file: `${LEGACY_ANSWERS} + ${LEGACY_MANIFEST}`,
+  };
+}
+
+export function topLevelValue(text, key) {
+  if (text === undefined) return undefined;
+  const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  // nosemgrep: javascript.lang.security.audit.detect-non-literal-regexp.detect-non-literal-regexp — the key is escaped
+  const value = text.match(new RegExp(`^${escaped}:[ \\t]*(.*?)[ \\t]*$`, 'm'))?.[1];
+  return value === undefined ? undefined : unquote(stripComment(value)) || undefined;
+}
+
+// undefined when the repository declares no contract, explicit or legacy.
+export function readContract(root) {
+  const read = (path) => (existsSync(join(root, path)) ? readFileSync(join(root, path), 'utf8') : undefined);
+  const text = read(CONTRACT);
+  if (text !== undefined) return validateContract(parseYamlSubset(text, CONTRACT));
+  const answers = read(LEGACY_ANSWERS);
+  const manifest = read(LEGACY_MANIFEST);
+  return answers !== undefined && manifest !== undefined ? legacyContract(answers, manifest) : undefined;
+}
+
+export const recordedVersion = (contract, readFile) =>
+  contract.sync.version ? topLevelValue(readFile(contract.sync.version.file), contract.sync.version.key) : undefined;
+
+export function normalizeUrl(url) {
+  return url
+    .trim()
+    .replace(/^git\+/, '')
+    .replace(/^gh:/, 'https://github.com/')
+    .replace(/^git@([^:]+):/, 'https://$1/')
+    .replace(/^(https?:\/\/)[^@/]+@/, '$1')
+    .replace(/\.git$/, '')
+    .replace(/\/+$/, '')
+    .toLowerCase();
+}
+
+// The template repository carries the contract too; its owned paths are its own.
+function isSourceRepository(root, contract) {
+  try {
+    return normalizeUrl(git(root, ['remote', 'get-url', 'origin'])) === normalizeUrl(contract.source.url);
+  } catch {
+    return false;
+  }
+}
+
+// The subset of YAML the exceptions file uses: one `exceptions:` list of flat mappings.
+export function parseExceptions(text, file = DEFAULT_EXCEPTIONS) {
   const entries = [];
   const problems = [];
   let inList = false;
   text.split(/\r?\n/).forEach((raw, index) => {
     const line = raw.replace(/\s+$/, '');
     if (line.trim() === '' || line.trim().startsWith('#')) return;
-    const at = `${EXCEPTIONS}:${index + 1}`;
+    const at = `${file}:${index + 1}`;
     const top = line.match(/^exceptions:\s*(\[\s*\])?\s*(?:#.*)?$/);
     if (top) {
       inList = !top[1];
@@ -91,7 +263,7 @@ export function parseExceptions(text) {
     else problems.push(`${at}: cannot read "${line.trim()}"; expected exceptions: [{ path, reason, issue, expires }]`);
   });
   for (const entry of entries) {
-    const at = `${EXCEPTIONS}:${entry.line}`;
+    const at = `${file}:${entry.line}`;
     const missing = ['path', 'reason', 'issue', 'expires'].filter((key) => !entry[key]);
     if (missing.length > 0) problems.push(`${at}: exception without ${missing.join(', ')}`);
     else if (!/^\d{4}-\d{2}-\d{2}$/.test(entry.expires) || Number.isNaN(Date.parse(entry.expires))) {
@@ -102,10 +274,14 @@ export function parseExceptions(text) {
   return { exceptions: valid.map((entry) => ({ ...entry, regex: globToRegExp(entry.path) })), problems };
 }
 
-const templateCommit = (answers) => answers?.match(/^_commit:\s*(.+?)\s*$/m)?.[1]?.replace(/^["']|["']$/g, '');
-
 function git(root, args) {
-  return execFileSync('git', args, { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+  return execFileSync('git', args, {
+    cwd: root,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+    maxBuffer: 64 * 1024 * 1024,
+  });
 }
 
 function gitShow(root, ref, path) {
@@ -116,63 +292,162 @@ function gitShow(root, ref, path) {
   }
 }
 
-export function checkConformance(root, { base, today = new Date().toISOString().slice(0, 10) } = {}) {
-  const read = (path) => (existsSync(join(root, path)) ? readFileSync(join(root, path), 'utf8') : undefined);
-  const answers = read(ANSWERS);
-  if (answers === undefined) return { adopted: false, failures: [], notes: [] };
+// `git ls-tree -r` and `git ls-files -s` lines, as path -> blob id; submodules are skipped.
+function blobIds(listing, idField) {
+  const ids = new Map();
+  for (const entry of listing.split('\0').filter(Boolean)) {
+    const [meta, path] = entry.split('\t');
+    const fields = meta.split(' ');
+    if (fields[0] !== '160000') ids.set(path, fields[idField]);
+  }
+  return ids;
+}
 
+// Blob ids of the source's files at the version: a tag or commit, or `git describe` output.
+function sourceBlobs(url, version) {
+  const scratch = mkdtempSync(join(tmpdir(), 'platform-source-'));
+  try {
+    git(scratch, ['init', '--quiet', '--bare']);
+    let ref = 'FETCH_HEAD';
+    try {
+      git(scratch, ['fetch', '--quiet', '--depth', '1', url, version]);
+    } catch {
+      git(scratch, ['fetch', '--quiet', url, '+refs/tags/*:refs/tags/*', '+refs/heads/*:refs/heads/*']);
+      ref = version.match(/-\d+-g([0-9a-f]{4,})$/)?.[1] ?? version;
+    }
+    return blobIds(git(scratch, ['ls-tree', '-r', '-z', `${ref}^{commit}`]), 2);
+  } finally {
+    rmSync(scratch, { recursive: true, force: true });
+  }
+}
+
+function compareWithSource(root, contract, patterns, live, version) {
   const failures = [];
   const notes = [];
-  const manifestText = read(MANIFEST);
-  if (manifestText === undefined) return { adopted: true, failures: [`${ANSWERS} exists but ${MANIFEST} does not`], notes };
-  const patterns = parseManifest(manifestText);
+  const { name, url, changes } = contract.source;
+  if (!version) return { failures: [`cannot compare with ${name}: ${contract.sync.version?.file ?? 'the contract'} records no template version (sync.version)`], notes };
+  let source;
+  try {
+    source = sourceBlobs(url, version);
+  } catch (error) {
+    const reason = String(error.stderr ?? error.message).trim().split('\n').at(-1);
+    return { failures, notes: [`cannot read ${url} at ${version} (${reason}); owned files were not compared with the source`] };
+  }
+  const local = blobIds(git(root, ['ls-files', '-s', '-z']), 1);
+  for (const [path, id] of source) {
+    if (!isOwned(patterns, path) || local.get(path) === id) continue;
+    const problem = local.has(path) ? `differs from ${name} at ${version}` : `is missing; ${name} at ${version} has it`;
+    const covered = live.find((entry) => entry.regex.test(path));
+    if (covered) notes.push(`${path}: ${problem}, allowed by the exception until ${covered.expires} (${covered.issue})`);
+    else failures.push(`${path}: ${problem}; change it in ${name} (${changes}) or add an exception to ${contract.exceptions}`);
+  }
+  const onlyHere = [...local.keys()].filter((path) => isOwned(patterns, path) && !source.has(path));
+  if (onlyHere.length > 0) notes.push(`${onlyHere.length} owned file(s) are not in ${name} at ${version} under the same path; not compared`);
+  return { failures, notes };
+}
+
+export function checkConformance(root, { base, compare = false, today = new Date().toISOString().slice(0, 10) } = {}) {
+  const read = (path) => (existsSync(join(root, path)) ? readFileSync(join(root, path), 'utf8') : undefined);
+  let contract;
+  try {
+    contract = readContract(root);
+  } catch (error) {
+    if (error instanceof ContractError) return { adopted: true, failures: [error.message], notes: [] };
+    throw error;
+  }
+  if (contract === undefined) return { adopted: false, failures: [], notes: [] };
+  if (isSourceRepository(root, contract)) {
+    return { adopted: true, failures: [], notes: [`this repository is ${contract.source.name}, the source of its own owned paths`] };
+  }
 
-  const { exceptions, problems } = parseExceptions(read(EXCEPTIONS) ?? '');
+  const failures = [];
+  const notes = [];
+  const patterns = parsePatterns(contract.owned);
+  const { exceptions, problems } = parseExceptions(read(contract.exceptions) ?? '', contract.exceptions);
   failures.push(...problems);
   const live = exceptions.filter((entry) => entry.expires >= today);
   for (const entry of exceptions.filter((e) => e.expires < today)) {
-    failures.push(`${EXCEPTIONS}:${entry.line}: the exception for ${entry.path} expired on ${entry.expires} (${entry.issue}); converge the code or renew it`);
+    failures.push(`${contract.exceptions}:${entry.line}: the exception for ${entry.path} expired on ${entry.expires} (${entry.issue}); converge the code or renew it`);
   }
 
   const tracked = git(root, ['ls-files', '-z']).split('\0').filter(Boolean);
-  for (const file of tracked.filter((path) => inManifest(patterns, path))) {
+  for (const file of tracked.filter((path) => isOwned(patterns, path))) {
     const text = read(file);
     if (text !== undefined && !text.includes('\0') && CONFLICT_MARKER.test(text)) {
       failures.push(`${file}: unresolved template-sync conflict markers`);
     }
   }
 
+  const version = recordedVersion(contract, read);
   if (base !== undefined) {
     const changed = git(root, ['diff', '--name-only', '--no-renames', `${base}...HEAD`]).split('\n').filter(Boolean);
-    const platform = changed.filter((path) => inManifest(patterns, path));
-    const before = templateCommit(gitShow(root, base, ANSWERS));
-    const after = templateCommit(answers);
-    if (before !== after) {
-      notes.push(`template sync ${before ?? '(adoption)'} -> ${after}: ${platform.length} platform file(s) may change`);
+    const owned = changed.filter((path) => isOwned(patterns, path));
+    const before = contract.sync.version ? topLevelValue(gitShow(root, base, contract.sync.version.file), contract.sync.version.key) : undefined;
+    const moved = contract.sync.version !== undefined && before !== version;
+    if (moved || (contract.sync.marker && changed.includes(contract.sync.marker))) {
+      const step = moved ? `${before ?? '(adoption)'} -> ${version}` : `(${contract.sync.marker} changed)`;
+      notes.push(`template sync ${step}: ${owned.length} owned file(s) may change`);
     } else {
-      for (const path of platform) {
+      for (const path of owned) {
         const covered = live.find((entry) => entry.regex.test(path));
         if (covered) notes.push(`${path}: allowed by the exception until ${covered.expires} (${covered.issue})`);
-        else failures.push(`${path}: platform file changed outside a template sync; change it in Kitchen-Sink, or add an exception to ${EXCEPTIONS}`);
+        else failures.push(`${path}: owned by ${contract.source.name} and changed outside a template sync; change it in ${contract.source.name} (${contract.source.changes}), or add an exception to ${contract.exceptions}`);
       }
     }
   }
+  if (compare) {
+    const result = compareWithSource(root, contract, patterns, live, version);
+    failures.push(...result.failures);
+    notes.push(...result.notes);
+  }
   return { adopted: true, failures, notes };
 }
 
+// One key=value line per field, for $GITHUB_OUTPUT; contract=absent when there is none.
+export function contractOutputs(root) {
+  const contract = readContract(root);
+  if (contract === undefined) return 'contract=absent\n';
+  const read = (path) => (existsSync(join(root, path)) ? readFileSync(join(root, path), 'utf8') : undefined);
+  const web = contract.source.url.replace(/^git\+/, '').replace(/\.git$/, '');
+  const fields = {
+    contract: 'present',
+    self: String(isSourceRepository(root, contract)),
+    source_name: contract.source.name,
+    source_url: contract.source.url,
+    source_web: /^https?:\/\//.test(web) ? web : '',
+    version: recordedVersion(contract, read) ?? '',
+    update: contract.sync.update ?? '',
+  };
+  for (const [key, value] of Object.entries(fields)) {
+    if (/[\r\n]/.test(value)) throw new ContractError(`${contract.file}: ${key} must be a single line`);
+  }
+  return Object.entries(fields).map(([key, value]) => `${key}=${value}\n`).join('');
+}
+
 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
   const args = process.argv.slice(2);
   const baseIndex = args.indexOf('--base');
   const base = baseIndex === -1 ? undefined : args[baseIndex + 1];
-  if (baseIndex !== -1 && !base) {
-    console.error('usage: node scripts/check-platform-conformance.mjs [--base <git ref>]');
+  const unknown = args.filter((arg, i) => i !== baseIndex + 1 || baseIndex === -1).filter((arg) => !['--base', '--compare', '--contract'].includes(arg));
+  if ((baseIndex !== -1 && !base) || unknown.length > 0) {
+    console.error('usage: node scripts/check-platform-conformance.mjs [--base <git ref>] [--compare] | --contract');
     process.exit(2);
   }
   const root = fileURLToPath(new URL('..', import.meta.url));
-  const { adopted, failures, notes } = checkConformance(root, { base });
+  if (args.includes('--contract')) {
+    try {
+      process.stdout.write(contractOutputs(root));
+      process.exit(0);
+    } catch (error) {
+      if (!(error instanceof ContractError)) throw error;
+      console.error(`✗ ${error.message}`);
+      process.exit(1);
+    }
+  }
+  const { adopted, failures, notes } = checkConformance(root, { base, compare: args.includes('--compare') });
   if (!adopted) process.exit(0);
   for (const note of notes) console.log(`· ${note}`);
   for (const failure of failures) console.error(`✗ ${failure}`);
-  if (failures.length === 0) console.log('✓ platform files match the template');
+  if (failures.length === 0) console.log('✓ owned files match the template');
   process.exit(failures.length === 0 ? 0 : 1);
 }

package/loops/workflows/agent-audit.md

@@ -19,15 +19,23 @@ env:
   # One line: gh-aw joins a multi-line env value onto a single line when it compiles the lock.
   AUDIT_FOCUS: "Architectural layer violations and dependencies pointing the wrong way. Missing or misleading tests around behaviour that already shipped. Security gaps: unvalidated input, missing authorization, secrets in code. Performance anti-patterns, N+1 queries in particular. Documentation that no longer matches the code it describes."
   AUDIT_MARKER: "<!-- agent-audit -->"
+  # The largest issue the audit files, measured with refine's own rule (issue-size.cjs). Three
+  # quarters of agent-refine.md's REFINE_MAX_BODY_CHARS and REFINE_MAX_WORK_UNITS, so a story a
+  # person edits a little still refines. A body over these is trimmed before it is filed.
+  AUDIT_MAX_BODY_CHARS: "6000"
+  AUDIT_MAX_WORK_UNITS: "18"
+  AUDIT_MAX_STORIES: "3"
   GIT_AUTHOR_NAME: "github-actions[bot]"
   GIT_AUTHOR_EMAIL: "github-actions[bot]@users.noreply.github.com"
   GIT_COMMITTER_NAME: "github-actions[bot]"
   GIT_COMMITTER_EMAIL: "github-actions[bot]@users.noreply.github.com"
 description: |
-  Read-only repository audit. Finds 5-7 problems, scores each 1-10, files a single issue
-  with all findings listed and the top 3 refined as actionable user stories. The issue is
-  labelled `audit` + `bug` + `refine`, so Refine sizes it and splits a multi-defect report
-  into one estimated issue per finding rather than one pull request that has to fix them all. Replaces .loops/recipes/guardrails-audit-loop.yaml.
+  Read-only repository audit. Finds 5-7 problems, scores each 1-10, and files a compact
+  tracking report of every finding, labelled `audit` + `bug`, plus one story issue for each of
+  the top 3, labelled `bug` + `refine` and linked to the report as sub-issues. Refine refines
+  each story on its own; the report never goes to Refine. Every body is measured with refine's
+  size rule before it is filed and trimmed to fit, because one issue holding every finding and
+  three stories was over refine's limit every time and was refused. Replaces .loops/recipes/guardrails-audit-loop.yaml.
 
   Router-only worker: triggered exclusively via workflow_call from work-router.yml.
   Contract input: trigger-kind(scheduled|manual).
@@ -54,7 +62,8 @@ on:
         type: string
         default: manual
 
-  # Rung 1. Do not pile reports on top of unactioned reports.
+  # Rung 1. Do not pile reports on top of unactioned reports. Only the report carries `audit`;
+  # its stories do not, or one audit would fill the three slots by itself.
   #
   # `-label:stale-audit` is what keeps this backpressure from becoming a stop. Three reports
   # nobody ever actioned used to disable the weekly audit for good: the query counted them
@@ -115,19 +124,27 @@ jobs:
         with:
           client-id: ${{ secrets.BOT_APP_ID }}
           private-key: ${{ secrets.BOT_PRIVATE_KEY }}
-      # No apply-agent-output here. The safe_outputs job already created the issue and
-      # exposes its number; calling the action with create-issues would file a second copy
-      # of the same report. It was only needed while staged: true suppressed the native
-      # write, and staged is gone.
-      - name: Apply audit labels to created issues
-        if: needs.safe_outputs.outputs.created_issue_number != ''
-        uses: ./.github/actions/add-issue-labels
+      # Staged, so this is the only write: the report, then each story with its labels and a
+      # link back, then the report's list of stories. Each body passes refine's size rule first.
+      - name: Download agent output
+        id: output
+        uses: ./.github/actions/download-agent-output
         with:
+          artifact-name: ${{ needs.activation.outputs.artifact_prefix }}agent
+      - name: File the report and its stories
+        uses: ./.github/actions/file-audit-issues
+        with:
+          output-file: ${{ steps.output.outputs.output-file }}
           token: ${{ steps.app-token.outputs.token }}
-          issue-number: ${{ needs.safe_outputs.outputs.created_issue_number }}
-          labels: |
+          max-body-chars: ${{ env.AUDIT_MAX_BODY_CHARS }}
+          max-work-units: ${{ env.AUDIT_MAX_WORK_UNITS }}
+          max-stories: ${{ env.AUDIT_MAX_STORIES }}
+          run-url: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+          report-labels: |-
             audit
             bug
+          story-labels: |-
+            bug
             refine
 
   # An audit that produced nothing reported success. The whole run -- a full agent, its tokens,
@@ -138,7 +155,7 @@ jobs:
   #
   # This fires when the agent succeeded and the safe-outputs handler processed nothing at all.
   #
-  # Step 6 of the prompt gives a clean codebase its own outcome -- call `noop` and stop -- and
+  # Step 7 of the prompt gives a clean codebase its own outcome -- call `noop` and stop -- and
   # that outcome must not be reported as a failure. `noop` is a registered safe output here
   # (`noop: max 1`), so the handler receives it as a message and the processed count is not zero,
   # which keeps a deliberately empty audit out of this branch. That is read from the handler
@@ -171,8 +188,11 @@ safe-outputs:
   # under noise nobody closes.
   report-failure-as-issue: false
   threat-detection: false
+  # The report and the stories are filed by `conclude`, after they are measured.
+  staged: true
+  # The report and up to three stories.
   create-issue:
-    max: 1
+    max: 4
 
 # The fleet is two machines, so this clock is also how long a stuck run can hold half of it.
 # 240 went on to every worker at once when the provider was slow, which fixed the deaths and
@@ -227,21 +247,18 @@ timeout-minutes: 90
    again. What this prevents is re-filing something the team looked at and chose to live
    with, which is the noise that makes an audit backlog get ignored.
 
-5. Call `create_issue` **once** with title "Audit: <date>". Do NOT specify labels , the
-   conclude job will apply them. The body MUST have two sections:
+5. File the report: call `create_issue` with title "Audit: <YYYY-MM-DD>" and nothing else in the title. Do NOT specify labels; the conclude job applies them. The report is a compact tracking list, not a story: Refine never reads it. One entry per finding, highest score first, each exactly this shape and no longer than about 600 characters:
 
-   **Section 1 , All findings:** A numbered list of every finding (5-7) with its score,
-   file path, and a one-line description. Order by score descending.
+   ```
+   ### <n>. <one-line problem> (score <s>)
+   **Where:** `path/to/file.ext:line`, `other/file.ext:line`
+   **Problem:** One or two sentences: what happens and its impact.
+   **Fix:** One or two sentences: the change that resolves it.
+   ```
 
-   **Section 2 , Top 3 to implement:** Call skill("pc-plan-story") and refine the top 3
-   findings by score into user stories; that skill owns their shape. Name the likely files to
-   change. Mark this section clearly with a heading like `## Top 3 , To Implement`.
+   No bullet lists, no Gherkin, no user stories, no reproduction walkthroughs. Do not write any issue number (`#123`) in the report: the workflow adds the links to the stories, and every number in it is read as work the report waits on.
 
-   The issue you file goes to Refine, not straight to implementation. Refine sizes it and,
-   because a report of several unrelated defects across different files is exactly the shape
-   that does not land as one pull request, splits it into one properly estimated issue per
-   finding. Write each finding so it survives that split: self-contained, naming its own
-   files and its own acceptance criteria, never "as above" or "same as finding 2".
+6. File the stories: call skill("pc-plan-story") and write the top ${{ env.AUDIT_MAX_STORIES }} findings by score as user stories; that skill owns their shape. Call `create_issue` once per story, after the report, titled with the story's own title (never "Audit: ..."), no labels. Refine refines each story on its own, so each must stand alone: it names its own files and its own acceptance criteria, never "as above" or "see finding 2", and never mentions the other stories or the report. Keep each story well under ${{ env.AUDIT_MAX_BODY_CHARS }} characters and ${{ env.AUDIT_MAX_WORK_UNITS }} bullet lines: the workflow measures every issue against that limit before filing and cuts anything over it from the end.
 
-6. If nothing met the bar, call `noop` and stop. Filing nothing is the right outcome when
+7. If nothing met the bar, call `noop` and stop. Filing nothing is the right outcome when
    the codebase is clean.