feat(harness): add task-scoped experience traces

.gitattributes

@@ -2,6 +2,7 @@
 
 *.js text eol=lf
 *.json text eol=lf
+*.jsonl text eol=lf
 *.md text eol=lf
 *.mjs text eol=lf
 *.yaml text eol=lf

CHANGELOG.md

@@ -32,6 +32,11 @@ observable behavior and compatibility, not every internal refactor.
   `kimi-workspace-index-absent` warning. The public npm package now ships
   seven host metadata roots; the Qoder runtime bundle remains Qoder-specific.
 
+- `better-harness harness experience-trace` adds a read-only Qoder
+  report-source create/validate v1. Callers explicitly bind task, workspace,
+  and run keys and select either one Episode or no-session evidence; output is
+  bounded, privacy-safe canonical JSONL.
+
 - A read-only native Learning Capture review contract can now screen ordinary
   Task Episodes for repeated exact repair routes, emit a bounded privacy-safe
   packet, validate evidence-bound `match` or `abstain` decisions, and project

docs/ARCHITECTURE.md

@@ -105,6 +105,14 @@ the target journey, contract, evidence, governance, and DX-measurement system.
   its bounded human-review integrity chain: packet binding, episode/delivery
   normalization, and review application. Non-facade consumers import its public
   `index.mjs`; historical flat paths remain compatibility entrypoints.
+- `scripts/experience-trace/` owns bounded, read-only Experience Trace JSONL:
+  its exact wire contract, Qoder report-source allowlist projection, and
+  create/validate command. It may consume report-source validation only through
+  that capability's public `index.mjs`; report-source, session-analysis,
+  Learning Capture, Harness Run Checkpoints, and component snapshots do not
+  import Experience Trace. Its `index.mjs` is the sole cross-capability
+  behavioral import surface; the root registry may project only its pure command
+  manifest so root help does not load runtime behavior.
 - `scripts/harness-component-snapshot/` owns the versioned, read-only Qoder
   project component snapshot, validation, bounded diff, and non-authorizing
   rollback-reference contracts. It composes only allowlisted public

docs/specs/fixtures/lc03-episode-v1.jsonl

