@nurix/nustack 0.23.12 → 0.23.14

package/dist/vendor/harness/rules/index.js

@@ -0,0 +1,109 @@
+// packages/harness/src/rules/index.ts - The one rule library (program ruling R14): runRule over a RuleContext, the
+// append-only RULE_IDS with their scopes, delegations and reads, and the ownership helpers ported from etna. Imports
+// no node: module, so the Worker runs it over a repo mirror. docs/architecture/systems/harness-records.md speaks for it
+// (Status check and enforcement).
+import { docsRootOf } from './context.js';
+import { changelogEntryRule, changelogRule, frozenRecordRule, ledgerRule, planGateRule, protectedFileRule } from './changeRules.js';
+import { outputGateRule } from './outputGate.js';
+import { ownershipRule } from './ownership.js';
+import { packageTableRule } from './packageTable.js';
+import { branchWorktreeRule, commitClaimRule, exitStopRule, foreignClaimRule, liveCommandRule, openDenialsRule, queueRule } from './sessionWalls.js';
+export * from './context.js';
+export { resolveDocsRoot, docsRootDeclaration, DEFAULT_DOCS_ROOT, DOCS_ROOT_SOURCES } from './docsRoot.js';
+export { scanOwningDocs, listRepoFiles, deadGlobs, overlaps, owningDoc, owningDocs, scanDocEdges, globToRegExp, specificity } from './ownership.js';
+export { listPlans, openGatedPlans, planScopePaths, inPlanScope, undischargedRows, undischargedDocRows } from './plans.js';
+export { changelogExemptFile, frozenReason, protectedListPath } from './changeRules.js';
+export { approvedPackages, rejectedPackages, APPROVED_TABLE_PATH } from './packageTable.js';
+export { AGENT_BRANCH_PREFIX, parseAgentRef } from './outputGate.js';
+/** Every rule id, append-only: an id is never renamed or removed. The last six delegate to other rules. */
+export const RULE_IDS = [
+    'ownership',
+    'plan-gate',
+    'ledger',
+    'frozen-record',
+    'changelog',
+    'changelog-entry',
+    'package-table',
+    'protected-file',
+    'output-gate',
+    'branch-worktree',
+    'live-command',
+    'commit-claim',
+    'foreign-claim',
+    'open-denials',
+    'exit-stop',
+    'queue',
+    'completion-integrity',
+    'changelog-presence',
+    'commit-gate',
+    'file-gate',
+    'bash-write-screen',
+    'harness-checks',
+];
+export const isRuleId = (value) => RULE_IDS.includes(value);
+/** Seed ids naming a check another rule already makes: each runs its targets, whose findings keep their own ids. */
+export const RULE_ALIASES = {
+    'completion-integrity': ['ledger'],
+    'changelog-presence': ['changelog'],
+    'commit-gate': ['changelog'],
+    'file-gate': ['plan-gate'],
+    'bash-write-screen': ['frozen-record', 'protected-file'],
+    'harness-checks': ['ownership', 'ledger', 'changelog'],
+};
+const SESSION_RULES = ['branch-worktree', 'live-command', 'commit-claim', 'foreign-claim', 'open-denials', 'exit-stop', 'queue'];
+/** Change rules judge trees and a change set; session rules judge one session's action or facts, at the hook. */
+export const RULE_SCOPES = Object.fromEntries(RULE_IDS.map((id) => [id, SESSION_RULES.includes(id) ? 'session' : 'change']));
+const DOCS_SOURCES = ['.nustack/workspace.json', '.claude/harness.json'];
+const DIRECT_READS = {
+    ownership: ['**'],
+    'plan-gate': [...DOCS_SOURCES, '@docs/history/plans/*.md'],
+    ledger: [...DOCS_SOURCES, '@docs/**/*.md'],
+    'frozen-record': [...DOCS_SOURCES, '@docs/history/plans/**/*.md', '@docs/history/changelog/**/*.md', '@docs/history/migrations/**/*.md'],
+    changelog: [...DOCS_SOURCES],
+    'changelog-entry': [...DOCS_SOURCES, '@docs/history/plans/**/*.md', '@docs/history/changelog/**/*.md'],
+    'package-table': ['**/package.json', '.claude/hooks/approved-packages.md', '.claude/rules/general.md', '.claude/rules/testing.md'],
+    'protected-file': [...DOCS_SOURCES, '@docs/operations/protected-files.md'],
+};
+/** The path patterns each rule reads, docs-root-relative ones written `@docs/…`; a delegating id's is its targets' union. */
+export const RULE_READS = Object.fromEntries(RULE_IDS.map((id) => [id, [...new Set((RULE_ALIASES[id] ?? [id]).flatMap((target) => DIRECT_READS[target] ?? []))]]));
+const RULES = {
+    ownership: (ctx) => ownershipRule(ctx, docsRootOf(ctx)),
+    'plan-gate': (ctx) => planGateRule(ctx, docsRootOf(ctx)),
+    ledger: (ctx) => ledgerRule(ctx, docsRootOf(ctx)),
+    'frozen-record': (ctx) => frozenRecordRule(ctx, docsRootOf(ctx)),
+    changelog: (ctx) => changelogRule(ctx, docsRootOf(ctx)),
+    'changelog-entry': (ctx) => changelogEntryRule(ctx, docsRootOf(ctx)),
+    'package-table': packageTableRule,
+    'protected-file': (ctx) => protectedFileRule(ctx, docsRootOf(ctx)),
+    'output-gate': outputGateRule,
+    'branch-worktree': branchWorktreeRule,
+    'live-command': liveCommandRule,
+    'commit-claim': commitClaimRule,
+    'foreign-claim': foreignClaimRule,
+    'open-denials': openDenialsRule,
+    'exit-stop': exitStopRule,
+    queue: queueRule,
+};
+export class UnknownRuleError extends Error {
+    constructor(id) {
+        super(`unknown rule id ${JSON.stringify(id)}; RULE_IDS lists the rules this library runs`);
+        this.name = 'UnknownRuleError';
+    }
+}
+const RANK = { pass: 0, flag: 1, block: 2 };
+/** Runs one rule: pass with no findings, else the configuration's rung (default block). An unknown id throws. */
+export function runRule(id, ctx) {
+    if (!isRuleId(id))
+        throw new UnknownRuleError(id);
+    const targets = RULE_ALIASES[id];
+    if (targets) {
+        const results = targets.map((target) => runRule(target, ctx));
+        const verdict = results.reduce((worst, result) => (RANK[result.verdict] > RANK[worst] ? result.verdict : worst), 'pass');
+        const findings = results.flatMap((result) => result.findings);
+        return results.every((result) => result.notApplicable) ? { verdict, findings, notApplicable: true } : { verdict, findings };
+    }
+    if (RULE_SCOPES[id] === 'session' && (ctx.at ?? 'change') === 'change')
+        return { verdict: 'pass', findings: [], notApplicable: true };
+    const findings = RULES[id](ctx);
+    return { verdict: findings.length === 0 ? 'pass' : (ctx.rung ?? 'block'), findings };
+}

