scip-query 0.17.2 → 0.18.0

package/dist/runtime.js

@@ -1,2 +1,2 @@
-import{b as j,c as b,d as D,f,g as T,k as m,l as W}from"./chunk-SON6DQNK.js";import{a as k}from"./chunk-YZXV3CU3.js";import{c as g,d as y}from"./chunk-Z4MCFCGX.js";import{fork as $}from"child_process";import{statSync as _}from"fs";import{isAbsolute as F,join as G,relative as M}from"path";import{watch as N}from"chokidar";import A from"ignore";var S=class{projectRoot;config;watchConfig;languages;pnpmWorkspaces;typescriptProjectMode;typescriptProjects;clojureConfigPath;indexerConcurrency;onStatus;onReindexComplete;onError;status={state:"idle"};debounceTimer=null;cooldownTimer=null;dirty=!1;changedFiles=0;pendingTrigger=null;reindexInFlight=!1;lastReindexEnd=0;fsWatchers=[];gitPollTimer=null;lastGitState=null;gitignoreFilter;extraIgnore;stopped=!1;constructor(t){this.projectRoot=t.projectRoot,this.config=t.config,this.watchConfig=T(t.config),this.languages=t.languages,this.pnpmWorkspaces=t.config.indexer?.typescript?.pnpmWorkspaces??!1,this.typescriptProjectMode=t.config.indexer?.typescript?.projectMode,this.typescriptProjects=t.config.indexer?.typescript?.projects,this.clojureConfigPath=t.config.indexer?.clojure?.configPath,this.indexerConcurrency=t.config.indexerConcurrency,this.onStatus=t.onStatus??(()=>{}),this.onReindexComplete=t.onReindexComplete??(()=>{}),this.onError=t.onError??(e=>console.error(e.message)),this.gitignoreFilter=k(t.projectRoot),this.extraIgnore=A(),this.watchConfig.ignore.length>0&&this.extraIgnore.add(this.watchConfig.ignore)}start(){this.stopped=!1,this.setStatus({state:"idle"}),this.startGitStatePolling();try{let t=N(this.projectRoot,{ignoreInitial:!0,ignored:(e,i)=>this.isIgnoredWatchPath(e,i?.isDirectory()??!1)});t.on("all",(e,i)=>{this.stopped||this.handleFileChange(i)}),t.on("error",e=>{this.onError(new Error(`Failed to watch ${this.projectRoot}: ${String(e)}`))}),this.fsWatchers.push(t)}catch(t){this.onError(new Error(`Failed to watch ${this.projectRoot}: ${String(t)}`))}}stop(){this.stopped=!0;for(let t of this.fsWatchers)t.close();this.fsWatchers=[],this.clearDebounceTimer(),this.clearCooldownTimer(),this.clearGitPollTimer(),this.setStatus({state:"idle"})}requestRefresh(t,e={}){if(!e.immediate||this.reindexInFlight||this.status.state==="cooldown"){this.scheduleReindex(t);return}this.pendingTrigger=P(this.pendingTrigger,t),this.changedFiles+=1,this.clearDebounceTimer(),this.triggerReindex()}isIgnoredWatchPath(t,e){let i=this.relativeWatchPath(t);if(!i)return!1;let r=e?`${i}/`:i;return r===".git/"||r.startsWith(".git/")?!0:this.gitignoreFilter.isIgnored(r)||this.extraIgnore.ignores(r)}handleFileChange(t){let e=this.relativeWatchPath(t);!e||e===".."||e.startsWith("../")||e===".git"||e.startsWith(".git/")||this.gitignoreFilter.isIgnored(e)||this.extraIgnore.ignores(e)||e.endsWith("index.db")||e.endsWith("index.scip")||e.endsWith("index.db.tmp")||this.scheduleReindex({kind:"watch-source",detail:e})}relativeWatchPath(t){let e=F(t)?t:G(this.projectRoot,t);return M(this.projectRoot,e).replaceAll("\\","/")}scheduleReindex(t){if(this.pendingTrigger=P(this.pendingTrigger,t),this.changedFiles++,this.reindexInFlight){this.dirty=!0,this.setStatus({state:"indexing",startedAt:this.status.startedAt});return}if(this.status.state==="cooldown"){this.dirty=!0,this.setStatus({state:"cooldown",until:this.status.until,dirty:!0});return}this.clearDebounceTimer();let e=Date.now()+this.watchConfig.debounceMs;this.setStatus({state:"waiting",changedFiles:this.changedFiles,reindexAt:e}),this.debounceTimer=setTimeout(()=>{this.debounceTimer=null,this.triggerReindex()},this.watchConfig.debounceMs)}triggerReindex(){if(this.reindexInFlight||this.stopped)return;let t=Date.now()-this.lastReindexEnd;if(this.lastReindexEnd>0&&t<this.watchConfig.cooldownMs){let r=this.watchConfig.cooldownMs-t;this.dirty=!0;let o=Date.now()+r;this.setStatus({state:"cooldown",until:o,dirty:!0}),this.cooldownTimer=setTimeout(()=>{this.cooldownTimer=null,this.dirty&&!this.stopped&&(this.dirty=!1,this.triggerReindex())},r);return}this.reindexInFlight=!0,this.dirty=!1,this.changedFiles=0;let e=this.pendingTrigger??{kind:"watch-source"};this.pendingTrigger=null;let i=Date.now();this.setStatus({state:"indexing",startedAt:i}),this.runReindex(e).then(r=>{if(this.reindexInFlight=!1,this.lastReindexEnd=Date.now(),this.onReindexComplete(r),this.dirty&&!this.stopped){let o=Date.now()+this.watchConfig.cooldownMs;this.setStatus({state:"cooldown",until:o,dirty:!0}),this.cooldownTimer=setTimeout(()=>{this.cooldownTimer=null,this.dirty&&!this.stopped?(this.dirty=!1,this.triggerReindex()):this.setStatus({state:"idle"})},this.watchConfig.cooldownMs)}else this.setStatus({state:"idle"})}).catch(r=>{this.reindexInFlight=!1,this.lastReindexEnd=Date.now(),this.onError(r instanceof Error?r:new Error(String(r))),this.setStatus({state:"idle"})})}runReindex(t){return new Promise((e,i)=>{let r=Date.now(),o=f(this.projectRoot),n=Object.keys(o).length>0?o:this.config,c=m(this.projectRoot,n),a=n.indexer?.typescript,l=n.indexer?.clojure,h=$(new URL("./reindex-worker.js",import.meta.url).pathname,[],{detached:!0,env:{...process.env,SCIP_REINDEX_PROJECT_ROOT:this.projectRoot,SCIP_REINDEX_OUTPUT_SCIP:c.indexPath,SCIP_REINDEX_OUTPUT_DB:c.dbPath,SCIP_REINDEX_LANGUAGES:(n.languages??this.languages)?.join(",")??"",SCIP_REINDEX_INDEXER_CONCURRENCY:String(n.indexerConcurrency??this.indexerConcurrency??""),SCIP_REINDEX_PNPM_WORKSPACES:a?.pnpmWorkspaces??this.pnpmWorkspaces?"1":"",SCIP_REINDEX_TYPESCRIPT_CONFIG:JSON.stringify({projectMode:a?.projectMode??this.typescriptProjectMode,projects:a?.projects??this.typescriptProjects??[]}),SCIP_REINDEX_CLOJURE_CONFIG_PATH:l?.configPath??this.clojureConfigPath??"",SCIP_REINDEX_TRIGGER_KIND:t.kind,SCIP_REINDEX_TRIGGER_DETAIL:t.detail??""},stdio:"pipe"});h.on("exit",d=>{d===0?e(Date.now()-r):i(new Error(`Reindex worker exited with code ${d}`))}),h.on("error",i)})}setStatus(t){this.status=t,this.onStatus(t)}clearDebounceTimer(){this.debounceTimer&&(clearTimeout(this.debounceTimer),this.debounceTimer=null)}clearCooldownTimer(){this.cooldownTimer&&(clearTimeout(this.cooldownTimer),this.cooldownTimer=null)}startGitStatePolling(){this.lastGitState=this.readGitState(),this.lastGitState&&(this.gitPollTimer=setInterval(()=>this.pollGitState(),this.watchConfig.gitPollMs),this.gitPollTimer.unref?.())}pollGitState(){let t=this.lastGitState,e=this.readGitState();if(!t||!e||this.stopped){this.lastGitState=e;return}this.lastGitState=e;let i=t.head!==e.head,r=t.indexPath!==e.indexPath||t.indexMtimeMs!==e.indexMtimeMs||t.indexSize!==e.indexSize;i&&r?this.scheduleReindex({kind:"watch-git-state",detail:"HEAD and index changed"}):i?this.scheduleReindex({kind:"watch-git-head",detail:"HEAD changed"}):r&&this.scheduleReindex({kind:"watch-git-index",detail:e.indexPath??"index changed"})}readGitState(){let t=g(this.projectRoot,["rev-parse","--git-path","index"]);if(!t)return null;let e=y(this.projectRoot,t),i={head:g(this.projectRoot,["rev-parse","--verify","HEAD"]),indexPath:e};try{let r=_(e);i.indexMtimeMs=r.mtimeMs,i.indexSize=r.size}catch{i.indexMtimeMs=void 0,i.indexSize=void 0}return i}clearGitPollTimer(){this.gitPollTimer&&(clearInterval(this.gitPollTimer),this.gitPollTimer=null)}};function P(s,t){return s?s.kind===t.kind?s.detail===t.detail?s:{kind:s.kind,detail:"multiple changes"}:{kind:"watch-git-state",detail:`${s.kind}, ${t.kind}`}:t}import{existsSync as x,mkdirSync as O,symlinkSync as L,readlinkSync as I,unlinkSync as w,readdirSync as U}from"fs";import{join as p,dirname as R,resolve as u,relative as X,isAbsolute as q}from"path";import{homedir as v,platform as H}from"os";import{fileURLToPath as z}from"url";var J=H()==="win32",C=["_shared","scip-query","scip-setup","scip-calibrate","scip-cleanup-audit","scip-cleanup-improve","scip-integrity-audit","scip-twin-drift","scip-claim-audit","scip-probe-reachability","scip-hyper-optimization","scip-api-impact","scip-concrete-plan","scip-conductor","scip-debug","scip-explore","scip-triage-issue","scip-diagram","scip-doc-reconcile","scip-directory-architecture","scip-maintainability","scip-react-maintainability","scip-vue-maintainability","scip-verify","scip-language-playbook","scip-tla-model-system"];function K(s={}){let t=s.quiet?()=>{}:console.log,e=z(import.meta.url),i=u(R(e),"..","skills"),r=[p(v(),".claude","skills"),p(v(),".codex","skills"),p(v(),".agents","skills")],o={installed:[],skipped:[],alreadyLinked:[],pruned:[]};for(let n of r){let c=R(n);if(!x(c))continue;O(n,{recursive:!0});let a=Y(n);B(n,i,a,o,t);for(let l of C){let h=p(i,l),d=p(n,l);if(!x(h)){o.skipped.push(`${a}/${l}`);continue}if(x(d)){try{let E=I(d);if(u(E)===u(h)){o.alreadyLinked.push(`${a}/${l}`),t(`  ok:   ${l} \u2192 ${a} (already linked)`);continue}}catch{o.skipped.push(`${a}/${l}`),t(`  skip: ${l} \u2192 ${a} (exists, not a symlink)`);continue}w(d)}L(h,d,J?"junction":"dir"),o.installed.push(`${a}/${l}`),t(`  done: ${l} \u2192 ${a}`)}}return o}function B(s,t,e,i,r){let o=new Set(C);for(let n of U(s)){if(o.has(n))continue;let c=p(s,n),a;try{a=u(R(c),I(c))}catch{continue}V(a,t)&&(w(c),i.pruned.push(`${e}/${n}`),r(`  prune: ${n} \u2192 ${e} (removed stale scip-query skill link)`))}}function V(s,t){let e=X(u(t),u(s));return e===""||!e.startsWith("..")&&!q(e)}function Y(s){return s.includes(".codex")?"Codex":s.includes(".agents")?"Agents":"Claude"}export{S as Watcher,b as getScipVersion,W as initProjectConfig,K as installSkills,j as isScipInstalled,f as loadProjectConfig,D as printScipInstallInstructions,m as resolveIndexStoragePaths};
+import{b as j,c as b,d as D,f,g as T,k as m,l as W}from"./chunk-EMEXMHOP.js";import{a as k}from"./chunk-YZXV3CU3.js";import{e as g,f as y}from"./chunk-GWNE2WJN.js";import{fork as $}from"child_process";import{statSync as _}from"fs";import{isAbsolute as F,join as G,relative as M}from"path";import{watch as N}from"chokidar";import A from"ignore";var S=class{projectRoot;config;watchConfig;languages;pnpmWorkspaces;typescriptProjectMode;typescriptProjects;clojureConfigPath;indexerConcurrency;onStatus;onReindexComplete;onError;status={state:"idle"};debounceTimer=null;cooldownTimer=null;dirty=!1;changedFiles=0;pendingTrigger=null;reindexInFlight=!1;lastReindexEnd=0;fsWatchers=[];gitPollTimer=null;lastGitState=null;gitignoreFilter;extraIgnore;stopped=!1;constructor(t){this.projectRoot=t.projectRoot,this.config=t.config,this.watchConfig=T(t.config),this.languages=t.languages,this.pnpmWorkspaces=t.config.indexer?.typescript?.pnpmWorkspaces??!1,this.typescriptProjectMode=t.config.indexer?.typescript?.projectMode,this.typescriptProjects=t.config.indexer?.typescript?.projects,this.clojureConfigPath=t.config.indexer?.clojure?.configPath,this.indexerConcurrency=t.config.indexerConcurrency,this.onStatus=t.onStatus??(()=>{}),this.onReindexComplete=t.onReindexComplete??(()=>{}),this.onError=t.onError??(e=>console.error(e.message)),this.gitignoreFilter=k(t.projectRoot),this.extraIgnore=A(),this.watchConfig.ignore.length>0&&this.extraIgnore.add(this.watchConfig.ignore)}start(){this.stopped=!1,this.setStatus({state:"idle"}),this.startGitStatePolling();try{let t=N(this.projectRoot,{ignoreInitial:!0,ignored:(e,i)=>this.isIgnoredWatchPath(e,i?.isDirectory()??!1)});t.on("all",(e,i)=>{this.stopped||this.handleFileChange(i)}),t.on("error",e=>{this.onError(new Error(`Failed to watch ${this.projectRoot}: ${String(e)}`))}),this.fsWatchers.push(t)}catch(t){this.onError(new Error(`Failed to watch ${this.projectRoot}: ${String(t)}`))}}stop(){this.stopped=!0;for(let t of this.fsWatchers)t.close();this.fsWatchers=[],this.clearDebounceTimer(),this.clearCooldownTimer(),this.clearGitPollTimer(),this.setStatus({state:"idle"})}requestRefresh(t,e={}){if(!e.immediate||this.reindexInFlight||this.status.state==="cooldown"){this.scheduleReindex(t);return}this.pendingTrigger=P(this.pendingTrigger,t),this.changedFiles+=1,this.clearDebounceTimer(),this.triggerReindex()}isIgnoredWatchPath(t,e){let i=this.relativeWatchPath(t);if(!i)return!1;let r=e?`${i}/`:i;return r===".git/"||r.startsWith(".git/")?!0:this.gitignoreFilter.isIgnored(r)||this.extraIgnore.ignores(r)}handleFileChange(t){let e=this.relativeWatchPath(t);!e||e===".."||e.startsWith("../")||e===".git"||e.startsWith(".git/")||this.gitignoreFilter.isIgnored(e)||this.extraIgnore.ignores(e)||e.endsWith("index.db")||e.endsWith("index.scip")||e.endsWith("index.db.tmp")||this.scheduleReindex({kind:"watch-source",detail:e})}relativeWatchPath(t){let e=F(t)?t:G(this.projectRoot,t);return M(this.projectRoot,e).replaceAll("\\","/")}scheduleReindex(t){if(this.pendingTrigger=P(this.pendingTrigger,t),this.changedFiles++,this.reindexInFlight){this.dirty=!0,this.setStatus({state:"indexing",startedAt:this.status.startedAt});return}if(this.status.state==="cooldown"){this.dirty=!0,this.setStatus({state:"cooldown",until:this.status.until,dirty:!0});return}this.clearDebounceTimer();let e=Date.now()+this.watchConfig.debounceMs;this.setStatus({state:"waiting",changedFiles:this.changedFiles,reindexAt:e}),this.debounceTimer=setTimeout(()=>{this.debounceTimer=null,this.triggerReindex()},this.watchConfig.debounceMs)}triggerReindex(){if(this.reindexInFlight||this.stopped)return;let t=Date.now()-this.lastReindexEnd;if(this.lastReindexEnd>0&&t<this.watchConfig.cooldownMs){let r=this.watchConfig.cooldownMs-t;this.dirty=!0;let o=Date.now()+r;this.setStatus({state:"cooldown",until:o,dirty:!0}),this.cooldownTimer=setTimeout(()=>{this.cooldownTimer=null,this.dirty&&!this.stopped&&(this.dirty=!1,this.triggerReindex())},r);return}this.reindexInFlight=!0,this.dirty=!1,this.changedFiles=0;let e=this.pendingTrigger??{kind:"watch-source"};this.pendingTrigger=null;let i=Date.now();this.setStatus({state:"indexing",startedAt:i}),this.runReindex(e).then(r=>{if(this.reindexInFlight=!1,this.lastReindexEnd=Date.now(),this.onReindexComplete(r),this.dirty&&!this.stopped){let o=Date.now()+this.watchConfig.cooldownMs;this.setStatus({state:"cooldown",until:o,dirty:!0}),this.cooldownTimer=setTimeout(()=>{this.cooldownTimer=null,this.dirty&&!this.stopped?(this.dirty=!1,this.triggerReindex()):this.setStatus({state:"idle"})},this.watchConfig.cooldownMs)}else this.setStatus({state:"idle"})}).catch(r=>{this.reindexInFlight=!1,this.lastReindexEnd=Date.now(),this.onError(r instanceof Error?r:new Error(String(r))),this.setStatus({state:"idle"})})}runReindex(t){return new Promise((e,i)=>{let r=Date.now(),o=f(this.projectRoot),n=Object.keys(o).length>0?o:this.config,c=m(this.projectRoot,n),a=n.indexer?.typescript,l=n.indexer?.clojure,h=$(new URL("./reindex-worker.js",import.meta.url).pathname,[],{detached:!0,env:{...process.env,SCIP_REINDEX_PROJECT_ROOT:this.projectRoot,SCIP_REINDEX_OUTPUT_SCIP:c.indexPath,SCIP_REINDEX_OUTPUT_DB:c.dbPath,SCIP_REINDEX_LANGUAGES:(n.languages??this.languages)?.join(",")??"",SCIP_REINDEX_INDEXER_CONCURRENCY:String(n.indexerConcurrency??this.indexerConcurrency??""),SCIP_REINDEX_PNPM_WORKSPACES:a?.pnpmWorkspaces??this.pnpmWorkspaces?"1":"",SCIP_REINDEX_TYPESCRIPT_CONFIG:JSON.stringify({projectMode:a?.projectMode??this.typescriptProjectMode,projects:a?.projects??this.typescriptProjects??[]}),SCIP_REINDEX_CLOJURE_CONFIG_PATH:l?.configPath??this.clojureConfigPath??"",SCIP_REINDEX_TRIGGER_KIND:t.kind,SCIP_REINDEX_TRIGGER_DETAIL:t.detail??""},stdio:"pipe"});h.on("exit",d=>{d===0?e(Date.now()-r):i(new Error(`Reindex worker exited with code ${d}`))}),h.on("error",i)})}setStatus(t){this.status=t,this.onStatus(t)}clearDebounceTimer(){this.debounceTimer&&(clearTimeout(this.debounceTimer),this.debounceTimer=null)}clearCooldownTimer(){this.cooldownTimer&&(clearTimeout(this.cooldownTimer),this.cooldownTimer=null)}startGitStatePolling(){this.lastGitState=this.readGitState(),this.lastGitState&&(this.gitPollTimer=setInterval(()=>this.pollGitState(),this.watchConfig.gitPollMs),this.gitPollTimer.unref?.())}pollGitState(){let t=this.lastGitState,e=this.readGitState();if(!t||!e||this.stopped){this.lastGitState=e;return}this.lastGitState=e;let i=t.head!==e.head,r=t.indexPath!==e.indexPath||t.indexMtimeMs!==e.indexMtimeMs||t.indexSize!==e.indexSize;i&&r?this.scheduleReindex({kind:"watch-git-state",detail:"HEAD and index changed"}):i?this.scheduleReindex({kind:"watch-git-head",detail:"HEAD changed"}):r&&this.scheduleReindex({kind:"watch-git-index",detail:e.indexPath??"index changed"})}readGitState(){let t=g(this.projectRoot,["rev-parse","--git-path","index"]);if(!t)return null;let e=y(this.projectRoot,t),i={head:g(this.projectRoot,["rev-parse","--verify","HEAD"]),indexPath:e};try{let r=_(e);i.indexMtimeMs=r.mtimeMs,i.indexSize=r.size}catch{i.indexMtimeMs=void 0,i.indexSize=void 0}return i}clearGitPollTimer(){this.gitPollTimer&&(clearInterval(this.gitPollTimer),this.gitPollTimer=null)}};function P(s,t){return s?s.kind===t.kind?s.detail===t.detail?s:{kind:s.kind,detail:"multiple changes"}:{kind:"watch-git-state",detail:`${s.kind}, ${t.kind}`}:t}import{existsSync as x,mkdirSync as O,symlinkSync as L,readlinkSync as I,unlinkSync as w,readdirSync as U}from"fs";import{join as p,dirname as R,resolve as u,relative as X,isAbsolute as q}from"path";import{homedir as v,platform as H}from"os";import{fileURLToPath as z}from"url";var J=H()==="win32",C=["_shared","scip-query","scip-setup","scip-calibrate","scip-cleanup-audit","scip-cleanup-improve","scip-integrity-audit","scip-twin-drift","scip-claim-audit","scip-probe-reachability","scip-hyper-optimization","scip-api-impact","scip-concrete-plan","scip-conductor","scip-debug","scip-explore","scip-root-cause","scip-triage-issue","scip-diagram","scip-doc-reconcile","scip-directory-architecture","scip-maintainability","scip-react-maintainability","scip-vue-maintainability","scip-verify","scip-language-playbook","scip-tla-model-system"];function K(s={}){let t=s.quiet?()=>{}:console.log,e=z(import.meta.url),i=u(R(e),"..","skills"),r=[p(v(),".claude","skills"),p(v(),".codex","skills"),p(v(),".agents","skills")],o={installed:[],skipped:[],alreadyLinked:[],pruned:[]};for(let n of r){let c=R(n);if(!x(c))continue;O(n,{recursive:!0});let a=Y(n);B(n,i,a,o,t);for(let l of C){let h=p(i,l),d=p(n,l);if(!x(h)){o.skipped.push(`${a}/${l}`);continue}if(x(d)){try{let E=I(d);if(u(E)===u(h)){o.alreadyLinked.push(`${a}/${l}`),t(`  ok:   ${l} \u2192 ${a} (already linked)`);continue}}catch{o.skipped.push(`${a}/${l}`),t(`  skip: ${l} \u2192 ${a} (exists, not a symlink)`);continue}w(d)}L(h,d,J?"junction":"dir"),o.installed.push(`${a}/${l}`),t(`  done: ${l} \u2192 ${a}`)}}return o}function B(s,t,e,i,r){let o=new Set(C);for(let n of U(s)){if(o.has(n))continue;let c=p(s,n),a;try{a=u(R(c),I(c))}catch{continue}V(a,t)&&(w(c),i.pruned.push(`${e}/${n}`),r(`  prune: ${n} \u2192 ${e} (removed stale scip-query skill link)`))}}function V(s,t){let e=X(u(t),u(s));return e===""||!e.startsWith("..")&&!q(e)}function Y(s){return s.includes(".codex")?"Codex":s.includes(".agents")?"Agents":"Claude"}export{S as Watcher,b as getScipVersion,W as initProjectConfig,K as installSkills,j as isScipInstalled,f as loadProjectConfig,D as printScipInstallInstructions,m as resolveIndexStoragePaths};
 //# sourceMappingURL=runtime.js.map