@@ -0,0 +1,13 @@
+{"binding":{"episode":{"provenance":"source-projected","reasonCode":"explicit-episode-selection","ref":"episode:abcdefabcdef"},"run":{"provenance":"caller-asserted","ref":"run:sha256:341d2e8ffe91f814b597ef41304711ceac5285aac6d8ff60f23fffcdb292619d"},"task":{"provenance":"caller-asserted","ref":"task:sha256:cf12e4ef94c4409b6a3cead516ae0955167d167da0a75c8e736e8eb2ebad05b4"},"workspace":{"provenance":"caller-asserted","ref":"workspace:sha256:635affe27510691386923ddaeace0c916a348b6664cd31e2b4dc6a479e95ba0e"}},"kind":"better-harness.experience-trace.header","producer":{"kind":"qoder-report-source-projection","platform":"qoder"},"recordOrdinal":0,"schemaVersion":1,"selection":{"analyzedCount":2,"confidence":"Medium","eligibleCount":3,"representative":false,"sampled":true,"sourceFingerprint":"fedcba9876543210","strategy":"stratified","warningCodes":["disabled-source-root","missing-optional-root"]},"source":{"manifestSchemaVersion":2,"projectionDigest":"sha256:670e6779abb62b2dae18d2f5081a11b102bbef3a9baa0799b1828d0666b4ff8b","reportSourceSchemaVersion":3},"traceId":"trace:sha256:4064d02402929c3629fdbeefa261106c0e9806c8802dcfbc5302ee2dae5279ee"}
+{"availability":"observed","eventType":"task-episode","evidenceRef":"source:episode","kind":"better-harness.experience-trace.event","payload":{"continuation":"session-bounded","episodeRef":"episode:abcdefabcdef","sessionCount":1,"startBoundary":"session-start"},"recordOrdinal":1,"schemaVersion":1,"traceId":"trace:sha256:4064d02402929c3629fdbeefa261106c0e9806c8802dcfbc5302ee2dae5279ee"}
+{"availability":"derived","eventType":"tool-observation","evidenceRef":"source:tool-summary","kind":"better-harness.experience-trace.event","payload":{"changeSets":[{"changeRef":"source:change:1","eventCount":2,"firstOrdinal":3,"lastOrdinal":4,"targetKeys":["11111111111111111111","22222222222222222222"]}],"toolCallCount":5},"recordOrdinal":2,"schemaVersion":1,"traceId":"trace:sha256:4064d02402929c3629fdbeefa261106c0e9806c8802dcfbc5302ee2dae5279ee"}
+{"availability":"observed","eventType":"validation-observation","evidenceRef":"source:validation:1","kind":"better-harness.experience-trace.event","payload":{"category":"node --test","checkIdentity":"check:aaaaaaaaaaaaaaaaaaaaaaaa","sourceOrdinal":7,"status":"passed","targetKeys":["33333333333333333333"],"validationRef":"source:validation:1"},"recordOrdinal":3,"schemaVersion":1,"traceId":"trace:sha256:4064d02402929c3629fdbeefa261106c0e9806c8802dcfbc5302ee2dae5279ee"}
+{"availability":"derived","eventType":"permission-boundary","evidenceRef":"source:permission-boundary","kind":"better-harness.experience-trace.event","payload":{"denied":0,"escalated":0,"prompted":1,"protectedActions":1},"recordOrdinal":4,"schemaVersion":1,"traceId":"trace:sha256:4064d02402929c3629fdbeefa261106c0e9806c8802dcfbc5302ee2dae5279ee"}
+{"availability":"derived","eventType":"episode-observation-ended","evidenceRef":"source:episode-end","kind":"better-harness.experience-trace.event","payload":{"closureStatus":"closed","repairStatus":"repaired-and-passed"},"recordOrdinal":5,"schemaVersion":1,"traceId":"trace:sha256:4064d02402929c3629fdbeefa261106c0e9806c8802dcfbc5302ee2dae5279ee"}
+{"availability":"unavailable","eventType":"capability-gap","evidenceRef":"source:gap:human-approval","kind":"better-harness.experience-trace.event","payload":{"capability":"human-approval","reasonCode":"human-approval-not-observed"},"recordOrdinal":6,"schemaVersion":1,"traceId":"trace:sha256:4064d02402929c3629fdbeefa261106c0e9806c8802dcfbc5302ee2dae5279ee"}
+{"availability":"unavailable","eventType":"capability-gap","evidenceRef":"source:gap:subagent-lineage","kind":"better-harness.experience-trace.event","payload":{"capability":"subagent-lineage","reasonCode":"subagent-parent-edge-not-observed"},"recordOrdinal":7,"schemaVersion":1,"traceId":"trace:sha256:4064d02402929c3629fdbeefa261106c0e9806c8802dcfbc5302ee2dae5279ee"}
+{"availability":"unavailable","eventType":"capability-gap","evidenceRef":"source:gap:worktree-lineage","kind":"better-harness.experience-trace.event","payload":{"capability":"worktree-lineage","reasonCode":"worktree-lineage-not-observed"},"recordOrdinal":8,"schemaVersion":1,"traceId":"trace:sha256:4064d02402929c3629fdbeefa261106c0e9806c8802dcfbc5302ee2dae5279ee"}
+{"availability":"unavailable","eventType":"capability-gap","evidenceRef":"source:gap:interruption-resume","kind":"better-harness.experience-trace.event","payload":{"capability":"interruption-resume","reasonCode":"interruption-resume-not-observed"},"recordOrdinal":9,"schemaVersion":1,"traceId":"trace:sha256:4064d02402929c3629fdbeefa261106c0e9806c8802dcfbc5302ee2dae5279ee"}
+{"availability":"unavailable","eventType":"capability-gap","evidenceRef":"source:gap:runtime-stop","kind":"better-harness.experience-trace.event","payload":{"capability":"runtime-stop","reasonCode":"runtime-stop-not-observed"},"recordOrdinal":10,"schemaVersion":1,"traceId":"trace:sha256:4064d02402929c3629fdbeefa261106c0e9806c8802dcfbc5302ee2dae5279ee"}
+{"availability":"unavailable","eventType":"capability-gap","evidenceRef":"source:gap:component-snapshot","kind":"better-harness.experience-trace.event","payload":{"capability":"component-snapshot","reasonCode":"component-snapshot-not-bound"},"recordOrdinal":11,"schemaVersion":1,"traceId":"trace:sha256:4064d02402929c3629fdbeefa261106c0e9806c8802dcfbc5302ee2dae5279ee"}
+{"coverage":[{"availability":"derived","capability":"task-binding","provenance":"caller-asserted","reasonCode":"explicit-caller-binding"},{"availability":"derived","capability":"workspace-binding","provenance":"caller-asserted","reasonCode":"explicit-caller-binding"},{"availability":"derived","capability":"run-binding","provenance":"caller-asserted","reasonCode":"explicit-caller-binding"},{"availability":"observed","capability":"task-episode","provenance":"source-projected","reasonCode":"explicit-episode-selection"},{"availability":"derived","capability":"tool-observation","provenance":"source-projected","reasonCode":"source-aggregate"},{"availability":"observed","capability":"validation-observation","provenance":"source-projected","reasonCode":"source-observation"},{"availability":"derived","capability":"permission-boundary","provenance":"source-projected","reasonCode":"source-permission-summary"},{"availability":"unavailable","capability":"human-approval","provenance":"unavailable","reasonCode":"human-approval-not-observed"},{"availability":"unavailable","capability":"subagent-lineage","provenance":"unavailable","reasonCode":"subagent-parent-edge-not-observed"},{"availability":"unavailable","capability":"worktree-lineage","provenance":"unavailable","reasonCode":"worktree-lineage-not-observed"},{"availability":"unavailable","capability":"interruption-resume","provenance":"unavailable","reasonCode":"interruption-resume-not-observed"},{"availability":"unavailable","capability":"runtime-stop","provenance":"unavailable","reasonCode":"runtime-stop-not-observed"},{"availability":"unavailable","capability":"component-snapshot","provenance":"unavailable","reasonCode":"component-snapshot-not-bound"}],"eventCount":11,"evidenceStatus":"partial","kind":"better-harness.experience-trace.terminal","policyUse":"advisory-only","recordCount":13,"recordOrdinal":12,"schemaVersion":1,"streamStatus":"complete","traceDigest":"sha256:f15892bcafa1ad3ac34586a0bdae412d73e995f84bd72ebe340b5470cf5ae5f1","traceId":"trace:sha256:4064d02402929c3629fdbeefa261106c0e9806c8802dcfbc5302ee2dae5279ee"}

