@davesheffer/hunch 1.20.0-rc.2 → 1.20.0-rc.4

package/README.md

@@ -58,11 +58,13 @@ existing configuration.
   passes, needs attention, or should be blocked.
 - **Past bugs stay useful** — see which old incident a piece of code fixed before accidentally
   undoing it.
-- **Understands how code connects** — for TypeScript, JavaScript, Python, Go, YAML, and Helm, Hunch
+- **Understands how code connects** — for TypeScript, JavaScript, Python, Go, PHP, YAML, and Helm, Hunch
   can see what calls or depends on the code you are about to change. Its memory works with any
   language.
 - **Works with existing decision documents** — import your architecture decision records into
-  Hunch, or export Hunch decisions back to a standard format other tools can read.
+  Hunch, or export Hunch decisions back to a standard format other tools can read. Imported ADRs
+  start as useful advisory memory; during normal work your assistant asks you to approve or decline
+  one exact ADR at a time. Silence never grants authority, and changed ADR text is asked again.
 
 The source of truth is readable JSON in `.hunch/`. A local SQLite index makes retrieval fast but
 is always rebuildable.
@@ -98,6 +100,7 @@ Most memory work happens automatically after commits. These commands cover the c
 | `hunch check --working` | Check current changes against the decisions and rules your team trusts |
 | `hunch log` | See what Hunch remembered and undo a memory change if needed |
 | `hunch escalations` | See the rare questions that need a human answer |
+| `hunch review` | Answer the current imported-ADR approve/decline question from the terminal |
 | `hunch doctor` | Diagnose setup problems |
 
 <details>

package/dist/cli/index.js

@@ -31,7 +31,7 @@ import { assertCompleteRepoScan, indexRepo, scanRepo } from "../extractors/index
 import { syncCommit, recordFailure, captureTestRun } from "../synthesis/synthesize.js";
 import { parseTestReport } from "../extractors/testreport.js";
 import { readSynthesisPreference, resolveSynthesisProvider, selectProvider, SYNTH_PREFERENCES, writeSynthesisPreference, normalizeProviderName, } from "../synthesis/provider.js";
-import { isGitRepo, isGitRepoRoot, sameGitPublication, sameRemoteUrl, canonicalRemoteUrl, repositoryUsesRemote, headSha, isolatedHeadSha, logSince, lastChangeDate, stagedFiles, workingFiles, commitFiles, asOfDate, stagedDiff, workingDiff, commitDiff, rangeFiles, rangeDiff, rangeSubjects, revExists, revParse, commitAndPushHunch, pullHunchStatus, syncExistingHunch, gitUntrackCached, gitCommonDir, hooksDir, isLinkedWorktree, mainWorktreeRoot, gitMemoryLog, memoryMoveDiff, revertMemoryMove, pushCurrentBranch, commitChanges } from "../extractors/git.js";
+import { isGitRepo, isGitRepoRoot, sameGitPublication, sameRemoteUrl, canonicalRemoteUrl, repositoryUsesRemote, headSha, isolatedHeadSha, logSince, lastChangeDate, firstCommitForFile, stagedFiles, workingFiles, commitFiles, asOfDate, stagedDiff, workingDiff, commitDiff, rangeFiles, rangeDiff, rangeSubjects, revExists, revParse, commitAndPushHunch, pullHunchStatus, syncExistingHunch, gitUntrackCached, gitCommonDir, hooksDir, isLinkedWorktree, mainWorktreeRoot, gitMemoryLog, memoryMoveDiff, revertMemoryMove, pushCurrentBranch, commitChanges } from "../extractors/git.js";
 import { parseMemoryLog } from "../core/memorylog.js";
 import { renamesOf, planRepair, repairDecision, repairConstraint } from "../core/repair.js";
 import { planPolicyRepair, repairPolicySpec } from "../constitution/repairPolicies.js";
@@ -75,6 +75,7 @@ import { generateWiki, wikiStatus, wikiPrompt, publicHome, privateHome, readWiki
 import { adoptProsePrompt } from "../wiki/adopt.js";
 import { topicCollisions, isInForce, liveForTopic } from "../core/topics.js";
 import { ADR_DIR_CANDIDATES, ADR_FILE_RE, mapAdrCorpus } from "../extractors/adrImport.js";
+import { applyImportedAdrReview, carryImportedAdrReview, importedAdrReviewHash, importedAdrSourceHash, isImportedAdrDecision, pendingImportedAdrReviews } from "../core/importReview.js";
 import { exportMadrCorpus, isRegenerableMadr } from "../integrations/madrExport.js";
 import { buildMadrManifest, writeMadrManifest, refreshMadrCorpus } from "../integrations/madrManifest.js";
 import { pendingEscalations, policyEscalations } from "../core/escalations.js";
@@ -217,6 +218,10 @@ program
             const res = indexRepo(store, root, { source: { kind: "commit", ref: "HEAD" } });
             store.reindex();
             console.log(`  ✓ indexed committed HEAD (${res.files} files) → ${res.symbols} symbols, ${res.edges} edges, ${res.components} components`);
+            for (const item of res.coverage) {
+                const reasons = Object.entries(item.reasons).map(([reason, count]) => `${reason}:${count}`).join(", ");
+                console.log(`    coverage ${item.language}: ${item.eligible} eligible · ${item.parsed} parsed · ${item.skipped} skipped${reasons ? ` (${reasons})` : ""}`);
+            }
             if (res.skipped)
                 console.log(`  ⚠ ${res.skipped} file(s) could not be parsed (skipped)`);
         }
