harness-everything 0.38.0 → 0.40.0

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

@@ -0,0 +1,280 @@
+'use strict';
+
+const crypto = require('crypto');
+
+// Both layouts are shipped by plugin:sync. Resolve modules at import, never during a decision.
+function runtimeModule(name) {
+  try { return require('../../../harness-everything/scripts/' + name); }
+  catch (error) {
+    if (error.code !== 'MODULE_NOT_FOUND' || !error.message.startsWith("Cannot find module '../../../harness-everything/scripts/" + name + "'")) throw error;
+    return require('../../../skills/harness-everything/scripts/' + name);
+  }
+}
+const { checkDocObligations } = runtimeModule('doc-evidence.js');
+const { deriveDocFacts, deriveDocObligations } = runtimeModule('doc-obligations.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;
+const bytes = value => Buffer.isBuffer(value) ? Buffer.from(value)
+  : value && value.type === 'Buffer' && Array.isArray(value.data) ? Buffer.from(value.data)
+    : (() => { throw new Error('inventory-unsupported'); })();
+function canonical(value) {
+  if (Buffer.isBuffer(value)) return { type: 'Buffer', data: [...value] };
+  if (Array.isArray(value)) return value.map(canonical);
+  if (!record(value)) return value;
+  return Object.fromEntries(Object.keys(value).sort(compare).map(key => [key, canonical(value[key])]));
+}
+const stable = value => JSON.stringify(canonical(value));
+const clone = value => JSON.parse(stable(value));
+const sha = value => crypto.createHash('sha256').update(value).digest('hex');
+const frame = value => { const b = Buffer.isBuffer(value) ? value : Buffer.from(String(value)); return Buffer.concat([Buffer.from(b.length + ':'), b]); };
+const hashFrames = values => sha(Buffer.concat(values.map(frame)));
+const structuredDigest = (domain, value) => hashFrames([domain, stable(value)]);
+const identityFields = ['workspaceId', 'sessionId', 'workflowId', 'workflowRevision', 'taskId', 'taskScopeDigest', 'baselineDigest', 'candidateDigest', 'configDigest', 'prdRoot'];
+const validIdentity = id => record(id) && ['workspaceId', 'sessionId', 'workflowId', 'taskId'].every(key => text(id[key]))
+  && Number.isInteger(id.workflowRevision) && id.workflowRevision >= 0 && id.prdRoot === 'docs/prd/'
+  && ['taskScopeDigest', 'baselineDigest', 'candidateDigest', 'configDigest'].every(key => /^[a-f0-9]{64}$/.test(id[key] || ''));
+const sameIdentity = (a, b) => validIdentity(a) && validIdentity(b) && identityFields.every(key => a[key] === b[key]);
+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 });
+// 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.
+const CODE_EXTENSION = /\.(?:c|cc|cpp|h|hpp|m|mm|go|rs|java|kt|swift|js|jsx|mjs|cjs|ts|tsx|py|rb|php|sh|ps1|sql)$/i;
+const TEST_PATH = /(?:^|\/)(?:test|tests|__tests__|spec)(?:\/|$)|(?:^|\/)[^/]*(?:\.test|\.spec)\.[^/]+$/i;
+// Glob semantics of the derive contract: '**' crosses directories, '*' stays inside one segment.
+function globToRegExp(glob) {
+  const source = String(glob).replace(/\\/g, '/').replace(/^\.\//, '');
+  let pattern = '^';
+  for (let index = 0; index < source.length; index++) {
+    const char = source[index];
+    if (char === '*' && source[index + 1] === '*') {
+      if (source[index + 2] === '/') { pattern += '(?:.*/)?'; index += 2; }
+      else { pattern += '.*'; index += 1; }
+    } else if (char === '*') pattern += '[^/]*';
+    else pattern += char.replace(/[|\\{}()[\]^$+?.]/g, '\\$&');
+  }
+  return new RegExp(`${pattern}$`);
+}
+// Semantic relevance of a path under the derive contract; null means the path cannot change applicability.
+function semanticRelevance(path, config) {
+  const governed = Array.isArray(config && config.governed) ? config.governed : [];
+  const legacy = Array.isArray(config && config.legacy) ? config.legacy : [];
+  const derived = Array.isArray(config && config.derived) ? config.derived : [];
+  const matches = globs => globs.some(glob => typeof glob === 'string' && globToRegExp(glob).test(path));
+  if (governed.some(entry => entry && typeof entry.path === 'string' && matches([entry.path]))) return 'document';
+  if (matches(legacy)) return 'document';
+  if (derived.some(entry => entry && typeof entry.path === 'string'
+    && (matches([entry.path]) || matches([entry.source, ...(Array.isArray(entry.sources) ? entry.sources : [])])))) return 'derived';
+  if (CODE_EXTENSION.test(path)) return 'code';
+  if (TEST_PATH.test(path)) return 'test';
+  return null;
+}
+// The derive contract reads the frontmatter of every captured file, so a record that opens a frontmatter
+// block is observed by it even when the record's bytes cannot be decoded. Match TextDecoder's BOM handling.
+function opensFrontmatter(stored) {
+  return stored.subarray(0, 11).toString('utf8').replace(/^\uFEFF/, '').split('\n')[0].replace(/\r$/, '') === '---';
+}
+// A whole-project inventory keeps every stored byte in the identity framing. Semantic derivation converts only
+// records it can decode; a record the derive contract can observe (governed/derived/code/test path or a
+// frontmatter document) fails closed instead of being silently dropped.
+function deriveFiles(records, config, options = {}) {
+  const files = {};
+  for (const item of records || []) {
+    if (!record(item) || item.presence !== 'present') continue;
+    // The unchanged derive API uses ordinary object maps, whose __proto__ setter drops this path.
+    if (item.path === '__proto__') throw codedError('inventory-unsupported');
+    const stored = bytes(item.storedBytes);
+    if (options.strict && (item.digest !== sha(stored) || item.type !== 'file' || !['100644', '100755'].includes(item.mode))) {
+      throw codedError('invalid-input');
+    }
+    let content;
+    try { content = new TextDecoder('utf-8', { fatal: true }).decode(stored); }
+    catch {
+      if (semanticRelevance(item.path, config) || opensFrontmatter(stored)) throw codedError('inventory-unsupported');
+      continue;
+    }
+    files[item.path] = content;
+  }
+  return files;
+}
+const identityTupleFields = ['workspaceId', 'sessionId', 'workflowId', 'workflowRevision', 'taskId'];
+// The captured origin context is the snapshot's only origin-correlated identity: every field it carries must be
+// the identity the snapshot claims, the captured plan must agree with both, and the captured host must be the
+// host the captured config was selected for (PR #353 review P1).
+function originBound(snapshot) {
+  const context = snapshot.originContext;
+  const id = snapshot.identity;
+  if (!record(context) || !validIdentity(id)) return false;
+  for (const key of identityTupleFields) if (context[key] !== id[key]) return false;
+  const plan = snapshot.taskSemantics;
+  if (!record(plan) || !record(plan.workflow) || !record(plan.task)) return false;
+  if (plan.workflow.workflowId !== id.workflowId || plan.workflow.workflowRevision !== id.workflowRevision
+    || plan.workflow.sessionId !== id.sessionId || plan.task.taskId !== id.taskId) return false;
+  if (plan.prdRoot !== id.prdRoot || plan.configDigest !== id.configDigest) return false;
+  const captured = context.activeHost === undefined || context.activeHost === null ? null : context.activeHost;
+  const selected = snapshot.config && snapshot.config.capture ? snapshot.config.capture.activeHost : null;
+  const chosen = selected === undefined || selected === null ? null : selected;
+  if (captured === null && chosen === null) return true;
+  return stable(captured) === stable(chosen);
+}
+// The captured config bytes must be the bytes the captured inventory holds for the same path; otherwise the
+// config digest binds a parsed value that the whole-project capture contradicts (the producer's own rule).
+function configBytesBound(snapshot) {
+  const sources = snapshot.config && snapshot.config.capture ? snapshot.config.capture.sources : null;
+  if (!Array.isArray(sources)) return false;
+  const records = Array.isArray(snapshot.candidate.records) ? snapshot.candidate.records : [];
+  for (const source of sources) {
+    const file = records.find(item => item && item.path === source.path && item.presence === 'present');
+    if (source.presence === 'present' ? !file || !bytes(source.bytes).equals(bytes(file.storedBytes)) : Boolean(file)) return false;
+  }
+  return true;
+}
+function snapshotDigest(kind, baseline, coverage, records) {
+  const fields = ['doc-snapshot-v1', kind, baseline.commit, baseline.treeRef, structuredDigest('doc-coverage-v1', coverage), String(records.length)];
+  for (const item of [...records].sort(pathCompare)) fields.push(item.path, item.presence, item.type, item.mode, bytes(item.storedBytes));
+  return hashFrames(fields);
+}
+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)];
+  for (const source of sources) fields.push(source.path, source.presence, bytes(source.bytes));
+  return hashFrames(fields);
+}
+function validateSnapshot(snapshot) {
+  const errors = [];
+  try {
+    if (!validIdentity(snapshot.identity) || !record(snapshot.facts) || !Array.isArray(snapshot.obligations)) throw new Error('invalid-input');
+    // 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)
+      || context.baseline.commit !== snapshot.baseline.commit || context.baseline.root !== context.workspaceRoot) {
+      errors.push(diagnostic('baseline-unavailable'));
+    }
+    // The captured origin identity, the captured plan and the selected host must be the identity the snapshot
+    // claims; otherwise the provider half and the event half of the trust contract stay disconnected.
+    if (!originBound(snapshot)) errors.push(diagnostic('identity-mismatch'));
+    if (snapshotDigest('baseline', snapshot.baseline, snapshot.candidate.coverage, snapshot.baseline.records) !== snapshot.identity.baselineDigest
+      || snapshotDigest('candidate', snapshot.baseline, snapshot.candidate.coverage, snapshot.candidate.records) !== snapshot.identity.candidateDigest
+      || snapshot.baseline.digest !== snapshot.identity.baselineDigest || snapshot.candidate.digest !== snapshot.identity.candidateDigest) errors.push(diagnostic('identity-mismatch'));
+    if (configDigest(snapshot.config) !== snapshot.identity.configDigest || snapshot.config.digest !== snapshot.identity.configDigest) errors.push(diagnostic('config-capture-mismatch'));
+    if (!configBytesBound(snapshot)) errors.push(diagnostic('config-capture-mismatch'));
+    if (structuredDigest('doc-task-scope-v1', snapshot.taskSemantics) !== snapshot.identity.taskScopeDigest) errors.push(diagnostic('identity-mismatch'));
+    const config = snapshot.config.resolution.config;
+    const derived = deriveDocFacts({ base: { files: deriveFiles(snapshot.baseline.records, config, { strict: true }) },
+      candidate: { files: deriveFiles(snapshot.candidate.records, config, { strict: true }) }, config });
+    if (stable(derived.facts) !== stable(snapshot.facts)
+      || stable(deriveDocObligations(derived.facts)) !== stable(snapshot.obligations)) errors.push(diagnostic('identity-mismatch'));
+    for (const obligation of snapshot.obligations) {
+      const reason = snapshot.derivationReasons && snapshot.derivationReasons[obligation.id];
+      if (obligation.strength === 'MUST' && obligation.applicability === 'N/A'
+        && (!reason || reason.applicability !== 'N/A' || !text(reason.reason) || !Array.isArray(reason.factRefs) || !reason.factRefs.length)) {
+        errors.push(diagnostic('na-reason-missing', { obligationId: obligation.id }));
+      }
+    }
+  } catch (error) {
+    const code = error && ['invalid-input', 'inventory-incomplete', 'inventory-unsupported'].includes(error.message)
+      ? error.message : 'invalid-input';
+    errors.push(diagnostic(code));
+  }
+  return errors;
+}
+
+function reconcileDocResults(input = {}) {
+  const { snapshot, accepted, checkerOutput, mode = 'verification' } = record(input) ? input : {};
+  const diagnostics = [];
+  const unsatisfied = [];
+  const results = Array.isArray(checkerOutput && checkerOutput.results) ? checkerOutput.results : [];
+  const base = { decision: 'unresolved', eligible: false, expectedMustIds: [], checkedMustIds: [], results, unsatisfied, diagnostics };
+  if (!record(snapshot) || !record(accepted) || !record(checkerOutput) || !Array.isArray(checkerOutput.results)
+    || !results.every(record) || !Array.isArray(checkerOutput.diagnostics) || !checkerOutput.diagnostics.every(record)
+    || !['verification', 'review'].includes(mode)
+    || !['ready', 'unresolved', 'unavailable'].includes(accepted.state)
+    || !Array.isArray(accepted.diagnostics) || !accepted.diagnostics.every(record)
+    || !Array.isArray(accepted.rejected) || !accepted.rejected.every(record) || !record(accepted.acceptedIndex)) {
+    diagnostics.push(diagnostic('invalid-input'));
+    return base;
+  }
+  diagnostics.push(...validateSnapshot(snapshot));
+  if (!Array.isArray(snapshot.obligations) || !snapshot.obligations.every(o => record(o) && record(o.scope) && Array.isArray(o.scope.paths))) return base;
+  const expected = snapshot.obligations.filter(o => o.strength === 'MUST' && o.applicability !== 'N/A');
+  base.expectedMustIds = expected.map(o => o.id).sort(compare);
+  const selected = mode === 'review' ? expected.filter(o => o.capability === 'quality-review') : expected;
+  base.checkedMustIds = selected.map(o => o.id).sort(compare);
+  const fail = (code, obligationId, state = 'pending') => {
+    diagnostics.push(diagnostic(code, obligationId ? { obligationId } : {}));
+    if (obligationId) unsatisfied.push({ obligationId, state, reasonCode: code });
+  };
+  if (diagnostics.length) return base;
+  const capturedArtifacts = Object.fromEntries(snapshot.candidate.records.filter(r => r.presence === 'present').map(r => [r.path, { digest: r.digest }]));
+  const capturedBaseline = { digest: snapshot.identity.baselineDigest,
+    artifacts: Object.fromEntries(snapshot.baseline.records.filter(r => r.presence === 'present').map(r => [r.path, { digest: r.digest }])) };
+  if (stable(accepted.checkerInputs?.artifacts) !== stable(capturedArtifacts)
+    || stable(accepted.checkerInputs?.baseline) !== stable(capturedBaseline)
+    || stable(accepted.checkerInputs?.obligations) !== stable(snapshot.obligations)) fail('artifact-mismatch');
+  if (!sameIdentity(snapshot.identity, accepted.identity) || stable(snapshot.originContext) !== stable(accepted.originContext)) fail('identity-mismatch');
+  if (snapshot.identity.configDigest !== accepted.identity?.configDigest) fail('config-capture-mismatch');
+  for (const item of [...(accepted.diagnostics || []), ...(accepted.rejected || [])]) {
+    diagnostics.push(item);
+    // Only rejected evidence for a checked expected MUST, or a global origin/identity fault, gates credit;
+    // a rejected SHOULD or N/A event stays a visible diagnostic (PR #353 review P2).
+    if (!item.obligationId || selected.some(o => o.id === item.obligationId)) {
+      unsatisfied.push({ obligationId: item.obligationId || 'origin', state: item.code === 'origin-unavailable' ? 'unavailable' : 'pending', reasonCode: item.code });
+    }
+  }
+  if (accepted.state === 'unavailable') fail('origin-unavailable');
+  if (checkerOutput?.unavailable) fail('checker-unavailable');
+  const known = new Set(snapshot.obligations.map(o => o.id));
+  for (const result of results) if (!known.has(result.obligationId)) fail('result-misattributed', result.obligationId);
+  for (const obligation of selected) {
+    const id = obligation.id;
+    if (obligation.applicability === 'unknown') { fail('unknown-applicability', id, 'unknown'); continue; }
+    const matches = results.filter(r => r.obligationId === id);
+    if (matches.length !== 1) { fail(matches.length ? 'result-duplicate' : 'result-missing', id); continue; }
+    const result = matches[0];
+    if (result.observation !== 'observed' || result.outcome !== 'pass') {
+      const hasAccepted = Object.values(accepted.acceptedIndex || {}).some(item => item.obligationId === id);
+      fail(hasAccepted ? 'result-not-pass' : 'result-missing', id);
+      continue;
+    }
+    const artifactDigest = obligation.scope.paths.length
+      ? obligation.scope.paths.map(p => `${p}=${capturedArtifacts[p]?.digest || 'missing'}`).join('|')
+      : snapshot.identity.baselineDigest;
+    if (result.baseDigest !== snapshot.identity.baselineDigest || result.artifactDigest !== artifactDigest) fail('result-misattributed', id);
+    if (!Array.isArray(result.recordRefs) || !result.recordRefs.length) { fail('result-untrusted', id); continue; }
+    for (const ref of result.recordRefs) {
+      const item = accepted.acceptedIndex?.[ref];
+      if (!item || item.obligationId !== id || !sameIdentity(item.identity, snapshot.identity)
+        || !text(item.originRef) || stable(item.paths) !== stable(obligation.scope.paths)
+        || item.artifactBinding !== snapshot.identity.candidateDigest) fail('result-untrusted', id);
+    }
+  }
+  // Validation failures must never be hidden by a cached report or a passing result subset.
+  // Global faults and diagnostics for a checked expected MUST block; SHOULD/N/A diagnostics stay visible only.
+  const blocking = diagnostics.filter(item => !item.obligationId || selected.some(o => o.id === item.obligationId));
+  // Checker diagnostics stay visible; eligibility is decided from the expected MUST set above.
+  // In particular, later verifier diagnostics cannot stall an independent review.
+  if (Array.isArray(checkerOutput.diagnostics)) diagnostics.push(...checkerOutput.diagnostics);
+  if (blocking.length || unsatisfied.length) {
+    if (blocking.some(d => ['origin-unavailable', 'checker-unavailable'].includes(d.code))) base.decision = 'unavailable';
+    return base;
+  }
+  if (!selected.length) { base.decision = 'legacy'; diagnostics.push(diagnostic('no-document-musts')); return base; }
+  base.decision = 'eligible';
+  base.eligible = true;
+  return base;
+}
+
+function checkAcceptedDocEvidence(input = {}) {
+  const { snapshot, accepted, mode = 'verification' } = record(input) ? input : {};
+  let checkerOutput;
+  try {
+    if (!accepted?.checkerInputs || !snapshot) throw new Error('invalid-input');
+    checkerOutput = checkDocObligations({ ...accepted.checkerInputs, obligations: snapshot.obligations });
+  } catch { checkerOutput = { results: [], diagnostics: [], unavailable: true }; }
+  return reconcileDocResults({ snapshot, accepted, checkerOutput, mode });
+}
+
+module.exports = { checkAcceptedDocEvidence, reconcileDocResults,
+  _internals: { runtimeModule, text, record, bytes, stable, clone, sha, structuredDigest, snapshotDigest, configDigest, sameIdentity, diagnostic, validateSnapshot, compare, deriveFiles, semanticRelevance, originBound, configBytesBound } };

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