docs/specs/fixtures/lc03-no-session-v1.jsonl

@@ -0,0 +1,12 @@
+{"binding":{"episode":{"provenance":"unavailable","reasonCode":"caller-declared-no-session-evidence","ref":null},"run":{"provenance":"caller-asserted","ref":"run:sha256:7522f027d7bb67cbdbb3818345249dc1f4429fe8e484f44c6330083f1292e1d0"},"task":{"provenance":"caller-asserted","ref":"task:sha256:fce82f8f9ff62cd9af044e2e21bfd2a1822d4cc506bf174a285b8fd03fb011e9"},"workspace":{"provenance":"caller-asserted","ref":"workspace:sha256:50c688560321b967e32f410e861cf64cc7af45c817bddbe466aa1f703a29850e"}},"kind":"better-harness.experience-trace.header","producer":{"kind":"qoder-report-source-projection","platform":"qoder"},"recordOrdinal":0,"schemaVersion":1,"selection":{"analyzedCount":0,"confidence":"Low","eligibleCount":0,"representative":true,"sampled":false,"sourceFingerprint":"0123456789abcdef","strategy":"all-eligible","warningCodes":[]},"source":{"manifestSchemaVersion":2,"projectionDigest":"sha256:f46c5aaea639376da6fca7bfa9df215ee2a22bdad509761912a705d57d8eb9c9","reportSourceSchemaVersion":3},"traceId":"trace:sha256:a924fb792337d1a641f2cc152a67764387d6ae0b0d04fa6ff0752469ab8d095f"}
+{"availability":"unavailable","eventType":"capability-gap","evidenceRef":"source:gap:task-episode","kind":"better-harness.experience-trace.event","payload":{"capability":"task-episode","reasonCode":"caller-declared-no-session-evidence"},"recordOrdinal":1,"schemaVersion":1,"traceId":"trace:sha256:a924fb792337d1a641f2cc152a67764387d6ae0b0d04fa6ff0752469ab8d095f"}
+{"availability":"unavailable","eventType":"capability-gap","evidenceRef":"source:gap:tool-observation","kind":"better-harness.experience-trace.event","payload":{"capability":"tool-observation","reasonCode":"caller-declared-no-session-evidence"},"recordOrdinal":2,"schemaVersion":1,"traceId":"trace:sha256:a924fb792337d1a641f2cc152a67764387d6ae0b0d04fa6ff0752469ab8d095f"}
+{"availability":"unavailable","eventType":"capability-gap","evidenceRef":"source:gap:validation-observation","kind":"better-harness.experience-trace.event","payload":{"capability":"validation-observation","reasonCode":"caller-declared-no-session-evidence"},"recordOrdinal":3,"schemaVersion":1,"traceId":"trace:sha256:a924fb792337d1a641f2cc152a67764387d6ae0b0d04fa6ff0752469ab8d095f"}
+{"availability":"unavailable","eventType":"capability-gap","evidenceRef":"source:gap:permission-boundary","kind":"better-harness.experience-trace.event","payload":{"capability":"permission-boundary","reasonCode":"caller-declared-no-session-evidence"},"recordOrdinal":4,"schemaVersion":1,"traceId":"trace:sha256:a924fb792337d1a641f2cc152a67764387d6ae0b0d04fa6ff0752469ab8d095f"}
+{"availability":"unavailable","eventType":"capability-gap","evidenceRef":"source:gap:human-approval","kind":"better-harness.experience-trace.event","payload":{"capability":"human-approval","reasonCode":"human-approval-not-observed"},"recordOrdinal":5,"schemaVersion":1,"traceId":"trace:sha256:a924fb792337d1a641f2cc152a67764387d6ae0b0d04fa6ff0752469ab8d095f"}
+{"availability":"unavailable","eventType":"capability-gap","evidenceRef":"source:gap:subagent-lineage","kind":"better-harness.experience-trace.event","payload":{"capability":"subagent-lineage","reasonCode":"subagent-parent-edge-not-observed"},"recordOrdinal":6,"schemaVersion":1,"traceId":"trace:sha256:a924fb792337d1a641f2cc152a67764387d6ae0b0d04fa6ff0752469ab8d095f"}
+{"availability":"unavailable","eventType":"capability-gap","evidenceRef":"source:gap:worktree-lineage","kind":"better-harness.experience-trace.event","payload":{"capability":"worktree-lineage","reasonCode":"worktree-lineage-not-observed"},"recordOrdinal":7,"schemaVersion":1,"traceId":"trace:sha256:a924fb792337d1a641f2cc152a67764387d6ae0b0d04fa6ff0752469ab8d095f"}
+{"availability":"unavailable","eventType":"capability-gap","evidenceRef":"source:gap:interruption-resume","kind":"better-harness.experience-trace.event","payload":{"capability":"interruption-resume","reasonCode":"interruption-resume-not-observed"},"recordOrdinal":8,"schemaVersion":1,"traceId":"trace:sha256:a924fb792337d1a641f2cc152a67764387d6ae0b0d04fa6ff0752469ab8d095f"}
+{"availability":"unavailable","eventType":"capability-gap","evidenceRef":"source:gap:runtime-stop","kind":"better-harness.experience-trace.event","payload":{"capability":"runtime-stop","reasonCode":"runtime-stop-not-observed"},"recordOrdinal":9,"schemaVersion":1,"traceId":"trace:sha256:a924fb792337d1a641f2cc152a67764387d6ae0b0d04fa6ff0752469ab8d095f"}
+{"availability":"unavailable","eventType":"capability-gap","evidenceRef":"source:gap:component-snapshot","kind":"better-harness.experience-trace.event","payload":{"capability":"component-snapshot","reasonCode":"component-snapshot-not-bound"},"recordOrdinal":10,"schemaVersion":1,"traceId":"trace:sha256:a924fb792337d1a641f2cc152a67764387d6ae0b0d04fa6ff0752469ab8d095f"}
+{"coverage":[{"availability":"derived","capability":"task-binding","provenance":"caller-asserted","reasonCode":"explicit-caller-binding"},{"availability":"derived","capability":"workspace-binding","provenance":"caller-asserted","reasonCode":"explicit-caller-binding"},{"availability":"derived","capability":"run-binding","provenance":"caller-asserted","reasonCode":"explicit-caller-binding"},{"availability":"unavailable","capability":"task-episode","provenance":"unavailable","reasonCode":"caller-declared-no-session-evidence"},{"availability":"unavailable","capability":"tool-observation","provenance":"unavailable","reasonCode":"caller-declared-no-session-evidence"},{"availability":"unavailable","capability":"validation-observation","provenance":"unavailable","reasonCode":"caller-declared-no-session-evidence"},{"availability":"unavailable","capability":"permission-boundary","provenance":"unavailable","reasonCode":"caller-declared-no-session-evidence"},{"availability":"unavailable","capability":"human-approval","provenance":"unavailable","reasonCode":"human-approval-not-observed"},{"availability":"unavailable","capability":"subagent-lineage","provenance":"unavailable","reasonCode":"subagent-parent-edge-not-observed"},{"availability":"unavailable","capability":"worktree-lineage","provenance":"unavailable","reasonCode":"worktree-lineage-not-observed"},{"availability":"unavailable","capability":"interruption-resume","provenance":"unavailable","reasonCode":"interruption-resume-not-observed"},{"availability":"unavailable","capability":"runtime-stop","provenance":"unavailable","reasonCode":"runtime-stop-not-observed"},{"availability":"unavailable","capability":"component-snapshot","provenance":"unavailable","reasonCode":"component-snapshot-not-bound"}],"eventCount":10,"evidenceStatus":"unavailable","kind":"better-harness.experience-trace.terminal","policyUse":"advisory-only","recordCount":12,"recordOrdinal":11,"schemaVersion":1,"streamStatus":"complete","traceDigest":"sha256:e568040d4ce087a63abb593e760ea4b94b140a8da6421dad7b69ab583426956e","traceId":"trace:sha256:a924fb792337d1a641f2cc152a67764387d6ae0b0d04fa6ff0752469ab8d095f"}

