@vpxa/aikit 0.1.1

package/packages/tools/dist/digest.d.ts

@@ -0,0 +1,50 @@
+import { IEmbedder } from "../../embeddings/dist/index.js";
+
+//#region packages/tools/src/digest.d.ts
+interface DigestSource {
+  /** Unique identifier for this source */
+  id: string;
+  /** The text to compress */
+  text: string;
+  /** Priority weight (default: 1). Higher = more budget share */
+  weight?: number;
+}
+interface DigestOptions {
+  /** Source texts to compress */
+  sources: DigestSource[];
+  /** Focus query — what matters for the next step? */
+  query: string;
+  /** Target budget in characters (default: 4000) */
+  maxChars?: number;
+  /** Key fields to always extract via keyword matching */
+  pinFields?: string[];
+  /** Segmentation strategy (default: 'paragraph') */
+  segmentation?: 'paragraph' | 'sentence' | 'line';
+}
+interface DigestFieldEntry {
+  sourceId: string;
+  value: string;
+}
+interface DigestResult {
+  /** Compressed narrative (all sources merged, reading order maintained) */
+  text: string;
+  /** Extracted structured fields */
+  fields: Record<string, DigestFieldEntry[]>;
+  /** Per-source compression stats */
+  sourceStats: Array<{
+    id: string;
+    originalChars: number;
+    keptChars: number;
+    segmentsKept: number;
+    segmentsTotal: number;
+  }>;
+  totalOriginalChars: number;
+  totalCompressedChars: number;
+  ratio: number;
+}
+/**
+ * Compress multiple text sources into a single digest.
+ */
+declare function digest(embedder: IEmbedder, options: DigestOptions): Promise<DigestResult>;
+//#endregion
+export { DigestFieldEntry, DigestOptions, DigestResult, DigestSource, digest };

package/packages/tools/dist/digest.js

@@ -0,0 +1,6 @@
+import{cosineSimilarity as e,estimateTokens as t,segment as n}from"./text-utils.js";const r=[`status`,`files`,`decisions`,`blockers`,`artifacts`,`next`],i={status:/\b(?:status|result)\s*[:=]/i,files:/\b(?:files?|modified|created|deleted)\s*[:=]/i,artifacts:/\b(?:artifacts?)\s*[:=]/i,decisions:/\b(?:decisions?|decided|chose|selected)\s*[:=]/i,blockers:/\b(?:blockers?|blocked|blocking)\s*[:=]/i,next:/\b(?:next\s*(?:steps?|actions?)|todo|follow.up)\s*[:=]/i},a={status:/(?:^|\b)(?:status|result)\s*[:=]\s*(.+)$/i,files:/(?:^|\b)(?:files?|modified|created|deleted)\s*[:=]\s*(.+)$/i,artifacts:/(?:^|\b)(?:artifacts?)\s*[:=]\s*(.+)$/i,decisions:/(?:^|\b)(?:decisions?|decided|chose|selected)\s*[:=]\s*(.+)$/i,blockers:/(?:^|\b)(?:blockers?|blocked|blocking)\s*[:=]\s*(.+)$/i,next:/(?:^|\b)(?:next\s*(?:steps?|actions?)|todo|follow.up)\s*[:=]\s*(.+)$/i},o=/\b(?:APPROVED|NEEDS_REVISION|BLOCKED|SUCCESS|PARTIAL|FAILED|ESCALATE)\b/i,s=.01;function c(e){let t=e??[...r];return[...new Set(t.map(e=>e.toLowerCase()))]}function l(e){return typeof e!=`number`||!Number.isFinite(e)||e<=0?1:e}function u(e,t){let n=new Set;for(let r of t)i[r]?.test(e)&&n.add(r);return t.includes(`status`)&&o.test(e)&&n.add(`status`),[...n]}function d(e,t){let n=t.split(`
+`).map(e=>e.trim()).filter(e=>e.length>0);for(let t of n){let n=a[e]?.exec(t);if(n?.[1])return n[1].trim();if(e===`status`){let e=t.match(o);if(e)return e[0]}}return t.trim()}function f(e,t,n,r){e[t]||(e[t]=[]),e[t].push({sourceId:n,value:r})}function p(e,t,r,i){return e.map(e=>{let a=n(e.text,t).map((t,n)=>{let a=u(t,r);for(let n of a)f(i,n,e.id,d(n,t));return{index:n,text:t,pinnedFields:a,score:0}}),o=a.filter(e=>e.pinnedFields.length>0).reduce((e,t)=>e+t.text.length,0),s=a.filter(e=>e.pinnedFields.length===0).reduce((e,t)=>e+t.text.length,0);return{id:e.id,originalText:e.text,weight:l(e.weight),segments:a,pinnedChars:o,nonPinnedChars:s}})}function m(e,t){let n=new Map(e.map(e=>[e.id,0])),r=Math.max(0,t),i=e.filter(e=>e.nonPinnedChars>0);for(;r>s&&i.length>0;){let e=i.reduce((e,t)=>e+t.weight,0),t=0,a=[];for(let o of i){let i=n.get(o.id)??0,c=o.nonPinnedChars-i;if(c<=s)continue;let l=r*(o.weight/e),u=Math.min(l,c);n.set(o.id,i+u),t+=u,c-u>s&&a.push(o)}if(t<=s)break;r-=t,i=a}return n}function h(e){return e.map(e=>`[${e.id}]\n${e.text}`).join(`
+
+`)}function g(e,t){return e===0?0:t/e}async function _(n,r){let{sources:i,query:a,maxChars:o=4e3,pinFields:l,segmentation:u=`paragraph`}=r,d={},f=p(i,u,c(l),d),_=i.reduce((e,t)=>e+t.text.length,0);if(_<=o){let e=f.filter(e=>e.originalText.trim().length>0).map(e=>({id:e.id,text:e.originalText})),t=f.map(e=>({id:e.id,originalChars:e.originalText.length,keptChars:e.originalText.length,segmentsKept:e.segments.length,segmentsTotal:e.segments.length}));return{text:h(e),fields:d,sourceStats:t,totalOriginalChars:_,totalCompressedChars:_,ratio:_===0?0:1}}let v=await n.embedQuery(a);for(let t of f)for(let r of t.segments)r.pinnedFields.length>0||(r.score=e(v,await n.embed(r.text)));let y=m(f,o-f.reduce((e,t)=>e+t.pinnedChars,0)),b=[],x=[],S=0;for(let e of f){let n=y.get(e.id)??0,r=new Map,i=0,a=e.segments.filter(e=>e.pinnedFields.length===0).sort((e,n)=>n.score-e.score||t(e.text)-t(n.text)||e.index-n.index),o;for(let e of a){let t=n-i;if(t<=s)break;if(e.text.length<=t+s){r.set(e.index,e.text),i+=e.text.length;continue}o||=e}let c=Math.floor(n-i);if(o&&c>0){let e=o.text.slice(0,c).trimEnd();e.length>0&&(r.set(o.index,e),i+=e.length)}let l=e.segments.filter(e=>e.pinnedFields.length>0||r.has(e.index)).map(e=>({index:e.index,text:r.get(e.index)??e.text})),u=l.reduce((e,t)=>e+t.text.length,0);b.push({id:e.id,originalChars:e.originalText.length,keptChars:u,segmentsKept:l.length,segmentsTotal:e.segments.length}),S+=u,l.length!==0&&x.push({id:e.id,text:l.map(e=>e.text).join(`
+
+`)})}return{text:h(x),fields:d,sourceStats:b,totalOriginalChars:_,totalCompressedChars:S,ratio:g(_,S)}}export{_ as digest};