@@ -351,6 +356,10 @@ program
     const healed = shouldAutoCommit ? [] : refreshExistingGrounding(root, store);
     console.log(`Indexed ${res.files} files:`);
     console.log(`  ${counts.symbols} symbols, ${counts.edges} edges, ${counts.components} components`);
+    for (const item of res.coverage) {
+        const reasons = Object.entries(item.reasons).map(([reason, count]) => `${reason}:${count}`).join(", ");
+        console.log(`  coverage ${item.language}: ${item.eligible} eligible · ${item.parsed} parsed · ${item.skipped} skipped${reasons ? ` (${reasons})` : ""}`);
+    }
     if (correctionSweep.scanned) {
         console.log(`  correction reviews: ${correctionSweep.proved} proved · ${correctionSweep.already_proved} current · ${correctionSweep.pending} pending · ${correctionSweep.legacy_only} legacy-only · ${correctionSweep.conflicted} conflicted · ${correctionSweep.failed.length} failed; authority none`);
     }
@@ -3110,7 +3119,16 @@ program
         const files = readdirSync(join(root, dir)).filter((f) => ADR_FILE_RE.test(f)).sort();
         if (!files.length)
             return fail(`no NNNN-slug.md ADR files in ${dir}`);
-        const sources = files.map((f) => ({ relPath: `${dir}/${f}`, text: readFileSync(join(root, dir, f), "utf8") }));
+        const sources = files.map((f) => {
+            const relPath = `${dir}/${f}`;
+            const sourceRevision = firstCommitForFile(relPath, root) || null;
+            return {
+                relPath,
+                text: readFileSync(join(root, dir, f), "utf8"),
+                sourceDate: sourceRevision ? (asOfDate(sourceRevision, root) ?? null) : null,
+                sourceRevision,
+            };
+        });
         const { decisions, warnings } = mapAdrCorpus(sources);
         for (const w of warnings)
             console.log(`  ⚠ ${w}`);
@@ -3136,8 +3154,12 @@ program
         }
         store.json.ensureDirs();
         let created = 0, updated = 0;
-        for (const d of decisions) {
-            if (store.getRec("decisions", d.id))
+        for (let index = 0; index < decisions.length; index++) {
+            const candidate = decisions[index];
+            const previous = opts.private ? store.getRec("decisions", candidate.id) : store.json.get("decisions", candidate.id);
+            const d = carryImportedAdrReview(previous, candidate);
+            decisions[index] = d;
+            if (previous)
                 updated++;
             else
                 created++;
@@ -3150,6 +3172,18 @@ program
         const flush = flushCapture(store, hunchPaths(root).hunch, !!opts.private, `hunch: import ${decisions.length} ADR(s) from ${dir}`);
         const live = decisions.filter((d) => d.status === "accepted").length;
         console.log(`✓ imported ${decisions.length} ADR(s) from ${dir} (${created} new, ${updated} updated; ${live} live, ${decisions.length - live} historical)${opts.private ? " [private overlay]" : ""}`);
+        const pending = pendingImportedAdrReviews(decisions);
+        if (pending.length) {
+            const first = pending[0];
+            const sourceHash = importedAdrSourceHash(first);
+            const reviewHash = importedAdrReviewHash(first);
+            console.log(`\n⚖ HUMAN REVIEW  ${pending.length} imported live ADR(s) are advisory until you answer.`);
+            console.log(`  “${first.title}” (${first.id})`);
+            console.log("  Approve it as human-confirmed project authority, or decline and keep it advisory?");
+            console.log(`  Approve: hunch review --approve-import ${first.id} --expected-source-hash ${sourceHash} --expected-review-hash ${reviewHash} --reviewed-by <you>`);
+            console.log(`  Decline: hunch review --decline-import ${first.id} --expected-source-hash ${sourceHash} --expected-review-hash ${reviewHash} --reviewed-by <you>`);
+            console.log("  Your coding assistant will also ask this inline in the next Hunch session; silence never approves it.");
+        }
         if (flush === "pushed")
             console.log("  ↳ private memory committed + pushed");
     }
@@ -3952,6 +3986,7 @@ program
     const precise = blocking.filter((c) => !!effectiveForbids(c));
     const scopeOnly = blocking.filter((c) => !effectiveForbids(c));
     const drafts = store.json.loadAll("decisions").filter(isReviewDraft);
+    const importedReviews = pendingImportedAdrReviews(store.json.loadAll("decisions"));
     const { ready, scrutiny } = partitionReview(drafts, READY_MIN_GROUNDED);
     const stale = store.staleness((f) => lastChangeDate(f, root)).filter((s) => s.kind === "constraint");
     const fnote = {
@@ -3970,6 +4005,9 @@ program
     if (ready.length || scrutiny.length) {
         console.log(`\n  ⏳ TO CONFIRM   ${ready.length} ready · ${scrutiny.length} need scrutiny   → hunch review${ready.length ? " --accept-verified" : ""}`);
     }
+    if (importedReviews.length) {
+        console.log(`\n  ⚖ ADR REVIEW   ${importedReviews.length} imported live ADR(s) need an approve/decline answer   → hunch review`);
+    }
     if (stale.length) {
         console.log(`\n  ♻ STALE        ${stale.length} rule(s) whose guarded code moved since last verified   → re-confirm to keep the teeth`);
     }
@@ -4573,9 +4611,14 @@ program
 });
 program
     .command("review")