scripts/better-harness-cli/cli.mjs

@@ -263,7 +263,7 @@ function hasHelpFlag(argv) {
 }
 
 function requiresOwnerHelpValidation(command, subcommand) {
-  return command === "harness" && subcommand === "source-review";
+  return command === "harness" && (subcommand === "source-review" || subcommand === "experience-trace");
 }
 
 function hasJsonFlag(argv) {

scripts/better-harness-cli/registry.mjs

@@ -1,4 +1,5 @@
 import { formatHostList, HOST_CAPABILITIES, hostIdsFor } from "../host-support/index.mjs";
+import { EXPERIENCE_TRACE_COMMAND_MANIFEST } from "../experience-trace/command-manifest.mjs";
 import { PLUGIN_COMMAND_MANIFEST } from "../plugin-lifecycle/command-manifest.mjs";
 
 export const FORMAT_VERSION = "1.0";
@@ -234,6 +235,13 @@ const COMMANDS = [
         summary: "Create, compile, and apply a bounded report-source review.",
         description: "Expose an explicit local create, caller-authored decision, and confirmed apply lifecycle without calling a model or merging native evidence aliases into the outer evidence namespace.",
       },
+      {
+        name: EXPERIENCE_TRACE_COMMAND_MANIFEST.name,
+        audience: EXPERIENCE_TRACE_COMMAND_MANIFEST.audience,
+        script: EXPERIENCE_TRACE_COMMAND_MANIFEST.entryScript,
+        summary: EXPERIENCE_TRACE_COMMAND_MANIFEST.summary,
+        description: EXPERIENCE_TRACE_COMMAND_MANIFEST.description,
+      },
       {
         name: "task-loop-report",
         audience: "maintainer",