package/packages/tools/dist/dogfood-log.d.ts

@@ -0,0 +1,49 @@
+//#region packages/tools/src/dogfood-log.d.ts
+/**
+ * aikit_dogfood — Review persistent warn/error logs for dogfooding.
+ *
+ * Reads daily JSONL log files from .aikit-state/logs/ and returns a
+ * summarized or detailed view of recent issues. Useful for periodic
+ * review cycles to identify and fix recurring problems.
+ */
+interface DogfoodLogEntry {
+  ts: string;
+  level: 'warn' | 'error';
+  component: string;
+  msg: string;
+  [key: string]: unknown;
+}
+interface DogfoodLogOptions {
+  /** Number of days to look back (default: 7) */
+  days?: number;
+  /** Filter by level */
+  level?: 'warn' | 'error';
+  /** Filter by component name */
+  component?: string;
+  /** Maximum entries to return in detail (default: 50) */
+  limit?: number;
+}
+interface DogfoodLogGroupedEntry {
+  component: string;
+  msg: string;
+  level: 'warn' | 'error';
+  count: number;
+  firstSeen: string;
+  lastSeen: string;
+}
+interface DogfoodLogResult {
+  /** Total entries found matching filters */
+  totalEntries: number;
+  /** Unique issue groups (by component + message) */
+  groups: DogfoodLogGroupedEntry[];
+  /** Most recent entries (up to limit) */
+  recent: DogfoodLogEntry[];
+  /** Date range covered */
+  dateRange: {
+    from: string;
+    to: string;
+  };
+}
+declare function dogfoodLog(options?: DogfoodLogOptions): DogfoodLogResult;
+//#endregion
+export { DogfoodLogEntry, DogfoodLogGroupedEntry, DogfoodLogOptions, DogfoodLogResult, dogfoodLog };

package/packages/tools/dist/dogfood-log.js

@@ -0,0 +1,2 @@
+import{join as e,resolve as t}from"node:path";import{readFileSync as n,readdirSync as r}from"node:fs";import{AIKIT_PATHS as i}from"../../core/dist/index.js";function a(){return t(process.cwd(),i.logs)}function o(t={}){let{days:i=7,level:o,component:s,limit:c=50}=t,l=a(),u=new Date,d=new Date(u.getTime()-i*864e5).toISOString().slice(0,10),f=u.toISOString().slice(0,10),p;try{p=r(l).filter(e=>e.endsWith(`.jsonl`)&&e.slice(0,10)>=d).sort()}catch{return{totalEntries:0,groups:[],recent:[],dateRange:{from:d,to:f}}}let m=[];for(let t of p)try{let r=n(e(l,t),`utf-8`);for(let e of r.trim().split(`
+`))if(e)try{let t=JSON.parse(e);if(o&&t.level!==o||s&&t.component!==s)continue;m.push(t)}catch{}}catch{}let h=new Map;for(let e of m){let t=`${e.component}::${e.msg}`,n=h.get(t);n?(n.count++,e.ts<n.firstSeen&&(n.firstSeen=e.ts),e.ts>n.lastSeen&&(n.lastSeen=e.ts)):h.set(t,{component:e.component,msg:e.msg,level:e.level,count:1,firstSeen:e.ts,lastSeen:e.ts})}let g=[...h.values()].sort((e,t)=>t.count-e.count),_=m.slice(-c);return{totalEntries:m.length,groups:g,recent:_,dateRange:{from:p.length>0?p[0].slice(0,10):d,to:f}}}export{o as dogfoodLog};

package/packages/tools/dist/encode.d.ts

@@ -0,0 +1,16 @@
+//#region packages/tools/src/encode.d.ts
+/**
+ * aikit_encode — Encoding, decoding, and hashing utilities.
+ */
+type EncodeOperation = 'base64_encode' | 'base64_decode' | 'url_encode' | 'url_decode' | 'sha256' | 'md5' | 'jwt_decode' | 'hex_encode' | 'hex_decode';
+interface EncodeOptions {
+  operation: EncodeOperation;
+  input: string;
+}
+interface EncodeResult {
+  output: string;
+  operation: string;
+}
+declare function encode(options: EncodeOptions): EncodeResult;
+//#endregion
+export { EncodeOperation, EncodeOptions, EncodeResult, encode };

package/packages/tools/dist/encode.js

@@ -0,0 +1 @@
+import{createHash as e}from"node:crypto";function t(t){let{operation:n,input:r}=t,i;switch(n){case`base64_encode`:i=Buffer.from(r).toString(`base64`);break;case`base64_decode`:i=Buffer.from(r,`base64`).toString(`utf8`);break;case`url_encode`:i=encodeURIComponent(r);break;case`url_decode`:i=decodeURIComponent(r);break;case`sha256`:i=e(`sha256`).update(r).digest(`hex`);break;case`md5`:i=e(`md5`).update(r).digest(`hex`);break;case`jwt_decode`:{let e=r.split(`.`);if(e.length!==3)throw Error(`Invalid JWT: expected 3 dot-separated parts`);let t,n;try{t=JSON.parse(Buffer.from(e[0],`base64url`).toString()),n=JSON.parse(Buffer.from(e[1],`base64url`).toString())}catch{throw Error(`Invalid JWT: header or payload is not valid JSON`)}i=JSON.stringify({header:t,payload:n},null,2);break}case`hex_encode`:i=Buffer.from(r).toString(`hex`);break;case`hex_decode`:i=Buffer.from(r,`hex`).toString(`utf8`);break;default:throw Error(`Unknown operation: ${n}`)}return{output:i,operation:n}}export{t as encode};

package/packages/tools/dist/env-info.d.ts

@@ -0,0 +1,30 @@
+//#region packages/tools/src/env-info.d.ts
+/**
+ * aikit_env — System environment and runtime information.
+ */
+interface EnvInfoOptions {
+  includeEnv?: boolean;
+  filterEnv?: string;
+  showSensitive?: boolean;
+}
+interface EnvInfoResult {
+  system: {
+    platform: string;
+    arch: string;
+    release: string;
+    hostname: string;
+    type: string;
+    cpus: number;
+    memoryTotalGb: number;
+    memoryFreeGb: number;
+  };
+  runtime: {
+    node: string;
+    v8: string;
+  };
+  cwd: string;
+  env?: Record<string, string>;
+}
+declare function envInfo(options?: EnvInfoOptions): EnvInfoResult;
+//#endregion
+export { EnvInfoOptions, EnvInfoResult, envInfo };

package/packages/tools/dist/env-info.js