package/docs/COMMAND_REFERENCE.md

@@ -129,7 +129,7 @@ This syntax summary is generated from the CLI command descriptors. Keep workflow
 |---|---|---|
 | `bench` | Benchmark indexing and command runtimes for this repository | `--json`<br>`--cold-index`<br>`--include-heavy`<br>`--command <cmd>`<br>`--timeout-ms <n>`<br>`--progress`<br>`--profile`<br>`--profile-out <path>` |
 | `work-audit <profile>` | Rank exact repeated computations in a profiling JSONL file by measured avoidable time | `--top <n>`<br>`--json` |
-| `install-skills` | Install skills (_shared, scip-query, scip-setup, scip-calibrate, scip-cleanup-audit, scip-cleanup-improve, scip-integrity-audit, scip-twin-drift, scip-claim-audit, scip-probe-reachability, scip-hyper-optimization, scip-api-impact, scip-concrete-plan, scip-conductor, scip-debug, scip-explore, scip-triage-issue, scip-diagram, scip-doc-reconcile, scip-directory-architecture, scip-maintainability, scip-react-maintainability, scip-vue-maintainability, scip-verify, scip-language-playbook, scip-tla-model-system) into Claude Code, Codex, and shared agent roots | - |
+| `install-skills` | Install skills (_shared, scip-query, scip-setup, scip-calibrate, scip-cleanup-audit, scip-cleanup-improve, scip-integrity-audit, scip-twin-drift, scip-claim-audit, scip-probe-reachability, scip-hyper-optimization, scip-api-impact, scip-concrete-plan, scip-conductor, scip-debug, scip-explore, scip-root-cause, scip-triage-issue, scip-diagram, scip-doc-reconcile, scip-directory-architecture, scip-maintainability, scip-react-maintainability, scip-vue-maintainability, scip-verify, scip-language-playbook, scip-tla-model-system) into Claude Code, Codex, and shared agent roots | - |
 | `setup-hooks` | Install or refresh project-local Codex and Claude Code lifecycle hooks | `--shared`<br>`--remove`<br>`--force`<br>`--json` |
 | `check-deps` | Check whether scip-query and the detected language indexers are actually runnable | - |
 | `capabilities` | Report which evidence and verification capabilities are available in this project | `--matrix`<br>`--json` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scip-query",
