harness-everything 0.36.2 → 0.36.4

package/docs/doc-evidence-boundary.md

@@ -0,0 +1,135 @@
+# Document-evidence boundary enforcement (#341 Phase 0C)
+
+## C1 method decision
+
+The C1 isolation trial does **not** establish enforcement equivalence for the document-evidence
+read boundary. The approved dependency-free checker rejects nine of eleven weakened-boundary
+controls in both distributions. N05 and N06 survive with complete C1 coverage and no diagnostics:
+each adds an unapproved read inside an existing compatibility method, and C1 checks that method's
+API/call surface without constraining its body. The plan therefore requires the bounded AST/source
+supplement in C2 before any E0 acceptance. These survivors are recorded as survivors; they are not
+out of scope, and corpus behavior does not count as their enforcement.
+
+## Checked source graph and policy
+
+`ci/lib/doc-evidence-boundary-check.js` exports only `checkBoundary({ distribution, sources,
+policy, method })`. For this trial `method` is `isolation`, and `sources` is the exact evaluator and
+capture source text supplied by the caller. The checker does not read source files itself. The
+mechanism suite loads and checks each pair independently:
+
+- canonical: `harness-everything/scripts/doc-evidence.js` and
+  `harness-everything/scripts/doc-evidence-capture.js`;
+- packaged: `plugins/harness-everything/skills/harness-everything/scripts/doc-evidence.js` and
+  `plugins/harness-everything/skills/harness-everything/scripts/doc-evidence-capture.js`.
+
+In the restricted VM, the evaluator's relative capture import resolves to the exact supplied
+capture text. The capture module may import only the declared `crypto` builtin. The policy at
+`ci/fixtures/doc-obligations/read-boundary/boundary-policy.json` is fixed input; the checker
+validates its required module/context surfaces, return schemas, ownership rules, call-site list,
+compatibility anchors, and nine coverage IDs. Missing or malformed policy schemas fail closed.
+The C1 policy fields remain unchanged. C2 adds a separate, pinned AST supplement to the same
+policy file; its final file hash is recorded in the C2 report.
+
+The checker provides deterministic mechanism evidence for these C1 surfaces:
+
+- exact evaluator/capture exports and import edges;
+- evaluator context handoff and consumer keys;
+- invocation and obligation capability names;
+- reachable tagged return shapes and primitive schemas;
+- recursively detached, plain owned views, opaque tokens, and repeated detached arrays;
+- exact direct capture call-site counts, including rejection of computed and optional-chain calls;
+- reviewed compatibility-site anchors.
+
+It compiles and exercises the supplied modules with synthetic objects; it does not wrap or freeze
+production caller objects or add production reads. The returned-view exercise checks reachable
+values and ownership. It is not source-flow analysis. Direct capability aliases, cross-function
+transfers, and statements or dormant branches added inside an already permitted compatibility
+method remain possible C1 bypasses. Compatibility anchors prove that reviewed text is present at
+declared sites; they do not constrain the complete body or control-flow footprint of those sites.
+
+## Trial evidence
+
+`ci/mechanism-341-boundary-enforcement.test.js` applies each transform in
+`ci/fixtures/doc-obligations/read-boundary/boundary-controls.json` exactly once to the selected
+in-memory pair, parses both changed texts, and calls the checker with the unchanged frozen policy.
+It checks the fixture-pinned intended rule for each rejection, records complete-coverage survivors,
+and includes a diagnostic-sink mutation that must make the N01/N02/N03 rejection assertions fail.
+Unchanged canonical and packaged pairs are positive checks.
+
+On Node.js 24.14.1 the focused suite passed, and `npm run test:mechanism` discovered 106 suites and
+passed all 106, including the C1 suite. For each distribution the unchanged pair passed with all
+nine coverage IDs complete and no diagnostics. The 11 controls produced nine `REJECTED`, two
+`SURVIVED`, and zero `UNCHECKED` outcomes:
+
+| Controls | Result in both distributions |
+|---|---|
+| N01d, N02d, N01, N02 | Rejected by the exact evaluator context surface |
+| N03, N04 | Rejected by returned-view ownership checks |
+| N07 | Rejected by capture call-site drift under COMP-C5 |
+| N08 | Rejected by the exact obligation capability surface |
+| N09 | Rejected by the exact module export surface |
+| N05, N06 | Survived with complete coverage and no diagnostics |
+
+N05 adds a candidate-bound read within the existing COMP-C2-BOUND method. N06 adds a dormant
+unvisited read within the compatibility boundary. Both demonstrate the same unbounded-method-body
+gap, including when ordinary corpus cases do not take the changed branch. The C1 fixture pins them
+as survivors; C2 below supplies their structural rejection. The C1 trial does not qualify E0 or
+establish live-host enforcement.
+
+## C2 structural supplement
+
+The checker retains `method: "isolation"` as the C1 leg and adds `method: "ast"` as a separate
+structural leg. The AST leg parses the exact evaluator/capture texts passed by its caller and never
+substitutes source read from disk. Its reviewed policy pins both complete module AST fingerprints
+and named targets for `checkDocObligations`, `evaluateObligation`, its exact consumer-context
+destructure, `captureEntry`, `createInvocationCapture`, `compatibilityCandidateBound`,
+`isPlainObject`, and `module.exports`. Each named target assigns alpha-normalized names to uniquely
+declared identifiers that occur in that target, numbering them in target-local AST order. A
+declaration added elsewhere therefore cannot renumber unrelated target fingerprints. A changed
+named target emits its structural rule; module-wide drift also emits `AST_SOURCE_STRUCTURE`.
+Thus a new read, dormant branch, helper edge, handoff field, or export cannot be admitted merely
+because it uses an existing method name or is not reached by the corpus.
+
+Fingerprints omit comments, source locations, and literal raw spelling; they preserve AST node
+shape, operators, guards, property names, and statement/call order. The target normalizer retains
+safe renames of uniquely declared enclosing locals referenced by nested targets, while a local
+addition to one target cannot shift another target's names. The full-module fingerprint applies the
+same alpha normalization across the whole program. Names with ambiguous declarations are kept
+verbatim, making some otherwise safe renames require an explicit policy review. The whole-module
+fingerprint is deliberately conservative: any other semantic source change needs a reviewed
+fingerprint update and the corresponding trace replay.
+Unknown walker nodes, parse failures, missing targets, policy errors, unavailable parser packages,
+and parser-version drift fail the AST coverage gate.
+
+Acorn 8.19.0 and acorn-walk 8.3.5 are exact development dependencies used only by CI. The checker
+also verifies the installed versions against the frozen policy. The parser is not part of the
+installed skill runtime. Both canonical and packaged source pairs are checked independently.
+
+The C2 in-memory trial applied all 11 frozen N01–N09 transforms (including N01d/N02d) to each
+distribution. All 22 attempts had complete AST coverage and were rejected with their fixture-pinned
+intended rule, including N05/N06 as `COMP-C2-BOUND`. Unchanged pairs passed. A unique local rename
+combined with CRLF/trailing-comment formatting passed in each distribution. A syntax-invalid
+control produced an incomplete AST result with `AST_PARSE_COMPLETE`, not a boundary PASS. The
+existing C1 enforcement suite still passes with its original isolation outcomes, and the repository
+mechanism discovery run passed all 106 suites on Node.js 24.14.1. These are deterministic mechanism
+results; they do not establish live-host enforcement or qualify E0. C3 mutation/compatibility
+qualification and the final C4 merged-SHA gates remain required. See
+[the baseline-binding contract](doc-evidence-baseline-binding.md) for the read roles and
+compatibility behavior the supplement must preserve.
+
+### C3 target-local repair
+
+The C3 attribution probe added an unused local to capture's `isPlainObject`. After the target-local
+normalizer change, the AST reports `AST_PROGRAM_DRIFT` plus exactly one target drift:
+`isPlainObject` under `AST_SOURCE_STRUCTURE`; no unrelated target fingerprint moves. The established
+local-rename positive still passes.
+
+The policy also pins `evaluateObligation`'s context-consumer destructure as the
+`@evaluateObligation-context-destructure` target under `EVALUATOR_CONTEXT_EXACT`. N02c was applied
+and checked separately in both distributions: it emits that exact target/rule pair with complete
+AST coverage. The enclosing `evaluateObligation` function fingerprint also detects the body edit
+under `CAPTURE_CALL_SITES`; the precise destructure target independently supplies the intended
+context-surface rejection. The 11 existing AST controls were re-run in both distributions and all
+22 were rejected under their intended rule. N02c is also on the AST route in the control fixture, and
+the enforcement suite asserts its context-destructure target on both distributions. These results
+address C3's two executed findings.