@@ -0,0 +1,141 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { _internals: U } = require('./doc-reconciliation-core');
+
+// Directory identity as in the producer: native realpath (Windows 8.3 names), case-insensitive on Windows.
+function samePath(a, b) {
+  try {
+    const left = fs.realpathSync.native(path.resolve(a));
+    const right = fs.realpathSync.native(path.resolve(b));
+    return process.platform === 'win32' ? left.toLowerCase() === right.toLowerCase() : left === right;
+  } catch { return false; }
+}
+
+function artifactsFor(records) {
+  return Object.fromEntries(records.filter(item => item.presence === 'present').map(item => [item.path, { digest: item.digest }]));
+}
+function prdDigest(artifacts) {
+  return U.sha(JSON.stringify(Object.keys(artifacts).filter(p => p.startsWith('docs/prd/')).sort().map(p => [p, artifacts[p].digest])));
+}
+function acceptDocEvents(input = {}, dependencies = {}) {
+  const { snapshot, eventRefs } = U.record(input) ? input : {};
+  const originProvider = dependencies?.originProvider;
+  const diagnostics = [];
+  const rejected = [];
+  const acceptedIndex = Object.create(null);
+  const empty = { state: 'unavailable', checkerInputs: null, acceptedIndex, rejected, diagnostics };
+  try {
+    if (!snapshot || !Array.isArray(eventRefs) || !eventRefs.every(U.text)) {
+      diagnostics.push(U.diagnostic('invalid-input'));
+      return empty;
+    }
+    diagnostics.push(...U.validateSnapshot(snapshot));
+    if (diagnostics.length) return { ...empty, state: 'unresolved' };
+    const artifacts = artifactsFor(snapshot.candidate.records);
+    const baselineArtifacts = artifactsFor(snapshot.baseline.records);
+    const checkerInputs = { obligations: U.clone(snapshot.obligations), artifacts,
+      baseline: { digest: snapshot.identity.baselineDigest, artifacts: baselineArtifacts }, executionRecords: [], reviewRecords: [] };
+    const out = { state: 'ready', identity: U.clone(snapshot.identity), originContext: U.clone(snapshot.originContext), checkerInputs, acceptedIndex, rejected, diagnostics };
+    if (!originProvider || typeof originProvider.resolveEvent !== 'function' || typeof originProvider.resolveContext !== 'function') {
+      diagnostics.push(U.diagnostic('origin-unavailable'));
+      out.state = 'unavailable';
+      return out;
+    }
+    const contextResponse = originProvider.resolveContext({ workspaceRoot: snapshot.originContext.workspaceRoot, workflowId: snapshot.identity.workflowId, sessionId: snapshot.identity.sessionId });
+    if (contextResponse?.status !== 'accepted' || !U.text(contextResponse.originRef)) {
+      diagnostics.push(U.diagnostic(contextResponse?.status === 'rejected' ? 'origin-untrusted' : 'origin-unavailable'));
+      out.state = 'unavailable';
+      return out;
+    }
+    if (contextResponse.originRef !== snapshot.originContext.originRef) diagnostics.push(U.diagnostic('identity-mismatch'));
+    const context = contextResponse.context;
+    for (const key of ['workspaceId', 'sessionId', 'workflowId', 'workflowRevision', 'taskId', 'principals', 'activeHost', 'baselineReference']) {
+      if (U.stable(context?.[key]) !== U.stable(snapshot.originContext[key])) diagnostics.push(U.diagnostic('identity-mismatch'));
+    }
+    // The concrete workflow-start pin and worktree bound at capture must still be what the provider issues;
+    // a different pin under the same baselineReference is not the captured baseline (PR #353 review P1).
+    const pin = snapshot.originContext.baseline;
+    if (!U.record(context?.baseline) || !U.record(pin) || context.baseline.commit !== pin.commit
+      || !U.text(context.baseline.root) || !samePath(context.baseline.root, pin.root)) diagnostics.push(U.diagnostic('baseline-unavailable'));
+    if (context?.workspaceRoot !== undefined && !(U.text(context.workspaceRoot) && samePath(context.workspaceRoot, snapshot.originContext.workspaceRoot))) {
+      diagnostics.push(U.diagnostic('identity-mismatch'));
+    }
+    const seenIds = new Set();
+    const seenCapabilities = new Set();
+    for (const reference of eventRefs) {
+      let response;
+      try { response = originProvider.resolveEvent({ reference, identity: U.clone(snapshot.identity) }); }
+      catch { response = { status: 'unavailable' }; }
+      if (response?.status !== 'accepted') {
+        const supplied = Array.isArray(response?.diagnostics) ? response.diagnostics : [];
+        rejected.push(...(supplied.length ? U.clone(supplied) : [U.diagnostic(response?.status === 'rejected' ? 'origin-untrusted' : 'origin-unavailable', { reference })]));
+        continue;
+      }
+      const event = U.clone(response.event);
+      const obligation = snapshot.obligations.find(o => o.capability === event?.capability);
+      const obligationId = obligation?.id;
+      const problems = [];
+      const reject = code => problems.push(U.diagnostic(code, { reference, ...(obligationId ? { obligationId } : {}) }));
+      if (!U.record(event) || !['eventId', 'producerId', 'originRef', 'principalId', 'provenance', 'capability'].every(k => U.text(event[k]))
+        || !U.text(response.originRef) || event.originRef !== response.originRef || !['execution', 'verification', 'review'].includes(event.kind)) reject('event-invalid');
+      if (!U.sameIdentity(event?.identity, snapshot.identity)) {
+        reject('identity-mismatch');
+        if (event?.identity?.configDigest !== snapshot.identity.configDigest) reject('config-capture-mismatch');
+      }
+      if (!obligation) reject('capability-mismatch');
+      if (seenIds.has(event?.eventId)) reject('event-duplicate');
+      if (seenCapabilities.has(event?.capability)) reject('event-conflict');
+      seenIds.add(event?.eventId);
+      seenCapabilities.add(event?.capability);
+      const paths = obligation?.scope?.paths || [];
+      if (!Array.isArray(event?.paths) || U.stable([...event.paths].sort()) !== U.stable([...paths].sort())) reject('scope-mismatch');
+      const digests = event?.kind === 'review' ? event.reviewedArtifactDigests : event?.artifactDigests;
+      if (!U.record(digests)) reject('artifact-mismatch');
+      else {
+        for (const p of paths) {
+          if (artifacts[p] && digests[p] !== artifacts[p].digest) reject('artifact-mismatch');
+          if (!artifacts[p] && (!baselineArtifacts[p] || event.baselineArtifacts?.[p] !== baselineArtifacts[p].digest || Object.hasOwn(digests, p))) reject('artifact-mismatch');
+        }
+        // Supplied extra digests must also describe this capture, never another tree.
+        for (const p of Object.keys(digests)) if (!artifacts[p] || digests[p] !== artifacts[p].digest) reject('artifact-mismatch');
+      }
+      if (event?.kind === 'review') {
+        if (event.verdict !== 'approve' || !U.text(event.summary)) reject('event-invalid');
+        const principals = context?.principals;
+        const independent = principals && [principals.author, ...(principals.executors || [])];
+        if (!independent || independent.includes(event.principalId) || !Array.isArray(event.independentOf)
+          || !independent.every(p => event.independentOf.includes(p))) reject('review-not-independent');
+      } else {
+        if (!U.text(event?.command) || !Array.isArray(event?.argv) || !event.argv.length || !event.argv.every(U.text)
+          || !U.text(event.cwd) || !Number.isInteger(event.exitCode) || event.exitCode !== 0 || event.signal !== null
+          || !U.text(event.toolCorrelationId) || response.correlation?.toolCorrelationId !== event.toolCorrelationId
+          || !U.text(event.resultRef)) reject('event-invalid');
+        if (!U.sameIdentity(event?.startIdentity, snapshot.identity) || !U.sameIdentity(event?.endIdentity, snapshot.identity)) reject('snapshot-changed');
+        // Provider acceptance covers command semantics; the adapter additionally rejects command/argv substitution.
+        if (Array.isArray(event?.argv) && event.command !== event.argv.join(' ')) reject('capability-mismatch');
+        if (!context?.principals?.executors?.includes(event?.principalId)) reject('origin-untrusted');
+      }
+      if (problems.length) { rejected.push(...problems); continue; }
+      const adapted = { id: reference, obligationId, kind: event.kind === 'review' ? 'review' : 'execution',
+        paths: [...paths], provenance: event.provenance, baseDigest: snapshot.identity.baselineDigest,
+        artifactDigests: U.clone(digests), ...(event.baselineArtifacts ? { baselineArtifacts: U.clone(event.baselineArtifacts) } : {}) };
+      if (event.kind === 'review') Object.assign(adapted, { verdict: event.verdict, summary: event.summary });
+      else Object.assign(adapted, { command: event.command, exitCode: event.exitCode });
+      if (event.capability === 'conflict-check') {
+        adapted.candidatePrdSet = { digest: prdDigest(artifacts), complete: true, paths: Object.keys(artifacts).filter(p => p.startsWith('docs/prd/')).sort() };
+      }
+      (event.kind === 'review' ? checkerInputs.reviewRecords : checkerInputs.executionRecords).push(adapted);
+      acceptedIndex[reference] = { reference, eventId: event.eventId, obligationId, capability: event.capability,
+        paths: [...paths], identity: U.clone(event.identity), originRef: response.originRef, artifactBinding: snapshot.identity.candidateDigest,
+        artifactDigests: U.clone(digests), event };
+    }
+    if (diagnostics.length || rejected.length) out.state = 'unresolved';
+    return out;
+  } catch {
+    diagnostics.push(U.diagnostic('invalid-input'));
+    return empty;
+  }
+}
+module.exports = { acceptDocEvents };

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