-  "version": "0.17.2",
+  "version": "0.18.0",
   "description": "Evidence and verification for AI coding agents: map code, reuse concepts, finish migrations, and gate diffs.",
   "type": "module",
   "main": "dist/index.js",

package/skills/_shared/SKILL.md

@@ -175,7 +175,7 @@ scip-query complexity <symbol> # Per-symbol complexity: branches, cyclomatic est
 ```bash
 scip-query bench # Benchmark indexing and command runtimes for this repository
 scip-query work-audit <profile> # Rank exact repeated computations in a profiling JSONL file by measured avoidable time
-scip-query install-skills # Install skills (_shared, scip-query, scip-setup, scip-calibrate, scip-cleanup-audit, scip-cleanup-improve, scip-integrity-audit, scip-twin-drift, scip-claim-audit, scip-probe-reachability, scip-hyper-optimization, scip-api-impact, scip-concrete-plan, scip-conductor, scip-debug, scip-explore, scip-triage-issue, scip-diagram, scip-doc-reconcile, scip-directory-architecture, scip-maintainability, scip-react-maintainability, scip-vue-maintainability, scip-verify, scip-language-playbook, scip-tla-model-system) into Claude Code, Codex, and shared agent roots
+scip-query install-skills # Install skills (_shared, scip-query, scip-setup, scip-calibrate, scip-cleanup-audit, scip-cleanup-improve, scip-integrity-audit, scip-twin-drift, scip-claim-audit, scip-probe-reachability, scip-hyper-optimization, scip-api-impact, scip-concrete-plan, scip-conductor, scip-debug, scip-explore, scip-root-cause, scip-triage-issue, scip-diagram, scip-doc-reconcile, scip-directory-architecture, scip-maintainability, scip-react-maintainability, scip-vue-maintainability, scip-verify, scip-language-playbook, scip-tla-model-system) into Claude Code, Codex, and shared agent roots
 scip-query setup-hooks # Install or refresh project-local Codex and Claude Code lifecycle hooks
 scip-query check-deps # Check whether scip-query and the detected language indexers are actually runnable
 scip-query capabilities # Report which evidence and verification capabilities are available in this project

package/skills/scip-api-impact/SKILL.md

@@ -107,7 +107,9 @@ This step is complete only when the migration shape explains deploy order, rollb
 
 ```markdown
 Surface:
