/moai-harness-learner

name: moai-harness-learner
description: Harness learning subsystem coordinator. Produces Tier 4 auto-update proposal payloads consumed by the orchestrator (which surfaces them via AskUserQuestion) and orchestrates Apply/Rollback flows. Triggers when harness learning proposals are pending or learning lifecycle management is needed.
when_to_use: >
  Use for harness learning lifecycle management: producing Tier 4 auto-update
  proposal payloads for the orchestrator (surfaced via AskUserQuestion), and
  coordinating Apply/Rollback flows when learning proposals are pending.
allowed-tools: Bash,Read,Write,Edit
user-invocable: false

moai-harness-learner

<!-- @MX:NOTE: [AUTO] this skill body is preserved unchanged per the harness foundation policy §10 exclusion #10 (text annotation only, no behavioral change). The 4-tier observation/heuristic/rule/auto_update ladder defined here is preserved verbatim. The orchestrator-only AskUserQuestion contract is asserted by the harness foundation policy (cross-reference: .claude/rules/moai/core/agent-common-protocol.md § User Interaction Boundary). The downstream replacement of the frequency-count classifier with an embedding-cluster algorithm is deferred to the harness classifier-upgrade policy. -->

Coordinator skill for the Harness Learning Subsystem. The harness foundation policy is the active contract; the 4-tier ladder from the earlier harness-learning policy is preserved unchanged. Produces Tier 4 auto-update proposal payloads consumed by the MoAI orchestrator; the orchestrator surfaces them to the user via AskUserQuestion and orchestrates Apply/Rollback flows. Canonical contract: `.claude/rules/moai/core/askuser-protocol.md § Orchestrator-Subagent Boundary`.

Quick Reference

**Role**: Orchestrator-side bridge between CLI (`moai harness`) and AskUserQuestion.

**Key constraint** [HARD]: `moai harness apply` returns a JSON payload representing a Tier 4 auto-update proposal. This skill produces the payload; the orchestrator surfaces it via `AskUserQuestion`. The CLI itself does NOT prompt the user. Canonical contract: `.claude/rules/moai/core/askuser-protocol.md § Orchestrator-Subagent Boundary`.

**Common triggers**:

• `moai harness status` — check tier distribution and pending proposals
• `moai harness apply` — load next pending proposal (returns JSON payload)
• `moai harness rollback <date>` — restore snapshot
• `moai harness disable` — set learning.enabled: false

**Workflow**: 1. Run `moai harness status` to inspect state. 2. Run `moai harness apply` to get the proposal payload. 3. Hand payload to the orchestrator for `AskUserQuestion` surfacing (approve / reject). 4. On approve: write approval to proposals dir and signal CLI to proceed. 5. On reject: remove proposal file (no changes applied).

---

Implementation Guide

Step 1: Status Check

moai harness status --project-root <project_root>

Output includes:

• `enabled` state
• Tier distribution (observation / heuristic / rule / auto_update)
• Rate limit window status
• Number of pending proposals

Step 2: Fetch Proposal Payload

moai harness apply --project-root <project_root>

The command outputs a JSON block with:

• `id` — proposal identifier
• `target_path` — file to be modified
• `field_key` — `description` or `triggers`
• `new_value` — proposed new content
• `pattern_key` — what triggered this proposal
• `observation_count` — how many times this pattern was observed

Step 3: Produce structured payload for orchestrator consumption

[HARD] This skill produces a structured payload representing the Tier 4 auto-update proposal; the MoAI orchestrator surfaces it via `AskUserQuestion`. Canonical contract: `.claude/rules/moai/core/askuser-protocol.md § Orchestrator-Subagent Boundary`.

**Payload schema**:

• `proposal_id` — proposal identifier
• `target_path` — file to be modified
• `field_key` — `description` or `triggers`
• `current_value` — existing content (for diff context)
• `new_value` — proposed new content
• `observation_count` — pattern observation count
• `confidence` — auto-update confidence score (0.0–1.0)
• `recommended_action` — `approve` (default) | `reject` | `inspect` | `defer`

The skill emits this payload as its tool output. The orchestrator reads the payload, preloads `AskUserQuestion` via `ToolSearch(query: "select:AskUserQuestion")`, and surfaces the four-option decision (approve / reject / inspect / defer) to the user. On user approval, the orchestrator re-delegates to this skill with `action=apply`; on rejection, `action=skip`. The "(권장)" recommendation suffix and per-option descriptions are constructed by the orchestrator from the payload's `recommended_action` field per `askuser-protocol.md § Socratic Interview Structure`.

Step 4: On Approve

Without `--execute`, `moai harness apply` only surfaces the payload. The write happens on the opt-in execute path (`Applier.Apply()`), gated by the 5-Layer Safety Pipeline, and `--execute` requires `--id` — the proposal it applies is named explicitly, never inferred from "the next pending one".

For the coordinator skill, the simplest flow is: 1. User selects "approve" 2. Write `approved: true` to `.moai/harness/proposals/<id>.decision` 3. Run the execute path, naming the approved proposal id and the project root the write targets:

moai harness apply --execute --id <proposal-id> --project-root <project_root>

`--project-root` defaults to the current directory. Pass it explicitly when the session is working inside a worktree — its value is that worktree's own `git rev-parse --show-toplevel`, so the write lands in the tree the proposal was raised against rather than in the primary checkout.

Step 5: On Reject

1. Delete `.moai/harness/proposals/<id>.json` 2. Confirm deletion to user.

Rollback Flow

# List available snapshots
ls .moai/harness/learning-history/snapshots/

# Rollback to a specific snapshot
moai harness rollback 2026-04-27T00-00-00.00