-    .description("Triage drafts: segmented list, accept/reject one, or batch-accept Critic-verified drafts.")
+    .description("Answer hash-bound imported-ADR questions, or triage deliberate proposed drafts.")
     .option("--accept <id>", "promote a decision to accepted/human-confirmed (confirms its tripwires)")
     .option("--reject <id>", "reject a draft decision with a durable lifecycle tombstone")
+    .option("--approve-import <id>", "approve one exact imported ADR as human-confirmed authority")
+    .option("--decline-import <id>", "record that one exact imported ADR was reviewed and must stay advisory")
+    .option("--expected-source-hash <hash>", "exact sha256 source hash printed with the imported-ADR question")
+    .option("--expected-review-hash <hash>", "exact sha256 mapped-meaning hash printed with the imported-ADR question")
+    .option("--reviewed-by <label>", "credential-free human reviewer label for an imported-ADR answer")
     .option("--accept-verified", "batch-accept every Critic-verified, well-grounded draft (>= --min-grounded)")
     .option("--reject-duplicates", "batch-reject drafts that near-duplicate an accepted record (deterministic term+file similarity — hygiene, not judgment)")
     .option("--min-grounded <n>", "grounded-ness threshold for the ready group / --accept-verified", String(READY_MIN_GROUNDED))
@@ -4587,15 +4630,60 @@ program
         store.close();
         return fail("--private needs HUNCH_PRIVATE_DIR set to a private store");
     }
+    const actionCount = [opts.accept, opts.reject, opts.approveImport, opts.declineImport, opts.acceptVerified, opts.rejectDuplicates].filter(Boolean).length;
+    if (actionCount > 1) {
+        store.close();
+        return fail("choose exactly one review action at a time");
+    }
     const decisions = () => opts.private ? store.recs("decisions") : store.json.loadAll("decisions");
     let publicGroundingChanged = false;
     const touchedHomes = new Set();