@@ -0,0 +1 @@
+import{arch as e,cpus as t,freemem as n,hostname as r,platform as i,release as a,totalmem as o,type as s}from"node:os";const c=[/key/i,/secret/i,/token/i,/password/i,/passwd/i,/credential/i,/private/i,/certificate/i];function l(l={}){let{includeEnv:u=!1,filterEnv:d,showSensitive:f=!1}=l,p={system:{platform:i(),arch:e(),release:a(),hostname:r(),type:s(),cpus:t().length,memoryTotalGb:Math.round(o()/1024**3*10)/10,memoryFreeGb:Math.round(n()/1024**3*10)/10},runtime:{node:process.versions.node,v8:process.versions.v8},cwd:process.cwd()};if(u){let e={};for(let[t,n]of Object.entries(process.env))n&&(d&&!t.toLowerCase().includes(d.toLowerCase())||(!f&&c.some(e=>e.test(t))?e[t]=`[REDACTED]`:e[t]=n));p.env=e}return p}export{l as envInfo};

package/packages/tools/dist/eval.d.ts

@@ -0,0 +1,15 @@
+//#region packages/tools/src/eval.d.ts
+interface EvalOptions {
+  code: string;
+  lang?: 'js' | 'ts';
+  timeout?: number;
+}
+interface EvalResult {
+  success: boolean;
+  output: string;
+  error?: string;
+  durationMs: number;
+}
+declare function evaluate(options: EvalOptions): EvalResult;
+//#endregion
+export { EvalOptions, EvalResult, evaluate };

package/packages/tools/dist/eval.js

