arkgate 4.5.0 → 4.5.5

package/CHANGELOG.md

@@ -5,14 +5,38 @@ in the immutable pre-2.0 archive linked below.
 
 ## Unreleased
 
+## 4.5.5 — 2026-08-11
+
+**Patch** over **4.5.0**. Deep-module coach train plus upgrade **suggested improvements /
+what’s new** so consumers know what to try after install. **No required config migration.**
+No new skill names, sensors, or scores. Freezes held.
+
+**Status: prepared** (implementation only; not yet on npm `latest` — remains `4.5.0` until
+the publication checklist completes).
+
+### Added
+
+- **Deep-module coach (advisory):** `ark-check --doctor` JSON `doctor.deepModuleCoach` + human
+  section + HTML `data-advisory="deepModuleCoach"`. Hot paths from bounded git history
+  (`unavailable` + empty when history missing — never invent). Deepening candidates projected
+  only from existing design smells / physical cohesion / pilot / residual compass evidence —
+  empty when no evidence. Always `notAScore: true`; never flips gate verdicts. Pure helper
+  `buildDeepeningCandidates` (+ CLI gen mirror).
+- **Product voice + skills:** lexicon for depth / seam / deletion test / test-at-public-interface
+  / domain glossary / two-axis done. Existing skills (explore, think, place, fix, loop, adopt)
+  deepened; agent-skills 1:1. Compact router + agent-guide **two-axis done** (Enforce green ≠
+  feature done). Remediation port/inject `nextAction` prose includes test at the public interface.
+- **Upgrade suggested improvements / what’s new:** `ark upgrade` JSON `whatsNew` + human block
+  lists concrete try/inspect actions (deep-module coach, improvement compass, session/status
+  honesty, two-axis done, self-service honesty). Always `notAScore`; never a gate input.
+
 ## 4.5.0 — 2026-08-10
 
 **Minor** over 4.4.0. Session control-plane honesty (status/MCP improvement compass with explicit
 modes), domain module fitness (split oversized pure modules), selective pure verification ratchet,
 self-service upgrade activation honesty, and a short session recipe in product docs. **No required
 config migration.** Codex remains advisory at write time. Skills and AGENTS projection never
-enforce. **Status: prepared in tree — not published on npm until OIDC publish + `npm view` succeed**
-(see `docs/releases/4.5.0.md`).
+enforce. **Status: published** (`arkgate@4.5.0` on npm `latest`; see `docs/releases/4.5.0.md`).
 
 ### Added
 

package/README.md

@@ -16,8 +16,9 @@ and makes sure a “green” check means something real.
 
 </div>
 
-> **ArkGate 4.4.0** is on npm `latest`. Tree is preparing **4.5.0** (session honesty + upgrade self-service) — see [4.5.0 notes](docs/releases/4.5.0.md) (Status: prepared until publish).
-> [4.5.0 notes](docs/releases/4.5.0.md) · [4.4.0](docs/releases/4.4.0.md) · [4.3.0](docs/releases/4.3.0.md) · [Docs hub](docs/README.md) · [Product voice](docs/product-voice.md)
+> **ArkGate 4.5.5** is **prepared** (deep-module coach + upgrade what’s new). npm `latest` remains
+> **4.5.0** until publish. [4.5.5 notes](docs/releases/4.5.5.md) · [4.5.0](docs/releases/4.5.0.md) ·
+> [4.4.0](docs/releases/4.4.0.md) · [Docs hub](docs/README.md) · [Product voice](docs/product-voice.md)
 
 ---
 
@@ -208,8 +209,9 @@ for real systems. Details: [docs/production-hardening.md](docs/production-harden
 | Config · package surface · TS | [configuration](docs/configuration.md) · [package-surface](docs/package-surface.md) · [typescript-support](docs/typescript-support.md) |
 | Brownfield | [docs/brownfield-adoption.md](docs/brownfield-adoption.md) |
 | Security | [SECURITY.md](SECURITY.md) |
-| Current release (4.4.0 on npm `latest`) | [docs/releases/4.4.0.md](docs/releases/4.4.0.md) · [CHANGELOG](CHANGELOG.md) |
-| Next prepare (4.5.0) | [docs/releases/4.5.0.md](docs/releases/4.5.0.md) (prepared — not published until npm verify) |
+| Prepared (4.5.5) | [docs/releases/4.5.5.md](docs/releases/4.5.5.md) · [CHANGELOG](CHANGELOG.md) |
+| Current published (4.5.0 on npm `latest`) | [docs/releases/4.5.0.md](docs/releases/4.5.0.md) |
+| Prior (4.4.0) | [docs/releases/4.4.0.md](docs/releases/4.4.0.md) |
 | Prior (4.3.0) | [docs/releases/4.3.0.md](docs/releases/4.3.0.md) |
 | Prior (4.2.1) | [docs/releases/4.2.1.md](docs/releases/4.2.1.md) |
 | Previous (4.2.0) | [docs/releases/4.2.0.md](docs/releases/4.2.0.md) |

package/bin/ark-check-runtime.mjs

@@ -1644,6 +1644,10 @@ async function main() {
         ...(designDepth?.improvementCompass
           ? { improvementCompass: designDepth.improvementCompass }
           : {}),
+        // Doctor parity: deep-module coach advisory (hot paths + deepening; notAScore).
+        ...(designDepth?.deepModuleCoach
+          ? { deepModuleCoach: designDepth.deepModuleCoach }
+          : {}),
       },
     };
     const html = args.beginner

package/bin/lib/adapter-contract.mjs

@@ -82,18 +82,18 @@ function nextActionForDiagnostic(ruleId, evidence, violation) {
             return 'Move the referenced type to a mutually allowed layer, use `import type`, then preflight again.';
         }
         if (violation.peerIsolation === true) {
-            return 'Extract the shared dependency to a shared layer, then preflight again.';
+            return 'Extract the shared dependency to a shared layer, test at the public interface, then preflight again.';
         }
-        return `Define a port in ${evidence.fromLayer ?? 'the source layer'}, inject the ${evidence.toLayer ?? 'outer-layer'} implementation, then preflight again.`;
+        return `Define a port in ${evidence.fromLayer ?? 'the source layer'}, inject the ${evidence.toLayer ?? 'outer-layer'} implementation, test at the public interface, then preflight again.`;
     }
     if (ruleId === 'FORBIDDEN_GLOBAL') {
-        return `Inject ${evidence.target ?? 'the capability'} through a port, then preflight again.`;
+        return `Inject ${evidence.target ?? 'the capability'} through a port, test at the public interface, then preflight again.`;
     }
     if (ruleId === 'CAPABILITY_VIOLATION') {
-        return `Define a ${text(violation.capability) ?? 'capability'} port in ${evidence.fromLayer ?? 'the walled layer'}, bind the implementation outside it, then preflight again.`;
+        return `Define a ${text(violation.capability) ?? 'capability'} port in ${evidence.fromLayer ?? 'the walled layer'}, bind the implementation outside it, test at the public interface, then preflight again.`;
     }
     if (ruleId === 'CIRCULAR_DEPENDENCY') {
-        return 'Extract the shared dependency into a third module, then preflight again.';
+        return 'Extract the shared dependency into a third module, test at the public interface, then preflight again.';
     }
     if (ruleId === 'RAW_EVENT_PUBLISH')
         return 'Publish through a registered intent creator, then run Ark again.';

package/bin/lib/analysis-engine.mjs

