weavatrix 0.1.4 → 0.2.1

package/src/mcp/tools-actions.mjs

@@ -1,29 +1,56 @@
 // Action tools: rebuild the graph, the explicit 'retarget' group, and the explicit 'online' group
 // (the ONLY tools that ever touch the network).
 // Hot-reloadable (re-imported by catalog.mjs on change).
-import {readFileSync, writeFileSync, existsSync, readdirSync, statSync, realpathSync} from 'node:fs'
-import {join, dirname, isAbsolute} from 'node:path'
-import {prevGraphPathFor, diffGraphs, formatGraphDiff} from './graph-context.mjs'
+import {readFileSync, writeFileSync, existsSync, statSync, realpathSync} from 'node:fs'
+import {dirname, join, isAbsolute} from 'node:path'
+import {prevGraphPathFor, diffGraphs, formatGraphDiff, graphStaleness} from './graph-context.mjs'
 import {buildGraphForRepo} from '../build-graph.js'
-import {graphOutDirForRepo} from '../graph/layout.js'
+import {graphHomeDir, graphOutDirForModule, graphOutDirForRepo} from '../graph/layout.js'
+import {liveRepositoryRecords, registerRepository, repositoryRecord} from '../graph/repo-registry.js'
 import {refreshAdvisories, storeMeta, DEFAULT_STORE} from '../security/advisory-store.js'
 import {collectInstalled} from '../security/installed.js'
-import {createSyncPayload} from './sync-payload.mjs'
+import {createSyncPayload, createSyncPayloadV3, MAX_SYNC_BODY_BYTES} from './sync-payload.mjs'
+import {createEvidenceSnapshot} from './evidence-snapshot.mjs'
+import {writeCachedArchitectureContract} from '../analysis/architecture-contract.js'
+
+const MAX_SYNC_GRAPH_FILE_BYTES = 64 * 1024 * 1024
+
+function syncRepoLabel(repoRoot) {
+    const basename = String(repoRoot || '').replace(/[\\/]+$/, '').split(/[\\/]/).pop() || 'repo'
+    const safe = basename.normalize('NFKC').replace(/[^a-z0-9._-]+/gi, '-').replace(/^-+|-+$/g, '')
+    return (safe || 'repo').slice(0, 128)
+}
 
 export async function tRebuildGraph(g, args, ctx) {
     if (!ctx.repoRoot) return 'Rebuild needs the repo root (not provided to this server).'
     const mode = ['no-tests', 'tests-only', 'full'].includes(args.mode) ? args.mode : 'full'
+    const scope = String(args.scope || '').replace(/\\/g, '/').replace(/^\/+|\/+$/g, '')
+    if (scope) {
+        const scopedDir = graphOutDirForModule(ctx.repoRoot, scope)
+        const scoped = await buildGraphForRepo(ctx.repoRoot, {mode, scope, outDir: scopedDir})
+        if (!scoped || !scoped.ok) return `Scoped graph build failed: ${(scoped && scoped.error) || 'unknown error'}`
+        return [
+            `Built an isolated scoped graph for ${scope} (${mode}). ${scoped.log || ''}.`,
+            `The active full-repository graph was not replaced, so this operation cannot report a false full→scope structural delta.`,
+            `Scoped graph: ${join(scopedDir, 'graph.json')}`,
+        ].join('\n')
+    }
     // snapshot the outgoing state: bytes → graph.prev.json (for graph_diff later), struct → inline delta
     let prevBytes = null
     try { prevBytes = readFileSync(ctx.graphPath) } catch { /* first build — nothing to diff against */ }
-    const before = g?.nodes ? {nodes: g.nodes, links: g.links, edgeTypesV: g.edgeTypesV || 0} : null
-    const res = await buildGraphForRepo(ctx.repoRoot, {mode, scope: args.scope || ''})
+    const before = g?.nodes ? {
+        nodes: g.nodes, links: g.links,
+        edgeTypesV: g.edgeTypesV || 0,
+        barrelResolutionV: g.barrelResolutionV || 0,
+        extractorSchemaV: g.extractorSchemaV || 0,
+    } : null
+    const res = await buildGraphForRepo(ctx.repoRoot, {mode, scope: '', outDir: ctx.graphPath ? dirname(ctx.graphPath) : undefined})
     if (!res || !res.ok) return `Graph rebuild failed: ${(res && res.error) || 'unknown error'}`
     if (prevBytes) { try { writeFileSync(prevGraphPathFor(ctx.graphPath), prevBytes) } catch { /* snapshot is best-effort */ } }
     const fresh = ctx.reload() // refresh THIS server's in-memory graph so subsequent tool calls see the new graph
     const delta = before && fresh ? formatGraphDiff(diffGraphs(before, fresh)) : null
     return [
-        `Rebuilt the graph (${mode}${args.scope ? `, scope=${args.scope}` : ''}). ${res.log || ''}. In-memory graph reloaded — graph tools now reflect it.`,
+        `Rebuilt the graph (${mode}). ${res.log || ''}. In-memory graph reloaded — graph tools now reflect it.`,
         delta
     ].filter(Boolean).join('\n\n')
 }