package/docs/doc-workflow-reconciliation.md

@@ -0,0 +1,224 @@
+# Document workflow reconciliation — Phase 3b preparation
+
+**Status: design and fixture contracts only. Runtime reconciliation is not shipped or activated.**
+This document refines the planned [document lifecycle contract](document-lifecycle.md#phase-3b--narrow-integration-contract-planned-not-shipped).
+The [owner's E0/E1 decision](https://github.com/dyphn1/Harness-everything/issues/325#issuecomment-6283237637)
+permits design and RED preparation before #341 E0. Even a default-OFF runtime implementation
+MUST NOT merge or activate before E0 is reviewed and accepted.
+
+## Entry gates and ownership
+
+| Gate | Permitted scope |
+| --- | --- |
+| Preparation, before E0 | This design, provider/trust data contracts, RED fixtures and legacy compatibility controls |
+| Accepted #341 E0 | Limited, opt-in, reversible consumer on the existing non-Fable typed workflow path, including the minimum trusted producer |
+| #341 E1 GO | Expansion beyond that limited consumer, after sufficient genuine development/review exposure; initial target 2–3 cycles is not a time-only gate |
+| #325 H1–H4 and paired-task architectural evidence | Inputs to separately owner-approved #320 promotion; neither E0 nor E1 alone approves a registry/CDG |
+
+Shared read/binding/decision defects return to #341 with fixture-first correction and affected
+re-observation. Documentation policy and host/VCS provenance belong to #325. The existing
+checker API and result schema remain unchanged. This consumer adds no router, provider requirement,
+automatic step insertion, tool/Stop lock, generator execution during discovery, or auto-commit.
+
+## Existing seams and planned credit order
+
+These source anchors describe the preparation baseline, `dba470813cb383945d405686cc6a65bd969b57ec`.
+They are source-traced behavior, not live-host evidence.
+
+| Boundary | Current implementation | Post-E0 integration requirement |
+| --- | --- | --- |
+| Authored step | `hooks/scripts/lib/workflow-obligations.js:updateStep()` (lines 617–645) validates active step/bindings and text, then persists pass | An authored `doc-change` step MAY advance under this existing contract; that grants no verified document-MUST credit |
+| Aggregate derivation | `syncTypedAggregateObligations()` (586–614) derives execute/verify from step statuses | Authored execute may reflect completed authored steps; verification PASS requires current document reconciliation |
+| Verification write | `hooks/scripts/workflow-disposition.js:279–296` delegates to `updateStep()` | After existing authorization/binding checks, reconcile before writing verification-step or aggregate verify PASS |
+| Direct aggregate write | `updateObligation()` (520–537) accepts nonempty evidence text and persists disposition | Guard direct `obligation execute\|verify --disposition pass` on doc-governed typed scope; text cannot bypass derived/reconciled evidence |
+| Unresolved calculation | `unresolvedObligations()` (648–682) checks generic obligations and active bindings | Include missing/unknown/unavailable/failed document evidence and current identity freshness |
+| Final completion | `hooks/scripts/workflow-stop-gate.js:36–64` calls unresolved calculation before writing `state = 'satisfied'` | Recollect identities and reconcile immediately before completion credit, including already-persisted PASS |
+
+An ordered `doc-change → review → verification` remains reachable. Authored work does not need
+to invent evidence that a later reviewer or authorized verification will produce. At verification,
+missing evidence leaves verification unresolved; later valid evidence permits a retry. A direct
+aggregate PASS attempt with unsatisfied document MUSTs MUST be rejected or ignored, including
+`execute` as well as `verify`; this does not prohibit internally derived authored execute status.
+
+Scope comes from trusted task/config/diff facts. Existing typed plans that acquire doc-governed
+scope MUST be checked against that current scope; their old aggregate PASS is not completion
+proof. Omitting a document result or authored step cannot erase a diff-derived expected MUST.
+Non-document typed plans retain existing bindings, authorization and disposition behavior.
+
+Supported reconciliation requires `stepBindingsEnabled === true` and a non-Fable strategy.
+Fable stage paths (`fable-staged`, `fable-parallel`, `fable-multi-agent-workspace`) and untyped
+workflows are explicitly unavailable for pilot credit. Loaded stage bindings are not document
+verification. Existing unsupported-path lifecycle behavior remains; unavailable pilot status
+does not add a host lock. Both Stop reminder surfaces continue to return success to the host.
+
+## Expected obligations and evidence
+
+The future adapter obtains trusted inputs, calls existing `deriveDocFacts()` and
+`deriveDocObligations()`, then `checkDocObligations()`, and reconciles against the **expected**
+obligation set. It MUST NOT treat a returned subset, empty results, or loaded skill as completion.
+Every expected applicable MUST needs a matching scope/identity-bound `observed` + `pass` result
+supported by independently accepted producer records. Missing, duplicate/conflicting, stale or
+untrusted results leave the MUST unsatisfied. Unknown applicability remains unresolved; N/A
+requires its derivation reason. SHOULD reminders do not become new gates.
+
+The checker's observation values remain `observed`, `not-observed`, `unavailable`, `unresolved`;
+its outcome values remain `pass`, `fail`, `none`. Adapter reason states such as `unknown` are
+separate from those enums. A structured pilot report is separate from the checker result.
+No timestamps, free text or result field can establish independent provenance on its own.
+
+## Minimum trusted producer
+
+The [trust data contract](../ci/fixtures/doc-obligations/reconciliation-prep/trust-contract.json)
+defines the exact identity tuple and fixture/report fields. Its positive examples are simulated
+test data, not runtime attestations. Production MUST derive or verify origins from host/VCS state;
+a caller cannot gain trust by copying these JSON fields or supplying different actor names.
+
+| Input | Required binding | Unknown/unavailable condition |
+| --- | --- | --- |
+| Baseline | Recorded baseline tree, whole identity and per-path SHA256 from the same repository-stored bytes | Missing history, unmatched snapshot origin, contradictory tree/path values |
+| Candidate | Actual candidate under review, complete inventory including new/untracked/deleted/rename paths and stored-byte semantics | Partial inventory, unsupported export, or only a PRD-set digest offered as whole candidate identity |
+| Config | Resolver-selected validated value, source/active-host selection and exact bytes parsed, bound to configDigest | Invalid/ambiguous selection, presence-only digest, substituted or changed bytes |
+| Task | Workspace/session/workflow identity and revision, task ID, effective scope digest and PRD root | Replayed task, narrowed/substituted scope or unsupported custom PRD root |
+| Execution/verification | Exact command, integer exit code, event/report reference, producer/principal identity, scope and complete identity tuple | Text-only claim, uncorrelated event, missing verifier, contradiction or replay |
+| Review | Host-validated independent human/cold-verifier principal, current reviewed scope/artifacts, approve verdict, summary and reference | Missing/mismatched reviewer, self-review by author/executor or stale approval |
+
+Preserve the checker's current `docs/prd/` envelope boundary; an unsupported custom root is
+unavailable, not silently generalized. The PRD-set digest and whole-candidate identity are distinct.
+Existing `state-persist.js:25–47` and `lib/observations.js:258,436` are potential event seams,
+not evidence that today's timestamps/counters already carry the required provenance tuple.
+Unavailable host capabilities remain visible and cannot earn PASS. A host export must establish
+repository-stored bytes across line endings; raw checkout-byte equality alone does not prove it.
+
+At verification and completion, recollect the tuple and validate relevant execution/review
+bindings. Later candidate/config/task/plan changes invalidate old credit despite persisted PASS.
+Collection never implicitly runs a verifier, generator or network fetch; new executions require
+the existing authorized verification path. Snapshot consistency is not VCS or reviewer attestation.
+
+## Advisory provider contract
+
+The [provider data contract](../ci/fixtures/doc-obligations/reconciliation-prep/provider-contract.json)
+specifies the planned interface:
+
+```text
+suggestDocProviders({ activeStep, neededCapabilities, availableProviderMetadata, hostCapabilities })
+  → { suggestions: [{ capability, providerId, availability, reason }], unavailable: [...] }
+```
+
+Only metadata relevant to the active step may be exposed. Candidate metadata supplies declared
+capabilities, host requirements and existing binding/tool locators; it does not execute commands
+or load SKILL.md content. Candidates are optional. Swapping or omitting a provider cannot alter
+expected obligations, authorize a tool, or convert missing evidence to PASS. Existing binding
+resolution handles a chosen provider; independent valid evidence can satisfy a MUST without it.
+An unsupported host reports unavailable capability/reason. H1/H2 runtime proof remains pending.
+
+## One switch and rollback
+
+Planned switch: `HARNESS_DOC_RECONCILIATION_PILOT=1`. Missing, `0`, or any other value is OFF.
+No production switch reader or runtime import is part of preparation. Test children explicitly
+set or remove the variable; requesting ON during prep still runs existing legacy production code.
+
+After E0, OFF preserves legacy disposition and grants zero pilot verification credit. Legacy
+`pass` or `satisfied` is not relabeled as document verification. Rollback removes the opt-in,
+records that pilot credit is disabled, and preserves session/evidence history. ON→OFF→ON MUST
+recollect/reconcile rather than trust any persisted pilot or legacy PASS. Withholding pilot
+credit never rejects Stop or changes host authorization. Runtime activation still requires E0;
+the switch cannot serve as a substitute for that acceptance gate.
+
+## Preparation harness handoff
+
+[provider-contract.json](../ci/fixtures/doc-obligations/reconciliation-prep/provider-contract.json)
+and [trust-contract.json](../ci/fixtures/doc-obligations/reconciliation-prep/trust-contract.json)
+are versioned plain-data specifications consumed by the preparation harness, not a production
+schema registry. Required shape and enums are validated before replay. Negative recipes remain
+inside their declared fixture payloads; assertions use stable IDs and explicit paths into captured
+replay reports.
+
+The executable source of the current case inventory is
+[cases.json](../ci/fixtures/doc-obligations/reconciliation-prep/cases.json). It contains 16
+replay cases:
+
+| Family | Executable case IDs | Coverage |
+| --- | --- | --- |
+| P01 | `P01` | Binding and free text without document evidence |
+| P02 | `P02a`, `P02b`, `P02c`, `P02d`, `P02e`, `P02f`, `P02g` | Missing result, failed execution, unknown observation, unavailable verifier control, self-review, forged identity, partial MUST coverage |
+| P03 | `P03` | Ordered work with evidence arriving before a later verification retry |
+| P04 | `P04` | Direct aggregate execute/verify PASS bypass |
+| P05 | `P05` | Candidate/config freshness, including ON→OFF→ON |
+| P06 | `P06` | Non-document typed-plan compatibility control |
+| P07 | `P07-fable-staged`, `P07-fable-parallel`, `P07-fable-multi-agent-workspace`, `P07u` | Three Fable strategies and the untyped compatibility control |
+
+P08 is the suite-level source/package parity check across every replay and the shared runtime bytes;
+it is not a separate `cases.json` record. The 16 cases currently produce 13 `EXPECTED_RED` cases
+and three `CONTROL_PASS` cases (`P02d`, `P06`, and `P07u`); all replay legs must agree. These
+statuses qualify the preparation harness only and do not grant document credit.
+
+The [pending-red.json registry](../ci/fixtures/doc-obligations/reconciliation-prep/pending-red.json)
+records 62 exact source/packaged gaps. Its root records `schemaVersion`, `phase`, `baselineSha`,
+`runtimeFingerprint`, and `entries`. The runner validates schema version, a 40-hex capture
+`baselineSha`, a 64-hex `runtimeFingerprint`, and the entry array. Each entry has exactly
+`caseId`, `assertionId`, `distribution`, `baselineSha`, `actual`, `desired`, `blocker`, and
+`reasonCode`; `assertionId` names an ON assertion as
+`<caseId>.on.<expectation-id>`, `distribution` is `source` or `packaged`, and each entry's
+`baselineSha` must equal the registry capture. Missing JSON values use the explicit
+`{ "kind": "absent" }` marker.
+
+`baselineSha` records the capture commit for provenance; it is not compared with the current
+checkout and does not qualify a gap by itself. Qualification uses `runtimeFingerprint`: the
+runner hashes the ordered paths and exact bytes in its `FINGERPRINT_FILES` list, framing each
+path and file content with NUL bytes. The current list is
+`hooks/scripts/lib/workflow-obligations.js`, `hooks/scripts/workflow-disposition.js`, and
+`hooks/scripts/workflow-stop-gate.js`; `doc-evidence.js` is excluded because the P01–P08 replays
+do not load it. A changed fingerprint fails qualification. To refresh deliberately, the runner
+prints an explicit command such as
+`node ci/prep/doc-reconciliation-red.js --recapture-candidate ci/fixtures/doc-obligations/reconciliation-prep/pending-red.candidate.json --baseline-sha <40-hex-commit>`.
+It writes a separate candidate; review its actual/desired values and reason codes before replacing
+the committed registry, then remove the candidate. Nothing is auto-accepted.
+
+The [preparation runner](../ci/prep/doc-reconciliation-red.js) has two replay modes:
+`--strict` exits 1 when a desired-contract gap remains; `--expect-red` exits 0 only when every
+current mismatch matches an exact case/assertion/distribution/actual/desired registry entry and
+all controls and parity checks pass. A stale fingerprint, unexpected PASS, unqualified mismatch,
+wrong assertion, crash, missing fixture, import error, or other infrastructure failure fails
+qualification. Infrastructure/registry errors exit 2. Expected RED is never a mutation kill or
+document verification credit.
+
+Each action may declare `expectExit` per mode (`off` and `on`; an exit code or array of exit codes,
+default `0`) for an intentional rejection. Before registry matching or parity, a replay action with a
+spawn error, a signal, no exit status, an exit outside its policy, or missing required output (the
+routing checkpoint on `route`, a JSON envelope with a string `state` on controller operations) makes
+the case `INFRASTRUCTURE`. That exits 2 and never qualifies as a gap, even when the other legs or
+later assertions still match.
+
+Every replay child has a 10 s deadline, a 4 MiB output bound and a SIGKILL on expiry. A child that
+times out (`ETIMEDOUT`), exceeds the output bound (`ENOBUFS`) or is force-terminated is an
+`INFRASTRUCTURE` fault. A test copy of the corpus may only shorten the deadline and substitute a
+fixture script; the committed corpus carries neither.
+
+The runner fails fast at three levels, so one shared fault costs one deadline, not one per replay. A
+replay stops at its first infrastructure fault and runs no later action. The case's remaining
+replays (both legs, both modes) are not run. The first `INFRASTRUCTURE` case ends the run. Each case
+not reached is reported `NOT_RUN` with its reason, so the report never looks complete. An
+`INFRASTRUCTURE` case names its `offending` leg, mode, action and fault, and `replaysRun` counts the
+replays actually started. `--recapture-candidate` refuses at the first infrastructure case.
+
+The discovered [preparation suite](../ci/mechanism-325-3b-preparation.test.js) validates the
+inventory, green OFF controls, exact pending-gap qualification and parity. Its report root contains
+`schemaVersion`, `mode`, `baselineSha`, `runtimeFingerprintMatches`, `pilotCredit`, and `cases`.
+Each case reports `caseId`, `status`, `qualifiedGaps`, `parity`, and `assertions`; each assertion
+identifies its `leg` (`source` or `packaged`), `mode` (`off` or `on`), full assertion `id`,
+classification `status`, and `actual`, with `desired`/`registered` values when applicable. Case
+statuses are `EXPECTED_RED`, `CONTROL_PASS`, `INFRASTRUCTURE`, `NOT_RUN`, or `FAIL`; assertion statuses distinguish
+passing controls, unexpected passes, qualified gaps, unqualified gaps, and registry mismatches.
+`pilotCredit` is always false. `reportOrigin` belongs to the replay's `pilotReportOrigin`
+(`runtime` only for an actual runtime report, otherwise `harness` for a synthesized marker);
+it is not a field on the preparation report's assertion rows. A harness-synthesized unavailable
+marker is never presented as a production report.
+## Implementation and acceptance after E0
+
+After accepted E0, implement the minimum trusted producer and optional provider adapter, add
+the switch reader and narrow W/D/completion integration, package generated copies, and remove
+pending exemptions as strict tests become GREEN. Require every expected applicable MUST and
+freshness check, source/package compatibility, negative cases and relevant green CI including
+Windows. A green preparation harness establishes only its declared mechanism/data checks.
+It does not claim runtime reconciliation, E0/E1 acceptance, independent host provenance or
+architectural benefit. E1 observations and H1–H4/paired evaluation remain separate gates.

package/docs/document-lifecycle.md

@@ -4,16 +4,75 @@ Contract for the documentation family: project docs configuration (D5), document
 
 Documentation is a **consumer** of the #320 workflow/obligation abstractions. Nothing here is a second router, a standing maintenance loop or a cognitive lock: every check is a pure function that reports diagnostics.
 
-## Scope of this slice
+## Scope of this slice (status as of 2026-10-20)
 
-| Phase | Status here |
+This table distinguishes merged mechanism code from end-to-end workflow integration. The last reviewed `main` commit is `29b1d65b398e2622af97bf067078373b7fa76b26` (v0.36.2). That release commit carries `[skip ci]` and only bumps package/distribution versions on top of `e5d22584e243d5b5e587ee0279625e97a9033160`, whose full-gate `CI` run [39374474269](https://github.com/dyphn1/Harness-everything/actions/runs/39374474269) completed with every job succeeded. The historical Windows System One resident teardown (`S1-RS15`) was observed in attempt 1 of [run 39175240370](https://github.com/dyphn1/Harness-everything/actions/runs/39175240370) on `main@75e04359ae5bf11a41739f8eb04d25a76ee8f3a7`; that run completed successfully on attempt 2 and says nothing about `29b1d65`. Treat the resident teardown as a known platform limitation only when a current run on the exact SHA reproduces it, and require an all-green full-gate run for that SHA before calling any baseline green.
+
+| Phase / prerequisite | Verified implementation and remaining work |
+| --- | --- |
+| 0 — contract + RED fixtures | Agreed decisions in this document, #325 and #327; fixtures under `ci/fixtures/doc-lifecycle/`; preserve earlier design history |
+| 1a — `project-docs.json` loader | **Merged** in #327; host-only malformed manifest protection remains a separate correction in #331 / draft PR #333 |
+| 2 — roles, IDs, aliases, legacy, supersession, index, D6.9 PRD revisions | **Merged** in #327; do not rebuild this lifecycle logic for Phase 3 |
+| Step-type prerequisite (#326) | **Complete:** PR #328 merged; Harness-owned `doc-change` is explicitly declared, has no implicit TDD binding, and is not auto-inserted by router/System One |
+| 3a — document facts, obligations and evidence producer | **Merged** in #334: `harness-everything/scripts/doc-obligations.js` and `doc-evidence.js`. H3/H4 have *partial deterministic mechanism* coverage, not integrated workflow evidence. Known limitations: caller-attested envelope; `configDigest` presence-only; `candidateDigest` restricted to `docs/prd/`; missing independent task-scope binding. Deleted and old rename paths are bound to trusted per-path baseline evidence ([doc-evidence-baseline-binding.md](doc-evidence-baseline-binding.md), #335 fixed by #342), with workflow-disposition reconciliation left out of scope |
+| 3b — pilot-local provider suggestions and workflow evidence reconciliation | **Preparation complete; runtime implementation not started and #341-gated.** Provider metadata, adapter/interface design and RED fixtures may proceed in parallel with #341 Phase 0A–0C; **runtime** Evidence Reconciliation must not merge or activate before **#341 E0** is accepted (see the entry-gates bullet in the 3b contract below). Implement only a thin consumer adapter; do not wait for a generic #320 registry/CDG. Includes the minimum trusted producer for baseline/candidate/config/task-scope/reviewer identity, fail-closed negative cases, doc-governed gating on `step`/`obligation` writes at the verification/completion boundary, and freshness re-check at completion. The #335 baseline-bound deletion/rename evidence has shipped (#342); claiming complete integration still requires the reconciliation gate above. Preserve existing required-binding compatibility |
+| 3c — H1–H4 and paired-task evaluation | **Not started.** Mechanism tests alone are insufficient for architecture promotion; compare frozen baseline and treatment on real bounded tasks, success/failure first, then conditional cost and latency |
+| 1b — shared documentation craft and family metadata | **Splittable.** Shared references and thin skill consumers can proceed independently. A small optional logical-family metadata seam may be piloted; physical skill directory moves remain blocked on #320 identity/path separation |
+| 4 — derived-view generators and `describes:` drift | **Not started.** Preserve generator authorization, deterministic regenerate-equals and scoped reminder semantics |
+
+### Phase 3b — narrow integration contract (planned, not shipped)
+
+The preparation design, test-only provider/trust contracts, and qualified RED replay are complete:
+[Document workflow reconciliation](doc-workflow-reconciliation.md),
+[case corpus](../ci/fixtures/doc-obligations/reconciliation-prep/cases.json),
+[pending-RED registry](../ci/fixtures/doc-obligations/reconciliation-prep/pending-red.json), and
+[preparation suite](../ci/mechanism-325-3b-preparation.test.js). Runtime reconciliation remains
+unshipped and unactivated until #341 E0 is reviewed and accepted.
+
+- **Inputs:** explicit active `doc-change` step, D6.5 diff facts, Phase 3a obligations/evidence, available provider *metadata*, and host capabilities.
+- **Entry and activation gates (#341):** parallel preparatory work — provider metadata, adapter/interface design and RED fixtures — may proceed while #341 Phase 0A–0C runs, but the **runtime** Evidence Reconciliation must not merge or activate until **#341 E0** is reviewed and accepted (initial evidence read/binding/outcome conformance, mutation and read-order compatibility, source/package parity, zero false MUST PASS on applicable adversarial cases, and applicable green CI including Windows). After E0, only the **bounded, opt-in, reversible** documentation consumer is eligible for runtime integration at the existing verification/disposition path (no second router, forced provider, new lock, or weakened authorization, with a documented rollback), and it supplies the observed exposure for **#341 E1** (initial target 2–3 genuine development/review cycles with sufficient case mix, not elapsed time). **#341 E1 GO / REVISE / NO-GO gates expansion beyond the limited pilot, not the pilot's own observation** (missing or unrepresentative exposure is `UNCHECKED`, never an automatic GO). The H1–H4 paired-task architectural gate below stays required for any #320 promotion in addition to E1. Shared evidence-read/binding/decision defects route to #341 (fixture-first correction, regression replay, re-observation); documentation policy and the trusted host/VCS producer remain #325 deliverables here.
+- **Advisory provider suggestions:** `suggestDocProviders({activeStep, neededCapabilities, availableProviderMetadata, hostCapabilities})` yields candidate providers and unavailable reasons without altering the MUST/SHOULD obligation set, granting tool access, or eagerly reading unrelated `SKILL.md`. Existing binding resolution handles an explicitly chosen provider. No new automatic step selection.
+- **Evidence reconciliation boundary and credit order:** the pilot wires Phase 3a results into the non-Fable typed-step path only. `hooks/scripts/workflow-disposition.js` delegates `step` to `updateStep()` and `binding` to `updateBinding()` in `hooks/scripts/lib/workflow-obligations.js`. Today `updateStep()` persists `step.status = 'pass'` when every required binding is `loaded` and `--evidence` is non-empty; `syncTypedAggregateObligations()` then derives aggregate `execute`/`verify` PASS from the persisted step statuses. An authored `doc-change` step is authored work, not verification: it may advance under its existing binding contract **without claiming** any doc MUST as verified. The doc-MUST reconciliation gate belongs at the authorized `verification` step and the final-completion boundary, matching D6.6 ("All events are checked at the existing workflow's `verification` step"). Phase 3b must evaluate `checkDocObligations()` for the active scope before aggregate `verify` PASS is persisted and before the workflow reports completion; an aggregate `execute` may still reflect authored step passes, but neither aggregate may stand as completion while an applicable doc MUST is unsatisfied, and `unresolvedObligations()` must surface the unsatisfied results (`pending`/`unknown`/`unavailable`/`failed`). Ordered `doc-change → review → verification` topologies stay reachable: evidence supplied by the later `review`/`verification` steps counts at its own stage, so no stage is forced to pass early and a normative doc change cannot deadlock. Non-document steps, persisted plans, existing bindings and authorization stay unchanged.
+- **Typed aggregate writes and freshness (doc-governed scope):** aggregate PASS is not derived exclusively from persisted step passes today. `updateObligation()` accepts a direct `obligation --obligation-id execute|verify --disposition pass --evidence <text>` write for **all** non-Fable typed plans, including workflows with no applicable document MUSTs. Phase 3b's guard is scoped to typed plans/steps with an applicable, doc-governed scope: there, a direct typed `execute`/`verify` PASS must be rejected or ignored unless it was derived/reconciled from satisfied doc evidence, and the `obligation` command joins `step` in the negative tests. Non-document typed workflows and persisted plans retain today's behavior unless a separately authorized compatibility decision changes them; an already-persisted plan that gains a doc-governed scope is validated against that scope and cannot complete on a stale direct aggregate PASS. Verified doc evidence must also stay bound to the persisted candidate, task and config identity: `unresolvedObligations()` and the final completion path re-check freshness, so evidence that was valid before a later candidate edit cannot remain a completion proof solely because `status: pass` was persisted.
+- **Minimum trusted producer (3b deliverable):** Phase 3b ships the pilot-local adapter that derives the VCS baseline and candidate identity, active task scope, parsed config bytes (`configDigest` bound rather than presence-checked), PRD root, execution/verification provenance and independent reviewer identity from host state (see *Phase 3b minimum trust boundary* below). `checkDocObligations()` only proves agreement with caller-supplied values; without this producer, a 3b PASS would promote caller-attested claims. Any input the producer cannot establish stays `unknown`/`unavailable` and MUST NOT pass. Phase 3c broadens adversarial H3 validation and adds paired architectural evaluation; it does not supply the minimum producer.
+- **Pilot topology and unsupported paths:** the pilot is limited to non-Fable typed-step workflows (`stepBindingsEnabled === true`, set when typed steps exist and the strategy is not `fable-*`). Fable stage-contract paths (`fable-staged`, `fable-parallel`, `fable-multi-agent-workspace`) and workflows without the typed-step contract are explicitly **not integrated / unavailable** for doc-MUST reconciliation: a `stage-binding` disposition is never doc verification, and no fallback may mark a doc MUST satisfied. Unsupported paths report that state rather than silently passing.
+- **Negative acceptance case:** for a doc-governed typed plan whose applicable MUST is failing or unknown, no boundary may report PASS: `step --disposition pass` on the verification step, `obligation --obligation-id execute|verify --disposition pass --evidence 'done'`, and final completion must all fail closed, report the unsatisfied obligation ids, and leave aggregate `verify` pending. A loaded skill plus free-text evidence is not verification. A RED fixture covers ordered `doc-change → review → verification` with reviewer/command evidence missing first and valid later: the authored `doc-change` step advances, aggregate/final PASS stays blocked until the later evidence satisfies the MUST, and neither a premature PASS nor a deadlock occurs.
+- **Compatibility:** preserve existing non-document step bindings, authorization/Rule-of-3 semantics, old persisted plans and no new Stop/tool lock. Source and installed plugin copies must behave consistently.
+- **Pre-integration work:** the baseline-bound tombstone/rename-pair evidence required by #335 shipped in #342; the remaining pre-integration work is the reconciliation contract above. #331 / draft PR #333 is a parallel host-config safety correction; neither requires the broad #320 migration.
+
+### Phase 3c — architecture promotion gate for #320 (planned, not shipped)
+
+| Hypothesis | Objective acceptance evidence |
+| --- | --- |
+| **H1 Provider independence** | Swap/omit suggestions without changing workflow obligations; valid alternate execution evidence can satisfy an applicable MUST; no evidence cannot |
+| **H2 Active-step progressive disclosure** | Captured step output / provider metadata access shows only active-step relevance and no eager unrelated `SKILL.md` content or future-step loading |
+| **H3 Evidence reconciliation** | Adversarial replay of fabricated completion, missing verifier, stale digest/base, scope substitution, forged identity, unsupported PRD roots, contradictory/failed results and unsupported waiver yields **zero false PASS** for MUSTs, with the fixture matrix below as the observable trust boundary |
+| **H4 Task-shaped composition** | Docs-only, docs+code, REQ-citing assertions, typo-only changes, code-only uncertainty, missing independent approval and waivers produce the expected obligation union and explicit unknown/unavailable outcomes |
+
+### Phase 3b minimum trust boundary and Phase 3c H3 validation (planned, not shipped)
+
+Phase 3b delivers the minimum producer and identity/scope binding needed for a trustworthy PASS; Phase 3c extends the same seam with adversarial H3 validation and paired architectural evaluation.
+
+- **Trusted producer, not the checker:** a pilot-local adapter is a **3b deliverable**; it derives the VCS baseline and candidate identity, active task scope, project-docs config identity (parsed config bytes, not presence) and execution/review provenance from host state. `checkDocObligations()` proves only that records agree with those caller-supplied values; matching a caller-provided digest is not independent validation of the input.
+- **Identity and scope requirements:** `baseline.digest` and `baseline.artifacts[path]` come from the same recorded baseline tree; candidate artifact digests come from the candidate tree actually under review; `configDigest` is bound to the parsed config bytes rather than checked for presence; the obligation's PRD root and active task scope must match the adapter's scope, and an unsupported custom PRD root is `unavailable`.
+- **Provenance and reviewer identity:** execution and verification records need the command, non-empty provenance and integer exit code; review approval needs an independent reviewer identity distinct from the executor/author. A free-text claim, self-review, missing verifier or replayed record never satisfies a MUST.
+- **Dispositions:** absent, untrusted, stale, replayed, contradictory, malformed or unsupported inputs resolve to `unknown`/`unavailable`/failed, never PASS. The 3b fail-closed negative cases cover missing producer identity, scope substitution, unbound config bytes and stale candidate evidence; 3c adds the full adversarial fixture matrix below.
+
+| H3 fixture | Expected disposition |
 | --- | --- |
-| 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 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 |
+| Fabricated completion claim / no record | `unknown`; MUST unsatisfied |
+| Forged baseline or candidate digest | rejected as stale/unknown; MUST unsatisfied |
+| Scope substitution across tasks or PRD roots | `unknown`; MUST unsatisfied |
+| Unsupported custom PRD root | `unavailable`; MUST unsatisfied |
+| Replayed earlier-candidate record | stale; MUST unsatisfied |
+| Missing, non-independent or mismatched reviewer identity | MUST unsatisfied |
+| Unsupported waiver (no reason, no cited observed record, or self-bound scope) | `unsupported-waiver`; MUST unsatisfied |
+| Contradictory or failed command results | failed; not PASS |
+| Positive control: current, independently produced matching evidence | pass |
+
+Two *separate* gates apply. The **functional gate** requires contract tests, negative cases, source/package parity, host/platform compatibility and an all-green applicable CI baseline. The **architectural gate** additionally requires H1–H4 and independently reviewed paired real-task outcomes. Freeze task fixtures, acceptance rubrics, model/effort, host permissions, comparison order and thresholds **after baseline measurement but before treatment outcomes**. Compare task correctness and failures first; report successful-task token/time/tool cost and failed-run overhead separately, with uncertainty. A small inconclusive sample is not approval. Broader #320 CDG/registry compilation and physical skill moves need **explicit owner sign-off on each specific validated interface**; retain the legacy path until then.
+
+**Cross-contract acceptance assertion:** the #341 E0/E1 gates in the Phase 3b entry-gates bullet above, [#341](https://github.com/dyphn1/Harness-everything/issues/341) and #325's phase table must stay mutually consistent: a change to one gate's semantics updates the other two records, replays affected #341 fixtures first, and only then re-collects affected 3b observations. E0 enables only the bounded, reversible, doc-only runtime consumer; E1 gates expansion beyond the limited pilot; neither approves generic #320 CDG/registry promotion, which additionally requires the H1–H4 paired real-task evidence and explicit owner sign-off above.
 
 ## 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.36.2
+  version: 0.36.4
 ---
 
 # Harness Everything