@jinn-network/client 0.1.2 → 0.1.3-canary.24b69ea4

package/plugins/claude-code-learner/skills/learn/SKILL.md

@@ -0,0 +1,412 @@
+---
+name: learn
+description: Use when running a goal end-to-end through a seven-phase learning loop. Sequences Orient → Strategize → Plan → Execute → Debrief → Improve → Memory consolidation, dispatching specialized subagents per phase, and improves itself between runs by mutating its own state directory.
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep, Task
+---
+
+# Learn — claude-code-learner orchestrator
+
+You are running one goal end-to-end through a seven-phase learning loop. This single skill drives the full pipeline. Each phase below dispatches a fresh-context subagent whose prompt body is read from a sibling `*-prompt.md` file in this skill directory; you collect the subagent's output and proceed.
+
+## Inputs (from the harness)
+
+- `goal` — `{ id, description, kind?, deadline?, spec? }`. Free-form payload describing what to achieve. The plugin reads `description` to know the task and may organize prior runs by `kind` if present. The plugin does not interpret `kind` semantically; it is an opaque string used for organizing artifacts.
+- `workingDir` — ephemeral path; the harness harvests it for delivery when this skill returns.
+- `implStateDir` — the agent's persistent self-state. Git-backed by the SessionStart hook. Mutations here persist across runs and constitute "learning."
+- `msUntilDeadline` — function returning remaining time.
+- `mode` — `train` or `frozen`. Default to `train` if absent. In `frozen` mode, the learning loop must not mutate `implStateDir`.
+- An abort signal that fires at the goal's deadline (if any).
+
+The session-start hook (`hooks/session-start`) has already initialized `implStateDir` as a git repo with the `claude-code-learner` author identity.
+
+## 1. Boot
+
+The session-start hook (`hooks/session-start`) has already run with `IMPL_STATE_DIR` set, so:
+- `implStateDir` is a git repo
+- The claude-code-learner git author identity is configured
+- HEAD sha is the implStateDir state at run start
+
+Capture it for the constitution span:
+
+```bash
+IMPL_STATE_DIR_SHA=$(git -C "$IMPL_STATE_DIR" rev-parse HEAD)
+SKILL_BUNDLE_CID=$(find "${CLAUDE_PLUGIN_ROOT:-$PLUGIN_ROOT}" -type f \( -name '*.md' -o -name '*.sh' -o -name '*.mjs' \) | sort | xargs sha256sum | sha256sum | cut -d' ' -f1)
+```
+
+The plugin root is provided by Claude Code as `${CLAUDE_PLUGIN_ROOT}`. Other harnesses may set `$PLUGIN_ROOT` from their session-start hook (the claude-code-learner hook does both for portability — sets and exports `PLUGIN_ROOT`). If neither is set, hash the loaded skills from their loaded paths.
+
+Write `workingDir/.coordinator/boot.json` (downstream phases — particularly Strategize — read it for the constitution span). The directory name is `coordinator` for backward compatibility with the existing on-disk artifact layout consumed by Strategize and Debrief; do not rename it. The shape is:
+
+```json
+{
+  "implStateDirShaAtStart": "<git HEAD sha of implStateDir at run start>",
+  "skillBundleCid": "sha256:<plugin bundle digest>",
+  "goalId": "<goal.id>",
+  "deadline": <goal.deadline as milliseconds since epoch>
+}
+```
+
+The harness hands you `goal`, `workingDir`, and `implStateDir` as session inputs (not POSIX env vars). Bind them to the variables this section uses, then write the file:
+
+```bash
+# Bind session inputs into shell variables (substitute your harness's
+# mechanism — e.g., values pulled from the initial prompt context or a
+# harness-provided JSON input):
+WORKING_DIR="<workingDir from session inputs>"
+GOAL_ID="<goal.id from session inputs>"
+DEADLINE="<goal.deadline from session inputs>"
+
+mkdir -p "$WORKING_DIR/.coordinator"
+cat > "$WORKING_DIR/.coordinator/boot.json" <<EOF
+{
+  "implStateDirShaAtStart": "$IMPL_STATE_DIR_SHA",
+  "skillBundleCid": "sha256:$SKILL_BUNDLE_CID",
+  "goalId": "$GOAL_ID",
+  "deadline": $DEADLINE
+}
+EOF
+```
+
+`deadline` is the goal's deadline in milliseconds since epoch.
+
+## 2. Phase-range guard
+
+*Phase-range hint:* if the env var `LEARNER_PHASE_RANGE` is set, run only the corresponding subset:
+
+- `full` (or unset) — run all seven phases (sections 3–9), then verify and return (sections 10–11).
+- `pre-execute` — run only sections 3–5 (Orient, Strategize, Plan), then return. The harness's specialist wrapper will run Execute itself and invoke this skill again with `post-execute`.
+- `post-execute` — run section 7 (Debrief), plus sections 8–9 (Improve, Memory consolidation) only when `mode = train`. The harness's specialist wrapper has already populated `workingDir/.execute/` from a domain-specialist Execute path before invoking this pass.
+
+This protocol exists so the harness's first-match wrapper can wrap domain-specialist Execute paths in the learning envelope without the specialist needing to know about the wrapper.
+
+Mode controls whether the self-improving phases are allowed:
+
+- `mode = train` — run Improve and Memory consolidation when phase-range includes sections 8–9.
+- `mode = frozen` — run Orient, Strategize, Plan, Execute, and Debrief only. Skip Improve and Memory consolidation, do not mutate `implStateDir`, and return with no `.improve/` or `.memory-consolidation/` requirement. The daemon enforces this with a freeze fence and rejects any envelope that mutates the frozen implementation state.
+
+For each section below, in order:
+
+1. Dispatch the section's subagent(s) per the uniform shape (see "Uniform dispatch shape" below).
+2. Collect outputs and verify the artifacts exist.
+3. Append a JSONL entry to `workingDir/.coordinator/log.jsonl`:
+   `{ ts, phase, status, summary }`.
+
+## Uniform dispatch shape
+
+Every section that dispatches a subagent uses the same shape. Spawn a fresh-context subagent. Read the prompt body from `${PLUGIN_ROOT}/skills/learn/<role>-prompt.md` (or `${CLAUDE_PLUGIN_ROOT}/skills/learn/<role>-prompt.md`) and pass it as the subagent's instructions. Pass these inputs:
+
+```
+goal             = <copy of goal>
+workingDir       = <path>
+implStateDir     = <path, read-only unless this role mutates it>
+outputPath       = workingDir/.<phase>/<artifact>.json
+msUntilDeadline  = <current value>
+... role-specific inputs (see <role>-prompt.md inputs section) ...
+```
+
+The subagent reads the prompt, follows it, writes `outputPath`, and returns a one-line summary plus `artifactPath`.
+
+Do not reference any registered-subagent registry by name. There is no `subagent_type:` argument and no `claude-code-learner:<role>` identifier. The mechanism is: read prompt file → spawn fresh-context subagent → pass prompt as instructions.
+
+Use the dispatch, wait, and release primitives exposed by the current harness. The harness is responsible for projecting those generic operations onto its native tool surface. Keep these lifecycle rules independent of harness:
+
+- Keep the returned handle/id for each dispatched subagent.
+- Wait until every required artifact for the current phase exists; if a multi-wait returns only some completed subagents, keep waiting on the remaining handles.
+- Release/close completed subagents once their outputs have been verified and their summaries have been captured, especially before spawning a later phase.
+- Pass absolute filesystem paths in subagent inputs. Subagents must use those absolute paths for reads and writes rather than assuming they inherited the coordinator's current working directory.
+
+For sections that dispatch multiple subagents in parallel (Orient, optional Debrief probes), spawn one subagent per topic with its own `topic` and `outputPath`. If your harness supports it, run them concurrently; otherwise dispatch sequentially. Subagents do not spawn further subagents — they are one level deep.
+
+## 3. Orient
+
+Purpose: gather goal + world-state + history; produce findings Strategize will consume.
+
+Decide what topics need gathering. Choose from these typical categories; add or omit based on the goal:
+
+1. **goal-parse** — what's the goal, kind (if present), deadline, spec, eligibility? Always include.
+2. **world-state** — for goals where the harness exposes tools to inspect external state, pull current relevant state. Include if such tools are available for this goal.
+3. **own-history** — list prior runs of this kind by this operator. Include if `implStateDir/runs/index.json` exists or the harness's history-of-runs query is exposed.
+4. **others-history** — recent runs of this kind by other operators. Include only if `implStateDir/policy.json` sets `allowCrossOperatorReads: true` AND the harness's history-of-runs query is exposed.
+
+For each chosen topic, dispatch an explorer subagent in parallel. Use the uniform dispatch shape with these role-specific inputs:
+
+```
+prompt body      = ${PLUGIN_ROOT}/skills/learn/explorer-prompt.md
+topic            = <topic name, e.g. "goal-parse">
+goal             = <copy of goal>
+scope            = <topic-specific scope; explorer-prompt.md describes what it expects>
+workingDir       = <path>
+implStateDir     = <path, read-only>
+outputPath       = workingDir/.orient/<topic>.json
+msUntilDeadline  = <current value>
+```
+
+After all explorers return, read each `workingDir/.orient/<topic>.json` and write `workingDir/.orient/summary.json`:
+
+```json
+{
+  "goal": { "id": "...", "kind": "...", "deadline": 0 },
+  "topics": [
+    { "topic": "goal-parse", "artifact": "workingDir/.orient/goal-parse.json", "summary": "...", "flags": [] },
+    { "topic": "world-state", "artifact": "workingDir/.orient/world-state.json", "summary": "...", "flags": ["stale"] }
+  ],
+  "openQuestions": ["string — anything Strategize needs to know was uncertain or unavailable"]
+}
+```
+
+Append a JSONL entry to `workingDir/.coordinator/log.jsonl`:
+`{ ts, phase, status, summary }`.
+
+## 4. Strategize
+
+Purpose: pick approach, freeze success criteria + timing posture into a constitution record.
+
+Dispatch a strategist subagent. Use the uniform dispatch shape with these role-specific inputs:
+
+```
+prompt body            = ${PLUGIN_ROOT}/skills/learn/strategist-prompt.md
+goal                   = <copy of goal>
+orientSummaryPath      = workingDir/.orient/summary.json
+priorStrategiesPath    = implStateDir/strategies/<goal.kind>/   (or null if absent)
+workingDir             = <path>
+implStateDir           = <path, read-only>
+outputDir              = workingDir/.strategize/
+skillBundleCid         = <from boot.json>
+implStateDirShaAtStart = <from boot.json>
+msUntilDeadline        = <current value>
+```
+
+After it returns, verify both files exist:
+- `workingDir/.strategize/strategy.json`
+- `workingDir/.strategize/constitution.json`
+
+If either is missing, write `workingDir/.errors/strategize.json` with the failure context and abort the pipeline. In `train` mode, still run section 9, Memory consolidation, before returning. In `frozen` mode, return without running section 9.
+
+After Strategize, read `workingDir/.strategize/constitution.json`. If the harness exposes an OTel tracer, emit the constitution fields as attributes on a state-transition span (the harness defines the span name). Otherwise the file itself is the constitution record; Debrief reads it from there.
+
+Never run a second strategist after the first has committed (no re-strategizing mid-run). The strategy is frozen for the remainder of this run.
+
+Append a JSONL entry to `workingDir/.coordinator/log.jsonl`:
+`{ ts, phase, status, summary }`.
+
+## 5. Plan
+
+Purpose: produce concrete steps, optionally time-anchored.
+
+Dispatch a planner subagent. Use the uniform dispatch shape with these role-specific inputs:
+
+```
+prompt body              = ${PLUGIN_ROOT}/skills/learn/planner-prompt.md
+goal                     = <copy of goal>
+strategyPath             = workingDir/.strategize/strategy.json
+orientSummaryPath        = workingDir/.orient/summary.json
+priorPlanTemplatesPath   = implStateDir/plans/<goal.kind>/ (or null)
+replanContextPath        = workingDir/.plan/replan-context.json (or null on first plan)
+priorPlanArchives        = [workingDir/.plan/plan-v1.json, ...] (or empty on first plan)
+workingDir               = <path>
+implStateDir             = <path, read-only>
+outputPath               = workingDir/.plan/plan.json
+msUntilDeadline          = <current value>
+```
+
+After it returns, verify `workingDir/.plan/plan.json` exists. If not, write `workingDir/.errors/plan.json` and abort the pipeline (still run section 9 before returning).
+
+Append a JSONL entry to `workingDir/.coordinator/log.jsonl`:
+`{ ts, phase, status, summary }`.
+
+## 6. Execute
+
+Purpose: walk the plan, dispatch one step-worker per work step, honor wait steps, decide at runtime when stuck.
+
+Inputs you read directly:
+- `workingDir/.plan/plan.json` — the steps
+- `workingDir/.strategize/strategy.json` — success criteria + timing posture
+- `workingDir/.orient/summary.json` — grounding
+- The goal + deadline + remaining time budget
+
+For each step in order, respecting `concurrency` markings:
+
+### Work steps
+
+Dispatch a step-worker subagent. Use the uniform dispatch shape with these role-specific inputs:
+
+```
+prompt body      = ${PLUGIN_ROOT}/skills/learn/step-worker-prompt.md
+stepSpec         = <the entire step object from plan.json>
+goal             = <copy of goal>
+workingDir       = <path>
+implStateDir     = <path, read-only>
+msUntilDeadline  = <current value>
+```
+
+For parallel-batch steps (steps sharing a `concurrency: parallel-batch-X` label), dispatch the whole batch concurrently if your harness supports it; wait for all to return before advancing.
+
+After a worker returns:
+- The worker's self-reported `status` and `blockers` are evidence; the authoritative verdict is your re-check of the step's `successSignal` against actual outputs on disk.
+- Check `successSignal` — did the step succeed?
+- If yes: append to `workingDir/.execute/log.jsonl` (carrying the worker's `status` and `blockers` into the log entry) and advance.
+- If no: see "When stuck" below.
+
+### Wait steps
+
+Use the harness's wait primitive (per spec §8 harness-adapter contract). Plan-emitted wait steps may include any combination of `durationMs`, `untilTs`, and `condition`; treat absent and explicit `null` identically as "not set." When multiple wakers are set, wake on the first to fire (per spec §5: `wait` wakes when any of duration / deadline / condition fires). The abort signal from the harness (the goal's `deadline`) always overrides any wait.
+
+### When stuck
+
+When a step fails its success signal or a worker returns without expected outputs, judge:
+
+- **continue** — accept partial; advance.
+- **retry-step** — dispatch a fresh worker for the same step. Cap at 2 retries unless step `abortCondition` says otherwise.
+- **replan** — archive the current plan and re-run section 5 (Plan), then continue Execute on the new plan. Concretely: rename `workingDir/.plan/plan.json` to `workingDir/.plan/plan-v<N>.json` where N is the next unused integer (start at 1), write `workingDir/.plan/replan-context.json` with `{ failedStepId, blockers, partialOutputs[] }`, then re-dispatch the planner subagent (section 5). The new `plan.json` is grounded in what's now in `workingDir/` (including the archived prior plans, the execute log up to the failure, and the replan-context). Continue Execute on the new `plan.json`.
+- **abort** — write `workingDir/.errors/execute.json` with failure context; exit Execute. Continue to Debrief and, in `train` mode only, Improve / Memory consolidation. Abort here is not a pipeline-level abort.
+
+Explain your judgment in `workingDir/.execute/log.jsonl`.
+
+### Outputs
+
+Throughout the phase:
+- `workingDir/.execute/log.jsonl` — one entry per step boundary: `{ ts, stepId, decision, summary, retryCount, workerStatus, workerBlockers }`. `workerStatus` and `workerBlockers` come directly from the step-worker's return shape so Debrief sees both the worker's self-assessment and Execute's verdict.
+- Per-step outputs as the plan declared.
+
+At end, write `workingDir/.execute/summary.json`:
+
+```json
+{
+  "stepsCompleted": ["step-1", "step-2"],
+  "stepsFailed": [],
+  "decisions": ["continue", "retry-step", "continue"],
+  "elapsedMs": 0,
+  "returnReason": "all-steps-completed | early-return | hold-and-revise-window-end | continuous-observation-window-end | abort"
+}
+```
+
+Append a JSONL entry to `workingDir/.coordinator/log.jsonl`:
+`{ ts, phase, status, summary }`.
+
+## 7. Debrief
+
+Purpose: post-execution analysis. Mirrors Orient — gather + sense-make in hindsight.
+
+### Optional: dispatch debrief explorers
+
+If the operator's policy enables cross-operator reads or fresh-world-state probes, dispatch explorer subagents in parallel for each post-execution topic. Typical topics:
+
+- `outcome-probe` — re-pull world state via whatever tools the harness exposes for this goal, to see post-execution outcome.
+- `cross-operator-comparison` — the harness's history-of-runs query, if exposed, for similar runs by other operators (only if policy allows).
+
+Use the uniform dispatch shape; each explorer writes `workingDir/.debrief/<topic>.json`.
+
+### Dispatch the analyst
+
+Dispatch an analyst subagent. Use the uniform dispatch shape with these role-specific inputs:
+
+```
+prompt body          = ${PLUGIN_ROOT}/skills/learn/analyst-prompt.md
+goal                 = <copy of goal>
+strategyPath         = workingDir/.strategize/strategy.json
+constitutionPath     = workingDir/.strategize/constitution.json
+planPath             = workingDir/.plan/plan.json
+executeSummaryPath   = workingDir/.execute/summary.json
+executeLogPath       = workingDir/.execute/log.jsonl
+orientSummaryPath    = workingDir/.orient/summary.json
+debriefExplorerPaths = [workingDir/.debrief/<topic>.json, ...]
+ownHistoryPath       = implStateDir/runs/index.json (or null)
+workingDir           = <path>
+implStateDir         = <path, read-only>
+outputPath           = workingDir/.debrief/analysis.json
+msUntilDeadline      = <current value>
+```
+
+After it returns, verify `workingDir/.debrief/analysis.json` exists. If not, write `workingDir/.errors/debrief.json` and abort the pipeline. In `train` mode, still run section 9 before returning. In `frozen` mode, return without running section 9.
+
+Append a JSONL entry to `workingDir/.coordinator/log.jsonl`:
+`{ ts, phase, status, summary }`.
+
+## 8. Improve
+
+Purpose: mutate `implStateDir`, commit each accepted mutation as a separate git commit. Changes take effect NEXT run.
+
+Run this section only when `mode = train`. If `mode = frozen`, skip it entirely and append a coordinator log entry noting `{ phase: "improve", status: "skipped", summary: "mode=frozen" }`.
+
+Dispatch a promoter subagent. Use the uniform dispatch shape with these role-specific inputs:
+
+```
+prompt body        = ${PLUGIN_ROOT}/skills/learn/promoter-prompt.md
+goal               = <copy of goal>
+analysisPath       = workingDir/.debrief/analysis.json
+policyPath         = implStateDir/policy.json (or null)
+implStateDir       = <path, read-write for the promoter>
+workingDir         = <path>
+outputDir          = workingDir/.improve/
+msUntilDeadline    = <current value>
+```
+
+The promoter writes mutations directly into `implStateDir`, commits each as a separate git commit (the session-start hook configured the author identity already), and writes one `promotion_record` per mutation under `workingDir/.improve/promotions/`.
+
+After it returns, read `workingDir/.improve/summary.json`. Verify:
+- `implStateDirShaAfter` matches `git -C <implStateDir> rev-parse HEAD`
+- One `promotion_record` per accepted change
+- Operator-access requests under `workingDir/.operator-requests/` if any
+
+If anything is inconsistent, write `workingDir/.errors/improve.json` and abort the pipeline, then still run section 9 before returning. This section only runs in `train` mode.
+
+Append a JSONL entry to `workingDir/.coordinator/log.jsonl`:
+`{ ts, phase, status, summary }`.
+
+## 9. Memory consolidation
+
+Purpose: curate `implStateDir` (prune unused, revert regressions) and `workingDir` (set public/private boundary); commit durable curation as one separate commit.
+
+Run this section only when `mode = train`. If `mode = frozen`, skip it entirely and append a coordinator log entry noting `{ phase: "memory-consolidation", status: "skipped", summary: "mode=frozen" }`. Do not create durable commits or modify `implStateDir` in frozen mode.
+
+Dispatch a consolidator subagent. Use the uniform dispatch shape with these role-specific inputs:
+
+```
+prompt body          = ${PLUGIN_ROOT}/skills/learn/consolidator-prompt.md
+goal                 = <copy of goal>
+analysisPath         = workingDir/.debrief/analysis.json
+improveSummaryPath   = workingDir/.improve/summary.json
+improvePromotionsDir = workingDir/.improve/promotions/
+policyPath           = implStateDir/policy.json (or null)
+implStateDir         = <path, read-write>
+workingDir           = <path, read-write>
+outputPath           = workingDir/.memory-consolidation/consolidation_record.json
+msUntilDeadline      = <current value>
+```
+
+The consolidator does both workstreams (durable + ephemeral), writes a single git commit on `implStateDir` for the durable curation, and produces the `consolidation_record`.
+
+After it returns, verify the `consolidation_record` exists. If the consolidator made a commit, `implStateDirShaAfter` must match `git -C <implStateDir> rev-parse HEAD`. If no commit was made (empty curation set), `implStateDirShaAfter` must equal `implStateDirShaBefore` and HEAD remains at that sha.
+
+Append a JSONL entry to `workingDir/.coordinator/log.jsonl`:
+`{ ts, phase, status, summary }`.
+
+## 10. Verify and return
+
+Before returning, assert each primary artifact exists:
+
+- `workingDir/.orient/summary.json`
+- `workingDir/.strategize/strategy.json`
+- `workingDir/.plan/plan.json`
+- `workingDir/.execute/summary.json`
+- `workingDir/.debrief/analysis.json`
+- `workingDir/.improve/summary.json`
+- `workingDir/.memory-consolidation/consolidation_record.json`
+
+When `mode = frozen`, do not require `workingDir/.improve/summary.json` or `workingDir/.memory-consolidation/consolidation_record.json`; those phases are skipped by contract.
+
+Do NOT include any goal-kind-specific assertions. The harness owns goal-kind enforcement (e.g. domain-specific solution payloads). The plugin verifies only its own seven generic phase artifacts.
+
+When the pipeline finishes — whether all sections completed cleanly, an abort signal fired, or a section reported failure — return. Never modify anything outside `implStateDir/**` or `workingDir/**`.
+
+## 11. Failure handling
+
+- **Within Execute (section 6):** that section judges `continue / retry-step / replan / abort` per its own rules.
+- **Execute reporting `abort` is not a pipeline-level abort** — continue to Debrief and, in `train` mode only, Improve / Memory consolidation so partial work is analyzed and curated. The Execute section writes `workingDir/.errors/execute.json` itself.
+- **Other sections:** if a section reports a hard problem, write `workingDir/.errors/<phase>.json` and abort the pipeline. In `train` mode, still run section 9 (Memory consolidation) so partial work gets curated. In `frozen` mode, do not run section 9.
+- **Abort signal fired (deadline reached):** stop the current section cleanly, write `workingDir/.errors/abort.json`, and return. In `train` mode, run section 9 first if there is enough time and doing so does not violate the abort signal. In `frozen` mode, do not run section 9.
+
+## Cross-reference
+
+- Pipeline + artifacts: `docs/superpowers/specs/2026-04-23-default-learning-restorer-design.md` v1.1.
+- Plugin layout: `docs/superpowers/specs/2026-05-06-claude-code-learner-plugin-simplification-design.md` v1.1.

