harness-everything 0.36.0 → 0.36.1

package/docs/doc-evidence-baseline-binding.md

@@ -0,0 +1,249 @@
+# Baseline-bound document evidence (#335)
+
+Additive evidence contract for deleted files and the source endpoint of a rename. This extends
+the phase 3a `doc-change` / `requirement-sync` producer in
+[`document-lifecycle.md`](document-lifecycle.md). It does not reconcile evidence with workflow
+disposition (#325 phase 3b/3c), add a lock, or add a router/provider path.
+
+## Data shape
+
+The trusted baseline keeps its existing whole-tree identity and may add per-path SHA256 values:
+
+```js
+baseline = {
+  digest: '<whole-baseline identity>',
+  artifacts: {
+    'docs/adr/GRPH-008.md': '<sha256 of the trusted baseline file>'
+  }
+}
+```
+
+`digest` is still required for every record, including baseline-only evidence. `artifacts` is
+optional; when a scope declares baseline-only paths, the matching per-path values are required.
+
+Derivation keeps every original `scope.paths` entry and adds an annotation for paths that cannot
+have a candidate artifact:
+
+```js
+scope = {
+  paths: ['docs/reference/guide.md', 'docs/reference/old-guide.md'],
+  baselinePaths: [
+    { path: 'docs/reference/old-guide.md', reason: 'rename-from', renameTo: 'docs/reference/guide.md' }
+  ]
+}
+```
+
+- `reason: 'deleted'` describes a path present in the trusted baseline and absent from the
+  candidate. A deleted entry must not carry `renameTo` at all; any own `renameTo` property,
+  including an explicitly present `undefined`, is malformed and fails the obligation closed.
+- `reason: 'rename-from'` describes the old endpoint of an identified content-identical move.
+  The destination is named by `renameTo` and must itself be a member of the same
+  `scope.paths`. A `renameTo` outside the scope is malformed and fails the obligation closed.
+- Every `baselinePaths` entry's fields (`path`, `reason`, and the own-key `renameTo` presence) are
+  snapshotted through one guarded inspection, and each field result is carried exactly once. An
+  entry whose field getter or descriptor trap throws is a metadata error (`baseline-path-invalid`)
+  and fails the entry closed instead of escaping the checker; a field accessor that throws only on
+  a later read cannot abort the audit mirror; the mirror is built from the metadata-validated
+   snapshot (validated path and captured digest) and is never a second read of the raw entry
+- A path without a `baselinePaths` entry remains a normal candidate path and keeps the existing
+  exact candidate-digest requirement.
+- `scope.paths` is never filtered to hide a baseline-only path. If the annotation is absent, the
+  old fail-closed behavior remains: the path still needs candidate evidence and cannot pass.
+
+## Record binding
+
+Records keep `paths`, `artifactDigests`, and `baseDigest`. They may add
+`baselineArtifacts`:
+
+```js
+{
+  id, obligationId, command, exitCode, provenance,
+  baseDigest: '<whole-baseline identity>',
+  paths: ['docs/reference/old-guide.md', 'docs/reference/guide.md'],
+  artifactDigests: { 'docs/reference/guide.md': '<candidate sha256>' },
+  baselineArtifacts: { 'docs/reference/old-guide.md': '<trusted baseline sha256>' }
+}
+```
+
+A deleted path is satisfied only when one observed record:
+
+1. carries the exact whole-baseline `baseDigest`;
+2. lists the path in `paths`;
+3. carries the exact trusted `baseline.artifacts[path]` value as an **own-key** entry in
+   `baselineArtifacts`;
+4. carries **no** `artifactDigests` entry for that path, and the candidate artifact map has **no
+   own-key entry** for that path.
+
+The trusted per-path value is validated once during metadata validation and then **captured**.
+The audit mirror, the stale-baseline diagnostics, and baseline binding compare against that
+captured value and never re-read the caller-owned `baseline.artifacts` map during evidence
+evaluation: a stateful own getter cannot satisfy a record with a value it started returning only
+after validation, cannot mute the stale-baseline diagnostic, and cannot drift the audit mirror.
+Its first read must therefore be the value every consumer sees; a getter that starts returning a
+different or unusable value later is factored out entirely. A baseline per-path inspection that
+throws during validation is a `baseline-artifact-invalid` metadata error and fails the path
+closed. The audit mirror is likewise keyed by the **validated** path snapshot rather than a
+re-read of `baselinePaths[].path`, so a stateful `path` accessor is read exactly once and a
+passing result always describes the baseline identity that validated and bound the evidence.
+closed instead of escaping the checker.
+
+Per-path evidence must be carried explicitly. Inherited properties in `baseline.artifacts` or a
+record's `baselineArtifacts` are not own-key evidence and never satisfy a path; the trusted
+baseline entry itself must also be an own-key entry. Null-prototype dictionaries remain valid
+when they carry own entries.
+
+Presence is own-key membership, not digest truthiness: a candidate map entry such as `{}`,
+`{ digest: '' }`, or `null` still means the path is present, so it is contradictory path state,
+not a deletion. Equally, a record with an otherwise correct `baselineArtifacts` entry that also
+carries an `artifactDigests` entry for the deleted path (a real, empty, or fake digest) is
+contradictory and does not bind that path; it is reported as `baseline-path-candidate-digest`.
+A valid alternate record may still satisfy the obligation.
+
+A rename source is satisfied only by a **single** record that also lists the current
+`renameTo` path, carries its current candidate digest as an **own-key** entry in
+`artifactDigests`, carries no `artifactDigests` entry for the old path, and has no own-key
+candidate artifact map entry for the old path. The candidate destination must itself be an
+own-key entry in the candidate artifact map whose artifact entry declares its own `digest`; an
+inherited nested digest is not explicit evidence. The own digest validated by that metadata check
+is carried into the captured snapshot, and the record binds the destination against that captured
+candidate digest — the same one used by ordinary candidate binding, the audit identity, and the
+stale diagnostics. The destination is therefore never read again through the candidate map during
+capture or binding: a nested `digest` that throws or changes after validation cannot make a stale
+destination pair bind while the audit/stale verdicts still describe the captured value. The same
+record can cover both endpoints. Destination-only evidence, source-only tombstones, split endpoint
+records, and stale destination digests do not satisfy the source. A deletion tombstone therefore
+cannot stand in for a known rename. This destination validation and the snapshot it produces are
+**applicability-gated**: `N/A` and `unknown` (and obligations without an applicability) never bind
+evidence, so they do not consume the destination digest getter during metadata validation; their
+audit identity keeps the un-gated legacy candidate read, and a stateful accessor therefore reports
+the same first legacy value to them that it would report without baseline binding.
+
+Metadata validation is the single candidate snapshot for a baseline-only path. Once a declared
+baseline path has been confirmed to have **no** own-key candidate entry, that validated absence is
+carried on the entry; binding and the `artifactDigest` audit identity reuse it instead of
+re-inspecting the candidate map, so a `Proxy` that answers own-property or `get` inspection
+consistently during validation cannot later abort the check or change the audit key. A
+baseline-only path therefore contributes `path=missing` to `artifactDigest` from the validated
+proof rather than from a fresh candidate read. This shortcut applies only to **applicable**
+obligations. `N/A` and `unknown` obligations never bind evidence and keep the legacy candidate read
+for their audit identity (so a candidate `get` that supplies a digest is still reflected there);
+they remain `outcome: 'none'` and do not emit `candidate-artifacts-invalid` from this applicability-gated check.
+
+A rename destination's validated own digest is carried too. When more than one accepted
+`rename-from` entry shares one `renameTo`, every entry's validated own digest must agree; a
+conflicting validated digest is a contradictory shared-destination snapshot and fails the whole
+obligation closed (metadata error, `outcome: 'none'`) before any binding. The carried digest must
+be a non-empty string: a stateful `digest` accessor whose value is not a usable string is not
+carried or seeded. Only **applicable** obligations validate and carry this destination snapshot;
+`N/A` and `unknown` obligations keep the legacy candidate read for their audit identity and do not
+consume the destination getter during metadata validation.
+
+The binding applies to execution and review records alike. Existing review approval, waiver,
+failing-command, requirement-sync authority, and applicability rules are unchanged. A correctly
+bound command that fails still produces an observed failure, not a pass.
+
+## Trust limits
+
+- `baseline.artifacts` is trusted caller/VCS input. The checker proves that evidence agrees with
+  the declared baseline values; it does not read Git or recompute those bytes. A validated
+  per-path value is read and captured once, so the agreement proof is against a single validated
+  snapshot rather than the value a stateful getter returns at later moments.
+- The whole-baseline `digest` remains the identity anchor. A per-path digest without the exact
+  whole-baseline identity is insufficient.
+- Candidate evidence remains authoritative for every present, new, or edited path. A baseline
+  digest alone never satisfies such a path.
+- Path membership is explicit. A record cannot bind a path only by carrying its digest.
+- Candidate presence is own-key membership in the candidate artifact map. A present entry whose
+  digest is absent, empty, or not a usable value is still present; it is never silently
+  reinterpreted as a deletion or as a rename source.
+- For an applicable obligation that declares baseline-only paths, the top-level candidate
+  `artifacts` argument must itself be a non-null object, not an array, whose prototype is
+  `Object.prototype` or `null`. An omitted, `undefined`, `null`, array, string, `Map`, `Date`,
+  `RegExp`, class instance, custom-prototype object, or other malformed top-level value is
+  **unknown inventory** and fails closed with `candidate-artifacts-invalid`; an explicit `{}` or
+  an empty null-prototype dictionary remains the legitimate empty deletion inventory. This
+  provenance check is limited to obligations that actually declare baseline paths, and it does
+  not change the shared `isPlainObject` normalizer used by callers without
+  `scope.baselinePaths`. The prototype is read only for those applicable baseline-only
+  obligations; a value whose prototype inspection throws (for example a `Proxy` with a throwing
+  `getPrototypeOf` trap) is likewise unknown inventory, and unrelated non-baseline or
+  inapplicable obligations never trigger the read. The same boundary is exception-safe for
+  own-property inspection: a throwing property-descriptor trap or a throwing nested `digest`
+  accessor encountered during metadata validation or the pre-binding capture is classified as
+  unknown inventory (`candidate-artifacts-invalid` for applicable baseline-only obligations)
+  instead of escaping the checker. Inspecting a `baselinePaths` entry itself is guarded the same
+  way: an entry whose `path`, `reason`, or `renameTo` field getter or descriptor trap throws is a
+  `baseline-path-invalid` metadata error, not an escape; the audit mirror is built from the
+  validated snapshot and contains no second read of the raw entry, so an accessor that only
+  misbehaves after the guarded snapshot is never reached. Inspection is not repeated after
+  validation for a validated baseline-only path or a rename destination, so a trap that only
+  starts throwing on a later re-inspection is never reached. `N/A` and `unknown` obligations never
+  emit that diagnostic.
+- A mixed scope can combine baseline-only paths with ordinary candidate paths (for example one
+  document deleted and another edited in the same change set). For an applicable obligation
+  that declares baseline paths, every ordinary scoped candidate digest is captured once before
+  evidence binding; binding, the `artifactDigest` audit identity, and the stale-digest
+  diagnostics all use that same captured snapshot, so a nested digest accessor whose later read
+  throws or returns a different value cannot make the audit key or a stale verdict disagree with
+  the digest that bound evidence. This includes the rename destination: after metadata proves the
+  destination is an own-key inventory entry with its own digest, the captured snapshot is seeded
+  with that validated own digest and the destination candidate map is not read again during
+  capture, so a stale pair plus a destination-only record cannot jointly pass. Declared
+  baseline-only paths were validated absent during metadata and are not read again either. A
+  throwing accessor on one of the remaining ordinary paths during capture also fails the candidate
+  inventory closed. Callers without `scope.baselinePaths` keep the legacy candidate-binding
+  behavior unchanged, including the legacy `candidateBound` read path.
+
+## Fail-closed cases
+
+The result is not a pass when any of the following is observed:
+
+- absent whole-baseline identity, absent `baseline.artifacts`, or an invalid/missing per-path
+  baseline value for a declared baseline-only path;
+- a baseline-only entry that is missing from `scope.paths`, is duplicated, has an unknown reason,
+  has a malformed `renameTo` (empty, equal to the source, outside `scope.paths`, or — for an
+  applicable obligation — without an own-key candidate destination artifact that declares its own
+  `digest`), or whose field inspection fails (a `path`, `reason`, or `renameTo` getter or
+  descriptor trap that throws during the guarded entry snapshot);
+- a deleted entry that carries a `renameTo` property at all, including an explicitly present
+  `undefined`;
+- a present `scope.baselinePaths` annotation that is not an array, including an explicitly
+  present `undefined`; absence of the property remains backward-compatible;
+- an applicable obligation that declares baseline-only paths but receives an absent or malformed
+  top-level candidate `artifacts` map (omitted, `undefined`, `null`, array, string, or an
+  object-like value that is not a plain object or null-prototype dictionary, including `Map`,
+  `Date`, `RegExp`, class instances, objects whose prototype cannot be inspected, and inventories
+  whose own-property descriptors or nested digest accessors throw); an explicit `{}` or
+  null-prototype dictionary is valid;
+- a mixed baseline+ordinary scope whose ordinary candidate digest accessor throws while the
+  candidate inventory is captured before binding;
+- a rename pair whose destination digest differs from the captured destination candidate digest,
+  including a stale pair that a separate destination-only record would otherwise leave jointly
+  passing;
+- a rename destination whose validated own digest conflicts with another accepted entry that
+  shares the same `renameTo`, or whose captured own value is not a usable non-empty string;
+- a baseline-only path with an own-key candidate artifact map entry, even when that entry has no
+  usable digest (`{}`, `{ digest: '' }`, or `null`);
+- a record that carries an `artifactDigests` entry (real, empty, or fake) for a baseline-only
+  path;
+- a rename destination with no candidate artifact (applicable obligations only; `N/A` and
+  `unknown` obligations keep the legacy candidate read for their audit identity);
+- a record with the wrong baseline identity, the wrong per-path baseline digest, an absent or
+  empty `baselineArtifacts` entry, or stale/missing endpoint evidence — where "wrong" is judged
+  against the validated baseline value captured during metadata, not a live re-read;
+- a baseline per-path digest whose inspection throws (a getter or descriptor trap), which is a
+  `baseline-artifact-invalid` metadata error rather than an escape;
+- a stateful `baselinePaths[].path` accessor whose later read names a different path: the audit
+  mirror is keyed by the validated path snapshot, so a pass can never describe a different
+  baseline identity than the one that validated the evidence;
+- an unsupported review kind, an unapproved review, or an incomplete execution record.
+
+These cases are visible in diagnostics and remain `outcome: 'none'` unless the failure is a
+correctly bound command, which remains `outcome: 'fail'` as before.
+
+## Audit output
+
+Results keep the existing `artifactDigest`, `baseDigest`, `provenance`, and `recordRefs` fields.
+Obligations that declare baseline paths additionally expose `baselineArtifacts`, mapping each
+validated baseline-only path to the trusted baseline value used for the check. The field is
+additive; callers that do not use baseline binding see unchanged output.

package/docs/document-lifecycle.md

@@ -11,8 +11,8 @@ Documentation is a **consumer** of the #320 workflow/obligation abstractions. No
 | 0 — contract + RED fixtures | This file; fixtures under `ci/fixtures/doc-lifecycle/` |
 | 1a — `project-docs.json` loader | `multi-agent-workspace/scripts/project-docs-resolver.js` |
 | 2 — roles, IDs, aliases, legacy, supersession, index, D6.9 PRD revisions | `harness-everything/scripts/doc-lifecycle.js` |
-| 3a — `doc-change` / `requirement-sync` pure derivation and evidence producer | `harness-everything/scripts/doc-obligations.js` (facts and obligations), `harness-everything/scripts/doc-evidence.js` (`checkDocObligations`). Pilot-local: not wired into workflow disposition yet. H3 and H4 have deterministic tests; H1 and H2 are deferred to 3c. Known limits: the attested-envelope fields are caller-asserted (`configDigest` is checked for presence only, not against the parsed config); `candidateDigest` covers only `docs/prd/`, so custom PRD roots and task-scope binding are not yet verified; deleted and renamed paths fail closed (#335) |
-| 1b, 3b–3c (provider suggestions, reconciliation, H1–H2 evaluation) | Not started: blocked by #320 family metadata, D1 obligation schema and D3 evidence states. Known gap: deleted and old rename paths cannot get candidate-bound evidence, so their MUSTs fail closed |
+| 3a — `doc-change` / `requirement-sync` pure derivation and evidence producer | `harness-everything/scripts/doc-obligations.js` (facts and obligations), `harness-everything/scripts/doc-evidence.js` (`checkDocObligations`). Pilot-local: not wired into workflow disposition yet. H3 and H4 have deterministic tests; H1 and H2 are deferred to 3c. Known limits: the attested-envelope fields are caller-asserted (`configDigest` is checked for presence only, not against the parsed config); `candidateDigest` covers only `docs/prd/`, so custom PRD roots and task-scope binding are not yet verified; deleted and old rename paths are bound to trusted per-path baseline evidence ([doc-evidence-baseline-binding.md](doc-evidence-baseline-binding.md), #335), with reconciliation left out of scope |
+| 1b, 3b–3c (provider suggestions, reconciliation, H1–H2 evaluation) | Not started: blocked by #320 family metadata, D1 obligation schema and D3 evidence states. Deleted and old rename paths now use trusted baseline-bound evidence (#335); reconciliation with workflow disposition remains open |
 | 4 — derived-view generators, `describes:` drift | Not started |
 
 ## Configuration (D5)

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.35.0
+  version: 0.36.1
 ---
 
 # Harness Everything