-Consumers:
+Consumer dispositions:
+| Consumer | Kind (direct/transitive/doc/config/test) | Disposition (unchanged-safe/update/shim/defer) |
+| --- | --- | --- |
 Required co-changes:
 Migration:
 Verification:
@@ -118,6 +120,8 @@ Verification:
 - `scip-query config-validate` when config changed
 ```
 
+Every consumer from `refs`/`affected` appears as a row — a blank disposition is unfinished analysis, and the plan is not complete while one exists. Non-indexed consumers (SQL, fixtures, dynamic strings, external callers) are checked with `rg` and rowed the same way.
+
 After editing, run routed checks from the shared reference and invoke `scip-verify`.
 
 The work is complete only when direct consumers, docs/config partners, and `scip-verify` have been checked.

package/skills/scip-claim-audit/SKILL.md

@@ -93,6 +93,7 @@ Write the report under `docs/scip-query/` unless the user asked only for a conve
 ```markdown
 Scope:
 Status words inventoried: N
+Classified: <d> derived / <h> hedged / <a> asserted — must sum to N; a gap is an unfinished audit
 
 Claim table:
 | Claim | Producer | Classification | Fix |

package/skills/scip-cleanup-audit/SKILL.md

@@ -101,11 +101,15 @@ scip-query co-change <file> --json --full
 
 Classify every candidate as `confirmed fix target`, `intentional design`, `false positive`, or `blocked`.
 