package/plugins/claude-code-learner/skills/learn/analyst-prompt.md

@@ -0,0 +1,68 @@
+---
+description: Specialized fresh-context subagent for Debrief. Synthesizes this run's trajectory, prior runs, optional cross-operator evidence, and outcome probes into an analysis Improve can act on.
+tools: Bash, Read, Write
+---
+
+# Analyst (subagent role)
+
+Produce an analysis Improve can act on. Cover four things.
+
+## Inputs (from your spawn prompt)
+
+All paths listed in the Debrief skill's spawn-input block. Read them.
+
+## What to cover
+
+1. **Did this run meet its success criteria?** Compare execute outputs against `successCriteria` from `strategy.json`. Yes / no / partial. If partial, where did it fall short?
+2. **Where did execution diverge from plan, and why?** Walk `executeLogPath`. For each retry / replan / abort decision, attribute the cause: prompt, tool choice, delegation, model, context, plan-wrong, world-state-changed.
+3. **What signals from others' runs are relevant?** Read explorer outputs if present. Are others doing this kind successfully with a different approach? Are there patterns in the attested-tier corpus that suggest this run's approach was suboptimal?
+4. **Trend — is this operator improving?** Read `ownHistoryPath`. Compare the last 5–10 runs by this operator for this kind. Trending up, flat, down? Note any specific kind+goal shape this operator does poorly on.
+
+## Output
+
+Write `<outputPath>`:
+
+```json
+{
+  "successCriteriaMet": "yes | no | partial",
+  "successCriteriaShortfall": "string — null if met",
+  "divergencesFromPlan": [
+    {
+      "stepId": "step-3",
+      "what": "string",
+      "attributedCause": "prompt | tool-choice | delegation | model | context | plan-wrong | world-state-changed",
+      "evidence": "string"
+    }
+  ],
+  "crossOperatorSignals": [
+    {
+      "envelopeCid": "...",
+      "tier": "attested | committed | self-signed",
+      "lesson": "string"
+    }
+  ],
+  "trend": {
+    "kind": "...",
+    "lastNRuns": 10,
+    "passRate": 0.6,
+    "direction": "improving | flat | declining",
+    "notableFailureShapes": ["string", "..."]
+  },
+  "recommendationsForImprove": [
+    "string — concrete suggestion (e.g. 'add a retry-on-stale-quote skill', 'tighten the slippage threshold in workflow.yaml')"
+  ]
+}
+```
+
+Return to the dispatching section of `skills/learn/SKILL.md`: a one-paragraph plain-English summary plus the path to analysis.json.
+
+## Boundaries
+
+- Do not change `successCriteria`
+- Do not modify `implStateDir`
+- Do not spawn further subagents
+- Do not invent recommendations not grounded in the evidence
+
+## Cross-reference
+
+Spec: §4.5.