@@ -71,31 +98,23 @@ export async function tOpenRepo(g, args, ctx) {
         ctx.reload()
         return `Failed to load ${graphPath} — still targeting the previous repo (${prev.repoRoot || 'none'}).`
     }
+    registerRepository({repoPath, graphDir: graphOutDirForRepo(repoPath), graphHome: graphHomeDir()})
     const buildNote = built ? (upgrade ? ' (graph upgraded to edge metadata v2)' : ' (graph built fresh)') : ''
     return `Opened ${repoPath}${buildNote}: ${loaded.nodes.length} nodes / ${loaded.links.length} edges. All tools now target this repo.`
 }
 
 // Sibling repos that already have a built graph in the central weavatrix-graphs folder — open_repo candidates.
 export function tListKnownRepos(g, args, ctx) {
-    if (!ctx.repoRoot) return 'No repo root — cannot locate the central graphs folder.'
-    const parent = dirname(ctx.repoRoot)
-    const root = join(parent, 'weavatrix-graphs')
+    const root = graphHomeDir()
     const norm = (p) => String(p).replace(/[\\/]+/g, '/').toLowerCase()
-    let entries = []
-    try { entries = readdirSync(root, {withFileTypes: true}) } catch { return `No central graphs folder at ${root}.` }
-    const rows = []
-    for (const entry of entries) {
-        if (!entry.isDirectory()) continue
-        const graphPath = join(root, entry.name, 'graph.json')
-        try {
-            const st = statSync(graphPath)
-            rows.push({name: entry.name, repoPath: join(parent, entry.name), builtAt: st.mtime.toISOString()})
-        } catch { /* no graph built for this entry */ }
-    }
-    if (!rows.length) return `No built graphs under ${root}.`
+    const rows = liveRepositoryRecords(root).map((record) => ({
+        ...record,
+        builtAt: statSync(join(record.graphDir, 'graph.json')).mtime.toISOString(),
+    }))
+    if (!rows.length) return `No registered graphs under ${root}. Build a repository once with open_repo or rebuild_graph.`
     return [
-        `Repos with built graphs under ${root} (switch with open_repo):`,
-        ...rows.map((r) => `  ${norm(r.repoPath) === norm(ctx.repoRoot) ? '»' : ' '} ${r.name} — graph built ${r.builtAt}  (${r.repoPath})`),
+        `Known repositories (${rows.length}) in ${root}:`,
+        ...rows.map((r) => `  ${norm(r.repoPath) === norm(ctx.repoRoot) ? '»' : ' '} ${r.label} [${r.repositoryId}] — graph built ${r.builtAt}  (${r.repoPath})`),
     ].join('\n')
 }
 