+A deletion is this skill's scrutiny-ending verdict, so a `confirmed fix target` that deletes code must survive refutation first. Run the known blind-spot checks and record them on the entry: `rg` for the symbol name as a string (dynamic dispatch, config keys, serialized references, CLI/doc text), and the cross-package barrel re-export gap (the one shape `dead` self-labels `unconfirmed`). Record `refutation: survived — <checks run>` on the entry, or reclassify it; the note stays either way.
+
 ### 4. Report
 
 ```markdown
 Health score: N/100
 
+Classification counts: <n> confirmed / <i> intentional / <fp> false positive / <b> blocked (must cover every collected signal)
+
 Confirmed items:
 - [priority] finding - evidence - first safe action
 

package/skills/scip-concrete-plan/SKILL.md

@@ -1,22 +1,24 @@
 ---
 name: scip-concrete-plan
-description: Plan code changes with scip-query evidence and testable design. Use for non-trivial implementation, refactor, migration, API, or bug-fix plans before editing code; require source citations, reuse audit, test seams, side-effect boundaries, contracts, and verification.
+description: Plan code changes with scip-query evidence and testable design. Use for non-trivial implementation, refactor, migration, API, or bug-fix plans before editing code; require contextual definitions, cited premises, reuse audit, test seams, counterexample attacks, and a derived verdict.
 commands:
   - template: "scip-query status --capabilities"
     when: "Discover: confirm the index is fresh before citing graph facts."
   - template: "scip-query plan-context <target>"
     when: "Discover: anchor the plan with pre-edit context for the target."
   - template: "scip-query refs <symbol>"
-    when: "Reuse audit: find existing consumers before proposing a new unit."
+    when: "Premises: enumerate every writer and reader of a touched state surface; reuse audit: find existing consumers."
+  - template: "scip-query dataflow <symbol-or-variable>"
+    when: "Premises: producers and consumers backing a state-authority premise."
   - template: "scip-query code <symbol>"
-    when: "Reuse audit: read source before citing a behavior claim."
+    when: "Premises: read source before citing a behavior claim."
   - template: "scip-query trace <symbol>"
     when: "Verify the plan: rerun source-producing context for cited targets."
 ---
 
 # Concrete Plan
 
-Use this skill to write an implementation plan that another agent can execute without guessing. A concrete plan is a dated Markdown checklist whose code claims come from scip-query evidence and whose design makes the intended behavior easy to test before it is easy to ship.
+Use this skill to write an implementation plan that another agent can execute without guessing and a reviewer can check without re-deriving. A concrete plan is a certificate: a dated Markdown document whose conclusion — ready to implement — is derived from numbered, source-cited premises, defended against constructed counterexamples, and shaped so the intended behavior is easy to test before it is easy to ship.
 
 Load shared mechanics from [`../_shared/SKILL.md`](../_shared/SKILL.md) when you need lookup tips, command families, postchecks, or subagent rules.
 
@@ -27,8 +29,9 @@ Load shared mechanics from [`../_shared/SKILL.md`](../_shared/SKILL.md) when you
 | --- | --- | --- |
 | `scip-query status --capabilities` | Show index status for this project | Discover: confirm the index is fresh before citing graph facts. |
 | `scip-query plan-context <target>` | Pre-edit planning context for a symbol, file, or module | Discover: anchor the plan with pre-edit context for the target. |
-| `scip-query refs <symbol>` | Find all files referencing a symbol | Reuse audit: find existing consumers before proposing a new unit. |
-| `scip-query code <symbol>` | Read the source code for a symbol (bounded to its definition range) | Reuse audit: read source before citing a behavior claim. |
+| `scip-query refs <symbol>` | Find all files referencing a symbol | Premises: enumerate every writer and reader of a touched state surface; reuse audit: find existing consumers. |
+| `scip-query dataflow <symbol-or-variable>` | Reference-level dataflow: definition sites, usage sites, producers, consumers | Premises: producers and consumers backing a state-authority premise. |
+| `scip-query code <symbol>` | Read the source code for a symbol (bounded to its definition range) | Premises: read source before citing a behavior claim. |
 | `scip-query trace <symbol>` | Trace a symbol: definition + all references | Verify the plan: rerun source-producing context for cited targets. |
 
 Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only when it is insufficient.
@@ -39,9 +42,14 @@ Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only
 1. Start with `scip-query status --capabilities`; reindex only when freshness is `stale`, `missing`, or `unknown`.
 2. Anchor the plan with `scip-query plan-context <target>`. If the target is not indexed, record that fact and use scip-query for every code-adjacent claim it can answer.
 3. Put the plan in `docs/plans/YYYY-MM-DD-<short-name>.md`.
-4. Every code step includes a `Source` field naming the scip-query command that produced the path, line range, and behavior claim.
-5. Every behavior-changing step includes a testability design: test seam, injected dependencies, pure core, side-effect boundary, and validation.
-6. Do not propose a new helper, wrapper, type, parameter, config flag, component, hook, or module until the reuse audit proves reuse or extension is not the better move.
+4. Define every load-bearing concept contextually and state every invariant in `iff` or `must always` form. A definition without referents (a `Source:` line) is a guess.
+5. Evidence lives in numbered premises (`P1`, `P2`, ...), each with a `Source` naming the scip-query command that produced it. Every shared-state surface the plan touches gets a state-authority premise enumerating its complete writer and reader sets.
+6. Steps and defenses cite the premises they depend on. A claim no premise supports is either new evidence to gather or an explicit `ASSUMPTION` — never silent.
+7. Do not propose a new helper, wrapper, type, parameter, config flag, component, hook, or module until the reuse audit proves reuse or extension is not the better move.
+8. Every behavior-changing step includes a testability design: test seam, injected dependencies, pure core, side-effect boundary, and validation.
+9. Attack entries must be constructed scenarios — actor, starting state, sequence — and each ends in a recorded outcome: `HELD` citing the defending step and premises, or `HOLE` with its repair step or accepted reason. An assertion of absence ("no new shared mutable state") is not a defense; it cannot fail, so it cannot catch anything.
+10. Installing an enforcer — trigger, constraint, guard, gate — opens an enforcement window: every existing writer in the relevant state-authority premise must be brought into compliance in the same or an earlier step, or the window recorded as an accepted hole. Every step declares `Deployable`.
+11. The verdict is derived, not asserted: `PLANNED-COMPLETE` only when the coverage matrix has no blank rows and every attack ends in `HELD` with citations or an accepted hole. An attack record where nothing ever broke is a red flag — attacks run against a draft should find holes; if none did, rerun the pass as falsification, preferably in a fresh subagent context.
 
 ## Planning Terms
 
@@ -53,6 +61,16 @@ A side-effect boundary is the edge where deterministic program decisions meet fi
 
 A contract is the stable promise one code unit exposes to another, including accepted inputs, returned outputs, errors, timing expectations, and side effects that callers may rely on.
 
+An invariant is a property of the changed system that must hold at every observable moment; what makes it load-bearing is that attacks are judged against it and the final verdict is derived from whether it survives them all.
+
+A premise is a numbered, source-cited statement of fact about the current code; what makes it a premise rather than a note is that steps and defenses cite it by ID, so a false premise is traceable to everything built on it.
+
+A state-authority premise is a premise that enumerates the complete writer and reader sets of one shared state surface; what makes it powerful is that "complete" is falsifiable with `refs` and `dataflow`, turning a forgotten write path from an unknowable into a checkable omission.
+
+A counterexample attack is a concrete actor, starting state, and action sequence constructed to violate an invariant; what makes it evidence is that its defense cites premises and steps, so "we considered failure" becomes "this specific failure is blocked here."
+
+An enforcement window is the interval between the step that installs an invariant enforcer and the step that brings the last existing writer into compliance; what makes it dangerous is that during it, every unupdated writer fails the new check in production, so the plan that adds safety is itself the outage.
+
 ## Workflow
 
 ### 1. Discover
@@ -64,22 +82,50 @@ scip-query status --capabilities
 scip-query plan-context <target>
 ```
 