package/plugins/claude-code-learner/skills/learn/consolidator-prompt.md

@@ -0,0 +1,94 @@
+---
+description: Specialized fresh-context subagent for Memory consolidation. Curates implStateDir (prune/archive unused, revert regressions, compact noise) and workingDir (public/private boundary); commits durable curation as one git commit distinct from Improve's per-change commits.
+tools: Bash, Read, Write, Edit, Glob, Grep
+---
+
+# Consolidator (subagent role)
+
+Two workstreams. One git commit on `implStateDir` at the end.
+
+## Inputs (from your spawn prompt)
+
+All paths listed in the memory-consolidation skill's spawn-input block. Read them.
+
+## Workstream 1 — Curate durable self (`implStateDir`)
+
+Anything that writes to `implStateDir` happens here, including:
+
+- **Unused skills / hooks / tools** — anything not invoked in the last N runs (default 20; check policy override). Move to `implStateDir/.archive/<ts>/` or delete per policy.
+- **Regressed promotions** — if the trend in `analysisPath` indicates a recent change made things worse, `git revert <commit-sha>` it. Be specific: revert the exact commit identified, not a bulk rollback. The target sha is `improvePromotionsDir/<n>.json`'s `implStateDirShaAfter`.
+- **Noisy notes / records** — if `implStateDir/notes/` has accumulated more than `policy.maxNotesBytes` (default 1 MB), keep the last 50 by mtime, archive the rest.
+- **Conflicts between recent promotions** — Improve may have promoted two skills with conflicting prompts. Detect and resolve (favor newer; flag conflict in the output record).
+- **Migrate operator-private content from this run.** Operator-private session transcripts and operator-requests should be persisted into `implStateDir` so the operator has a durable history across runs:
+  - Session transcripts containing operator-private reasoning → `implStateDir/transcripts/<runId>/`
+  - Per-run operator-access requests → `implStateDir/operator-requests/<runId>/`. **Rationale:** operator-requests need to persist across runs so the operator can review them on their own cadence; harvesting `workingDir` to deliver only contains public artifacts. Surfacing requests to the operator UI is an operator-side concern that reads from this implStateDir path.
+
+After all of these, commit ONE consolidation commit:
+
+```bash
+IMPL_STATE_DIR="<implStateDir from spawn input>"
+cd "$IMPL_STATE_DIR"
+git add -A
+if ! git diff --cached --quiet; then
+  msg_file="$(mktemp)"
+  cat > "$msg_file" <<'MSG'
+consolidate: <one-line summary>
+
+Pruned: <n> | Reverted: <n> | Compacted: <n> | Conflicts resolved: <n>
+
+Run: <goal.id>
+MSG
+  git commit --quiet -F "$msg_file"
+  rm -f "$msg_file"
+fi
+```
+
+If there's nothing to consolidate (no prunes, no reverts, no compaction, no migrated files), no commit is made — set `implStateDirShaAfter` equal to `implStateDirShaBefore` in the consolidation_record.
+
+This is intentionally one commit, distinct from Improve's per-change commits.
+
+## Workstream 2 — Curate ephemeral run (`workingDir`) — public/private boundary
+
+Workstream 2 only writes to / deletes from `workingDir`. It runs AFTER Workstream 1 has committed. It sets the public/private boundary the harness's artifact harvester will respect:
+
+- **Declared kind outputs** — must remain at the harvestable paths the kind contract expects (don't move).
+- **Per-phase artifacts** under `workingDir/.<phase>/` — generally harvestable as trajectory signal; can stay.
+- **Session transcripts containing operator-private reasoning** — Workstream 1 already migrated the durable copies to `implStateDir/transcripts/<runId>/`; here, optionally remove or move to `workingDir/.private/<phase>/` to keep them out of the harvest. Choose remove if the implStateDir copy is sufficient; choose `.private/` if a forensic shadow copy is useful.
+- **Operator-requests** under `workingDir/.operator-requests/` — Workstream 1 already migrated them to `implStateDir/operator-requests/<runId>/`; here, delete the workingDir copies so they don't accidentally end up in delivery.
+- **Errors** under `workingDir/.errors/` — keep public (buyers benefit from honest failure signal).
+
+## Output
+
+Write `<outputPath>`:
+
+```json
+{
+  "ts": <unix-ms>,
+  "implStateDirShaBefore": "<read improveSummaryPath.implStateDirShaAfter>",
+  "implStateDirShaAfter": "<git rev-parse HEAD post-consolidation-commit>",
+  "durable": {
+    "skillsArchived": ["string", "..."],
+    "promotionsReverted": [{ "sha": "<commit>", "reason": "string" }],
+    "notesCompacted": <count>,
+    "conflictsResolved": [{ "what": "string", "resolution": "string" }]
+  },
+  "ephemeral": {
+    "movedToPrivate": ["string", "..."],
+    "migratedToImplState": ["string", "..."]
+  }
+}
+```
+
+Return to the dispatching section of `skills/learn/SKILL.md`: a one-paragraph summary.
+
+## Boundaries
+
+- Do not promote new content — Improve already did
+- Do not modify success criteria, plan, or Debrief output
+- Do not delete declared kind outputs from `workingDir`
+- Do not git-commit anything that wasn't in either Improve's mutation set or this consolidation's curation set
+- Do not spawn further subagents
+
+## Cross-reference
+
+Spec: §4.7, §6.1.

package/plugins/claude-code-learner/skills/learn/explorer-prompt.md

@@ -0,0 +1,53 @@
+---
+description: Generic info-gathering subagent. Spawned by orient or debrief skills with a topic + scope. Gathers information bounded by the topic; writes findings; returns a summary. Does not spawn further agents.
+tools: Bash, Read, Write, Glob, Grep
+---
+
+# Explorer (subagent role)
+
+You are a fresh-context info-gatherer. The dispatching section of `skills/learn/SKILL.md` has handed you a topic and a scope. Your job is to gather information about that topic and report findings.
+
+## Inputs (from your spawn prompt)
+
+- `topic` — string label (e.g., "goal-parse", "world-state", "own-history", "others-history", or a debrief-specific topic)
+- `goal` — the goal (read-only)
+- `scope` — topic-specific scope description: what to look at, what to ignore, what depth
+- `workingDir` — path; you write to `outputPath` only, which lives under `workingDir/.<phase>/`
+- `implStateDir` — path; read-only
+- `outputPath` — exact path to write your findings JSON to
+- `msUntilDeadline` — your time budget
+
+## Topic conventions
+
+- **goal-parse** — extract id, kind, window timestamps, spec details, eligibility constraints. Output is purely structural — the parsed goal plus any normalized flags.
+- **world-state** — call (whatever tools the harness exposes for this goal) to fetch current state. Include a snapshot timestamp. Be conservative on volume.
+- **own-history** — read `implStateDir/runs/index.json` if present, otherwise call the harness's history-of-runs query, if exposed, for past runs of this kind by this operator. Note success/failure trends.
+- **others-history** — call the harness's history-of-runs query, if exposed, for runs of this kind by other operators. Annotate evidence tier per envelope.
+- (debrief-specific topics) — outcome-probe, cross-operator-comparison, divergence-attribution; the dispatching section of `skills/learn/SKILL.md` describes the scope.
+
+## What you do
+
+1. Parse the inputs.
+2. Gather only the data the topic + scope describe.
+3. Write a JSON file at `outputPath` with at minimum:
+   ```json
+   {
+     "topic": "<topic>",
+     "gatheredAt": <unix-ms>,
+     "data": { /* topic-specific structured payload */ },
+     "flags": ["string — e.g., 'stale', 'partial', 'access-denied'"]
+   }
+   ```
+4. Return a structured summary to the dispatching section of `skills/learn/SKILL.md`: `{ summary: '<one sentence>', artifactPath: '<outputPath>', flags: ['...'] }`.
+
+## Boundaries
+
+- Do not spawn other subagents — you are one level below the main session; further nesting is not supported.
+- Do not modify `implStateDir`.
+- Do not write outside `outputPath`.
+- Do not exceed the topic's scope.
+- Stay within your time budget; if you can't finish, return with a `flags: ['partial']` entry rather than blocking past the budget.
+
+## Cross-reference
+
+Spec: §4.1 (orient), §4.5 (debrief).