Native Learning Candidate Mining

Traceability

• Spec ID: lc05-native-learning-candidate-mining
• Roadmap: LC-05
• Status: Implemented

Intent

Allow ordinary normalized Task Episodes to produce evidence-bound Learning Loop candidate inputs without requiring an adapter-supplied learningPatternId. The first slice deterministically prepares a bounded, privacy-safe review packet, accepts an external review decision of match or abstain, validates that decision against the packet, and then feeds accepted signals through the existing buildLearningLoopReview() contract.

This is a read-only discovery method. It may identify an opportunity, but it does not call a model, mutate a Harness asset, authorize an intervention, or claim that an intervention is effective.

Acceptance Scenarios

• AC-1: Bounded ordinary-Episode packet: Given normalized Task Episodes with no adapter-supplied learningPatternId, deterministic screening emits a versioned review packet containing only bounded structural facts, Task Episode ids plus opaque evidence aliases, allowed review enums, a source binding over only those projected privacy-safe facts, and a packet digest. Raw Episode, prompt, path, or transcript content is never directly hashed. Input Episode order does not change the packet or digest.
• AC-2: First-slice pattern boundary: A reviewed native match can produce only recurring-correction, backed by an ordinary Episode's explicit correction observation or exact failure-edit-same-check-rerun repair shape. Provider-supplied repeated-rediscovery signals remain supported by the existing path, but native rediscovery waits for a privacy-safe work/read trace. The resulting native signal has ai-reviewed field provenance and remains an opportunity; no readiness or effectiveness claim is produced.
• AC-3: Match and abstain: Every deterministically screened group receives exactly one match or abstain decision. A match requires at least two distinct Episode refs and evidence from every referenced Episode. Missing, incomplete, or insufficiently comparable evidence must remain an abstention or an explicit non-clean coverage reason.
• AC-4: Hard-negative identity boundary: Episodes are not grouped merely because both failed. They need a shared privacy-safe request/task route, target, or check identity plus structural friction. Different task, target, and check identities therefore abstain before AI review. Route and target identity are only available on the report-source Episode projection that carries taskRoute and targetKeys; the buildTaskEpisodes() contract shape supplies check identity only, so screening it groups on same-check alone.
• AC-5: Protective behavior exclusion: Permission, Hook, or Guardrail denials identified as protective interventions are retained as a minimal ordinary Task Episode fact, excluded from native friction groups, and cannot become learning candidates.
• AC-6: Deterministic binding: Review decisions may reference only group, Episode, evidence, pattern, and reason values allowed by the packet. Unknown or invented refs, a stale source/packet digest, duplicate decisions, or decision/group mismatches fail closed before candidate construction.
• AC-7: Existing signal compatibility: Provider-supplied learning signals and the historical flat event-to-learningSignals path remain supported. Missing userCorrection stays unavailable instead of being materialized as observed false, while explicit false and true values retain provenance. Applying a native review appends rather than replaces signals and avoids duplicating an equivalent provider/native pattern and signature.
• AC-8: Boolean evidence states: Missing observations are represented as unavailable, not coerced to false; explicitly observed false and true values remain distinguishable through field provenance or field-coverage evidence in packet facts and validation.
• AC-9: Privacy boundary: Packet and apply output contain no raw prompt, command, transcript, session identifier, credential, email address, or Windows, POSIX, or UNC home path. episodeRef is the Task Episode id, which the Episode contract already emits as episode:<fingerprint>, so it is privacy-safe without further aliasing and stays resolvable for an authorized caller. Evidence refs are opaque aliases that bind privacy-safe source evidence IDs or public fingerprints, and each bounded Episode fact carries an aggregate digest over the complete accepted identity set. A change outside the displayed evidence limit therefore still invalidates an old review. Apply output keeps evidence aliases and the aggregate binding opaque; an authorized caller can deterministically re-derive the association from the source, but the public artifact never resolves or exposes raw evidence IDs.
• AC-10: Evaluation fixtures: Positive and hard-negative fixtures report expected match, abstain, and coverage counts for native recurring-correction plus legacy-signal compatibility, including single-Episode, protective-intervention, unrelated-failure, reordered-input, invented-ref, legacy/native-deduplication, tri-state boolean, and privacy-sentinel cases.

Non-goals

• Do not call an AI model or add provider-specific model routing.
• Do not natively infer patterns beyond first-slice recurring-correction.
• Do not natively infer repeated-rediscovery from repair, tool-count, or target-overlap proxies; add it only after an ordinary privacy-safe work/read trace exists. Existing provider-supplied signals remain supported.
• Do not auto-create or modify Memory, Rule, Skill, Hook, Gate, Eval, or other Harness components.
• Do not run, schedule, retain, or revert an intervention.
• Do not claim effectiveness, transfer, causality, or cost savings.
• Do not expose raw transcript text to the reviewer.
• Do not replace adapter-supplied learning signals or broaden provider adapters.
• Do not change the report-source schema or automatically insert unreviewed native candidates into normal report generation.

