harness-everything 0.47.5 → 0.49.0

package/docs/doc-workflow-reconciliation.md

@@ -406,7 +406,9 @@ cannot replace that baseline with the latest HEAD or trust a persisted PASS.
 and governed cases exercise actual diffs. Fixtures without `baseFiles` remain non-Git, so their
 baseline is unavailable and credit is withheld. Fixture maps alone are not runtime authority.
 
-- **Accepted S1 residual (gitignored paths):** ignored, untracked candidate content is outside the non-ignored inventory. S1 grants no positive credit either way; the S2 producer must close this gap or explicitly re-accept it.
+- **F4 inventory coverage (S2 producer):** ignored and untracked paths remain in the candidate inventory, including new files and rename destinations, except for the bounded dependency-artifact policy below. With no policy, there are no new exclusions.
+- **Dependency-artifact policy:** the original project config `.agents/harness-everything/project-docs.json` may set `inventory.dependencyArtifactRoots` to any of `node_modules` and `.husky/_` (each is optional). These exact roots are pinned from baseline B; the candidate field must match B. Candidate-only config, host config, `.gitignore`, globs, aliases and other paths do not authorize pruning.
+- Before pruning, baseline and current-index paths, config sources, governed/legacy selectors, derived sources/outputs, and explicit task inputs are checked for overlap. Any overlap, ambiguous selector, unsafe root (file, symlink, alias, or outside the workspace), or retained-path symlink makes capture unavailable. Package files and `.bin` symlinks inside an approved root are not traversed; lockfiles, other paths, and ignored content outside the roots remain covered. Exclusion means installed bytes are outside this task's identity and ordinary code/frontmatter facts; it does not attest dependency contents or execution behavior.
 
 ### Refusal and completion contract
 
@@ -1258,7 +1260,53 @@ flowchart LR
 | Worker and D | The dispatch key is `(session_id, tool_use_id)`. Exactly one matching Task/Agent result must carry `tool_response.status === 'completed'`; its observed `tool_response.agentId` must map to exactly one `SubagentStart` and one `SubagentStop` with the same `session_id` and `agent_id`. Require PreToolUse < SubagentStart < SubagentStop in journal order, but do not order the completed result against Stop. Both worker events need exact canonical `cwd === workerRoot`. `prompt_id` and `parent_tool_use_id` are not correlation keys; `interrupted` is not completion proof. Async launches, failures, cancellation, missing/duplicate events, replayed IDs, worktree isolation and root mismatch stay unresolved. D is checked against the current candidate separately from O. O must be a strict ancestor of D. A squash may retain the cycle only when a coordinator correspondence record proves identical target blobs between retained pre-merge D and the merged tree; changed bytes need fresh final quality review. |
 | Checker outcome | `outline-confirmation` has its own pass/unresolved lane. Generic command success and waivers never satisfy it. No D is incomplete/unresolved. Its result is separate from the aggregate result over every MUST derived from original B→D; an outline pass never waives lint, conflict, quality review, requirement-sync or other MUSTs. |
 
