Agent Skills: moai-harness-learner

moai-harness-learner

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.000000000Z --project-root <project_root>

Disable Learning

moai harness disable --project-root <project_root>

Sets learning.enabled: false in .moai/config/sections/harness.yaml. Comments and key ordering are preserved (YAML round-trip).

Works Well With

• moai-meta-harness — generates the hns-* skills that are targets of auto-updates
• moai-workflow-tdd — TDD cycle generates events that feed into the observer
• moai-foundation-quality — quality gates run after auto-updates to validate correctness

Safety Architecture Reference

The 5-Layer Safety Pipeline (L1 Frozen Guard → L2 Canary Check → L3 Contradiction Detector → L4 Rate Limiter → L5 Human Oversight) protects every Tier 4 auto-update:

| Layer | Guard | Action on violation | |-------|-------|---------------------| | L1 | Frozen Guard | Block — FROZEN paths are never modified | | L2 | Canary Check | Block — if effectiveness drops >0.10 | | L3 | Contradiction Detector | Block — if trigger conflicts arise | | L4 | Rate Limiter | Block — max 3 per week, 24h cooldown | | L5 | Human Oversight | Orchestrator surfaces user-approval via AskUserQuestion (this skill emits payload) |

[HARD] L1 Frozen paths (never auto-modified at runtime):

• ~/.claude/agents/** (template-managed agents; .claude/agents/harness/ is a user-owned allowed-write target, NOT frozen)
• ~/.claude/skills/moai-*/**
• .claude/rules/moai/**

Only user-area skills (.claude/skills/hns-*/, plus legacy .claude/skills/harness-*/ and .claude/skills/my-harness-*/ generations) and agents (.claude/agents/harness/) are valid auto-update targets.