@@ -0,0 +1,206 @@
+'use strict';
+
+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 { 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); }
+// 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)); }
+function samePath(a, b) {
+  const left = canonicalPath(a);
+  const right = canonicalPath(b);
+  return process.platform === 'win32' ? left.toLowerCase() === right.toLowerCase() : left === right;
+}
+function git(root, args, options = {}) {
+  const env = { ...process.env };
+  for (const key of Object.keys(env)) if (key.startsWith('GIT_')) delete env[key];
+  try {
+    return execFileSync('git', ['-C', root, ...args], { env, timeout: 10000, maxBuffer: MAX_BYTES, stdio: ['pipe', 'pipe', 'pipe'], ...options });
+  } catch { fail('baseline-unavailable'); }
+}
+function fileRecord(relative, mode, storedBytes, presence = 'present') {
+  return { path: relative, presence, type: presence === 'present' ? 'file' : '', mode,
+    storedBytes: Buffer.from(storedBytes), digest: U.sha(storedBytes) };
+}
+function validatePaths(records) {
+  const names = new Set();
+  for (const item of records) {
+    const name = item.path;
+    if (!name || name.includes('\\') || name.includes('\ufffd') || name.startsWith('/')
+      || name.split('/').some(segment => !segment || segment === '..' || segment === '.')) fail('inventory-unsupported');
+    const folded = name.normalize('NFC').toLowerCase();
+    if (names.has(folded)) fail('inventory-unsupported');
+    names.add(folded);
+  }
+}
+function captureBaseline(root, pin) {
+  if (!U.record(pin) || !/^[a-f0-9]{40,64}$/.test(pin.commit || '') || !U.text(pin.root)
+    || !samePath(pin.root, root)) fail('baseline-unavailable');
+  const actualRoot = git(root, ['rev-parse', '--show-toplevel']).toString('utf8').trim();
+  if (!samePath(actualRoot, root)) fail('baseline-unavailable');
+  const commit = git(root, ['rev-parse', '--verify', '--end-of-options', `${pin.commit}^{commit}`]).toString('utf8').trim();
+  const treeRef = git(root, ['rev-parse', '--verify', '--end-of-options', `${commit}^{tree}`]).toString('utf8').trim();
+  const entries = git(root, ['ls-tree', '-r', '-z', '--full-tree', treeRef]).toString('utf8').split('\0').filter(Boolean);
+  if (entries.length > MAX_FILES) fail('inventory-unsupported');
+  const records = [];
+  let total = 0;
+  for (const entry of entries) {
+    const match = entry.match(/^(100644|100755) blob ([a-f0-9]{40,64})\t(.+)$/s);
+    if (!match) fail('inventory-unsupported');
+    const storedBytes = git(root, ['cat-file', 'blob', match[2]]);
+    total += storedBytes.length;
+    if (total > MAX_BYTES) fail('inventory-unsupported');
+    records.push(fileRecord(match[3], match[1], storedBytes));
+  }
+  validatePaths(records);
+  return { commit, treeRef, records };
+}
+function captureCandidate(root, baseline) {
+  const raw = [];
+  let total = 0;
+  let visited = 0;
+  function walk(dir, prefix) {
+    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;
+      const absolute = path.join(dir, entry.name);
+      const stat = fs.lstatSync(absolute);
+      if (stat.isDirectory()) {
+        // Windows stats carry no POSIX permission bits (directories report 0o666); an unreadable
+        // path there makes readdir/readFile throw instead.
+        if (POSIX_MODES && (!(stat.mode & 0o444) || !(stat.mode & 0o111))) fail('inventory-incomplete');
+        walk(absolute, relative);
+        continue;
+      }
+      if (!stat.isFile()) fail('inventory-unsupported');
+      // Unreadable files must remain unavailable even when the process has elevated read access.
+      if (POSIX_MODES && !(stat.mode & 0o444)) fail('inventory-incomplete');
+      const bytes = fs.readFileSync(absolute);
+      total += bytes.length;
+      if (raw.length >= MAX_FILES || total > MAX_BYTES) fail('inventory-unsupported');
+      raw.push({ path: relative, raw: bytes, mode: stat.mode & 0o111 ? '100755' : '100644' });
+    }
+  }
+  walk(root, '');
+  validatePaths(raw);
+  // Refuse filters/encodings that the existing stored-byte reader does not model.
+  if (raw.length) {
+    const attrs = git(root, ['check-attr', '-z', '--stdin', 'filter', 'working-tree-encoding', 'ident'], { input: Buffer.from(raw.map(r => r.path).join('\0') + '\0') }).toString('utf8').split('\0');
+    for (let i = 0; i + 2 < attrs.length; i += 3) {
+      if (!['unspecified', 'unset'].includes(attrs[i + 2])) fail('inventory-unsupported');
+    }
+  }
+  // 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 records = raw.map(item => {
+    const converted = stored.get(item.path);
+    if (!converted) fail('inventory-unsupported');
+    // An unexplained non-CR difference means the two readers observed different bytes.
+    if (!item.raw.includes(13) && !item.raw.equals(converted)) fail('snapshot-changed');
+    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;
+}
+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
+// requirement, each requirement binding). Nested objects keep every key: a nested `status`/`state` there
+// is semantic and must change taskScopeDigest (PR #353 review P2).
+function withoutProgress(value, keys = progressKeys) {
+  if (!U.record(value)) return U.clone(value);
+  return Object.fromEntries(Object.keys(value).filter(key => !keys.has(key)).map(key => [key, U.clone(value[key])]));
+}
+// A binding's `report`/`reports` object configures the binding; only its load/status records are progress.
+const bindingProgressKeys = new Set([...progressKeys].filter(key => key !== 'report' && key !== 'reports'));
+function taskSemantics(task) {
+  const semantic = withoutProgress(task);
+  if (Array.isArray(task?.requirements)) {
+    semantic.requirements = task.requirements.map(requirement => {
+      const item = withoutProgress(requirement);
+      if (U.record(requirement) && Array.isArray(requirement.bindings)) item.bindings = requirement.bindings.map(binding => withoutProgress(binding, bindingProgressKeys));
+      return item;
+    });
+  }
+  return semantic;
+}
+function contextFor(input, provider) {
+  if (!provider || typeof provider.resolveContext !== 'function') fail('origin-unavailable');
+  const response = provider.resolveContext({ workspaceRoot: input.workspaceRoot, workflowId: input.workflow.workflowId, sessionId: input.workflow.sessionId });
+  if (response?.status !== 'accepted') fail(response?.status === 'rejected' ? 'origin-untrusted' : 'origin-unavailable');
+  const c = response.context;
+  if (!U.record(c) || !U.text(response.originRef) || !U.text(c.workspaceId) || !U.text(c.baselineReference)
+    || !U.text(c.principals?.author) || !Array.isArray(c.principals?.executors) || !c.principals.executors.every(U.text)) fail('origin-untrusted');
+  for (const key of ['sessionId', 'workflowId', 'workflowRevision']) if (c[key] !== input.workflow[key]) fail('identity-mismatch');
+  if (c.taskId !== input.task.taskId || U.stable(c.activeHost) !== U.stable(input.activeHost)) fail('identity-mismatch');
+  if (c.workspaceRoot && !samePath(c.workspaceRoot, input.workspaceRoot)) fail('identity-mismatch');
+  // The provider must bind the concrete workflow-start pin; a bare reference cannot authorize a
+  // re-anchored baseline (PR #353 review P1).
+  if (!U.record(c.baseline) || !U.text(c.baseline.commit) || !U.text(c.baseline.root)
+    || !U.record(input.baseline) || c.baseline.commit !== input.baseline.commit || !samePath(c.baseline.root, input.baseline.root)) fail('baseline-unavailable');
+  const root = canonicalPath(input.workspaceRoot);
+  return U.clone({ ...c, baseline: { ...c.baseline, root }, workspaceRoot: root, originRef: response.originRef });
+}
+function filesOf(records, config) {
+  // The inventory is whole-project: binary records keep their stored bytes in the identity framing and are
+  // omitted from semantic derivation unless the derive contract can observe them (PR #353 review P2).
+  return U.deriveFiles(records, config);
+}
+function produceDocSnapshot(input, dependencies = {}) {
+  const originProvider = dependencies?.originProvider;
+  try {
+    if (!U.record(input) || !U.text(input.workspaceRoot) || !U.record(input.workflow) || !U.record(input.task)
+      || !U.text(input.task.taskId) || !Array.isArray(input.task.requirements) || !U.record(input.scope)
+      || !Number.isInteger(input.workflow.workflowRevision) || input.workflow.workflowRevision < 0) fail('invalid-input');
+    if ((input.prdRoot === undefined ? 'docs/prd/' : input.prdRoot) !== 'docs/prd/' || (input.scope.prdRoot && input.scope.prdRoot !== 'docs/prd/')) fail('unsupported-prd-root');
+    const root = canonicalPath(input.workspaceRoot);
+    const detached = U.clone(input);
+    const originContext = contextFor(detached, originProvider);
+    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 };
+    // 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');
+      if (source.presence === 'present' ? !file || !U.bytes(source.bytes).equals(file.storedBytes) : Boolean(file)) fail('snapshot-changed');
+    }
+    config.digest = U.configDigest(config);
+    baseline.digest = U.snapshotDigest('baseline', baseline, coverage, baseline.records);
+    candidate.digest = U.snapshotDigest('candidate', baseline, coverage, candidate.records);
+    const planIdentity = { task: taskSemantics(detached.task), scope: U.clone(detached.scope), workflow: withoutProgress(detached.workflow), coverage, configDigest: config.digest, prdRoot: 'docs/prd/' };
+    const identity = { workspaceId: originContext.workspaceId, sessionId: originContext.sessionId, workflowId: originContext.workflowId,
+      workflowRevision: originContext.workflowRevision, taskId: originContext.taskId, taskScopeDigest: U.structuredDigest('doc-task-scope-v1', planIdentity),
+      baselineDigest: baseline.digest, candidateDigest: candidate.digest, configDigest: config.digest, prdRoot: 'docs/prd/' };
+    const derived = deriveDocFacts({ base: { files: filesOf(baseline.records, config.resolution.config) },
+      candidate: { files: filesOf(candidate.records, config.resolution.config) }, config: config.resolution.config });
+    if (!derived.facts?.inputKnown) fail('inventory-incomplete');
+    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 configAgain = resolveDocsConfigCaptured(root, { activeHost: detached.activeHost });
+    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
+      || 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)] };
+  }
+}
+module.exports = { produceDocSnapshot };

package/multi-agent-workspace/SKILL.md

@@ -4,7 +4,7 @@ description: "Scaffold a verified multi-agent workspace and select bounded speci
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.36.3
+  version: 0.39.0
 ---
 
 # Multi-Agent Workspace