-Capture and validation failures stay fail-open to host tools and withhold evidence credit. Unclassified shell commands and writes outside the correlated worker/root remain unresolved. A same-root subagent start is unresolved as a competing writer when it may overlap the exclusive draft interval, from accepted dispatch PreToolUse through the uniquely correlated draft worker’s Stop. A uniquely identified agent whose Start and unique Stop both precede dispatch, or whose Start occurs strictly after that worker Stop, does not establish overlap by its Start alone. Missing, duplicated or inconsistent lifecycle evidence stays unresolved. This exception does not authorize writes outside the correlated draft worker/root or relax independent review, artifact identity or final-byte validation.
+Capture and validation failures stay fail-open to host tools and withhold evidence credit. Writer activity is decided per captured record by the phase-aware policy below (see [Writer policy](#writer-policy-phase-aware)); anything it does not allow stays `outline-writer-activity-ambiguous`. A same-root subagent start is unresolved as a competing writer when it may overlap the exclusive draft interval, from accepted dispatch PreToolUse through the uniquely correlated draft worker’s Stop. A uniquely identified agent whose Start and unique Stop both precede dispatch, or whose Start occurs strictly after that worker Stop, does not establish overlap by its Start alone. Missing, duplicated or inconsistent lifecycle evidence stays unresolved. This exception does not authorize writes outside the correlated draft worker/root or relax independent review, artifact identity or final-byte validation.
+
+### Writer policy (phase-aware)
+
+Each captured writer record is decided by principal × phase × operation × target. Captured identity and journal position are the only inputs; a command string never decides on its own. This replaces the earlier blanket rule that rejected any writer other than the draft worker.
+
+```mermaid
+flowchart LR
+  R["captured writer record"] --> P{"journal phase"}
+  P -->|"before reviewer launch"| B["B→O: coordinator writes or git add/commit of the pinned target"]
+  P -->|"reviewer launch to its Stop"| V["review: no writer"]
+  P -->|"review Stop to dispatch"| H["review→dispatch: no writer (W3 unverifiable)"]
+  P -->|"dispatch to worker Stop"| D["draft: correlated worker in its root"]
+  P -->|"after worker Stop"| A["after D: no writer"]
+  B --> S["O commit must change exactly the pinned target(s) against B"]
+```
+
+| Phase | Principal | Operation and target | Result |
+|---|---|---|---|
+| Before reviewer launch | Coordinator: no `agent_id`, author `session_id` | `Write`, `Edit` or `apply_patch` whose every path is a pinned target | Allowed |
+| Before reviewer launch | Coordinator | `git add [--] <literal pinned file>...` or `git commit -m <message>`; R11-1 (b): record before review, validate at dispatch; uncaptured/pre-B index effects are UNCHECKED | Allowed only under this grammar; unbound or unverified index effects receive no credit |
+| Before reviewer launch | Any | Any other write, chained or unknown shell command, or a path that is not the target | `outline-writer-activity-ambiguous` |
+| Review | Reviewer or any other agent | Any writer | Ambiguous |
+| Review to dispatch | Coordinator | Any write, including handoff, lease, pin and merge-correspondence files | Ambiguous |
+| Dispatch to worker Stop | Correlated worker, `cwd` equal to the worker root | Any writer | Allowed |
+| Dispatch to worker Stop | Other agent or coordinator | Any writer | Ambiguous; an overlapping same-root start is `outline-competing-writer-start` |
+| After worker Stop | Any | Any writer | Ambiguous |
+
+- The reviewer launch is the first journal record that is the reviewer's own, or the launch result sharing its `tool_use_id`. The review ends at the reviewer's `SubagentStop`.
+- Write-family records carry `writeTargets` (the `file_path`, or the `apply_patch` headers). A record without a target is ambiguous.
+- **Exact target spelling.** For pinned `T` under captured root `R`, credit requires every extracted file-tool or Git-add operand to match `T`, `R/T` or product-canonical `C/T` byte-for-byte (Windows native-separator forms are allowed only for file tools), with captured cwd exactly `R` or `C`; normalization, folding, expansion and URL decoding never create identity. Other host renderings remain UNCHECKED without retained payload.
+- **F1 symlink boundary.** Coordinator writer credit requires an in-root path with no symlink components and a regular current leaf (Git add also requires a regular leaf at PreToolUse); O citations are parsed only from an exact pinned-tree `blob` entry of mode `100644` or `100755`. The PreToolUse topology snapshot does not lock the path through the operation, so any unbound operation-time state is UNCHECKED; locally rewritten events remain within the F13 limit.
+- The O commit scope check requires `git diff --name-only B O` to equal the pinned target paths, otherwise `outline-commit-scope-invalid`.
+- **Pre-review Git identity (W2).** This is the immutable Git object identity of Outline O, taken before independent review. It is not the Git author's name or email. Harness records `{baselineCommit, outlineCommit, outlineTree, targetPaths, targetBlobs}` (per target: `blobOid` and `storedBytesSha256`) at each `SubagentStart` inside an outline task. The reviewer's launch record therefore predates its review, and the reviewer does not echo any identity. Dispatch requires the handoff identity to equal the reviewer's record exactly; any difference is `outline-identity-mismatch`, and a fresh review is needed for a new O.
+
+```mermaid
+flowchart LR
+  S["reviewer SubagentStart<br/>records O identity"] --> R["review<br/>bound to that record"]
+  R --> D{"dispatch: handoff identity equal?"}
+  D -->|"yes"| W["worker starts from clean O"]
+  D -->|"no: amend, replacement, tree or target change"| X["outline-identity-mismatch: fresh review"]
+```
+
+- Suggested contract wording (owner, #341 comment 6708822276): "Exact task and target-path binding, captured writer operations, and immutable Outline O Git commit/tree/artifact identity validated before independent review and revalidated at dispatch."
+- **W3 stays rejected.** Handoff, lease, pin and merge-correspondence files are written outside capture and their content is not bound at capture time, so no coordinator state write is verifiable from evidence yet. The dispatch seam still validates those bytes; the writes themselves are rejected.
+- **W4 is unchanged.** Outline credit still needs a host-captured `SubagentStop` review and a correlated Task/Agent result from an agent distinct from the coordinator and worker. Only the Claude Code host is captured for outline credit; OpenCode and other reviewer providers are not.
+- Negative controls: the mechanism file injects each rejected case through the real hook, provider and `pilot.assess()` (`writer-policy negative controls`, `pre-review writer positive controls`).
 
 Retries use a fresh attempt, token, clean worktree and immutable handoff; only one non-superseded leaf is current. An identical same-tool-ID/input callback may reuse its stored seam, but repeated PreToolUse records remain ambiguous for evidence credit; changed input or token reuse is unresolved. OpenCode and Codex remain unsupported for positive outline credit.
 

package/harness-everything/SKILL.md

@@ -4,7 +4,7 @@ description: "Route software/project work through Harness: classify tier/topolog
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.47.3
+  version: 0.48.0
 ---
 
 # Harness Everything

package/harness-everything/scripts/doc-lifecycle.js

@@ -1701,6 +1701,15 @@ function parseInventoryDoc(relativePath, bytes) {
   };
 }
 
+function convertWorkspaceFiles(root, inventory) {
+  const files = (Array.isArray(inventory) ? inventory : []).map(item => ({
+    relative: item.path,
+    bytes: Buffer.from(item.bytes)
+  }));
+  const rules = readWorkingTreeRules(root, files.filter(item => item.bytes.includes(0x0d)).map(item => item.relative));
+  return files.map(item => ({ path: item.relative, bytes: workingStoredBytes(root, item.relative, item.bytes, rules) }));
+}
+
 function scanWorkspaceFiles(root, scope = null) {
   if (!root) return [];
   const workspace = path.resolve(root);
@@ -1728,8 +1737,7 @@ function scanWorkspaceFiles(root, scope = null) {
     }
   }
   walk(workspace, '');
-  const rules = readWorkingTreeRules(workspace, files.filter(item => item.bytes.includes(0x0d)).map(item => item.relative));
-  return files.map(item => ({ path: item.relative, bytes: workingStoredBytes(workspace, item.relative, item.bytes, rules) }));
+  return convertWorkspaceFiles(workspace, files.map(item => ({ path: item.relative, bytes: item.bytes })));
 }
 
 function scanWorkspaceInventory(root) {
@@ -2785,6 +2793,6 @@ function main(argv = process.argv.slice(2)) {
   return analysis.diagnostics.some(item => item.severity === 'error') ? 1 : 0;
 }
 
-module.exports = { readGitBaseInventory, scanWorkspaceFiles, parseFrontmatter, parseRequirementBlocks, collectDocs, documentCorpusPaths, analyzeDocs, resolveRef, lintDocs, buildIndex, buildIndexSnapshot, configSourceInventory, diffRevisions, buildGitDocumentInventory };
+module.exports = { readGitBaseInventory, scanWorkspaceFiles, convertWorkspaceFiles, parseFrontmatter, parseRequirementBlocks, collectDocs, documentCorpusPaths, analyzeDocs, resolveRef, lintDocs, buildIndex, buildIndexSnapshot, configSourceInventory, diffRevisions, buildGitDocumentInventory };
 
 if (require.main === module) process.exitCode = main();

package/harness-everything/scripts/project-docs-resolver.js

@@ -21,6 +21,7 @@ const PROJECT_DOCS_CONFIG = path.join('.agents', 'harness-everything', 'project-
 const PROJECT_DOC_ROLES = Object.freeze(['prd', 'adr', 'ticket', 'reference', 'log', 'report']);
 const PROJECT_DOC_CONFIG_KEYS = new Set([
   'governed', 'domains', 'legacy', 'derived', 'tickets',
+  'inventory',
   'docLocation', 'tracker', 'issueDefinition', 'contextMap', 'contextMapPath',
   'decisionLocation', 'decisions', 'adrLocation', 'adr',
   'domainLocation', 'contextLocation', 'contexts', 'domain',
@@ -327,6 +328,17 @@ function validateDocsConfig(config) {
     }
   }
 
+  if (Object.prototype.hasOwnProperty.call(config, 'inventory')) {
+    const inventory = config.inventory;
+    const roots = inventory && inventory.dependencyArtifactRoots;
+    const supportedRoots = new Set(['node_modules', '.husky/_']);
+    if (!isPlainObject(inventory) || Object.keys(inventory).some(key => key !== 'dependencyArtifactRoots')
+      || !Array.isArray(roots) || roots.some(root => typeof root !== 'string' || !supportedRoots.has(root))
+      || new Set(roots).size !== roots.length) {
+      invalid('invalid-dependency-artifact-roots', 'inventory.dependencyArtifactRoots must contain distinct exact roots from node_modules and .husky/_');
+    }
+  }
+
   if (Object.prototype.hasOwnProperty.call(config, 'tickets') &&
       config.tickets !== 'tracker' && !isRepoRelativePath(config.tickets)) {
     invalid('invalid-tickets', 'tickets must be "tracker" or a repo-relative path');

package/hooks/scripts/lib/doc-reconciliation-core.js

@@ -12,6 +12,7 @@ function runtimeModule(name) {
 }
 const { checkDocObligations } = runtimeModule('doc-evidence.js');
 const { deriveDocFacts, deriveDocObligations } = runtimeModule('doc-obligations.js');
+const { validateDocsConfig } = runtimeModule('project-docs-resolver.js');
 const text = value => typeof value === 'string' && value.trim().length > 0;
 const record = value => value !== null && typeof value === 'object' && !Array.isArray(value);
 const compare = (a, b) => a < b ? -1 : a > b ? 1 : 0;
@@ -38,6 +39,9 @@ const sameIdentity = (a, b) => validIdentity(a) && validIdentity(b) && identityF
 const diagnostic = (code, context = {}) => ({ code, message: code.replace(/-/g, ' '), ...context });
 const pathCompare = (a, b) => Buffer.compare(Buffer.from(a.path), Buffer.from(b.path));
 const codedError = code => Object.assign(new Error(code), { code });
+const PROJECT_CONFIG_PATH = '.agents/harness-everything/project-docs.json';
+const DEPENDENCY_ARTIFACT_ROOTS = new Set(['node_modules', '.husky/_']);
+const DEPENDENCY_POLICY_VERSION = 'dependency-artifact-scope/1';
 // The derive contract (doc-obligations.js) decides applicability from governed/legacy documents, derived
 // outputs and code/REQ-test paths. Records outside them cannot affect document obligations.
 // shortcut: mirrors derive path rules, update them together until a shared classifier is exposed.
@@ -136,6 +140,57 @@ function snapshotDigest(kind, baseline, coverage, records) {
   for (const item of [...records].sort(pathCompare)) fields.push(item.path, item.presence, item.type, item.mode, bytes(item.storedBytes));
   return hashFrames(fields);
 }
+function pathUnderDependencyRoot(relative, root) {
+  const candidate = String(relative).replace(/\\/g, '/').normalize('NFC').toLowerCase();
+  const prefix = root.normalize('NFC').toLowerCase();
+  return candidate === prefix || candidate.startsWith(`${prefix}/`);
+}
+function projectConfigFromStoredBytes(value) {
+  try {
+    const config = JSON.parse(bytes(value).toString('utf8'));
+    return validateDocsConfig(config).valid ? config : null;
+  } catch { return null; }
+}
+function validCoverage(snapshot) {
+  const coverage = snapshot.candidate?.coverage;
+  if (!record(coverage) || !Array.isArray(coverage.excluded) || !record(coverage.scope)) return false;
+  if (coverage.kind === 'whole-project') {
+    return Object.keys(coverage).sort(compare).join('\0') === ['excluded', 'kind', 'scope'].sort(compare).join('\0')
+      && stable(coverage.excluded) === stable(['.git']);
+  }
+  const fields = ['dependencyArtifactRoots', 'excluded', 'excludedRootStates', 'guardOutcomes', 'kind', 'policySource', 'policyVersion', 'scope'];
+  if (coverage.kind !== 'project-with-dependency-artifact-exclusions'
+    || Object.keys(coverage).sort(compare).join('\0') !== fields.sort(compare).join('\0')
+    || coverage.policyVersion !== DEPENDENCY_POLICY_VERSION || !record(coverage.policySource)
+    || Object.keys(coverage.policySource).sort(compare).join('\0') !== ['baselineCommit', 'path', 'storedBytesDigest'].sort(compare).join('\0')
+    || coverage.policySource.path !== PROJECT_CONFIG_PATH || coverage.policySource.baselineCommit !== snapshot.baseline.commit
+    || !/^[a-f0-9]{64}$/.test(coverage.policySource.storedBytesDigest || '')
+    || !Array.isArray(coverage.dependencyArtifactRoots) || !coverage.dependencyArtifactRoots.length
+    || coverage.dependencyArtifactRoots.some(root => !DEPENDENCY_ARTIFACT_ROOTS.has(root))
+    || stable(coverage.dependencyArtifactRoots) !== stable([...coverage.dependencyArtifactRoots].sort())
+    || new Set(coverage.dependencyArtifactRoots).size !== coverage.dependencyArtifactRoots.length
+    || stable(coverage.excluded) !== stable(['.git', ...coverage.dependencyArtifactRoots])) return false;
+  const roots = coverage.dependencyArtifactRoots;
+  const baselinePolicy = snapshot.baseline.records.find(item => item.path === PROJECT_CONFIG_PATH && item.presence === 'present');
+  const candidatePolicy = snapshot.config.capture.sources.find(item => item.path === PROJECT_CONFIG_PATH && item.presence === 'present');
+  if (!baselinePolicy || !candidatePolicy || sha(bytes(baselinePolicy.storedBytes)) !== coverage.policySource.storedBytesDigest) return false;
+  const baseConfig = projectConfigFromStoredBytes(baselinePolicy.storedBytes);
+  const candidateConfig = projectConfigFromStoredBytes(candidatePolicy.bytes);
+  const baseRoots = baseConfig?.inventory?.dependencyArtifactRoots;
+  const candidateRoots = candidateConfig?.inventory?.dependencyArtifactRoots;
+  if (!Array.isArray(baseRoots) || !Array.isArray(candidateRoots)
+    || stable([...baseRoots].sort()) !== stable([...candidateRoots].sort())
+    || stable([...baseRoots].sort()) !== stable(roots)) return false;
+  if ([...snapshot.baseline.records, ...snapshot.candidate.records].some(item => roots.some(root => pathUnderDependencyRoot(item.path, root)))) return false;
+  if (!Array.isArray(coverage.excludedRootStates) || coverage.excludedRootStates.length !== roots.length
+    || coverage.excludedRootStates.some((item, index) => !record(item) || item.path !== roots[index]
+      || !['absent', 'present-directory'].includes(item.presence)
+      || Object.keys(item).sort(compare).join('\0') !== ['path', 'presence'].sort(compare).join('\0'))) return false;
+  const guards = ['baseline-paths', 'index-paths', 'config-sources', 'config-selectors', 'task-inputs', 'excluded-root-types'];
+  return Array.isArray(coverage.guardOutcomes) && coverage.guardOutcomes.length === guards.length
+    && coverage.guardOutcomes.every((item, index) => record(item) && item.guard === guards[index] && item.state === 'clear'
+      && text(item.reason) && (index !== guards.length - 1 || stable(item.roots) === stable(coverage.excludedRootStates)));
+}
 function configDigest(config) {
   const sources = [...config.capture.sources].sort(pathCompare);
   const fields = ['doc-config-v1', stable({ activeHost: config.capture.activeHost, selectionInputs: config.capture.selectionInputs, resolution: config.resolution }), String(sources.length)];
@@ -146,6 +201,7 @@ function validateSnapshot(snapshot) {
   const errors = [];
   try {
     if (!validIdentity(snapshot.identity) || !record(snapshot.facts) || !Array.isArray(snapshot.obligations)) throw new Error('invalid-input');
+    if (!validCoverage(snapshot)) errors.push(diagnostic('inventory-unsupported'));
     // Roots are canonicalized at capture; keep reconciliation detached and free of filesystem reads.
     const context = snapshot.originContext;
     if (!record(context) || !record(context.baseline) || !text(context.workspaceRoot)

package/hooks/scripts/lib/doc-reconciliation-producer.js

@@ -4,14 +4,17 @@ const fs = require('fs');
 const path = require('path');
 const { execFileSync } = require('child_process');
 const { _internals: U } = require('./doc-reconciliation-core');
-const { scanWorkspaceFiles } = U.runtimeModule('doc-lifecycle.js');
-const { resolveDocsConfigCaptured } = U.runtimeModule('project-docs-resolver.js');
+const { convertWorkspaceFiles } = U.runtimeModule('doc-lifecycle.js');
+const { resolveDocsConfigCaptured, validateDocsConfig } = U.runtimeModule('project-docs-resolver.js');
 const { deriveDocFacts, deriveDocObligations } = U.runtimeModule('doc-obligations.js');
 
 const MAX_FILES = 10000;
 const MAX_BYTES = 64 * 1024 * 1024;
 const POSIX_MODES = process.platform !== 'win32';
-function fail(code) { throw new Error(code); }
+const PROJECT_CONFIG_PATH = '.agents/harness-everything/project-docs.json';
+const SUPPORTED_ARTIFACT_ROOTS = new Set(['node_modules', '.husky/_']);
+const POLICY_VERSION = 'dependency-artifact-scope/1';
+function fail(code, reasonCode) { throw Object.assign(new Error(code), reasonCode ? { reasonCode } : {}); }
 // The JS realpath keeps Windows 8.3 spellings (RUNNER~1) while Git reports the long name, so
 // directory identity uses native resolution and is case-insensitive on Windows (as workflow-isolation).
 function canonicalPath(value) { return fs.realpathSync.native(path.resolve(value)); }
@@ -64,7 +67,249 @@ function captureBaseline(root, pin) {
   validatePaths(records);
   return { commit, treeRef, records };
 }
-function captureCandidate(root, baseline) {
+
+function pathUnderRoot(relative, root) {
+  const candidate = String(relative).replace(/\\/g, '/').normalize('NFC').toLowerCase();
+  const expected = root.normalize('NFC').toLowerCase();
+  return candidate === expected || candidate.startsWith(`${expected}/`);
+}
+function rootMention(value, root) {
+  const normalized = String(value).replace(/\\/g, '/').normalize('NFC').toLowerCase();
+  const needle = root.normalize('NFC').toLowerCase();
+  let offset = 0;
+  while ((offset = normalized.indexOf(needle, offset)) >= 0) {
+    const before = offset === 0 || !/[a-z0-9_.-]/.test(normalized[offset - 1]);
+    const after = offset + needle.length;
+    const boundary = after === normalized.length || /[/*?\s"'`:#),;\]]/.test(normalized[after]);
+    if (before && boundary) return true;
+    offset++;
+  }
+  return false;
+}
+function globSegmentMatches(rawPattern, rawSegment) {
+  // Same NFC + lowercase folding as rootMention()/pathUnderRoot(), so a wildcard spelling cannot dodge it.
+  const pattern = rawPattern.normalize('NFC').toLowerCase();
+  const segment = rawSegment.normalize('NFC').toLowerCase();
+  if (/[\[\]{}]/.test(pattern)) return true;
+  const escaped = pattern.split(/([*?])/).map(part => part === '*' ? '[\\s\\S]*' : part === '?' ? '[\\s\\S]'
+    : part.replace(/[|\\{}()[\]^$+?.]/g, '\\$&')).join('');
+  return new RegExp(`^${escaped}$`).test(segment);
+}
+function relativeSelectorMayIntersectRoot(selector, root) {
+  const normalized = selector.replace(/\\/g, '/');
+  if (/[\[\]{}]/.test(normalized) || normalized.split('/').includes('..')) return true;
+  // `.` and empty segments are redundant anywhere in a workspace-relative selector.
+  const pattern = normalized.split('/').filter(segment => segment !== '' && segment !== '.');
+  const target = root.split('/');
+  let states = new Set([0]);
+  const closure = values => {
+    const expanded = new Set(values);
+    let changed = true;
+    while (changed) {
+      changed = false;
+      for (const index of expanded) {
+        if (pattern[index] === '**' && !expanded.has(index + 1)) {
+          expanded.add(index + 1);
+          changed = true;
+        }
+      }
+    }
+    return expanded;
+  };
+  states = closure(states);
+  for (const segment of target) {
+    const next = new Set();
+    for (const index of states) {
+      if (index >= pattern.length) continue;
+      if (pattern[index] === '**') next.add(index);
+      else if (globSegmentMatches(pattern[index], segment)) next.add(index + 1);
+    }
+    states = closure(next);
+    if (!states.size) return false;
+  }
+  return states.size > 0;
+}
+function relativePathWithin(workspace, candidate, pathApi) {
+  const relative = pathApi.relative(workspace, candidate);
+  if (!relative) return '';
+  const normalized = relative.replace(/\\/g, '/');
+  // Case and filesystem aliases that cannot be resolved exactly must fail closed.
+  const workspaceParts = workspace.replace(/\\/g, '/').split('/').filter(Boolean);
+  const candidateParts = candidate.replace(/\\/g, '/').split('/').filter(Boolean);
+  const samePrefix = workspaceParts.length <= candidateParts.length
+    && workspaceParts.every((part, index) => part.normalize('NFC').toLowerCase()
+      === candidateParts[index].normalize('NFC').toLowerCase());
+  if (samePrefix) return candidateParts.slice(workspaceParts.length).join('/');
+  if (pathApi.isAbsolute(relative) || normalized === '..' || normalized.startsWith('../')) return null;
+  return normalized;
+}
+function realpathWithMissingSuffix(candidate, pathApi) {
+  let current = candidate;
+  const suffix = [];
+  while (true) {
+    try { return pathApi.resolve(fs.realpathSync.native(current), ...suffix); }
+    catch (error) {
+      if (!['ENOENT', 'ENOTDIR'].includes(error.code)) return null;
+      const parent = pathApi.dirname(current);
+      if (parent === current) return null;
+      suffix.unshift(pathApi.basename(current));
+      current = parent;
+    }
+  }
+}
+function absoluteSelectorRelatives(selector, workspaceRoot) {
+  const windowsDrive = /^[A-Za-z]:/.test(selector);
+  if ((windowsDrive || selector.startsWith('\\') || selector.startsWith('//')) && process.platform !== 'win32') return true;
+  const pathApi = process.platform === 'win32' ? path.win32 : path;
+  if (windowsDrive && !pathApi.isAbsolute(selector)) return true;
+  if (!pathApi.isAbsolute(selector)) return null;
+
+  const workspace = canonicalPath(workspaceRoot);
+  const absolute = pathApi.resolve(selector);
+  const lexicalRelative = relativePathWithin(workspace, absolute, pathApi);
+  const resolved = realpathWithMissingSuffix(absolute, pathApi);
+  if (!resolved) return true;
+  const realRelative = relativePathWithin(workspace, resolved, pathApi);
+  if (lexicalRelative !== null && realRelative !== null) return [lexicalRelative, realRelative];
+  if (lexicalRelative !== null || realRelative !== null) return true;
+  // A glob outside the workspace can still expand into it (via a parent such as /tmp/*/node_modules/**
+  // or a symlinked entry under an unrelated directory); only literal outside paths are provably disjoint.
+  if (/[*?\[\]{}]/.test(selector)) return true;
+  return false;
+}
+function selectorMayIntersectRoot(selector, root, workspaceRoot) {
+  if (typeof selector !== 'string' || !selector.trim()) return true;
+  const absolute = absoluteSelectorRelatives(selector, workspaceRoot);
+  if (absolute === true) return true;
+  if (absolute === false) return false;
+  if (absolute !== null) return absolute.some(relative => relativeSelectorMayIntersectRoot(relative || '.', root));
+  return relativeSelectorMayIntersectRoot(selector, root);
+}
+function valueMayIntersectRoots(value, roots, workspaceRoot) {
+  if (typeof value === 'string') {
+    const absolute = absoluteSelectorRelatives(value, workspaceRoot);
+    if (absolute === true) return true;
+    if (absolute === false) return false;
+    if (absolute !== null) return roots.some(root => absolute.some(relative => {
+      const selector = relative || '.';
+      return rootMention(selector, root)
+        || ((selector.includes('/') || /[*?\[\]{}]/.test(selector)) && selectorMayIntersectRoot(selector, root, workspaceRoot));
+    }));
+    return roots.some(root => rootMention(value, root)
+      || ((!value.trim() || value.includes('/') || /[*?\[\]{}]/.test(value))
+        && selectorMayIntersectRoot(value, root, workspaceRoot)));
+  }
+  if (Array.isArray(value)) return value.some(item => valueMayIntersectRoots(item, roots, workspaceRoot));
+  if (U.record(value)) return Object.entries(value).some(([key, item]) => valueMayIntersectRoots(key, roots, workspaceRoot)
+    || valueMayIntersectRoots(item, roots, workspaceRoot));
+  return false;
+}
+function withoutTaskPinIdentity(value) {
+  if (Array.isArray(value)) return value.map(withoutTaskPinIdentity);
+  if (!U.record(value)) return value;
+  return Object.fromEntries(Object.entries(value)
+    .filter(([key]) => !/ids?$/i.test(key))
+    .map(([key, item]) => [key, withoutTaskPinIdentity(item)]));
+}
+function projectConfigFromBytes(bytes) {
+  try {
+    const config = JSON.parse(Buffer.from(bytes).toString('utf8'));
+    return { config, valid: validateDocsConfig(config).valid };
+  } catch { return { config: null, valid: false }; }
+}
+function baselineProjectConfig(baseline) {
+  const source = baseline.records.find(item => item.path === PROJECT_CONFIG_PATH && item.presence === 'present');
+  return source ? { source, ...projectConfigFromBytes(source.storedBytes) } : { source: null, config: null, valid: false };
+}
+function capturedProjectConfig(config) {
+  const source = config.capture.sources.find(item => item.path === PROJECT_CONFIG_PATH);
+  return source && source.presence === 'present'
+    ? { source, ...projectConfigFromBytes(source.bytes) }
+    : { source: source || null, config: null, valid: false };
+}
+function dependencyRoots(config) {
+  return U.record(config) && U.record(config.inventory)
+    && Object.prototype.hasOwnProperty.call(config.inventory, 'dependencyArtifactRoots')
+    ? config.inventory.dependencyArtifactRoots : undefined;
+}
+function sameRootField(left, right) {
+  if (left === undefined || right === undefined) return left === right;
+  return U.stable([...left].sort()) === U.stable([...right].sort());
+}
+function validateExcludedRoots(workspaceRoot, roots) {
+  const workspace = canonicalPath(workspaceRoot);
+  const states = [];
+  for (const root of roots) {
+    let parent = workspace;
+    let presence = 'present-directory';
+    for (const component of root.split('/')) {
+      let entries;
+      try { entries = fs.readdirSync(parent, { withFileTypes: true }); }
+      catch { fail('inventory-incomplete', 'dependency-root-parent-unreadable'); }
+      const aliases = entries.filter(entry => entry.name.normalize('NFC').toLowerCase() === component.normalize('NFC').toLowerCase());
+      if (aliases.length > 1 || aliases.some(entry => entry.name !== component)) fail('inventory-unsupported', 'dependency-root-alias');
+      const current = path.join(parent, component);
+      let stat;
+      try { stat = fs.lstatSync(current); }
+      catch (error) {
+        if (error.code === 'ENOENT') { presence = 'absent'; break; }
+        fail('inventory-incomplete', 'dependency-root-unreadable');
+      }
+      if (stat.isSymbolicLink() || !stat.isDirectory()) fail('inventory-unsupported', 'dependency-root-not-plain-directory');
+      let real;
+      try { real = fs.realpathSync.native(current); }
+      catch { fail('inventory-incomplete', 'dependency-root-unreadable'); }
+      const within = process.platform === 'win32'
+        ? real.toLowerCase().startsWith(`${workspace.toLowerCase()}${path.sep}`)
+        : real.startsWith(`${workspace}${path.sep}`);
+      if (!within) fail('inventory-unsupported', 'dependency-root-outside-workspace');
+      parent = current;
+    }
+    states.push({ path: root, presence });
+  }
+  return states;
+}
+function guardedPolicy(root, baseline, capturedConfig, input) {
+  const base = baselineProjectConfig(baseline);
+  const current = capturedProjectConfig(capturedConfig);
+  const baselineRoots = base.valid ? dependencyRoots(base.config) : undefined;
+  const candidateRoots = current.valid ? dependencyRoots(current.config) : undefined;
+  if (current.valid && candidateRoots !== undefined && (!base.valid || !sameRootField(baselineRoots, candidateRoots))) {
+    fail('inventory-unsupported', 'dependency-artifact-policy-changed-or-unpinned');
+  }
+  if (!base.valid || baselineRoots === undefined || baselineRoots.length === 0) return null;
+  if (!current.valid || !sameRootField(baselineRoots, candidateRoots)) fail('inventory-unsupported', 'dependency-artifact-policy-changed-or-unpinned');
+  const roots = [...baselineRoots].sort();
+  const indexed = git(root, ['ls-files', '-z']).toString('utf8').split('\0').filter(Boolean);
+  if (baseline.records.some(item => roots.some(value => pathUnderRoot(item.path, value)))) fail('inventory-unsupported', 'baseline-path-overlap');
+  if (indexed.some(item => roots.some(value => pathUnderRoot(item, value)))) fail('inventory-unsupported', 'index-path-overlap');
+  if (capturedConfig.capture.sources.some(item => roots.some(value => pathUnderRoot(item.path, value)))) {
+    fail('inventory-unsupported', 'config-source-overlap');
+  }
+  const configs = [base.config, capturedConfig.resolution.config];
+  if (configs.some(config => {
+    if (!U.record(config)) return false;
+    const selectors = Object.fromEntries(Object.entries(config).filter(([key]) => key !== 'inventory'));
+    return valueMayIntersectRoots(selectors, roots, root);
+  })) fail('inventory-unsupported', 'config-selector-overlap');
+  if (valueMayIntersectRoots(withoutTaskPinIdentity(input.task), roots, root) || valueMayIntersectRoots(input.scope, roots, root)) {
+    fail('inventory-unsupported', 'task-input-overlap');
+  }
+  return {
+    roots,
+    baselineCommit: baseline.commit,
+    storedBytesDigest: U.sha(base.source.storedBytes),
+    guardOutcomes: [
+      { guard: 'baseline-paths', state: 'clear', reason: 'No baseline path intersects an approved root.' },
+      { guard: 'index-paths', state: 'clear', reason: 'No current index path intersects an approved root.' },
+      { guard: 'config-sources', state: 'clear', reason: 'No baseline or current config source intersects an approved root.' },
+      { guard: 'config-selectors', state: 'clear', reason: 'Baseline and current config declarations are disjoint from approved roots.' },
+      { guard: 'task-inputs', state: 'clear', reason: 'No explicit task or requirement input intersects an approved root.' }
+    ]
+  };
+}
+function captureCandidate(root, baseline, excludedRoots = []) {
+  const excludedRootStates = excludedRoots.length ? validateExcludedRoots(root, excludedRoots) : [];
   const raw = [];
   let total = 0;
   let visited = 0;
@@ -72,8 +317,9 @@ function captureCandidate(root, baseline) {
     const entries = fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => U.compare(a.name, b.name));
     for (const entry of entries) {
       if (!prefix && entry.name === '.git') continue;
-      if (++visited > MAX_FILES) fail('inventory-unsupported');
       const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
+      if (excludedRoots.includes(relative)) continue;
+      if (++visited > MAX_FILES) fail('inventory-unsupported');
       const absolute = path.join(dir, entry.name);
       const stat = fs.lstatSync(absolute);
       if (stat.isDirectory()) {
@@ -102,7 +348,8 @@ function captureCandidate(root, baseline) {
     }
   }
   // Lifecycle owns text/eol/autocrlf conversion. A completeness walk above detects its skipped paths.
-  const stored = new Map(scanWorkspaceFiles(root).map(item => [item.path, item.bytes]));
+  const stored = new Map(convertWorkspaceFiles(root, raw.map(item => ({ path: item.path, bytes: item.raw })))
+    .map(item => [item.path, item.bytes]));
   const records = raw.map(item => {
     const converted = stored.get(item.path);
     if (!converted) fail('inventory-unsupported');
@@ -111,7 +358,7 @@ function captureCandidate(root, baseline) {
     return fileRecord(item.path, item.mode, converted);
   });
   for (const item of baseline.records) if (!stored.has(item.path)) records.push(fileRecord(item.path, '', Buffer.alloc(0), 'deleted'));
-  return records;
+  return { records, excludedRootStates };
 }
 const progressKeys = new Set(['status', 'state', 'evidence', 'loaded', 'loadedAt', 'updatedAt', 'createdAt', 'completedAt', 'timestamp', 'report', 'reports']);
 // Progress fields are excluded only at their defined record locations (top-level task/workflow, each
@@ -169,8 +416,20 @@ function produceDocSnapshot(input, dependencies = {}) {
     const baseline = captureBaseline(root, detached.baseline);
     const config = resolveDocsConfigCaptured(root, { activeHost: detached.activeHost });
     if (!['project', 'host'].includes(config.resolution.status) || config.capture.sources.some(s => s.presence === 'unreadable')) fail('config-unavailable');
-    const coverage = { kind: 'whole-project', excluded: ['.git'], scope: U.clone(detached.scope) };
-    const candidate = { records: captureCandidate(root, baseline), coverage };
+    const policy = guardedPolicy(root, baseline, config, detached);
+    const firstCapture = captureCandidate(root, baseline, policy?.roots || []);
+    const coverage = policy ? {
+      kind: 'project-with-dependency-artifact-exclusions',
+      policyVersion: POLICY_VERSION,
+      policySource: { path: PROJECT_CONFIG_PATH, baselineCommit: policy.baselineCommit, storedBytesDigest: policy.storedBytesDigest },
+      dependencyArtifactRoots: policy.roots,
+      excluded: ['.git', ...policy.roots],
+      excludedRootStates: firstCapture.excludedRootStates,
+      guardOutcomes: [...policy.guardOutcomes,
+        { guard: 'excluded-root-types', state: 'clear', reason: 'Each approved root is an in-workspace directory or absent.', roots: firstCapture.excludedRootStates }],
+      scope: U.clone(detached.scope)
+    } : { kind: 'whole-project', excluded: ['.git'], scope: U.clone(detached.scope) };
+    const candidate = { records: firstCapture.records, coverage };
     // Same owned config bytes must be the bytes covered by the working-tree capture.
     for (const source of config.capture.sources) {
       const file = candidate.records.find(r => r.path === source.path && r.presence === 'present');
@@ -189,18 +448,21 @@ function produceDocSnapshot(input, dependencies = {}) {
     const facts = derived.facts;
     const obligations = deriveDocObligations(facts);
     const derivationReasons = Object.fromEntries(obligations.map(o => [o.id, { applicability: o.applicability, reason: `captured facts derive ${o.capability}: ${o.applicability}`, factRefs: ['facts', ...(o.scope?.paths || []).map(p => `inventory:${p}`)] }]));
-    const again = captureCandidate(root, baseline);
+    const again = captureCandidate(root, baseline, policy?.roots || []);
     const configAgain = resolveDocsConfigCaptured(root, { activeHost: detached.activeHost });
+    const policyAgain = guardedPolicy(root, baseline, configAgain, detached);
     let finalContext;
     try { finalContext = contextFor(detached, originProvider); }
     catch { fail('snapshot-changed'); }
-    if (U.snapshotDigest('candidate', baseline, coverage, again) !== candidate.digest || U.configDigest(configAgain) !== config.digest
+    if (U.snapshotDigest('candidate', baseline, coverage, again.records) !== candidate.digest
+      || U.stable(again.excludedRootStates) !== U.stable(firstCapture.excludedRootStates)
+      || U.stable(policyAgain) !== U.stable(policy) || U.configDigest(configAgain) !== config.digest
       || U.stable(originContext) !== U.stable(finalContext)) fail('snapshot-changed');
     return { state: 'ready', snapshot: { identity, baseline, candidate, config, originContext, taskSemantics: planIdentity, facts, obligations, derivationReasons }, diagnostics: [] };
   } catch (error) {
     const codes = ['invalid-input', 'baseline-unavailable', 'inventory-incomplete', 'inventory-unsupported', 'snapshot-changed', 'config-unavailable', 'unsupported-prd-root', 'identity-mismatch', 'origin-unavailable', 'origin-untrusted'];
     const code = codes.includes(error.message) ? error.message : 'inventory-unsupported';
-    return { state: 'unavailable', snapshot: null, diagnostics: [U.diagnostic(code)] };
+    return { state: 'unavailable', snapshot: null, diagnostics: [U.diagnostic(code, error.reasonCode ? { reasonCode: error.reasonCode } : {})] };
   }
 }
 module.exports = { produceDocSnapshot };