package/dist/vendor/harness/rules/node.js

@@ -0,0 +1,144 @@
+// packages/harness/src/rules/node.ts - nodeRuleContext: a RuleContext over a local git repository. Trees come from
+// `git ls-files` (the working tree, untracked files included) or `git ls-tree`/`git cat-file` at a ref, the change set
+// from `git diff --name-status -M`, and the pull request's head ref from the checked-out branch. Also
+// readBookkeepingWaivers, the `waived:` rows of the bookkeeping queue every local caller passes as waivers. Node only.
+// docs/architecture/systems/harness-records.md speaks for it (Status check and enforcement).
+import { execFileSync } from 'node:child_process';
+import { readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { isSafeRelativePath } from '../lib/paths.js';
+import { resolveDocsRoot } from './docsRoot.js';
+const MAX_BUFFER = 512 * 1024 * 1024;
+function git(root, args) {
+    try {
+        return execFileSync('git', args, { cwd: root, encoding: 'utf8', maxBuffer: MAX_BUFFER, stdio: ['ignore', 'pipe', 'ignore'] });
+    }
+    catch {
+        return null;
+    }
+}
+const nulList = (out) => (out ?? '').split('\0').filter(Boolean);
+/** A tree over the files committed at `ref`. */
+export function gitRefTree(root, ref) {
+    const files = nulList(git(root, ['ls-tree', '-r', '-z', '--name-only', ref])).sort();
+    const known = new Set(files);
+    const cache = new Map();
+    return {
+        read(path) {
+            if (!known.has(path))
+                return null;
+            if (!cache.has(path))
+                cache.set(path, git(root, ['cat-file', 'blob', `${ref}:${path}`]));
+            return cache.get(path);
+        },
+        list: (prefix) => files.filter((path) => path.startsWith(prefix)),
+    };
+}
+/** A tree over the working tree: tracked and untracked-but-not-ignored files that exist; any safe path reads from disk. */
+export function workingTree(root) {
+    const files = [...new Set(nulList(git(root, ['ls-files', '-z', '--cached', '--others', '--exclude-standard'])))]
+        .filter((path) => {
+        try {
+            return statSync(join(root, path)).isFile();
+        }
+        catch {
+            return false;
+        }
+    })
+        .sort();
+    return {
+        read(path) {
+            if (!isSafeRelativePath(path))
+                return null;
+            try {
+                return readFileSync(join(root, path), 'utf8');
+            }
+            catch {
+                return null;
+            }
+        },
+        list: (prefix) => files.filter((path) => path.startsWith(prefix)),
+    };
+}
+/** `git diff --name-status -M -z` parsed; copies count as adds. */
+function parseNameStatus(out) {
+    const fields = nulList(out);
+    const changes = [];
+    for (let i = 0; i < fields.length;) {
+        const status = fields[i];
+        const kind = status[0];
+        if (kind === 'R' || kind === 'C') {
+            const from = fields[i + 1];
+            const path = fields[i + 2];
+            changes.push(kind === 'R' ? { path, status: 'R', from } : { path, status: 'A' });
+            i += 3;
+        }
+        else {
+            changes.push({ path: fields[i + 1], status: kind === 'A' ? 'A' : kind === 'D' ? 'D' : 'M' });
+            i += 2;
+        }
+    }
+    return changes;
+}
+/**
+ * A rule context over the repository at `root`. With `headRef`, head is that commit and base is `baseRef` when given;
+ * without it, head is the working tree and base is `baseRef`, else HEAD.
+ */
+export function nodeRuleContext(options) {
+    const { root, headRef } = options;
+    const hasHead = git(root, ['rev-parse', '--verify', '--quiet', 'HEAD']) !== null;
+    const baseRef = options.baseRef ?? (headRef || !hasHead ? undefined : 'HEAD');
+    const head = headRef ? gitRefTree(root, headRef) : workingTree(root);
+    const base = baseRef ? gitRefTree(root, baseRef) : undefined;
+    let changes = [];
+    if (baseRef) {
+        changes = parseNameStatus(git(root, ['diff', '--name-status', '-M', '-z', baseRef, ...(headRef ? [headRef] : [])]));
+        if (!headRef) {
+            const tracked = new Set(changes.map((change) => change.path));
+            for (const path of nulList(git(root, ['ls-files', '-z', '--others', '--exclude-standard'])))
+                if (!tracked.has(path))
+                    changes.push({ path, status: 'A' });
+        }
+    }
+    const log = git(root, ['log', '-1', '--format=%an <%ae>%x00%B', headRef ?? 'HEAD']);
+    const [author, message] = log ? [log.slice(0, log.indexOf('\0')), log.slice(log.indexOf('\0') + 1).trimEnd()] : ['', ''];
+    const branch = (git(root, ['rev-parse', '--abbrev-ref', 'HEAD']) ?? '').trim();
+    return {
+        head,
+        ...(base ? { base } : {}),
+        changes,
+        commit: { author, message },
+        today: options.today ?? new Date().toISOString().slice(0, 10),
+        pullRequest: { headRef: branch, baseRef: options.baseRef ?? '' },
+    };
+}
+/** The bookkeeping queue, relative to the docs root. */
+export const BOOKKEEPING_QUEUE_PATH = 'operations/bookkeeping.md';
+const QUEUE_ROW = /^-\s+(auto|note|needs-session|waived):\s+(.*)$/;
+/**
+ * The `waived:` rows of `<docs root>/operations/bookkeeping.md` as RuleWaivers, ported from etna's `readQueue`: one
+ * per row, its body trimmed. `scripts/verify/check-ownership.mjs` and `nustack check` both pass these, so the two
+ * never read waivers differently. None when the queue is absent.
+ */
+export function readBookkeepingWaivers(root) {
+    const read = (path) => {
+        if (!isSafeRelativePath(path))
+            return null;
+        try {
+            return readFileSync(join(root, path), 'utf8');
+        }
+        catch {
+            return null;
+        }
+    };
+    const text = read(`${resolveDocsRoot({ read })}/${BOOKKEEPING_QUEUE_PATH}`);
+    if (text === null)
+        return [];
+    const waivers = [];
+    for (const line of text.split(/\r?\n/)) {
+        const match = QUEUE_ROW.exec(line.trim());
+        if (match && match[1] === 'waived')
+            waivers.push({ kind: 'waived', body: match[2].trim() });
+    }
+    return waivers;
+}

package/dist/vendor/harness/rules/outputGate.js

@@ -0,0 +1,28 @@
+export const AGENT_BRANCH_PREFIX = 'nustack/agent/';
+const SEGMENT = /^[A-Za-z0-9_-]+$/;
+/** `nustack/agent/<slug>/<runId>` split, or null when a ref under the prefix does not parse. */
+export function parseAgentRef(ref) {
+    if (!ref.startsWith(AGENT_BRANCH_PREFIX))
+        return null;
+    const parts = ref.slice(AGENT_BRANCH_PREFIX.length).split('/');
+    return parts.length === 2 && SEGMENT.test(parts[0]) && SEGMENT.test(parts[1]) ? { agentSlug: parts[0], runId: parts[1] } : null;
+}
+export function outputGateRule(ctx) {
+    if (!ctx.pullRequest)
+        return [{ id: 'output-gate.context_missing', message: 'no pull request refs were passed; the output gate fails closed' }];
+    const ref = ctx.pullRequest.headRef;
+    const run = ctx.agentRun;
+    const namespaced = ref.startsWith(AGENT_BRANCH_PREFIX);
+    const parsed = parseAgentRef(ref);
+    const findings = [];
+    if (run && !namespaced) {
+        findings.push({ id: 'output-gate.outside_namespace', message: `agent ${run.agentSlug} run ${run.runId} opened ${ref}, outside ${AGENT_BRANCH_PREFIX}${run.agentSlug}/` });
+    }
+    if (namespaced && !parsed)
+        findings.push({ id: 'output-gate.malformed_ref', message: `${ref} is under ${AGENT_BRANCH_PREFIX} but is not <slug>/<runId>` });
+    if (parsed && run && parsed.agentSlug !== run.agentSlug)
+        findings.push({ id: 'output-gate.foreign_namespace', message: `${ref} is ${parsed.agentSlug}'s namespace, but the run is ${run.agentSlug}'s` });
+    if (namespaced && run === null)
+        findings.push({ id: 'output-gate.unclaimed_ref', message: `${ref} is in the agent namespace but no agent run claims it` });
+    return findings;
+}

package/dist/vendor/harness/rules/ownership.js

@@ -0,0 +1,178 @@
+// packages/harness/src/rules/ownership.ts - The `ownership` rule and the ownership helpers over a RuleTree: dead owns:
+// globs, equal-specificity overlaps and dangling doc edges. Ported from etna harness/code/hooks/check-ownership.mjs
+// and lib/ownership.mjs, each helper taking a tree where etna took a project directory.
+// docs/architecture/systems/harness-records.md speaks for it (Status check and enforcement).
+import { asList, field, frontmatter } from '../lib/frontmatter.js';
+import { waiverCovers } from './context.js';
+import { resolveDocsRoot } from './docsRoot.js';
+/** Folders under the docs root that never hold an owning document: frozen history and unharvested research. */
+const NON_OWNING_DIRS = new Set(['history', 'research']);
+const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build', '.claude', '.codex']);
+const markdownUnder = (tree, root) => tree.list(`${root}/`).filter((path) => path.endsWith('.md'));
+/** One entry per document under the docs root that declares owns:, history/, research/ and .bkp. files aside. */
+export function scanOwningDocs(tree, docsRoot = resolveDocsRoot(tree)) {
+    const docs = [];
+    for (const path of markdownUnder(tree, docsRoot)) {
+        if (path.includes('.bkp.') || NON_OWNING_DIRS.has(path.slice(docsRoot.length + 1).split('/')[0]))
+            continue;
+        const block = frontmatter(tree.read(path) ?? '');
+        if (!block)
+            continue;
+        const owns = asList(field(block, 'owns'));
+        if (owns.length === 0)
+            continue;
+        docs.push({
+            doc: path,
+            owns,
+            module: String(field(block, 'module') || '—'),
+            keywords: asList(field(block, 'keywords')),
+            objects: asList(field(block, 'objects')),
+            status: String(field(block, 'status') || 'active').toLowerCase(),
+        });
+    }
+    return docs;
+}
+/** Every file of the tree outside the heavy and machine-local folders. */
+export function listRepoFiles(tree) {
+    return tree.list('').filter((path) => !path.split('/').some((segment) => SKIP_DIRS.has(segment)));
+}
+/** One owns:-style glob (`**` any depth, `*` within a segment) as a RegExp; `a/**` also matches `a`. */
+export function globToRegExp(glob) {
+    const g = glob.replace(/\\/g, '/').replace(/\/+$/, '');
+    const escaped = g.replace(/[\\^$.|?+()[\]{}]/g, '\\$&');
+    const re = escaped
+        .replace(/\/\*\*$/, '\0TAIL\0')
+        .replace(/\*\*\//g, '\0LEAD\0')
+        .replace(/\*\*/g, '\0ANY\0')
+        .replace(/\*/g, '[^/]*')
+        .replace(/\0TAIL\0/g, '(?:/.*)?')
+        .replace(/\0LEAD\0/g, '(?:.*/)?')
+        .replace(/\0ANY\0/g, '.*');
+    return new RegExp(`^${re}$`);
+}
+/** A glob's specificity as literal and wildcard segment counts; only an exact tie leaves an owner ambiguous. */
+export function specificity(glob) {
+    let literal = 0;
+    let wildcard = 0;
+    for (const segment of String(glob).split('/')) {
+        if (segment === '')
+            continue;
+        if (segment.includes('*') || segment.includes('?'))
+            wildcard++;
+        else
+            literal++;
+    }
+    return { literal, wildcard };
+}
+export function owningDocs(tree, relPath, docs = scanOwningDocs(tree)) {
+    return docs.filter((entry) => entry.status !== 'deprecated' && entry.owns.some((glob) => globToRegExp(glob).test(relPath)));
+}
+/** The one owning doc for a path, most specific glob first, with every doc tied at that specificity. */
+export function owningDoc(tree, relPath, docs) {
+    const matches = owningDocs(tree, relPath, docs);
+    if (matches.length <= 1)
+        return matches.length ? { doc: matches[0], glob: null, tied: [] } : null;
+    const scored = [];
+    for (const entry of matches) {
+        let best = null;
+        for (const glob of entry.owns) {
+            if (!globToRegExp(glob).test(relPath))
+                continue;
+            const s = specificity(glob);
+            if (!best || s.literal > best.s.literal || (s.literal === best.s.literal && s.wildcard < best.s.wildcard))
+                best = { glob, s };
+        }
+        if (best)
+            scored.push({ entry, ...best });
+    }
+    if (!scored.length)
+        return null;
+    scored.sort((a, b) => b.s.literal - a.s.literal || a.s.wildcard - b.s.wildcard);
+    const top = scored[0];
+    const tied = scored.filter((x) => x !== top && x.s.literal === top.s.literal && x.s.wildcard === top.s.wildcard);
+    return { doc: top.entry, glob: top.glob, tied: tied.map((x) => x.entry) };
+}
+/** Globs across all owning docs that match no file. */
+export function deadGlobs(tree, repoFiles = listRepoFiles(tree), docs = scanOwningDocs(tree)) {
+    const dead = [];
+    for (const entry of docs) {
+        if (entry.status === 'deprecated')
+            continue;
+        for (const glob of entry.owns) {
+            const re = globToRegExp(glob);
+            if (!repoFiles.some((file) => re.test(file)))
+                dead.push({ glob, doc: entry.doc });
+        }
+    }
+    return dead;
+}
+/** Two globs of different docs matching one file at equal specificity, one example per glob pair. */
+export function overlaps(tree, repoFiles = listRepoFiles(tree), docs = scanOwningDocs(tree)) {
+    const owners = [];
+    for (const entry of docs) {
+        if (entry.status === 'deprecated')
+            continue;
+        for (const glob of entry.owns) {
+            const s = specificity(glob);
+            owners.push({ doc: entry.doc, glob, key: `${s.literal}/${s.wildcard}`, re: globToRegExp(glob) });
+        }
+    }
+    const found = [];
+    const seen = new Set();
+    for (const file of repoFiles) {
+        const here = owners.filter((owner) => owner.re.test(file));
+        for (let i = 0; i < here.length; i++) {
+            for (let j = i + 1; j < here.length; j++) {
+                const a = here[i];
+                const b = here[j];
+                if (a.doc === b.doc || a.key !== b.key)
+                    continue;
+                const pair = `${a.doc}·${a.glob}·${b.doc}·${b.glob}`;
+                if (seen.has(pair))
+                    continue;
+                seen.add(pair);
+                found.push({ a: { doc: a.doc, glob: a.glob }, b: { doc: b.doc, glob: b.glob }, example: file });
+            }
+        }
+    }
+    return found;
+}
+/** Every `verifies:` edge declared under the docs root, with whether its target is absent. */
+export function scanDocEdges(tree, docsRoot = resolveDocsRoot(tree)) {
+    const edges = [];
+    for (const path of markdownUnder(tree, docsRoot)) {
+        if (path.includes('.bkp.'))
+            continue;
+        const block = frontmatter(tree.read(path) ?? '');
+        if (!block)
+            continue;
+        for (const to of asList(field(block, 'verifies'))) {
+            const target = to.trim();
+            if (!target)
+                continue;
+            edges.push({ from: path, kind: 'verifies', to: target, missing: tree.read(target) === null && tree.list(`${target.replace(/\/+$/, '')}/`).length === 0 });
+        }
+    }
+    return edges;
+}
+export function ownershipRule(ctx, docsRoot) {
+    const tree = ctx.head;
+    const files = listRepoFiles(tree);
+    const docs = scanOwningDocs(tree, docsRoot);
+    const waivers = ctx.waivers ?? [];
+    const findings = [];
+    for (const dead of deadGlobs(tree, files, docs)) {
+        if (!waiverCovers(waivers, 'dead-glob', dead.glob, ctx.today))
+            findings.push({ id: 'ownership.dead_glob', path: dead.doc, message: `${dead.glob} → ${dead.doc} matches no file` });
+    }
+    for (const overlap of overlaps(tree, files, docs)) {
+        if (!waiverCovers(waivers, 'ownership-overlap', overlap.example, ctx.today)) {
+            findings.push({ id: 'ownership.overlap', path: overlap.example, message: `${overlap.example} is owned at equal specificity by ${overlap.a.glob} → ${overlap.a.doc} and ${overlap.b.glob} → ${overlap.b.doc}` });
+        }
+    }
+    for (const edge of scanDocEdges(tree, docsRoot).filter((candidate) => candidate.missing)) {
+        if (!waiverCovers(waivers, 'dangling-edge', edge.to, ctx.today))
+            findings.push({ id: 'ownership.dangling_edge', path: edge.from, message: `${edge.from} ${edge.kind}: ${edge.to}, which does not exist` });
+    }
+    return findings;
+}

package/dist/vendor/harness/rules/packageTable.js

@@ -0,0 +1,113 @@
+// packages/harness/src/rules/packageTable.ts - The `package-table` rule: a dependency a change set adds that the
+// approved-packages table rejects, named with that row's replacement. Ported from etna harness/code/hooks/lib/approved.mjs
+// and compliance.mjs packageGate. docs/architecture/systems/harness-records.md speaks for it (Status check and enforcement).
+import { basenamePosix } from '../lib/paths.js';
+export const APPROVED_TABLE_PATH = '.claude/hooks/approved-packages.md';
+export const PACKAGE_RULE_SOURCES = [APPROVED_TABLE_PATH, '.claude/rules/general.md', '.claude/rules/testing.md'];
+function approvedPart(line, banColumn) {
+    if (line.trimStart().startsWith('|')) {
+        if (banColumn < 0)
+            return line;
+        return line
+            .split('|')
+            .filter((_, index) => index !== banColumn)
+            .join('|');
+    }
+    const ban = line.search(/\*\*never\*\*|❌/i);
+    return ban === -1 ? line : line.slice(0, ban);
+}
+function banColumnOf(line, current) {
+    if (!line.trimStart().startsWith('|'))
+        return -1;
+    const header = line.split('|').findIndex((cell) => /don'?t use|never use/i.test(cell));
+    return header === -1 ? current : header;
+}
+/** Package names the table, general.md and testing.md approve; empty when no rules file is present. */
+export function approvedPackages(tree) {
+    const names = new Set();
+    for (const source of PACKAGE_RULE_SOURCES) {
+        let banColumn = -1;
+        for (const line of (tree.read(source) ?? '').split('\n')) {
+            banColumn = banColumnOf(line, banColumn);
+            for (const match of approvedPart(line, banColumn).matchAll(/`(@?[a-z0-9][\w./-]*)`/g))
+                names.add(match[1]);
+        }
+    }
+    return names;
+}
+/** Every rejected package with the row it points at: the table's Don't-use cells, then testing.md's framework bans. */
+export function rejectedPackages(tree) {
+    const rejected = new Map();
+    for (const line of (tree.read(APPROVED_TABLE_PATH) ?? '').split('\n')) {
+        const cells = line.split('|');
+        if (cells.length < 6)
+            continue;
+        const pkg = /`([^`]+)`/.exec(cells[1] ?? '');
+        if (!pkg || pkg[1] === 'Package' || pkg[1] === '---')
+            continue;
+        const version = /`?([^`|]+)`?/.exec((cells[2] ?? '').trim())?.[1] ?? '';
+        for (const match of (cells[4] ?? '').matchAll(/`(@?[a-z0-9][\w./-]*)`/g)) {
+            if (match[1] === pkg[1])
+                continue;
+            rejected.set(match[1], { use: pkg[1], version: version.trim(), purpose: (cells[3] ?? '').trim() });
+        }
+    }
+    let banColumn = -1;
+    for (const line of (tree.read('.claude/rules/testing.md') ?? '').split('\n')) {
+        banColumn = banColumnOf(line, banColumn);
+        if (banColumn < 0 || !line.trimStart().startsWith('|'))
+            continue;
+        for (const match of (line.split('|')[banColumn] ?? '').matchAll(/`(@?[a-z0-9][\w./-]*)`/g)) {
+            if (!rejected.has(match[1]))
+                rejected.set(match[1], { rule: 'testing.md § Frameworks by stack' });
+        }
+    }
+    return rejected;
+}
+const DEPENDENCY_FIELDS = ['dependencies', 'devDependencies', 'optionalDependencies', 'peerDependencies'];
+function dependencies(text) {
+    const out = new Map();
+    if (!text)
+        return out;
+    try {
+        const manifest = JSON.parse(text);
+        for (const fieldName of DEPENDENCY_FIELDS) {
+            const block = manifest[fieldName];
+            if (block && typeof block === 'object')
+                for (const name of Object.keys(block))
+                    out.set(name, (out.get(name) ?? new Set()).add(fieldName));
+        }
+    }
+    catch {
+        /* an unparsable package.json adds nothing the table can judge */
+    }
+    return out;
+}
+export function packageTableRule(ctx) {
+    const manifests = (ctx.changes ?? []).filter((change) => change.status !== 'D' && basenamePosix(change.path) === 'package.json');
+    if (manifests.length === 0)
+        return [];
+    const approved = approvedPackages(ctx.head);
+    if (approved.size === 0)
+        return [];
+    const rejected = rejectedPackages(ctx.head);
+    const approvedScopes = new Set([...approved].filter((name) => name.startsWith('@')).map((name) => name.split('/')[0]));
+    approvedScopes.add('@types');
+    const findings = [];
+    for (const change of manifests) {
+        const before = dependencies(ctx.base?.read(change.from ?? change.path) ?? null);
+        for (const [pkg, fields] of dependencies(ctx.head.read(change.path))) {
+            if (before.has(pkg) || approved.has(pkg))
+                continue;
+            const isDev = fields.size === 1 && fields.has('devDependencies');
+            if (isDev && pkg.startsWith('@') && approvedScopes.has(pkg.split('/')[0]))
+                continue;
+            const no = rejected.get(pkg);
+            if (!no)
+                continue;
+            const instead = no.use ? `use \`${no.use}\`${no.version ? ` ${no.version}` : ''}${no.purpose ? ` — ${no.purpose}` : ''}` : `the prescribed choice is in ${no.rule}`;
+            findings.push({ id: 'package-table.rejected', path: change.path, message: `${change.path} adds \`${pkg}\`, which ${APPROVED_TABLE_PATH} rejects: ${instead}` });
+        }
+    }
+    return findings;
+}

package/dist/vendor/harness/rules/plans.js

@@ -0,0 +1,96 @@
+// packages/harness/src/rules/plans.ts - The one reader of the plans folder and of a plan's two ledgers, over a
+// RuleTree. Ported from etna harness/code/hooks/lib/plans.mjs and lib/ledger.mjs.
+// docs/architecture/systems/harness-records.md speaks for it (Status check and enforcement).
+import { backtickTokens, markdownIn } from './context.js';
+import { globToRegExp } from './ownership.js';
+/** A plan's scope: the path-shaped backticked tokens of its `## Proposed Changes` section. */
+export function planScopePaths(text) {
+    const section = /^##\s+Proposed Changes\s*$([\s\S]*?)(?=^##\s|(?![\s\S]))/m.exec(text);
+    if (!section)
+        return [];
+    return backtickTokens(section[1]).filter((token) => token.includes('/'));
+}
+/** True when `rel` falls inside a scope entry: a glob, a folder (its subtree), or an exact file. */
+export function inPlanScope(rel, scope) {
+    return scope.some((entry) => {
+        if (entry.includes('*'))
+            return globToRegExp(entry).test(rel);
+        if (entry.endsWith('/'))
+            return rel === entry.slice(0, -1) || rel.startsWith(entry);
+        return rel === entry || rel.startsWith(`${entry}/`);
+    });
+}
+export const plansFolder = (docsRoot) => `${docsRoot}/history/plans`;
+export function listPlans(tree, docsRoot) {
+    const plans = [];
+    for (const path of markdownIn(tree, plansFolder(docsRoot))) {
+        const text = tree.read(path) ?? '';
+        const status = /^\*\*Status:\*\*\s*(.+)$/m.exec(text)?.[1]?.trim() ?? null;
+        if (!status)
+            continue;
+        plans.push({
+            file: path.slice(path.lastIndexOf('/') + 1),
+            path,
+            status,
+            gates: /^\*\*Gates:\*\*\s*(.+)$/m.exec(text)?.[1]?.trim() ?? null,
+            scope: planScopePaths(text),
+            hasLedger: /^##\s+Test Obligations\b/m.test(text),
+            hasDocLedger: /^##\s+Doc Obligations\b/m.test(text),
+        });
+    }
+    return plans;
+}
+/** Open plans carrying a `Gates:` line; plans without one are legacy and pass every plan gate. */
+export const openGatedPlans = (tree, docsRoot) => listPlans(tree, docsRoot).filter((plan) => !/Complete|Abandoned/.test(plan.status) && plan.gates);
+const OUTCOME = /^(satisfied|owes nothing|blocked)\b/i;
+const DOC_OUTCOME = /^(updated|owes nothing|blocked)\b/i;
+/** One table row's cells, split on unescaped pipes. */
+const splitRow = (line) => line.split(/(?<!\\)\|/).map((cell) => cell.replace(/\\\|/g, '|').trim());
+function sectionTable(planText, heading) {
+    const start = (planText || '').search(new RegExp(`^##\\s+${heading}\\b`, 'm'));
+    if (start === -1)
+        return null;
+    const body = [];
+    for (const line of planText.slice(start).split('\n').slice(1)) {
+        if (/^##\s/.test(line))
+            break;
+        body.push(line);
+    }
+    const rows = body.filter((line) => /^\s*\|/.test(line));
+    if (rows.length < 3)
+        return null;
+    const header = splitRow(rows[0]).map((cell) => cell.toLowerCase());
+    const col = header.indexOf('outcome');
+    return { rows: rows.slice(2).map(splitRow), col: col === -1 ? null : col };
+}
+/** Row ids of every Test Obligations row whose Outcome is empty or off-vocabulary. */
+export function undischargedRows(planText) {
+    const table = sectionTable(planText, 'Test Obligations');
+    if (!table || table.col === null)
+        return [];
+    const out = [];
+    for (const cells of table.rows) {
+        if (!/^\d+[a-z]?$/i.test(cells[1] ?? ''))
+            continue;
+        const outcome = (cells[table.col] ?? '').replace(/\*/g, '').trim();
+        if (!OUTCOME.test(outcome))
+            out.push(cells[1]);
+    }
+    return out;
+}
+/** Doc names of every Doc Obligations row whose Outcome is empty or off-vocabulary. */
+export function undischargedDocRows(planText) {
+    const table = sectionTable(planText, 'Doc Obligations');
+    if (!table || table.col === null)
+        return [];
+    const out = [];
+    for (const cells of table.rows) {
+        const doc = (cells[1] ?? '').replace(/`/g, '');
+        if (!doc || /^-+$/.test(doc))
+            continue;
+        const outcome = (cells[table.col] ?? '').replace(/\*/g, '').trim();
+        if (!DOC_OUTCOME.test(outcome))
+            out.push(doc);
+    }
+    return out;
+}