-    if (opts.accept) {
+    if (opts.approveImport || opts.declineImport) {
+        const id = opts.approveImport ?? opts.declineImport;
+        if (!opts.expectedSourceHash || !opts.expectedReviewHash || !opts.reviewedBy) {
+            store.close();
+            return fail("an imported-ADR answer requires --expected-source-hash <hash>, --expected-review-hash <hash>, and --reviewed-by <label>");
+        }
+        const d = opts.private ? store.getRec("decisions", id) : store.json.get("decisions", id);
+        if (!d) {
+            store.close();
+            return fail(`decision ${id} not found`);
+        }
+        try {
+            const reviewed = applyImportedAdrReview(d, {
+                disposition: opts.approveImport ? "approve" : "decline",
+                expectedSourceHash: opts.expectedSourceHash,
+                expectedReviewHash: opts.expectedReviewHash,
+                reviewer: opts.reviewedBy,
+            });
+            const home = opts.private ? decisionMemoryHome(store, id) : "public";
+            putDecisionInHome(store, reviewed, home);
+            touchedHomes.add(home);
+            store.reindex();
+            if (home === "public") {
+                publicGroundingChanged = true;
+                if (!store.autoCommit)
+                    refreshExistingGrounding(root, store);
+            }
+            console.log(opts.approveImport
+                ? `✓ approved ${id} for exact source ${opts.expectedSourceHash} (now human-confirmed authority)`
+                : `✓ declined authority for ${id} at exact source ${opts.expectedSourceHash} (reviewed; remains advisory)`);
+        }
+        catch (error) {
+            store.close();
+            return fail(error instanceof Error ? error.message : String(error));
+        }
+    }
+    else if (opts.accept) {
         const d = opts.private ? store.getRec("decisions", opts.accept) : store.json.get("decisions", opts.accept);
         if (!d) {
             store.close();
             return fail(`decision ${opts.accept} not found`);
         }
+        if (isImportedAdrDecision(d)) {
+            store.close();
+            return fail(`imported ADR ${d.id} requires the hash-bound --approve-import flow shown by hunch review`);
+        }
         const { source, armed, home } = acceptDecision(store, d, opts.private ? decisionMemoryHome(store, d.id) : "public");
         touchedHomes.add(home);
         store.reindex();
@@ -4668,12 +4756,26 @@ program
         }
     }
     else {
-        const drafts = decisions().filter(isReviewDraft);
+        const allDecisions = decisions();
+        const imported = pendingImportedAdrReviews(allDecisions);
+        const drafts = allDecisions.filter(isReviewDraft);
         const { ready, scrutiny } = partitionReview(drafts, minGrounded);
-        if (!ready.length && !scrutiny.length) {
+        if (!ready.length && !scrutiny.length && !imported.length) {
             console.log("✓ No drafts awaiting review — captured memory auto-trusts (advisory) the moment it lands.");
         }
         else {
+            if (imported.length) {
+                const d = imported[0];
+                const sourceHash = importedAdrSourceHash(d);
+                const reviewHash = importedAdrReviewHash(d);
+                console.log(`⚖ ${imported.length} imported live ADR(s) need a human answer (one at a time):\n`);
+                console.log(`  ${d.id}  ${d.title}`);
+                console.log(`      ${d.related_files[0] ?? "source unknown"}  source ${sourceHash}  review ${reviewHash}`);
+                console.log(`      ${d.decision.slice(0, 180)}`);
+                console.log("\n  Approve as human-confirmed authority, or decline and keep advisory?");
+                console.log(`  Approve: hunch review --approve-import ${d.id} --expected-source-hash ${sourceHash} --expected-review-hash ${reviewHash} --reviewed-by <you>`);
+                console.log(`  Decline: hunch review --decline-import ${d.id} --expected-source-hash ${sourceHash} --expected-review-hash ${reviewHash} --reviewed-by <you>\n`);
+            }
             if (ready.length) {
                 console.log(`✓ ${ready.length} ready to confirm — Critic-verified, grounded ≥ ${minGrounded} (best first):\n`);
                 for (const it of ready)
@@ -4905,7 +5007,7 @@ program
 // ---- escalations (the inline "ask the human" surface) ---------------------
 program
     .command("escalations")
-    .description("The decisions a human must make NOW — surfaced to be asked INLINE (in the prompt), never a background queue. Captured memory auto-trusts on landing; this lists only what the graph genuinely can't resolve itself: topic conflicts, Constitution candidates awaiting review, and proposed policies whose activation is a human call. Normally empty. Exits non-zero when any are open, so an assistant/CI knows to raise them.")
+    .description("The decisions a human must make NOW — surfaced to be asked INLINE, never inferred: one exact imported ADR at a time, topic conflicts, stale premises, and Constitution activation calls. Normally empty. Exits non-zero when any are open.")
     .option("--json", "emit the escalation entries as JSON (the VS Code panel's data source)")
     .action(async (opts) => {
     const { store, root } = storeFor();

package/dist/constitution/delta.js

@@ -4,7 +4,7 @@ import { commitChanges, fileAtRef, firstParent, revParse } from "../extractors/g
 import { attributeCalls, parseSource } from "../extractors/parse.js";
 import { canonicalHash } from "./canonical.js";
 import { StructuralDeltaSchema, } from "./schema.js";
-const CODE_EXT = /\.(ts|tsx|mts|cts|js|jsx|mjs|cjs)$/;
+const CODE_EXT = /\.(ts|tsx|mts|cts|js|jsx|mjs|cjs|php)$/;
 const SKIP_SEGMENTS = new Set(["node_modules", ".git", ".hunch", "dist", "build", "coverage", ".next", "out", "vendor"]);
 const MAX_CODE_FILES = 64;
 const MAX_SOURCE_BYTES = 8 * 1024 * 1024;

package/dist/constitution/schema.js

@@ -14,7 +14,7 @@ export const DataClassSchema = z.enum(["public", "private", "secret"]);
 export const StructuralSymbolRefSchema = z.object({
     file: z.string().min(1),
     name: z.string().min(1),
-    kind: z.enum(["function", "method", "class", "interface", "type", "variable", "file"]),
+    kind: z.enum(["function", "method", "class", "interface", "trait", "enum", "type", "variable", "file"]),
 });
 export const StructuralCallRefSchema = z.object({
     file: z.string().min(1),

package/dist/core/correctionStage.js

@@ -1,4 +1,5 @@
 import { createHash } from "node:crypto";
+import { compareCodeUnits } from "./canonicalOrder.js";
 import { rankIssueImplementationOwners, } from "./pipeline.js";
 import { compileVerifiedEvidenceMap, } from "./evidenceMap.js";
 import { buildFileFirstDeclarationClusters, buildProgressiveDeclarationPlan, } from "./declarationClusters.js";
@@ -109,8 +110,10 @@ function terms(value) {
  * but runtime declarations win ties in the selected layer. */
 function runtimeDeclarationOwners(sources) {
     const owners = new Set();
-    const declaration = /^(?:export\s+)?(?:default\s+)?(?:declare\s+)?(?:async\s+)?(?:function|class|enum|const|let|var)\s+([$A-Za-z_][$\w]*)/gm;
     for (const source of sources) {
+        const declaration = source.path.endsWith(".php")
+            ? /^(?:(?:#\[[^\r\n]*\])\r?\n)*(?:(?:abstract|final|readonly)\s+)*(?:class|interface|trait|enum|function)\s+&?\s*([A-Za-z_][A-Za-z0-9_]*)/gm
+            : /^(?:export\s+)?(?:default\s+)?(?:declare\s+)?(?:async\s+)?(?:function|class|enum|const|let|var)\s+([$A-Za-z_][$\w]*)/gm;
         for (const match of source.content.matchAll(declaration)) {
             owners.add(`${source.path}::${match[1]}`);
         }
@@ -149,7 +152,7 @@ export function rankIssueCorrectionStageCandidates(issueValue, sources) {
         || Number(a.type_scaffolding) - Number(b.type_scaffolding)
         || b.symbol_overlap - a.symbol_overlap
         || b.lexical_score - a.lexical_score
-        || a.owner.localeCompare(b.owner));
+        || compareCodeUnits(a.owner, b.owner));
     // Overloads and repeated declarations can produce the same owner more than
     // once. A shortlist must spend each slot on a distinct correction candidate.
     const seen = new Set();
@@ -264,7 +267,7 @@ export function selectGuardedExecutionBridge(baselineOwnersValue, rankedOwnersVa
                 : [];
         }).sort((left, right) => right.execution_ratio - left.execution_ratio
             || left.static_rank - right.static_rank
-            || left.owner.localeCompare(right.owner))[0];
+            || compareCodeUnits(left.owner, right.owner))[0];
         if (direct)
             return [direct];
         const maxRatio = evidence.reduce((best, entry) => Math.max(best, entry.ratio), 0);
@@ -283,7 +286,7 @@ export function selectGuardedExecutionBridge(baselineOwnersValue, rankedOwnersVa
         - Number(left.strategy === "direct-high-contrast-execution")
         || right.execution_ratio - left.execution_ratio
         || left.static_rank - right.static_rank
-        || left.owner.localeCompare(right.owner));
+        || compareCodeUnits(left.owner, right.owner));
     return choices[0] ?? null;
 }
 export function reserveExecutionGuidedFileOwner(baselineOwnersValue, rankedOwnersValue, evidenceMap, requestedLimit = CORRECTION_STAGE_CANDIDATE_LIMIT) {
@@ -352,7 +355,7 @@ export function rankIssueAdaptiveCorrectionCandidates(issueValue, sources) {
         || b.path_overlap - a.path_overlap
         || b.symbol_overlap - a.symbol_overlap
         || Number(b.runtime_declaration) - Number(a.runtime_declaration)
-        || a.owner.localeCompare(b.owner));
+        || compareCodeUnits(a.owner, b.owner));
     const deeper = ranked.filter((candidate) => !candidate.invoked_entrance
         && (candidate.path_overlap > 0 || candidate.symbol_overlap > 0));
     return deeper.length ? ranked.filter((candidate) => !candidate.invoked_entrance) : ranked;

package/dist/core/escalations.js

@@ -1,4 +1,5 @@
 import { topicCollisions } from "./topics.js";
+import { importedAdrReviewHash, importedAdrSourceHash, pendingImportedAdrReviews } from "./importReview.js";
 /** The decisions a human must make NOW, to be asked INLINE. Empty in a healthy graph. */
 export function pendingEscalations(decisions) {
     const out = [];
@@ -12,6 +13,26 @@ export function pendingEscalations(decisions) {
             resolution: `supersede the others: re-record the chosen one with supersedes:<other-id>, or split the topic.`,
         });
     }
+    // Imported ADRs are immediately useful as advisory memory, but reading a file
+    // cannot mint human authority. Ask about exactly one at a time in ordinary
+    // session orientation; once answered, the next one naturally surfaces.
+    const imported = pendingImportedAdrReviews(decisions);
+    const next = imported[0];
+    if (next) {
+        const sourceHash = importedAdrSourceHash(next);
+        const reviewHash = importedAdrReviewHash(next);
+        const sourcePath = next.related_files[0] ?? "its ADR source";
+        const remaining = imported.length - 1;
+        const clip = (value, max) => value.length > max ? value.slice(0, max - 1).trimEnd() + "…" : value;
+        out.push({
+            kind: "imported-adr-review",
+            topic: next.topic ?? next.id,
+            decisionIds: [next.id],
+            question: `I imported ADR “${clip(next.title, 90)}” (${next.id}) as advisory memory. Approve it as human-confirmed project authority, or decline and keep it advisory?`,
+            detail: `${sourcePath} · source ${sourceHash} · review ${reviewHash} · ${clip(next.decision, 180)}${remaining ? ` · ${remaining} more imported ADR(s) will follow one at a time` : ""}`,
+            resolution: `after the human answers, call hunch_review_imported_adr with decision_id=${next.id}, expected_source_hash=${sourceHash}, expected_review_hash=${reviewHash}, and disposition=approve|decline; CLI: hunch review --approve-import|--decline-import ${next.id} --expected-source-hash ${sourceHash} --expected-review-hash ${reviewHash} --reviewed-by <you>`,
+        });
+    }
     return out;
 }
 /** The Constitution's genuine human moments (§59.5.3), framed as inline questions:

package/dist/core/importReview.js

@@ -0,0 +1,192 @@
+/**
+ * Hash-bound human review for live ADRs imported from MADR/Nygard documents.
+ *
+ * Import gives Hunch useful advisory memory immediately, but importing a file is
+ * not a human countersign. This module owns the narrow trust-elevation boundary:
+ * an explicit approve/decline answer applies only to the exact source bytes the
+ * person saw. Re-importing unchanged bytes preserves the answer; changed bytes
+ * discard it and become reviewable again.
+ */
+import { createHash } from "node:crypto";
+import { isCredentialFreeText } from "./types.js";
+const SOURCE_HASH = /^sha256:[a-f0-9]{64}$/;
+const REVIEW_RECEIPT = /^adr-review:(approved|declined):(sha256:[a-f0-9]{64})$/;
+const REVIEW_HASH_PREFIX = "adr-review-candidate:";
+const REVIEWER_PREFIX = "adr-reviewer:";
+const REVIEWED_AT_PREFIX = "adr-reviewed-at:";
+function sourceTokens(source) {
+    return source.split("+").filter(Boolean);
+}
+function withoutHumanConfirmation(source) {
+    return sourceTokens(source).filter((token) => token !== "human_confirmed").join("+");
+}
+function withHumanConfirmation(source) {
+    const tokens = sourceTokens(source);
+    if (!tokens.includes("human_confirmed"))
+        tokens.push("human_confirmed");
+    return tokens.join("+");
+}
+export function isImportedAdrDecision(decision) {
+    return sourceTokens(decision.provenance.source).includes("imported:madr");
+}
+export function importedAdrSourceHash(decision) {
+    return decision.provenance.evidence.find((item) => SOURCE_HASH.test(item)) ?? null;
+}
+/** Hash the complete mapped meaning, not just the ADR source bytes. This prevents
+ * a later importer/parser change from carrying old authority onto new semantics
+ * even when the Markdown file itself did not change. */
+export function importedAdrReviewHash(decision) {
+    const evidence = decision.provenance.evidence.filter((item) => !REVIEW_RECEIPT.test(item)
+        && !item.startsWith(REVIEW_HASH_PREFIX)
+        && !item.startsWith(REVIEWER_PREFIX)
+        && !item.startsWith(REVIEWED_AT_PREFIX));
+    const canonical = {
+        id: decision.id,
+        title: decision.title,
+        topic: decision.topic,
+        status: decision.status,
+        context: decision.context,
+        decision: decision.decision,
+        consequences: decision.consequences,
+        alternatives_rejected: decision.alternatives_rejected,
+        rejected_tripwires: decision.rejected_tripwires,
+        related_components: decision.related_components,
+        related_files: decision.related_files,
+        supersedes: decision.supersedes,
+        superseded_by: decision.superseded_by,
+        caused_by_bug: decision.caused_by_bug,
+        commit: decision.commit,
+        valid_from: decision.valid_from ?? null,
+        valid_to: decision.valid_to,
+        retired: decision.retired,
+        date: decision.date,
+        import_evidence: evidence,
+    };
+    return `sha256:${createHash("sha256").update(JSON.stringify(canonical)).digest("hex")}`;
+}
+function currentReviewReceipt(decision) {
+    const sourceHash = importedAdrSourceHash(decision);
+    if (!sourceHash)
+        return null;
+    const reviewHash = importedAdrReviewHash(decision);
+    const recordedReviewHash = decision.provenance.evidence.find((value) => value.startsWith(REVIEW_HASH_PREFIX))?.slice(REVIEW_HASH_PREFIX.length);
+    if (recordedReviewHash !== reviewHash)
+        return null;
+    for (const item of decision.provenance.evidence) {
+        const match = REVIEW_RECEIPT.exec(item);
+        if (!match || match[2] !== sourceHash)
+            continue;
+        return {
+            disposition: match[1] === "approved" ? "approve" : "decline",
+            sourceHash,
+            reviewHash,
+            reviewer: decision.provenance.evidence.find((value) => value.startsWith(REVIEWER_PREFIX))?.slice(REVIEWER_PREFIX.length) ?? null,
+            reviewedAt: decision.provenance.evidence.find((value) => value.startsWith(REVIEWED_AT_PREFIX))?.slice(REVIEWED_AT_PREFIX.length) ?? null,
+        };
+    }
+    return null;
+}
+export function importedAdrReview(decision) {
+    const receipt = currentReviewReceipt(decision);
+    if (receipt)
+        return receipt;
+    const sourceHash = importedAdrSourceHash(decision);
+    if (sourceHash && sourceTokens(decision.provenance.source).includes("human_confirmed")) {
+        // Backward-compatible with an imported record countersigned before receipts
+        // existed. Its exact source hash still prevents carrying it onto changed bytes.
+        return {
+            disposition: "approve",
+            sourceHash,
+            reviewHash: importedAdrReviewHash(decision),
+            reviewer: null,
+            reviewedAt: decision.provenance.last_verified ?? null,
+        };
+    }
+    return null;
+}
+export function isPendingImportedAdrReview(decision) {
+    return isImportedAdrDecision(decision)
+        && decision.status === "accepted"
+        && !decision.superseded_by
+        && !decision.valid_to
+        && !!importedAdrSourceHash(decision)
+        && importedAdrReview(decision) === null;
+}
+export function pendingImportedAdrReviews(decisions) {
+    return decisions
+        .filter(isPendingImportedAdrReview)
+        .sort((a, b) => (a.date || "").localeCompare(b.date || "") || a.id.localeCompare(b.id));
+}
+function validateReviewer(reviewer) {
+    const normalized = reviewer.trim();
+    if (!normalized || normalized.length > 128 || /[\r\n]/.test(normalized) || !isCredentialFreeText(normalized)) {
+        throw new Error("ADR reviewer must be a credential-free label of 1-128 characters");
+    }
+    return normalized;
+}
+/** Apply one explicit answer to one exact live imported ADR. Never changes the
+ * ADR lifecycle or content: decline means "reviewed, keep advisory", not delete. */
+export function applyImportedAdrReview(decision, input) {
+    if (!isImportedAdrDecision(decision))
+        throw new Error(`${decision.id} is not an imported MADR/Nygard decision`);
+    if (decision.status !== "accepted" || decision.superseded_by || decision.valid_to) {
+        throw new Error(`${decision.id} is no longer a live accepted ADR; refresh the review question`);
+    }
+    if (!SOURCE_HASH.test(input.expectedSourceHash))
+        throw new Error("expected ADR source hash must be sha256:<64 lowercase hex characters>");
+    const actualHash = importedAdrSourceHash(decision);
+    if (!actualHash || actualHash !== input.expectedSourceHash) {
+        throw new Error(`ADR source changed after the question was shown (expected ${input.expectedSourceHash}, current ${actualHash ?? "missing"}); review the current ADR instead`);
+    }
+    if (!SOURCE_HASH.test(input.expectedReviewHash))
+        throw new Error("expected ADR review hash must be sha256:<64 lowercase hex characters>");
+    const actualReviewHash = importedAdrReviewHash(decision);
+    if (actualReviewHash !== input.expectedReviewHash) {
+        throw new Error(`imported ADR meaning changed after the question was shown (expected ${input.expectedReviewHash}, current ${actualReviewHash}); review the current ADR instead`);
+    }
+    const reviewer = validateReviewer(input.reviewer);
+    const reviewedAt = input.reviewedAt ?? new Date().toISOString();
+    if (reviewedAt.length > 64 || !Number.isFinite(Date.parse(reviewedAt)))
+        throw new Error("ADR review timestamp must be ISO-compatible");
+    const evidence = decision.provenance.evidence.filter((item) => !REVIEW_RECEIPT.test(item) && !item.startsWith(REVIEW_HASH_PREFIX) && !item.startsWith(REVIEWER_PREFIX) && !item.startsWith(REVIEWED_AT_PREFIX));
+    evidence.push(`adr-review:${input.disposition === "approve" ? "approved" : "declined"}:${actualHash}`, `${REVIEW_HASH_PREFIX}${actualReviewHash}`, `${REVIEWER_PREFIX}${reviewer}`, `${REVIEWED_AT_PREFIX}${reviewedAt}`);
+    return {
+        ...decision,
+        provenance: {
+            ...decision.provenance,
+            source: input.disposition === "approve"
+                ? withHumanConfirmation(decision.provenance.source)
+                : withoutHumanConfirmation(decision.provenance.source),
+            confidence: input.disposition === "approve" ? Math.max(decision.provenance.confidence, 0.95) : Math.min(decision.provenance.confidence, 0.75),
+            evidence,
+            last_verified: reviewedAt,
+        },
+    };
+}
+/** Carry a review across idempotent re-import only when the source bytes match.
+ * A changed hash deliberately returns the clean new import, reopening review. */
+export function carryImportedAdrReview(previous, next) {
+    if (!previous || !isImportedAdrDecision(previous) || !isImportedAdrDecision(next))
+        return next;
+    const previousHash = importedAdrSourceHash(previous);
+    const nextHash = importedAdrSourceHash(next);
+    if (!previousHash || previousHash !== nextHash)
+        return next;
+    const review = importedAdrReview(previous);
+    if (!review || review.reviewHash !== importedAdrReviewHash(next))
+        return next;
+    const receiptEvidence = previous.provenance.evidence.filter((item) => REVIEW_RECEIPT.test(item) || item.startsWith(REVIEW_HASH_PREFIX) || item.startsWith(REVIEWER_PREFIX) || item.startsWith(REVIEWED_AT_PREFIX));
+    return {
+        ...next,
+        provenance: {
+            ...next.provenance,
+            source: review.disposition === "approve"
+                ? withHumanConfirmation(next.provenance.source)
+                : withoutHumanConfirmation(next.provenance.source),
+            confidence: review.disposition === "approve" ? Math.max(next.provenance.confidence, 0.95) : next.provenance.confidence,
+            evidence: [...next.provenance.evidence, ...receiptEvidence],
+            last_verified: previous.provenance.last_verified,
+        },
+    };
+}
+//# sourceMappingURL=importReview.js.map

package/dist/core/pipeline.js

@@ -25,6 +25,7 @@
 import { mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { compareCodeUnits } from "./canonicalOrder.js";
 export const EXECUTION_OBLIGATION_CATEGORIES = [
     "evidence",
     "behavior",
@@ -34,6 +35,21 @@ export const EXECUTION_OBLIGATION_CATEGORIES = [
     "other",
 ];
 export const CONTRACT_AXES = ["runtime", "static", "serialization", "compatibility"];
+function ownerSourcePath(path) {
+    return /^[A-Za-z0-9._/-]+\.(?:tsx?|php)$/.test(path)
+        && !/(?:^|\/)(?:tests?|__tests__)(?:\/|$)|\.test\.(?:tsx?|php)$/.test(path);
+}
+/** Extract top-level declarations for the bounded correction diagnostic. PHP
+ * declarations deliberately require column-zero PSR-style layout so methods or
+ * nested conditional declarations cannot masquerade as repository owners. */
+function ownerDeclarations(path, content) {
+    const declaration = path.endsWith(".php")
+        ? /^(?:(?:#\[[^\r\n]*\])\r?\n)*(?:(abstract|final|readonly)\s+)*(class|interface|trait|enum|function)\s+&?\s*([A-Za-z_][A-Za-z0-9_]*)/gm
+        : /(?:^|\n)\s*(?:export\s+)?(?:declare\s+)?(interface|class|function|const|type)\s+([$A-Za-z_][$\w]*)/g;
+    return [...content.matchAll(declaration)].map((match) => path.endsWith(".php")
+        ? { kind: match[2], symbol: match[3], index: match.index ?? 0 }
+        : { kind: match[1], symbol: match[2], index: match.index ?? 0 });
+}
 export const emptyState = () => ({
     turn: 0,
     soulInjected: false,
@@ -408,17 +424,14 @@ export function rankContractAxisRiskOwners(closure, sourceValue) {
         const content = typeof item.content === "string" && item.content.length <= 1_000_000 ? item.content : null;
         if (!path || !content || seen.has(path) || path.startsWith("/") || path.split("/").includes(".."))
             continue;
-        if (!/^[A-Za-z0-9._/-]+\.tsx?$/.test(path) || /(?:^|\/)(?:tests?|__tests__)(?:\/|$)|\.test\.tsx?$/.test(path))
+        if (!ownerSourcePath(path))
             continue;
         seen.add(path);
         sources.push({ path, content });
     }
     const ranked = [];
-    const declaration = /(?:^|\n)\s*(?:export\s+)?(?:declare\s+)?(interface|class|function|const|type)\s+([$A-Za-z_][$\w]*)/g;
     for (const source of sources) {
-        for (const match of source.content.matchAll(declaration)) {
-            const kind = match[1];
-            const symbol = match[2];
+        for (const { kind, symbol } of ownerDeclarations(source.path, source.content)) {
             const normalized = symbol.toLowerCase().replace(/[^a-z0-9]/g, "");
             for (const [anchor, evidenceWeight] of candidates) {
                 if (!normalized.includes(anchor))
@@ -446,7 +459,7 @@ export function rankContractAxisRiskOwners(closure, sourceValue) {
             }
         }
     }
-    ranked.sort((a, b) => b.score - a.score || a.owner.localeCompare(b.owner));
+    ranked.sort((a, b) => b.score - a.score || compareCodeUnits(a.owner, b.owner));
     const ownerScores = new Map();
     for (const item of ranked) {
         if (!ownerScores.has(item.owner))
@@ -534,19 +547,18 @@ export function rankIssueImplementationOwners(issueValue, sourceValue, candidate
         const content = typeof item.content === "string" && item.content.length <= 1_000_000 ? item.content : null;
         if (!path || !content || seen.has(path) || path.startsWith("/") || path.split("/").includes(".."))
             continue;
-        if (!/^[A-Za-z0-9._/-]+\.tsx?$/.test(path) || /(?:^|\/)(?:tests?|__tests__)(?:\/|$)|\.test\.tsx?$/.test(path))
+        if (!ownerSourcePath(path))
             continue;
         seen.add(path);
         sources.push({ path, content });
     }
     const declarations = [];
-    const declaration = /^(?:export\s+)?(?:declare\s+)?(?:interface|class|function|const|type)\s+([$A-Za-z_][$\w]*)/gm;
     for (const source of sources) {
-        const matches = [...source.content.matchAll(declaration)];
+        const matches = ownerDeclarations(source.path, source.content);
         for (let index = 0; index < matches.length; index++) {
             const match = matches[index];
-            const symbol = match[1];
-            const start = match.index ?? 0;
+            const symbol = match.symbol;
+            const start = match.index;
             const end = matches[index + 1]?.index ?? source.content.length;
             const text = `${symbol} ${symbol} ${source.content.slice(start, end)}`.slice(0, 80_000);
             const tokens = implementationOwnerTokens(text);
@@ -598,7 +610,7 @@ export function rankIssueImplementationOwners(issueValue, sourceValue, candidate
             symbol_disclosed: symbolDisclosed,
             path_disclosed: pathDisclosed,
         };
-    }).sort((a, b) => b.score - a.score || a.owner.localeCompare(b.owner));
+    }).sort((a, b) => b.score - a.score || compareCodeUnits(a.owner, b.owner));
     const limit = Number.isSafeInteger(candidateLimit) ? Math.max(1, Math.min(4_000, candidateLimit)) : 20;
     return { candidates: candidates.slice(0, limit) };
 }

package/dist/core/types.js

@@ -254,7 +254,7 @@ export const EdgeSchema = z.object({
         ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["provenance"], message: "resource relationship fields must remain bounded" });
     }
 });
-export const SymbolKind = z.enum(["function", "method", "class", "interface", "type", "variable", "file"]);
+export const SymbolKind = z.enum(["function", "method", "class", "interface", "trait", "enum", "type", "variable", "file"]);
 export const SymbolMetricsSchema = z.object({
     loc: z.number().default(0),
     churn_90d: z.number().default(0).describe("times changed in last 90 days"),