Plan and Tasks

1. Add a capability-owned Learning Loop review-packet module under scripts/harness-analysis/. It normalizes only privacy-safe structural Episode facts, screens bounded comparable pairs, builds opaque evidence alias maps by deterministic recomputation, and publishes the allowed decision contract.
2. Extend the existing capability owner in learning-loop-candidates.mjs with a deterministic apply API that validates source and packet digests, exact decision coverage, enum domains, distinct Episode membership, evidence ownership, privacy-safe reason codes, and the packet allowlist.
3. For accepted matches, append bounded learningSignals to cloned Episodes, preserve provider signals, reuse an equivalent provider signature when all matched Episodes already carry it, and invoke the existing buildLearningLoopReview() implementation.
4. Add focused fixtures that measure positive matches and abstentions while exercising hard negatives, privacy sentinels, binding failures, signal compatibility, and deterministic ordering.
5. Run focused tests, document-link integrity, the full test suite, and package verification. Perform a Review Readiness Check before any commit.

Privacy and Risk

• False grouping: Shared failure status alone can merge unrelated work. Mitigation: require shared normalized task/target/check identity and explicit structural friction, then require an evidence-bound human/AI match decision.
• Protective behavior mislabeled as waste: Permission and Hook denials can be expected safeguards. Mitigation: protective signals fail closed out of native groups.
• Reviewer invention: A reviewer could add Episode or evidence refs that were never observed. Mitigation: opaque allowlists, per-Episode evidence ownership, exact group membership, and digest binding.
• Private content leakage: Episode IDs, source refs, paths, credentials, or text could escape through packets or signatures. Mitigation: fingerprint-only Episode ids, opaque evidence aliases, enum-only reviewer prose, no raw text fields, privacy sentinel validation, deterministic signatures, and source binding over projected safe facts only.
• Overstated coverage: Truncation or absent observations could look clean. Mitigation: explicit unavailable, insufficient-*, and truncated coverage codes; the method never emits checked-clean for missing or truncated facts.
• Contract regression: Native signals could overwrite or duplicate provider signals. Mitigation: clone-and-append semantics and equivalent-signal dedupe.

Test and Review Evidence

Planned evidence, to be replaced or augmented only by actual command results:

• AC-1, AC-4, AC-5, AC-8, AC-9: node --test test/native-learning-candidate-review.test.mjs
• AC-2, AC-3, AC-6, AC-7, AC-10: node --test test/native-learning-candidate-review.test.mjs test/learning-loop-review.test.mjs
• Documentation integrity: node --test test/doc-link-graph.test.mjs
• Repository regression evidence: npm test
• Packaged-runtime evidence: npm run pack:verify

Implementation Evidence

• learning-loop-review-packet.mjs owns the versioned privacy-safe projection, deterministic screening, membership-independent pattern signature, bounded coverage, digest binding, and packet replay validation (AC-1, AC-3 to AC-6, AC-8, AC-9).
• learning-loop-candidates.mjs exposes the packet API through the existing Learning Loop owner and applies reviewed matches through buildLearningLoopReview() while preserving and deduplicating provider signals (AC-2, AC-6, AC-7).
• episode-contract.mjs records an ordinary Episode's protective-intervention observation and keeps a provider's missing userCorrection observation unavailable instead of coercing it to false (AC-5, AC-8).
• native-learning-candidate-review.test.mjs uses ordinary buildTaskEpisodes() failure-edit-same-check-rerun events with no learningSignals for the native positive path. It also covers three-Episode grouping, hard negatives, ordinary Hook protection, abstention shape, invented refs, evidence-identity replay binding inside and beyond the bounded display limit, per-Episode evidence ownership, mixed correction/repair friction, distinct-Episode handling, tri-state observations, privacy sentinels, truncation, reorder stability, and legacy/flat-signal compatibility (AC-1 to AC-10).
• Focused evidence passed after the independent-review revisions: 37/37 tests from node --test test/native-learning-candidate-review.test.mjs test/learning-loop-review.test.mjs test/session-episode-contract.test.mjs.
• Documentation integrity passed: 6/6 tests from node --test test/doc-link-graph.test.mjs.
• The final post-review full npm test completed with 1053 passing, 4 failing, and 6 skipped tests. All four failures are pre-existing Windows EPERM failures where the local account cannot create test symlinks; none touch the changed modules or focused LC-05 tests.
• Final package verification passed with an isolated temporary npm cache configuration; npm run pack:verify verified 369 npm entries and 392 runtime ZIP entries.
• git diff --check passed. No generated documentation graph changed, and no files are staged in this worktree.