-Use the shared reference for follow-up commands. Fill three gates before designing:
+Use the shared reference for follow-up commands. Fill four gates before designing:
 
 ```markdown
 ## Goal
 What the user is trying to accomplish and what done looks like for them.
 
+## Definitions & Invariants
+For each load-bearing concept: its wider class, then the one trait that causally
+explains its other traits in this codebase — with the referents. Then the
+invariants the change must preserve, in iff / must-always form.
+
 ## Current State
-The affected end-to-end flow, with scip-query citations for entry points, callers, data flow, dependencies, downstream impact, and non-obvious invariants.
+A short narrative of the affected end-to-end flow. Every factual sentence
+cites a premise by ID.
 
 ## Reuse Audit
-For every new symbol or file being considered: reuse target, extension target, or evidence-backed reason new code is justified.
+For every new symbol or file being considered: reuse target, extension target,
+or evidence-backed reason new code is justified.
 ```
 
-This step is complete only when the plan can explain the current flow, its consumers, and every proposed new unit's reuse decision with citations.
+Definition discipline: place the concept in its wider class, then name the essential trait — the one that makes the concept's other traits in this codebase possible and explains them. Do not label genus or differentia; write it as prose. Ban circular and synonym definitions ("the refresh coordinator coordinates refreshes" defines nothing). Any new term the plan introduces gets defined the same way. Good definitions condense: they imply the concept's other traits instead of listing them, and derived requirements fall out of them — if restore is defined as the inverse of cancel, then the privilege to restore must not be weaker than the privilege to cancel, and a plan that gates them asymmetrically must defend that asymmetry.
+
+This step is complete only when the concepts are defined with referents, the invariants are stated formally, and every proposed new unit has a reuse decision with citations.
+
+### 2. Establish Premises
 
-### 2. Shape for Tests
+Number every fact the plan depends on:
+
+```markdown
+## Premises
+
+- P1. <current behavior fact> — Source: `scip-query code <symbol>`
+- P2. Writers of `<state surface>`: <complete list>. Readers: <complete list>.
+  — Source: `scip-query refs <symbol>` + `scip-query dataflow <symbol>`
+- P3. ASSUMPTION: <belief the evidence cannot yet confirm, and what would confirm it>
+```
+
+State-authority rule: for every state surface the plan touches — database column, store field, event topic, endpoint, cache entry — write one premise enumerating its complete writer and reader sets. Completeness comes from `refs` and `dataflow`, not memory.
+
+Why this premise class exists: a sprint-restore plan hardened `restore()` and the cancellation path but never enumerated the writers of sprint status. Review found `PATCH /sprints/:id` could set `status: 'active'` around every restore invariant, and transition automations wrote `sprintId` straight past the new membership guard — two of that review's five ship-blockers, both sitting in the writer list one `refs` call would have produced. With a state-authority premise, each writer in the list must be visited by an attack; without it, the side doors are invisible until review.
+
+This step is complete only when every state surface named in any phase has a state-authority premise and every remaining unknown is an explicit `ASSUMPTION`.
+
+### 3. Shape for Tests
 
 Before writing implementation phases, add:
 
@@ -101,7 +147,7 @@ Plan the code so tests can call the pure core directly and exercise the side-eff
 
 This step is complete only when every changed behavior has a named test seam and the plan makes clear which logic can be tested without real external services.
 
-### 3. Design the Checklist
+### 4. Design the Checklist
 
 Write phases in execution order. Keep each phase deployable or explicitly mark why it is not. Use this step format:
 
@@ -109,7 +155,8 @@ Write phases in execution order. Keep each phase deployable or explicitly mark w
 ### N.M - Imperative title
 
 - [ ] **File**: `path/to/file.ts:LINE-LINE`
-- **Source**: `scip-query <command>`
+- **Premises**: P<n>, P<m>
+- **Deployable**: yes | no — <reason> | part of single-deploy group <name>
 - **What**: Current behavior verified from source.
 - **Change**: Exact edit to make.
 - **Testability**:
@@ -119,41 +166,59 @@ Write phases in execution order. Keep each phase deployable or explicitly mark w
   - Side-effect shell:
   - Contract:
 - **Validation**: Targeted test, smoke command, or manual check that proves the behavior.
-- **Why**: Why this step is needed and why this order is safe.
+- **Why**: Why this step is needed and why this order is safe, citing the premises it rests on.
 ```
 
-This step is complete only when no checklist item says "update this file" without exact current behavior, target behavior, and validation.
+If a step installs an enforcer — trigger, constraint, guard, gate — check its enforcement window here: every existing writer in the relevant state-authority premise is brought into compliance in the same or an earlier step, or the window is carried into the attack record as a hole to accept or repair.
+
+This step is complete only when no checklist item says "update this file" without exact current behavior, target behavior, cited premises, a deployability declaration, and validation.
 
-### 4. Stress-Test
+### 5. Attack the Plan
 
-Apply these lenses to every phase. Add or change steps until each answer is concrete:
+Construct counterexamples against every invariant. This pass is falsification, not defense: it succeeds by finding holes, and against a draft it should find some. Prefer delegating it to a fresh subagent when the environment can spawn one — give the adversary only the Definitions & Invariants, Premises, state-authority maps, and the checklist, not your design rationale, and brief it that it wins by producing holes; fold its findings back as HOLE entries and repair steps. Solo fallback: enumerate the full attack list from the coverage-matrix rows below before writing any Outcome line, so attacks cannot be shaped around defenses you already have.
 
-| Lens | Plan must answer |
+Use the lenses as attack prompts — purpose, blast radius, valid intermediate state, reversibility, failure, concurrency, boundaries, data integrity, observability, human experience, efficiency, reuse, testability — and record each attack in this form:
+
+```markdown
+### A<n>. <invariant> via <lens>
+- Attack: <actor> + <starting state> + <action sequence>
+- Outcome: HELD — defended by step <N.M> (P<i>, P<j>)
+  | HOLE — repaired by new step <N.M>
+  | HOLE — accepted: <reason>
+```
+
+A `HELD` that cannot name its defending step and premises is not `HELD`; it is a hole wearing confidence. A repaired hole keeps its `HOLE — repaired by step N.M` label permanently — do not rewrite it to `HELD` after the repair, because the repair history is the evidence that the pass falsified. The verdict's repaired count must equal the number of `HOLE — repaired` entries in the record. Close the record with a coverage matrix — one row per writer in every state-authority premise and per applicable lens (valid intermediate state is always applicable when any step installs an enforcer or migration):
+
+```markdown
+| Surface or lens | Attacks |
 | --- | --- |
