@praneeth_54/agentdoctor 3.0.0 → 3.0.2

package/dist/product/discovery/roots.js

@@ -2,6 +2,7 @@ import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { DEFAULT_IGNORE_DIRECTORIES } from "../../constants.js";
+import { detectProject } from "../../detectors/project.js";
 import { isDirectory, pathExists } from "../../utils/fs.js";
 import { resolveRepoRoot } from "../../utils/path.js";
 /** Markers that strongly suggest a software project root. */
@@ -19,6 +20,8 @@ const PROJECT_MARKERS = [
     "pubspec.yaml",
     ".git",
 ];
+/** Directory basenames that must never be treated as a project root candidate. */
+const FORBIDDEN_ROOT_BASENAMES = new Set([".private", "agentdoctoros"]);
 const SUSPICIOUS_DIR_NAMES = new Set([
     "desktop",
     "downloads",
@@ -32,9 +35,19 @@ const SUSPICIOUS_DIR_NAMES = new Set([
 function normalizeHome(home) {
     return path.resolve(home);
 }
+function pathsEqual(a, b) {
+    const left = path.resolve(a);
+    const right = path.resolve(b);
+    return process.platform === "win32" ? left.toLowerCase() === right.toLowerCase() : left === right;
+}
 function isUnderHomeSubtree(abs, home, leaf) {
     const target = path.resolve(home, leaf);
     const resolved = path.resolve(abs);
+    if (process.platform === "win32") {
+        const t = target.toLowerCase();
+        const r = resolved.toLowerCase();
+        return r === t || r.startsWith(t + "\\");
+    }
     return resolved === target || resolved.startsWith(target + path.sep);
 }
 async function countEntriesShallow(dir, budget) {
@@ -84,6 +97,26 @@ function scoreMarkers(markers) {
     }
     return score;
 }
+/**
+ * True when `cwd` is the user home directory or a similarly unsafe broad folder
+ * (Desktop / Downloads / Documents). Used to refuse silent whole-home scans.
+ */
+export function classifyBroadUserScanRoot(cwdInput, homeInput) {
+    const cwd = path.resolve(cwdInput);
+    const home = normalizeHome(homeInput ?? os.homedir());
+    const baselower = path.basename(cwd).toLowerCase();
+    if (pathsEqual(cwd, home) ||
+        SUSPICIOUS_DIR_NAMES.has(baselower) ||
+        isUnderHomeSubtree(cwd, home, "Desktop") ||
+        isUnderHomeSubtree(cwd, home, "Downloads") ||
+        isUnderHomeSubtree(cwd, home, "Documents")) {
+        return {
+            blocked: true,
+            reason: "Refusing to scan home / Desktop / Downloads / Documents (or similarly broad user folders) as a project root. Navigate into a project directory or pass an explicit project path.",
+        };
+    }
+    return { blocked: false };
+}
 /**
  * Discover likely project roots from cwd without silently scanning home/Desktop/Downloads
  * or unbounded parent trees.
@@ -93,24 +126,20 @@ export async function discoverProjectRoots(options = {}) {
     const home = normalizeHome(os.homedir());
     const maxEntries = options.maxEntries ?? 25_000;
     const limitations = [
-        "Discovery uses shallow marker probes and bounded entry counts — not a full repository index.",
-        "Candidates are VERIFIED only when marker files/directories exist on disk.",
+        "Discovery uses shallow marker probes, bounded entry counts, and detectProject for cwd/prefer when classic markers are absent.",
+        "Candidates are VERIFIED only when marker files exist or detectProject finds languages/source under that root.",
     ];
-    const baselower = path.basename(cwd).toLowerCase();
-    if (cwd === home ||
-        SUSPICIOUS_DIR_NAMES.has(baselower) ||
-        isUnderHomeSubtree(cwd, home, "Desktop") ||
-        isUnderHomeSubtree(cwd, home, "Downloads") ||
-        isUnderHomeSubtree(cwd, home, "Documents")) {
-        const estimatedEntries = await countEntriesShallow(cwd, Math.min(maxEntries, 5_000));
+    const broad = classifyBroadUserScanRoot(cwd, home);
+    if (broad.blocked) {
         return {
             cwd,
             home,
             candidates: [],
             selected: null,
             blocked: true,
-            blockReason: "Refusing to scan home / Desktop / Downloads / Documents (or similarly broad user folders) as a project root. Navigate into a project directory or pass an explicit project path.",
-            estimatedEntries,
+            blockReason: broad.reason,
+            // Do not walk the tree — counting home/Desktop can hang CI (esp. Windows).
+            estimatedEntries: 0,
             limitations,
         };
     }
@@ -129,13 +158,19 @@ export async function discoverProjectRoots(options = {}) {
     }
     const candidates = [];
     const seen = new Set();
+    function rejectForbiddenRoot(resolved) {
+        const base = path.basename(resolved).toLowerCase();
+        return FORBIDDEN_ROOT_BASENAMES.has(base);
+    }
     async function consider(dir, reason) {
         const resolved = path.resolve(dir);
         if (seen.has(resolved))
             return;
         if (!(await isDirectory(resolved)))
             return;
-        if (resolved === home)
+        if (pathsEqual(resolved, home))
+            return;
+        if (rejectForbiddenRoot(resolved))
             return;
         const markers = await markersAt(resolved);
         if (markers.length === 0)
@@ -149,6 +184,46 @@ export async function discoverProjectRoots(options = {}) {
             reason,
         });
     }
+    /**
+     * When classic manifests/.git are absent, reuse the same detectProject path as DNA
+     * so `start` agrees with `dna` for valid software trees (e.g. language-only roots).
+     * Only applied to prefer/cwd — never to unbounded parent/child walks.
+     */
+    async function considerDetectProject(dir, reason) {
+        const resolved = path.resolve(dir);
+        if (seen.has(resolved))
+            return;
+        if (!(await isDirectory(resolved)))
+            return;
+        if (pathsEqual(resolved, home))
+            return;
+        if (rejectForbiddenRoot(resolved))
+            return;
+        if (classifyBroadUserScanRoot(resolved, home).blocked)
+            return;
+        let detection;
+        try {
+            detection = await detectProject(resolved);
+        }
+        catch {
+            return;
+        }
+        // detectProject returns ["unknown"] for empty trees — that is not a project signal.
+        const languages = detection.repository.languages.filter((l) => l !== "unknown");
+        const sourceFiles = detection.discovery.files.filter((f) => /\.(ts|tsx|js|jsx|mjs|cjs|py|php|go|rs|java|kt|kts|dart|rb|cs)$/i.test(f.relativePath)).length;
+        if (languages.length === 0 && sourceFiles === 0)
+            return;
+        seen.add(resolved);
+        const markers = languages.length > 0 ? languages.map((l) => `lang:${l}`) : [`source-files:${sourceFiles}`];
+        candidates.push({
+            root: resolved,
+            // Match strong marker score so a lone detectProject hit auto-selects like package.json.
+            score: languages.length > 0 ? 5 : 3,
+            markers,
+            truth: "VERIFIED",
+            reason,
+        });
+    }
     if (options.prefer) {
         await consider(options.prefer, "explicit prefer path");
     }
@@ -156,7 +231,7 @@ export async function discoverProjectRoots(options = {}) {
     // Walk up a few parents looking for markers (bounded).
     let parent = path.dirname(cwd);
     for (let i = 0; i < 4; i++) {
-        if (parent === home || parent === path.dirname(parent))
+        if (pathsEqual(parent, home) || parent === path.dirname(parent))
             break;
         await consider(parent, "parent directory with project markers");
         parent = path.dirname(parent);
@@ -169,16 +244,63 @@ export async function discoverProjectRoots(options = {}) {
                 continue;
             if (DEFAULT_IGNORE_DIRECTORIES.has(entry.name) || entry.name.startsWith("."))
                 continue;
+            if (FORBIDDEN_ROOT_BASENAMES.has(entry.name.toLowerCase()))
+                continue;
             await consider(path.join(cwd, entry.name), "child directory with project markers");
         }
     }
     catch {
         limitations.push("Could not list child directories for candidate discovery.");
     }
+    // detectProject fallback (same engine as DNA) for prefer/cwd when no classic markers
+    // apply to that path AND no ancestor marker candidate already covers it (nested Case B).
+    // Also skip when child classic-marker projects already exist — otherwise detectProject
+    // would absorb sibling packages into a multi-project parent (start always passes prefer=cwd).
+    const preferAbs = options.prefer ? path.resolve(options.prefer) : null;
+    function ancestorMarkerCovers(target) {
+        return candidates.find((c) => {
+            if (pathsEqual(c.root, target))
+                return true;
+            const rootWithSep = c.root.endsWith(path.sep) ? c.root : c.root + path.sep;
+            if (process.platform === "win32") {
+                return target.toLowerCase().startsWith(rootWithSep.toLowerCase());
+            }
+            return target.startsWith(rootWithSep);
+        });
+    }
+    function descendantMarkerCandidates(target) {
+        const targetWithSep = target.endsWith(path.sep) ? target : target + path.sep;
+        return candidates.filter((c) => {
+            if (pathsEqual(c.root, target))
+                return false;
+            if (process.platform === "win32") {
+                return c.root.toLowerCase().startsWith(targetWithSep.toLowerCase());
+            }
+            return c.root.startsWith(targetWithSep);
+        });
+    }
+    if (preferAbs) {
+        // Skip detectProject absorption when 2+ classic child projects exist (multi-project
+        // parent). A single nested foreign repo must not block prefer's own language tree.
+        if (!ancestorMarkerCovers(preferAbs) && descendantMarkerCandidates(preferAbs).length < 2) {
+            await considerDetectProject(preferAbs, "explicit prefer path (detectProject)");
+        }
+    }
+    else if (candidates.length === 0) {
+        await considerDetectProject(cwd, "current working directory (detectProject)");
+    }
     candidates.sort((a, b) => b.score - a.score || a.root.localeCompare(b.root));
     let selected = null;
-    if (options.prefer) {
-        selected = candidates.find((c) => c.root === path.resolve(options.prefer)) ?? null;
+    if (preferAbs) {
+        const exact = candidates.find((c) => pathsEqual(c.root, preferAbs));
+        const covered = ancestorMarkerCovers(preferAbs);
+        // Nested dir under a marker project → select the marker root, not the nested leaf.
+        if (covered && !pathsEqual(covered.root, preferAbs)) {
+            selected = covered;
+        }
+        else {
+            selected = exact ?? covered ?? null;
+        }
     }
     else if (options.autoSelect !== false) {
         const strong = candidates.filter((c) => c.score >= 5);

package/dist/product/graph/enrich-languages.js

@@ -1,7 +1,7 @@
-import fs from "node:fs/promises";
 import path from "node:path";
 import { createHash } from "node:crypto";
 import { getAdapterForFile, parseSourceFile } from "../../languages/index.js";
+import { discoverFiles } from "../../discovery/files.js";
 import { readTextFile } from "../../utils/fs.js";
 import { resolveRepoRoot, toPosixRelative } from "../../utils/path.js";
 function nodeId(kind, key) {
@@ -9,37 +9,12 @@ function nodeId(kind, key) {
 }
 const LANG_FILE_RE = /\.(py|php|go|java|kt|kts|rs|dart)$/i;
 async function listLanguageSourceFiles(root, limit = 120) {
-    const out = [];
-    const skip = new Set(["node_modules", ".git", "dist", "coverage", ".agentdoctor", "vendor"]);
-    async function walk(dir) {
-        if (out.length >= limit)
-            return;
-        let entries;
-        try {
-            entries = await fs.readdir(dir, { withFileTypes: true });
-        }
-        catch {
-            return;
-        }
-        for (const e of entries) {
-            if (out.length >= limit)
-                return;
-            if (skip.has(e.name))
-                continue;
-            const abs = path.join(dir, e.name);
-            if (e.isSymbolicLink())
-                continue;
-            if (e.isDirectory()) {
-                await walk(abs);
-                continue;
-            }
-            if (LANG_FILE_RE.test(e.name)) {
-                out.push(abs);
-            }
-        }
-    }
-    await walk(root);
-    return out.sort();
+    const discovered = await discoverFiles({ root });
+    return discovered.files
+        .filter((f) => LANG_FILE_RE.test(f.relativePath))
+        .map((f) => f.absolutePath)
+        .sort()
+        .slice(0, limit);
 }
 function evidenceFromAdapter(kind) {
     if (kind === "ast")

package/dist/product/index.d.ts

@@ -39,7 +39,7 @@ export { analyzeInfra } from "./ops/infra.js";
 export type { InfraReport, InfraArtifact } from "./ops/infra.js";
 export { buildIncidentHypotheses } from "./ops/incident.js";
 export type { IncidentReport, IncidentTimelineItem } from "./ops/incident.js";
-export { discoverProjectRoots, resolveStartedProjectRoot } from "./discovery/roots.js";
+export { discoverProjectRoots, resolveStartedProjectRoot, classifyBroadUserScanRoot, } from "./discovery/roots.js";
 export type { ProjectDiscoveryReport, ProjectCandidate, DiscoverProjectOptions, } from "./discovery/roots.js";
 export { buildProjectDna, persistProjectDna } from "./dna/build.js";
 export type { ProjectDna } from "./dna/build.js";
@@ -67,3 +67,6 @@ export { evaluateApprovalRecord, formatApprovalRecordSummary } from "./approval/
 export type { ApprovalRecord, ApprovalState, ApprovalRisk, ApprovalEvaluationInput, ApprovalEvaluationResult, } from "./approval/model.js";
 export { issueApprovalGrant, consumeApprovalGrant, hashPlanPayload, hashFileWritePlan, } from "./approval/session.js";
 export type { ApprovalGrant, ConsumeApprovalResult } from "./approval/session.js";
+export { classifyRelativePathOwnership, decideDirectoryTraversal, isNestedRepositoryRoot, isProjectOwnedRelativePath, isUnderNestedRepository, assertProjectOwnedRepoPath, ProjectOwnershipError, OWNERSHIP_BOUNDARY_VERSION, verifiedDecisionTruthMeaning, } from "../project/ownership.js";
+export type { ProjectOwnershipClass, DirectoryTraversalDecision } from "../project/ownership.js";
+export type { DecisionSourceKind } from "./decisions/ledger.js";

package/dist/product/index.js

@@ -19,7 +19,7 @@ export { runEvalLab } from "./eval/lab.js";
 export { diagnoseAgentDoctorSelf } from "./self/diagnose.js";
 export { analyzeInfra } from "./ops/infra.js";
 export { buildIncidentHypotheses } from "./ops/incident.js";
-export { discoverProjectRoots, resolveStartedProjectRoot } from "./discovery/roots.js";
+export { discoverProjectRoots, resolveStartedProjectRoot, classifyBroadUserScanRoot, } from "./discovery/roots.js";
 export { buildProjectDna, persistProjectDna } from "./dna/build.js";
 export { enrichGraphWithLanguageAdapters } from "./graph/enrich-languages.js";
 export { analyzeSecuritySurface } from "./security/doctor.js";
@@ -33,3 +33,4 @@ export { buildSoftwareEvolutionTimeline } from "./evolution/timeline.js";
 export { queryMemory } from "./memory/institutional.js";
 export { evaluateApprovalRecord, formatApprovalRecordSummary } from "./approval/model.js";
 export { issueApprovalGrant, consumeApprovalGrant, hashPlanPayload, hashFileWritePlan, } from "./approval/session.js";
+export { classifyRelativePathOwnership, decideDirectoryTraversal, isNestedRepositoryRoot, isProjectOwnedRelativePath, isUnderNestedRepository, assertProjectOwnedRepoPath, ProjectOwnershipError, OWNERSHIP_BOUNDARY_VERSION, verifiedDecisionTruthMeaning, } from "../project/ownership.js";

package/dist/product/map/software-map.js

@@ -3,6 +3,7 @@ import path from "node:path";
 import { DEFAULT_MAX_FILE_SIZE_BYTES } from "../../constants.js";
 import { detectProject } from "../../detectors/project.js";
 import { detectMonorepo } from "../../detectors/monorepo.js";
+import { isProjectOwnedRelativePath } from "../../project/ownership.js";
 import { resolveRepoRoot } from "../../utils/path.js";
 function nodeId(prefix, p) {
     return `${prefix}:${p.replace(/[^\w./-]/g, "_")}`;
@@ -11,7 +12,7 @@ async function topLevelEntries(root) {
     try {
         const entries = await fs.readdir(root, { withFileTypes: true });
         return entries
-            .filter((e) => e.isDirectory() && !e.name.startsWith("."))
+            .filter((e) => e.isDirectory() && !e.name.startsWith(".") && isProjectOwnedRelativePath(e.name))
             .map((e) => e.name)
             .sort();
     }

package/dist/product/memory/institutional.js

@@ -19,6 +19,11 @@ export async function queryMemory(rootInput, query) {
     const brain = await loadLatestBrain(root);
     if (brain) {
         for (const bh of searchBrain(brain, q).slice(0, 15)) {
+            if (bh.text.includes(".private/") ||
+                bh.text.includes("AgentDoctorOS/") ||
+                bh.text.includes("oss-validation/")) {
+                continue;
+            }
             hits.push({
                 source: "brain",
                 id: bh.id,

package/dist/product/search/software-search.js

@@ -22,6 +22,11 @@ export async function searchSymbolsAndConcepts(rootInput, query, options) {
     const brain = await loadLatestBrain(root);
     if (brain) {
         for (const bh of searchBrain(brain, q)) {
+            if (bh.text.includes(".private/") ||
+                bh.text.includes("AgentDoctorOS/") ||
+                bh.text.includes("oss-validation/")) {
+                continue;
+            }
             hits.push({
                 kind: "brain",
                 path: ".agentdoctor/project-brain",

package/dist/product/twin/store.js

@@ -5,6 +5,7 @@ import { DEFAULT_MAX_FILE_SIZE_BYTES } from "../../constants.js";
 import { atomicWriteTextFile, pathExists, readJsonFile } from "../../utils/fs.js";
 import { resolveRepoRoot } from "../../utils/path.js";
 import { buildSoftwareDigitalTwinSnapshot } from "./digital-twin.js";
+import { OWNERSHIP_BOUNDARY_VERSION } from "../../project/ownership.js";
 function twinDir(root) {
     return path.join(resolveRepoRoot(root), ".agentdoctor", "twin");
 }
@@ -12,7 +13,10 @@ function snapshotPath(root) {
     return path.join(twinDir(root), "snapshot.json");
 }
 function hashInputs(changedFiles) {
-    const payload = (changedFiles ?? []).slice().sort().join("\n");
+    const payload = [
+        `ownership-boundary:${OWNERSHIP_BOUNDARY_VERSION}`,
+        ...(changedFiles ?? []).slice().sort(),
+    ].join("\n");
     return createHash("sha256").update(payload).digest("hex").slice(0, 16);
 }
 export async function loadTwinSnapshot(rootInput) {
@@ -22,6 +26,10 @@ export async function loadTwinSnapshot(rootInput) {
         return null;
     if (parsed.data.meta.root !== root)
         return null;
+    // Reject twins built under a prior ownership boundary (or any mismatched hash).
+    const expected = hashInputs(parsed.data.meta.changedFiles);
+    if (parsed.data.meta.invalidationHash !== expected)
+        return null;
     return parsed.data;
 }
 export async function saveTwinSnapshot(rootInput, twin, meta) {

package/dist/product/whatif/engine.js

@@ -1,16 +1,37 @@
 import { deriveGraphChangeImpact } from "../../assurance/change.js";
 import { buildIntelligenceGraph } from "../../intelligence/graph/build.js";
+import { assertProjectOwnedRepoPath, classifyRelativePathOwnership, ProjectOwnershipError, } from "../../project/ownership.js";
+import { PathEscapeError, resolveSafeRepoPath } from "../../security/paths.js";
 import { resolveRepoRoot } from "../../utils/path.js";
 import { minProductTruth } from "../truth.js";
 function normalizeTarget(target) {
     return target.replace(/\\/g, "/").replace(/^\.\//, "");
 }
+async function assertOwnedWhatIfTarget(root, target) {
+    const normalized = normalizeTarget(target);
+    const lexical = classifyRelativePathOwnership(normalized);
+    if (lexical !== "project_owned") {
+        throw new ProjectOwnershipError(lexical, `what-if target outside project ownership (${lexical})`);
+    }
+    try {
+        const abs = resolveSafeRepoPath(root, normalized);
+        await assertProjectOwnedRepoPath(root, abs, normalized);
+    }
+    catch (error) {
+        if (error instanceof PathEscapeError || error instanceof ProjectOwnershipError) {
+            throw error;
+        }
+        // Non-existent owned path remains a valid hypothetical change target.
+    }
+    return normalized;
+}
 export async function analyzeWhatIf(rootInput, target, options) {
     const root = resolveRepoRoot(rootInput);
-    const normalized = normalizeTarget(target);
+    const normalized = await assertOwnedWhatIfTarget(root, target);
     const limitations = [
         "Impact analysis uses intelligence graph import/call edges when available.",
         "Symbol-level precision depends on graph node coverage.",
+        "What-if targets must be project-owned paths (containment alone is not ownership).",
     ];
     let graph = options?.graph;
     if (!graph && options?.buildGraph !== false) {

package/dist/project/ownership.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Semantic project ownership — filesystem containment alone is not ownership.
+ *
+ * VERIFIED file evidence still means "we read this path under the scan root";
+ * ownership classification decides whether that path may feed current-project
+ * intelligence (DNA, decisions, search corpus, etc.).
+ */
+export type ProjectOwnershipClass = "project_owned" | "nested_repository" | "private_workspace" | "internal_docs" | "fixture_tree" | "validation_checkout" | "generated" | "unknown";
+/** Top-level directory names that are never current-project source by default. */
+export declare const NON_OWNED_TOP_LEVEL_DIRECTORIES: Set<string>;
+/** Relative path prefixes (posix) treated as non-owned validation/fixture trees. */
+export declare const NON_OWNED_PATH_PREFIXES: readonly ["validation/real-world/repositories/checkouts/", "fixtures/nested-repos/"];
+/** Bump when ownership/traversal rules change so cached twins/brain consumers invalidate. */
+export declare const OWNERSHIP_BOUNDARY_VERSION = 4;
+export declare class ProjectOwnershipError extends Error {
+    readonly code = "PROJECT_OWNERSHIP";
+    readonly ownership: ProjectOwnershipClass;
+    constructor(ownership: ProjectOwnershipClass, message?: string);
+}
+export interface DirectoryTraversalDecision {
+    traverse: boolean;
+    ownership: ProjectOwnershipClass;
+    reason: string;
+}
+/**
+ * Classify a relative path for current-project ownership (no I/O).
+ * Nested git detection is handled separately during traversal.
+ */
+export declare function classifyRelativePathOwnership(relativePath: string): ProjectOwnershipClass;
+export declare function isProjectOwnedRelativePath(relativePath: string): boolean;
+/**
+ * True when `dir` is a nested VCS root (has `.git` file or directory) and is
+ * not the canonical project root itself.
+ */
+export declare function isNestedRepositoryRoot(projectRootInput: string, dirAbsolute: string): Promise<boolean>;
+/**
+ * Decide whether discovery should descend into a directory under the project root.
+ */
+export declare function decideDirectoryTraversal(options: {
+    projectRoot: string;
+    absoluteDir: string;
+    relativeDir: string;
+}): Promise<DirectoryTraversalDecision>;
+/**
+ * True when any ancestor directory under `projectRoot` (excluding the root) is a nested VCS root.
+ * Used for path-targeted access (agent/MCP) where discovery traversal never ran.
+ */
+export declare function isUnderNestedRepository(projectRootInput: string, absolutePath: string): Promise<boolean>;
+/**
+ * Assert a user-supplied path is both inside the repo root AND project-owned.
+ * Containment alone is not ownership (.private, AgentDoctorOS, nested repos, fixtures).
+ *
+ * Ownership is classified from the realpath-relative path under the real project root
+ * so symlink aliases (e.g. link-to-private → .private) cannot launder ownership.
+ * Lexical hints are also rejected when they themselves name a non-owned tree.
+ */
+export declare function assertProjectOwnedRepoPath(projectRootInput: string, absolutePath: string, relativeHint?: string): Promise<{
+    absolutePath: string;
+    relativePath: string;
+    ownership: ProjectOwnershipClass;
+}>;
+/**
+ * Human-readable meaning for decision truth labels in product UI.
+ */
+export declare function verifiedDecisionTruthMeaning(): string;

package/dist/project/ownership.js

@@ -0,0 +1,169 @@
+import path from "node:path";
+import fs from "node:fs";
+import { pathExists } from "../utils/fs.js";
+import { resolveRepoRoot, toPosixRelative } from "../utils/path.js";
+/** Top-level directory names that are never current-project source by default. */
+export const NON_OWNED_TOP_LEVEL_DIRECTORIES = new Set([".private", "AgentDoctorOS"]);
+/** Relative path prefixes (posix) treated as non-owned validation/fixture trees. */
+export const NON_OWNED_PATH_PREFIXES = [
+    "validation/real-world/repositories/checkouts/",
+    "fixtures/nested-repos/",
+];
+/** Bump when ownership/traversal rules change so cached twins/brain consumers invalidate. */
+export const OWNERSHIP_BOUNDARY_VERSION = 4;
+export class ProjectOwnershipError extends Error {
+    code = "PROJECT_OWNERSHIP";
+    ownership;
+    constructor(ownership, message) {
+        super(message ?? `path is outside project ownership (${ownership})`);
+        this.name = "ProjectOwnershipError";
+        this.ownership = ownership;
+    }
+}
+function firstSegment(relativePosix) {
+    const norm = relativePosix.replace(/\\/g, "/").replace(/^\.\//, "");
+    if (!norm || norm === ".")
+        return "";
+    return norm.split("/")[0] ?? "";
+}
+/**
+ * Classify a relative path for current-project ownership (no I/O).
+ * Nested git detection is handled separately during traversal.
+ */
+export function classifyRelativePathOwnership(relativePath) {
+    const norm = relativePath.replace(/\\/g, "/").replace(/^\.\//, "");
+    if (!norm || norm === ".")
+        return "project_owned";
+    const top = firstSegment(norm);
+    if (top === ".private")
+        return "private_workspace";
+    if (top === "AgentDoctorOS")
+        return "internal_docs";
+    if (top === "fixtures")
+        return "fixture_tree";
+    for (const prefix of NON_OWNED_PATH_PREFIXES) {
+        if (norm === prefix.slice(0, -1) || norm.startsWith(prefix)) {
+            return "validation_checkout";
+        }
+    }
+    if (norm.startsWith("validation/") && norm.includes("/checkouts/")) {
+        return "validation_checkout";
+    }
+    return "project_owned";
+}
+export function isProjectOwnedRelativePath(relativePath) {
+    return classifyRelativePathOwnership(relativePath) === "project_owned";
+}
+/**
+ * True when `dir` is a nested VCS root (has `.git` file or directory) and is
+ * not the canonical project root itself.
+ */
+export async function isNestedRepositoryRoot(projectRootInput, dirAbsolute) {
+    const root = resolveRepoRoot(projectRootInput);
+    const abs = path.resolve(dirAbsolute);
+    if (abs === root)
+        return false;
+    return pathExists(path.join(abs, ".git"));
+}
+/**
+ * Decide whether discovery should descend into a directory under the project root.
+ */
+export async function decideDirectoryTraversal(options) {
+    const root = resolveRepoRoot(options.projectRoot);
+    const abs = path.resolve(options.absoluteDir);
+    const rel = toPosixRelative(root, abs) || options.relativeDir.replace(/\\/g, "/");
+    if (abs === root) {
+        return {
+            traverse: true,
+            ownership: "project_owned",
+            reason: "canonical project root",
+        };
+    }
+    const pathClass = classifyRelativePathOwnership(rel);
+    if (pathClass !== "project_owned") {
+        return {
+            traverse: false,
+            ownership: pathClass,
+            reason: `non-owned tree (${pathClass})`,
+        };
+    }
+    if (await isNestedRepositoryRoot(root, abs)) {
+        return {
+            traverse: false,
+            ownership: "nested_repository",
+            reason: "nested .git repository boundary",
+        };
+    }
+    return {
+        traverse: true,
+        ownership: "project_owned",
+        reason: "inside project-owned tree",
+    };
+}
+/**
+ * True when any ancestor directory under `projectRoot` (excluding the root) is a nested VCS root.
+ * Used for path-targeted access (agent/MCP) where discovery traversal never ran.
+ */
+export async function isUnderNestedRepository(projectRootInput, absolutePath) {
+    const root = resolveRepoRoot(projectRootInput);
+    let current = path.resolve(absolutePath);
+    if (current === root)
+        return false;
+    // Walk ancestors including the path itself when it is a directory.
+    for (;;) {
+        if (current !== root && (await pathExists(path.join(current, ".git")))) {
+            return true;
+        }
+        if (current === root)
+            return false;
+        const parent = path.dirname(current);
+        if (parent === current)
+            return false;
+        current = parent;
+        if (current === root)
+            return false;
+    }
+}
+function realpathOrResolve(candidate) {
+    try {
+        return fs.realpathSync(candidate);
+    }
+    catch {
+        return path.resolve(candidate);
+    }
+}
+/**
+ * Assert a user-supplied path is both inside the repo root AND project-owned.
+ * Containment alone is not ownership (.private, AgentDoctorOS, nested repos, fixtures).
+ *
+ * Ownership is classified from the realpath-relative path under the real project root
+ * so symlink aliases (e.g. link-to-private → .private) cannot launder ownership.
+ * Lexical hints are also rejected when they themselves name a non-owned tree.
+ */
+export async function assertProjectOwnedRepoPath(projectRootInput, absolutePath, relativeHint) {
+    const root = resolveRepoRoot(projectRootInput);
+    const abs = path.resolve(absolutePath);
+    const realRoot = realpathOrResolve(root);
+    const realAbs = realpathOrResolve(abs);
+    const resolvedRelative = toPosixRelative(realRoot, realAbs) || ".";
+    if (relativeHint) {
+        const hintClass = classifyRelativePathOwnership(relativeHint.replace(/\\/g, "/"));
+        if (hintClass !== "project_owned") {
+            throw new ProjectOwnershipError(hintClass);
+        }
+    }
+    const pathClass = classifyRelativePathOwnership(resolvedRelative);
+    if (pathClass !== "project_owned") {
+        throw new ProjectOwnershipError(pathClass);
+    }
+    if (await isUnderNestedRepository(root, realAbs)) {
+        throw new ProjectOwnershipError("nested_repository");
+    }
+    return { absolutePath: realAbs, relativePath: resolvedRelative, ownership: "project_owned" };
+}
+/**
+ * Human-readable meaning for decision truth labels in product UI.
+ */
+export function verifiedDecisionTruthMeaning() {
+    return "File evidence was found and parsed for the current project. This does not prove the architectural decision is correct.";
+}