@nurix/nustack 0.23.12 → 0.23.14

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

@@ -0,0 +1,352 @@
+// packages/harness/src/mount/index.ts - Mounts one runtime's half of a harness version into a repository: the digest
+// verified over the whole manifest, every object verified (fetched or cached) before the first write, writes deepest
+// path first, contract and seed files kept when a person owns them, merge targets folded, the unmodified files a
+// version drops pruned, the mounted paths kept out of git, and the mount record written by its one writer.
+// Ported from etna packages/cli/lib/install/mount.mjs and packages/cli/src/lib/harness/mount.ts.
+// docs/architecture/systems/harness-records.md speaks for it (Harness mount).
+import { existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { DOCS_ROOT_TOKEN, INSTRUCTION_FILE_OF, isRuntime, MERGE_TARGET_OF, splitRuntimePath } from '../assemble/runtimes.js';
+import { mergeClaudeSettings, mergeCodexHooks, mergeMcpServers } from '../assemble/settingsMerge.js';
+import { contentDigest } from '../digest/index.js';
+import { depthOf, isSafeRelativePath } from '../lib/paths.js';
+import { resolveDocsRoot } from '../rules/docsRoot.js';
+import { defaultHarnessCacheDir, evictCacheFolder, newestCachedDigest, readCachedManifest, readCachedObject, writeCachedManifest, writeCachedObject, } from './cache.js';
+import { trackedMergeTargets, writeExcludeBlock } from './exclude.js';
+import { readBytes, removeEmptyParents, sha256Of, writeAtomic } from './files.js';
+export { FINDING_CODES } from '../lib/findings.js';
+export { defaultHarnessCacheDir, newestCachedDigest, HARNESS_CACHE_DIR_ENV } from './cache.js';
+export { MOUNT_EXCLUDE_START, MOUNT_EXCLUDE_END, resolveGitDirs, excludeBlockLines } from './exclude.js';
+export const MOUNT_RECORD_PATH = '.claude/state/mount.json';
+export const NO_ROUTE_LINE = 'harness not mounted: no route to NuStack and no cached version';
+const SHA256 = /^[0-9a-f]{64}$/;
+const FETCH_CONCURRENCY = 8;
+const MERGE_OF = { 'claude-settings': mergeClaudeSettings, 'codex-hooks': mergeCodexHooks, 'mcp-servers': mergeMcpServers };
+/** The mount record, or null when none parses; an older record parses as one with no `runtimes`. */
+export function readMountRecord(root) {
+    const bytes = readBytes(join(root, MOUNT_RECORD_PATH));
+    if (!bytes)
+        return null;
+    try {
+        const parsed = JSON.parse(bytes.toString('utf8'));
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** A repository path the mount may write: safe, outside `.git` and outside the mount's own state folder. */
+function isWritablePath(path) {
+    return isSafeRelativePath(path) && !path.split('/').includes('.git') && !path.startsWith('.claude/state/');
+}
+/** The first reason the manifest must be refused, before anything is fetched or written. */
+function manifestProblem(manifest, expectedDigest) {
+    if (!manifest || typeof manifest !== 'object' || manifest.schemaVersion !== 1)
+        return { code: 'mount.schema_unknown', message: `schemaVersion ${String(manifest?.schemaVersion)} is not 1` };
+    if (!Array.isArray(manifest.files))
+        return { code: 'mount.schema_unknown', message: 'the manifest lists no files' };
+    for (const entry of manifest.files) {
+        if (typeof entry?.sha256 !== 'string' || !SHA256.test(entry.sha256))
+            return { code: 'mount.bad_sha256', message: `${String(entry?.path)}: sha256 is not 64 lowercase hex`, path: String(entry?.path) };
+        const split = typeof entry.path === 'string' && isSafeRelativePath(entry.path) ? splitRuntimePath(entry.path) : null;
+        if (!split)
+            return { code: 'mount.unsafe_path', message: `${String(entry.path)}: not a safe <runtime>/<path>`, path: String(entry.path) };
+        const placed = entry.policy === 'seed' ? (split.path.startsWith(`${DOCS_ROOT_TOKEN}/`) ? split.path.slice(DOCS_ROOT_TOKEN.length + 1) : '') : split.path;
+        if (!isWritablePath(placed) || (entry.policy !== 'seed' && placed.startsWith('@')))
+            return { code: 'mount.unsafe_path', message: `${entry.path}: unsafe repository path`, path: entry.path };
+        if (entry.policy === 'contract' && split.path !== INSTRUCTION_FILE_OF[split.runtime])
+            return { code: 'mount.contract_outside', message: `${entry.path}: a contract entry outside ${split.runtime}'s instruction file`, path: entry.path };
+        if (entry.policy !== 'mount' && entry.policy !== 'contract' && entry.policy !== 'seed')
+            return { code: 'mount.schema_unknown', message: `${entry.path}: unknown policy ${String(entry.policy)}`, path: entry.path };
+        if (entry.merge !== undefined && (entry.policy !== 'mount' || MERGE_TARGET_OF[entry.merge] !== split.path))
+            return { code: 'mount.unsafe_path', message: `${entry.path}: merge ${String(entry.merge)} at the wrong path`, path: entry.path };
+    }
+    if (contentDigest(manifest.files) !== manifest.digest)
+        return { code: 'mount.digest_mismatch', message: 'the manifest digest does not match its files' };
+    if (expectedDigest && manifest.digest !== expectedDigest)
+        return { code: 'mount.expected_digest_mismatch', message: `the manifest digest ${manifest.digest} is not the expected ${expectedDigest}` };
+    return null;
+}
+/** Runs task over items with at most `limit` in flight. */
+async function eachLimited(items, limit, task) {
+    let next = 0;
+    const worker = async () => {
+        while (next < items.length) {
+            const item = items[next];
+            next += 1;
+            await task(item);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+}
+export async function mountVersion(options) {
+    const runtime = (options.runtime ?? 'claude-code');
+    const root = options.root;
+    const cacheDir = options.cacheDir ?? defaultHarnessCacheDir();
+    const writeContract = options.writeContract ?? 'when-unmodified';
+    const result = { status: 'unavailable', digest: null, semver: null, runtime, source: null, written: [], kept: [], removed: [], contractDrift: [], findings: [], line: '' };
+    const finish = (status, line, finding) => {
+        if (finding)
+            result.findings.push({ code: finding.code, message: finding.message, ...(finding.path ? { path: finding.path } : {}) });
+        return { ...result, status, line };
+    };
+    const refuse = (finding) => finish('refused', `harness not mounted: ${finding.message}`, finding);
+    if (!isRuntime(runtime))
+        return refuse({ code: 'mount.runtime_unknown', message: `unknown runtime ${String(runtime)}` });
+    // The manifest: the caller's, verified; else the cache entry the expected digest or the project's newest names.
+    let manifest;
+    let source;
+    if (options.manifest) {
+        const problem = manifestProblem(options.manifest, options.expectedDigest);
+        if (problem)
+            return refuse(problem);
+        manifest = options.manifest;
+        source = 'network';
+    }
+    else {
+        const projectId = options.projectId;
+        let digest = options.expectedDigest;
+        if (!digest) {
+            if (!projectId)
+                return refuse({ code: 'mount.project_unknown', message: 'no manifest, no expected digest and no projectId to find a cached version by' });
+            digest = newestCachedDigest(cacheDir, projectId)?.digest ?? null;
+        }
+        const cached = digest ? readCachedManifest(cacheDir, digest) : null;
+        if (!digest || !cached)
+            return finish('unavailable', NO_ROUTE_LINE, { code: 'mount.no_route', message: NO_ROUTE_LINE });
+        const problem = manifestProblem(cached, digest);
+        if (problem || cached.digest !== digest) {
+            evictCacheFolder(cacheDir, digest);
+            return refuse({ code: 'mount.cache_corrupt', message: `the cached version ${digest} failed verification (${problem?.message ?? 'its digest is not its folder'}) and was evicted` });
+        }
+        manifest = cached;
+        source = 'cache';
+    }
+    result.digest = manifest.digest;
+    result.semver = manifest.semver;
+    result.source = source;
+    const planned = manifest.files.flatMap((entry) => {
+        const split = splitRuntimePath(entry.path);
+        return split && split.runtime === runtime ? [{ entry, path: split.path }] : [];
+    });
+    const record = readMountRecord(root) ?? {};
+    const prior = record.runtimes?.[runtime];
+    // Current: the record names this digest for this runtime and every recorded file still matches.
+    if (prior && prior.digest === manifest.digest && Array.isArray(prior.files) && prior.files.every((file) => sha256Of(readBytes(join(root, file.path)) ?? '\0missing') === file.sha256)) {
+        result.kept = prior.files.map((file) => file.path);
+        return finish('current', `harness current: ${manifest.semver} (${manifest.digest.slice(0, 12)}) for ${runtime}`);
+    }
+    const docsRoot = resolveDocsRoot({ read: (path) => readBytes(join(root, path))?.toString('utf8') ?? null });
+    const placedPath = (item) => (item.entry.policy === 'seed' ? `${docsRoot}/${item.path.slice(DOCS_ROOT_TOKEN.length + 1)}` : item.path);
+    const onDisk = new Map();
+    const disk = (path) => {
+        if (!onDisk.has(path))
+            onDisk.set(path, readBytes(join(root, path)));
+        return onDisk.get(path);
+    };
+    const priorSha = new Map((prior?.files ?? []).map((file) => [file.path, file.sha256]));
+    // Decide what each entry needs before fetching anything: only the bytes a write uses are fetched.
+    const needed = [];
+    const unchanged = [];
+    for (const item of planned) {
+        const target = placedPath(item);
+        const held = disk(target);
+        const heldSha = held ? sha256Of(held) : null;
+        if (item.entry.merge)
+            needed.push(item);
+        else if (item.entry.policy === 'mount') {
+            if (heldSha === item.entry.sha256)
+                unchanged.push(target);
+            else
+                needed.push(item);
+        }
+        else if (item.entry.policy === 'seed') {
+            if (held)
+                result.kept.push(target);
+            else if (writeContract !== 'never')
+                needed.push(item);
+        }
+        else if (heldSha === item.entry.sha256)
+            unchanged.push(target);
+        else if (writeContract === 'never') {
+            if (held)
+                result.kept.push(target);
+        }
+        else if (!held || writeContract === 'always' || priorSha.get(target) === heldSha)
+            needed.push(item);
+        else {
+            result.kept.push(target);
+            result.contractDrift.push(target);
+            result.findings.push({ code: 'mount.contract_edited', message: `${target} differs from what the last mount wrote; left as edited`, path: target });
+        }
+    }
+    // Every needed object, from the cache (verified) or fetched (verified), before the first write.
+    const bytesOf = new Map();
+    const fetched = [];
+    for (const item of needed) {
+        const cached = readCachedObject(cacheDir, manifest.digest, item.entry);
+        if (cached && sha256Of(cached) === item.entry.sha256)
+            bytesOf.set(item.entry.path, cached);
+        else if (source === 'cache') {
+            if (cached) {
+                evictCacheFolder(cacheDir, manifest.digest);
+                return refuse({ code: 'mount.cache_corrupt', message: `the cached ${item.entry.path} does not match its entry; the cached version was evicted`, path: item.entry.path });
+            }
+            return finish('unavailable', `harness not mounted: no route to NuStack and the cached version lacks ${item.entry.path}`, { code: 'mount.no_route', message: `the cached version lacks ${item.entry.path}`, path: item.entry.path });
+        }
+        else
+            fetched.push(item);
+    }
+    let failure = null;
+    await eachLimited(fetched, FETCH_CONCURRENCY, async (item) => {
+        if (failure)
+            return;
+        try {
+            const bytes = await options.fetchObject(item.entry);
+            if (sha256Of(bytes) !== item.entry.sha256)
+                failure ??= { code: 'mount.object_mismatch', message: `${item.entry.path}: the object does not match its sha256`, path: item.entry.path };
+            else
+                bytesOf.set(item.entry.path, bytes);
+        }
+        catch (error) {
+            failure ??= { code: 'mount.fetch_failed', message: `fetching ${item.entry.path} failed: ${error instanceof Error ? error.message : String(error)}`, path: item.entry.path };
+        }
+    });
+    if (failure) {
+        const found = failure;
+        return found.code === 'mount.fetch_failed' ? finish('unavailable', `harness not mounted: ${found.message}`, found) : refuse(found);
+    }
+    // The cache: fetched objects, then the manifest last as the completeness mark.
+    for (const item of fetched)
+        writeCachedObject(cacheDir, manifest.digest, item.entry, bytesOf.get(item.entry.path));
+    if (source === 'network')
+        writeCachedManifest(cacheDir, manifest, runtime);
+    // Merge targets: tracked ones are left alone; an unparsable one is left alone; the rest fold the fragment in.
+    const merges = needed.filter((item) => item.entry.merge);
+    const mergeTargets = [...new Set([...merges.map((item) => item.path), ...Object.keys(prior?.managed ?? {})])];
+    const tracked = trackedMergeTargets(root, mergeTargets);
+    const managed = {};
+    const createdMergeTargets = new Set((prior?.createdMergeTargets ?? []).filter((path) => existsSync(join(root, path))));
+    const mergeWrites = [];
+    for (const target of mergeTargets) {
+        const item = merges.find((candidate) => candidate.path === target);
+        const kind = (item?.entry.merge ?? Object.entries(MERGE_TARGET_OF).find(([, path]) => path === target)?.[0]);
+        if (!kind)
+            continue;
+        if (tracked.has(target)) {
+            result.findings.push({ code: 'mount.merge_target_tracked', message: `${target} is tracked by git; left untouched`, path: target });
+            continue;
+        }
+        const held = disk(target);
+        let existing = null;
+        if (held) {
+            try {
+                const parsed = JSON.parse(held.toString('utf8'));
+                if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+                    throw new Error('not an object');
+                existing = parsed;
+            }
+            catch {
+                result.findings.push({ code: 'mount.merge_target_unparsable', message: `${target} does not parse as a JSON object; left untouched`, path: target });
+                continue;
+            }
+        }
+        let fragment = {};
+        if (item) {
+            try {
+                fragment = JSON.parse(Buffer.from(bytesOf.get(item.entry.path)).toString('utf8'));
+            }
+            catch {
+                return refuse({ code: 'mount.object_mismatch', message: `${item.entry.path}: the merge fragment is not JSON`, path: item.entry.path });
+            }
+        }
+        const merged = MERGE_OF[kind](existing, fragment, prior?.managed?.[target]);
+        if (Object.keys(merged.managed).length > 0)
+            managed[target] = merged.managed;
+        const content = `${JSON.stringify(merged.merged, null, 2)}\n`;
+        if (held && held.toString('utf8') === content)
+            continue;
+        if (!held) {
+            if (!item)
+                continue;
+            createdMergeTargets.add(target);
+        }
+        mergeWrites.push({ target, content });
+    }
+    // All writes, deepest path first, so a module lands before the file importing it.
+    const writes = needed.filter((item) => !item.entry.merge).map((item) => ({ target: placedPath(item), bytes: bytesOf.get(item.entry.path) }));
+    writes.sort((a, b) => depthOf(b.target) - depthOf(a.target) || (a.target < b.target ? -1 : a.target > b.target ? 1 : 0));
+    for (const write of writes) {
+        writeAtomic(join(root, write.target), write.bytes);
+        result.written.push(write.target);
+    }
+    for (const write of mergeWrites) {
+        writeAtomic(join(root, write.target), write.content);
+        result.written.push(write.target);
+    }
+    result.kept.push(...unchanged);
+    // What this runtime now holds: mount and contract files whose bytes equal their entry.
+    const files = [];
+    for (const item of planned) {
+        if (item.entry.merge || item.entry.policy === 'seed')
+            continue;
+        const target = placedPath(item);
+        const held = result.written.includes(target) ? item.entry.sha256 : sha256Of(disk(target) ?? '\0missing');
+        if (held === item.entry.sha256)
+            files.push({ path: target, sha256: item.entry.sha256, policy: item.entry.policy });
+    }
+    // Prune: a file the previous mount of this runtime recorded and this version omits, still unmodified, and no
+    // other runtime's record listing it.
+    const now = new Set(files.map((file) => file.path));
+    const otherRuntimes = Object.entries(record.runtimes ?? {}).filter(([name]) => name !== runtime);
+    const listedElsewhere = (path) => otherRuntimes.some(([, other]) => (other?.files ?? []).some((file) => file.path === path));
+    for (const old of prior?.files ?? []) {
+        if (old.policy !== 'mount' || now.has(old.path) || planned.some((item) => placedPath(item) === old.path))
+            continue;
+        const held = readBytes(join(root, old.path));
+        if (!held)
+            continue;
+        if (sha256Of(held) !== old.sha256) {
+            result.kept.push(old.path);
+            result.findings.push({ code: 'mount.kept_edited', message: `${old.path} was dropped by this version but edited since the last mount; left in place`, path: old.path });
+            continue;
+        }
+        if (listedElsewhere(old.path))
+            continue;
+        rmSync(join(root, old.path), { force: true });
+        removeEmptyParents(root, old.path);
+        result.removed.push(old.path);
+    }
+    // Out of git: every runtime's mounted files and the merge targets a mount created.
+    const runtimes = { ...(record.runtimes ?? {}) };
+    const mountedAt = new Date().toISOString();
+    runtimes[runtime] = {
+        digest: manifest.digest,
+        treeDigest: contentDigest(planned.filter((item) => !item.entry.merge && item.entry.policy !== 'seed').map((item) => ({ path: placedPath(item), sha256: item.entry.sha256 }))),
+        semver: manifest.semver,
+        source,
+        mountedAt,
+        files,
+        managed,
+        createdMergeTargets: [...createdMergeTargets].sort(),
+    };
+    const excluded = Object.values(runtimes).flatMap((entry) => [...(entry?.files ?? []).filter((file) => file.policy === 'mount').map((file) => file.path), ...(entry?.createdMergeTargets ?? [])]);
+    writeExcludeBlock(root, excluded);
+    // The record, by its one writer: unknown top-level keys kept, the caller's extras beside the owned keys.
+    const stateDir = join(root, '.claude', 'state');
+    mkdirSync(stateDir, { recursive: true });
+    if (!existsSync(join(stateDir, '.gitignore')))
+        writeFileSync(join(stateDir, '.gitignore'), '*\n');
+    const body = {
+        ...record,
+        ...(options.recordExtras ?? {}),
+        version: manifest.semver,
+        digest: manifest.digest,
+        mountedAt,
+        projectId: options.projectId ?? manifest.projectId,
+        source,
+        runtimes,
+    };
+    writeAtomic(join(root, MOUNT_RECORD_PATH), `${JSON.stringify(body, null, 2)}\n`);
+    return finish('mounted', `harness mounted: ${manifest.semver} (${manifest.digest.slice(0, 12)}) for ${runtime} from ${source}`);
+}

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

@@ -0,0 +1,162 @@
+// packages/harness/src/rules/changeRules.ts - The change rules over a tree and a change set: plan-gate, ledger,
+// frozen-record, changelog, changelog-entry and protected-file. Ported from etna harness/code/hooks/compliance.mjs,
+// check-completion-integrity.mjs, check-changelog-presence.mjs, lib/frozen.mjs and lib/exempt.mjs.
+// docs/architecture/systems/harness-records.md speaks for it (Status check and enforcement).
+import { field, frontmatter } from '../lib/frontmatter.js';
+import { basenamePosix, joinPosix } from '../lib/paths.js';
+import { backtickTokens, markdownIn, SOURCE_EXT, waiverCovers } from './context.js';
+import { inPlanScope, openGatedPlans, plansFolder, undischargedDocRows, undischargedRows } from './plans.js';
+const changedPaths = (change) => (change.status === 'R' && change.from ? [change.path, change.from] : [change.path]);
+export function planGateRule(ctx, root) {
+    const findings = [];
+    const seen = new Set();
+    const add = (finding) => {
+        const key = `${finding.id}|${finding.path}`;
+        if (!seen.has(key))
+            findings.push(finding), seen.add(key);
+    };
+    const sources = (ctx.changes ?? []).map((change) => change.path).filter((rel) => !(rel.startsWith(`${root}/`) || rel.startsWith('.claude/') || rel.endsWith('.md')) && SOURCE_EXT.test(rel));
+    if (sources.length === 0)
+        return findings;
+    const plans = openGatedPlans(ctx.head, root);
+    for (const rel of sources) {
+        for (const plan of plans) {
+            if (plan.scope.length && !inPlanScope(rel, plan.scope))
+                continue;
+            const boundary = /Boundary:\s*(\w+)/i.exec(plan.gates ?? '');
+            if (boundary && !/^passed$/i.test(boundary[1])) {
+                add({ id: /^blocked$/i.test(boundary[1]) ? 'plan-gate.boundary_blocked' : 'plan-gate.boundary_pending', path: plan.path, message: `${rel} changes inside ${plan.file}, whose Gates line reads 'Boundary: ${boundary[1]}'` });
+            }
+            if (!plan.hasLedger)
+                add({ id: 'plan-gate.no_test_ledger', path: plan.path, message: `${rel} changes inside ${plan.file}, which has no ## Test Obligations section` });
+            if (!plan.hasDocLedger)
+                add({ id: 'plan-gate.no_doc_ledger', path: plan.path, message: `${rel} changes inside ${plan.file}, which has no ## Doc Obligations section` });
+        }
+    }
+    return findings;
+}
+/** Completion integrity for every gated plan at head: discharged ledgers, active Spec docs, their checklists, an Abandoned plan's backlog. */
+export function ledgerRule(ctx, root) {
+    const findings = [];
+    const folder = plansFolder(root);
+    for (const path of markdownIn(ctx.head, folder)) {
+        const file = basenamePosix(path);
+        const text = ctx.head.read(path) ?? '';
+        if (!/^\*\*Gates:\*\*/m.test(text))
+            continue;
+        const status = /^\*\*Status:\*\*\s*(\S+)/m.exec(text)?.[1];
+        if (status === 'Complete') {
+            const docRows = undischargedDocRows(text);
+            if (docRows.length)
+                findings.push({ id: 'ledger.doc_rows_undischarged', path, message: `${file} is Complete with ${docRows.length} Doc Obligations row(s) missing a discharge outcome (${docRows.join(', ')})` });
+            const rows = undischargedRows(text);
+            if (rows.length)
+                findings.push({ id: 'ledger.test_rows_undischarged', path, message: `${file} is Complete with ${rows.length} Test Obligations row(s) missing a discharge outcome (#${rows.join(', #')})` });
+            for (const match of text.matchAll(/^\*\*Spec:\*\*\s*\[[^\]]*\]\(([^)]+)\)/gm)) {
+                const spec = match[1];
+                const specPath = joinPosix(folder, spec);
+                const specText = specPath === null ? '' : (ctx.head.read(specPath) ?? '');
+                const specStatus = String(field(frontmatter(specText), 'status') ?? '');
+                if (specText && specStatus !== 'active')
+                    findings.push({ id: 'ledger.spec_not_active', path, message: `${file} is Complete but its Spec ${spec} is status: ${specStatus || 'unknown'} (expected active)` });
+                const feature = basenamePosix(spec).replace(/\.md$/, '');
+                if (ctx.head.read(`${root}/tests/${feature}.md`) === null)
+                    findings.push({ id: 'ledger.checklist_missing', path, message: `${file} is Complete but ${root}/tests/${feature}.md (the behavioral checklist) is missing` });
+            }
+        }
+        if (status === 'Abandoned' && !/backlog/i.test(text))
+            findings.push({ id: 'ledger.abandoned_without_backlog', path, message: `${file} is Abandoned without referencing the backlog` });
+    }
+    return findings;
+}
+/** Why a path is frozen in `tree` (a committed changelog entry, a Complete or Abandoned plan, an executed runbook), or null. */
+export function frozenReason(tree, root, rel) {
+    if (rel.includes('.bkp.') || !rel.endsWith('.md'))
+        return null;
+    if (rel.startsWith(`${root}/history/changelog/`))
+        return tree.read(rel) !== null ? 'committed changelog entry' : null;
+    if (rel.startsWith(`${root}/history/plans/`))
+        return /^\*\*Status:\*\*\s*(Complete|Abandoned)\b/m.test(tree.read(rel) ?? '') ? 'plan with Status: Complete or Abandoned' : null;
+    if (rel.startsWith(`${root}/history/migrations/`))
+        return /^\*\*Executed:\*\*\s*\d{4}-\d{2}-\d{2}/m.test(tree.read(rel) ?? '') ? 'outcome-stamped migration runbook' : null;
+    return null;
+}
+/** A change to a record frozen at base. With no base tree nothing is committed, so nothing is frozen. */
+export function frozenRecordRule(ctx, root) {
+    if (!ctx.base)
+        return [];
+    const findings = [];
+    for (const change of ctx.changes ?? []) {
+        for (const rel of changedPaths(change)) {
+            if (change.status === 'A' && rel === change.path)
+                continue;
+            const reason = frozenReason(ctx.base, root, rel);
+            if (reason)
+                findings.push({ id: 'frozen-record.modified', path: rel, message: `${rel} is frozen (${reason}); a correction is a new dated record that links back` });
+        }
+    }
+    return findings;
+}
+const LOCKFILES = /^(pnpm-lock\.yaml|package-lock\.json|yarn\.lock|bun\.lockb?|Cargo\.lock)$/;
+const HARNESS_PREFIXES = ['.claude/', '.agents/', '.codex/'];
+const HARNESS_FILES = ['AGENTS.md', 'CLAUDE.md', '.mcp.json', '.vscode/settings.json', '.prettierignore', '.prettierrc.json'];
+/** The changelog rule's closed exemption list, judged per file. */
+export function changelogExemptFile(root, path) {
+    return (LOCKFILES.test(basenamePosix(path)) ||
+        HARNESS_PREFIXES.some((prefix) => path.startsWith(prefix)) ||
+        HARNESS_FILES.includes(path) ||
+        path.startsWith(`${root}/history/changelog/`) ||
+        path.includes('.bkp.') ||
+        path === `${root}/history/CHANGELOG.md`);
+}
+/** A non-exempt change set carries a changelog entry: bot authors, pure renames and exempt-only sets aside. */
+export function changelogRule(ctx, root) {
+    const changes = ctx.changes ?? [];
+    if (changes.length === 0)
+        return [];
+    const isBot = /\[bot\]|actions@github\.com/i.test(ctx.commit?.author ?? '');
+    const allRenames = changes.every((change) => change.status === 'R');
+    const allExempt = changes.every((change) => changelogExemptFile(root, change.path));
+    const hasEntry = changes.some((change) => change.status !== 'D' && change.path.startsWith(`${root}/history/changelog/`) && change.path.endsWith('.md'));
+    if (isBot || allRenames || allExempt || hasEntry)
+        return [];
+    return [{ id: 'changelog.missing_entry', message: `the change set is not exempt and carries no ${root}/history/changelog/ entry` }];
+}
+/** A plan flipped Complete in the change set needs a changelog entry at head naming its slug. */
+export function changelogEntryRule(ctx, root) {
+    const findings = [];
+    const complete = /^\*\*Status:\*\*\s*Complete\b/m;
+    const folder = `${root}/history/changelog`;
+    let entries = null;
+    for (const change of ctx.changes ?? []) {
+        if (change.status === 'D' || !change.path.startsWith(`${root}/history/plans/`) || !change.path.endsWith('.md'))
+            continue;
+        if (!complete.test(ctx.head.read(change.path) ?? ''))
+            continue;
+        if (ctx.base && complete.test(ctx.base.read(change.from ?? change.path) ?? ''))
+            continue;
+        const slug = basenamePosix(change.path).replace(/\.md$/, '');
+        entries ??= ctx.head
+            .list(`${folder}/`)
+            .filter((path) => path.endsWith('.md'))
+            .map((path) => ctx.head.read(path) ?? '');
+        if (!entries.some((text) => text.includes(slug)))
+            findings.push({ id: 'changelog-entry.missing', path: change.path, message: `${change.path} reached Status: Complete with no ${folder}/ entry naming ${slug}` });
+    }
+    return findings;
+}
+export const protectedListPath = (root) => `${root}/operations/protected-files.md`;
+/** A changed path (or a rename's source) on the protected list, read from base so a change cannot drop a path and edit it at once. */
+export function protectedFileRule(ctx, root) {
+    const listPath = protectedListPath(root);
+    const listed = new Set([listPath, ...backtickTokens((ctx.base ?? ctx.head).read(listPath) ?? '')]);
+    const findings = [];
+    for (const change of ctx.changes ?? []) {
+        for (const rel of changedPaths(change)) {
+            if (!listed.has(rel) || waiverCovers(ctx.waivers ?? [], 'protected-file', rel, ctx.today))
+                continue;
+            findings.push({ id: 'protected-file.modified', path: rel, message: `${rel} is on the protected list (${listPath})` });
+        }
+    }
+    return findings;
+}

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

@@ -0,0 +1,38 @@
+// packages/harness/src/rules/context.ts - The rule library's shared shapes: the tree a rule reads, the change set,
+// the context, the result, waivers and the session facts a hook supplies. Imports no node: module, so the Worker
+// runs every rule. docs/architecture/systems/harness-records.md speaks for it (Status check and enforcement).
+import { resolveDocsRoot } from './docsRoot.js';
+export const docsRootOf = (ctx) => ctx.docsRoot?.trim().replace(/\/+$/, '') || resolveDocsRoot(ctx.head);
+export const waiverExpiry = (row) => /expires=(\d{4}-\d{2}-\d{2})/.exec(row.body)?.[1] ?? null;
+/** Unexpired waived rows for a finding kind. */
+export function unexpiredWaivers(rows, kind, today) {
+    return rows.filter((row) => {
+        if (row.kind !== 'waived')
+            return false;
+        if (kind && !row.body.includes(kind))
+            return false;
+        const expires = waiverExpiry(row);
+        return !!expires && expires >= today;
+    });
+}
+/** True when an unexpired waiver of `kind` names the subject in backticks; a bare substring never covers. */
+export function waiverCovers(rows, kind, subject, today) {
+    return unexpiredWaivers(rows, kind, today).some((row) => row.body.includes(`\`${subject}\``));
+}
+/** Space-free backticked tokens in markdown, `./` stripped: the grammar of path-carrying prose. */
+export function backtickTokens(text) {
+    const out = [];
+    for (const match of String(text || '').matchAll(/`([^`\n]+)`/g)) {
+        const candidate = match[1].trim().replace(/^\.\//, '');
+        if (candidate && !candidate.includes(' '))
+            out.push(candidate);
+    }
+    return out;
+}
+/** One definition of a source file: the plan gate and the drift detector agree on it. */
+export const SOURCE_EXT = /\.(m?[jt]sx?|py|rs|go|rb|java|kt|swift|c|h|cpp|hpp|cs|sh|sql|css|scss|vue|svelte)$/;
+/** The markdown files directly inside a folder of the tree. */
+export const markdownIn = (tree, folder) => tree
+    .list(`${folder}/`)
+    .filter((path) => path.endsWith('.md') && !path.slice(folder.length + 1).includes('/'))
+    .sort();

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

@@ -0,0 +1,34 @@
+// packages/harness/src/rules/docsRoot.ts - The repository's docs root: `.nustack/workspace.json` docsRoot, else
+// `.claude/harness.json` docsRoot, else `docs`. One function for the rules and the mount, applying the declaration
+// rule the `project-contract` conformance seam binds every reader to. docs/architecture/systems/harness-records.md
+// speaks for it.
+export const DEFAULT_DOCS_ROOT = 'docs';
+export const DOCS_ROOT_SOURCES = ['.nustack/workspace.json', '.claude/harness.json'];
+/** A `docsRoot` value as a declaration: trimmed, trailing slashes stripped; empty, absolute or `..`-segmented is none. */
+export function docsRootDeclaration(value) {
+    if (typeof value !== 'string')
+        return null;
+    const trimmed = value.trim().replace(/[\\/]+$/, '');
+    if (trimmed === '' || /^([A-Za-z]:)?[\\/]/.test(trimmed))
+        return null;
+    return trimmed.split(/[\\/]/).includes('..') ? null : trimmed;
+}
+function declaredRoot(text) {
+    if (!text)
+        return null;
+    try {
+        const parsed = JSON.parse(text);
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? docsRootDeclaration(parsed.docsRoot) : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function resolveDocsRoot(tree) {
+    for (const source of DOCS_ROOT_SOURCES) {
+        const root = declaredRoot(tree.read(source));
+        if (root)
+            return root;
+    }
+    return DEFAULT_DOCS_ROOT;
+}