-| Purpose | Why does the current code exist, and what invariant must survive? |
-| Blast radius | Which direct and transitive consumers move with this change? |
-| Valid intermediate state | Would the project still work after only this phase? |
-| Reversibility | Is this a one-way or two-way door, and what rollback exists? |
-| Failure | What happens when I/O, external APIs, malformed data, retries, or crashes occur? |
-| Concurrency | What shared state can be touched twice or out of order? |
-| Boundaries | Who can call this entry point, and where is input validated? |
-| Data integrity | What existing data, generated artifacts, or persisted contracts are affected? |
-| Observability | Can a maintainer diagnose failures from logs/errors without rereading the source? |
-| Human experience | What would surprise, confuse, or block a real user? |
-| Reuse | Does existing code already solve this problem or most of it? |
-| Testability | Are dependencies injectable, logic pure where practical, concerns separated, and contracts small? |
-
-This step is complete only when every discovered gap has either a new plan step or a written reason it is accepted.
-
-### 5. Verify the Plan
+| <writer, reader, or lens> | A2, A7 |
+```
+
+A blank row is an unattacked writer. The record is incomplete until every row names an attack or carries an accepted reason. Spread attacks across rows before deepening one: depth on the axis you already anticipated does not protect the axes you did not — the leaks come from blank rows, not from the tenth variation of the race you already modeled.
+
+Invalid entry — this exact shape preceded three post-review remediation rounds on a real plan:
+
+> **Concurrency**: Validation happens before database writes; no new shared mutable state or retry behavior is introduced.
+
+It names no actor, no interleaving, and cites nothing. It is an assertion of absence: it cannot fail, so it caught nothing — review later found exactly the race it waved away. A valid entry for the same phase:
+
+> ### A3. "Every stored value is a member of its field's option set" via concurrency
+> - Attack: admin removes option O in transaction A while a user writes value O in transaction B; interleaving B-validates → A-commits → B-commits persists an orphaned value.
+> - Outcome: HOLE — repaired by new step 2.2: validation reads the option definition outside B's lock (P4), so serialize definition changes with every value writer via FOR UPDATE on the definition row; regression proves both interleavings against PostgreSQL.
+
+This step is complete only when the coverage matrix has no blank rows and every attack entry ends in a cited `HELD` or a recorded `HOLE`.
+
+### 6. Verify the Plan and Derive the Verdict
 
 Run or delegate phase-by-phase reference checks. Each verifier confirms:
 
 - every path exists;
 - every line range is still within about five lines;
+- every premise reproduces when its `Source` command is rerun — a premise that no longer reproduces is false, and everything citing it is suspect until fixed;
 - every behavior claim matches source;
 - every new unit has reuse evidence;
-- every behavior-changing step has a validation command and testability design.
+- every behavior-changing step has cited premises, a validation command, and a testability design.
 
 Then rerun the source-producing context for the cited targets:
 
@@ -161,9 +226,22 @@ Then rerun the source-producing context for the cited targets:
 scip-query plan-context <target>
 ```
 
-Use the shared reference for subagent briefing text when delegating.
+Use the shared reference for subagent briefing text when delegating. Close the plan by applying the definitions to the record — do not summarize feelings:
+
+```markdown
+## Verdict
+
+A plan is PLANNED-COMPLETE iff the coverage matrix has no blank rows, every
+attack ends in HELD with cited steps and premises or an accepted hole with a
+written reason, and no premise failed reverification.
+
+Result: PLANNED-COMPLETE | INCOMPLETE — <n> attacks, <x> holes repaired,
+<y> holes accepted; <unresolved items>
+```
+
+The counts are part of the verdict. "16 attacks, 0 holes repaired" against a fresh draft is not a strong plan; it is an attack pass that defended instead of falsified — rerun it before shipping the plan.
 
-This step is complete only when stale references are fixed and every phase has a validation path.
+This step is complete only when stale references are fixed, every premise reverified, and the verdict line is derived from the attack record.
 
 ## Output Shape
 
@@ -171,11 +249,14 @@ The plan file contains:
 
 1. Title and date.
 2. Goal.
-3. Current State.
-4. Reuse Audit.
-5. Testability Design.
-6. Design Phases.
-7. Stress-Test Findings.
-8. Execution Order and deployable phase notes.
-9. Ship Order with one-way doors flagged.
-10. Summary of files to create, edit, delete, and verify.
+3. Definitions & Invariants.
+4. Premises (including state-authority premises and explicit assumptions).
+5. Current State (narrative citing premise IDs).
+6. Reuse Audit.
+7. Testability Design.
+8. Design Phases (steps citing premises, each with a deployability declaration).
+9. Attack Record (attacks with outcomes, holes repaired or accepted, coverage matrix).
+10. Execution Order and deployable phase notes.
+11. Ship Order with one-way doors flagged.
+12. Verdict with attack and hole counts.
+13. Summary of files to create, edit, delete, and verify.

package/skills/scip-debug/SKILL.md

@@ -43,6 +43,7 @@ Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only
 2. Use scip-query to find entry points, call paths, data flow, and blast radius.
 3. Prefer one narrow fix over broad cleanup.
 4. Verify with the narrowest repo test or smoke command, then invoke `scip-verify`.
+5. A root-cause claim whose fix crosses a file boundary requires a rival: state the next-most-plausible explanation for the same symptom and run the observation that separates them. A root cause with no rival considered is a guess with confidence.
 
 ## Workflow
 
@@ -82,6 +83,8 @@ scip-query slice <symbol-or-variable> --forward
 
 Stop expanding when the first code fact that can cause the symptom is found.
 
+When a candidate cause emerges, state it as a hypothesis alongside one rival — the next-most-plausible explanation for the same symptom. Name the observation that distinguishes them (a log line, a probe, a narrower test) and execute it. Choose the discriminator that is cheapest to run, not the one most likely to confirm.
+
 This step is complete only when the path explains the symptom or the missing evidence is explicit.
 
 ### 4. Compare nearby implementations
@@ -117,9 +120,11 @@ Run the reproduction, narrow test or smoke command, and invoke `scip-verify`.
 Bug:
 Entry point:
 Root cause:
+Rival considered:
+Discriminator: <the executed observation that separated them>
 Fix:
 Verification:
 Remaining risk:
 ```
 
-Do not present a guess as a root cause. If no root cause is proven, report the missing evidence.
+Do not present a guess as a root cause. A root cause with no rival considered and no executed discriminator is a guess. If no root cause is proven, report the missing evidence.

package/skills/scip-explore/SKILL.md

@@ -44,6 +44,7 @@ Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only
 3. Read source with `scip-query code`; do not describe what a function probably does.
 4. Follow the graph before trusting folder structure.
 5. Start wide, then narrow.
+6. Descriptions need citations; conclusions need discriminators. A conclusion — why something happens, what a unit is for, which intent explains a shape — states one rival explanation and the trace evidence that rules it out.
 
 ## Workflow
 
@@ -117,4 +118,4 @@ This step is complete only when the explanation includes the risky symbols or st
 
 ## Report
 
-Report overview, entry points, call flow, data flow, dependencies, consumers, risk areas, and the command citations that prove each claim. Exploration is complete only when the user can see what was proven and what remains unverified.
+Report overview, entry points, call flow, data flow, dependencies, consumers, risk areas, and the command citations that prove each claim. For each conclusion-bearing claim, name the rival explanation considered and the evidence that ruled it out. Exploration is complete only when the user can see what was proven, what remains unverified, and which conclusions rest on a discriminator rather than a single story.

package/skills/scip-integrity-audit/SKILL.md

@@ -43,6 +43,12 @@ validates (checkers, gates, verifiers, validators — find producers with
 an input that MUST fail — a wrong binding, a corrupt file, an impossible
 value — and run it. A checker that passes its should-fail input is
 decorative: file it as a defect, not a note.
+Before filing, attempt the defense: an accusation triggers a rewrite, so
+search for the failure exit the drill may have missed — a config-gated
+branch, an async rejection, one-hop delegation (the calibration's known
+noise archetypes). File the defect with the executed should-fail input
+attached and the defense attempt noted; a defense that succeeds clears the
+checker and stays in the record as its witness.
 Complete only when every checker in scope has been witnessed rejecting a
 constructed should-fail input, or is listed with a reason it cannot be.
 
@@ -121,6 +127,17 @@ the fix. The audit is complete only when every drill's exit criterion is
 met for the scope, and every defect found has a regression artifact — a
 test, fixture, or model that fails on the pre-fix behavior.
 
+End with a derived verdict, not an impression:
+
+```markdown
+Integrity: <scope> — <c> checkers witnessed failing, <a> adapters diffed
+against reality, <f> fallback primaries witnessed live, <m> metrics
+recomputed, <t> twins compared; <d> defects filed, <u> unverifiable (reasons)
+```
+
+A suspect scope that produces zero defects is itself a claim: state what
+made the suspicion wrong, or rerun the drill that should have caught it.
+
 A regression artifact that doesn't actually assert anything, or asserts the
 same literal it stubbed into its own mock, is a fake witness — the same
 "reports success without doing the work" failure mode this skill hunts in

package/skills/scip-maintainability/SKILL.md

@@ -53,6 +53,8 @@ Essential variation is difference that must remain because the real units differ
 
 System compression is replacing several mechanisms that perform the same role, policy, lifecycle, or surface job with fewer named mechanisms that preserve behavior.
 
+A unifying definition is the single essential trait that makes several code sites one concept; what makes it a test is that failing to state it proves the sites are not one concept, and consolidating them anyway would package-deal essential variation into a false abstraction.
+
 ## Rules
 
 1. Ground claims in files, symbols, references, call graphs, dependencies, surfaces, and blast radius.
@@ -61,6 +63,7 @@ System compression is replacing several mechanisms that perform the same role, p
 4. Preserve essential variation.
 5. Add an abstraction only when it removes hidden policy, names a lifecycle, enforces a rule, or reduces concept count.
 6. Prefer deletion, inlining, merging, generation, or enforcement before broad frameworks.
+7. A scattered-concept or consolidation claim ships its unifying definition. If no single essential trait covers every cited site, the variation is essential: record it and do not consolidate.
 
 ## Workflow
 
@@ -100,7 +103,7 @@ This step is complete only when concrete units, consumers, tests, fallbacks, ada
 
 For each cluster, ask:
 
-- What one concept appears in several places?
+- What one concept appears in several places — and what single essential trait makes them one concept? If the trait cannot be stated, they are not one concept.
 - What policy is hidden?
 - What lifecycle is unnamed?
 - Which differences are essential?
@@ -144,6 +147,8 @@ For broad review, write a register under `docs/plans/` unless the user asks not
 
 Use dispositions: `merge`, `delete`, `inline`, `extract`, `generate`, `enforce`, `supersede`, `defer`, `skip`.
 
+Every `merge`, `extract`, or `generate` entry carries its unifying definition and its strongest dissenter — the cited site most likely to differ essentially — with the evidence that it does not. A dissenter that survives moves the entry to `skip` with reason `essential variation`; the dissenter stays in the register either way.
+
 This step is complete only when each opportunity has evidence, disposition, dependency order, touch map, and validation plan.
 
 ### 7. Implement and verify when asked

package/skills/scip-query/SKILL.md

@@ -44,6 +44,7 @@ The loop is complete only when `scip-verify` passes or each remaining finding ha
 | --- | --- | --- |
 | Understand a system before answering or editing | `scip-explore` | `system`, `trace`, `call-graph`, `dataflow` |
 | Root-cause a bug or regression | `scip-debug` | `trace`, `dataflow`, `change-surface` |
+| Diagnose the design flaw behind a family of recurring bugs | `scip-root-cause` | `co-change`, `similar`, `refs` |
 | Turn a report into a fix packet | `scip-triage-issue` | `files`, `trace`, `affected` |
 | Create a code flow, dependency, or blast-radius diagram | `scip-diagram` | `call-graph`, `dataflow`, `affected` |
 | Plan a feature, fix, or refactor | `scip-concrete-plan` | `plan-context` |
@@ -72,6 +73,7 @@ Routing is complete only when one owning skill is selected or the task is small
 
 - "Is this implementation real / does it actually work" → `scip-integrity-audit`; "is this well-organized" → `scip-maintainability`; same-name drifted twins specifically → `scip-twin-drift`.
 - One change → `scip-concrete-plan`; a program of changes with delegation → `scip-conductor`.
+- One failing behavior → `scip-debug`; a family of similar bugs whose fixes keep recurring, or "what is really wrong with this system" backed by bug history → `scip-root-cause`; structure smells with no bug evidence → `scip-maintainability`.
 
 - Use `scip-cleanup-audit` for reports, ranking, confirmation, or recent AI-residue triage without edits.
 - Use `scip-cleanup-improve` when the user asks to fix, improve, continue cleaning, or raise health autonomously.
@@ -105,6 +107,7 @@ Top commands per routed skill, generated from each skill's own `commands:` front
 | `scip-maintainability` | `scip-query stats`, `scip-query system <scope>`, `scip-query surface <scope>` |
 | `scip-probe-reachability` | `scip-query outline <file> --signatures`, `scip-query code <symbol>`, `scip-query trace <symbol>` |
 | `scip-react-maintainability` | `scip-query react-component-duplicates --scope <scope> --full --json`, `scip-query react-hook-candidates --scope <scope> --full --json`, `scip-query react-large-component-pressure --scope <scope> --full --json` |
+| `scip-root-cause` | `scip-query trace <mechanism-symbol>`, `scip-query co-change <fix-site-file>`, `scip-query system <system-scope>` |
 | `scip-setup` | `scip-query setup --json`, `scip-query doctor`, `scip-query status --json` |
 | `scip-tla-model-system` | `scip-query tla scaffold <file>`, `scip-query tla verify <spec>`, `scip-query tla instrument <spec>` |
 | `scip-triage-issue` | `scip-query files <issue-term>`, `scip-query trace <entry-or-error-symbol>`, `scip-query code <entry-or-error-symbol>` |