@@ -7,4 +7,4 @@ ${n.map(r=>`- ${r.path}: ${r.message}`).join(`
 `)}`),this.name="ArkConfigValidationError",this.source=t,this.issues=n}};function Mt(e){return e!==null&&typeof e=="object"&&!Array.isArray(e)}function xe(e,t){return/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(t)?`${e}.${t}`:`${e}[${JSON.stringify(t)}]`}function le(e){return e===null?"null":Array.isArray(e)?"array":typeof e}function Vn(e,t){let n="#/$defs/";if(e.startsWith(n))return t.$defs[e.slice(n.length)]}function Ae(e,t,n,r,s){if(t.$ref){let a=Vn(t.$ref,r);if(!a){s.push({path:n,message:`schema reference ${t.$ref} cannot be resolved`});return}Ae(e,a,n,r,s);return}if(t.const!==void 0&&!Object.is(e,t.const)){s.push({path:n,message:`must equal ${JSON.stringify(t.const)}`});return}if(t.enum&&!t.enum.some(a=>Object.is(a,e))){s.push({path:n,message:`must be one of ${t.enum.map(String).join(", ")}`});return}if(t.type==="object"){if(!Mt(e)){s.push({path:n,message:`must be an object; received ${le(e)}`});return}let a=t.properties??{};for(let i of t.required??[])e[i]===void 0&&s.push({path:xe(n,i),message:"is required"});if(t.additionalProperties===!1)for(let i of Object.keys(e))i in a||s.push({path:xe(n,i),message:"unknown field"});else if(t.additionalProperties!==void 0&&t.additionalProperties!==!0&&typeof t.additionalProperties=="object"){let i=t.additionalProperties;for(let d of Object.keys(e))d in a||Ae(e[d],i,xe(n,d),r,s)}for(let[i,d]of Object.entries(a))e[i]!==void 0&&Ae(e[i],d,xe(n,i),r,s);return}if(t.type==="array"){if(!Array.isArray(e)){s.push({path:n,message:`must be an array; received ${le(e)}`});return}if(t.minItems!==void 0&&e.length<t.minItems&&s.push({path:n,message:`must contain at least ${t.minItems} item(s)`}),t.uniqueItems){let a=e.map(i=>JSON.stringify(i));new Set(a).size!==a.length&&s.push({path:n,message:"must not contain duplicate items"})}t.items&&e.forEach((a,i)=>Ae(a,t.items,`${n}[${i}]`,r,s));return}if(t.type==="string"){if(typeof e!="string"){s.push({path:n,message:`must be a string; received ${le(e)}`});return}t.minLength!==void 0&&e.length<t.minLength&&s.push({path:n,message:`must contain at least ${t.minLength} character(s)`});return}if(t.type==="boolean"){typeof e!="boolean"&&s.push({path:n,message:`must be a boolean; received ${le(e)}`});return}if(t.type==="integer"){if(!Number.isInteger(e)){s.push({path:n,message:`must be an integer; received ${le(e)}`});return}t.minimum!==void 0&&e<t.minimum&&s.push({path:n,message:`must be at least ${t.minimum}`})}}function Un(e){return{...e,$schema:e.$schema===void 0?nt:e.$schema,schemaVersion:e.schemaVersion===void 0?"1.1":e.schemaVersion,include:e.include===void 0?["src"]:e.include,layers:e.layers===void 0?[]:e.layers,rules:e.rules===void 0?Nt.map(t=>({...t})):e.rules}}function Gn(){let e=new Set(["1.1"]);for(let t of rt)t.from!=="unversioned"&&e.add(t.from),e.add(t.to);return e}function qn(e,t="ark.config.json"){if(!Mt(e))throw new G(t,[{path:"$",message:`must be an object; received ${le(e)}`}]);let n=Gn(),r=e.schemaVersion===void 0?"unversioned":typeof e.schemaVersion=="string"?e.schemaVersion:null;if(r===null)throw new G(t,[{path:"$.schemaVersion",message:`unsupported version ${JSON.stringify(e.schemaVersion)}; expected 1.1`}]);if(r!=="unversioned"&&!n.has(r))throw new G(t,[{path:"$.schemaVersion",message:`unsupported version ${JSON.stringify(r)}; expected 1.1`}]);let s=r,a={...e},i=0;for(;s!=="1.1"&&i<rt.length+1;){i+=1;let p=rt.find(b=>b.from===s);if(!p)throw new G(t,[{path:"$.schemaVersion",message:`unsupported version ${JSON.stringify(s)}; expected 1.1`}]);s=p.to,a.schemaVersion=s}if(s!=="1.1")throw new G(t,[{path:"$.schemaVersion",message:`unsupported version ${JSON.stringify(r)}; expected 1.1`}]);let d=r==="unversioned"?"unversioned":r==="1.0"?"1.0":null;return{candidate:Un(a),migratedFrom:d}}function st(e,t="ark.config.json"){let{candidate:n,migratedFrom:r}=qn(e,t),s=[];if(Ae(n,Lt,"$",Lt,s),s.length>0)throw new G(t,s);return{config:n,migratedFrom:r}}function Ht(e,t="ark.config.json"){let n;try{n=JSON.parse(e)}catch(r){throw new G(t,[{path:"$",message:`invalid JSON: ${r instanceof Error?r.message:String(r)}`}])}return st(n,t)}function Dt(e){return{config:e.config,arkRules:{schemaVersion:e.arkRules.schemaVersion,structure:e.arkRules.structure.map(t=>({id:t.id,sensor:t.sensor,mode:t.mode,appliesTo:t.appliesTo??null,description:t.description??null,provenance:t.provenance})),invariants:e.arkRules.invariants.map(t=>({id:t.id,description:t.description,aggregate:t.aggregate??null,coverage:t.coverage??null,mode:t.mode,appliesTo:t.appliesTo??null,provenance:t.provenance}))}}}var Ut="1.0";function I(e,t){e.push({id:`${t.classification}:${t.path}:${t.kind}`,path:t.path,classification:t.classification,message:t.message,...t.classification==="weakening"||t.classification==="judgment-required"?{nextAction:`Restore the previous protection at ${t.path}, then run ArkGate again.`}:{},...t.before===void 0?{}:{before:t.before},...t.after===void 0?{}:{after:t.after}})}function T(e){return[...new Set(e??[])].sort()}function X(e,t,n,r,s){let a=T(n),i=T(r),d=new Set(a),p=new Set(i),b=i.filter(h=>!d.has(h)),A=a.filter(h=>!p.has(h));b.length===0&&A.length===0||(b.length>0&&I(e,{kind:"added",path:t,classification:s.added,message:s.addedMessage,before:a,after:i}),A.length>0&&I(e,{kind:"removed",path:t,classification:s.removed,message:s.removedMessage,before:a,after:i}))}function Oe(e,t,n,r,s,a,i){if(n===r)return;I(e,{kind:r?"enabled":"disabled",path:t,classification:r?s:s==="strengthening"?"weakening":"strengthening",message:r?a:i,before:n,after:r})}function Pe(e,t){let n=new Map,r=new Set;for(let s of e){let a=t(s);n.has(a)?r.add(a):n.set(a,s)}return{values:n,duplicates:[...r].sort()}}function zn(e,t,n){let r=Pe(t,a=>a.name),s=Pe(n,a=>a.name);(r.duplicates.length>0||s.duplicates.length>0)&&I(e,{kind:"duplicate-layer",path:"$.layers",classification:"judgment-required",message:"Duplicate layer names make policy ownership ambiguous.",before:r.duplicates,after:s.duplicates});for(let a of[...new Set([...r.values.keys(),...s.values.keys()])].sort()){let i=r.values.get(a),d=s.values.get(a),p=`$.layers[${a}]`;if(!i&&d){I(e,{kind:"layer-added",path:p,classification:"judgment-required",message:"A layer was added; verify overlap, ownership, and rule coverage.",after:d});continue}if(i&&!d){I(e,{kind:"layer-removed",path:p,classification:"weakening",message:"Removing a layer can leave its source paths ungoverned.",before:i});continue}if(!i||!d)continue;X(e,`${p}.patterns`,i.patterns,d.patterns,{added:"strengthening",removed:"weakening",addedMessage:"Additional paths are governed by this layer.",removedMessage:"Paths were removed from this layer and may become ungoverned."}),X(e,`${p}.exclude`,i.exclude,d.exclude,{added:"weakening",removed:"strengthening",addedMessage:"Additional paths are excluded from this layer.",removedMessage:"Fewer paths are excluded from this layer."});let b=Se(i),A=Se(d);X(e,`${p}.forbiddenGlobals`,b.rawGlobals,A.rawGlobals,{added:"strengthening",removed:"weakening",addedMessage:"Additional forbidden globals are enforced in this layer.",removedMessage:"A forbidden-global protection was removed from this layer."}),X(e,`${p}.capabilities`,b.atoms,A.atoms,{added:"strengthening",removed:"weakening",addedMessage:"Additional ambient/import protection is enforced in this layer (coverage atoms).",removedMessage:"An ambient/import protection was lost from this layer (coverage atoms)."}),T(i.intentPrefixes).join("\0")!==T(d.intentPrefixes).join("\0")&&I(e,{kind:"intent-prefixes-changed",path:`${p}.intentPrefixes`,classification:"judgment-required",message:"Intent ownership changed and must be reviewed against publishers and consumers.",before:T(i.intentPrefixes),after:T(d.intentPrefixes)}),Oe(e,`${p}.mayImportInfrastructure`,i.mayImportInfrastructure===!0,d.mayImportInfrastructure===!0,"weakening","The layer may now import infrastructure directly.","Direct infrastructure imports are no longer allowed for this layer."),Oe(e,`${p}.optional`,i.optional===!0,d.optional===!0,"weakening","The layer is now optional and can be absent without a strict warning.","The layer is now required when its contract is active.")}}function Bn(e,t,n){let r=i=>`${i.from}->${i.to}`,s=Pe(t,r),a=Pe(n,r);(s.duplicates.length>0||a.duplicates.length>0)&&I(e,{kind:"duplicate-rule",path:"$.rules",classification:"judgment-required",message:"Duplicate rule edges make the effective verdict order-dependent.",before:s.duplicates,after:a.duplicates});for(let i of[...new Set([...s.values.keys(),...a.values.keys()])].sort()){let d=s.values.get(i),p=a.values.get(i),b=`$.rules[${i}]`;if(!d&&p){p.allowed===!1&&I(e,{kind:"deny-added",path:b,classification:"strengthening",message:"A denied dependency edge was added.",after:p});continue}if(d&&!p){d.allowed===!1&&I(e,{kind:"deny-removed",path:b,classification:"weakening",message:"A denied dependency edge was removed.",before:d});continue}if(!d||!p)continue;d.allowed!==p.allowed&&I(e,{kind:p.allowed?"deny-disabled":"deny-enabled",path:`${b}.allowed`,classification:p.allowed?"weakening":"strengthening",message:p.allowed?"A previously denied dependency edge is now allowed.":"A dependency edge is now denied.",before:d.allowed,after:p.allowed});let A=d.peerIsolation===!0,h=p.peerIsolation===!0;if(A!==h){let o=d.from===d.to&&p.from===p.to;I(e,{kind:h?"peer-isolation-enabled":"peer-isolation-disabled",path:`${b}.peerIsolation`,classification:o?h?"strengthening":"weakening":"judgment-required",message:o?h?"Cross-slice dependencies inside this layer are now denied.":"Cross-slice dependencies inside this layer are no longer denied.":"Changing peer isolation on a cross-layer edge changes the denial scope.",before:A,after:h})}T(d.sliceFolders).join("\0")!==T(p.sliceFolders).join("\0")&&I(e,{kind:"slice-folders-changed",path:`${b}.sliceFolders`,classification:"judgment-required",message:"Slice ownership folders changed and can reclassify existing dependencies.",before:T(d.sliceFolders),after:T(p.sliceFolders)})}}function Kn(e,t,n){let r=t.safety??{},s=n.safety??{};for(let a of["maxTsSuppressions","maxAnyCasts"]){let i=r[a]??0,d=s[a]??0;i!==d&&I(e,{kind:d>i?"threshold-raised":"threshold-lowered",path:`$.safety.${a}`,classification:d>i?"weakening":"strengthening",message:d>i?"The safety threshold allows more violations.":"The safety threshold allows fewer violations.",before:i,after:d})}for(let a of["allowInMemory","allowDisabledPeerIsolation"])Oe(e,`$.safety.${a}`,r[a]===!0,s[a]===!0,"weakening","A safety exception was enabled.","A safety exception was disabled.")}function Yn(e){return e.some(t=>t.classification==="weakening")?"weakening":e.some(t=>t.classification==="judgment-required")?"judgment-required":e.some(t=>t.classification==="strengthening")?"strengthening":"neutral"}function jt(e,t){return`${e}::${t}`}function Vt(e){let t=new Map,n=new Map;if(!e)return{structure:t,invariants:n};for(let r of e.structure)t.set(jt(r.provenance.layer,r.id),r);for(let r of e.invariants)n.set(jt(r.provenance.layer,r.id),r);return{structure:t,invariants:n}}function Wn(e,t,n,r,s,a){let i=new Map((a??[]).map(o=>[o.invariantId,o])),d=t.arkRules??{},p=n.arkRules??{},b=[...new Set([...Object.keys(d),...Object.keys(p)])].sort();for(let o of b){let l=d[o],c=p[o],f=`$.arkRules[${o}]`;if(l===void 0&&c!==void 0){I(e,{kind:"arkrules-ref-added",path:f,classification:"strengthening",message:`ArkRules reference for layer ${o} was added.`,after:c});continue}if(l!==void 0&&c===void 0){I(e,{kind:"arkrules-ref-removed",path:f,classification:"weakening",message:`ArkRules reference for layer ${o} was removed.`,before:l});continue}l!==c&&I(e,{kind:"arkrules-ref-path-changed",path:f,classification:"judgment-required",message:`ArkRules file path for layer ${o} changed; verify the effective rules still match intent.`,before:l,after:c})}let A=Vt(r),h=Vt(s);for(let o of[...new Set([...A.structure.keys(),...h.structure.keys()])].sort()){let l=A.structure.get(o),c=h.structure.get(o),f=`$.arkRules.structure[${o}]`;if(!l&&c){I(e,{kind:"arkrule-structure-added",path:f,classification:"strengthening",message:`Structure ArkRule ${c.id} was added (${c.mode}).`,after:c});continue}if(l&&!c){I(e,{kind:"arkrule-structure-removed",path:f,classification:"weakening",message:`Structure ArkRule ${l.id} was removed.`,before:l});continue}if(!(!l||!c)){if(l.mode!==c.mode){let y=l.mode==="advisory"&&c.mode==="enforced";I(e,{kind:y?"arkrule-promoted":"arkrule-demoted",path:`${f}.mode`,classification:y?"strengthening":"weakening",message:y?`Structure ArkRule ${c.id} was promoted to enforced.`:`Structure ArkRule ${c.id} was demoted to advisory.`,before:l.mode,after:c.mode})}l.sensor!==c.sensor&&I(e,{kind:"arkrule-sensor-changed",path:`${f}.sensor`,classification:"judgment-required",message:`Structure ArkRule ${c.id} changed sensor identity.`,before:l.sensor,after:c.sensor})}}for(let o of[...new Set([...A.invariants.keys(),...h.invariants.keys()])].sort()){let l=A.invariants.get(o),c=h.invariants.get(o),f=`$.arkRules.invariants[${o}]`;if(!l&&c){I(e,{kind:"arkrule-invariant-added",path:f,classification:"strengthening",message:`Invariant ${c.id} was added (${c.mode}).`,after:c});continue}if(l&&!c){I(e,{kind:"arkrule-invariant-removed",path:f,classification:"weakening",message:`Invariant ${l.id} was removed.`,before:l});continue}if(!(!l||!c)&&l.mode!==c.mode)if(l.mode==="advisory"&&c.mode==="enforced"){let R=i?.get(c.id),u=$t(R);u.ok?I(e,{kind:"arkrule-invariant-promoted",path:`${f}.mode`,classification:"strengthening",message:`Invariant ${c.id} was promoted to enforced (coverage evidence present).`,before:l.mode,after:c.mode}):I(e,{kind:"arkrule-invariant-promote-refused",path:`${f}.mode`,classification:"judgment-required",message:`Invariant ${c.id} cannot be promoted to enforced: ${u.reason}`,before:l.mode,after:c.mode})}else I(e,{kind:"arkrule-invariant-demoted",path:`${f}.mode`,classification:"weakening",message:`Invariant ${c.id} was demoted to advisory.`,before:l.mode,after:c.mode})}}function Gt(e,t,n){let r=[];X(r,"$.include",e.include,t.include,{added:"strengthening",removed:"weakening",addedMessage:"Additional project roots are governed.",removedMessage:"Project roots were removed from governance."}),X(r,"$.exclude",e.exclude,t.exclude,{added:"weakening",removed:"strengthening",addedMessage:"Additional project paths are excluded from governance.",removedMessage:"Fewer project paths are excluded from governance."}),X(r,"$.dynamicImportAllowlist",e.dynamicImportAllowlist,t.dynamicImportAllowlist,{added:"weakening",removed:"strengthening",addedMessage:"Additional files may use non-literal dynamic imports.",removedMessage:"Fewer files may use non-literal dynamic imports."}),Oe(r,"$.excludeGenerated",e.excludeGenerated!==!1,t.excludeGenerated!==!1,"weakening","Generated source is now excluded from governance.","Generated source is now governed.");let s={off:0,soft:1,"framework-soft":1,strict:2},a=e.cyclePolicy??"strict",i=t.cyclePolicy??"strict";if(a!==i){let d=s[i]===s[a]?"judgment-required":s[i]>s[a]?"strengthening":"weakening";I(r,{kind:"cycle-policy-changed",path:"$.cyclePolicy",classification:d,message:"The cycle enforcement level changed.",before:a,after:i})}return(e.frameworkOverlay??null)!==(t.frameworkOverlay??null)&&I(r,{kind:"framework-overlay-changed",path:"$.frameworkOverlay",classification:"judgment-required",message:"The framework overlay changed and may alter effective layer matching.",before:e.frameworkOverlay??null,after:t.frameworkOverlay??null}),zn(r,e.layers,t.layers),Bn(r,e.rules,t.rules),Kn(r,e,t),Wn(r,e,t,n?.baseArkRules,n?.candidateArkRules,n?.candidateInvariantCoverage),r.sort((d,p)=>d.path.localeCompare(p.path)||d.id.localeCompare(p.id)),{schemaVersion:Ut,classification:Yn(r),findings:r}}function qt(e,t){if(!e||e.schemaVersion!==Ut||typeof e.basePolicyHash!="string"||typeof e.candidatePolicyHash!="string"||typeof e.reason!="string"||!Array.isArray(e.findingIds)||e.findingIds.some(s=>typeof s!="string")||e.reason.trim().length===0||e.basePolicyHash!==t.basePolicyHash||e.candidatePolicyHash!==t.candidatePolicyHash)return!1;let n=T(e.findingIds),r=T(t.findingIds);return n.length===r.length&&n.every((s,a)=>s===r[a])}function Q(e){let t=[];for(let n of e.replace(/\\/g,"/").split("/"))!n||n==="."||(n===".."&&t.length>0&&t.at(-1)!==".."?t.pop():t.push(n));return t.join("/")}function zt(e){return e!==void 0&&/[A-Za-z_$]/.test(e)}function Fe(e){return e!==void 0&&/[A-Za-z0-9_$]/.test(e)}function P(e,t){for(;t<e.length&&/\s/.test(e[t]);)t+=1;return t}function Re(e,t){let n=e[t];if(n!=="'"&&n!=='"')return;let r=t,s="";for(t+=1;t<e.length;t+=1){let a=e[t];if(a===n)return{value:s,offset:r,excerpt:e.slice(r,t+1)};a==="\\"&&t+1<e.length?(s+=e[t+1],t+=1):s+=a}}function _(e,t,n){return e.startsWith(t,n)&&!Fe(e[n-1])&&!Fe(e[n+t.length])}function Bt(e,t){let n=P(e,t);if(e[n]!=="{")return!1;n+=1;let r=!1;for(;n<e.length;){if(n=P(e,n),e[n]==="}")return r;if(e[n]===","){n+=1;continue}if(!_(e,"type",n))return!1;let s=P(e,n+4);if(s>=e.length||e[s]===","||e[s]==="}"||_(e,"as",s)||!zt(e[s]))return!1;for(n=s;n<e.length&&Fe(e[n]);)n+=1;if(n=P(e,n),_(e,"as",n)){if(n=P(e,n+2),!zt(e[n]))return!1;for(;n<e.length&&Fe(e[n]);)n+=1}r=!0}return!1}function Jn(e,t){if(t=P(e,t+6),e[t]==="(")return Re(e,P(e,t+1));let n=!1;if(_(e,"type",t)){let s=P(e,t+4);e[s]!==","&&!_(e,"from",s)&&(n=!0)}else Bt(e,t)&&(n=!0);let r=Kt(e,t,!0);return r&&n?{...r,typeOnly:!0}:r}function Zn(e,t){t=t+6;let n=P(e,t),r=!1;if(_(e,"type",n)){let a=P(e,n+4);(e[a]==="{"||e[a]==="*")&&(r=!0)}else Bt(e,n)&&(r=!0);let s=Kt(e,t,!1);return s&&r?{...s,typeOnly:!0}:s}function Kt(e,t,n){for(;t<e.length;t+=1){if(e[t]===";")return;if(_(e,"from",t))return Re(e,P(e,t+4));if(n&&(e[t]==="'"||e[t]==='"'))return Re(e,t);if(t>0&&(_(e,"import",t)||_(e,"export",t)))return}}function Xn(e,t){for(t+=1;t<e.length;t+=1){let n=e[t];if(n==="\\")t+=1;else if(n==="`")return t}return e.length}function Qn(e,t){let n=t-1;for(;n>=0&&/\s/.test(e[n]);)n-=1;if(e[n]===".")return;let r=P(e,t+7);if(e[r]!=="(")return;r=P(e,r+1);let s=Re(e,r);return s?{...s,requireCall:!0}:void 0}function er(e){let t=[];for(let n=0;n<e.length;n+=1){let r=e[n];if(r==="/"&&e[n+1]==="/"){if(n=e.indexOf(`
 `,n+2),n<0)break;continue}if(r==="/"&&e[n+1]==="*"){let a=e.indexOf("*/",n+2);if(a<0)break;n=a+1;continue}if(r==="`"){n=Xn(e,n);continue}if(r==="'"||r==='"'){let a=Re(e,n);a&&(n=a.offset+a.excerpt.length-1);continue}let s=r==="i"&&_(e,"import",n)?Jn(e,n):r==="e"&&_(e,"export",n)?Zn(e,n):r==="r"&&_(e,"require",n)?Qn(e,n):void 0;s&&(t.push(s),n=s.offset+s.excerpt.length-1)}return t}function Yt(e,t){let n=[],r=[];for(let s of er(e.content)){let a=s.value;if(!a.startsWith(".")){if(s.typeOnly)continue;let b=pe(a);if(!b)continue;let A=e.content.slice(0,s.offset).split(`
 `).length;r.push({file:e.path,symbol:a,capability:b,evidence:{kind:"import",file:e.path,line:A,excerpt:s.excerpt}});continue}let i=e.content.slice(0,s.offset).split(`
-`).length,d={kind:"import",file:e.path,line:i,excerpt:s.excerpt},p=tr(e.path,a,t);n.push({from:e.path,specifier:a,to:p?.path??null,resolution:p?"resolved":"unresolved",fromLayer:e.layer,toLayer:p?.layer??null,evidence:d})}return{edges:n,capabilityUses:r}}function tr(e,t,n){let r=e.split("/");r.pop();for(let a of t.split("/"))a==="."||a===""||(a===".."?r.pop():r.push(a));let s=r.join("/");for(let a of[s,`${s}.ts`,`${s}.tsx`,`${s}.mts`,`${s}.cts`,`${s}/index.ts`,`${s}/index.tsx`]){let i=n.get(a);if(i)return i}}function Wt(e,t){let n=[];for(let r of e){if(!r.to||!r.fromLayer||!r.toLayer)continue;let s=ae(t.rules,r.fromLayer,r.toLayer,{fromPath:r.from,toPath:r.to,layers:t.layers});s&&n.push({ruleId:`layer-dependency:${s.from}->${s.to}`,message:s.message??`${s.from} must not depend on ${s.to}.`,edge:r,evidence:r.evidence})}return n}var nr={code:"LEXICAL_EVIDENCE_INCOMPLETE",message:"Lexical compatibility mode cannot prove parse status, TypeScript/package/symlink resolution, or symbol-aware source-policy and safety evidence. Use the resolved candidate facts APIs for an authoritative verdict."};function rr(e,t){return e.arkRules!==void 0&&Object.keys(e.arkRules).length>0||t.structure.length>0||t.invariants.length>0}function sr(e,t){return rr(e,t)?E(S(Dt({config:e,arkRules:t,warnings:[]}))):E(S(e))}function at(e,t,n){let r=typeof e=="string"?Ht(e,t):st(e,t),s=n?.arkRules??me();return{...r,arkRules:s,policyHash:sr(r.config,s)}}function ar(e){let t=at(e.baseConfig,e.baseSource??"base ark.config.json",{arkRules:e.baseArkRules}),n=at(e.candidateConfig,e.candidateSource??"candidate ark.config.json",{arkRules:e.candidateArkRules}),r=Gt(t.config,n.config,{baseArkRules:t.arkRules,candidateArkRules:n.arkRules,candidateInvariantCoverage:e.candidateInvariantCoverage}),s=r.findings.filter(d=>d.classification==="weakening"||d.classification==="judgment-required").map(d=>d.id).sort(),a=s.length>0,i=a&&qt(e.acknowledgement,{basePolicyHash:t.policyHash,candidatePolicyHash:n.policyHash,findingIds:s});return{schemaVersion:r.schemaVersion,basePolicyHash:t.policyHash,candidatePolicyHash:n.policyHash,classification:r.classification,findings:r.findings,blockingFindingIds:s,requiresAcknowledgement:a,acknowledged:i,valid:!a||i}}function Te(e){let t=e.files.map(h=>{let o=Q(h.path);return{path:o,content:h.content,contentHash:E(h.content),layer:V(o,e.contract.config.layers)??null}}).sort((h,o)=>h.path.localeCompare(o.path)),n=new Map(t.map(h=>[h.path,h])),r=[],s=[];for(let h of t){let o=Yt(h,n);r.push(...o.edges),s.push(...o.capabilityUses)}let a=Wt(r,e.contract.config),i=new Map(e.contract.config.layers.map(h=>[h.name,h])),d=new Map(e.contract.config.layers.map(h=>[h.name,new Set(se(h))]));for(let h of s){let o=n.get(h.file)?.layer;if(!o)continue;let l=i.get(o),c=fe(h.symbol,l?.forbiddenGlobals??[]);if(c){a.push({ruleId:"FORBIDDEN_GLOBAL",message:`${o} must not use module "${h.symbol}" because it is the import form of forbidden global "${c}".`,symbol:h.symbol,evidence:h.evidence});continue}d.get(o)?.has(h.capability)&&a.push({ruleId:"CAPABILITY_VIOLATION",message:`${o} denies the ${h.capability} capability; found import of "${h.symbol}".`,capability:h.capability,symbol:h.symbol,evidence:h.evidence})}let p=t.length===0?"complete":"partial",b=p==="complete"?[]:[{...nr}],A={schemaVersion:mt,policyHash:e.contract.policyHash,compilerOptionsHash:E(S(e.compilerOptions??{})),files:t,layers:e.contract.config.layers.map(h=>h.name),edges:r,capabilityUses:s,violations:a};return{mode:"lexical-compatibility",completeness:p,completenessReasons:b,valid:p==="complete"&&a.length===0,ir:A}}function it(e){let t=new Map(e.files.map(n=>[Q(n.path),n]));for(let n of e.changes){let r=Q(n.path);"delete"in n&&n.delete?t.delete(r):"content"in n&&t.set(r,{path:r,content:n.content})}return Te({contract:e.contract,files:[...t.values()],compilerOptions:e.compilerOptions})}function ir(e){let t=`${e.evidence.file}:${e.evidence.line}`;if(!e.edge)return`${e.ruleId} at ${t}: ${e.message}`;let n=e.edge.to??e.edge.specifier;return`${e.ruleId} at ${t}: ${e.edge.from} imports ${n}. ${e.message}`}function _e(e){switch(e.ruleId){case"LAYER_IMPORT_VIOLATION":return e.typeOnly||e.targetTypeOnlyExports||e.namedBindingsTypeOnly?"Move the referenced type to a mutually allowed layer, use `import type`, then preflight again.":e.peerIsolation?"Extract the shared dependency to a shared layer, then preflight again.":`Define a port in ${e.fromLayer??"the source layer"}, inject the ${e.toLayer??"outer-layer"} implementation, then preflight again.`;case"FORBIDDEN_GLOBAL":return`Inject ${e.target??"the capability"} through a port, then preflight again.`;case"CAPABILITY_VIOLATION":return`Define a ${String(e.capability??"capability")} port in ${e.fromLayer??"the walled layer"}, bind the implementation outside it, then preflight again.`;case"CIRCULAR_DEPENDENCY":return"Extract the shared dependency into a third module, then preflight again.";case"RAW_EVENT_PUBLISH":return"Publish through a registered intent creator, then run Ark again.";case"PUBLISH_MISSING_SOURCE":return"Add metadata.source to the publish call, then run Ark again.";case"ARKRULE_STRUCTURE":case"ARKRULE_INVARIANT":case"INVARIANT_UNCOVERED":return`Fix the structure or invariant for ${typeof e.arkruleId=="string"&&e.arkruleId.length>0?e.arkruleId:"the ArkRule"} (declared in ${typeof e.arkruleSource=="string"&&e.arkruleSource.length>0?e.arkruleSource:"arkrules/<Layer>.json"}), then preflight again. Do not demote the rule without a hash-bound policy acknowledgement.`;default:return typeof e.ruleId=="string"&&e.ruleId.startsWith("ARKRULE_")?`Fix the ArkRule ${typeof e.arkruleId=="string"?e.arkruleId:e.ruleId}, then preflight again.`:`Resolve ${typeof e.ruleId=="string"&&e.ruleId.length>0?e.ruleId:"ARK_UNKNOWN"} without weakening ark.config.json, then run Ark again.`}}function Jt(e){return E(S(e.map(({path:t,contentHash:n})=>({path:t,contentHash:n}))))}function or(e){let t=Te(e),n=new Map(t.ir.files.map(c=>[c.path,c])),r=[],s=new Set,a=[];for(let c of e.changes){let f=c.path.replace(/\\/g,"/"),y=Q(c.path);if(!y||y===".."||y.startsWith("../")||f.startsWith("/")||/^[A-Za-z]:\//.test(f)||f.includes("\0")){a.push({ruleId:"INVALID_CHANGE_PATH",file:"<change-set>",line:1,message:"Every change requires a safe, non-empty project-relative path."});continue}if(s.has(y)){a.push({ruleId:"DUPLICATE_CHANGE_PATH",file:y,line:1,message:`The atomic change set contains more than one operation for ${y}.`});continue}s.add(y),"delete"in c&&c.delete&&!n.has(y)&&a.push({ruleId:"DELETE_TARGET_MISSING",file:y,line:1,message:`Cannot delete ${y} because it is not present in the supplied base tree.`}),r.push("delete"in c&&c.delete?{path:y,delete:!0}:{path:y,content:"content"in c?c.content:""})}e.changes.length===0&&a.push({ruleId:"CHANGE_SET_EMPTY",file:"<change-set>",line:1,message:"Atomic preflight requires at least one create, update, or delete."});let i=it({...e,changes:r}),d=new Map(i.ir.files.map(c=>[c.path,c])),p=i.ir.violations.filter(c=>c.ruleId==="CAPABILITY_VIOLATION"||c.ruleId==="FORBIDDEN_GLOBAL").map(c=>{let f=d.get(c.evidence.file)?.layer;return{ruleId:c.ruleId,file:c.evidence.file,line:c.evidence.line,target:c.symbol,...c.capability?{capability:c.capability}:{},...f?{fromLayer:f}:{},edgeKind:"import",message:c.message}}),b=ge({config:e.contract.config,rules:e.contract.config.rules,files:i.ir.files.map(c=>c.path),contentViolations:p,edges:i.ir.edges.filter(c=>!!c.fromLayer).map(c=>({from:c.from,fromLayer:c.fromLayer,...c.to?{to:c.to}:{},...c.toLayer?{toLayer:c.toLayer}:{},line:c.evidence.line,kind:"import",...c.typeOnly?{typeOnly:!0}:{},...c.namedBindingsTypeOnly?{namedBindingsTypeOnly:!0}:{}}))}),A=r.map(c=>{let f=Q(c.path),y=n.get(f),R=d.get(f);return{path:f,operation:"delete"in c&&c.delete?"delete":y?"update":"create",...y?{beforeContentHash:y.contentHash}:{},...R?{candidateContentHash:R.contentHash}:{}}}).sort((c,f)=>c.path.localeCompare(f.path)),h=[...a,...b.violations].map(c=>({...c,nextAction:_e(c)})),o=h.filter(c=>c.failsStrict!==!1),l=e.changeMap?be({changeMap:e.changeMap,changes:A,baseDependencies:t.ir.edges.flatMap(c=>c.to?[{from:c.from,to:c.to}]:[]),candidateDependencies:i.ir.edges.flatMap(c=>c.to?[{from:c.from,to:c.to}]:[])}):void 0;return{schemaVersion:"1.0",mode:"lexical-compatibility",valid:t.completeness==="complete"&&i.valid&&o.length===0&&(l?.structurallyConverged??!0),readOnly:!0,policyHash:e.contract.policyHash,compilerOptionsHash:i.ir.compilerOptionsHash,baseTreeHash:Jt(t.ir.files),candidateTreeHash:Jt(i.ir.files),baseCompleteness:t.completeness,candidateCompleteness:i.completeness,baseCompletenessReasons:t.completenessReasons,candidateCompletenessReasons:i.completenessReasons,...e.changeMap?{changeMapHash:e.changeMap.hash}:{},...l?{convergence:l}:{},changes:A,violations:h,warnings:b.warnings}}function lr(e){let t=e.replace(/\\/g,"/");if(!t||t.startsWith("/")||/^[A-Za-z]:\//.test(t)||t.includes("\0"))return;let n=[];for(let s of t.split("/"))if(!(!s||s==="."))if(s===".."){if(n.length===0)return;n.pop()}else n.push(s);let r=n.join("/");return r&&r===t?r:void 0}function cr(e,t){return[["resolverIdentity",e.resolverIdentity,t.resolverIdentity],["compilerIdentity",e.compilerIdentity,t.compilerIdentity],["evidenceRequirementsHash",e.evidenceRequirementsHash,t.evidenceRequirementsHash],["projectPackageName",e.projectPackageName??"",t.projectPackageName??""]].filter(([,r,s])=>r!==s).map(([r,s,a])=>({ruleId:"FACTS_IDENTITY_MISMATCH",file:"<change-set>",line:1,field:r,before:s,candidate:a,message:`Base and candidate facts must use the same ${r}.`}))}function dr(e,t,n,r){let s=n.get(t),a=r.get(t);return{path:t,operation:"delete"in e&&e.delete?"delete":s?"update":"create",...s?{beforeContentHash:s.contentHash}:{},...a?{candidateContentHash:a.contentHash}:{}}}function pr(e){let t=W(e.baseFacts),n=W(e.candidateFacts),r=$e({contract:e.contract,facts:t}),s=$e({contract:e.contract,facts:n}),a=new Map(t.files.map(l=>[l.path,l])),i=new Map(n.files.map(l=>[l.path,l])),d=cr(t,n),p=new Map,b=[];for(let l of e.changes){let c=lr(l.path);if(!c){d.push({ruleId:"INVALID_CHANGE_PATH",file:"<change-set>",line:1,message:"Every change requires a canonical project-relative path."});continue}if(p.has(c)){d.push({ruleId:"DUPLICATE_CHANGE_PATH",file:c,line:1,message:`The atomic change set contains more than one operation for ${c}.`});continue}p.set(c,l);let f=a.get(c),y=i.get(c);if("delete"in l&&l.delete)f||d.push({ruleId:"DELETE_TARGET_MISSING",file:c,line:1,message:`Cannot delete ${c} because it is not present in the supplied base facts.`}),y&&d.push({ruleId:"CANDIDATE_DELETE_NOT_APPLIED",file:c,line:1,message:`Candidate facts still contain deleted file ${c}.`});else{let R="content"in l?l.content:"",u=E(R);y?y.contentHash!==u&&d.push({ruleId:"CANDIDATE_CONTENT_HASH_MISMATCH",file:c,line:1,expectedContentHash:u,candidateContentHash:y.contentHash,message:`Candidate facts for ${c} do not match the declared content.`}):d.push({ruleId:"CANDIDATE_CHANGE_MISSING",file:c,line:1,message:`Candidate facts do not contain changed file ${c}.`})}b.push(dr(l,c,a,i))}e.changes.length===0&&d.push({ruleId:"CHANGE_SET_EMPTY",file:"<change-set>",line:1,message:"Atomic preflight requires at least one create, update, or delete."});for(let l of new Set([...a.keys(),...i.keys()])){if(p.has(l))continue;let c=a.get(l),f=i.get(l);c&&f&&S(c)===S(f)||d.push({ruleId:"UNDECLARED_CANDIDATE_CHANGE",file:l,line:1,message:`Candidate facts change ${l}, but the atomic change set does not declare it.`})}let A=e.changeMap?be({changeMap:e.changeMap,changes:b,baseDependencies:r.ir.edges.flatMap(l=>l.to?[{from:l.from,to:l.to}]:[]),candidateDependencies:s.ir.edges.flatMap(l=>l.to?[{from:l.from,to:l.to}]:[])}):void 0,h=[...d,...s.ir.violations].map(l=>({...l,nextAction:_e(l)})),o=h.filter(l=>l.failsStrict!==!1);return{schemaVersion:"1.0",mode:"resolved-candidate-facts",valid:r.completeness==="complete"&&s.strictValid&&o.length===0&&(A?.structurallyConverged??!0),readOnly:!0,policyHash:e.contract.policyHash,resolverIdentity:n.resolverIdentity,compilerIdentity:n.compilerIdentity,compilerOptionsHash:n.compilerOptionsHash,tsconfigHash:n.tsconfigHash,baseCompilerOptionsHash:t.compilerOptionsHash,candidateCompilerOptionsHash:n.compilerOptionsHash,baseTsconfigHash:t.tsconfigHash,candidateTsconfigHash:n.tsconfigHash,evidenceRequirementsHash:n.evidenceRequirementsHash,baseFactsHash:t.factsHash,candidateFactsHash:n.factsHash,baseTreeHash:t.candidateTreeHash,candidateTreeHash:n.candidateTreeHash,baseCompleteness:r.completeness,candidateCompleteness:s.completeness,baseCompletenessReasons:r.completenessReasons,candidateCompletenessReasons:s.completenessReasons,...e.changeMap?{changeMapHash:e.changeMap.hash}:{},...A?{convergence:A}:{},changes:b.sort((l,c)=>l.path<c.path?-1:l.path>c.path?1:0),violations:h,warnings:s.ir.warnings}}var Zt=new WeakSet;function Xt(e){if(!e||typeof e!="object"||Object.isFrozen(e))return e;for(let t of Object.values(e))Xt(t);return Object.freeze(e)}function Ys(e){let t=Xt(Ie(e));return Zt.add(t),t}function Ws(e){if(!Zt.has(e.facts))throw new Error("Trusted resolved analysis requires immutable in-process canonical facts.");return Ye(e)}export{De as AMBIENT_CAPABILITY_ENTRIES,Me as CAPABILITY_IDS,Ge as DEFAULT_INTENT_PREFIXES,ut as RESOLVED_CANDIDATE_FACTS_SCHEMA,ee as RESOLVED_CANDIDATE_FACTS_SCHEMA_VERSION,Ue as SOURCE_POLICY_MESSAGES,je as ambientCoveredByForbiddenGlobals,be as analyzeArchitectureConvergence,it as analyzeChange,ar as analyzePolicyDelta,Te as analyzeProject,$e as analyzeResolvedProject,Ws as analyzeTrustedResolvedProject,ue as capabilityForAmbientName,pe as capabilityForModuleSpecifier,ze as classifyPublishFacts,Ke as collectAnalysisConfigWarnings,Hn as collectCapabilityUses,tt as collectForbiddenCapabilityUses,Ie as createResolvedCandidateFacts,Ys as createTrustedResolvedCandidateFacts,wt as detectArchitectureCycles,E as deterministicHash,se as effectiveCapabilityDeny,ge as evaluateArchitectureGraph,ir as explainViolation,et as extractSemanticDependencies,fe as forbiddenGlobalForModuleSpecifier,Ln as loadArchitectureChangeMap,at as loadContract,W as loadResolvedCandidateFacts,bt as looksLikeArkIntent,an as lowerForbiddenGlobal,Se as loweredLayerCoverage,or as preflightChange,pr as preflightResolvedChange,qe as resolveIntentLayer,ve as resolvedFactsEvidenceRequirementsHash,S as stableSerialize};
+`).length,d={kind:"import",file:e.path,line:i,excerpt:s.excerpt},p=tr(e.path,a,t);n.push({from:e.path,specifier:a,to:p?.path??null,resolution:p?"resolved":"unresolved",fromLayer:e.layer,toLayer:p?.layer??null,evidence:d})}return{edges:n,capabilityUses:r}}function tr(e,t,n){let r=e.split("/");r.pop();for(let a of t.split("/"))a==="."||a===""||(a===".."?r.pop():r.push(a));let s=r.join("/");for(let a of[s,`${s}.ts`,`${s}.tsx`,`${s}.mts`,`${s}.cts`,`${s}/index.ts`,`${s}/index.tsx`]){let i=n.get(a);if(i)return i}}function Wt(e,t){let n=[];for(let r of e){if(!r.to||!r.fromLayer||!r.toLayer)continue;let s=ae(t.rules,r.fromLayer,r.toLayer,{fromPath:r.from,toPath:r.to,layers:t.layers});s&&n.push({ruleId:`layer-dependency:${s.from}->${s.to}`,message:s.message??`${s.from} must not depend on ${s.to}.`,edge:r,evidence:r.evidence})}return n}var nr={code:"LEXICAL_EVIDENCE_INCOMPLETE",message:"Lexical compatibility mode cannot prove parse status, TypeScript/package/symlink resolution, or symbol-aware source-policy and safety evidence. Use the resolved candidate facts APIs for an authoritative verdict."};function rr(e,t){return e.arkRules!==void 0&&Object.keys(e.arkRules).length>0||t.structure.length>0||t.invariants.length>0}function sr(e,t){return rr(e,t)?E(S(Dt({config:e,arkRules:t,warnings:[]}))):E(S(e))}function at(e,t,n){let r=typeof e=="string"?Ht(e,t):st(e,t),s=n?.arkRules??me();return{...r,arkRules:s,policyHash:sr(r.config,s)}}function ar(e){let t=at(e.baseConfig,e.baseSource??"base ark.config.json",{arkRules:e.baseArkRules}),n=at(e.candidateConfig,e.candidateSource??"candidate ark.config.json",{arkRules:e.candidateArkRules}),r=Gt(t.config,n.config,{baseArkRules:t.arkRules,candidateArkRules:n.arkRules,candidateInvariantCoverage:e.candidateInvariantCoverage}),s=r.findings.filter(d=>d.classification==="weakening"||d.classification==="judgment-required").map(d=>d.id).sort(),a=s.length>0,i=a&&qt(e.acknowledgement,{basePolicyHash:t.policyHash,candidatePolicyHash:n.policyHash,findingIds:s});return{schemaVersion:r.schemaVersion,basePolicyHash:t.policyHash,candidatePolicyHash:n.policyHash,classification:r.classification,findings:r.findings,blockingFindingIds:s,requiresAcknowledgement:a,acknowledged:i,valid:!a||i}}function Te(e){let t=e.files.map(h=>{let o=Q(h.path);return{path:o,content:h.content,contentHash:E(h.content),layer:V(o,e.contract.config.layers)??null}}).sort((h,o)=>h.path.localeCompare(o.path)),n=new Map(t.map(h=>[h.path,h])),r=[],s=[];for(let h of t){let o=Yt(h,n);r.push(...o.edges),s.push(...o.capabilityUses)}let a=Wt(r,e.contract.config),i=new Map(e.contract.config.layers.map(h=>[h.name,h])),d=new Map(e.contract.config.layers.map(h=>[h.name,new Set(se(h))]));for(let h of s){let o=n.get(h.file)?.layer;if(!o)continue;let l=i.get(o),c=fe(h.symbol,l?.forbiddenGlobals??[]);if(c){a.push({ruleId:"FORBIDDEN_GLOBAL",message:`${o} must not use module "${h.symbol}" because it is the import form of forbidden global "${c}".`,symbol:h.symbol,evidence:h.evidence});continue}d.get(o)?.has(h.capability)&&a.push({ruleId:"CAPABILITY_VIOLATION",message:`${o} denies the ${h.capability} capability; found import of "${h.symbol}".`,capability:h.capability,symbol:h.symbol,evidence:h.evidence})}let p=t.length===0?"complete":"partial",b=p==="complete"?[]:[{...nr}],A={schemaVersion:mt,policyHash:e.contract.policyHash,compilerOptionsHash:E(S(e.compilerOptions??{})),files:t,layers:e.contract.config.layers.map(h=>h.name),edges:r,capabilityUses:s,violations:a};return{mode:"lexical-compatibility",completeness:p,completenessReasons:b,valid:p==="complete"&&a.length===0,ir:A}}function it(e){let t=new Map(e.files.map(n=>[Q(n.path),n]));for(let n of e.changes){let r=Q(n.path);"delete"in n&&n.delete?t.delete(r):"content"in n&&t.set(r,{path:r,content:n.content})}return Te({contract:e.contract,files:[...t.values()],compilerOptions:e.compilerOptions})}function ir(e){let t=`${e.evidence.file}:${e.evidence.line}`;if(!e.edge)return`${e.ruleId} at ${t}: ${e.message}`;let n=e.edge.to??e.edge.specifier;return`${e.ruleId} at ${t}: ${e.edge.from} imports ${n}. ${e.message}`}function _e(e){switch(e.ruleId){case"LAYER_IMPORT_VIOLATION":return e.typeOnly||e.targetTypeOnlyExports||e.namedBindingsTypeOnly?"Move the referenced type to a mutually allowed layer, use `import type`, then preflight again.":e.peerIsolation?"Extract the shared dependency to a shared layer, test at the public interface, then preflight again.":`Define a port in ${e.fromLayer??"the source layer"}, inject the ${e.toLayer??"outer-layer"} implementation, test at the public interface, then preflight again.`;case"FORBIDDEN_GLOBAL":return`Inject ${e.target??"the capability"} through a port, test at the public interface, then preflight again.`;case"CAPABILITY_VIOLATION":return`Define a ${String(e.capability??"capability")} port in ${e.fromLayer??"the walled layer"}, bind the implementation outside it, test at the public interface, then preflight again.`;case"CIRCULAR_DEPENDENCY":return"Extract the shared dependency into a third module, test at the public interface, then preflight again.";case"RAW_EVENT_PUBLISH":return"Publish through a registered intent creator, then run Ark again.";case"PUBLISH_MISSING_SOURCE":return"Add metadata.source to the publish call, then run Ark again.";case"ARKRULE_STRUCTURE":case"ARKRULE_INVARIANT":case"INVARIANT_UNCOVERED":return`Fix the structure or invariant for ${typeof e.arkruleId=="string"&&e.arkruleId.length>0?e.arkruleId:"the ArkRule"} (declared in ${typeof e.arkruleSource=="string"&&e.arkruleSource.length>0?e.arkruleSource:"arkrules/<Layer>.json"}), then preflight again. Do not demote the rule without a hash-bound policy acknowledgement.`;default:return typeof e.ruleId=="string"&&e.ruleId.startsWith("ARKRULE_")?`Fix the ArkRule ${typeof e.arkruleId=="string"?e.arkruleId:e.ruleId}, then preflight again.`:`Resolve ${typeof e.ruleId=="string"&&e.ruleId.length>0?e.ruleId:"ARK_UNKNOWN"} without weakening ark.config.json, then run Ark again.`}}function Jt(e){return E(S(e.map(({path:t,contentHash:n})=>({path:t,contentHash:n}))))}function or(e){let t=Te(e),n=new Map(t.ir.files.map(c=>[c.path,c])),r=[],s=new Set,a=[];for(let c of e.changes){let f=c.path.replace(/\\/g,"/"),y=Q(c.path);if(!y||y===".."||y.startsWith("../")||f.startsWith("/")||/^[A-Za-z]:\//.test(f)||f.includes("\0")){a.push({ruleId:"INVALID_CHANGE_PATH",file:"<change-set>",line:1,message:"Every change requires a safe, non-empty project-relative path."});continue}if(s.has(y)){a.push({ruleId:"DUPLICATE_CHANGE_PATH",file:y,line:1,message:`The atomic change set contains more than one operation for ${y}.`});continue}s.add(y),"delete"in c&&c.delete&&!n.has(y)&&a.push({ruleId:"DELETE_TARGET_MISSING",file:y,line:1,message:`Cannot delete ${y} because it is not present in the supplied base tree.`}),r.push("delete"in c&&c.delete?{path:y,delete:!0}:{path:y,content:"content"in c?c.content:""})}e.changes.length===0&&a.push({ruleId:"CHANGE_SET_EMPTY",file:"<change-set>",line:1,message:"Atomic preflight requires at least one create, update, or delete."});let i=it({...e,changes:r}),d=new Map(i.ir.files.map(c=>[c.path,c])),p=i.ir.violations.filter(c=>c.ruleId==="CAPABILITY_VIOLATION"||c.ruleId==="FORBIDDEN_GLOBAL").map(c=>{let f=d.get(c.evidence.file)?.layer;return{ruleId:c.ruleId,file:c.evidence.file,line:c.evidence.line,target:c.symbol,...c.capability?{capability:c.capability}:{},...f?{fromLayer:f}:{},edgeKind:"import",message:c.message}}),b=ge({config:e.contract.config,rules:e.contract.config.rules,files:i.ir.files.map(c=>c.path),contentViolations:p,edges:i.ir.edges.filter(c=>!!c.fromLayer).map(c=>({from:c.from,fromLayer:c.fromLayer,...c.to?{to:c.to}:{},...c.toLayer?{toLayer:c.toLayer}:{},line:c.evidence.line,kind:"import",...c.typeOnly?{typeOnly:!0}:{},...c.namedBindingsTypeOnly?{namedBindingsTypeOnly:!0}:{}}))}),A=r.map(c=>{let f=Q(c.path),y=n.get(f),R=d.get(f);return{path:f,operation:"delete"in c&&c.delete?"delete":y?"update":"create",...y?{beforeContentHash:y.contentHash}:{},...R?{candidateContentHash:R.contentHash}:{}}}).sort((c,f)=>c.path.localeCompare(f.path)),h=[...a,...b.violations].map(c=>({...c,nextAction:_e(c)})),o=h.filter(c=>c.failsStrict!==!1),l=e.changeMap?be({changeMap:e.changeMap,changes:A,baseDependencies:t.ir.edges.flatMap(c=>c.to?[{from:c.from,to:c.to}]:[]),candidateDependencies:i.ir.edges.flatMap(c=>c.to?[{from:c.from,to:c.to}]:[])}):void 0;return{schemaVersion:"1.0",mode:"lexical-compatibility",valid:t.completeness==="complete"&&i.valid&&o.length===0&&(l?.structurallyConverged??!0),readOnly:!0,policyHash:e.contract.policyHash,compilerOptionsHash:i.ir.compilerOptionsHash,baseTreeHash:Jt(t.ir.files),candidateTreeHash:Jt(i.ir.files),baseCompleteness:t.completeness,candidateCompleteness:i.completeness,baseCompletenessReasons:t.completenessReasons,candidateCompletenessReasons:i.completenessReasons,...e.changeMap?{changeMapHash:e.changeMap.hash}:{},...l?{convergence:l}:{},changes:A,violations:h,warnings:b.warnings}}function lr(e){let t=e.replace(/\\/g,"/");if(!t||t.startsWith("/")||/^[A-Za-z]:\//.test(t)||t.includes("\0"))return;let n=[];for(let s of t.split("/"))if(!(!s||s==="."))if(s===".."){if(n.length===0)return;n.pop()}else n.push(s);let r=n.join("/");return r&&r===t?r:void 0}function cr(e,t){return[["resolverIdentity",e.resolverIdentity,t.resolverIdentity],["compilerIdentity",e.compilerIdentity,t.compilerIdentity],["evidenceRequirementsHash",e.evidenceRequirementsHash,t.evidenceRequirementsHash],["projectPackageName",e.projectPackageName??"",t.projectPackageName??""]].filter(([,r,s])=>r!==s).map(([r,s,a])=>({ruleId:"FACTS_IDENTITY_MISMATCH",file:"<change-set>",line:1,field:r,before:s,candidate:a,message:`Base and candidate facts must use the same ${r}.`}))}function dr(e,t,n,r){let s=n.get(t),a=r.get(t);return{path:t,operation:"delete"in e&&e.delete?"delete":s?"update":"create",...s?{beforeContentHash:s.contentHash}:{},...a?{candidateContentHash:a.contentHash}:{}}}function pr(e){let t=W(e.baseFacts),n=W(e.candidateFacts),r=$e({contract:e.contract,facts:t}),s=$e({contract:e.contract,facts:n}),a=new Map(t.files.map(l=>[l.path,l])),i=new Map(n.files.map(l=>[l.path,l])),d=cr(t,n),p=new Map,b=[];for(let l of e.changes){let c=lr(l.path);if(!c){d.push({ruleId:"INVALID_CHANGE_PATH",file:"<change-set>",line:1,message:"Every change requires a canonical project-relative path."});continue}if(p.has(c)){d.push({ruleId:"DUPLICATE_CHANGE_PATH",file:c,line:1,message:`The atomic change set contains more than one operation for ${c}.`});continue}p.set(c,l);let f=a.get(c),y=i.get(c);if("delete"in l&&l.delete)f||d.push({ruleId:"DELETE_TARGET_MISSING",file:c,line:1,message:`Cannot delete ${c} because it is not present in the supplied base facts.`}),y&&d.push({ruleId:"CANDIDATE_DELETE_NOT_APPLIED",file:c,line:1,message:`Candidate facts still contain deleted file ${c}.`});else{let R="content"in l?l.content:"",u=E(R);y?y.contentHash!==u&&d.push({ruleId:"CANDIDATE_CONTENT_HASH_MISMATCH",file:c,line:1,expectedContentHash:u,candidateContentHash:y.contentHash,message:`Candidate facts for ${c} do not match the declared content.`}):d.push({ruleId:"CANDIDATE_CHANGE_MISSING",file:c,line:1,message:`Candidate facts do not contain changed file ${c}.`})}b.push(dr(l,c,a,i))}e.changes.length===0&&d.push({ruleId:"CHANGE_SET_EMPTY",file:"<change-set>",line:1,message:"Atomic preflight requires at least one create, update, or delete."});for(let l of new Set([...a.keys(),...i.keys()])){if(p.has(l))continue;let c=a.get(l),f=i.get(l);c&&f&&S(c)===S(f)||d.push({ruleId:"UNDECLARED_CANDIDATE_CHANGE",file:l,line:1,message:`Candidate facts change ${l}, but the atomic change set does not declare it.`})}let A=e.changeMap?be({changeMap:e.changeMap,changes:b,baseDependencies:r.ir.edges.flatMap(l=>l.to?[{from:l.from,to:l.to}]:[]),candidateDependencies:s.ir.edges.flatMap(l=>l.to?[{from:l.from,to:l.to}]:[])}):void 0,h=[...d,...s.ir.violations].map(l=>({...l,nextAction:_e(l)})),o=h.filter(l=>l.failsStrict!==!1);return{schemaVersion:"1.0",mode:"resolved-candidate-facts",valid:r.completeness==="complete"&&s.strictValid&&o.length===0&&(A?.structurallyConverged??!0),readOnly:!0,policyHash:e.contract.policyHash,resolverIdentity:n.resolverIdentity,compilerIdentity:n.compilerIdentity,compilerOptionsHash:n.compilerOptionsHash,tsconfigHash:n.tsconfigHash,baseCompilerOptionsHash:t.compilerOptionsHash,candidateCompilerOptionsHash:n.compilerOptionsHash,baseTsconfigHash:t.tsconfigHash,candidateTsconfigHash:n.tsconfigHash,evidenceRequirementsHash:n.evidenceRequirementsHash,baseFactsHash:t.factsHash,candidateFactsHash:n.factsHash,baseTreeHash:t.candidateTreeHash,candidateTreeHash:n.candidateTreeHash,baseCompleteness:r.completeness,candidateCompleteness:s.completeness,baseCompletenessReasons:r.completenessReasons,candidateCompletenessReasons:s.completenessReasons,...e.changeMap?{changeMapHash:e.changeMap.hash}:{},...A?{convergence:A}:{},changes:b.sort((l,c)=>l.path<c.path?-1:l.path>c.path?1:0),violations:h,warnings:s.ir.warnings}}var Zt=new WeakSet;function Xt(e){if(!e||typeof e!="object"||Object.isFrozen(e))return e;for(let t of Object.values(e))Xt(t);return Object.freeze(e)}function Ys(e){let t=Xt(Ie(e));return Zt.add(t),t}function Ws(e){if(!Zt.has(e.facts))throw new Error("Trusted resolved analysis requires immutable in-process canonical facts.");return Ye(e)}export{De as AMBIENT_CAPABILITY_ENTRIES,Me as CAPABILITY_IDS,Ge as DEFAULT_INTENT_PREFIXES,ut as RESOLVED_CANDIDATE_FACTS_SCHEMA,ee as RESOLVED_CANDIDATE_FACTS_SCHEMA_VERSION,Ue as SOURCE_POLICY_MESSAGES,je as ambientCoveredByForbiddenGlobals,be as analyzeArchitectureConvergence,it as analyzeChange,ar as analyzePolicyDelta,Te as analyzeProject,$e as analyzeResolvedProject,Ws as analyzeTrustedResolvedProject,ue as capabilityForAmbientName,pe as capabilityForModuleSpecifier,ze as classifyPublishFacts,Ke as collectAnalysisConfigWarnings,Hn as collectCapabilityUses,tt as collectForbiddenCapabilityUses,Ie as createResolvedCandidateFacts,Ys as createTrustedResolvedCandidateFacts,wt as detectArchitectureCycles,E as deterministicHash,se as effectiveCapabilityDeny,ge as evaluateArchitectureGraph,ir as explainViolation,et as extractSemanticDependencies,fe as forbiddenGlobalForModuleSpecifier,Ln as loadArchitectureChangeMap,at as loadContract,W as loadResolvedCandidateFacts,bt as looksLikeArkIntent,an as lowerForbiddenGlobal,Se as loweredLayerCoverage,or as preflightChange,pr as preflightResolvedChange,qe as resolveIntentLayer,ve as resolvedFactsEvidenceRequirementsHash,S as stableSerialize};

package/bin/lib/ci-and-commands.mjs

@@ -414,6 +414,11 @@ ${projectionBlock}
 - **Design-weak / residual shape lenses** (compass residual while edges may look green) → map first, then guided apply with user OK — never “you’re done” on green edges alone.
 - Empty plan A + residual lenses / design-weak → **not finished**.
 
+**Two-axis done (never collapse):**
+1. **Architecture residual** — status / doctor / compass (scan). Prefer deep modules; name seams; test at the public interface.
+2. **Feature / ticket residual** — does the change match the requested behavior? (process outside the package).
+**Enforce green ≠ feature done.** No package LLM verdict for either axis.
+
 The selected host is \`${selectedHost}\`. Host registration and CI are installed with this file.
 This compact router is enough for normal feature work.
 

package/bin/lib/deep-module-coach.mjs

@@ -0,0 +1,177 @@
+/**
+ * Deep-module coach advisory (Tooling) — hot paths + deepening candidates.
+ *
+ * Advisory only (`notAScore`). Never feeds valid / strict-merge / goal.met /
+ * completeness green. Hot paths use a bounded git log heuristic; incomplete or
+ * missing history → status `unavailable`, empty paths (never invent).
+ * Deepening candidates come only from existing smells / cohesion / compass /
+ * pilot evidence via Domain pure projection.
+ */
+import { spawnSync } from 'node:child_process';
+import {
+  buildDeepeningCandidates,
+  ARK_DEEPENING_COACH_SCHEMA_VERSION,
+  DEEPENING_CANDIDATE_CAP,
+} from './deepening-coach.mjs';
+
+export { buildDeepeningCandidates, ARK_DEEPENING_COACH_SCHEMA_VERSION, DEEPENING_CANDIDATE_CAP };
+
+/** Recent-window commit cap for hot-path heuristic (budget). */
+export const HOT_PATH_COMMIT_LIMIT = 200;
+/** Max listed hot paths. */
+export const HOT_PATH_LIST_CAP = 8;
+/** Minimum change hits before a path is “elevated”. */
+export const HOT_PATH_MIN_HITS = 3;
+
+/**
+ * Best-effort recent-churn paths from git history.
+ * @param {string} root
+ * @param {{ runGit?: Function, commitLimit?: number, minHits?: number, listCap?: number }} [opts]
+ */
+export function computeHotPathAdvisory(root, opts = {}) {
+  const commitLimit = Number(opts.commitLimit) > 0 ? Number(opts.commitLimit) : HOT_PATH_COMMIT_LIMIT;
+  const minHits = Number(opts.minHits) > 0 ? Number(opts.minHits) : HOT_PATH_MIN_HITS;
+  const listCap = Number(opts.listCap) > 0 ? Number(opts.listCap) : HOT_PATH_LIST_CAP;
+  const runGit =
+    typeof opts.runGit === 'function'
+      ? opts.runGit
+      : (args) =>
+          spawnSync('git', ['-C', root, ...args], {
+            encoding: 'utf8',
+            maxBuffer: 8 * 1024 * 1024,
+            stdio: ['ignore', 'pipe', 'pipe'],
+          });
+
+  const emptyUnavailable = (reason) => ({
+    available: false,
+    status: 'unavailable',
+    reason,
+    paths: [],
+    notAScore: true,
+  });
+
+  try {
+    const head = runGit(['rev-parse', '--verify', 'HEAD']);
+    if (!head || head.status !== 0) {
+      return emptyUnavailable('git history incomplete or missing (no HEAD)');
+    }
+
+    const log = runGit([
+      'log',
+      '-n',
+      String(commitLimit),
+      '--name-only',
+      '--pretty=format:',
+      '--diff-filter=AMR',
+    ]);
+    if (!log || log.status !== 0) {
+      return emptyUnavailable('git log unavailable for hot-path heuristic');
+    }
+
+    const counts = new Map();
+    const text = typeof log.stdout === 'string' ? log.stdout : '';
+    for (const line of text.split('\n')) {
+      const raw = line.trim().replace(/\\/g, '/');
+      if (!raw || raw.startsWith('.git/')) continue;
+      // Prefer product source; still allow other paths if they dominate.
+      counts.set(raw, (counts.get(raw) || 0) + 1);
+    }
+
+    if (counts.size === 0) {
+      return {
+        available: true,
+        status: 'ok',
+        reason: null,
+        paths: [],
+        notAScore: true,
+        window: { commitLimit, minHits },
+      };
+    }
+
+    const ranked = [...counts.entries()]
+      .filter(([, n]) => n >= minHits)
+      .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+      .slice(0, listCap)
+      .map(([path, changeCount]) => ({ path, changeCount }));
+
+    return {
+      available: true,
+      status: 'ok',
+      reason: null,
+      paths: ranked,
+      notAScore: true,
+      window: { commitLimit, minHits },
+    };
+  } catch {
+    return emptyUnavailable('git history incomplete or missing');
+  }
+}
+
+/**
+ * Full deep-module coach advisory for doctor / report.
+ * @param {string} root
+ * @param {{
+ *   designSmells?: object[],
+ *   physicalCohesion?: object | null,
+ *   improvementCompass?: object | null,
+ *   pilotLoop?: object | null,
+ *   runGit?: Function,
+ * }} [input]
+ */
+export function buildDeepModuleCoachAdvisory(root, input = {}) {
+  const deepening = buildDeepeningCandidates({
+    designSmells: input.designSmells,
+    physicalCohesion: input.physicalCohesion,
+    improvementCompass: input.improvementCompass,
+    pilotLoop: input.pilotLoop,
+  });
+  const hotPaths = computeHotPathAdvisory(root, {
+    runGit: input.runGit,
+  });
+
+  return {
+    schemaVersion: ARK_DEEPENING_COACH_SCHEMA_VERSION,
+    notAScore: true,
+    hotPaths,
+    deepeningCandidates: deepening.candidates,
+  };
+}
+
+/**
+ * Human doctor section (never a score bar). Always one short block when coach is present.
+ * @param {ReturnType<typeof buildDeepModuleCoachAdvisory>} coach
+ * @param {{ line: Function, warn: string, ok: string, color: { bold: Function, dim: Function } }} io
+ */
+export function printDeepModuleCoachSection(coach, io) {
+  if (!coach || coach.notAScore !== true) return;
+  const { line, warn, ok, color } = io;
+  const hot = coach.hotPaths || { status: 'unavailable', paths: [], reason: 'missing' };
+  const candidates = Array.isArray(coach.deepeningCandidates) ? coach.deepeningCandidates : [];
+  const paths = Array.isArray(hot.paths) ? hot.paths : [];
+
+  console.log('');
+  console.log(color.bold('Deep-module coach (advisory — not a score)'));
+
+  if (hot.status === 'unavailable') {
+    line(ok, color.dim(`Hot paths: unavailable — ${hot.reason || 'no git history'}; never invented.`));
+  } else if (paths.length > 0) {
+    line(warn, `Hot paths (recent churn heuristic, top ${paths.length}):`);
+    for (const row of paths.slice(0, HOT_PATH_LIST_CAP)) {
+      line(' ', color.dim(`${row.path} · ${row.changeCount} recent change(s)`));
+    }
+  } else {
+    line(ok, color.dim('Hot paths: none above churn threshold (advisory only).'));
+  }
+
+  if (candidates.length === 0) {
+    line(ok, color.dim('Deepening candidates: none from existing evidence.'));
+  } else {
+    line(warn, `Deepening candidates (${candidates.length}, from existing residual only):`);
+    for (const c of candidates.slice(0, DEEPENING_CANDIDATE_CAP)) {
+      line(' ', `${c.target} — ${c.friction}`);
+      if (c.intent) line(' ', color.dim(`intent: ${c.intent}`));
+      if (c.benefit) line(' ', color.dim(`benefit: ${c.benefit}`));
+    }
+  }
+  line(ok, color.dim('Never changes gate verdicts. Prefer deep modules; test at the public interface.'));
+}

package/bin/lib/deepening-coach.mjs

@@ -0,0 +1,177 @@
+/**
+ * GENERATED FILE — do not edit by hand.
+ *
+ * Canonical algorithm: src/domain/deepeningCoach.ts
+ * Regenerate: node scripts/generate-cli-pure.mjs
+ * Drift check: node scripts/generate-cli-pure.mjs --check
+ *
+ * Pure CLI helper (bin/lib/deepening-coach.mjs). Zero Node I/O.
+ */
+
+export const ARK_DEEPENING_COACH_SCHEMA_VERSION = '1.0';
+/** Cap on listed deepening candidates (agent-legible; not a ranking score). */
+export const DEEPENING_CANDIDATE_CAP = 5;
+function asString(value) {
+    return typeof value === 'string' ? value.trim() : '';
+}
+function firstEvidencePath(evidence) {
+    if (!Array.isArray(evidence))
+        return '';
+    for (const row of evidence) {
+        if (typeof row === 'string' && row.trim())
+            return row.trim().replace(/\\/g, '/');
+        if (row && typeof row === 'object') {
+            const path = asString(row.path)
+                || asString(row.file);
+            if (path)
+                return path.replace(/\\/g, '/');
+        }
+    }
+    return '';
+}
+function evidenceList(source, refs, detail) {
+    const out = [];
+    for (const ref of refs) {
+        const r = asString(ref);
+        if (!r)
+            continue;
+        out.push(detail ? { source, ref: r, detail } : { source, ref: r });
+    }
+    return out;
+}
+/**
+ * Project deepening candidates from existing doctor-side evidence only.
+ * Empty input / no residual → empty `candidates` (honesty: no fake list).
+ */
+export function buildDeepeningCandidates(input = {}) {
+    const candidates = [];
+    const seen = new Set();
+    const push = (candidate) => {
+        if (candidates.length >= DEEPENING_CANDIDATE_CAP)
+            return;
+        const key = `${candidate.target}|${candidate.friction}`.toLowerCase();
+        if (seen.has(key))
+            return;
+        if (!asString(candidate.target) || !asString(candidate.friction))
+            return;
+        seen.add(key);
+        candidates.push(candidate);
+    };
+    const pilot = input.pilotLoop?.active === true && input.pilotLoop.nextPilot
+        ? input.pilotLoop.nextPilot
+        : null;
+    if (pilot) {
+        // Require a real pilot identity — empty shells are not evidence.
+        const target = asString(pilot.pilotTarget) || asString(pilot.pilot) || asString(pilot.smellId);
+        if (target) {
+            push({
+                target,
+                friction: asString(pilot.smellId)
+                    ? `Shape pilot residual (${pilot.smellId}) — one extraction at a time`
+                    : 'Shape pilot residual — one extraction at a time',
+                intent: asString(pilot.move) ||
+                    'Deepen the public seam; hide implementation behind a small interface',
+                benefit: asString(pilot.successSignal) ||
+                    'Locality: change and tests concentrate at the public interface',
+                evidence: evidenceList('pilotLoop', [target], 'nextPilot'),
+            });
+        }
+    }
+    const smells = Array.isArray(input.designSmells) ? input.designSmells : [];
+    for (const smell of smells) {
+        if (!smell || typeof smell !== 'object')
+            continue;
+        const id = asString(smell.id);
+        const path = firstEvidencePath(smell.evidence);
+        // Require non-empty smell id or evidence path — whitespace shells are not evidence.
+        if (!id && !path)
+            continue;
+        const target = path || id;
+        const friction = asString(smell.outcome) || asString(smell.message) || `Design residual (${id || target})`;
+        push({
+            target,
+            friction,
+            intent: asString(smell.fix) ||
+                'Prefer a deep module at a named seam; apply the deletion test before pass-through extracts',
+            benefit: 'Leverage: callers learn a smaller interface; locality of change improves',
+            evidence: evidenceList('designSmells', path ? [path, id].filter(Boolean) : [id], id || undefined),
+        });
+    }
+    const pc = input.physicalCohesion;
+    const reshape = pc?.reshapePilot?.nextPilot;
+    if (reshape) {
+        const target = asString(reshape.pilotTarget) || asString(reshape.pilot);
+        if (target) {
+            push({
+                target,
+                friction: 'Physical cohesion residual — concept concentration across anchors',
+                intent: asString(reshape.move) ||
+                    'One reshape pilot toward locality; never mechanical-safe multi-file batch',
+                benefit: asString(reshape.successSignal) ||
+                    'Related behavior co-located; public seams stay small',
+                evidence: evidenceList('physicalCohesion', [target], 'reshapePilot'),
+            });
+        }
+    }
+    const findings = Array.isArray(pc?.findings) ? pc.findings : [];
+    for (const finding of findings) {
+        if (!finding || typeof finding !== 'object')
+            continue;
+        const concept = asString(finding.concept);
+        const anchors = Array.isArray(finding.anchors)
+            ? finding.anchors.map((a) => asString(a)).filter(Boolean)
+            : [];
+        const target = anchors[0] || concept;
+        if (!target)
+            continue;
+        push({
+            target,
+            friction: asString(finding.message) ||
+                (concept
+                    ? `Concept "${concept}" concentrated across physical anchors`
+                    : 'Physical cohesion residual'),
+            intent: 'Deepen by colocating behavior behind one public interface per concern',
+            benefit: 'Locality of change; fewer cross-anchor edits for one concept',
+            evidence: evidenceList('physicalCohesion', anchors.length > 0 ? anchors.slice(0, 3) : [target], concept || undefined),
+        });
+    }
+    const compass = input.improvementCompass;
+    if (compass && compass.notAScore === true) {
+        const residualIds = Array.isArray(compass.topResidual)
+            ? compass.topResidual.map((id) => asString(id)).filter(Boolean)
+            : [];
+        const lensById = new Map();
+        if (Array.isArray(compass.lenses)) {
+            for (const lens of compass.lenses) {
+                if (lens && typeof lens === 'object' && asString(lens.id)) {
+                    lensById.set(asString(lens.id), { summary: asString(lens.summary) || undefined });
+                }
+            }
+        }
+        for (const id of residualIds) {
+            // Each residual lens id is independent evidence. Cap + target|friction dedupe may
+            // still list both a smell card and lens:<id> — no cross-source suppression.
+            const summary = lensById.get(id)?.summary;
+            push({
+                target: `lens:${id}`,
+                friction: summary
+                    ? `Residual lens ${id}: ${summary}`
+                    : `Residual architecture lens ${id} (not a score)`,
+                intent: 'Process judgment: deepen modules / name seams that clear this lens residual',
+                benefit: 'Clear residual without inventing a depth score or gate fail',
+                evidence: evidenceList('improvementCompass', [id], 'topResidual'),
+            });
+        }
+    }
+    return {
+        schemaVersion: ARK_DEEPENING_COACH_SCHEMA_VERSION,
+        notAScore: true,
+        candidates,
+    };
+}
+/**
+ * True when the pure projection would list zero candidates (honesty helper for tests).
+ */
+export function hasNoDeepeningEvidence(input) {
+    return buildDeepeningCandidates(input).candidates.length === 0;
+}

package/bin/lib/doctor-plan.mjs

@@ -66,6 +66,10 @@ import {
   buildDoctorImprovementCompass,
   printImprovementCompassSection,
 } from './improvement-compass-doctor.mjs';
+import {
+  buildDeepModuleCoachAdvisory,
+  printDeepModuleCoachSection,
+} from './deep-module-coach.mjs';
 
 const color = {
   green: (s) => `\x1b[32m${s}\x1b[0m`,
@@ -660,6 +664,13 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
     goldenPatternPresent: goldenPattern.present === true,
     arkRulesLoaded: rulesUnderContract?.active === true,
   });
+  // Deep-module coach: hot paths + deepening candidates — advisory only (notAScore).
+  const deepModuleCoach = buildDeepModuleCoachAdvisory(root, {
+    designSmells,
+    physicalCohesion: doctorAdvisories.physicalCohesion,
+    improvementCompass,
+    pilotLoop,
+  });
 
   if (asJson) {
     (options.writeJson ?? console.log)(
@@ -677,6 +688,8 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
             designSmells,
             // Improvement compass (lenses; notAScore; never a gate input).
             improvementCompass,
+            // Deep-module coach (hot paths + deepening; notAScore; never a gate input).
+            deepModuleCoach,
             ...(options.designDelta ? { designDelta: options.designDelta } : {}),
             // Q01: primary next action when Shape residual dominates (null if not design-weak).
             postGreenPath,
@@ -870,6 +883,7 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
   }
 
   printImprovementCompassSection(improvementCompass, { line, warn, ok, color });
+  printDeepModuleCoachSection(deepModuleCoach, { line, warn, ok, color });
 
   console.log('');
   console.log(color.bold('Design fitness'));