@@ -0,0 +1,2 @@
+import e from"node:vm";function t(t){let{code:i,lang:a=`js`,timeout:o=5e3}=t,s=Math.min(Math.max(o,100),1e4),c=Date.now();try{let t=a===`ts`?r(i):i,o=[],l={console:{log:(...e)=>o.push(e.map(String).join(` `)),error:(...e)=>o.push(`[error] ${e.map(String).join(` `)}`),warn:(...e)=>o.push(`[warn] ${e.map(String).join(` `)}`)},setTimeout:void 0,setInterval:void 0,setImmediate:void 0,fetch:void 0,process:void 0,require:void 0,JSON,Math,Date,Array,Object,String,Number,Boolean,Map,Set,RegExp,Error,Promise,parseInt,parseFloat,isNaN,isFinite},u=e.createContext(l,{codeGeneration:{strings:!1,wasm:!1}}),d=e.runInContext(t,u,{timeout:s});return{success:!0,output:o.length>0?o.join(`
+`)+(d===void 0?``:`\n→ ${n(d)}`):d===void 0?`(no output)`:n(d),durationMs:Date.now()-c}}catch(e){return{success:!1,output:``,error:e.message,durationMs:Date.now()-c}}}function n(e){if(e===void 0)return`undefined`;if(e===null)return`null`;if(typeof e==`object`)try{return JSON.stringify(e,null,2)}catch{return String(e)}return String(e)}function r(e){return e.replace(/^\s*import\s+type\s+.*?;\s*$/gm,``).replace(/^\s*(?:export\s+)?interface\s+\w+[^{]*\{[\s\S]*?^\s*}\s*$/gm,``).replace(/^\s*(?:export\s+)?type\s+\w+\s*=.*?;\s*$/gm,``).replace(/([,(]\s*[A-Za-z_$][\w$]*)\s*:\s*[^,)=\n]+/g,`$1`).replace(/\)\s*:\s*[^={\n]+(?=\s*(?:=>|\{))/g,`)`).replace(/\s+as\s+[A-Za-z_$][\w$<>,[\]|&\s.]*/g,``).replace(/<(?:[A-Za-z_$][\w$]*\s*,?\s*)+>(?=\s*\()/g,``)}export{t as evaluate};

package/packages/tools/dist/evidence-map.d.ts

@@ -0,0 +1,92 @@
+//#region packages/tools/src/evidence-map.d.ts
+/**
+ * aikit_evidence_map — FORGE Evidence Map CRUD + Gate evaluator.
+ *
+ * Structured storage, validation, and gate evaluation for FORGE Evidence Map entries.
+ * Persisted in .aikit-state/evidence-maps.json.
+ */
+type EvidenceStatus = 'V' | 'A' | 'U';
+type UnknownType = 'contract' | 'convention' | 'freshness' | 'runtime' | 'data-flow' | 'impact';
+type GateDecision = 'YIELD' | 'HOLD' | 'HARD_BLOCK' | 'FORCED_DELIVERY';
+type ForgeTier = 'floor' | 'standard' | 'critical';
+type SafetyGate = 'provenance' | 'commitment' | 'coverage';
+interface EvidenceEntry {
+  id: number;
+  claim: string;
+  status: EvidenceStatus;
+  receipt: string;
+  criticalPath: boolean;
+  unknownType?: UnknownType;
+  safetyGate?: SafetyGate;
+}
+interface EvidenceMapState {
+  taskId: string;
+  tier: ForgeTier;
+  entries: EvidenceEntry[];
+  createdAt: string;
+  updatedAt: string;
+}
+interface SafetyGateResult {
+  provenance: 'pass' | 'fail';
+  commitment: 'pass' | 'fail';
+  coverage: 'pass' | 'fail';
+  failures: string[];
+}
+interface GateResult {
+  decision: GateDecision;
+  reason: string;
+  unresolvedCritical: EvidenceEntry[];
+  warnings: string[];
+  stats: {
+    total: number;
+    verified: number;
+    assumed: number;
+    unresolved: number;
+  };
+  safetyGates?: SafetyGateResult;
+  annotation?: string;
+}
+type EvidenceMapAction = {
+  action: 'create';
+  taskId: string;
+  tier: ForgeTier;
+} | {
+  action: 'add';
+  taskId: string;
+  claim: string;
+  status: EvidenceStatus;
+  receipt: string;
+  criticalPath?: boolean;
+  unknownType?: UnknownType;
+  safetyGate?: SafetyGate;
+} | {
+  action: 'update';
+  taskId: string;
+  id: number;
+  status: EvidenceStatus;
+  receipt: string;
+} | {
+  action: 'get';
+  taskId: string;
+} | {
+  action: 'gate';
+  taskId: string;
+  retryCount?: number;
+} | {
+  action: 'list';
+} | {
+  action: 'delete';
+  taskId: string;
+};
+interface EvidenceMapResult {
+  state?: EvidenceMapState;
+  states?: EvidenceMapState[];
+  entry?: EvidenceEntry;
+  gate?: GateResult;
+  deleted?: boolean;
+  formattedMap?: string;
+}
+declare function evidenceMap(action: EvidenceMapAction, cwd?: string): EvidenceMapResult;
+declare function autoClaimTestFailures(taskId: string, failures: string[], cwd?: string): EvidenceEntry[];
+//#endregion
+export { EvidenceEntry, EvidenceMapAction, EvidenceMapResult, EvidenceMapState, EvidenceStatus, ForgeTier, GateDecision, GateResult, SafetyGate, SafetyGateResult, UnknownType, autoClaimTestFailures, evidenceMap };

package/packages/tools/dist/evidence-map.js

@@ -0,0 +1,2 @@
+import{dirname as e,resolve as t}from"node:path";import{existsSync as n,mkdirSync as r,readFileSync as i,writeFileSync as a}from"node:fs";import{AIKIT_PATHS as o}from"../../core/dist/index.js";const s=o.state;function c(e){return t(e??process.cwd(),s,`evidence-maps.json`)}function l(e){let t=c(e);if(!n(t))return{};try{let e=i(t,`utf-8`);return JSON.parse(e)}catch{return{}}}function u(t,i){let o=c(i),s=e(o);n(s)||r(s,{recursive:!0}),a(o,`${JSON.stringify(t,null,2)}\n`,`utf-8`)}function d(e,t){let n=l(t),r=n[e];if(!r)throw Error(`Evidence map not found: ${e}`);return{maps:n,state:r}}function f(e){return e.reduce((e,t)=>Math.max(e,t.id),0)+1}function p(e){let t=e.trim();if(!t)throw Error(`Claim is required`);if(/\r?\n/.test(t))throw Error(`Claim must be a single line`);return t}function m(e){return(e??``).replace(/\r?\n/g,` `).replace(/\|/g,`\\|`)}function h(e){let t=[`| # | Claim | Status | Receipt | Critical | Type | Safety |`,`|---|-------|--------|---------|----------|------|--------|`];for(let n of e.entries)t.push(`| ${n.id} | ${m(n.claim)} | ${n.status} | ${m(n.receipt)} | ${n.criticalPath?`yes`:`no`} | ${m(n.unknownType)} | ${m(n.safetyGate)} |`);return t.join(`
+`)}function g(e){return{total:e.length,verified:e.filter(e=>e.status===`V`).length,assumed:e.filter(e=>e.status===`A`).length,unresolved:e.filter(e=>e.status===`U`).length}}function _(e){let t=[];for(let n of e.entries)n.status===`V`&&n.receipt.trim()===``&&t.push(`V entry without receipt`),n.status===`A`&&e.tier===`critical`&&n.unknownType===`contract`&&t.push(`Assumed contract at Critical tier — should be Verified`);return t}function v(e){return`FORCED DELIVERY annotation: unresolved entries remain -> ${e.filter(e=>e.status===`U`).map(e=>`#${e.id} ${e.claim}`).join(`; `)}`}function y(e){let t=[],n=e.entries.filter(e=>e.status===`V`&&!e.receipt.trim());n.length>0&&t.push(`Provenance: ${n.length} verified claim(s) lack receipts`);let r=e.entries.filter(e=>e.safetyGate===`commitment`&&e.status!==`V`);r.length>0&&t.push(`Commitment: ${r.length} commitment(s) not verified`);let i=e.entries.some(e=>e.safetyGate===`coverage`&&e.status===`U`);return i&&t.push(`Coverage: unresolved coverage entries remain`),{provenance:n.length>0?`fail`:`pass`,commitment:r.length>0?`fail`:`pass`,coverage:i?`fail`:`pass`,failures:t}}function b(e,t=0){let n=e.entries.filter(e=>e.criticalPath&&e.status===`U`),r=_(e),i=g(e.entries);return n.find(e=>e.unknownType===`contract`)?{decision:`HARD_BLOCK`,reason:`Unresolved contract unknown on critical path`,unresolvedCritical:n,warnings:r,stats:i}:n.length>0&&t===0?{decision:`HOLD`,reason:`Unresolved critical-path unknown — retry available`,unresolvedCritical:n,warnings:r,stats:i}:n.length>0&&t>=1?{decision:`FORCED_DELIVERY`,reason:`Unresolved critical-path unknown after retry`,unresolvedCritical:n,warnings:r,stats:i,annotation:v(e.entries)}:{decision:`YIELD`,reason:`All critical-path claims satisfy gate rules`,unresolvedCritical:[],warnings:r,stats:i,...x(e,r,i)}}function x(e,t,n){if(!e.entries.some(e=>e.safetyGate)||e.tier===`floor`)return{};let r=y(e);return r.failures.length>0?{safetyGates:r,decision:`HOLD`,reason:`Safety gate failure: ${r.failures.join(`; `)}`,warnings:[...t,...r.failures]}:{safetyGates:r}}function S(e,t){switch(e.action){case`create`:{let n=l(t),r=new Date().toISOString(),i={taskId:e.taskId,tier:e.tier,entries:[],createdAt:r,updatedAt:r};return n[e.taskId]=i,u(n,t),{state:i,formattedMap:h(i)}}case`add`:{let{maps:n,state:r}=d(e.taskId,t),i={id:f(r.entries),claim:p(e.claim),status:e.status,receipt:e.receipt,criticalPath:e.criticalPath??!1,unknownType:e.unknownType,safetyGate:e.safetyGate};return r.entries.push(i),r.updatedAt=new Date().toISOString(),n[e.taskId]=r,u(n,t),{state:r,entry:i,formattedMap:h(r)}}case`update`:{let{maps:n,state:r}=d(e.taskId,t),i=r.entries.find(t=>t.id===e.id);if(!i)throw Error(`Evidence entry not found: ${e.id}`);return i.status=e.status,i.receipt=e.receipt,r.updatedAt=new Date().toISOString(),n[e.taskId]=r,u(n,t),{state:r,entry:i,formattedMap:h(r)}}case`get`:{let{state:n}=d(e.taskId,t);return{state:n,formattedMap:h(n)}}case`gate`:{let{state:n}=d(e.taskId,t);return{state:n,gate:b(n,e.retryCount??0),formattedMap:h(n)}}case`list`:return{states:Object.values(l(t)).sort((e,t)=>e.createdAt.localeCompare(t.createdAt))};case`delete`:{let n=l(t);return e.taskId in n?(delete n[e.taskId],u(n,t),{deleted:!0}):{deleted:!1}}}}function C(e,t,n){let r=[];for(let i of t){let t=S({action:`add`,taskId:e,claim:`Test failure: ${i}`,status:`U`,receipt:``,criticalPath:!0},n);t.entry&&r.push(t.entry)}return r}export{C as autoClaimTestFailures,S as evidenceMap};

package/packages/tools/dist/file-cache.d.ts

@@ -0,0 +1,41 @@
+//#region packages/tools/src/file-cache.d.ts
+interface FileCacheEntry {
+  /** Full file content */
+  content: string;
+  /** SHA-256 hash of content */
+  hash: string;
+  /** Line count */
+  lines: number;
+  /** Estimated token count (~chars/4) */
+  estimatedTokens: number;
+  /** How many times this file has been requested */
+  hitCount: number;
+  /** Whether content changed since last read (false on cache hit) */
+  changed: boolean;
+}
+interface FileCacheStats {
+  totalReads: number;
+  cacheHits: number;
+  filesTracked: number;
+}
+declare class FileCache {
+  private cache;
+  private totalReads;
+  private cacheHits;
+  private static readonly MAX_ENTRIES;
+  /**
+   * Get file content with deduplication.
+   * First call: reads from disk, hashes, caches.
+   * Subsequent calls: checks mtime → if unchanged, cache hit (skip read).
+   * If mtime changed: re-reads, re-hashes, checks if content actually changed.
+   */
+  get(filePath: string): Promise<FileCacheEntry>;
+  /** Remove a single file from cache. Returns true if it was cached. */
+  invalidate(filePath: string): boolean;
+  /** Clear all cached files. Returns how many were cleared. */
+  clear(): number;
+  /** Get cache statistics. */
+  stats(): FileCacheStats;
+}
+//#endregion
+export { FileCache, FileCacheEntry, FileCacheStats };

package/packages/tools/dist/file-cache.js

@@ -0,0 +1,3 @@
+import{estimateTokens as e}from"./text-utils.js";import{readFile as t,stat as n}from"node:fs/promises";import{resolve as r}from"node:path";import{createHash as i}from"node:crypto";var a=class i{cache=new Map;totalReads=0;cacheHits=0;static MAX_ENTRIES=500;async get(a){let s=r(a);this.totalReads++;let c=await n(s);if(c.isDirectory())throw Error(`Path is a directory: ${a}. Expected a file path, not a directory. Use analyze_structure or find to explore directories.`);let l=c.mtimeMs,u=this.cache.get(s);if(u){if(u.mtimeMs===l)return this.cacheHits++,u.hitCount++,{content:u.content,hash:u.hash,lines:u.lines,estimatedTokens:u.estimatedTokens,hitCount:u.hitCount,changed:!1};let n=await t(s,`utf-8`),r=o(n);if(r===u.hash)return this.cacheHits++,u.hitCount++,u.mtimeMs=l,{content:u.content,hash:u.hash,lines:u.lines,estimatedTokens:u.estimatedTokens,hitCount:u.hitCount,changed:!1};let i=n.split(`
+`).length,a=e(n);return u.content=n,u.hash=r,u.lines=i,u.estimatedTokens=a,u.hitCount++,u.mtimeMs=l,{content:n,hash:r,lines:i,estimatedTokens:a,hitCount:u.hitCount,changed:!0}}let d=await t(s,`utf-8`),f=o(d),p=d.split(`
+`).length,m=e(d);if(this.cache.set(s,{content:d,hash:f,lines:p,estimatedTokens:m,hitCount:1,mtimeMs:l}),this.cache.size>i.MAX_ENTRIES){let e=this.cache.keys().next().value;e&&this.cache.delete(e)}return{content:d,hash:f,lines:p,estimatedTokens:m,hitCount:1,changed:!0}}invalidate(e){return this.cache.delete(r(e))}clear(){let e=this.cache.size;return this.cache.clear(),e}stats(){return{totalReads:this.totalReads,cacheHits:this.cacheHits,filesTracked:this.cache.size}}};function o(e){return i(`sha256`).update(e).digest(`hex`)}export{a as FileCache};

package/packages/tools/dist/file-summary.d.ts

@@ -0,0 +1,52 @@
+//#region packages/tools/src/file-summary.d.ts
+interface FileSummaryOptions {
+  path: string;
+  /** Pre-loaded content — skip readFile when provided (e.g., from FileCache) */
+  content?: string;
+  previewLines?: number;
+}
+interface FileSummaryResult {
+  path: string;
+  lines: number;
+  language: string;
+  imports: string[];
+  exports: string[];
+  functions: Array<{
+    name: string;
+    line: number;
+    exported: boolean;
+    signature?: string;
+  }>;
+  classes: Array<{
+    name: string;
+    line: number;
+    exported: boolean;
+    signature?: string;
+  }>;
+  interfaces: Array<{
+    name: string;
+    line: number;
+    exported: boolean;
+  }>;
+  types: Array<{
+    name: string;
+    line: number;
+    exported: boolean;
+  }>;
+  /** Import details with external/internal classification (AST-powered) */
+  importDetails?: Array<{
+    source: string;
+    specifiers: string[];
+    isExternal: boolean;
+  }>;
+  /** Intra-file call edges showing which functions call which (AST-powered) */
+  callEdges?: Array<{
+    caller: string;
+    callee: string;
+    line: number;
+  }>;
+  estimatedTokens: number;
+}
+declare function fileSummary(options: FileSummaryOptions): Promise<FileSummaryResult>;
+//#endregion
+export { FileSummaryOptions, FileSummaryResult, fileSummary };

package/packages/tools/dist/file-summary.js

@@ -0,0 +1,2 @@
+import{readFile as e,stat as t}from"node:fs/promises";import{extname as n}from"node:path";import{SUPPORTED_EXTENSIONS as r,WasmRuntime as i,extractCalls as a,extractImports as o,extractSymbols as s}from"../../chunker/dist/index.js";async function c(a){let{path:o,previewLines:s=3}=a;if(!a.content){let e;try{e=await t(o)}catch(e){let t=e.code;throw t===`ENOENT`?Error(`File not found: ${o}. Check the path and try again.`):t===`EACCES`||t===`EPERM`?Error(`Permission denied reading ${o}. The file exists but is not accessible.`):e}if(e.isDirectory())throw Error(`Path is a directory: ${o}. file_summary requires a file path, not a directory. Use analyze_structure or find to explore directories.`);if(e.size>1e7)throw Error(`File too large (${(e.size/1e6).toFixed(1)}MB). file_summary supports files up to 10MB. Use search or compact with a query instead.`)}let c=a.content??await e(o,`utf-8`),d=c.split(`
+`),f=o.split(`.`).pop()??``,p=n(o);return i.get()&&r.has(p)?l(o,c,d,f,p):u(o,c,d,f)}async function l(e,t,n,r,i){let[c,l,u]=await Promise.all([s(t,i,e),o(t,i,e),a(t,i,e).catch(()=>[])]),f=l.map(e=>`import ${e.specifiers.length>0?`{ ${e.specifiers.join(`, `)} }`:`*`} from '${e.source}'`),p=[],m=[],h=[],g=[],_=[];for(let e of c)switch(e.exported&&p.push(e.name),e.kind){case`function`:case`method`:m.push({name:e.name,line:e.line,exported:e.exported,signature:e.signature});break;case`class`:h.push({name:e.name,line:e.line,exported:e.exported,signature:e.signature});break;case`interface`:g.push({name:e.name,line:e.line,exported:e.exported});break;case`type`:_.push({name:e.name,line:e.line,exported:e.exported});break}let v=l.map(e=>({source:e.source,specifiers:e.specifiers,isExternal:e.isExternal})),y=u.map(e=>({caller:e.callerName,callee:e.calleeName,line:e.line}));return{path:e,lines:n.length,language:d(r),imports:f,exports:p,functions:m,classes:h,interfaces:g,types:_,importDetails:v,callEdges:y.length>0?y:void 0,estimatedTokens:Math.ceil(t.length/4)}}function u(e,t,n,r){let i=[],a=[],o=[],s=[],c=[],l=[];for(let e=0;e<n.length;e+=1){let t=n[e],r=e+1;if(/^import\s+.+/.test(t)){i.push(t.trim());continue}let u=t.match(/^export\s+(?:async\s+)?function\s+(\w+)/);if(u){o.push({name:u[1],line:r,exported:!0}),a.push(u[1]);continue}let d=t.match(/^(?:async\s+)?function\s+(\w+)/);if(d){o.push({name:d[1],line:r,exported:!1});continue}let f=t.match(/^(export\s+)?const\s+(\w+)\s*=.*(?:=>|\bfunction\b)/);if(f){let e=!!f[1];o.push({name:f[2],line:r,exported:e}),e&&a.push(f[2]);continue}let p=t.match(/^export\s+const\s+(\w+)\s*=/);if(p){a.push(p[1]);continue}let m=t.match(/^(export\s+)?(?:abstract\s+)?class\s+(\w+)/);if(m){let e=!!m[1];s.push({name:m[2],line:r,exported:e}),e&&a.push(m[2]);continue}let h=t.match(/^(export\s+)?interface\s+(\w+)/);if(h){let e=!!h[1];c.push({name:h[2],line:r,exported:e}),e&&a.push(h[2]);continue}let g=t.match(/^(export\s+)?type\s+(\w+)/);if(g){let e=!!g[1];l.push({name:g[2],line:r,exported:e}),e&&a.push(g[2]);continue}let _=t.match(/^export\s+\{(.+)\}/);if(_){let e=_[1].split(`,`).map(e=>e.trim().split(/\s+as\s+/).pop()?.trim()??``).filter(Boolean);a.push(...e)}}return{path:e,lines:n.length,language:d(r),imports:i,exports:a,functions:o,classes:s,interfaces:c,types:l,estimatedTokens:Math.ceil(t.length/4)}}function d(e){return{ts:`typescript`,tsx:`typescript-jsx`,js:`javascript`,jsx:`javascript-jsx`,py:`python`,rs:`rust`,go:`go`,java:`java`,rb:`ruby`,md:`markdown`,json:`json`,yaml:`yaml`,yml:`yaml`,css:`css`,html:`html`,sh:`shell`,bash:`shell`}[e]??e}export{c as fileSummary};

package/packages/tools/dist/file-walk.d.ts

@@ -0,0 +1,6 @@
+//#region packages/tools/src/file-walk.d.ts
+declare const DEFAULT_TOOL_EXTENSIONS: string[];
+declare function matchesGlobPattern(path: string, pattern: string): boolean;
+declare function walkFiles(rootPath: string, extensions: string[], exclude: string[]): Promise<string[]>;
+//#endregion
+export { DEFAULT_TOOL_EXTENSIONS, matchesGlobPattern, walkFiles };

package/packages/tools/dist/file-walk.js

@@ -0,0 +1 @@
+import{readdir as e,stat as t}from"node:fs/promises";import{extname as n,join as r,relative as i}from"node:path";import{AIKIT_PATHS as a}from"../../core/dist/index.js";const o=[`.ts`,`.tsx`,`.js`,`.jsx`],s=new Set([`node_modules`,`.git`,`dist`,`build`,`coverage`,`.turbo`,`.cache`,`cdk.out`,a.state]);function c(e){return e.replace(/\\/g,`/`)}function l(e){return e.replace(/[.+^${}()|[\]\\]/g,`\\$&`)}function u(e,t){let n=c(e),r=c(t).trim();if(!r)return!1;let i=l(r).replace(/\*\*/g,`::DOUBLE_STAR::`).replace(/\*/g,`[^/]*`).replace(/\?/g,`[^/]`).replace(/::DOUBLE_STAR::/g,`.*`);return RegExp(`^${i}$`).test(n)}function d(e,t,n){return t.some(t=>u(e,t)?!0:n?u(`${e}/`,t):!1)}async function f(a,o,l){let u=[],f=o.map(e=>e.toLowerCase());async function p(o){let m=await e(o);for(let e of m){if(s.has(e))continue;let m=r(o,e),h=await t(m),g=c(i(a,m));if(h.isDirectory()){d(g,l,!0)||await p(m);continue}d(g,l,!1)||f.includes(n(e).toLowerCase())&&u.push(m)}}return await p(a),u.sort((e,t)=>e.localeCompare(t)),u}export{o as DEFAULT_TOOL_EXTENSIONS,u as matchesGlobPattern,f as walkFiles};

package/packages/tools/dist/find-examples.d.ts

@@ -0,0 +1,29 @@
+import { ContentType } from "../../core/dist/index.js";
+import { IEmbedder } from "../../embeddings/dist/index.js";
+import { IKnowledgeStore } from "../../store/dist/index.js";
+
+//#region packages/tools/src/find-examples.d.ts
+interface FindExamplesOptions {
+  /** Symbol or pattern to find examples of */
+  query: string;
+  /** Max examples to return (default: 5) */
+  limit?: number;
+  /** Filter by content type */
+  contentType?: ContentType;
+}
+interface Example {
+  path: string;
+  startLine: number;
+  endLine: number;
+  content: string;
+  relevance: number;
+  context: string;
+}
+interface FindExamplesResult {
+  query: string;
+  examples: Example[];
+  totalFound: number;
+}
+declare function findExamples(embedder: IEmbedder, store: IKnowledgeStore, options: FindExamplesOptions): Promise<FindExamplesResult>;
+//#endregion
+export { Example, FindExamplesOptions, FindExamplesResult, findExamples };

package/packages/tools/dist/find-examples.js

@@ -0,0 +1,3 @@
+import{escapeRegExp as e}from"./regex-utils.js";async function t(t,n,r){let{query:i,limit:a=5,contentType:o}=r,s=`usage example of ${i}`,c=await t.embed(s),l=await n.search(c,{limit:a*3,contentType:o}),u=RegExp(`\\b${e(i)}\\b`,`i`),d=l.filter(e=>u.test(e.record.content));return{query:i,examples:d.map(e=>{let t=e.record.content,n=/export\s+(?:async\s+)?(?:function|class|const|interface|type)\s/.test(t),r=/^\s*import\s/m.test(t),i=/(?:^|[\\/])(test|tests|__tests__|spec)(?:[\\/]|$)/i.test(e.record.sourcePath)||/\.(test|spec)\.[jt]sx?$/i.test(e.record.sourcePath),a=0;n||(a+=.1),r||(a+=.05),i&&(a+=.05);let o=t.split(`
+`),s=o.findIndex(e=>u.test(e)),c=Math.max(0,s-2),l=Math.min(o.length,s+5),d=o.slice(c,l).join(`
+`);return{path:e.record.sourcePath,startLine:e.record.startLine,endLine:e.record.endLine,content:d||t.slice(0,300),relevance:Math.min(1,e.score+a),context:i?`test`:n?`definition`:`usage`}}).sort((e,t)=>t.relevance-e.relevance).slice(0,a),totalFound:d.length}}export{t as findExamples};

package/packages/tools/dist/find.d.ts

@@ -0,0 +1,49 @@
+import { ContentType } from "../../core/dist/index.js";
+import { IEmbedder } from "../../embeddings/dist/index.js";
+import { IKnowledgeStore } from "../../store/dist/index.js";
+
+//#region packages/tools/src/find.d.ts
+interface FindOptions {
+  /** Semantic search query (optional) */
+  query?: string;
+  /** File glob pattern (optional) */
+  glob?: string;
+  /** Keyword/regex pattern for text search (optional) */
+  pattern?: string;
+  /** Max results per strategy (default: 10) */
+  limit?: number;
+  /** Filter by content type */
+  contentType?: ContentType;
+  /** Working directory for glob resolution (default: cwd) */
+  cwd?: string;
+}
+interface FindResult {
+  /** File path (relative to cwd) */
+  path: string;
+  /** How this result was found */
+  source: 'vector' | 'keyword' | 'glob' | 'pattern';
+  /** Relevance score (0-1 for vector/keyword, 1 for glob/pattern matches) */
+  score: number;
+  /** Line range if from KB search */
+  lineRange?: {
+    start: number;
+    end: number;
+  };
+  /** Content preview */
+  preview?: string;
+}
+interface FindResults {
+  results: FindResult[];
+  strategies: string[];
+  totalFound: number;
+  failedStrategies?: Array<{
+    strategy: string;
+    reason: string;
+  }>;
+}
+/**
+ * Run federated search across multiple strategies.
+ */
+declare function find(embedder: IEmbedder, store: IKnowledgeStore, options: FindOptions): Promise<FindResults>;
+//#endregion
+export { FindOptions, FindResult, FindResults, find };

package/packages/tools/dist/find.js

@@ -0,0 +1 @@
+import{AIKIT_PATHS as e}from"../../core/dist/index.js";async function t(t,n,r){let{query:i,glob:a,pattern:o,limit:s=10,contentType:c,cwd:l=process.cwd()}=r,u=[],d=[],f=new Set,p=[];if(i){u.push(`vector`);let e=await t.embed(i),r={limit:s,contentType:c},a=await n.search(e,r);for(let e of a){let t=`${e.record.sourcePath}:${e.record.startLine}`;f.has(t)||(f.add(t),d.push({path:e.record.sourcePath,source:`vector`,score:e.score,lineRange:{start:e.record.startLine,end:e.record.endLine},preview:e.record.content.slice(0,200)}))}}if(i){u.push(`keyword`);try{let e=await n.ftsSearch(i,{limit:s,contentType:c});for(let t of e){let e=`${t.record.sourcePath}:${t.record.startLine}`;f.has(e)||(f.add(e),d.push({path:t.record.sourcePath,source:`keyword`,score:t.score,lineRange:{start:t.record.startLine,end:t.record.endLine},preview:t.record.content.slice(0,200)}))}}catch(e){p.push({strategy:`keyword`,reason:e instanceof Error?e.message:String(e)})}}if(a){u.push(`glob`);try{let{globSync:t}=await import(`node:fs`),n=t(a,{cwd:l,withFileTypes:!1}),r=new Set([`node_modules`,`.git`,`dist`,`build`,`coverage`,`.turbo`,`.cache`,`cdk.out`,e.state,e.data]),i=n.filter(e=>!e.replace(/\\/g,`/`).split(`/`).some(e=>r.has(e)));for(let e of i.slice(0,s)){let t=`glob:${e}`;f.has(t)||(f.add(t),d.push({path:e,source:`glob`,score:1}))}}catch(e){p.push({strategy:`glob`,reason:e instanceof Error?e.message:String(e)})}}if(o){u.push(`pattern`);try{let e=new RegExp(o,`i`),t=await n.ftsSearch(o,{limit:s*2,contentType:c});for(let n of t)if(e.test(n.record.content)){let e=`${n.record.sourcePath}:${n.record.startLine}`;f.has(e)||(f.add(e),d.push({path:n.record.sourcePath,source:`pattern`,score:n.score,lineRange:{start:n.record.startLine,end:n.record.endLine},preview:n.record.content.slice(0,200)}))}}catch(e){p.push({strategy:`pattern`,reason:e instanceof Error?e.message:String(e)})}}return d.sort((e,t)=>t.score-e.score),{results:d.slice(0,s),strategies:u,totalFound:d.length,...p.length>0&&{failedStrategies:p}}}export{t as find};

package/packages/tools/dist/forge-classify.d.ts

@@ -0,0 +1,44 @@
+import { ForgeTier } from "./evidence-map.js";
+
+//#region packages/tools/src/forge-classify.d.ts
+interface ForgeClassifyOptions {
+  /** Files being modified (absolute or relative paths) */
+  files: string[];
+  /** Task description for keyword detection */
+  task: string;
+  /** Root path for package boundary detection */
+  rootPath: string;
+}
+interface ClassifyTrigger {
+  rule: string;
+  detail: string;
+  source: 'blast_radius' | 'cross_package' | 'schema_contract' | 'security_auth' | 'task_hint' | 'default';
+}
+interface TypedUnknownSeed {
+  description: string;
+  type: 'contract' | 'convention' | 'freshness' | 'runtime' | 'data-flow' | 'impact';
+  suggestedTool: string;
+}
+interface ForgeClassifyCeremony {
+  ground: string;
+  build: string;
+  break: string;
+  evidenceMap: string;
+  gate: string;
+}
+interface ForgeClassifyResult {
+  tier: ForgeTier;
+  triggers: ClassifyTrigger[];
+  packagesCrossed: string[];
+  hasSchemaChange: boolean;
+  hasSecurityPath: boolean;
+  typedUnknownSeeds: TypedUnknownSeed[];
+  ceremony: ForgeClassifyCeremony;
+  reclassifyHint?: {
+    suggestedTier: ForgeTier;
+    reason: string;
+  };
+}
+declare function forgeClassify(options: ForgeClassifyOptions): Promise<ForgeClassifyResult>;
+//#endregion
+export { ClassifyTrigger, ForgeClassifyCeremony, ForgeClassifyOptions, ForgeClassifyResult, TypedUnknownSeed, forgeClassify };

package/packages/tools/dist/forge-classify.js

@@ -0,0 +1,2 @@
+import{fileSummary as e}from"./file-summary.js";import{dirname as t,extname as n,relative as r,resolve as i}from"node:path";import{existsSync as a,readFileSync as o,readdirSync as s,statSync as c}from"node:fs";import{AIKIT_PATHS as l}from"../../core/dist/index.js";const u=new Set([`.ts`,`.tsx`,`.js`,`.jsx`,`.mts`,`.cts`,`.mjs`,`.cjs`]),d=new Set([`.git`,l.data,l.state,`.turbo`,`.yarn`,`build`,`coverage`,`dist`,`node_modules`]),f=/auth|token|permission|acl|encrypt|secret|credential|jwt|oauth|password/i,p=/\b(hash|sign|verify|bcrypt|jwt|decrypt|secret|password)\b/i,m=/auth|security|permission|encrypt|secret|credential/i,h=/types\.ts$|schema\.ts$|contract\.ts$|\.proto$|openapi|swagger|\.graphql$/i,g=/(?:^|\/)(events|contracts|shared)(?:\/|$)/i,_=/export\s+interface\b|export\s+type\b|export\s+const\s+\w*Schema\w*\s*=\s*z\./i,v=/schema|contract|migration|breaking.change|api.change/i,y=/migration|data.?model|multi.?service|breaking|backward.?compat/i,b={floor:{ground:`Parasitic — read target file only`,build:`Implement directly`,break:`Skip`,evidenceMap:`Not required`,gate:`Self-certify`},standard:{ground:`Scope map + blast radius + constraint seed`,build:`TDD — test first, then implement`,break:`Error paths + edge cases`,evidenceMap:`3-8 critical-path entries`,gate:`YIELD/HOLD evaluation`},critical:{ground:`Full scope map + blast radius + trace + patterns + constraint pack`,build:`TDD + contract verification + cross-service validation`,break:`Error paths + edge cases + security dimensions + data-flow verification`,evidenceMap:`Comprehensive — all critical-path claims with receipts`,gate:`Strict YIELD/HOLD/HARD_BLOCK evaluation`}};async function x(e){let t=i(e.rootPath),n=e.task.trim(),r=e.files.map(e=>i(t,e)),a=[],o=!1,s=!1;for(let e of r){let r=C(e,t),i=T(e);(f.test(r)||p.test(i)||m.test(n))&&(o=!0),(h.test(r)||g.test(r)||v.test(n)||_.test(i)||await E(e))&&(s=!0)}o&&S(a,{rule:`security-path`,detail:`Security/auth path, task, or content matched security heuristics`,source:`security_auth`}),s&&S(a,{rule:`schema-contract`,detail:`Schema or contract path, task, or export shape matched contract heuristics`,source:`schema_contract`});let c=D(r,t);c.affectedFiles>5&&S(a,{rule:`blast-radius-importers`,detail:`${c.affectedFiles} affected files via direct import scanning`,source:`blast_radius`});let l=[...new Set(r.map(e=>M(e,t)).filter(e=>!!e))].sort();l.length>=2&&S(a,{rule:`cross-package-boundary`,detail:`Files span ${l.length} packages: ${l.join(`, `)}`,source:`cross_package`}),y.test(n)&&S(a,{rule:`task-hint-critical`,detail:`Task description matched migration or compatibility criticality hints`,source:`task_hint`});let u=a.length>0?`critical`:r.length===1?`floor`:`standard`;u===`floor`&&(o||s)&&(u=`standard`);let d=j(a),x=u===`floor`&&d.some(e=>e.type===`contract`)?{suggestedTier:`standard`,reason:`Contract-type unknowns detected — Floor may be insufficient`}:void 0;return{tier:u,triggers:a,packagesCrossed:l,hasSchemaChange:s,hasSecurityPath:o,typedUnknownSeeds:d,ceremony:b[u],reclassifyHint:x}}function S(e,t){e.some(e=>e.rule===t.rule&&e.source===t.source)||e.push(t)}function C(e,t){let n=i(t,e),a=r(t,n);return(a&&!a.startsWith(`..`)?a:n).replace(/\\/g,`/`)}function w(e){if(!a(e))return!1;try{return c(e).size<=1e5}catch{return!1}}function T(e){if(!w(e))return``;try{return o(e,`utf-8`).split(/\r?\n/).slice(0,200).join(`
+`)}catch{return``}}async function E(t){if(!w(t))return!1;try{let n=await e({path:t}),r=new Set(n.exports);return n.interfaces.some(e=>r.has(e.name))||n.types.some(e=>r.has(e.name))}catch{return!1}}function D(e,t){let n=new Set(e.filter(e=>a(e)));if(n.size===0)return{affectedFiles:e.length,importers:[]};let i=new Set;for(let e of O(t)){if(n.has(e)||!w(e))continue;let t=T(e);t&&k(t).some(t=>A(t,e,n))&&i.add(e)}return{affectedFiles:e.length+i.size,importers:[...i].map(e=>r(t,e).replace(/\\/g,`/`))}}function O(e){let t=[];function r(e){let a=[];try{a=s(e)}catch{return}for(let o of a){if(d.has(o))continue;let a=i(e,o),s;try{s=c(a)}catch{continue}if(s.isDirectory()){r(a);continue}u.has(n(o).toLowerCase())&&t.push(a)}}return r(e),t}function k(e){let t=new Set;for(let n of e.matchAll(/(?:from\s+['"]([^'"]+)['"]|import\s+['"]([^'"]+)['"]|require\(\s*['"]([^'"]+)['"]\s*\))/g)){let e=n[1]??n[2]??n[3];e&&t.add(e)}return[...t]}function A(e,n,r){if(!e.startsWith(`.`))return!1;let a=i(t(n),e);return[a,`${a}.ts`,`${a}.tsx`,`${a}.js`,`${a}.jsx`,`${a}.mts`,`${a}.cts`,`${a}.mjs`,`${a}.cjs`,i(a,`index.ts`),i(a,`index.tsx`),i(a,`index.js`),i(a,`index.jsx`)].some(e=>r.has(e))}function j(e){return e.map(e=>{switch(e.source){case`security_auth`:return{description:`Verify auth and security assumptions before yielding`,type:`contract`,suggestedTool:`aikit_search`};case`schema_contract`:return{description:`Confirm schema and contract compatibility`,type:`contract`,suggestedTool:`aikit_schema_validate`};case`blast_radius`:return{description:`Inspect affected importers before delivery`,type:`impact`,suggestedTool:`aikit_blast_radius`};case`cross_package`:return{description:`Assess downstream package impact across boundaries`,type:`impact`,suggestedTool:`aikit_blast_radius`};case`task_hint`:return{description:`Check established conventions for migrations or compatibility work`,type:`convention`,suggestedTool:`aikit_find`};default:return{description:`No explicit unknown routing required`,type:`freshness`,suggestedTool:`aikit_lookup`}}})}function M(e,n){let s=t(i(n,e)),c=i(n);for(;s.length>=c.length;){let e=i(s,`package.json`);if(a(e))try{return JSON.parse(o(e,`utf-8`)).name??r(c,s).replace(/\\/g,`/`)}catch{return r(c,s).replace(/\\/g,`/`)}let n=t(s);if(n===s)break;s=n}}export{x as forgeClassify};

package/packages/tools/dist/forge-ground.d.ts

@@ -0,0 +1,61 @@
+import { ForgeTier } from "./evidence-map.js";
+import { ClassifyTrigger, TypedUnknownSeed } from "./forge-classify.js";
+import { ScopeMapResult } from "./scope-map.js";
+import { IEmbedder } from "../../embeddings/dist/index.js";
+import { IKnowledgeStore } from "../../store/dist/index.js";
+
+//#region packages/tools/src/forge-ground.d.ts
+interface ForgeGroundOptions {
+  /** Task description */
+  task: string;
+  /** Target files being modified (absolute paths) */
+  files: string[];
+  /** Root path of the codebase */
+  rootPath: string;
+  /** Max constraint entries to load (default: 3) */
+  maxConstraints?: number;
+  /** Force a specific tier (skip auto-classify) */
+  forceTier?: ForgeTier;
+  /** Task ID for evidence map creation (default: auto-generated from task) */
+  taskId?: string;
+}
+interface ConstraintRef {
+  source: string;
+  snippet: string;
+  relevance: number;
+}
+interface ForgeGroundResult {
+  /** Computed or forced tier */
+  tier: ForgeTier;
+  /** Classification triggers (empty if tier was forced) */
+  classifyTriggers: ClassifyTrigger[];
+  /** Scope map (relevant files with focus ranges) — null for Floor tier */
+  scopeMap: ScopeMapResult | null;
+  /** Typed Unknown Queue seeds */
+  typedUnknownSeeds: TypedUnknownSeed[];
+  /** Constraint seed — relevant KB entries from decisions/patterns */
+  constraints: ConstraintRef[];
+  /** File summaries for target files */
+  fileSummaries: Array<{
+    path: string;
+    exports: string[];
+    functions: string[];
+    lines: number;
+    error?: string;
+  }>;
+  /** Evidence map task ID (created if Standard or Critical) */
+  evidenceMapTaskId: string | null;
+  /** Total estimated tokens for this Ground output */
+  estimatedTokens: number;
+  /** Ceremony recommendations for this tier */
+  ceremony: {
+    ground: string;
+    build: string;
+    break: string;
+    evidenceMap: string;
+    gate: string;
+  };
+}
+declare function forgeGround(embedder: IEmbedder, store: IKnowledgeStore, options: ForgeGroundOptions): Promise<ForgeGroundResult>;
+//#endregion
+export { ConstraintRef, ForgeGroundOptions, ForgeGroundResult, forgeGround };