@@ -120,6 +139,32 @@ export async function tRefreshAdvisories(g, args, ctx) {
     ].filter(Boolean).join('\n')
 }
 
+export async function tPullArchitectureContract(g, args, ctx) {
+    if (!ctx.repoRoot || !ctx.graphPath) return 'No active repository graph — open_repo first.'
+    const syncUrl = process.env.WEAVATRIX_SYNC_URL
+    const token = process.env.WEAVATRIX_SYNC_TOKEN
+    if (!syncUrl || !token) return 'Hosted architecture pull is not configured. Use the hosted profile with WEAVATRIX_SYNC_URL and WEAVATRIX_SYNC_TOKEN, or keep .weavatrix/architecture.json locally.'
+    let url
+    try { url = process.env.WEAVATRIX_ARCHITECTURE_URL || new URL('/api/v1/architecture-contract', syncUrl).toString() }
+    catch { return 'WEAVATRIX_SYNC_URL is invalid.' }
+    const registry = repositoryRecord(ctx.repoRoot, graphHomeDir())
+        || registerRepository({repoPath: ctx.repoRoot, graphDir: graphOutDirForRepo(ctx.repoRoot), graphHome: graphHomeDir()})
+    const timeoutMs = Math.min(120000, Math.max(1000, Number(args.timeout_ms) || 30000))
+    try {
+        const res = await fetch(url, {
+            headers: {authorization: `Bearer ${token}`, 'x-weavatrix-repository-id': registry.repositoryId},
+            signal: AbortSignal.timeout(timeoutMs),
+        })
+        const body = await res.json().catch(() => null)
+        if (!res.ok) return `Hosted architecture endpoint answered HTTP ${res.status}; the local contract cache was not changed.`
+        if (body?.state === 'NOT_CONFIGURED' || !body?.contract) return 'Hosted target architecture is NOT_CONFIGURED. Define and save it in the Architecture editor first.'
+        const stored = writeCachedArchitectureContract(ctx.graphPath, body.contract)
+        return `Pulled target architecture ${stored.contract.name} (${stored.contract.style}, ${stored.contract.enforcement}) into the local graph cache. get_architecture_contract and verify_architecture now use it.`
+    } catch (error) {
+        return `Hosted architecture pull failed: ${error.message}; the previous local contract, if any, remains active.`
+    }
+}
+
 // Push the current graph.json to a user-configured endpoint. Off until WEAVATRIX_SYNC_URL is set.
 // The payload is graph metadata (paths, symbols/ranges, imports, edges, metrics), never file contents.
 export async function tSyncGraph(g, args, ctx) {
@@ -130,13 +175,38 @@ export async function tSyncGraph(g, args, ctx) {
     }
     if (!g) return 'No graph loaded — build one first (open_repo / rebuild_graph).'
     let raw
-    try { raw = JSON.parse(readFileSync(ctx.graphPath, 'utf8')) } catch (e) { return `Cannot read ${ctx.graphPath}: ${e.message}` }
+    try {
+        const size = statSync(ctx.graphPath).size
+        if (size > MAX_SYNC_GRAPH_FILE_BYTES) {
+            return `Cannot sync: graph.json is ${Math.ceil(size / 1024 / 1024)} MB; the local safety limit is ${MAX_SYNC_GRAPH_FILE_BYTES / 1024 / 1024} MB.`
+        }
+        raw = JSON.parse(readFileSync(ctx.graphPath, 'utf8'))
+    } catch (e) { return `Cannot read ${ctx.graphPath}: ${e.message}` }
+    const requestedVersion = Number(args.payload_version) === 2 ? 2 : 3
     let payload
-    try { payload = createSyncPayload(raw) } catch (e) {
+    try {
+        if (requestedVersion === 2) {
+            payload = createSyncPayload(raw)
+        } else {
+            if (!ctx.repoRoot) return 'Cannot build evidence: no repository root is active.'
+            if (graphStaleness(ctx).stale) {
+                return 'Cannot sync evidence from a stale graph. Run rebuild_graph, then call sync_graph again.'
+            }
+            const evidence = await createEvidenceSnapshot({repoRoot: ctx.repoRoot, graph: raw})
+            payload = createSyncPayloadV3(raw, evidence)
+        }
+    } catch (e) {
         return `Cannot sync: ${e.message}. Run rebuild_graph once before sync_graph.`
     }
     const body = JSON.stringify(payload)
-    const repoName = String(ctx.repoRoot || '').replace(/[\\/]+$/, '').split(/[\\/]/).pop() || 'repo'
+    const bodyBytes = Buffer.byteLength(body)
+    if (bodyBytes > MAX_SYNC_BODY_BYTES) {
+        return `Cannot sync: payload is ${Math.ceil(bodyBytes / 1024)} KB; the hosted safety limit is ${MAX_SYNC_BODY_BYTES / 1024} KB. Narrow the graph scope and rebuild before retrying.`
+    }
+    const repoName = syncRepoLabel(ctx.repoRoot)
+    const registry = repositoryRecord(ctx.repoRoot, graphHomeDir())
+        || registerRepository({repoPath: ctx.repoRoot, graphDir: graphOutDirForRepo(ctx.repoRoot), graphHome: graphHomeDir()})
+    const timeoutMs = Math.min(120000, Math.max(1000, Number(args.timeout_ms) || 30000))
     try {
         const res = await fetch(url, {
             method: 'POST',
@@ -144,12 +214,23 @@ export async function tSyncGraph(g, args, ctx) {
                 'content-type': 'application/json',
                 'x-weavatrix-payload-version': String(payload.syncPayloadV),
                 'x-weavatrix-repo': repoName,
+                'x-weavatrix-repository-id': registry.repositoryId,
                 ...(process.env.WEAVATRIX_SYNC_TOKEN ? {authorization: `Bearer ${process.env.WEAVATRIX_SYNC_TOKEN}`} : {}),
             },
             body,
+            signal: AbortSignal.timeout(timeoutMs),
         })
-        if (!res.ok) return `Sync endpoint answered HTTP ${res.status} — graph NOT accepted.`
-        return `Graph for ${repoName} (${payload.nodes.length} nodes / ${payload.links.length} edges, ${Math.round(Buffer.byteLength(body) / 1024)} KB) pushed to ${url}.`
+        if (!res.ok) {
+            const accepted = res.headers?.get?.('x-weavatrix-accept-payload-versions')
+            const compatibility = (res.status === 415 || res.status === 422) && accepted
+                ? ` Endpoint accepts payload version(s) ${accepted}; retry with payload_version:2 only if you intentionally want graph-only sync.`
+                : ''
+            return `Sync endpoint answered HTTP ${res.status} — graph NOT accepted.${compatibility}`
+        }
+        const evidenceNote = payload.syncPayloadV === 3
+            ? ` + evidence ${payload.evidence?.snapshotHash?.slice(0, 12) || 'unknown'}`
+            : ''
+        return `Graph for ${repoName} (${payload.nodes.length} nodes / ${payload.links.length} edges${evidenceNote}, ${Math.round(bodyBytes / 1024)} KB) pushed to ${url}.`
     } catch (e) {
         return `Sync failed: ${e.message} — the graph stays local.`
     }

package/src/mcp/tools-architecture.mjs

@@ -0,0 +1,200 @@
+// Executable target architecture for agents: read the active contract before a change, then run the
+// same deterministic verifier after it. No tool silently edits policy or accepts debt.
+import {contractForChange, loadArchitectureContract, normalizeArchitectureContract, verifyArchitecture} from '../analysis/architecture-contract.js'
+import {createPathClassifier, hasPathClass} from '../path-classification.js'
+import {detectRepoStack} from '../scan/discover.js'
+import {toolResult} from './tool-result.mjs'
+
+const PROVISIONAL_BUDGETS = Object.freeze({
+    runtimeCycles: 0,
+    maxFileLoc: 300,
+    maxFunctionLoc: 120,
+    maxCyclomatic: 15,
+    maxModuleFiles: 80,
+    minModuleCohesion: .5,
+    maxModuleBoundaryRatio: .65,
+})
+
+const remediation = () => ({
+    offlinePath: '.weavatrix/architecture.json',
+    hostedAction: 'Open Architecture -> choose intended style -> Save target & baseline',
+    nextTool: 'verify_architecture',
+})
+
+const stackIds = (repoRoot) => {
+    try {
+        const stack = detectRepoStack(repoRoot)
+        return ['languages', 'runtimes', 'tests', 'infra', 'deploy']
+            .flatMap((category) => (Array.isArray(stack?.[category]) ? stack[category] : []))
+            .map((item) => String(item?.id || '')).filter(Boolean)
+    } catch { return [] }
+}
+
+function activeContract(ctx) {
+    if (!ctx?.repoRoot) return {contract: null, source: null, error: 'no repository root is active'}
+    return loadArchitectureContract(ctx.repoRoot, ctx.graphPath)
+}
+
+function starterContract(g) {
+    const files = [...new Set((g?.nodes || [])
+        .filter((node) => !String(node.id).includes('#'))
+        .map((node) => String(node.source_file || node.id || '').replace(/\\/g, '/'))
+        .filter(Boolean))]
+    const groups = new Map()
+    for (const file of files) {
+        const parts = file.split('/').filter(Boolean)
+        const depth = ['src', 'app', 'lib', 'packages', 'services'].includes(parts[0]) ? 2 : 1
+        const path = parts.slice(0, Math.max(1, Math.min(depth, parts.length - 1))).join('/') || '(root)'
+        groups.set(path, (groups.get(path) || 0) + 1)
+    }
+    const components = [...groups].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).slice(0, 80)
+        .filter(([path]) => path !== '(root)')
+        .map(([path], index) => ({
+            id: path.toLowerCase().replace(/[^a-z0-9._:-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 100) || `component-${index + 1}`,
+            name: path,
+            paths: [path],
+        }))
+    return normalizeArchitectureContract({
+        name: 'Proposed no-regressions baseline', style: 'custom', enforcement: 'ratchet', components,
+        dependencyRules: [],
+        budgets: PROVISIONAL_BUDGETS,
+        technologies: {required: [], forbidden: []}, exceptions: [], ratchet: {baseline: {fingerprints: [], metrics: {}}},
+    })
+}
+
+function notConfiguredResult(g, action, {includeStarter = false} = {}) {
+    const starter = includeStarter ? starterContract(g) : null
+    const starterText = starter
+        ? ` A source-free starter with ${starter.components.length} path territories is available in JSON output from this lookup.`
+        : ''
+    return toolResult([
+        `Architecture ${action} is NOT_CONFIGURED — no target contract is active.${starterText}`,
+        'Next: save .weavatrix/architecture.json (offline) or approve a target in Hosted, then call verify_architecture.',
+    ].join('\n'), {
+        state: 'NOT_CONFIGURED',
+        remediation: remediation(),
+        ...(starter ? {
+            starterSummary: {components: starter.components.length, budgets: starter.budgets},
+            starterContract: starter,
+        } : {}),
+    })
+}
+
+function classifyChangeFiles(files, repoRoot) {
+    const classifier = createPathClassifier(repoRoot)
+    const normalized = [...new Set((Array.isArray(files) ? files : [])
+        .slice(0, 200)
+        .map((file) => String(file || '').replace(/\\/g, '/').replace(/^\.\//, ''))
+        .filter((file) => file && !file.startsWith('../') && !file.includes('/../')))]
+        .sort((a, b) => a.localeCompare(b))
+    const testOnlyFiles = normalized.filter((file) => hasPathClass(classifier.explain(file), 'test', 'e2e'))
+    const testOnly = new Set(testOnlyFiles)
+    return {files: normalized, productFiles: normalized.filter((file) => !testOnly.has(file)), testOnlyFiles}
+}
+
+function provisionalPreflight(g, args, ctx) {
+    const surfaces = classifyChangeFiles(args?.files, ctx?.repoRoot)
+    const intent = String(args?.intent || '').slice(0, 500)
+    const budgetText = [
+        `no new runtime cycles (baseline ${PROVISIONAL_BUDGETS.runtimeCycles})`,
+        `file <= ${PROVISIONAL_BUDGETS.maxFileLoc} LOC`,
+        `function <= ${PROVISIONAL_BUDGETS.maxFunctionLoc} LOC`,
+        `cyclomatic <= ${PROVISIONAL_BUDGETS.maxCyclomatic}`,
+    ].join('; ')
+    return toolResult([
+        `Architecture preflight is NOT_CONFIGURED for ${surfaces.files.length} file(s)${intent ? ` — ${intent}` : ''}.`,
+        `Provisional no-regression guidance (not enforced policy): ${budgetText}.`,
+        `${surfaces.productFiles.length} product file(s); ${surfaces.testOnlyFiles.length} test-only file(s). Save a target contract to make these budgets enforceable.`,
+    ].join('\n'), {
+        state: 'NOT_CONFIGURED',
+        guidance: 'PROVISIONAL_BUDGETS',
+        enforceable: false,
+        intent,
+        ...surfaces,
+        provisionalBudgets: PROVISIONAL_BUDGETS,
+        remediation: remediation(),
+    })
+}
+
+export function tGetArchitectureContract(g, args, ctx) {
+    const loaded = activeContract(ctx)
+    if (!loaded.contract) {
+        const text = loaded.error
+            ? `Architecture contract is invalid (${loaded.source || 'unknown'}): ${loaded.error}`
+            : 'No target architecture contract is active.'
+        if (!loaded.error) return notConfiguredResult(g, 'lookup', {includeStarter: true})
+        return toolResult(text, {state: 'ERROR', source: loaded.source, error: loaded.error})
+    }
+    const contract = loaded.contract
+    return toolResult([
+        `Target architecture: ${contract.name} (${contract.style}, ${contract.enforcement}).`,
+        `Contract ${contract.contractHash.slice(0, 12)} from ${loaded.source}; ${contract.components.length} components, ${contract.dependencyRules.length} dependency rules.`,
+        `Quality budgets: ${Object.entries(contract.budgets).map(([key, value]) => `${key}=${value}`).join(', ') || '(none)'}.`,
+    ].join('\n'), {state: 'ACTIVE', source: loaded.source, contract})
+}
+
+export function tPrepareChange(g, args = {}, ctx) {
+    const loaded = activeContract(ctx)
+    if (!loaded.contract) return provisionalPreflight(g, args, ctx)
+    const prepared = contractForChange(loaded.contract, args.files)
+    const surfaces = classifyChangeFiles(prepared.files, ctx?.repoRoot)
+    const intent = String(args.intent || '').slice(0, 500)
+    return toolResult([
+        `Architecture preflight for ${prepared.files.length} file(s)${intent ? ` — ${intent}` : ''}.`,
+        `Affected target components: ${prepared.components.join(', ') || '(unmapped)'}.`,
+        ...(surfaces.testOnlyFiles.length ? [`Test-only surface: ${surfaces.testOnlyFiles.join(', ')}.`] : []),
+        `Applicable rules: ${prepared.rules.map((rule) => rule.id).join(', ') || '(none)'}.`,
+        'Run verify_architecture after the edit; do not silently add an exception or rewrite the target contract.',
+    ].join('\n'), {state: 'READY', intent, contractHash: loaded.contract.contractHash, ...prepared, productFiles: surfaces.productFiles, testOnlyFiles: surfaces.testOnlyFiles})
+}
+
+export function tVerifyArchitecture(g, args, ctx) {
+    const loaded = activeContract(ctx)
+    if (!loaded.contract) return notConfiguredResult(g, 'verification')
+    const verification = verifyArchitecture({graph: g, contract: loaded.contract, technologies: stackIds(ctx.repoRoot)})
+    const groups = [['new', verification.new], ['existing', verification.existing], ['fixed', verification.fixed], ['excepted', verification.excepted]]
+    const lines = [
+        `Architecture verify: ${verification.status} (${verification.enforcement}; contract ${verification.contractHash.slice(0, 12)}).`,
+        `New ${verification.new.length} · existing debt ${verification.existing.length} · fixed ${verification.fixed.length} · excepted ${verification.excepted.length}.`,
+        ...groups.filter(([, values]) => values.length).flatMap(([label, values]) => [
+            `${label}:`,
+            ...values.slice(0, 20).map((item) => typeof item === 'string' ? `  ${item}` : `  ${item.ruleId}: ${item.evidence}${item.current != null ? ` (${item.current} > ${item.target})` : ''}`),
+        ]),
+    ]
+    return toolResult(lines.join('\n'), {state: verification.status, source: loaded.source, verification}, {
+        completeness: {violationsReturned: Math.min(20, verification.new.length + verification.existing.length), violationsTotal: verification.new.length + verification.existing.length},
+    })
+}
+
+export function tExplainArchitectureViolation(g, args, ctx) {
+    const loaded = activeContract(ctx)
+    if (!loaded.contract) return toolResult('No active architecture contract.', {state: 'NOT_CONFIGURED'})
+    const verification = verifyArchitecture({graph: g, contract: loaded.contract, technologies: stackIds(ctx.repoRoot)})
+    const fingerprint = String(args.fingerprint || '')
+    const item = [...verification.new, ...verification.existing, ...verification.excepted]
+        .find((entry) => entry.fingerprint === fingerprint)
+    if (!item) return toolResult(`Violation ${fingerprint || '(missing)'} is not active in the current verification.`, {state: 'NOT_FOUND', fingerprint})
+    const rule = loaded.contract.dependencyRules.find((candidate) => candidate.id === item.ruleId)
+    return toolResult([
+        `${item.ruleId}: ${item.evidence}.`,
+        rule?.reason ? `Reason: ${rule.reason}` : 'The finding violates an explicit dependency or quality rule in the active target contract.',
+        'Preferred action: change the dependency/metric. If that is intentionally impossible, propose a time-bounded exception for human review.',
+    ].join('\n'), {state: 'ACTIVE', violation: item, rule: rule || null})
+}
+
+export function tProposeArchitectureException(g, args, ctx) {
+    const loaded = activeContract(ctx)
+    if (!loaded.contract) return toolResult('No active architecture contract.', {state: 'NOT_CONFIGURED'})
+    const verification = verifyArchitecture({graph: g, contract: loaded.contract, technologies: stackIds(ctx.repoRoot)})
+    const item = [...verification.new, ...verification.existing].find((entry) => entry.fingerprint === String(args.fingerprint || ''))
+    if (!item) return toolResult('Only an active violation can be proposed as an exception.', {state: 'NOT_FOUND'})
+    const proposal = {
+        fingerprint: item.fingerprint,
+        reason: String(args.reason || '').trim().slice(0, 300),
+        ...(args.expires ? {expires: String(args.expires)} : {}),
+    }
+    const checked = normalizeArchitectureContract({...loaded.contract, exceptions: [...loaded.contract.exceptions, proposal]})
+    const normalized = checked.exceptions.find((entry) => entry.fingerprint === item.fingerprint)
+    if (!normalized || !normalized.reason) return toolResult('A non-empty reason and optional YYYY-MM-DD expiry are required.', {state: 'INVALID'})
+    return toolResult('Exception proposal prepared for human review; the contract was not changed.', {state: 'PROPOSED', proposal: normalized, contractHash: loaded.contract.contractHash})
+}