docguard-cli 0.38.0 → 0.40.0

package/cli/repository-root.mjs

@@ -0,0 +1,159 @@
+/** Read-only repository-root guidance for commands launched in nested packages. */
+import { execFileSync } from 'node:child_process';
+import { existsSync, lstatSync, readFileSync } from 'node:fs';
+import { dirname, isAbsolute, join, posix, relative, resolve } from 'node:path';
+import { compileGlob } from './shared-ignore.mjs';
+
+const MAX_ANCESTORS = 32;
+const MAX_MANIFEST_BYTES = 256 * 1024;
+
+function regularFile(path) {
+  try {
+    const stat = lstatSync(path);
+    return stat.isFile() && !stat.isSymbolicLink() && stat.size <= MAX_MANIFEST_BYTES;
+  } catch { return false; }
+}
+
+function readRegular(path) {
+  if (!regularFile(path)) return null;
+  try { return readFileSync(path, 'utf8'); } catch { return null; }
+}
+
+function gitTopLevel(dir) {
+  try {
+    return resolve(execFileSync('git', ['-C', dir, 'rev-parse', '--show-toplevel'], {
+      encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+      env: { ...process.env, GIT_CONFIG_NOSYSTEM: '1', GIT_TERMINAL_PROMPT: '0' },
+      timeout: 3000,
+    }).trim());
+  } catch { return null; }
+}
+
+function within(parent, child) {
+  const rel = relative(parent, child);
+  return rel === '' || (!isAbsolute(rel) && rel !== '..' && !rel.startsWith(`..${process.platform === 'win32' ? '\\' : '/'}`));
+}
+
+function normalizePattern(pattern) {
+  const value = String(pattern).trim().replaceAll('\\', '/').replace(/^\.\//, '');
+  return posix.normalize(value).replace(/^\.\//, '').replace(/\/$/, '');
+}
+
+function npmPatterns(root) {
+  const content = readRegular(join(root, 'package.json'));
+  if (content == null) return [];
+  try {
+    const value = JSON.parse(content).workspaces;
+    const patterns = Array.isArray(value) ? value : value?.packages;
+    return Array.isArray(patterns) ? patterns.filter(item => typeof item === 'string') : [];
+  } catch { return []; }
+}
+
+function pnpmPatterns(root) {
+  const content = readRegular(join(root, 'pnpm-workspace.yaml'));
+  if (content == null) return [];
+  const patterns = [];
+  let packages = false;
+  for (const line of content.split(/\r?\n/)) {
+    if (/^packages\s*:/.test(line)) { packages = true; continue; }
+    if (!packages) continue;
+    if (/^[^\s#][^:]*\s*:/.test(line)) break;
+    const match = line.match(/^\s*-\s*(?:'([^']*)'|"([^"]*)"|([^#]*?))\s*(?:#.*)?$/);
+    const value = match && (match[1] ?? match[2] ?? match[3])?.trim();
+    if (value) patterns.push(value);
+  }
+  return patterns;
+}
+
+function matchesWorkspace(patterns, packagePath) {
+  const normalized = patterns.map(normalizePattern).filter(Boolean);
+  const positives = normalized.filter(pattern => !pattern.startsWith('!'));
+  const negatives = normalized.filter(pattern => pattern.startsWith('!')).map(pattern => pattern.slice(1));
+  const matches = (pattern) => {
+    try { return compileGlob(pattern).test(packagePath); } catch { return false; }
+  };
+  return positives.some(matches) && !negatives.some(matches);
+}
+
+function workspaceOwner(root, selected) {
+  const hasPnpmWorkspace = regularFile(join(root, 'pnpm-workspace.yaml'));
+  const pnpm = pnpmPatterns(root);
+  const npm = hasPnpmWorkspace ? [] : npmPatterns(root);
+  const patterns = hasPnpmWorkspace ? pnpm : npm;
+  if (patterns.length === 0) return null;
+
+  let packageDir = selected;
+  while (within(root, packageDir) && packageDir !== root) {
+    if (regularFile(join(packageDir, 'package.json'))) {
+      const packagePath = relative(root, packageDir).replaceAll('\\', '/');
+      if (matchesWorkspace(patterns, packagePath)) {
+        return {
+          reason: hasPnpmWorkspace ? 'pnpm_workspace' : 'npm_workspace',
+          evidence: hasPnpmWorkspace ? 'pnpm-workspace.yaml#packages' : 'package.json#workspaces',
+          packagePath,
+        };
+      }
+    }
+    const parent = dirname(packageDir);
+    if (parent === packageDir) break;
+    packageDir = parent;
+  }
+  return null;
+}
+
+function shellQuote(value) {
+  const text = String(value);
+  if (/^[A-Za-z0-9_./:@%+=,-]+$/.test(text)) return text;
+  return `'${text.replaceAll("'", `'"'"'`)}'`;
+}
+
+/**
+ * Find the nearest ancestor with explicit DocGuard or workspace ownership.
+ * The selected directory is never changed.
+ * @implements docguard.language-repository-coverage#FR-012
+ * @implements docguard.language-repository-coverage#FR-013
+ * @implements docguard.language-repository-coverage#FR-014
+ */
+export function detectRepositoryRootGuidance(selectedDir, { explicitDir = false, argv = [] } = {}) {
+  const selected = resolve(selectedDir);
+  if (explicitDir || existsSync(join(selected, '.docguard.json'))) return null;
+  const gitRoot = gitTopLevel(selected);
+  let current = dirname(selected);
+  for (let depth = 1; depth <= MAX_ANCESTORS && current !== dirname(current); depth++) {
+    // A nested repository is an independent boundary unless ownership is
+    // declared inside that same working tree.
+    if (gitRoot && !within(gitRoot, current)) break;
+    let ownership = regularFile(join(current, '.docguard.json'))
+      ? { reason: 'ancestor_docguard_config', evidence: '.docguard.json', packagePath: relative(current, selected).replaceAll('\\', '/') }
+      : null;
+    ownership ||= workspaceOwner(current, selected);
+    if (ownership) {
+      const rerun = ['docguard', ...argv.map(shellQuote), '--dir', shellQuote(current)].join(' ');
+      return {
+        selectedDir: selected,
+        suggestedDir: current,
+        reason: ownership.reason,
+        evidence: ownership.evidence,
+        packagePath: ownership.packagePath,
+        gitRoot,
+        rerun,
+        automaticScopeChange: false,
+      };
+    }
+    current = dirname(current);
+  }
+  return null;
+}
+
+export function renderRepositoryRootGuidance(guidance, { machine = false } = {}) {
+  if (!guidance) return '';
+  if (machine) return JSON.stringify({
+    type: 'docguard.repository-root-guidance',
+    repositoryRootGuidance: guidance,
+  });
+  return [
+    `DocGuard is checking ${guidance.selectedDir}.`,
+    `${guidance.suggestedDir} appears to govern this package via ${guidance.evidence}; the scan scope was not changed.`,
+    `Re-run for repository scope: ${guidance.rerun}`,
+  ].join('\n');
+}

package/cli/scanners/py-ast.mjs

@@ -13,6 +13,8 @@
  * (or `python`) isn't on PATH, or the subprocess errors, every entry point here
  * returns `null` and the callers transparently fall back to their regex (beta)
  * tier. Python parsing never becomes load-bearing for the CLI to run.
+ * @implements docguard.language-repository-coverage#FR-001
+ * @implements docguard.language-repository-coverage#FR-004
  */
 import { spawnSync } from 'node:child_process';
 
@@ -147,6 +149,37 @@ def fields_from_class(cls):
                         rels.append(rel)
     return pyd, orm, rels
 
+def imports_from_tree(tree):
+    imports = []
+    dynamic = False
+    path_mutation = False
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for name in node.names:
+                imports.append({"kind": "import", "module": name.name, "level": 0, "names": []})
+        elif isinstance(node, ast.ImportFrom):
+            imports.append({
+                "kind": "from", "module": node.module or "", "level": node.level or 0,
+                "names": [name.name for name in node.names]
+            })
+        elif isinstance(node, ast.Call):
+            fn = node.func
+            if isinstance(fn, ast.Name) and fn.id == "__import__":
+                dynamic = True
+            elif isinstance(fn, ast.Attribute):
+                if isinstance(fn.value, ast.Name) and fn.value.id == "importlib" and fn.attr == "import_module":
+                    dynamic = True
+                if fn.attr in {"append", "insert", "extend"} and isinstance(fn.value, ast.Attribute):
+                    if isinstance(fn.value.value, ast.Name) and fn.value.value.id == "sys" and fn.value.attr == "path":
+                        path_mutation = True
+        elif isinstance(node, (ast.Assign, ast.AugAssign)):
+            targets = node.targets if isinstance(node, ast.Assign) else [node.target]
+            for target in targets:
+                if isinstance(target, ast.Attribute) and isinstance(target.value, ast.Name):
+                    if target.value.id == "sys" and target.attr == "path":
+                        path_mutation = True
+    return imports, dynamic, path_mutation
+
 results = []
 for path in sys.stdin.read().splitlines():
     path = path.strip()
@@ -169,7 +202,11 @@ for path in sys.stdin.read().splitlines():
                 schemas.append({"name": node.name, "fields": pyd, "kind": "pydantic", "rels": rels})
             elif any(b in ORM_BASES for b in bn) and orm:
                 schemas.append({"name": node.name, "fields": orm, "kind": "sqlalchemy", "rels": rels})
-    results.append({"file": path, "ok": True, "routes": routes, "schemas": schemas})
+    imports, dynamic_imports, path_mutation = imports_from_tree(tree)
+    results.append({
+        "file": path, "ok": True, "routes": routes, "schemas": schemas,
+        "imports": imports, "dynamicImports": dynamic_imports, "pathMutation": path_mutation
+    })
 
 sys.stdout.write(json.dumps(results))
 `;
@@ -178,7 +215,7 @@ sys.stdout.write(json.dumps(results))
  * Parse a batch of Python files in ONE python3 subprocess.
  *
  * @param {string[]} filePaths - absolute paths to .py files
- * @returns {Object<string, {ok:boolean, routes?, schemas?}>|null}
+ * @returns {Object<string, {ok:boolean, routes?, schemas?, imports?, dynamicImports?, pathMutation?}>|null}
  *   A map keyed by the input path, or `null` when Python is unavailable / the
  *   subprocess failed / output was unparseable (caller falls back to regex).
  *   An empty input returns `{}` (nothing to do, but Python IS available).

package/cli/scanners/task-context.mjs

@@ -0,0 +1,312 @@
+/**
+ * Deterministic task-specific context selection.
+ *
+ * @implements docguard.task-specific-agent-context#FR-001
+ * @implements docguard.task-specific-agent-context#FR-002
+ * @implements docguard.task-specific-agent-context#FR-003
+ * @implements docguard.task-specific-agent-context#FR-004
+ * @implements docguard.task-specific-agent-context#FR-005
+ * @implements docguard.task-specific-agent-context#FR-006
+ * @implements docguard.task-specific-agent-context#FR-007
+ * @implements docguard.task-specific-agent-context#FR-008
+ * @implements docguard.task-specific-agent-context#FR-009
+ */
+
+import { basename } from 'node:path';
+import { citedSources, contentHash, createEvidenceReader, evidenceDocs, gitEvidence } from './semantic-claims.mjs';
+import { compileGlob } from '../shared-ignore.mjs';
+
+const LIMITS = Object.freeze({
+  taskChars: 2000,
+  documents: 32,
+  chunks: 256,
+  selectedExcerpts: 6,
+  linesPerExcerpt: 16,
+  totalChars: 6000,
+  pointers: 8,
+});
+const SCORE_THRESHOLD = 12;
+const STOP = new Set('a an and are as at be by can change cli create do docguard for from has have how i improve in into is it make mjs of on or preserve should that the this to update use want when with you your'.split(' '));
+const FINDING_RE = /\b[A-Z]{2,5}\d{3}\b/g;
+const QUALIFIED_REQ_RE = /\b[a-z0-9][a-z0-9._/-]{2,127}#(?:FR|SC|NFR)-\d{3}\b/gi;
+const REQUIREMENT_RE = /\b(?:FR|SC|NFR)-\d{3}\b/g;
+
+function normalizeTask(task) {
+  if (typeof task !== 'string') throw new Error('Task context requires a text task.');
+  const normalized = task.replace(/\0/g, '').replace(/\s+/g, ' ').trim();
+  if (!normalized) throw new Error('Task context requires a non-empty task.');
+  if (normalized.length > LIMITS.taskChars) throw new Error(`Task context is limited to ${LIMITS.taskChars} characters.`);
+  return normalized;
+}
+
+function words(text) {
+  return [...new Set((String(text).toLowerCase().match(/[a-z][a-z0-9_-]{2,}/g) || [])
+    .filter(word => !STOP.has(word)))].sort();
+}
+
+function exactTokens(text) {
+  return [...new Set(String(text).match(/[A-Za-z_$][A-Za-z0-9_$.-]{2,}|(?:[^\s]+\/)+[^\s]+/g) || [])]
+    .filter(token => !STOP.has(token.toLowerCase())
+      && (/[._/$-]/.test(token) || /[A-Z]/.test(token.slice(1)) || /\d/.test(token)))
+    .sort();
+}
+
+function ignored(path, config) {
+  for (const pattern of config.ignore || []) {
+    try { if (compileGlob(pattern).test(path)) return true; } catch { /* invalid config is handled elsewhere */ }
+  }
+  return false;
+}
+
+function safeRegistry(read) {
+  const loaded = read('.docguard-specs.json');
+  if (loaded.content == null) return { active: [], excluded: 0, issue: 'spec-registry-unavailable' };
+  try {
+    const registry = JSON.parse(loaded.content);
+    if (registry.schemaVersion !== 2 || !Array.isArray(registry.specs)) throw new Error('schema');
+    const active = [];
+    let excluded = 0;
+    for (const entry of registry.specs) {
+      const lifecycle = entry?.reviewed?.lifecycle;
+      if (lifecycle?.context !== 'current' || lifecycle?.approval !== 'approved') { excluded++; continue; }
+      const artifact = entry?.observed?.artifacts?.find(item => item.path === entry.path);
+      const spec = read(entry.path);
+      if (!artifact?.digest || spec.content == null || contentHash(spec.content) !== artifact.digest) { excluded++; continue; }
+      active.push(entry);
+    }
+    return { active: active.sort((a, b) => a.specId.localeCompare(b.specId)), excluded, issue: null };
+  } catch {
+    return { active: [], excluded: 0, issue: 'spec-registry-invalid' };
+  }
+}
+
+function chunks(path, kind, content, specId = null) {
+  const lines = content.split('\n');
+  const headings = [];
+  for (let index = 0; index < lines.length; index++) {
+    const match = lines[index].match(/^#{1,4}\s+(.+)$/);
+    if (match) headings.push({ index, heading: match[1].trim() });
+  }
+  if (!headings.length || headings[0].index !== 0) headings.unshift({ index: 0, heading: basename(path) });
+  const ranges = [];
+  for (let h = 0; h < headings.length; h++) {
+    const sectionStart = headings[h].index;
+    const sectionEnd = headings[h + 1]?.index ?? lines.length;
+    if (/^implementation outcomes$/i.test(headings[h].heading)) continue;
+    for (let start = sectionStart; start < sectionEnd; start += LIMITS.linesPerExcerpt) {
+      const end = Math.min(sectionEnd, start + LIMITS.linesPerExcerpt);
+      ranges.push({ path, kind, specId, heading: headings[h].heading, startLine: start + 1, endLine: end, content: lines.slice(start, end).join('\n') });
+    }
+  }
+  return ranges;
+}
+
+function scoreChunk(chunk, task) {
+  const lower = chunk.content.toLowerCase();
+  const heading = chunk.heading.toLowerCase();
+  const reasons = [];
+  let score = 0;
+  if (task.paths.includes(chunk.path)) { score += 120; reasons.push('exact-path'); }
+  for (const req of task.qualifiedRequirements) {
+    const split = req.lastIndexOf('#');
+    const scope = req.slice(0, split).toLowerCase();
+    const id = req.slice(split + 1).toUpperCase();
+    if (lower.includes(req.toLowerCase()) || (chunk.specId?.toLowerCase() === scope && chunk.content.includes(id))) {
+      score += 100;
+      reasons.push(`qualified-requirement:${req}`);
+    }
+  }
+  for (const code of task.findingCodes) {
+    if (chunk.content.includes(code)) { score += 80; reasons.push(`finding-code:${code}`); }
+  }
+  for (const token of task.exact) {
+    if (chunk.content.includes(token)) { score += 12; reasons.push(`exact-token:${token}`); }
+  }
+  for (const word of task.words) {
+    if (lower.includes(word)) {
+      score += heading.includes(word) ? 8 : 4;
+      reasons.push(`${heading.includes(word) ? 'heading' : 'term'}:${word}`);
+    }
+  }
+  const pathTerms = words(chunk.path);
+  const pathOverlap = pathTerms.filter(word => task.words.includes(word));
+  if (pathOverlap.length) {
+    score += 8 * pathOverlap.length;
+    reasons.push(...pathOverlap.map(word => `path-term:${word}`));
+  }
+  return { score, reasons: [...new Set(reasons)].sort() };
+}
+
+function taskSignals(normalized) {
+  const paths = [...new Set((normalized.match(/(?:^|\s|[`'"(])([^\s`'"()]+\/[A-Za-z0-9_.\/-]+)(?=$|\s|[`'"),.])/g) || [])
+    .map(value => value.trim().replace(/^[`'"(]+|[`'"),.]+$/g, '')))];
+  return {
+    normalized,
+    words: words(normalized),
+    exact: exactTokens(normalized),
+    paths,
+    findingCodes: [...new Set(normalized.match(FINDING_RE) || [])].sort(),
+    qualifiedRequirements: [...new Set(normalized.match(QUALIFIED_REQ_RE) || [])].sort(),
+  };
+}
+
+function requirementIds(chunk) {
+  const ids = [...new Set(chunk.content.match(REQUIREMENT_RE) || [])];
+  return chunk.specId ? ids.map(id => `${chunk.specId}#${id}`) : [];
+}
+
+function pointerRecords(selected, registry, read, task) {
+  const candidates = new Map();
+  const push = (path, kind, reason, requirement = null, priority = 3) => {
+    if (!path) return;
+    const result = read(path);
+    if (result.evidence.status !== 'snapshot') return;
+    const existing = candidates.get(path);
+    if (existing) {
+      if (!existing.reasons.includes(reason)) existing.reasons.push(reason);
+      if (requirement && !existing.requirements.includes(requirement)) existing.requirements.push(requirement);
+      if (priority < existing.priority) { existing.priority = priority; existing.kind = kind; }
+      return;
+    }
+    candidates.set(path, { path, kind, requirements: requirement ? [requirement] : [], reasons: [reason], hash: result.evidence.hash, priority });
+  };
+  for (const path of task.paths) push(path, 'task-path', 'named-by-task', null, 0);
+  const explicitRequirements = new Set(task.qualifiedRequirements.map(value => value.toLowerCase()));
+  for (const excerpt of selected) {
+    for (const path of citedSources(excerpt.content)) {
+      const clean = path.replace(/:\d+(?:-\d+)?$/, '');
+      const relevant = task.paths.includes(clean) || words(clean).some(word => task.words.includes(word));
+      if (relevant) push(clean, 'cited-source', `cited-by:${excerpt.path}`, null, 3);
+    }
+    for (const identity of requirementIds(excerpt)) {
+      if (explicitRequirements.size && !explicitRequirements.has(identity.toLowerCase())) continue;
+      const split = identity.lastIndexOf('#');
+      const specId = identity.slice(0, split);
+      const id = identity.slice(split + 1);
+      const spec = registry.find(item => item.specId === specId);
+      for (const evidence of spec?.observed?.implementationEvidence || []) {
+        if (evidence.requirementId === id) push(evidence.file, 'implementation', `implements:${identity}`, identity, explicitRequirements.size ? 1 : 2);
+      }
+      for (const evidence of spec?.observed?.testEvidence || []) {
+        if (evidence.requirementId === id) push(evidence.file, 'test', `tests:${identity}`, identity, explicitRequirements.size ? 1 : 2);
+      }
+    }
+  }
+  return [...candidates.values()]
+    .sort((a, b) => a.priority - b.priority || a.path.localeCompare(b.path))
+    .slice(0, LIMITS.pointers)
+    .map(({ priority: _priority, ...item }) => ({
+      ...item,
+      requirements: item.requirements.sort(),
+      reasons: item.reasons.sort(),
+    }));
+}
+
+function removeContent(excerpt) {
+  const { content: _content, ...rest } = excerpt;
+  return rest;
+}
+
+/** Build a bounded packet or an honest abstention; never writes repository state. */
+export function buildTaskContextPacket(projectDir, config = {}, taskText) {
+  const normalized = normalizeTask(taskText);
+  const signal = taskSignals(normalized);
+  const read = createEvidenceReader(projectDir);
+  const lifecycle = safeRegistry(read);
+  const docPaths = evidenceDocs(projectDir, config).filter(path => !ignored(path, config)).slice(0, LIMITS.documents);
+  const safeCanonicalDocs = [];
+  const candidates = [];
+  const inventory = [];
+  const add = (path, kind, specId = null) => {
+    if (inventory.includes(path) || inventory.length >= LIMITS.documents) return false;
+    const result = read(path);
+    if (result.content == null) return false;
+    inventory.push(path);
+    candidates.push(...chunks(path, kind, result.content, specId));
+    return true;
+  };
+  for (const path of docPaths) if (add(path, 'canonical')) safeCanonicalDocs.push(path);
+  for (const spec of lifecycle.active) add(spec.path, 'active-spec', spec.specId);
+  if (!ignored('AGENTS.md', config)) add('AGENTS.md', 'project-rules');
+
+  const ranked = candidates.slice(0, LIMITS.chunks).map(chunk => ({ ...chunk, ...scoreChunk(chunk, signal) }))
+    .filter(chunk => chunk.score >= SCORE_THRESHOLD)
+    .sort((a, b) => b.score - a.score || a.path.localeCompare(b.path) || a.startLine - b.startLine);
+  const selected = [];
+  let chars = 0;
+  let truncated = candidates.length > LIMITS.chunks;
+  for (const candidate of ranked) {
+    if (selected.length >= LIMITS.selectedExcerpts) { truncated = true; break; }
+    if (selected.filter(item => item.path === candidate.path).length >= 2) continue;
+    if (selected.some(item => item.path === candidate.path && !(candidate.endLine < item.startLine || candidate.startLine > item.endLine))) continue;
+    const remaining = LIMITS.totalChars - chars;
+    if (remaining <= 0) { truncated = true; break; }
+    const content = candidate.content.length > remaining ? candidate.content.slice(0, remaining) : candidate.content;
+    if (content.length < candidate.content.length) truncated = true;
+    const file = read(candidate.path).evidence;
+    selected.push({
+      path: candidate.path,
+      kind: candidate.kind,
+      specId: candidate.specId,
+      heading: candidate.heading,
+      startLine: candidate.startLine,
+      endLine: candidate.endLine,
+      fileHash: file.hash,
+      excerptHash: contentHash(content),
+      score: candidate.score,
+      reasons: candidate.reasons,
+      content,
+    });
+    chars += content.length;
+  }
+  if (ranked.length > selected.length) truncated = true;
+
+  const status = selected.length ? 'targeted' : 'abstained';
+  const limitations = [
+    'Selection is deterministic retrieval, not proof that selected prose or omitted files are correct.',
+    'Agents may inspect additional repository evidence before editing.',
+  ];
+  if (lifecycle.issue) limitations.push(lifecycle.issue);
+  if (truncated) limitations.push('selection-budget-reached');
+  if (status === 'abstained') limitations.push('no-candidate-met-relevance-threshold');
+  const pointers = status === 'targeted' ? pointerRecords(selected, lifecycle.active, read, signal) : [];
+  const publicExcerpts = status === 'targeted' ? selected : [];
+  return {
+    schemaVersion: 1,
+    kind: 'docguard.task-context',
+    task: { digest: contentHash(normalized), characters: normalized.length },
+    provenance: { git: gitEvidence(projectDir), registry: lifecycle.issue ? 'unavailable' : 'snapshot' },
+    assurance: { scope: 'retrieval-only', factualAccuracy: null, verification: 'unverified' },
+    selection: {
+      status,
+      threshold: SCORE_THRESHOLD,
+      candidatesConsidered: Math.min(candidates.length, LIMITS.chunks),
+      selectedExcerpts: publicExcerpts.length,
+      omittedCandidates: Math.max(0, ranked.length - publicExcerpts.length),
+      excludedLifecycleDocuments: lifecycle.excluded,
+      limits: LIMITS,
+      truncated,
+    },
+    excerpts: publicExcerpts,
+    pointers,
+    verification: [
+      { command: 'docguard guard --format json', purpose: 'Resolve deterministic errors and triage warnings.' },
+      ...(pointers.some(item => item.kind === 'test')
+        ? [{ command: 'Run the repository tests that cover the selected test pointers.', purpose: 'Verify task behavior and existing behavior.' }]
+        : []),
+    ],
+    navigation: {
+      canonicalDocs: safeCanonicalDocs.sort(),
+      activeSpecs: lifecycle.active.map(spec => ({ specId: spec.specId, path: spec.path })),
+    },
+    limitations,
+    coreDigest: contentHash(JSON.stringify({
+      task: contentHash(normalized), status,
+      excerpts: publicExcerpts.map(removeContent), pointers,
+      inventory: inventory.sort(), limitations,
+    })),
+  };
+}
+
+export const TASK_CONTEXT_LIMITS = LIMITS;
+export const TASK_CONTEXT_THRESHOLD = SCORE_THRESHOLD;

package/cli/shared-doc-roles.mjs

@@ -1,5 +1,5 @@
 /** Explicit document roles let existing repository layouts serve as canonical input. */
-import { lstatSync } from 'node:fs';
+import { existsSync, lstatSync, readFileSync } from 'node:fs';
 import { resolve, isAbsolute, join } from 'node:path';
 export const DOC_ROLES = Object.freeze({
   architecture: 'docs-canonical/ARCHITECTURE.md', dataModel: 'docs-canonical/DATA-MODEL.md',
@@ -52,6 +52,49 @@ export function remapDocPath(config, path) {
   return role ? docRolePath(config, role) : path;
 }
 
+export function mappedRolesForPath(config = {}, path) {
+  const target = String(path).replace(/\\/g, '/').replace(/^\.\//, '');
+  return Object.keys(DOC_ROLES).filter(role => {
+    const configured = config.docs?.roles?.[role];
+    return configured !== undefined && docRolePath(config, role) === target && target !== DOC_ROLES[role];
+  });
+}
+
+export function isMappedDocPath(config = {}, path) {
+  return mappedRolesForPath(config, path).length > 0;
+}
+
+/**
+ * Authorize a whole-document write to custom role targets. New files are safe;
+ * existing files must explicitly grant full ownership and one file cannot be
+ * the whole-document target of several roles.
+ * @implements docguard.language-repository-coverage#FR-010
+ * @implements docguard.language-repository-coverage#FR-011
+ */
+export function assertMappedFullDocumentWrites(projectDir, config = {}, roles = Object.keys(DOC_ROLES)) {
+  const selected = roles.filter(role => Object.hasOwn(DOC_ROLES, role) && config.docs?.roles?.[role] !== undefined
+    && docRolePath(config, role) !== DOC_ROLES[role]);
+  const paths = new Map();
+  for (const role of selected) {
+    const rel = docRolePath(config, role);
+    if (!paths.has(rel)) paths.set(rel, []);
+    paths.get(rel).push(role);
+  }
+  for (const [rel, owners] of paths) {
+    const allOwners = mappedRolesForPath(config, rel);
+    if (allOwners.length > 1) {
+      throw new Error(`Mapped document ${rel} serves multiple roles (${allOwners.join(', ')}); whole-document generation is unavailable. Use unique source=code sections instead.`);
+    }
+    const role = owners[0];
+    const full = resolveDocRole(projectDir, config, role);
+    if (!existsSync(full)) continue;
+    const content = readFileSync(full, 'utf8');
+    if (!/^[ \t]*<!--\s*docguard:generated\s+true\s*-->[ \t]*$/mi.test(content)) {
+      throw new Error(`Mapped document ${rel} is not fully owned by DocGuard. Add unique source=code sections for bounded writes; --force cannot overwrite its prose.`);
+    }
+  }
+}
+
 export function assertDefaultDocWrites(config) {
   if (Object.entries(config.docs?.roles || {}).some(([role, path]) => path !== DOC_ROLES[role])) {
     throw new Error('Custom docs.roles currently support validation and read-only planning. Automatic document generation/repair is unavailable for mapped layouts; review and edit the existing documents directly.');