@ornexus/neocortex 4.60.66 → 4.60.68

package/packages/client/dist/memory/project-memory-writer.js

@@ -1,40 +1,1007 @@
-import{randomUUID as U}from"node:crypto";import{constants as V,existsSync as g,lstatSync as C,mkdirSync as O,copyFileSync as j,readdirSync as Q,readFileSync as E,readlinkSync as ee,realpathSync as we,renameSync as te,rmSync as N,statSync as Ee,symlinkSync as B,unlinkSync as re,writeFileSync as q}from"node:fs";import{platform as M}from"node:os";import{basename as Re,dirname as I,join as p,relative as Se,resolve as Ce}from"node:path";import{CANONICAL_PROJECT_MEMORY_SOURCE as b,getProjectMemoryTarget as W,renderArchitectureReferenceTable as Pe}from"./shared-project-memory-types.js";import{assertProjectMemoryPaths as F,invalidProjectMemoryPath as $e,isValidScopedRelativePath as Te}from"./project-memory-path-scope.js";function ne(e){return(e.memoryNotes?.length??0)>0||(e.architectureReferences?.length??0)>0||e.bootstrapArchitecture!==void 0}const X="<!-- NEOCORTEX-REFRESH-UPDATES-START -->",z="<!-- NEOCORTEX-REFRESH-UPDATES-END -->";function A(e,t){return e.split(t).length-1}function ve(e){ce(e.memoryNotes??[],e.architectureReferences??[],e.bootstrapArchitecture);const t=G(e.memoryNotes??[]).map(r=>`- [${r.reasonCode}] ${r.summary} (layer: ${r.layer})`),n=(e.architectureReferences??[]).map(r=>`- [architecture-reference] \`${r.path}\`: ${r.title}; ${r.purpose}; use: ${r.suggestedUsage}`),o=e.bootstrapArchitecture,s=o===void 0?[]:[...(o.universalLaws??[]).map(r=>`- [bootstrap-law] ${r}`),...(o.businessContext??[]).map(r=>`- [bootstrap-business] ${r}`),...(o.activeContext??[]).map(r=>`- [bootstrap-context] ${r}`),...(o.repositoryMap??[]).map(r=>`- [bootstrap-repository] ${r}`),...(o.environmentPractices??[]).map(r=>`- [bootstrap-environment] ${r}`),...(o.platformMemoryContract??[]).map(r=>`- [bootstrap-platform] ${r}`),...(o.maintenanceRules??[]).map(r=>`- [bootstrap-maintenance] ${r}`),...(o.heuristics??[]).map(r=>`- [bootstrap-heuristic] ${r}`)];return w([...t,...n,...s])}function xe(e,t){if(t.split(`
-`).length>e.budget.maxLines||Buffer.byteLength(t,"utf8")>e.budget.maxBytes)throw new Error("Canonical project memory update exceeds its context budget; refusing to truncate existing content.")}function oe(e,t,n){const o=ve(n);if(o.length===0)return t;const s=t.includes(`\r
-`)?`\r
-`:`
-`,r=$(e),a=L(e),c=A(t,r),u=A(t,a);if(c!==1||u!==1||t.indexOf(a)<t.indexOf(r))throw new Error("Canonical project memory has ambiguous managed-block markers; refusing refresh.");const l=A(t,X),i=A(t,z);if(l!==i||l>1)throw new Error("Canonical project memory has ambiguous refresh-update markers; refusing refresh.");let d;if(l===0){const m=t.indexOf(a),h=t.slice(0,m),k=[X,"## Durable Refresh Updates",...o,z,""].join(s);d=`${h}${h.endsWith(s)?"":s}${k}${t.slice(m)}`}else{const m=t.indexOf(X),h=t.indexOf(z),k=t.indexOf(r),R=t.indexOf(a);if(m<k||h>R||h<m)throw new Error("Canonical refresh-update block is outside the managed block; refusing refresh.");const _=t.slice(m,h),D=new Set(_.split(/\r?\n/).map(S=>S.trim().toLowerCase())),f=o.filter(S=>!D.has(S.trim().toLowerCase()));if(f.length===0)return t;const x=t.slice(0,h);d=`${x}${x.endsWith(s)?"":s}${f.join(s)}${s}${t.slice(h)}`}return xe(e,d),d}function Oe(e){return{readFile(t){try{return E(t,"utf8")}catch{return}},writeFileAtomic(t,n){O(I(t),{recursive:!0});const o=U(),s=`${t}.tmp-${o}`,r=g(t)?fe(t,o,e):void 0;try{return q(s,n,{encoding:"utf8",flag:"wx",mode:384}),r!==void 0&&j(t,r,V.COPYFILE_EXCL),te(s,t),{backupPath:r}}catch(a){if(N(s,{force:!0}),r!==void 0&&g(r))try{j(r,t)}catch{}throw a}},join(...t){return p(...t)}}}function $(e){return`<!-- ${e.ownedBlockName}-START -->`}function L(e){return`<!-- ${e.ownedBlockName}-END -->`}function w(e){const t=new Set,n=[];for(const o of e){const s=o.trim().replace(/\s+/g," ");s.length===0||t.has(s.toLowerCase())||(t.add(s.toLowerCase()),n.push(s))}return n}function je(e){const t=new Set,n=[];for(const o of e)t.has(o.path)||(t.add(o.path),n.push(o));return n}function Ne(e){switch(e.templateKind){case"neocortex-md":return"# NEOCORTEX.md Project Memory";case"claude-md":return"# CLAUDE.md Project Memory";case"agents-md":return"# AGENTS.md Project Instructions";case"gemini-md":return"# GEMINI.md Project Memory";case"copilot-instructions":return"# GitHub Copilot Repository Instructions";case"cursor-rule":return`---
-description: Neocortex project memory
-alwaysApply: true
----
-
-# Cursor Project Memory`}}const Me=["Keep always-loaded memory compact: laws, active context, and references only.","Preserve human-authored instructions outside this owned block.","Prefer repository SSoT docs over duplicating architecture details here."],Ie=["Consult `docs/architecture/` before changes that affect architecture, contracts, data, security, performance, UX, or infrastructure.","Reference architecture documents by repository path, such as `docs/architecture/architecture.md`, before changing related implementation.","Summarize decisions and trade-offs in NEOCORTEX.md; do not paste complete architecture documents into memory.","Update memory for durable cross-layer changes across skills/agents, frontend, backend, API, DB, schemas, envs, DevOps, cyber security, testing/QA, observability, product, docs, and platform contracts.","Prioritize compact summaries of durable decisions, public contracts, operational risks, debts, command behavior, and repository paths; skip transient logs, raw payloads, secrets, private prompts, long documents, and duplicated canonical sources.","Keep platform memory files symlink-backed or include-backed to NEOCORTEX.md when supported."],it=["skills-agents","frontend","backend","api","db","schemas","envs","devops","cyber-security","testing-qa","observability","product-business","docs-architecture","platform-memory","command-behavior","generic"],Ae=360,se={feature:"Features",rule:"Rules/Policies",flag:"Flags",route:"Routes",api:"APIs/Contracts","db-schema":"DB/Schema",architecture:"Architecture",debt:"Debts",decision:"Decisions",generic:"General Updates"},Le=/\b(private|proprietary|server[- ]only|system)\s+prompt\b|\b(api[-_ ]?key|license[-_ ]?key|password|authorization|bearer|token|secret)\s*[:=]|\b(ghp_[A-Za-z0-9_]+|sk-[A-Za-z0-9_-]+|xox[baprs]-[A-Za-z0-9-]+)\b|\b(customer|cliente)\s+(payload|record|email|phone)\b|\b(customer|cliente)\s+(data|dados)\s+(payload|record|email|phone)\b|\b(customer|cliente)\s+(data|dados)\s*[:=]|\braw\s+payload\b/i;function _e(e){const t=e.toLowerCase();return/\b(project memory|canonical memory|memory heuristic|neocortex\.md|\*update-memory)\b/.test(t)?"decision":/\b(feature|capability|funcionalidade|release)\b/.test(t)?"feature":/\b(rule|policy|guardrail|regra|lei|must|never)\b/.test(t)?"rule":/\b(flag|feature[- ]?flag|toggle|env var|environment variable)\b/.test(t)?"flag":/\b(api|contract|schema contract|graphql|rest|rpc|webhook)\b/.test(t)?"api":/\b(db|database|schema|migration|table|column|prisma|sql)\b/.test(t)?"db-schema":/\b(decision|decisão|decisao|accepted|rejected|trade[- ]?off)\b/.test(t)?"decision":/\b(route|endpoint route|url path|pathname)\b|\/(api|admin|portal|v\d+)\//.test(t)?"route":/\b(architecture|arquitetura|adr|topology|infra|boundary)\b/.test(t)?"architecture":/\b(debt|follow[- ]?up|todo|tech[- ]?debt|dívida|divida)\b/.test(t)?"debt":"generic"}function De(e){const t=e.toLowerCase();return/\b(neocortex\.md|project memory|canonical memory|memory wrapper|symlink|owned block|memory heuristic)\b/.test(t)?"platform-memory":/\b(command|cli|\*update-memory|\*create-epic|\*arch-plan|workflow behavior)\b/.test(t)?"command-behavior":/\b(skill|agent|subagent|orchestrator|opencode|codex|claude|gemini|cursor)\b/.test(t)?"skills-agents":/\b(frontend|ui|ux|react|component|design[- ]?system|css|accessibility|a11y)\b/.test(t)?"frontend":/\b(backend|server|service|worker|job|queue)\b/.test(t)?"backend":/\b(api|endpoint|rest|graphql|rpc|webhook|contract)\b/.test(t)?"api":/\b(db|database|table|column|migration|sql|prisma)\b/.test(t)?"db":/\b(schema|schemas|zod|json schema|protobuf|openapi)\b/.test(t)?"schemas":/\b(env|environment|\.env\.example|config|configuration|feature[- ]?flag)\b/.test(t)?"envs":/\b(devops|deploy|deployment|ci|cd|docker|container|kubernetes|infra|terraform|rollback)\b/.test(t)?"devops":/\b(security|cyber|auth|authorization|permission|compliance|vulnerability|secret|token redaction)\b/.test(t)?"cyber-security":/\b(test|testing|qa|e2e|unit|integration|snapshot|property[- ]?based|flaky)\b/.test(t)?"testing-qa":/\b(observability|metric|metrics|log|logging|trace|tracing|alert|monitoring|slo)\b/.test(t)?"observability":/\b(product|business|user journey|onboarding|pricing|tenant|customer-facing)\b/.test(t)?"product-business":/\b(docs|documentation|architecture|arquitetura|adr|runbook|decision record)\b/.test(t)?"docs-architecture":"generic"}function ae(e){const t=e.trim().replace(/\s+/g," ");if(Buffer.byteLength(t,"utf8")<=Ae)return t;const n=t.match(/(?:^|\s)([\w.-]+(?:\/[\w.@-]+)+(?:\.[A-Za-z0-9]+)?)/)?.[1],o=t.slice(0,220).replace(/\s+\S*$/,"").trim();return n?`${o}\u2026 See ${n} for details.`:`${o}\u2026 Details omitted from always-loaded memory; keep source content in repository docs.`}function Ue(e){y(e);const t=_e(e),n=De(e);return{kind:t,layer:n,sectionTitle:se[t],summary:ae(e),reasonCode:`memory_update_${t.replace("-","_")}`}}function G(e){const t=new Set,n=[];for(const o of e){const s=Ue(o),r=`${s.kind}:${s.summary.toLowerCase()}`;t.has(r)||(t.add(r),n.push(s))}return n}function y(e){if(Le.test(e))throw new Error("Project memory input violates IP boundary guardrails.")}function ie(e,t){const n=(e??"").split(`
-`),o=t.split(`
-`),s=[],r=Math.max(n.length,o.length);for(let c=0;c<r;c++){const u=n[c],l=o[c];if(u!==l&&(u!==void 0&&s.push(`- ${u}`),l!==void 0&&s.push(`+ ${l}`),s.length>=80)){s.push("\u2026 diff truncated; inspect repository diff for full context.");break}}const a=s.join(`
-`);return y(a),a}function H(e){y(e.path),y(e.title),y(e.purpose),y(e.suggestedUsage)}function ce(e,t,n){e.forEach(y),t.forEach(H),n?.universalLaws?.forEach(y),n?.businessContext?.forEach(y),n?.activeContext?.forEach(y),n?.repositoryMap?.forEach(y),n?.environmentPractices?.forEach(y),n?.platformMemoryContract?.forEach(y),n?.maintenanceRules?.forEach(y),n?.heuristics?.forEach(y),n?.importantReferences?.forEach(H),n?.architectureReferences?.forEach(H)}function ue(e){return[Ne(e),"","This file contains compact, always-loaded project memory. Keep detailed architecture in referenced docs.",""].join(`
-`)}function de(e,t,n,o){ce(t,n,o);const s=w([...Me,...o?.universalLaws??[]]),r=w([...o?.activeContext??[],...t.map(ae)]),a=G(t),c=w(o?.businessContext??["Product/business context was not explicitly documented during bootstrap; treat conclusions as repository-inferred until a human updates this section."]),u=w(o?.repositoryMap??["Source, tests, package/build files, docs, CI, and runtime manifests are the permitted bootstrap sources for repository orientation."]),l=w(o?.environmentPractices??["Use `.env.example` for configuration shape only; do not read real environment files or credential-bearing files into always-loaded memory."]),i=w(o?.platformMemoryContract??["Semantic platform memory file must resolve to NEOCORTEX.md through a symlink; do not replace it with an unrelated wrapper or copied frontmatter.","Platform wrapper/frontmatter must be preserved via split/include/managed block while the semantic memory payload remains symlink-backed by NEOCORTEX.md."]),d=w(o?.maintenanceRules??["Keep NEOCORTEX.md deterministic, compact, objective, and direct; store only summaries, indexes, and links to detailed docs.","Do not copy protected prompt bodies, proprietary wrappers, server-side internals, customer data, license keys, or long document bodies into always-loaded memory."]),m=je([...o?.importantReferences??[],...o?.architectureReferences??[],...n]),h=w([...Ie,...o?.heuristics??[]]),k=s.map(f=>`- ${f}`),R=r.length>0?r.map(f=>`- ${f}`):["- No active project notes recorded."],_=m.length>0?Pe(m):"No architecture references discovered.",D=a.length>0?Object.entries(se).flatMap(([f,x])=>{const S=a.filter(P=>P.kind===f);return S.length>0?[`### ${x}`,...S.map(P=>`- [${P.reasonCode}] ${P.summary} (layer: ${P.layer})`)]:[]}):["- No durable change feedback recorded."];return[$(e),"## Universal Project Laws",...k,"","## Business/Product Context",...c.map(f=>`- ${f}`),"","## Active Context",...R,"","## Durable Change Feedback",...D,"","## Architecture References",_,"","## Repository Map",...u.map(f=>`- ${f}`),"","## Environment/Container/Production/Security/Dev Practices",...l.map(f=>`- ${f}`),"","## Platform Memory Contract",...i.map(f=>`- ${f}`),`- NEOCORTEX.md is the canonical project memory source for every platform target; run \`${e.bidirectionalReference.feedbackTrigger}\` when durable context discovered in a platform wrapper should be fed back into canonical memory.`,"","## Maintenance Rules",...d.map(f=>`- ${f}`),"","## Architecture Heuristics",...h.map(f=>`- ${f}`),L(e)].join(`
-`)}const le=["docs/architecture","docs/arquitetura-software"],Be=["README.md","readme.md","architecture.md","docs/architecture.md"],qe=["package.json","pnpm-lock.yaml","package-lock.json","yarn.lock","tsconfig.json","vite.config.ts","turbo.json"],We=["Dockerfile","docker-compose.yml","compose.yml",".env.example","fly.toml"],Fe=["AGENTS.md","CLAUDE.md","GEMINI.md",".opencode/AGENTS.md",".cursor/rules/neocortex.mdc"];function me(e,t,n=24e3){const o=p(e,t);try{if(!g(o)||C(o).isDirectory())return;const s=E(o,"utf8");return s.length<=n?s:s.slice(0,n)}catch{return}}function fe(e,t,n){if(!n)return`${e}.bak-${t}`;const o=Ce(n),s=C(o);if(!s.isDirectory()||s.isSymbolicLink()||s.uid!==process.getuid?.()||(s.mode&63)!==0||we(o)!==o)throw new Error("project-memory-backup-directory-unsafe");return p(o,`${Re(e)}.bak-${t}`)}function Y(e,t,n){O(I(e),{recursive:!0});const o=U(),s=`${e}.tmp-${o}`,r=g(e)?fe(e,o,n):void 0;try{return q(s,t,{encoding:"utf8",flag:"wx",mode:384}),r!==void 0&&j(e,r,V.COPYFILE_EXCL),te(s,e),r}catch(a){if(N(s,{force:!0}),r!==void 0&&g(r))try{j(r,e)}catch{}throw a}}function K(e){return Array.from(new Set(G(e).map(t=>t.reasonCode)))}function T(e,t){try{return g(p(e,t))}catch{return!1}}function Xe(e,t){try{return Q(p(e,t),{withFileTypes:!0}).filter(n=>!n.name.startsWith(".")&&!n.name.toLowerCase().includes("secret")).sort((n,o)=>n.name.localeCompare(o.name)).slice(0,8).map(n=>`${t}/${n.name}${n.isDirectory()?"/":""}`)}catch{return[]}}function pe(e,t,n=16){try{const o=Q(p(e,t),{withFileTypes:!0}).filter(r=>!r.name.startsWith(".")&&!r.name.startsWith("_")).sort((r,a)=>r.name.localeCompare(a.name)),s=[];for(const r of o){const a=`${t}/${r.name}`;if(r.isDirectory()?s.push(...pe(e,a,n-s.length)):/\.(md|markdown)$/i.test(r.name)&&s.push(a),s.length>=n)break}return s}catch{return[]}}function ze(e,t){const n=t.match(/^#\s+(.+?)\s*$/m)?.[1]?.trim();return n?n.replace(/[`*_#]/g,""):e.split("/").pop()?.replace(/\.(md|markdown)$/i,"").replace(/[-_]+/g," ")??e}function Ge(e,t){const n=/\b(stale|deprecated|outdated|incerto|uncertain)\b/i.test(`${e}
-${t.slice(0,2e3)}`),o=t.replace(/^---[\s\S]*?---\s*/,"").split(/\n{2,}/).map(r=>r.replace(/^#+\s+.+$/gm,"").replace(/[`*_>#]/g,"").replace(/\s+/g," ").trim()).find(r=>r.length>0&&!r.startsWith("|"));return`${n?"[stale/uncertain evidence] ":""}${(o??"Architecture reference for this project.").slice(0,180)}`}function He(e){const t=e.toLowerCase();return/deploy|infra|docker|production|runbook/.test(t)?"Use before changing deployment, runtime, containers, or production operations.":/security|auth|compliance/.test(t)?"Use before changing auth, compliance, or security-sensitive behavior.":/api|contract|state|schema/.test(t)?"Use before changing contracts, APIs, schemas, or persisted state.":"Use before implementation in this area; verify freshness when marked stale or uncertain."}function ye(e){const t=qe.filter(i=>T(e,i)),n=We.filter(i=>T(e,i)),o=Fe.filter(i=>T(e,i)),s=["packages","src","apps","tests","__tests__"].filter(i=>T(e,i)),a=[...le.flatMap(i=>pe(e,i)),...Be.filter(i=>T(e,i))].slice(0,24).flatMap(i=>{const d=me(e,i,48e3);return d?[{path:i,title:ze(i,d),purpose:Ge(i,d),suggestedUsage:He(i),source:le.some(m=>i.startsWith(`${m}/`))?"architecture-root":"fallback-file"}]:[]}),c=me(e,"package.json"),u=c?.match(/"name"\s*:\s*"([^"]+)"/)?.[1],l=[...c?.matchAll(/"(test|build|lint|typecheck|dev)"\s*:/g)??[]].map(i=>i[1]);return{universalLaws:["Bootstrap canonical memory before creating or repairing platform memory wrappers when NEOCORTEX.md is absent.","Use only permitted repository sources for bootstrap: package/build files, architecture docs, README/deploy docs, .env.example, runtime manifests, CI, source/test layout, and platform memory wrappers."],businessContext:[u?`Repository package name: ${u}.`:"Repository product name was not declared in package metadata.","Business/product conclusions are bootstrap-inferred and must be refined from canonical docs or human input."],activeContext:[`Bootstrap scanned ${t.length} package/build files, ${a.length} architecture/readme docs, ${n.length} runtime/config templates, and ${o.length} platform memory wrappers.`,l.length>0?`Detected quality scripts: ${l.sort().join(", ")}.`:"No standard quality scripts were detected in package metadata."],repositoryMap:[t.length>0?`Package/build files: ${t.join(", ")}.`:"No package/build files detected in permitted bootstrap set.",s.length>0?`Source/test roots: ${s.flatMap(i=>Xe(e,i)).slice(0,16).join(", ")}.`:"Source/test roots were not detected in standard locations.",o.length>0?`Platform memory/wrappers: ${o.join(", ")}.`:"No platform memory wrappers detected before bootstrap."],environmentPractices:[n.length>0?`Runtime/config templates: ${n.join(", ")}.`:"No Docker/compose/.env.example/runtime manifest detected in permitted bootstrap set.","Read `.env.example` only for configuration shape; never ingest real .env files, credentials, customer data, or license keys into memory.","Run repository quality scripts before commit and keep CI/deploy evidence referenced by path or URL rather than copied verbatim."],platformMemoryContract:["Semantic platform memory file must resolve to NEOCORTEX.md through a symlink; do not replace it with an unrelated wrapper or copied frontmatter.","Preserve wrappers/frontmatter via split/include/managed block while the semantic memory payload remains symlink-backed by NEOCORTEX.md."],maintenanceRules:["Generated memory must be deterministic, objective, direct, compact, and inside the target always-loaded context budget.","Cite long architecture docs by path with usage guidance; mark stale or uncertain docs when repository evidence indicates that status.","Do not copy protected prompt bodies, proprietary wrappers, server internals, secrets, customer data, license keys, or complete long documents."],architectureReferences:a,heuristics:["Before processing a story, consult the cited Architecture References whose path or suggested usage intersects the change.","When a referenced doc is marked stale/uncertain, validate against current package/runtime/source evidence before relying on it."]}}function J(e,t,n){const o=$(t),s=L(t),r=e.indexOf(o),a=e.indexOf(s);if(r>=0&&a>=r){const u=a+s.length;return`${e.slice(0,r)}${n}${e.slice(u)}`}const c=e.endsWith(`
-`)?`
-`:`
-
-`;return`${e}${c}${n}
-`}function Ye(e){return e.endsWith(".mdc")?`---
-description: Neocortex project memory
-alwaysApply: true
----
-
-`:e.endsWith(".toml")?`[agent]
-name = "neocortex"
-description = "Neocortex project memory wrapper"
-
-`:e.endsWith(".agent.md")?`---
-name: neocortex
-description: Neocortex project memory wrapper
----
-
-`:""}function be(e,t){const n=I(p(e,t)),o=p(e,b),s=Se(n,o);return s.length>0?s:b}function v(e,t){return!!(e.targetId==="canonical"||e.requiresWrapperPreservation||e.linkRequirement.requiresWrapperPreservation||e.linkRequirement.wrapperAllowed||t==="AGENTS.md"||t.includes("/agents/")||t.includes("/skills/")||t.endsWith(".toml")||t.endsWith(".mdc")||t.endsWith(".agent.md")||t.endsWith(".instructions.md"))}function Ke(e){return e.linkRequirement.symlinkBacked&&e.linkRequirement.semanticFileRequired}function Z(e){return/EPERM|EACCES|operation not permitted|permission/i.test(e)?"EPERM: symlink permission denied":/ENOSYS|ENOTSUP|EOPNOTSUPP|not supported/i.test(e)?"symlink filesystem unsupported":"symlink capability unavailable"}function he(e,t,n,o,s=!1){if(o!==void 0)return o;const r=Ke(t);if(!r)return{os:M(),supported:!1,permission:"unknown",filesystem:"unknown",targetPolicy:t.linkRequirement.policy,targetPolicyAllowsSymlink:r,requiresWrapperPreservation:v(t,n),reason:`target policy ${t.linkRequirement.policy} does not allow semantic symlink orchestration`};if(s)return{os:M(),supported:!0,permission:"unknown",filesystem:"unknown",targetPolicy:t.linkRequirement.policy,targetPolicyAllowsSymlink:r,requiresWrapperPreservation:v(t,n),reason:"dry-run does not probe filesystem symlink support"};const a=p(e,".neocortex","tmp"),c=U(),u=p(a,`symlink-capability-source-${c}`),l=p(a,`symlink-capability-link-${c}`);try{O(a,{recursive:!0}),q(u,"probe",{encoding:"utf8",flag:"wx",mode:384}),B(u,l);const i=C(l).isSymbolicLink()&&Ee(l).isFile();return{os:M(),supported:i,permission:i?"ok":"unknown",filesystem:i?"supports-symlink":"no-symlink-support",targetPolicy:t.linkRequirement.policy,targetPolicyAllowsSymlink:r,requiresWrapperPreservation:v(t,n),reason:i?void 0:"filesystem probe did not create a resolvable symbolic link"}}catch(i){const d=i instanceof Error?i.message:String(i),m=/EPERM|EACCES|operation not permitted|permission/i.test(d);return{os:M(),supported:!1,permission:m?"denied":"unknown",filesystem:"no-symlink-support",targetPolicy:t.linkRequirement.policy,targetPolicyAllowsSymlink:r,requiresWrapperPreservation:v(t,n),reason:Z(d)}}finally{N(l,{force:!0}),N(u,{force:!0})}}function Je(e,t,n,o){const s=be(o,t),r=n??`${Ye(t)}# ${e.platformName} Neocortex Memory Wrapper
-
-`,a=[$(e),"## Canonical Project Memory Source","",`This platform wrapper preserves host-specific frontmatter/instructions while resolving project memory to \`${s}\`.`,"",`- Canonical source: \`${b}\``,`- Symlink-backed/source-of-truth file: \`${s}\``,`- Feedback loop: read \`${s}\` for shared context and run \`${e.bidirectionalReference.feedbackTrigger}\` when durable platform findings should update \`${b}\`.`,"- Human-authored content outside this managed block is preserved byte-for-byte.",L(e)].join(`
-`);return J(r,e,a)}function ge(e,t,n,o,s,r=!1){const a=p(e,t),c=Z(s),l=`${["[NEOCORTEX COMPATIBILITY REMEDIATION]","Materialized project memory fallback because semantic symlink orchestration failed.","This is not product mode; repair host permissions/filesystem support and restore the symlink to NEOCORTEX.md.","WARNING: materialized fallback is remediation debt, not a silent mode; run *update-memory for durable context and repair this file back to canonical NEOCORTEX.md resolution.",`Fallback reason: ${c}`,""].join(`
-`)}${n}`,d=(g(a)?E(a,"utf8"):void 0)!==l;return d&&!r&&(g(a)&&C(a).isSymbolicLink()&&re(a),Y(a,l)),{filePath:a,relativeFile:t,changed:d,content:l,mode:"compatibility-materialized-fallback",canonicalSource:b,symlinkCapability:o,fallbackReason:c,remediationDebt:`Repair ${t} so it is a symlink to ${b}; fallback is compatibility remediation only.`}}function Ze(e,t,n,o,s,r=!1){const a=p(e,t),c=be(e,t);r||O(I(a),{recursive:!0});const u=he(e,n,t,s,r);if(!u.supported)return ge(e,t,o,u,u.reason??"symlink capability detection reported unsupported host",r);if(r){let i=!0;try{i=!(g(a)&&C(a).isSymbolicLink()&&ee(a)===c)}catch{i=!0}return{filePath:a,relativeFile:t,changed:i,content:o,mode:"semantic-symlink",canonicalSource:b,symlinkCapability:u}}let l=!1;try{return g(a)?C(a).isSymbolicLink()&&ee(a)===c?l=!1:(re(a),B(c,a),l=!0):(B(c,a),l=!0),{filePath:a,relativeFile:t,changed:l,content:E(a,"utf8"),mode:"semantic-symlink",canonicalSource:b,symlinkCapability:u}}catch(i){const d=i instanceof Error?i.message:String(i),m=Z(d);return ge(e,t,o,{...u,supported:!1,permission:/EPERM|EACCES|operation not permitted|permission/i.test(d)?"denied":u.permission,filesystem:"no-symlink-support",reason:m},m,r)}}function Ve(e,t,n,o,s){const r=u=>u.split(`
-`).length<=e.budget.maxLines&&Buffer.byteLength(u,"utf8")<=e.budget.maxBytes;if(r(t))return t;const a=de(e,n.slice(0,8),o.slice(0,12),s),c=J(t.includes($(e))?t:ue(e),e,a);return r(c)?c:c.slice(0,e.budget.maxBytes)}function ke(e,t,n=[],o=[],s){const r=t??ue(e),a=de(e,n,o,s),c=J(r,e,a);return Ve(e,c,n,o,s)}function Qe(e){const t=W(e.targetId),n=e.fs??Oe(e.backupDirectory),o=n.join(e.projectRoot,t.primaryFile);if(e.fs===void 0&&t.targetId==="canonical"&&F(e.projectRoot,[b]),t.targetId!=="canonical"&&e.fs===void 0){const u=et(e).files.find(l=>l.relativeFile===t.primaryFile);if(u===void 0)throw new Error(`Primary project memory file was not written for ${t.targetId}.`);return{filePath:u.filePath,changed:u.changed,content:u.content}}const s=n.readFile(o),r=e.bootstrapArchitecture??(e.fs===void 0&&t.targetId==="canonical"&&s===void 0?ye(e.projectRoot):void 0),a=t.targetId==="canonical"&&s!==void 0?ne(e)?oe(t,s,e):s:ke(t,s,e.memoryNotes,e.architectureReferences,r);if(s===a)return{filePath:o,changed:!1,content:a};const c=e.dryRun?void 0:n.writeFileAtomic(o,a);return{filePath:o,changed:!0,content:a,safeDiff:ie(s,a),backupPath:c?.backupPath,reasonCodes:K(e.memoryNotes??[])}}function ct(e){return Qe({...e,targetId:"canonical"})}function et(e){if(e.fs!==void 0)throw new Error("writeProjectMemoryTargetFiles requires the node filesystem to manage symlinks safely.");const t=W(e.targetId),n=W("canonical");t.secondaryFiles.some(d=>d===null||d.scope!=="project"&&d.scope!=="user"||!Te(d.path))&&$e("invalid");const o=Array.from(new Set([t.primaryFile,...t.targetId==="canonical"?[]:t.secondaryFiles.filter(d=>d.scope==="project").map(d=>d.path)]));F(e.projectRoot,[b,...o,".neocortex/tmp"]);const s=p(e.projectRoot,b),r=g(s)?E(s,"utf8"):void 0,a=e.bootstrapArchitecture??(r===void 0?ye(e.projectRoot):void 0),c=r!==void 0?ne(e)?oe(n,r,e):r:ke(n,r,e.memoryNotes,e.architectureReferences,a),u=!g(s)||E(s,"utf8")!==c;let l;if(u&&!e.dryRun&&(l=Y(s,c,e.backupDirectory)),t.targetId==="canonical")return{targetId:t.targetId,canonicalFilePath:s,changed:u,files:[{filePath:s,relativeFile:b,changed:u,content:c,mode:"canonical",canonicalSource:b,safeDiff:ie(r,c),backupPath:l,reasonCodes:K(e.memoryNotes??[])}]};const i=o.map(d=>{if(F(e.projectRoot,[d,".neocortex/tmp"]),!v(t,d))return Ze(e.projectRoot,d,t,c,e.symlinkCapability,e.dryRun);const m=p(e.projectRoot,d),h=g(m)?E(m,"utf8"):void 0,k=Je(t,d,h,e.projectRoot),R=h!==k;return R&&!e.dryRun&&Y(m,k,e.backupDirectory),{filePath:m,relativeFile:d,changed:R,content:k,mode:"managed-wrapper",canonicalSource:b,symlinkCapability:he(e.projectRoot,t,d,e.symlinkCapability,e.dryRun),reasonCodes:K(e.memoryNotes??[])}});return{targetId:t.targetId,canonicalFilePath:s,files:i,changed:u||i.some(d=>d.changed)}}export{it as PROJECT_MEMORY_LAYER_CATEGORIES,ye as bootstrapArchitectureMemory,ke as buildProjectMemoryContent,Ue as classifyProjectMemoryUpdate,Oe as createNodeProjectMemoryFs,ie as createSafeProjectMemoryDiff,v as shouldUseManagedWrapper,ct as writeCanonicalProjectMemory,Qe as writeProjectMemory,et as writeProjectMemoryTargetFiles};
+/**
+ * Project memory writer for platform-specific always-loaded files.
+ *
+ * The writer owns only the NEOCORTEX-MEMORY block. Everything outside that
+ * block is preserved byte-for-byte so users can keep local instructions.
+ */
+import { randomUUID } from 'node:crypto';
+import { constants as fsConstants, existsSync, lstatSync, mkdirSync, copyFileSync, readdirSync, readFileSync, readlinkSync, realpathSync, renameSync, rmSync, statSync, symlinkSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { platform } from 'node:os';
+import { basename, dirname, join, relative, resolve } from 'node:path';
+import { CANONICAL_PROJECT_MEMORY_SOURCE, getProjectMemoryTarget, renderArchitectureReferenceTable, } from './shared-project-memory-types.js';
+import { assertProjectMemoryPaths, invalidProjectMemoryPath, isValidScopedRelativePath } from './project-memory-path-scope.js';
+function hasCanonicalUpdateInput(options) {
+    return (options.memoryNotes?.length ?? 0) > 0 ||
+        (options.architectureReferences?.length ?? 0) > 0 ||
+        options.bootstrapArchitecture !== undefined;
+}
+const REFRESH_UPDATE_START = '<!-- NEOCORTEX-REFRESH-UPDATES-START -->';
+const REFRESH_UPDATE_END = '<!-- NEOCORTEX-REFRESH-UPDATES-END -->';
+function occurrenceCount(content, value) {
+    return content.split(value).length - 1;
+}
+function canonicalRefreshRows(options) {
+    assertSafeProjectMemoryInput(options.memoryNotes ?? [], options.architectureReferences ?? [], options.bootstrapArchitecture);
+    const noteRows = classifyProjectMemoryUpdates(options.memoryNotes ?? [])
+        .map((entry) => `- [${entry.reasonCode}] ${entry.summary} (layer: ${entry.layer})`);
+    const referenceRows = (options.architectureReferences ?? []).map((reference) => `- [architecture-reference] \`${reference.path}\`: ${reference.title}; ${reference.purpose}; use: ${reference.suggestedUsage}`);
+    const bootstrap = options.bootstrapArchitecture;
+    const bootstrapRows = bootstrap === undefined ? [] : [
+        ...(bootstrap.universalLaws ?? []).map((value) => `- [bootstrap-law] ${value}`),
+        ...(bootstrap.businessContext ?? []).map((value) => `- [bootstrap-business] ${value}`),
+        ...(bootstrap.activeContext ?? []).map((value) => `- [bootstrap-context] ${value}`),
+        ...(bootstrap.repositoryMap ?? []).map((value) => `- [bootstrap-repository] ${value}`),
+        ...(bootstrap.environmentPractices ?? []).map((value) => `- [bootstrap-environment] ${value}`),
+        ...(bootstrap.platformMemoryContract ?? []).map((value) => `- [bootstrap-platform] ${value}`),
+        ...(bootstrap.maintenanceRules ?? []).map((value) => `- [bootstrap-maintenance] ${value}`),
+        ...(bootstrap.heuristics ?? []).map((value) => `- [bootstrap-heuristic] ${value}`),
+    ];
+    return uniqueLines([...noteRows, ...referenceRows, ...bootstrapRows]);
+}
+function assertWithinBudgetWithoutTruncation(target, content) {
+    if (content.split('\n').length > target.budget.maxLines ||
+        Buffer.byteLength(content, 'utf8') > target.budget.maxBytes) {
+        throw new Error('Canonical project memory update exceeds its context budget; refusing to truncate existing content.');
+    }
+}
+function mergeCanonicalRefreshUpdate(target, existingContent, options) {
+    const rows = canonicalRefreshRows(options);
+    if (rows.length === 0)
+        return existingContent;
+    const eol = existingContent.includes('\r\n') ? '\r\n' : '\n';
+    const outerStart = markerStart(target);
+    const outerEnd = markerEnd(target);
+    const outerStartCount = occurrenceCount(existingContent, outerStart);
+    const outerEndCount = occurrenceCount(existingContent, outerEnd);
+    if (outerStartCount !== 1 || outerEndCount !== 1 || existingContent.indexOf(outerEnd) < existingContent.indexOf(outerStart)) {
+        throw new Error('Canonical project memory has ambiguous managed-block markers; refusing refresh.');
+    }
+    const innerStartCount = occurrenceCount(existingContent, REFRESH_UPDATE_START);
+    const innerEndCount = occurrenceCount(existingContent, REFRESH_UPDATE_END);
+    if (innerStartCount !== innerEndCount || innerStartCount > 1) {
+        throw new Error('Canonical project memory has ambiguous refresh-update markers; refusing refresh.');
+    }
+    let nextContent;
+    if (innerStartCount === 0) {
+        const outerEndIndex = existingContent.indexOf(outerEnd);
+        const prefix = existingContent.slice(0, outerEndIndex);
+        const block = [
+            REFRESH_UPDATE_START,
+            '## Durable Refresh Updates',
+            ...rows,
+            REFRESH_UPDATE_END,
+            '',
+        ].join(eol);
+        nextContent = `${prefix}${prefix.endsWith(eol) ? '' : eol}${block}${existingContent.slice(outerEndIndex)}`;
+    }
+    else {
+        const innerStartIndex = existingContent.indexOf(REFRESH_UPDATE_START);
+        const innerEndIndex = existingContent.indexOf(REFRESH_UPDATE_END);
+        const outerStartIndex = existingContent.indexOf(outerStart);
+        const outerEndIndex = existingContent.indexOf(outerEnd);
+        if (innerStartIndex < outerStartIndex || innerEndIndex > outerEndIndex || innerEndIndex < innerStartIndex) {
+            throw new Error('Canonical refresh-update block is outside the managed block; refusing refresh.');
+        }
+        const currentBlock = existingContent.slice(innerStartIndex, innerEndIndex);
+        const existingRows = new Set(currentBlock.split(/\r?\n/).map((line) => line.trim().toLowerCase()));
+        const missingRows = rows.filter((row) => !existingRows.has(row.trim().toLowerCase()));
+        if (missingRows.length === 0)
+            return existingContent;
+        const prefix = existingContent.slice(0, innerEndIndex);
+        nextContent = `${prefix}${prefix.endsWith(eol) ? '' : eol}${missingRows.join(eol)}${eol}${existingContent.slice(innerEndIndex)}`;
+    }
+    assertWithinBudgetWithoutTruncation(target, nextContent);
+    return nextContent;
+}
+export function createNodeProjectMemoryFs(backupDirectory) {
+    return {
+        readFile(path) {
+            try {
+                return readFileSync(path, 'utf8');
+            }
+            catch {
+                return undefined;
+            }
+        },
+        writeFileAtomic(path, content) {
+            mkdirSync(dirname(path), { recursive: true });
+            const nonce = randomUUID();
+            const tempPath = `${path}.tmp-${nonce}`;
+            const backupPath = existsSync(path) ? memoryBackupPath(path, nonce, backupDirectory) : undefined;
+            try {
+                writeFileSync(tempPath, content, { encoding: 'utf8', flag: 'wx', mode: 0o600 });
+                if (backupPath !== undefined)
+                    copyFileSync(path, backupPath, fsConstants.COPYFILE_EXCL);
+                renameSync(tempPath, path);
+                return { backupPath };
+            }
+            catch (error) {
+                rmSync(tempPath, { force: true });
+                if (backupPath !== undefined && existsSync(backupPath)) {
+                    try {
+                        copyFileSync(backupPath, path);
+                    }
+                    catch { /* best-effort rollback */ }
+                }
+                throw error;
+            }
+        },
+        join(...parts) {
+            return join(...parts);
+        },
+    };
+}
+function markerStart(target) {
+    return `<!-- ${target.ownedBlockName}-START -->`;
+}
+function markerEnd(target) {
+    return `<!-- ${target.ownedBlockName}-END -->`;
+}
+function uniqueLines(values) {
+    const seen = new Set();
+    const result = [];
+    for (const value of values) {
+        const normalized = value.trim().replace(/\s+/g, ' ');
+        if (normalized.length === 0 || seen.has(normalized.toLowerCase()))
+            continue;
+        seen.add(normalized.toLowerCase());
+        result.push(normalized);
+    }
+    return result;
+}
+function uniqueArchitectureReferences(references) {
+    const seen = new Set();
+    const result = [];
+    for (const reference of references) {
+        if (seen.has(reference.path))
+            continue;
+        seen.add(reference.path);
+        result.push(reference);
+    }
+    return result;
+}
+function templateTitle(target) {
+    switch (target.templateKind) {
+        case 'neocortex-md':
+            return '# NEOCORTEX.md Project Memory';
+        case 'claude-md':
+            return '# CLAUDE.md Project Memory';
+        case 'agents-md':
+            return '# AGENTS.md Project Instructions';
+        case 'gemini-md':
+            return '# GEMINI.md Project Memory';
+        case 'copilot-instructions':
+            return '# GitHub Copilot Repository Instructions';
+        case 'cursor-rule':
+            return '---\ndescription: Neocortex project memory\nalwaysApply: true\n---\n\n# Cursor Project Memory';
+    }
+}
+const DEFAULT_UNIVERSAL_LAWS = [
+    'Keep always-loaded memory compact: laws, active context, and references only.',
+    'Preserve human-authored instructions outside this owned block.',
+    'Prefer repository SSoT docs over duplicating architecture details here.',
+];
+const DEFAULT_ARCHITECTURE_HEURISTICS = [
+    'Consult `docs/architecture/` before changes that affect architecture, contracts, data, security, performance, UX, or infrastructure.',
+    'Reference architecture documents by repository path, such as `docs/architecture/architecture.md`, before changing related implementation.',
+    'Summarize decisions and trade-offs in NEOCORTEX.md; do not paste complete architecture documents into memory.',
+    'Update memory for durable cross-layer changes across skills/agents, frontend, backend, API, DB, schemas, envs, DevOps, cyber security, testing/QA, observability, product, docs, and platform contracts.',
+    'Prioritize compact summaries of durable decisions, public contracts, operational risks, debts, command behavior, and repository paths; skip transient logs, raw payloads, secrets, private prompts, long documents, and duplicated canonical sources.',
+    'Keep platform memory files symlink-backed or include-backed to NEOCORTEX.md when supported.',
+];
+export const PROJECT_MEMORY_LAYER_CATEGORIES = [
+    'skills-agents',
+    'frontend',
+    'backend',
+    'api',
+    'db',
+    'schemas',
+    'envs',
+    'devops',
+    'cyber-security',
+    'testing-qa',
+    'observability',
+    'product-business',
+    'docs-architecture',
+    'platform-memory',
+    'command-behavior',
+    'generic',
+];
+const PROJECT_MEMORY_NOTE_BUDGET_BYTES = 360;
+const CHANGE_KIND_SECTIONS = {
+    feature: 'Features',
+    rule: 'Rules/Policies',
+    flag: 'Flags',
+    route: 'Routes',
+    api: 'APIs/Contracts',
+    'db-schema': 'DB/Schema',
+    architecture: 'Architecture',
+    debt: 'Debts',
+    decision: 'Decisions',
+    generic: 'General Updates',
+};
+const IP_BOUNDARY_PATTERN = /\b(private|proprietary|server[- ]only|system)\s+prompt\b|\b(api[-_ ]?key|license[-_ ]?key|password|authorization|bearer|token|secret)\s*[:=]|\b(ghp_[A-Za-z0-9_]+|sk-[A-Za-z0-9_-]+|xox[baprs]-[A-Za-z0-9-]+)\b|\b(customer|cliente)\s+(payload|record|email|phone)\b|\b(customer|cliente)\s+(data|dados)\s+(payload|record|email|phone)\b|\b(customer|cliente)\s+(data|dados)\s*[:=]|\braw\s+payload\b/i;
+function classifyKind(value) {
+    const text = value.toLowerCase();
+    if (/\b(project memory|canonical memory|memory heuristic|neocortex\.md|\*update-memory)\b/.test(text))
+        return 'decision';
+    if (/\b(feature|capability|funcionalidade|release)\b/.test(text))
+        return 'feature';
+    if (/\b(rule|policy|guardrail|regra|lei|must|never)\b/.test(text))
+        return 'rule';
+    if (/\b(flag|feature[- ]?flag|toggle|env var|environment variable)\b/.test(text))
+        return 'flag';
+    if (/\b(api|contract|schema contract|graphql|rest|rpc|webhook)\b/.test(text))
+        return 'api';
+    if (/\b(db|database|schema|migration|table|column|prisma|sql)\b/.test(text))
+        return 'db-schema';
+    if (/\b(decision|decisão|decisao|accepted|rejected|trade[- ]?off)\b/.test(text))
+        return 'decision';
+    if (/\b(route|endpoint route|url path|pathname)\b|\/(api|admin|portal|v\d+)\//.test(text))
+        return 'route';
+    if (/\b(architecture|arquitetura|adr|topology|infra|boundary)\b/.test(text))
+        return 'architecture';
+    if (/\b(debt|follow[- ]?up|todo|tech[- ]?debt|dívida|divida)\b/.test(text))
+        return 'debt';
+    return 'generic';
+}
+function classifyLayer(value) {
+    const text = value.toLowerCase();
+    if (/\b(neocortex\.md|project memory|canonical memory|memory wrapper|symlink|owned block|memory heuristic)\b/.test(text))
+        return 'platform-memory';
+    if (/\b(command|cli|\*update-memory|\*create-epic|\*arch-plan|workflow behavior)\b/.test(text))
+        return 'command-behavior';
+    if (/\b(skill|agent|subagent|orchestrator|opencode|codex|claude|gemini|cursor)\b/.test(text))
+        return 'skills-agents';
+    if (/\b(frontend|ui|ux|react|component|design[- ]?system|css|accessibility|a11y)\b/.test(text))
+        return 'frontend';
+    if (/\b(backend|server|service|worker|job|queue)\b/.test(text))
+        return 'backend';
+    if (/\b(api|endpoint|rest|graphql|rpc|webhook|contract)\b/.test(text))
+        return 'api';
+    if (/\b(db|database|table|column|migration|sql|prisma)\b/.test(text))
+        return 'db';
+    if (/\b(schema|schemas|zod|json schema|protobuf|openapi)\b/.test(text))
+        return 'schemas';
+    if (/\b(env|environment|\.env\.example|config|configuration|feature[- ]?flag)\b/.test(text))
+        return 'envs';
+    if (/\b(devops|deploy|deployment|ci|cd|docker|container|kubernetes|infra|terraform|rollback)\b/.test(text))
+        return 'devops';
+    if (/\b(security|cyber|auth|authorization|permission|compliance|vulnerability|secret|token redaction)\b/.test(text))
+        return 'cyber-security';
+    if (/\b(test|testing|qa|e2e|unit|integration|snapshot|property[- ]?based|flaky)\b/.test(text))
+        return 'testing-qa';
+    if (/\b(observability|metric|metrics|log|logging|trace|tracing|alert|monitoring|slo)\b/.test(text))
+        return 'observability';
+    if (/\b(product|business|user journey|onboarding|pricing|tenant|customer-facing)\b/.test(text))
+        return 'product-business';
+    if (/\b(docs|documentation|architecture|arquitetura|adr|runbook|decision record)\b/.test(text))
+        return 'docs-architecture';
+    return 'generic';
+}
+function compactMemoryNote(value) {
+    const normalized = value.trim().replace(/\s+/g, ' ');
+    if (Buffer.byteLength(normalized, 'utf8') <= PROJECT_MEMORY_NOTE_BUDGET_BYTES)
+        return normalized;
+    const pathReference = normalized.match(/(?:^|\s)([\w.-]+(?:\/[\w.@-]+)+(?:\.[A-Za-z0-9]+)?)/)?.[1];
+    const summary = normalized.slice(0, 220).replace(/\s+\S*$/, '').trim();
+    return pathReference
+        ? `${summary}… See ${pathReference} for details.`
+        : `${summary}… Details omitted from always-loaded memory; keep source content in repository docs.`;
+}
+export function classifyProjectMemoryUpdate(value) {
+    assertSafeMemoryText(value);
+    const kind = classifyKind(value);
+    const layer = classifyLayer(value);
+    return {
+        kind,
+        layer,
+        sectionTitle: CHANGE_KIND_SECTIONS[kind],
+        summary: compactMemoryNote(value),
+        reasonCode: `memory_update_${kind.replace('-', '_')}`,
+    };
+}
+function classifyProjectMemoryUpdates(values) {
+    const seen = new Set();
+    const result = [];
+    for (const value of values) {
+        const classified = classifyProjectMemoryUpdate(value);
+        const key = `${classified.kind}:${classified.summary.toLowerCase()}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        result.push(classified);
+    }
+    return result;
+}
+function assertSafeMemoryText(value) {
+    if (IP_BOUNDARY_PATTERN.test(value)) {
+        throw new Error('Project memory input violates IP boundary guardrails.');
+    }
+}
+export function createSafeProjectMemoryDiff(before, after) {
+    const beforeLines = (before ?? '').split('\n');
+    const afterLines = after.split('\n');
+    const rows = [];
+    const max = Math.max(beforeLines.length, afterLines.length);
+    for (let index = 0; index < max; index++) {
+        const oldLine = beforeLines[index];
+        const newLine = afterLines[index];
+        if (oldLine === newLine)
+            continue;
+        if (oldLine !== undefined)
+            rows.push(`- ${oldLine}`);
+        if (newLine !== undefined)
+            rows.push(`+ ${newLine}`);
+        if (rows.length >= 80) {
+            rows.push('… diff truncated; inspect repository diff for full context.');
+            break;
+        }
+    }
+    const diff = rows.join('\n');
+    assertSafeMemoryText(diff);
+    return diff;
+}
+function assertSafeArchitectureReference(reference) {
+    assertSafeMemoryText(reference.path);
+    assertSafeMemoryText(reference.title);
+    assertSafeMemoryText(reference.purpose);
+    assertSafeMemoryText(reference.suggestedUsage);
+}
+function assertSafeProjectMemoryInput(memoryNotes, architectureReferences, bootstrapArchitecture) {
+    memoryNotes.forEach(assertSafeMemoryText);
+    architectureReferences.forEach(assertSafeArchitectureReference);
+    bootstrapArchitecture?.universalLaws?.forEach(assertSafeMemoryText);
+    bootstrapArchitecture?.businessContext?.forEach(assertSafeMemoryText);
+    bootstrapArchitecture?.activeContext?.forEach(assertSafeMemoryText);
+    bootstrapArchitecture?.repositoryMap?.forEach(assertSafeMemoryText);
+    bootstrapArchitecture?.environmentPractices?.forEach(assertSafeMemoryText);
+    bootstrapArchitecture?.platformMemoryContract?.forEach(assertSafeMemoryText);
+    bootstrapArchitecture?.maintenanceRules?.forEach(assertSafeMemoryText);
+    bootstrapArchitecture?.heuristics?.forEach(assertSafeMemoryText);
+    bootstrapArchitecture?.importantReferences?.forEach(assertSafeArchitectureReference);
+    bootstrapArchitecture?.architectureReferences?.forEach(assertSafeArchitectureReference);
+}
+function buildTemplate(target) {
+    return [
+        templateTitle(target),
+        '',
+        'This file contains compact, always-loaded project memory. Keep detailed architecture in referenced docs.',
+        '',
+    ].join('\n');
+}
+function buildOwnedBlock(target, memoryNotes, architectureReferences, bootstrapArchitecture) {
+    assertSafeProjectMemoryInput(memoryNotes, architectureReferences, bootstrapArchitecture);
+    const laws = uniqueLines([
+        ...DEFAULT_UNIVERSAL_LAWS,
+        ...(bootstrapArchitecture?.universalLaws ?? []),
+    ]);
+    const notes = uniqueLines([
+        ...(bootstrapArchitecture?.activeContext ?? []),
+        ...memoryNotes.map(compactMemoryNote),
+    ]);
+    const classifiedUpdates = classifyProjectMemoryUpdates(memoryNotes);
+    const businessContext = uniqueLines(bootstrapArchitecture?.businessContext ?? [
+        'Product/business context was not explicitly documented during bootstrap; treat conclusions as repository-inferred until a human updates this section.',
+    ]);
+    const repositoryMap = uniqueLines(bootstrapArchitecture?.repositoryMap ?? [
+        'Source, tests, package/build files, docs, CI, and runtime manifests are the permitted bootstrap sources for repository orientation.',
+    ]);
+    const environmentPractices = uniqueLines(bootstrapArchitecture?.environmentPractices ?? [
+        'Use `.env.example` for configuration shape only; do not read real environment files or credential-bearing files into always-loaded memory.',
+    ]);
+    const platformMemoryContract = uniqueLines(bootstrapArchitecture?.platformMemoryContract ?? [
+        'Semantic platform memory file must resolve to NEOCORTEX.md through a symlink; do not replace it with an unrelated wrapper or copied frontmatter.',
+        'Platform wrapper/frontmatter must be preserved via split/include/managed block while the semantic memory payload remains symlink-backed by NEOCORTEX.md.',
+    ]);
+    const maintenanceRules = uniqueLines(bootstrapArchitecture?.maintenanceRules ?? [
+        'Keep NEOCORTEX.md deterministic, compact, objective, and direct; store only summaries, indexes, and links to detailed docs.',
+        'Do not copy protected prompt bodies, proprietary wrappers, server-side internals, customer data, license keys, or long document bodies into always-loaded memory.',
+    ]);
+    const references = uniqueArchitectureReferences([
+        ...(bootstrapArchitecture?.importantReferences ?? []),
+        ...(bootstrapArchitecture?.architectureReferences ?? []),
+        ...architectureReferences,
+    ]);
+    const heuristics = uniqueLines([
+        ...DEFAULT_ARCHITECTURE_HEURISTICS,
+        ...(bootstrapArchitecture?.heuristics ?? []),
+    ]);
+    const lawRows = laws.map((law) => `- ${law}`);
+    const noteRows = notes.length > 0
+        ? notes.map((note) => `- ${note}`)
+        : ['- No active project notes recorded.'];
+    const referenceSection = references.length > 0
+        ? renderArchitectureReferenceTable(references)
+        : 'No architecture references discovered.';
+    const feedbackRows = classifiedUpdates.length > 0
+        ? Object.entries(CHANGE_KIND_SECTIONS)
+            .flatMap(([kind, sectionTitle]) => {
+            const updates = classifiedUpdates.filter((entry) => entry.kind === kind);
+            return updates.length > 0
+                ? [`### ${sectionTitle}`, ...updates.map((entry) => `- [${entry.reasonCode}] ${entry.summary} (layer: ${entry.layer})`)]
+                : [];
+        })
+        : ['- No durable change feedback recorded.'];
+    return [
+        markerStart(target),
+        '## Universal Project Laws',
+        ...lawRows,
+        '',
+        '## Business/Product Context',
+        ...businessContext.map((line) => `- ${line}`),
+        '',
+        '## Active Context',
+        ...noteRows,
+        '',
+        '## Durable Change Feedback',
+        ...feedbackRows,
+        '',
+        '## Architecture References',
+        referenceSection,
+        '',
+        '## Repository Map',
+        ...repositoryMap.map((line) => `- ${line}`),
+        '',
+        '## Environment/Container/Production/Security/Dev Practices',
+        ...environmentPractices.map((line) => `- ${line}`),
+        '',
+        '## Platform Memory Contract',
+        ...platformMemoryContract.map((line) => `- ${line}`),
+        `- NEOCORTEX.md is the canonical project memory source for every platform target; run \`${target.bidirectionalReference.feedbackTrigger}\` when durable context discovered in a platform wrapper should be fed back into canonical memory.`,
+        '',
+        '## Maintenance Rules',
+        ...maintenanceRules.map((line) => `- ${line}`),
+        '',
+        '## Architecture Heuristics',
+        ...heuristics.map((heuristic) => `- ${heuristic}`),
+        markerEnd(target),
+    ].join('\n');
+}
+const BOOTSTRAP_ARCHITECTURE_ROOTS = ['docs/architecture', 'docs/arquitetura-software'];
+const BOOTSTRAP_FALLBACK_DOCS = ['README.md', 'readme.md', 'architecture.md', 'docs/architecture.md'];
+const BOOTSTRAP_PACKAGE_FILES = ['package.json', 'pnpm-lock.yaml', 'package-lock.json', 'yarn.lock', 'tsconfig.json', 'vite.config.ts', 'turbo.json'];
+const BOOTSTRAP_RUNTIME_FILES = ['Dockerfile', 'docker-compose.yml', 'compose.yml', '.env.example', 'fly.toml'];
+const BOOTSTRAP_PLATFORM_FILES = ['AGENTS.md', 'CLAUDE.md', 'GEMINI.md', '.opencode/AGENTS.md', '.cursor/rules/neocortex.mdc'];
+function readOptional(projectRoot, relativePath, maxBytes = 24_000) {
+    const fullPath = join(projectRoot, relativePath);
+    try {
+        if (!existsSync(fullPath) || lstatSync(fullPath).isDirectory())
+            return undefined;
+        const content = readFileSync(fullPath, 'utf8');
+        return content.length <= maxBytes ? content : content.slice(0, maxBytes);
+    }
+    catch {
+        return undefined;
+    }
+}
+function memoryBackupPath(path, nonce, backupDirectory) {
+    if (!backupDirectory)
+        return `${path}.bak-${nonce}`;
+    const directory = resolve(backupDirectory), info = lstatSync(directory);
+    if (!info.isDirectory() || info.isSymbolicLink() || info.uid !== process.getuid?.()
+        || (info.mode & 0o077) !== 0 || realpathSync(directory) !== directory)
+        throw new Error('project-memory-backup-directory-unsafe');
+    return join(directory, `${basename(path)}.bak-${nonce}`);
+}
+function writeFileWithBackup(path, content, backupDirectory) {
+    mkdirSync(dirname(path), { recursive: true });
+    const nonce = randomUUID();
+    const tempPath = `${path}.tmp-${nonce}`;
+    const backupPath = existsSync(path) ? memoryBackupPath(path, nonce, backupDirectory) : undefined;
+    try {
+        writeFileSync(tempPath, content, { encoding: 'utf8', flag: 'wx', mode: 0o600 });
+        if (backupPath !== undefined)
+            copyFileSync(path, backupPath, fsConstants.COPYFILE_EXCL);
+        renameSync(tempPath, path);
+        return backupPath;
+    }
+    catch (error) {
+        rmSync(tempPath, { force: true });
+        if (backupPath !== undefined && existsSync(backupPath)) {
+            try {
+                copyFileSync(backupPath, path);
+            }
+            catch { /* best-effort rollback */ }
+        }
+        throw error;
+    }
+}
+function reasonCodesForNotes(memoryNotes) {
+    return Array.from(new Set(classifyProjectMemoryUpdates(memoryNotes).map((entry) => entry.reasonCode)));
+}
+function safeExists(projectRoot, relativePath) {
+    try {
+        return existsSync(join(projectRoot, relativePath));
+    }
+    catch {
+        return false;
+    }
+}
+function listSourceChildren(projectRoot, relativePath) {
+    try {
+        return readdirSync(join(projectRoot, relativePath), { withFileTypes: true })
+            .filter((entry) => !entry.name.startsWith('.') && !entry.name.toLowerCase().includes('secret'))
+            .sort((a, b) => a.name.localeCompare(b.name))
+            .slice(0, 8)
+            .map((entry) => `${relativePath}/${entry.name}${entry.isDirectory() ? '/' : ''}`);
+    }
+    catch {
+        return [];
+    }
+}
+function collectMarkdownDocs(projectRoot, relativeDir, limit = 16) {
+    try {
+        const entries = readdirSync(join(projectRoot, relativeDir), { withFileTypes: true })
+            .filter((entry) => !entry.name.startsWith('.') && !entry.name.startsWith('_'))
+            .sort((a, b) => a.name.localeCompare(b.name));
+        const files = [];
+        for (const entry of entries) {
+            const relativeEntry = `${relativeDir}/${entry.name}`;
+            if (entry.isDirectory()) {
+                files.push(...collectMarkdownDocs(projectRoot, relativeEntry, limit - files.length));
+            }
+            else if (/\.(md|markdown)$/i.test(entry.name)) {
+                files.push(relativeEntry);
+            }
+            if (files.length >= limit)
+                break;
+        }
+        return files;
+    }
+    catch {
+        return [];
+    }
+}
+function extractBootstrapTitle(path, content) {
+    const heading = content.match(/^#\s+(.+?)\s*$/m)?.[1]?.trim();
+    if (heading)
+        return heading.replace(/[`*_#]/g, '');
+    return path.split('/').pop()?.replace(/\.(md|markdown)$/i, '').replace(/[-_]+/g, ' ') ?? path;
+}
+function referencePurpose(path, content) {
+    const stale = /\b(stale|deprecated|outdated|incerto|uncertain)\b/i.test(`${path}\n${content.slice(0, 2_000)}`);
+    const firstParagraph = content
+        .replace(/^---[\s\S]*?---\s*/, '')
+        .split(/\n{2,}/)
+        .map((part) => part.replace(/^#+\s+.+$/gm, '').replace(/[`*_>#]/g, '').replace(/\s+/g, ' ').trim())
+        .find((part) => part.length > 0 && !part.startsWith('|'));
+    const prefix = stale ? '[stale/uncertain evidence] ' : '';
+    return `${prefix}${(firstParagraph ?? 'Architecture reference for this project.').slice(0, 180)}`;
+}
+function bootstrapSuggestedUsage(path) {
+    const lower = path.toLowerCase();
+    if (/deploy|infra|docker|production|runbook/.test(lower))
+        return 'Use before changing deployment, runtime, containers, or production operations.';
+    if (/security|auth|compliance/.test(lower))
+        return 'Use before changing auth, compliance, or security-sensitive behavior.';
+    if (/api|contract|state|schema/.test(lower))
+        return 'Use before changing contracts, APIs, schemas, or persisted state.';
+    return 'Use before implementation in this area; verify freshness when marked stale or uncertain.';
+}
+export function bootstrapArchitectureMemory(projectRoot) {
+    const packageFiles = BOOTSTRAP_PACKAGE_FILES.filter((path) => safeExists(projectRoot, path));
+    const runtimeFiles = BOOTSTRAP_RUNTIME_FILES.filter((path) => safeExists(projectRoot, path));
+    const platformFiles = BOOTSTRAP_PLATFORM_FILES.filter((path) => safeExists(projectRoot, path));
+    const sourceRoots = ['packages', 'src', 'apps', 'tests', '__tests__']
+        .filter((path) => safeExists(projectRoot, path));
+    const docs = [
+        ...BOOTSTRAP_ARCHITECTURE_ROOTS.flatMap((root) => collectMarkdownDocs(projectRoot, root)),
+        ...BOOTSTRAP_FALLBACK_DOCS.filter((path) => safeExists(projectRoot, path)),
+    ];
+    const references = docs.slice(0, 24).flatMap((path) => {
+        const content = readOptional(projectRoot, path, 48_000);
+        if (!content)
+            return [];
+        return [{
+                path,
+                title: extractBootstrapTitle(path, content),
+                purpose: referencePurpose(path, content),
+                suggestedUsage: bootstrapSuggestedUsage(path),
+                source: BOOTSTRAP_ARCHITECTURE_ROOTS.some((root) => path.startsWith(`${root}/`)) ? 'architecture-root' : 'fallback-file',
+            }];
+    });
+    const packageJson = readOptional(projectRoot, 'package.json');
+    const packageName = packageJson?.match(/"name"\s*:\s*"([^"]+)"/)?.[1];
+    const scripts = [...(packageJson?.matchAll(/"(test|build|lint|typecheck|dev)"\s*:/g) ?? [])].map((match) => match[1]);
+    return {
+        universalLaws: [
+            'Bootstrap canonical memory before creating or repairing platform memory wrappers when NEOCORTEX.md is absent.',
+            'Use only permitted repository sources for bootstrap: package/build files, architecture docs, README/deploy docs, .env.example, runtime manifests, CI, source/test layout, and platform memory wrappers.',
+        ],
+        businessContext: [
+            packageName ? `Repository package name: ${packageName}.` : 'Repository product name was not declared in package metadata.',
+            'Business/product conclusions are bootstrap-inferred and must be refined from canonical docs or human input.',
+        ],
+        activeContext: [
+            `Bootstrap scanned ${packageFiles.length} package/build files, ${references.length} architecture/readme docs, ${runtimeFiles.length} runtime/config templates, and ${platformFiles.length} platform memory wrappers.`,
+            scripts.length > 0 ? `Detected quality scripts: ${scripts.sort().join(', ')}.` : 'No standard quality scripts were detected in package metadata.',
+        ],
+        repositoryMap: [
+            packageFiles.length > 0 ? `Package/build files: ${packageFiles.join(', ')}.` : 'No package/build files detected in permitted bootstrap set.',
+            sourceRoots.length > 0 ? `Source/test roots: ${sourceRoots.flatMap((root) => listSourceChildren(projectRoot, root)).slice(0, 16).join(', ')}.` : 'Source/test roots were not detected in standard locations.',
+            platformFiles.length > 0 ? `Platform memory/wrappers: ${platformFiles.join(', ')}.` : 'No platform memory wrappers detected before bootstrap.',
+        ],
+        environmentPractices: [
+            runtimeFiles.length > 0 ? `Runtime/config templates: ${runtimeFiles.join(', ')}.` : 'No Docker/compose/.env.example/runtime manifest detected in permitted bootstrap set.',
+            'Read `.env.example` only for configuration shape; never ingest real .env files, credentials, customer data, or license keys into memory.',
+            'Run repository quality scripts before commit and keep CI/deploy evidence referenced by path or URL rather than copied verbatim.',
+        ],
+        platformMemoryContract: [
+            'Semantic platform memory file must resolve to NEOCORTEX.md through a symlink; do not replace it with an unrelated wrapper or copied frontmatter.',
+            'Preserve wrappers/frontmatter via split/include/managed block while the semantic memory payload remains symlink-backed by NEOCORTEX.md.',
+        ],
+        maintenanceRules: [
+            'Generated memory must be deterministic, objective, direct, compact, and inside the target always-loaded context budget.',
+            'Cite long architecture docs by path with usage guidance; mark stale or uncertain docs when repository evidence indicates that status.',
+            'Do not copy protected prompt bodies, proprietary wrappers, server internals, secrets, customer data, license keys, or complete long documents.',
+        ],
+        architectureReferences: references,
+        heuristics: [
+            'Before processing a story, consult the cited Architecture References whose path or suggested usage intersects the change.',
+            'When a referenced doc is marked stale/uncertain, validate against current package/runtime/source evidence before relying on it.',
+        ],
+    };
+}
+function replaceOwnedBlock(existingContent, target, ownedBlock) {
+    const start = markerStart(target);
+    const end = markerEnd(target);
+    const startIndex = existingContent.indexOf(start);
+    const endIndex = existingContent.indexOf(end);
+    if (startIndex >= 0 && endIndex >= startIndex) {
+        const afterEnd = endIndex + end.length;
+        return `${existingContent.slice(0, startIndex)}${ownedBlock}${existingContent.slice(afterEnd)}`;
+    }
+    const separator = existingContent.endsWith('\n') ? '\n' : '\n\n';
+    return `${existingContent}${separator}${ownedBlock}\n`;
+}
+function frontmatterForWrapper(relativeFile) {
+    if (relativeFile.endsWith('.mdc')) {
+        return '---\ndescription: Neocortex project memory\nalwaysApply: true\n---\n\n';
+    }
+    if (relativeFile.endsWith('.toml')) {
+        return '[agent]\nname = "neocortex"\ndescription = "Neocortex project memory wrapper"\n\n';
+    }
+    if (relativeFile.endsWith('.agent.md')) {
+        return '---\nname: neocortex\ndescription: Neocortex project memory wrapper\n---\n\n';
+    }
+    return '';
+}
+function relativeCanonicalLink(projectRoot, relativeFile) {
+    const fromDir = dirname(join(projectRoot, relativeFile));
+    const toFile = join(projectRoot, CANONICAL_PROJECT_MEMORY_SOURCE);
+    const target = relative(fromDir, toFile);
+    return target.length > 0 ? target : CANONICAL_PROJECT_MEMORY_SOURCE;
+}
+export function shouldUseManagedWrapper(target, relativeFile) {
+    if (target.targetId === 'canonical')
+        return true;
+    if (target.requiresWrapperPreservation || target.linkRequirement.requiresWrapperPreservation)
+        return true;
+    if (target.linkRequirement.wrapperAllowed)
+        return true;
+    if (relativeFile === 'AGENTS.md')
+        return true;
+    if (relativeFile.includes('/agents/') || relativeFile.includes('/skills/'))
+        return true;
+    if (relativeFile.endsWith('.toml') || relativeFile.endsWith('.mdc'))
+        return true;
+    if (relativeFile.endsWith('.agent.md') || relativeFile.endsWith('.instructions.md'))
+        return true;
+    return false;
+}
+function isPolicySymlinkCapable(target) {
+    return target.linkRequirement.symlinkBacked && target.linkRequirement.semanticFileRequired;
+}
+function safeSymlinkFailureReason(reason) {
+    if (/EPERM|EACCES|operation not permitted|permission/i.test(reason))
+        return 'EPERM: symlink permission denied';
+    if (/ENOSYS|ENOTSUP|EOPNOTSUPP|not supported/i.test(reason))
+        return 'symlink filesystem unsupported';
+    return 'symlink capability unavailable';
+}
+function detectSymlinkCapability(projectRoot, target, relativeFile, override, dryRun = false) {
+    if (override !== undefined)
+        return override;
+    const targetPolicyAllowsSymlink = isPolicySymlinkCapable(target);
+    if (!targetPolicyAllowsSymlink) {
+        return {
+            os: platform(),
+            supported: false,
+            permission: 'unknown',
+            filesystem: 'unknown',
+            targetPolicy: target.linkRequirement.policy,
+            targetPolicyAllowsSymlink,
+            requiresWrapperPreservation: shouldUseManagedWrapper(target, relativeFile),
+            reason: `target policy ${target.linkRequirement.policy} does not allow semantic symlink orchestration`,
+        };
+    }
+    if (dryRun) {
+        return {
+            os: platform(),
+            supported: true,
+            permission: 'unknown',
+            filesystem: 'unknown',
+            targetPolicy: target.linkRequirement.policy,
+            targetPolicyAllowsSymlink,
+            requiresWrapperPreservation: shouldUseManagedWrapper(target, relativeFile),
+            reason: 'dry-run does not probe filesystem symlink support',
+        };
+    }
+    const probeDir = join(projectRoot, '.neocortex', 'tmp');
+    const nonce = randomUUID();
+    const probeSource = join(probeDir, `symlink-capability-source-${nonce}`);
+    const probeLink = join(probeDir, `symlink-capability-link-${nonce}`);
+    try {
+        mkdirSync(probeDir, { recursive: true });
+        writeFileSync(probeSource, 'probe', { encoding: 'utf8', flag: 'wx', mode: 0o600 });
+        symlinkSync(probeSource, probeLink);
+        const supported = lstatSync(probeLink).isSymbolicLink() && statSync(probeLink).isFile();
+        return {
+            os: platform(),
+            supported,
+            permission: supported ? 'ok' : 'unknown',
+            filesystem: supported ? 'supports-symlink' : 'no-symlink-support',
+            targetPolicy: target.linkRequirement.policy,
+            targetPolicyAllowsSymlink,
+            requiresWrapperPreservation: shouldUseManagedWrapper(target, relativeFile),
+            reason: supported ? undefined : 'filesystem probe did not create a resolvable symbolic link',
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const denied = /EPERM|EACCES|operation not permitted|permission/i.test(message);
+        return {
+            os: platform(),
+            supported: false,
+            permission: denied ? 'denied' : 'unknown',
+            filesystem: 'no-symlink-support',
+            targetPolicy: target.linkRequirement.policy,
+            targetPolicyAllowsSymlink,
+            requiresWrapperPreservation: shouldUseManagedWrapper(target, relativeFile),
+            reason: safeSymlinkFailureReason(message),
+        };
+    }
+    finally {
+        rmSync(probeLink, { force: true });
+        rmSync(probeSource, { force: true });
+    }
+}
+function buildManagedWrapperContent(target, relativeFile, existingContent, projectRoot) {
+    const canonicalLink = relativeCanonicalLink(projectRoot, relativeFile);
+    const baseContent = existingContent ?? `${frontmatterForWrapper(relativeFile)}# ${target.platformName} Neocortex Memory Wrapper\n\n`;
+    const ownedBlock = [
+        markerStart(target),
+        '## Canonical Project Memory Source',
+        '',
+        `This platform wrapper preserves host-specific frontmatter/instructions while resolving project memory to \`${canonicalLink}\`.`,
+        '',
+        `- Canonical source: \`${CANONICAL_PROJECT_MEMORY_SOURCE}\``,
+        `- Symlink-backed/source-of-truth file: \`${canonicalLink}\``,
+        `- Feedback loop: read \`${canonicalLink}\` for shared context and run \`${target.bidirectionalReference.feedbackTrigger}\` when durable platform findings should update \`${CANONICAL_PROJECT_MEMORY_SOURCE}\`.`,
+        '- Human-authored content outside this managed block is preserved byte-for-byte.',
+        markerEnd(target),
+    ].join('\n');
+    return replaceOwnedBlock(baseContent, target, ownedBlock);
+}
+function writeCompatibilityFallback(projectRoot, relativeFile, canonicalContent, capability, fallbackReason, dryRun = false) {
+    const filePath = join(projectRoot, relativeFile);
+    const publicFallbackReason = safeSymlinkFailureReason(fallbackReason);
+    const remediationDebt = [
+        '[NEOCORTEX COMPATIBILITY REMEDIATION]',
+        'Materialized project memory fallback because semantic symlink orchestration failed.',
+        'This is not product mode; repair host permissions/filesystem support and restore the symlink to NEOCORTEX.md.',
+        'WARNING: materialized fallback is remediation debt, not a silent mode; run *update-memory for durable context and repair this file back to canonical NEOCORTEX.md resolution.',
+        `Fallback reason: ${publicFallbackReason}`,
+        '',
+    ].join('\n');
+    const content = `${remediationDebt}${canonicalContent}`;
+    const existingContent = existsSync(filePath) ? readFileSync(filePath, 'utf8') : undefined;
+    const changed = existingContent !== content;
+    if (changed && !dryRun) {
+        if (existsSync(filePath) && lstatSync(filePath).isSymbolicLink())
+            unlinkSync(filePath);
+        writeFileWithBackup(filePath, content);
+    }
+    return {
+        filePath,
+        relativeFile,
+        changed,
+        content,
+        mode: 'compatibility-materialized-fallback',
+        canonicalSource: CANONICAL_PROJECT_MEMORY_SOURCE,
+        symlinkCapability: capability,
+        fallbackReason: publicFallbackReason,
+        remediationDebt: `Repair ${relativeFile} so it is a symlink to ${CANONICAL_PROJECT_MEMORY_SOURCE}; fallback is compatibility remediation only.`,
+    };
+}
+function writeSemanticSymlink(projectRoot, relativeFile, target, canonicalContent, symlinkCapability, dryRun = false) {
+    const filePath = join(projectRoot, relativeFile);
+    const linkTarget = relativeCanonicalLink(projectRoot, relativeFile);
+    if (!dryRun)
+        mkdirSync(dirname(filePath), { recursive: true });
+    const capability = detectSymlinkCapability(projectRoot, target, relativeFile, symlinkCapability, dryRun);
+    if (!capability.supported) {
+        return writeCompatibilityFallback(projectRoot, relativeFile, canonicalContent, capability, capability.reason ?? 'symlink capability detection reported unsupported host', dryRun);
+    }
+    if (dryRun) {
+        let changed = true;
+        try {
+            changed = !(existsSync(filePath) && lstatSync(filePath).isSymbolicLink() && readlinkSync(filePath) === linkTarget);
+        }
+        catch {
+            changed = true;
+        }
+        return {
+            filePath,
+            relativeFile,
+            changed,
+            content: canonicalContent,
+            mode: 'semantic-symlink',
+            canonicalSource: CANONICAL_PROJECT_MEMORY_SOURCE,
+            symlinkCapability: capability,
+        };
+    }
+    let changed = false;
+    try {
+        if (existsSync(filePath)) {
+            const stat = lstatSync(filePath);
+            if (stat.isSymbolicLink() && readlinkSync(filePath) === linkTarget) {
+                changed = false;
+            }
+            else {
+                unlinkSync(filePath);
+                symlinkSync(linkTarget, filePath);
+                changed = true;
+            }
+        }
+        else {
+            symlinkSync(linkTarget, filePath);
+            changed = true;
+        }
+        return {
+            filePath,
+            relativeFile,
+            changed,
+            content: readFileSync(filePath, 'utf8'),
+            mode: 'semantic-symlink',
+            canonicalSource: CANONICAL_PROJECT_MEMORY_SOURCE,
+            symlinkCapability: capability,
+        };
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        const publicReason = safeSymlinkFailureReason(reason);
+        return writeCompatibilityFallback(projectRoot, relativeFile, canonicalContent, {
+            ...capability,
+            supported: false,
+            permission: /EPERM|EACCES|operation not permitted|permission/i.test(reason) ? 'denied' : capability.permission,
+            filesystem: 'no-symlink-support',
+            reason: publicReason,
+        }, publicReason, dryRun);
+    }
+}
+function enforceBudget(target, content, memoryNotes, architectureReferences, bootstrapArchitecture) {
+    const fits = (value) => value.split('\n').length <= target.budget.maxLines &&
+        Buffer.byteLength(value, 'utf8') <= target.budget.maxBytes;
+    if (fits(content))
+        return content;
+    const compactBlock = buildOwnedBlock(target, memoryNotes.slice(0, 8), architectureReferences.slice(0, 12), bootstrapArchitecture);
+    const compactContent = replaceOwnedBlock(content.includes(markerStart(target)) ? content : buildTemplate(target), target, compactBlock);
+    return fits(compactContent) ? compactContent : compactContent.slice(0, target.budget.maxBytes);
+}
+export function buildProjectMemoryContent(target, existingContent, memoryNotes = [], architectureReferences = [], bootstrapArchitecture) {
+    const baseContent = existingContent ?? buildTemplate(target);
+    const ownedBlock = buildOwnedBlock(target, memoryNotes, architectureReferences, bootstrapArchitecture);
+    const content = replaceOwnedBlock(baseContent, target, ownedBlock);
+    return enforceBudget(target, content, memoryNotes, architectureReferences, bootstrapArchitecture);
+}
+export function writeProjectMemory(options) {
+    const target = getProjectMemoryTarget(options.targetId);
+    const fs = options.fs ?? createNodeProjectMemoryFs(options.backupDirectory);
+    const filePath = fs.join(options.projectRoot, target.primaryFile);
+    if (options.fs === undefined && target.targetId === 'canonical') {
+        assertProjectMemoryPaths(options.projectRoot, [CANONICAL_PROJECT_MEMORY_SOURCE]);
+    }
+    if (target.targetId !== 'canonical' && options.fs === undefined) {
+        const result = writeProjectMemoryTargetFiles(options).files.find((file) => file.relativeFile === target.primaryFile);
+        if (result === undefined)
+            throw new Error(`Primary project memory file was not written for ${target.targetId}.`);
+        return { filePath: result.filePath, changed: result.changed, content: result.content };
+    }
+    const existingContent = fs.readFile(filePath);
+    const bootstrapArchitecture = options.bootstrapArchitecture ?? (options.fs === undefined && target.targetId === 'canonical' && existingContent === undefined
+        ? bootstrapArchitectureMemory(options.projectRoot)
+        : undefined);
+    const content = target.targetId === 'canonical' && existingContent !== undefined
+        ? (hasCanonicalUpdateInput(options) ? mergeCanonicalRefreshUpdate(target, existingContent, options) : existingContent)
+        : buildProjectMemoryContent(target, existingContent, options.memoryNotes, options.architectureReferences, bootstrapArchitecture);
+    if (existingContent === content) {
+        return { filePath, changed: false, content };
+    }
+    const writeResult = options.dryRun ? undefined : fs.writeFileAtomic(filePath, content);
+    return {
+        filePath,
+        changed: true,
+        content,
+        safeDiff: createSafeProjectMemoryDiff(existingContent, content),
+        backupPath: writeResult?.backupPath,
+        reasonCodes: reasonCodesForNotes(options.memoryNotes ?? []),
+    };
+}
+export function writeCanonicalProjectMemory(options) {
+    return writeProjectMemory({ ...options, targetId: 'canonical' });
+}
+export function writeProjectMemoryTargetFiles(options) {
+    if (options.fs !== undefined) {
+        throw new Error('writeProjectMemoryTargetFiles requires the node filesystem to manage symlinks safely.');
+    }
+    const target = getProjectMemoryTarget(options.targetId);
+    const canonicalTarget = getProjectMemoryTarget('canonical');
+    if (target.secondaryFiles.some((file) => file === null || (file.scope !== 'project' && file.scope !== 'user') || !isValidScopedRelativePath(file.path))) {
+        invalidProjectMemoryPath('invalid');
+    }
+    const relativeFiles = Array.from(new Set([
+        target.primaryFile,
+        ...(target.targetId === 'canonical' ? [] : target.secondaryFiles.filter((file) => file.scope === 'project').map((file) => file.path)),
+    ]));
+    assertProjectMemoryPaths(options.projectRoot, [CANONICAL_PROJECT_MEMORY_SOURCE, ...relativeFiles, '.neocortex/tmp']);
+    const canonicalFilePath = join(options.projectRoot, CANONICAL_PROJECT_MEMORY_SOURCE);
+    const existingCanonicalContent = existsSync(canonicalFilePath) ? readFileSync(canonicalFilePath, 'utf8') : undefined;
+    const bootstrapArchitecture = options.bootstrapArchitecture ?? (existingCanonicalContent === undefined ? bootstrapArchitectureMemory(options.projectRoot) : undefined);
+    const canonicalContent = existingCanonicalContent !== undefined
+        ? (hasCanonicalUpdateInput(options) ? mergeCanonicalRefreshUpdate(canonicalTarget, existingCanonicalContent, options) : existingCanonicalContent)
+        : buildProjectMemoryContent(canonicalTarget, existingCanonicalContent, options.memoryNotes, options.architectureReferences, bootstrapArchitecture);
+    const canonicalChanged = !existsSync(canonicalFilePath) || readFileSync(canonicalFilePath, 'utf8') !== canonicalContent;
+    let canonicalBackupPath;
+    if (canonicalChanged && !options.dryRun) {
+        canonicalBackupPath = writeFileWithBackup(canonicalFilePath, canonicalContent, options.backupDirectory);
+    }
+    if (target.targetId === 'canonical') {
+        return {
+            targetId: target.targetId,
+            canonicalFilePath,
+            changed: canonicalChanged,
+            files: [{
+                    filePath: canonicalFilePath,
+                    relativeFile: CANONICAL_PROJECT_MEMORY_SOURCE,
+                    changed: canonicalChanged,
+                    content: canonicalContent,
+                    mode: 'canonical',
+                    canonicalSource: CANONICAL_PROJECT_MEMORY_SOURCE,
+                    safeDiff: createSafeProjectMemoryDiff(existingCanonicalContent, canonicalContent),
+                    backupPath: canonicalBackupPath,
+                    reasonCodes: reasonCodesForNotes(options.memoryNotes ?? []),
+                }],
+        };
+    }
+    const files = relativeFiles.map((relativeFile) => {
+        assertProjectMemoryPaths(options.projectRoot, [relativeFile, '.neocortex/tmp']);
+        if (!shouldUseManagedWrapper(target, relativeFile)) {
+            return writeSemanticSymlink(options.projectRoot, relativeFile, target, canonicalContent, options.symlinkCapability, options.dryRun);
+        }
+        const filePath = join(options.projectRoot, relativeFile);
+        const existingContent = existsSync(filePath) ? readFileSync(filePath, 'utf8') : undefined;
+        const content = buildManagedWrapperContent(target, relativeFile, existingContent, options.projectRoot);
+        const changed = existingContent !== content;
+        if (changed && !options.dryRun) {
+            writeFileWithBackup(filePath, content, options.backupDirectory);
+        }
+        return {
+            filePath,
+            relativeFile,
+            changed,
+            content,
+            mode: 'managed-wrapper',
+            canonicalSource: CANONICAL_PROJECT_MEMORY_SOURCE,
+            symlinkCapability: detectSymlinkCapability(options.projectRoot, target, relativeFile, options.symlinkCapability, options.dryRun),
+            reasonCodes: reasonCodesForNotes(options.memoryNotes ?? []),
+        };
+    });
+    return {
+        targetId: target.targetId,
+        canonicalFilePath,
+        files,
+        changed: canonicalChanged || files.some((file) => file.changed),
+    };
+}