@ornexus/neocortex 4.60.67 → 4.60.68

package/packages/client/dist/commands/refactor-root.js

@@ -1,7 +1,588 @@
-import{createHash as se}from"node:crypto";import{closeSync as q,constants as j,existsSync as ne,fstatSync as ae,fsyncSync as G,lstatSync as p,mkdirSync as ce,openSync as I,readFileSync as A,readSync as fe,realpathSync as v,writeFileSync as de}from"node:fs";import{dirname as U,isAbsolute as Q,join as b,resolve as L}from"node:path";import{mutationQaGit as E}from"./mutation-qa-git.js";const K=/^P[0-9]{1,12}(?:\.[0-9]{1,12}){1,3}$/,F=/^[a-f0-9]{64}$/,N=8*1024*1024,Y=256;function g(s){return se("sha256").update(s).digest("hex")}function Z(s){const o=E(s,["rev-parse","--git-common-dir"]).toString("utf8").trim(),t=Q(o)?L(o):L(s,o);if(v(t)!==t||p(t).isSymbolicLink()||p(t).uid!==process.getuid?.())throw new Error("refactor-root-store-unverified");const r=b(t,"neocortex-refactor");ce(r,{recursive:!0,mode:448});const i=p(r);if(!i.isDirectory()||i.isSymbolicLink()||i.uid!==process.getuid?.()||(i.mode&63)!==0)throw new Error("refactor-root-store-unverified");return r}function C(s){return!s||s.length>512||Q(s)||s.includes("\\")||/[\u0000-\u001f\u007f:*?\[\]]/.test(s)||s.normalize("NFC")!==s?!1:!s.split("/").some(t=>!t||t==="."||t===".."||[".git",".neocortex","node_modules"].includes(t.toLowerCase()))}function le(s,o){if(!C(o))throw new Error("refactor-root-write-set-invalid");const t=b(s,o),r=p(t);if(v(t)!==t||!r.isFile()||r.isSymbolicLink()||r.size===0||r.size>N)throw new Error("refactor-root-write-set-invalid");const i=A(t);if(i.length===0||i.length>N)throw new Error("refactor-root-write-set-invalid");if(new TextDecoder("utf-8",{fatal:!0}).decode(i),i.includes(0))throw new Error("refactor-root-write-set-invalid");const n=E(s,["show",`HEAD:${o}`]);if(!i.equals(n))throw new Error("refactor-root-source-dirty");return Object.freeze({sha256:g(i),mode:r.mode&511})}function ee(s,o){try{return E(s,["check-ignore","--no-index","-q","--",o]),!0}catch(t){if(t.status===1)return!1;throw t}}function P(s,o){if(!C(o))throw new Error("refactor-root-write-set-invalid");const t=b(s,o),r=U(t),i=p(r);if(!i.isDirectory()||i.isSymbolicLink()||v(r)!==r||E(s,["ls-files","--stage","-z","--",o]).length>0||ee(s,o))throw new Error("refactor-root-write-set-invalid");try{throw p(t),new Error("refactor-root-write-set-invalid")}catch(n){if(n.code!=="ENOENT")throw n}}function _(s){return g(E(s,["ls-files","--stage","-z"]))}function D(s,o){const t=E(s,o);return new TextDecoder("utf-8",{fatal:!0}).decode(t).split("\0").filter(Boolean)}function M(s){if(D(s,["ls-files","-v","-z"]).some(t=>!t.startsWith("H ")))throw new Error("refactor-root-index-unverified")}function W(s){const o=[],t=new Set;let r=0;const i=D(s,["status","--porcelain=v1","-z","--untracked-files=all"]);i.push(...D(s,["ls-files","--others","--ignored","--exclude-standard","-z","--",".neocortex/"]).map(n=>`!! ${n}`));for(const n of i){if(n.length<4||n[2]!==" ")throw new Error("refactor-root-sidecar-unverified");const e=n.slice(3);if(!e.startsWith(".neocortex/"))continue;if(t.has(e)||e.includes("\\")||/[\u0000-\u001f\u007f]/.test(e)||e.split("/").some(l=>!l||l==="."||l===".."))throw new Error("refactor-root-sidecar-unverified");t.add(e);const d=b(s,e),f=p(d);if(v(d)!==d||!f.isFile()||f.isSymbolicLink()||f.nlink!==1||f.size>64*1024*1024)throw new Error("refactor-root-sidecar-unverified");if(r+=f.size,r>128*1024*1024)throw new Error("refactor-root-sidecar-unverified");const w=I(d,j.O_RDONLY|j.O_NOFOLLOW);try{const l=Buffer.alloc(f.size+1);let h=0;for(;h<l.length;){const u=fe(w,l,h,l.length-h,h);if(!u)break;h+=u}const m=ae(w),c=p(d);if(h!==f.size||v(d)!==d||[m,c].some(u=>u.dev!==f.dev||u.ino!==f.ino||u.size!==f.size||u.mtimeMs!==f.mtimeMs||u.ctimeMs!==f.ctimeMs||u.mode!==f.mode||u.nlink!==1))throw new Error("refactor-root-sidecar-unverified");o.push({status:n.slice(0,2),path:e,sha256:g(l.subarray(0,h)),mode:f.mode&511})}finally{q(w)}}return o.sort((n,e)=>Buffer.from(n.path).compare(Buffer.from(e.path))),g(JSON.stringify(o))}function V(s){return[...s].sort((o,t)=>Buffer.from(o).compare(Buffer.from(t)))}function te(s){const o=s.files.map(t=>t.path);return g(JSON.stringify(s.schemaVersion===1?o:{files:o,newFiles:s.newFiles.map(t=>t.path)}))}function re(s,o){if(!F.test(o))throw new Error("refactor-root-admission-invalid");return b(Z(s),`admission-${o}.json`)}function X(s,o){const t=re(s,o),r=p(t);if(!r.isFile()||r.isSymbolicLink()||r.uid!==process.getuid?.()||(r.mode&63)!==0||r.size<100||r.size>512*1024)throw new Error("refactor-root-admission-invalid");const i=A(t);if(i.length>512*1024)throw new Error("refactor-root-admission-invalid");let n;try{n=JSON.parse(new TextDecoder("utf-8",{fatal:!0}).decode(i))}catch{throw new Error("refactor-root-admission-invalid")}if(!n||typeof n!="object"||Array.isArray(n))throw new Error("refactor-root-admission-invalid");const e=n,d=e.schemaVersion===2,f=["schemaVersion","kind","storyId","sourceHead","storySha256","planSha256","indexSha256","sidecarSha256","files","admissionSha256"];if(d&&f.push("newFiles"),Object.keys(e).sort().join("\0")!==f.sort().join("\0")||![1,2].includes(e.schemaVersion)||e.kind!=="private-root-refactor-admission"||typeof e.storyId!="string"||!K.test(e.storyId)||typeof e.sourceHead!="string"||!/^[a-f0-9]{40}(?:[a-f0-9]{24})?$/.test(e.sourceHead)||typeof e.storySha256!="string"||!F.test(e.storySha256)||typeof e.planSha256!="string"||!F.test(e.planSha256)||typeof e.indexSha256!="string"||!F.test(e.indexSha256)||typeof e.sidecarSha256!="string"||!F.test(e.sidecarSha256)||e.admissionSha256!==o||!Array.isArray(e.files)||e.files.length>Y||(d?!Array.isArray(e.newFiles)||e.newFiles.length<1||e.files.length+e.newFiles.length>Y:e.files.length<1))throw new Error("refactor-root-admission-invalid");if(g(`root-refactor-story-scope-v1\0${e.sourceHead}\0${e.storyId}\0${e.storySha256}`)!==e.planSha256)throw new Error("refactor-root-admission-invalid");const w=e.files;if(w.some(c=>!c||typeof c!="object"||Array.isArray(c)||Object.keys(c).sort().join("\0")!==["mode","path","sha256"].join("\0")||typeof c.path!="string"||!C(c.path)||typeof c.sha256!="string"||!F.test(c.sha256)||!Number.isSafeInteger(c.mode)||c.mode<0||c.mode>511))throw new Error("refactor-root-admission-invalid");const l=w.map(c=>c.path);if(new Set(l).size!==l.length||l.join("\0")!==V(l).join("\0"))throw new Error("refactor-root-admission-invalid");if(d){const c=e.newFiles;if(c.some(y=>!y||typeof y!="object"||Array.isArray(y)||Object.keys(y).join("\0")!=="path"||typeof y.path!="string"||!C(y.path)))throw new Error("refactor-root-admission-invalid");const u=c.map(y=>y.path);if(new Set([...l,...u]).size!==l.length+u.length||u.join("\0")!==V(u).join("\0")||[...l,...u].includes(`docs/stories/${e.storyId}.story.md`))throw new Error("refactor-root-admission-invalid")}const{admissionSha256:h,...m}=e;if(g(JSON.stringify(m))!==o||!i.equals(Buffer.from(`${JSON.stringify(e)}
-`)))throw new Error("refactor-root-admission-invalid");return e}function he(s,o,t,r,i,n=[]){if(!i)throw new Error("refactor-root-authorization-required");if(!F.test(t)||r.length+n.length<1||r.length+n.length>Y)throw new Error("refactor-root-write-set-invalid");const e=L(s);try{const d=B(e,o);if(d.planSha256!==t)throw new Error("refactor-root-plan-stale");M(e);const f=_(e),w=W(e),l=V(r),h=V(n);if(new Set([...l,...h]).size!==l.length+h.length||[...l,...h].includes(`docs/stories/${o}.story.md`))throw new Error("refactor-root-write-set-invalid");const m=l.map(S=>Object.freeze({path:S,...le(e,S)})),c=h.map(S=>(P(e,S),Object.freeze({path:S})));if(_(e)!==f||W(e)!==w||B(e,o).planSha256!==t)throw new Error("refactor-root-source-dirty");for(const S of c)P(e,S.path);const u={kind:"private-root-refactor-admission",storyId:o,sourceHead:d.sourceHead,storySha256:d.storySha256,planSha256:t,indexSha256:f,sidecarSha256:w,files:m},y=c.length>0?{schemaVersion:2,...u,newFiles:c}:{schemaVersion:1,...u},k=g(JSON.stringify(y)),R={...y,admissionSha256:k},T=re(e,k),J=Buffer.from(`${JSON.stringify(R)}
-`);if(ne(T))X(e,k);else{const S=I(T,j.O_WRONLY|j.O_CREAT|j.O_EXCL|(j.O_NOFOLLOW??0),384);try{de(S,J),G(S)}finally{q(S)}const a=I(Z(e),j.O_RDONLY|(j.O_DIRECTORY??0));try{G(a)}finally{q(a)}}if(X(e,k),_(e)!==f||W(e)!==w||B(e,o).planSha256!==t)throw new Error("refactor-root-source-dirty");for(const S of c)P(e,S.path);const $={kind:"root-refactor-write-set-admission",storyId:o,sourceHead:d.sourceHead,planSha256:t,writeSetSha256:te(R),admissionSha256:k,fileCount:m.length,rootEditPrepared:!0,privateChildAuthorized:!1,gitCommitAuthorized:!1,publicSafe:!0};return R.schemaVersion===2?Object.freeze({schemaVersion:2,...$,newFileCount:c.length}):Object.freeze({schemaVersion:1,...$})}catch(d){throw d instanceof Error&&d.message.startsWith("refactor-root-")?d:new Error("refactor-root-write-set-invalid")}}function oe(s,o){if(!C(o)||ee(s,o)||E(s,["ls-files","--stage","-z","--",o]).length>0)throw new Error("refactor-root-delta-outside-admission");const t=b(s,o),r=U(t);if(!p(r).isDirectory()||v(r)!==r)throw new Error("refactor-root-delta-outside-admission");const i=p(t);if(v(t)!==t||!i.isFile()||i.isSymbolicLink()||i.size===0||i.size>N||(i.mode&75)!==0)throw new Error("refactor-root-delta-outside-admission");const n=A(t);if(n.length===0||n.length>N||n.includes(0))throw new Error("refactor-root-delta-outside-admission");return new TextDecoder("utf-8",{fatal:!0}).decode(n),g(n)}function ue(s,o){return ie(s,o,!1).receipt}function ge(s,o){return ie(s,o,!0)}function ie(s,o,t){const r=L(s);try{const i=X(r,o),n=E(r,["rev-parse","--verify","HEAD"]).toString("utf8").trim();if(n!==i.sourceHead||_(r)!==i.indexSha256||W(r)!==i.sidecarSha256)throw new Error("refactor-root-baseline-stale");M(r);const e=b(r,"docs","stories",`${i.storyId}.story.md`),d=p(e);if(!d.isFile()||d.isSymbolicLink()||v(e)!==e||g(A(e))!==i.storySha256||g(E(r,["show",`HEAD:docs/stories/${i.storyId}.story.md`]))!==i.storySha256)throw new Error("refactor-root-baseline-stale");const f=D(r,["diff","--name-only","-z","--no-ext-diff","--no-textconv"]).filter(a=>!a.startsWith(".neocortex/")),w=D(r,["ls-files","--others","--exclude-standard","-z"]).filter(a=>!a.startsWith(".neocortex/")),l=new Set(i.files.map(a=>a.path)),h=i.schemaVersion===2?i.newFiles.map(a=>a.path):[],m=[];if(t){for(const a of h)if(a.endsWith(".md"))try{p(b(r,a))}catch(z){if(z.code!=="ENOENT")throw z;P(r,a),m.push(a)}}const c=h.filter(a=>!m.includes(a)),u=new Set(h);if(f.length+w.length===0||w.length!==c.length||f.some(a=>!l.has(a))||w.some(a=>!u.has(a)))throw new Error("refactor-root-delta-outside-admission");let y=0;const k=[];for(const a of i.files){const z=b(r,a.path);if(g(E(r,["show",`HEAD:${a.path}`]))!==a.sha256)throw new Error("refactor-root-admission-invalid");const x=p(z);if(v(z)!==z||!x.isFile()||x.isSymbolicLink()||x.size===0||x.size>N||(x.mode&511)!==a.mode)throw new Error("refactor-root-delta-outside-admission");const O=A(z);if(O.length===0||O.length>N)throw new Error("refactor-root-delta-outside-admission");if(new TextDecoder("utf-8",{fatal:!0}).decode(O),O.includes(0))throw new Error("refactor-root-delta-outside-admission");const H=g(O);k.push(H),H!==a.sha256&&y++}const R=c.map(a=>oe(r,a));y+=R.length;const T=D(r,["diff","--name-only","-z","--no-ext-diff","--no-textconv"]).filter(a=>!a.startsWith(".neocortex/")),J=D(r,["ls-files","--others","--exclude-standard","-z"]).filter(a=>!a.startsWith(".neocortex/"));if(M(r),y===0||y!==f.length+w.length||T.join("\0")!==f.join("\0")||J.join("\0")!==w.join("\0")||i.files.some((a,z)=>{const x=b(r,a.path),O=p(x);if(v(x)!==x||!O.isFile()||O.isSymbolicLink()||O.size>N||(O.mode&511)!==a.mode)return!0;const H=A(x);return H.length>N||g(H)!==k[z]})||c.some((a,z)=>oe(r,a)!==R[z])||_(r)!==i.indexSha256||W(r)!==i.sidecarSha256||E(r,["rev-parse","--verify","HEAD"]).toString("utf8").trim()!==n)throw new Error("refactor-root-baseline-stale");for(const a of m)P(r,a);const $={kind:"root-refactor-delta-containment",storyId:i.storyId,sourceHead:i.sourceHead,planSha256:i.planSha256,admissionSha256:o,writeSetSha256:te(i),changedFileCount:y,rootEditContained:!0,qaAccepted:!1,gitCommitAuthorized:!1,publicSafe:!0},S=i.schemaVersion===2?Object.freeze({schemaVersion:2,...$,newFileCount:c.length}):Object.freeze({schemaVersion:1,...$});return Object.freeze({receipt:S,pendingDocumentationPaths:Object.freeze(m)})}catch(i){throw i instanceof Error&&i.message.startsWith("refactor-root-")?i:new Error("refactor-root-delta-unverified")}}function B(s,o){if(!K.test(o))throw new Error("refactor-root-story-invalid");const t=L(s);try{if(v(t)!==t||!p(t).isDirectory())throw new Error("refactor-root-source-unverified");if(E(t,["rev-parse","--show-toplevel"]).toString("utf8").trim()!==t)throw new Error("refactor-root-source-unverified");if(E(t,["status","--porcelain=v1","-z","--untracked-files=all"]).toString("utf8").split("\0").filter(Boolean).some(c=>!/^.{2} \.neocortex\//.test(c)))throw new Error("refactor-root-source-dirty");const n=E(t,["rev-parse","--verify","HEAD"]).toString("utf8").trim();if(!/^[a-f0-9]{40}(?:[a-f0-9]{24})?$/.test(n))throw new Error("refactor-root-source-unverified");const e=`docs/stories/${o}.story.md`,d=b(t,e),f=p(d);if(v(d)!==d||!f.isFile()||f.isSymbolicLink()||f.size===0||f.size>1024*1024)throw new Error("refactor-root-story-unverified");const w=A(d),l=E(t,["show",`HEAD:${e}`]);if(!w.equals(l))throw new Error("refactor-root-story-unverified");const h=g(w),m=g(`root-refactor-story-scope-v1\0${n}\0${o}\0${h}`);return Object.freeze({schemaVersion:1,kind:"root-refactor-story-scope",storyId:o,sourceHead:n,storySha256:h,planSha256:m,candidateWriteSetRequired:!0,characterizationRequired:!0,executionAuthorized:!1,gitAuthority:"ROOT_ONLY",graphExecution:"NOT_RUN",publicSafe:!0})}catch(r){throw r instanceof Error&&r.message.startsWith("refactor-root-")?r:new Error("refactor-root-source-unverified")}}function Se(s){let o="",t="",r="",i="",n="",e=!1;const d=[],f=[];let w="plain";try{const l=[...s];o=l.shift()??"";for(let h=0;h<l.length;h++){const m=l[h],c=()=>{const u=l[++h];if(!u||u.startsWith("--"))throw new Error("refactor-root-arguments-invalid");return u};if(m==="--project-root")t=c();else if(m==="--story")r=c();else if(m==="--plan-sha")i=c();else if(m==="--admission-sha")n=c();else if(m==="--path")d.push(c());else if(m==="--new-path")f.push(c());else if(m==="--authorize-root-edit")e=!0;else if(m==="--format")w=c();else throw new Error("refactor-root-arguments-invalid")}if(!t||!["plain","json"].includes(w))throw new Error("refactor-root-arguments-invalid");if(o==="plan"&&r&&!i&&!n&&d.length===0&&f.length===0&&!e){const h=B(t,r);process.stdout.write(`${JSON.stringify({ok:!0,plan:h})}
-`)}else if(o==="admit"&&r&&i&&!n&&d.length+f.length>0){const h=he(t,r,i,d,e,f);process.stdout.write(`${JSON.stringify({ok:!0,admission:h})}
-`)}else if(o==="verify"&&!r&&!i&&n&&d.length===0&&f.length===0&&!e){const h=ue(t,n);process.stdout.write(`${JSON.stringify({ok:!0,containment:h})}
-`)}else throw new Error("refactor-root-arguments-invalid");return 0}catch(l){const h=l instanceof Error&&/^refactor-root-[a-z-]+$/.test(l.message)?l.message:"refactor-root-source-unverified";return process.stdout.write(`${JSON.stringify({ok:!1,reasonCode:h})}
-`),1}}export{he as admitRootRefactor,le as exactCommittedRefactorFile,B as planRootRefactor,Z as privateRefactorDirectory,X as readPrivateRefactorAdmission,Se as refactorRootCliHandler,W as refactorSidecarDigest,ue as verifyRootRefactor,ge as verifyRootRefactorForCharacterization};
+/** Root-owned refactor scope and physical containment. No private child or Git grant. */
+import { createHash } from 'node:crypto';
+import { closeSync, constants, existsSync, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, readSync, realpathSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { mutationQaGit } from './mutation-qa-git.js';
+const STORY_ID = /^P[0-9]{1,12}(?:\.[0-9]{1,12}){1,3}$/;
+const SHA256 = /^[a-f0-9]{64}$/;
+const MAX_FILE_BYTES = 8 * 1024 * 1024;
+const MAX_PATHS = 256;
+function digest(bytes) {
+    return createHash('sha256').update(bytes).digest('hex');
+}
+export function privateRefactorDirectory(root) {
+    const commonRaw = mutationQaGit(root, ['rev-parse', '--git-common-dir']).toString('utf8').trim();
+    const common = isAbsolute(commonRaw) ? resolve(commonRaw) : resolve(root, commonRaw);
+    if (realpathSync(common) !== common || lstatSync(common).isSymbolicLink()
+        || lstatSync(common).uid !== process.getuid?.())
+        throw new Error('refactor-root-store-unverified');
+    const directory = join(common, 'neocortex-refactor');
+    mkdirSync(directory, { recursive: true, mode: 0o700 });
+    const stat = lstatSync(directory);
+    if (!stat.isDirectory() || stat.isSymbolicLink() || stat.uid !== process.getuid?.()
+        || (stat.mode & 0o077) !== 0)
+        throw new Error('refactor-root-store-unverified');
+    return directory;
+}
+function pathIsSafe(path) {
+    if (!path || path.length > 512 || isAbsolute(path) || path.includes('\\')
+        || /[\u0000-\u001f\u007f:*?\[\]]/.test(path) || path.normalize('NFC') !== path)
+        return false;
+    const parts = path.split('/');
+    return !parts.some((part) => !part || part === '.' || part === '..'
+        || ['.git', '.neocortex', 'node_modules'].includes(part.toLowerCase()));
+}
+export function exactCommittedRefactorFile(root, path) {
+    if (!pathIsSafe(path))
+        throw new Error('refactor-root-write-set-invalid');
+    const physicalPath = join(root, path);
+    const stat = lstatSync(physicalPath);
+    if (realpathSync(physicalPath) !== physicalPath || !stat.isFile() || stat.isSymbolicLink()
+        || stat.size === 0 || stat.size > MAX_FILE_BYTES)
+        throw new Error('refactor-root-write-set-invalid');
+    const bytes = readFileSync(physicalPath);
+    if (bytes.length === 0 || bytes.length > MAX_FILE_BYTES) {
+        throw new Error('refactor-root-write-set-invalid');
+    }
+    new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+    if (bytes.includes(0))
+        throw new Error('refactor-root-write-set-invalid');
+    const committed = mutationQaGit(root, ['show', `HEAD:${path}`]);
+    if (!bytes.equals(committed))
+        throw new Error('refactor-root-source-dirty');
+    return Object.freeze({ sha256: digest(bytes), mode: stat.mode & 0o777 });
+}
+function ignoredByGit(root, path) {
+    try {
+        mutationQaGit(root, ['check-ignore', '--no-index', '-q', '--', path]);
+        return true;
+    }
+    catch (error) {
+        if (error.status === 1)
+            return false;
+        throw error;
+    }
+}
+/** A new test/document path is explicit, absent, untracked and not ignored. */
+function exactNewPath(root, path) {
+    if (!pathIsSafe(path))
+        throw new Error('refactor-root-write-set-invalid');
+    const physicalPath = join(root, path);
+    const parent = dirname(physicalPath);
+    const parentStat = lstatSync(parent);
+    if (!parentStat.isDirectory() || parentStat.isSymbolicLink() || realpathSync(parent) !== parent
+        || mutationQaGit(root, ['ls-files', '--stage', '-z', '--', path]).length > 0
+        || ignoredByGit(root, path))
+        throw new Error('refactor-root-write-set-invalid');
+    try {
+        lstatSync(physicalPath);
+        throw new Error('refactor-root-write-set-invalid');
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+}
+function indexDigest(root) {
+    return digest(mutationQaGit(root, ['ls-files', '--stage', '-z']));
+}
+function names(root, args) {
+    const bytes = mutationQaGit(root, args);
+    const decoded = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+    return decoded.split('\0').filter(Boolean);
+}
+function requireNormalIndex(root) {
+    const entries = names(root, ['ls-files', '-v', '-z']);
+    if (entries.some((entry) => !entry.startsWith('H '))) {
+        throw new Error('refactor-root-index-unverified');
+    }
+}
+/** Preserve pre-existing visible and ignored Neocortex controls without copying them to a model. */
+export function refactorSidecarDigest(root) {
+    const rows = [];
+    const seen = new Set();
+    let totalBytes = 0;
+    const entries = names(root, ['status', '--porcelain=v1', '-z', '--untracked-files=all']);
+    entries.push(...names(root, ['ls-files', '--others', '--ignored', '--exclude-standard', '-z', '--', '.neocortex/'])
+        .map(path => `!! ${path}`));
+    for (const entry of entries) {
+        if (entry.length < 4 || entry[2] !== ' ')
+            throw new Error('refactor-root-sidecar-unverified');
+        const path = entry.slice(3);
+        if (!path.startsWith('.neocortex/'))
+            continue;
+        if (seen.has(path) || path.includes('\\') || /[\u0000-\u001f\u007f]/.test(path)
+            || path.split('/').some((part) => !part || part === '.' || part === '..')) {
+            throw new Error('refactor-root-sidecar-unverified');
+        }
+        seen.add(path);
+        const physicalPath = join(root, path);
+        const stat = lstatSync(physicalPath);
+        if (realpathSync(physicalPath) !== physicalPath || !stat.isFile() || stat.isSymbolicLink()
+            || stat.nlink !== 1 || stat.size > 64 * 1024 * 1024)
+            throw new Error('refactor-root-sidecar-unverified');
+        totalBytes += stat.size;
+        if (totalBytes > 128 * 1024 * 1024)
+            throw new Error('refactor-root-sidecar-unverified');
+        const fd = openSync(physicalPath, constants.O_RDONLY | constants.O_NOFOLLOW);
+        try {
+            const buffer = Buffer.alloc(stat.size + 1);
+            let length = 0;
+            while (length < buffer.length) {
+                const count = readSync(fd, buffer, length, buffer.length - length, length);
+                if (!count)
+                    break;
+                length += count;
+            }
+            const after = fstatSync(fd), current = lstatSync(physicalPath);
+            if (length !== stat.size || realpathSync(physicalPath) !== physicalPath
+                || [after, current].some(value => value.dev !== stat.dev || value.ino !== stat.ino
+                    || value.size !== stat.size || value.mtimeMs !== stat.mtimeMs || value.ctimeMs !== stat.ctimeMs
+                    || value.mode !== stat.mode || value.nlink !== 1))
+                throw new Error('refactor-root-sidecar-unverified');
+            rows.push({ status: entry.slice(0, 2), path, sha256: digest(buffer.subarray(0, length)), mode: stat.mode & 0o777 });
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    rows.sort((a, b) => Buffer.from(a.path).compare(Buffer.from(b.path)));
+    return digest(JSON.stringify(rows));
+}
+function orderedPaths(paths) {
+    return [...paths].sort((a, b) => Buffer.from(a).compare(Buffer.from(b)));
+}
+function writeSetDigest(record) {
+    const files = record.files.map((file) => file.path);
+    return digest(JSON.stringify(record.schemaVersion === 1
+        ? files : { files, newFiles: record.newFiles.map((file) => file.path) }));
+}
+function admissionPath(root, sha256) {
+    if (!SHA256.test(sha256))
+        throw new Error('refactor-root-admission-invalid');
+    return join(privateRefactorDirectory(root), `admission-${sha256}.json`);
+}
+export function readPrivateRefactorAdmission(root, sha256) {
+    const path = admissionPath(root, sha256);
+    const stat = lstatSync(path);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.uid !== process.getuid?.()
+        || (stat.mode & 0o077) !== 0 || stat.size < 100 || stat.size > 512 * 1024) {
+        throw new Error('refactor-root-admission-invalid');
+    }
+    const raw = readFileSync(path);
+    if (raw.length > 512 * 1024)
+        throw new Error('refactor-root-admission-invalid');
+    let parsed;
+    try {
+        parsed = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(raw));
+    }
+    catch {
+        throw new Error('refactor-root-admission-invalid');
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error('refactor-root-admission-invalid');
+    }
+    const record = parsed;
+    const v2 = record.schemaVersion === 2;
+    const keys = ['schemaVersion', 'kind', 'storyId', 'sourceHead', 'storySha256',
+        'planSha256', 'indexSha256', 'sidecarSha256', 'files', 'admissionSha256'];
+    if (v2)
+        keys.push('newFiles');
+    if (Object.keys(record).sort().join('\0') !== keys.sort().join('\0')
+        || ![1, 2].includes(record.schemaVersion)
+        || record.kind !== 'private-root-refactor-admission'
+        || typeof record.storyId !== 'string' || !STORY_ID.test(record.storyId)
+        || typeof record.sourceHead !== 'string' || !/^[a-f0-9]{40}(?:[a-f0-9]{24})?$/.test(record.sourceHead)
+        || typeof record.storySha256 !== 'string' || !SHA256.test(record.storySha256)
+        || typeof record.planSha256 !== 'string' || !SHA256.test(record.planSha256)
+        || typeof record.indexSha256 !== 'string' || !SHA256.test(record.indexSha256)
+        || typeof record.sidecarSha256 !== 'string' || !SHA256.test(record.sidecarSha256)
+        || record.admissionSha256 !== sha256 || !Array.isArray(record.files)
+        || record.files.length > MAX_PATHS
+        || (v2 ? !Array.isArray(record.newFiles) || record.newFiles.length < 1
+            || record.files.length + record.newFiles.length > MAX_PATHS
+            : record.files.length < 1)) {
+        throw new Error('refactor-root-admission-invalid');
+    }
+    if (digest(`root-refactor-story-scope-v1\0${record.sourceHead}\0${record.storyId}\0${record.storySha256}`)
+        !== record.planSha256)
+        throw new Error('refactor-root-admission-invalid');
+    const files = record.files;
+    if (files.some((file) => !file || typeof file !== 'object' || Array.isArray(file)
+        || Object.keys(file).sort().join('\0') !== ['mode', 'path', 'sha256'].join('\0')
+        || typeof file.path !== 'string'
+        || !pathIsSafe(file.path)
+        || typeof file.sha256 !== 'string'
+        || !SHA256.test(file.sha256)
+        || !Number.isSafeInteger(file.mode)
+        || file.mode < 0
+        || file.mode > 0o777)) {
+        throw new Error('refactor-root-admission-invalid');
+    }
+    const ordered = files.map((file) => file.path);
+    if (new Set(ordered).size !== ordered.length
+        || ordered.join('\0') !== orderedPaths(ordered).join('\0')) {
+        throw new Error('refactor-root-admission-invalid');
+    }
+    if (v2) {
+        const newFiles = record.newFiles;
+        if (newFiles.some((file) => !file || typeof file !== 'object' || Array.isArray(file)
+            || Object.keys(file).join('\0') !== 'path'
+            || typeof file.path !== 'string'
+            || !pathIsSafe(file.path))) {
+            throw new Error('refactor-root-admission-invalid');
+        }
+        const newPaths = newFiles.map((file) => file.path);
+        if (new Set([...ordered, ...newPaths]).size !== ordered.length + newPaths.length
+            || newPaths.join('\0') !== orderedPaths(newPaths).join('\0')
+            || [...ordered, ...newPaths].includes(`docs/stories/${record.storyId}.story.md`)) {
+            throw new Error('refactor-root-admission-invalid');
+        }
+    }
+    const { admissionSha256: _digest, ...body } = record;
+    if (digest(JSON.stringify(body)) !== sha256 || !raw.equals(Buffer.from(`${JSON.stringify(record)}\n`))) {
+        throw new Error('refactor-root-admission-invalid');
+    }
+    return record;
+}
+export function admitRootRefactor(projectRoot, storyId, planSha256, paths, authorizeRootEdit, newPaths = []) {
+    if (!authorizeRootEdit)
+        throw new Error('refactor-root-authorization-required');
+    if (!SHA256.test(planSha256) || paths.length + newPaths.length < 1
+        || paths.length + newPaths.length > MAX_PATHS) {
+        throw new Error('refactor-root-write-set-invalid');
+    }
+    const root = resolve(projectRoot);
+    try {
+        const plan = planRootRefactor(root, storyId);
+        if (plan.planSha256 !== planSha256)
+            throw new Error('refactor-root-plan-stale');
+        requireNormalIndex(root);
+        const beforeIndex = indexDigest(root);
+        const beforeSidecar = refactorSidecarDigest(root);
+        const ordered = orderedPaths(paths);
+        const orderedNew = orderedPaths(newPaths);
+        if (new Set([...ordered, ...orderedNew]).size !== ordered.length + orderedNew.length
+            || [...ordered, ...orderedNew].includes(`docs/stories/${storyId}.story.md`)) {
+            throw new Error('refactor-root-write-set-invalid');
+        }
+        const files = ordered.map((path) => Object.freeze({ path, ...exactCommittedRefactorFile(root, path) }));
+        const newFiles = orderedNew.map((path) => { exactNewPath(root, path); return Object.freeze({ path }); });
+        if (indexDigest(root) !== beforeIndex || refactorSidecarDigest(root) !== beforeSidecar
+            || planRootRefactor(root, storyId).planSha256 !== planSha256) {
+            throw new Error('refactor-root-source-dirty');
+        }
+        for (const file of newFiles)
+            exactNewPath(root, file.path);
+        const base = { kind: 'private-root-refactor-admission',
+            storyId, sourceHead: plan.sourceHead, storySha256: plan.storySha256,
+            planSha256, indexSha256: beforeIndex, sidecarSha256: beforeSidecar, files };
+        const body = newFiles.length > 0
+            ? { schemaVersion: 2, ...base, newFiles }
+            : { schemaVersion: 1, ...base };
+        const admissionSha256 = digest(JSON.stringify(body));
+        const record = { ...body, admissionSha256 };
+        const path = admissionPath(root, admissionSha256);
+        const bytes = Buffer.from(`${JSON.stringify(record)}\n`);
+        if (existsSync(path)) {
+            readPrivateRefactorAdmission(root, admissionSha256);
+        }
+        else {
+            const handle = openSync(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL
+                | (constants.O_NOFOLLOW ?? 0), 0o600);
+            try {
+                writeFileSync(handle, bytes);
+                fsyncSync(handle);
+            }
+            finally {
+                closeSync(handle);
+            }
+            const directoryHandle = openSync(privateRefactorDirectory(root), constants.O_RDONLY | (constants.O_DIRECTORY ?? 0));
+            try {
+                fsyncSync(directoryHandle);
+            }
+            finally {
+                closeSync(directoryHandle);
+            }
+        }
+        readPrivateRefactorAdmission(root, admissionSha256);
+        if (indexDigest(root) !== beforeIndex || refactorSidecarDigest(root) !== beforeSidecar
+            || planRootRefactor(root, storyId).planSha256 !== planSha256) {
+            throw new Error('refactor-root-source-dirty');
+        }
+        for (const file of newFiles)
+            exactNewPath(root, file.path);
+        const receipt = { kind: 'root-refactor-write-set-admission',
+            storyId, sourceHead: plan.sourceHead, planSha256,
+            writeSetSha256: writeSetDigest(record), admissionSha256,
+            fileCount: files.length, rootEditPrepared: true, privateChildAuthorized: false,
+            gitCommitAuthorized: false, publicSafe: true };
+        return record.schemaVersion === 2
+            ? Object.freeze({ schemaVersion: 2, ...receipt, newFileCount: newFiles.length })
+            : Object.freeze({ schemaVersion: 1, ...receipt });
+    }
+    catch (error) {
+        if (error instanceof Error && error.message.startsWith('refactor-root-'))
+            throw error;
+        throw new Error('refactor-root-write-set-invalid');
+    }
+}
+function physicalNewFile(root, path) {
+    if (!pathIsSafe(path) || ignoredByGit(root, path)
+        || mutationQaGit(root, ['ls-files', '--stage', '-z', '--', path]).length > 0) {
+        throw new Error('refactor-root-delta-outside-admission');
+    }
+    const physicalPath = join(root, path);
+    const parent = dirname(physicalPath);
+    if (!lstatSync(parent).isDirectory() || realpathSync(parent) !== parent) {
+        throw new Error('refactor-root-delta-outside-admission');
+    }
+    const stat = lstatSync(physicalPath);
+    if (realpathSync(physicalPath) !== physicalPath || !stat.isFile() || stat.isSymbolicLink()
+        || stat.size === 0 || stat.size > MAX_FILE_BYTES
+        || (stat.mode & 0o113) !== 0)
+        throw new Error('refactor-root-delta-outside-admission');
+    const bytes = readFileSync(physicalPath);
+    if (bytes.length === 0 || bytes.length > MAX_FILE_BYTES || bytes.includes(0)) {
+        throw new Error('refactor-root-delta-outside-admission');
+    }
+    new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+    return digest(bytes);
+}
+export function verifyRootRefactor(projectRoot, admissionSha256) {
+    return verifyRefactorDelta(projectRoot, admissionSha256, false).receipt;
+}
+/** Private characterization preparation only. Full review/commit still requires
+ * every admitted new file. Missing Markdown cannot authorize QA or Git effects.
+ */
+export function verifyRootRefactorForCharacterization(projectRoot, admissionSha256) {
+    return verifyRefactorDelta(projectRoot, admissionSha256, true);
+}
+function verifyRefactorDelta(projectRoot, admissionSha256, allowPendingDocumentation) {
+    const root = resolve(projectRoot);
+    try {
+        const record = readPrivateRefactorAdmission(root, admissionSha256);
+        const head = mutationQaGit(root, ['rev-parse', '--verify', 'HEAD']).toString('utf8').trim();
+        if (head !== record.sourceHead || indexDigest(root) !== record.indexSha256
+            || refactorSidecarDigest(root) !== record.sidecarSha256) {
+            throw new Error('refactor-root-baseline-stale');
+        }
+        requireNormalIndex(root);
+        const storyPath = join(root, 'docs', 'stories', `${record.storyId}.story.md`);
+        const storyStat = lstatSync(storyPath);
+        if (!storyStat.isFile() || storyStat.isSymbolicLink() || realpathSync(storyPath) !== storyPath
+            || digest(readFileSync(storyPath)) !== record.storySha256
+            || digest(mutationQaGit(root, ['show', `HEAD:docs/stories/${record.storyId}.story.md`]))
+                !== record.storySha256) {
+            throw new Error('refactor-root-baseline-stale');
+        }
+        const changed = names(root, ['diff', '--name-only', '-z', '--no-ext-diff', '--no-textconv'])
+            .filter((path) => !path.startsWith('.neocortex/'));
+        const untracked = names(root, ['ls-files', '--others', '--exclude-standard', '-z'])
+            .filter((path) => !path.startsWith('.neocortex/'));
+        const admitted = new Set(record.files.map((file) => file.path));
+        const admittedNew = record.schemaVersion === 2 ? record.newFiles.map((file) => file.path) : [];
+        const pendingDocumentationPaths = [];
+        if (allowPendingDocumentation)
+            for (const path of admittedNew) {
+                if (!path.endsWith('.md'))
+                    continue;
+                try {
+                    lstatSync(join(root, path));
+                }
+                catch (error) {
+                    if (error.code !== 'ENOENT')
+                        throw error;
+                    exactNewPath(root, path);
+                    pendingDocumentationPaths.push(path);
+                }
+            }
+        const materializedNew = admittedNew.filter(path => !pendingDocumentationPaths.includes(path));
+        const newSet = new Set(admittedNew);
+        if (changed.length + untracked.length === 0 || untracked.length !== materializedNew.length
+            || changed.some((path) => !admitted.has(path))
+            || untracked.some((path) => !newSet.has(path))) {
+            throw new Error('refactor-root-delta-outside-admission');
+        }
+        let changedFileCount = 0;
+        const currentDigests = [];
+        for (const file of record.files) {
+            const physicalPath = join(root, file.path);
+            if (digest(mutationQaGit(root, ['show', `HEAD:${file.path}`])) !== file.sha256) {
+                throw new Error('refactor-root-admission-invalid');
+            }
+            const stat = lstatSync(physicalPath);
+            if (realpathSync(physicalPath) !== physicalPath || !stat.isFile() || stat.isSymbolicLink()
+                || stat.size === 0 || stat.size > MAX_FILE_BYTES || (stat.mode & 0o777) !== file.mode) {
+                throw new Error('refactor-root-delta-outside-admission');
+            }
+            const bytes = readFileSync(physicalPath);
+            if (bytes.length === 0 || bytes.length > MAX_FILE_BYTES) {
+                throw new Error('refactor-root-delta-outside-admission');
+            }
+            new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+            if (bytes.includes(0))
+                throw new Error('refactor-root-delta-outside-admission');
+            const current = digest(bytes);
+            currentDigests.push(current);
+            if (current !== file.sha256)
+                changedFileCount++;
+        }
+        const newDigests = materializedNew.map((path) => physicalNewFile(root, path));
+        changedFileCount += newDigests.length;
+        const finalChanged = names(root, ['diff', '--name-only', '-z', '--no-ext-diff', '--no-textconv'])
+            .filter((path) => !path.startsWith('.neocortex/'));
+        const finalUntracked = names(root, ['ls-files', '--others', '--exclude-standard', '-z'])
+            .filter((path) => !path.startsWith('.neocortex/'));
+        requireNormalIndex(root);
+        if (changedFileCount === 0 || changedFileCount !== changed.length + untracked.length
+            || finalChanged.join('\0') !== changed.join('\0')
+            || finalUntracked.join('\0') !== untracked.join('\0')
+            || record.files.some((file, index) => {
+                const path = join(root, file.path);
+                const stat = lstatSync(path);
+                if (realpathSync(path) !== path || !stat.isFile() || stat.isSymbolicLink()
+                    || stat.size > MAX_FILE_BYTES || (stat.mode & 0o777) !== file.mode)
+                    return true;
+                const bytes = readFileSync(path);
+                return bytes.length > MAX_FILE_BYTES || digest(bytes) !== currentDigests[index];
+            })
+            || materializedNew.some((path, index) => physicalNewFile(root, path) !== newDigests[index])
+            || indexDigest(root) !== record.indexSha256
+            || refactorSidecarDigest(root) !== record.sidecarSha256
+            || mutationQaGit(root, ['rev-parse', '--verify', 'HEAD']).toString('utf8').trim() !== head) {
+            throw new Error('refactor-root-baseline-stale');
+        }
+        for (const path of pendingDocumentationPaths)
+            exactNewPath(root, path);
+        const receipt = { kind: 'root-refactor-delta-containment',
+            storyId: record.storyId, sourceHead: record.sourceHead,
+            planSha256: record.planSha256, admissionSha256,
+            writeSetSha256: writeSetDigest(record),
+            changedFileCount, rootEditContained: true, qaAccepted: false,
+            gitCommitAuthorized: false, publicSafe: true };
+        const fullReceipt = record.schemaVersion === 2
+            ? Object.freeze({ schemaVersion: 2, ...receipt, newFileCount: materializedNew.length })
+            : Object.freeze({ schemaVersion: 1, ...receipt });
+        return Object.freeze({ receipt: fullReceipt,
+            pendingDocumentationPaths: Object.freeze(pendingDocumentationPaths) });
+    }
+    catch (error) {
+        if (error instanceof Error && error.message.startsWith('refactor-root-'))
+            throw error;
+        throw new Error('refactor-root-delta-unverified');
+    }
+}
+export function planRootRefactor(projectRoot, storyId) {
+    if (!STORY_ID.test(storyId))
+        throw new Error('refactor-root-story-invalid');
+    const root = resolve(projectRoot);
+    try {
+        if (realpathSync(root) !== root || !lstatSync(root).isDirectory()) {
+            throw new Error('refactor-root-source-unverified');
+        }
+        const top = mutationQaGit(root, ['rev-parse', '--show-toplevel']).toString('utf8').trim();
+        if (top !== root)
+            throw new Error('refactor-root-source-unverified');
+        const status = mutationQaGit(root, ['status', '--porcelain=v1', '-z', '--untracked-files=all'])
+            .toString('utf8').split('\0').filter(Boolean);
+        if (status.some((entry) => !/^.{2} \.neocortex\//.test(entry))) {
+            throw new Error('refactor-root-source-dirty');
+        }
+        const sourceHead = mutationQaGit(root, ['rev-parse', '--verify', 'HEAD']).toString('utf8').trim();
+        if (!/^[a-f0-9]{40}(?:[a-f0-9]{24})?$/.test(sourceHead)) {
+            throw new Error('refactor-root-source-unverified');
+        }
+        const relativePath = `docs/stories/${storyId}.story.md`;
+        const physicalPath = join(root, relativePath);
+        const stat = lstatSync(physicalPath);
+        if (realpathSync(physicalPath) !== physicalPath || !stat.isFile() || stat.isSymbolicLink()
+            || stat.size === 0 || stat.size > 1024 * 1024) {
+            throw new Error('refactor-root-story-unverified');
+        }
+        const physical = readFileSync(physicalPath);
+        const committed = mutationQaGit(root, ['show', `HEAD:${relativePath}`]);
+        if (!physical.equals(committed))
+            throw new Error('refactor-root-story-unverified');
+        const storySha256 = digest(physical);
+        const planSha256 = digest(`root-refactor-story-scope-v1\0${sourceHead}\0${storyId}\0${storySha256}`);
+        return Object.freeze({ schemaVersion: 1, kind: 'root-refactor-story-scope', storyId,
+            sourceHead, storySha256, planSha256, candidateWriteSetRequired: true,
+            characterizationRequired: true, executionAuthorized: false,
+            gitAuthority: 'ROOT_ONLY', graphExecution: 'NOT_RUN', publicSafe: true });
+    }
+    catch (error) {
+        if (error instanceof Error && error.message.startsWith('refactor-root-'))
+            throw error;
+        throw new Error('refactor-root-source-unverified');
+    }
+}
+export function refactorRootCliHandler(args) {
+    let action = '';
+    let projectRoot = '';
+    let storyId = '';
+    let planSha256 = '';
+    let admissionSha256 = '';
+    let authorizeRootEdit = false;
+    const paths = [];
+    const newPaths = [];
+    let format = 'plain';
+    try {
+        const tokens = [...args];
+        action = tokens.shift() ?? '';
+        for (let index = 0; index < tokens.length; index++) {
+            const token = tokens[index];
+            const next = () => {
+                const value = tokens[++index];
+                if (!value || value.startsWith('--'))
+                    throw new Error('refactor-root-arguments-invalid');
+                return value;
+            };
+            if (token === '--project-root')
+                projectRoot = next();
+            else if (token === '--story')
+                storyId = next();
+            else if (token === '--plan-sha')
+                planSha256 = next();
+            else if (token === '--admission-sha')
+                admissionSha256 = next();
+            else if (token === '--path')
+                paths.push(next());
+            else if (token === '--new-path')
+                newPaths.push(next());
+            else if (token === '--authorize-root-edit')
+                authorizeRootEdit = true;
+            else if (token === '--format')
+                format = next();
+            else
+                throw new Error('refactor-root-arguments-invalid');
+        }
+        if (!projectRoot || !['plain', 'json'].includes(format)) {
+            throw new Error('refactor-root-arguments-invalid');
+        }
+        if (action === 'plan' && storyId && !planSha256 && !admissionSha256
+            && paths.length === 0 && newPaths.length === 0 && !authorizeRootEdit) {
+            const plan = planRootRefactor(projectRoot, storyId);
+            process.stdout.write(`${JSON.stringify({ ok: true, plan })}\n`);
+        }
+        else if (action === 'admit' && storyId && planSha256 && !admissionSha256
+            && paths.length + newPaths.length > 0) {
+            const admission = admitRootRefactor(projectRoot, storyId, planSha256, paths, authorizeRootEdit, newPaths);
+            process.stdout.write(`${JSON.stringify({ ok: true, admission })}\n`);
+        }
+        else if (action === 'verify' && !storyId && !planSha256 && admissionSha256
+            && paths.length === 0 && newPaths.length === 0 && !authorizeRootEdit) {
+            const containment = verifyRootRefactor(projectRoot, admissionSha256);
+            process.stdout.write(`${JSON.stringify({ ok: true, containment })}\n`);
+        }
+        else
+            throw new Error('refactor-root-arguments-invalid');
+        return 0;
+    }
+    catch (error) {
+        const reasonCode = error instanceof Error && /^refactor-root-[a-z-]+$/.test(error.message)
+            ? error.message : 'refactor-root-source-unverified';
+        process.stdout.write(`${JSON.stringify({ ok: false, reasonCode })}\n`);
+        return 1;
+    }
+}