arc-learning

name	arc-learning
description	Run the opt-in learning lifecycle: turn observations into reviewable candidates, inactive drafts, then explicitly activated instincts. Use when the default-off learning module is enabled and observations should become artifacts.
category	memory
status	promoted

Optional Learning Candidate Lifecycle

Overview

arc-learning turns repeated project observations into reviewable learning candidates. Learning is disabled by default, automatic once enabled, and conservative at every behavior-change boundary.

Position: observations → candidate queue → dashboard review → inactive drafts → explicit activation → active artifacts

The primary interface for reviewing and acting on candidates is the dashboard (arcforge learn dashboard). Candidates are queued automatically by the observer daemon's LLM curator; the dashboard is where the human reviewer approves, dismisses, materializes, activates, promotes, or deactivates them.

The default scope is project-local. Promotion to global scope is an explicit dashboard action; silent auto-promotion to global remains unsupported — the dashboard's Promote action is the only path, and it requires explicit user authorization.

Quick Reference

Primary surface — dashboard-driven:

Task	Command
Check config	arcforge learn status [--json]
Enable project learning	arcforge learn enable --project
Disable project learning	arcforge learn disable --project
Open review dashboard	arcforge learn dashboard [--port N]

Once the daemon is running and learning is enabled, the dashboard is where all candidate review and lifecycle actions happen (Approve, Dismiss, Materialize, Activate, Deactivate, Promote, Evolve). The dashboard reads from ~/.arcforge/learning/candidates/queue.jsonl (the canonical Layer 5 queue produced by the LLM curator). See docs/guide/learning-dashboard.md for the full operational guide.

Retired / Deprecated CLI commands

Legacy arcforge learn analyze|review|inbox|approve|reject|materialize|activate|inspect|drafts subcommands remain in the CLI. Under --project scope they read/write a project-local queue that the dashboard and curator never touch — informational only, safe to ignore. Under --global scope, review|inbox|inspect|drafts read the same canonical ~/.arcforge/learning/candidates/queue.jsonl file the curator populates (verify: getCandidateQueuePath({scope:'global'}) in ${ARCFORGE_ROOT}/scripts/lib/learning.js resolves to the identical path as the curator's ${ARCFORGE_ROOT}/scripts/lib/learning-curator/queue-writer.js) and remain read-only informational in that scope; approve|reject|materialize|activate --global now throw and refuse to run outright, since they would otherwise rewrite that file wholesale without acquiring the curator's store.lock — use the dashboard instead of any legacy subcommand, in either scope.

Use --json on any command when another tool or test needs machine-readable output.

Workflow

1. Confirm enablement. Run arcforge learn status [--json]. Learning is disabled by default for both project and global scopes.
2. Enable only when requested. Run arcforge learn enable --project for project-local learning. After enablement, the observer daemon assembles evidence batches, calls the LLM curator, and automatically queues pending candidates in the candidate queue.
3. Automatic candidate queueing. Once enabled, the daemon's LLM curator converts batched observations into pending candidates. The automatic trigger only appends candidate records; it does not approve, materialize, activate, tag, push, publish, or change runtime behavior.
4. Review via dashboard. Run arcforge learn dashboard to open the browser control plane at http://localhost:3334. The dashboard is the canonical review surface.
5. Approve or dismiss. Use the dashboard [Approve] or [Dismiss] action. Approval is required before any artifact is written.
6. Materialize as inactive drafts. Use the dashboard [Materialize] action. Draft artifacts are written to ~/.arcforge/learning/drafts/<candidate-id>/<materialization-id>/instincts/<name>.md — these are inactive review files; they are not loaded into Claude context.
7. Inspect before activation. Open the candidate card on the dashboard; preview the draft body before activating.
8. Explicit activation. Use the dashboard [Activate] action only after reviewing the draft. Activation copies the draft to ~/.arcforge/instincts/<project>/<candidate-id>.md (project scope) or ~/.arcforge/instincts/global/<candidate-id>.md (global scope), with supersede_with_backup if an active artifact already exists at that path. Once activated, the instinct is injected at SessionStart through that activation gate only — the top 5 by confidence (sort/cap, not a threshold), with an inject_activated_instincts kill-switch (default ON). Non-activated candidates are never injected.

Candidate Lifecycle Statuses

The full set of statuses a candidate moves through:

Status	Meaning
pending_review	Queued by LLM curator, awaiting human review
needs_more_evidence	Flagged for more evidence before approval
approved	Human-approved, ready to materialize
materialized	Inactive draft artifact(s) written under ~/.arcforge/learning/drafts/<cid>/<mid>/, ready to activate
activated	Draft promoted to active instinct file under ~/.arcforge/instincts/<scope>/<cid>.md
deactivated	Previously activated, now deactivated
dismissed	Rejected; no artifacts written
superseded	Replaced by an evolved candidate

Key Principles

• No active behavior change without explicit activation. Pending candidates and inactive drafts do not affect runtime behavior.
• Project scope first. Project learning writes project-local config, queues, and drafts. Promotion to global scope is an explicit dashboard action; silent auto-promotion to global remains unsupported.
• Human authorization at gates. The LLM curator proposes; users approve/reject, materialize, and activate via dashboard.
• Redacted durable evidence. Observations are sanitized before persistence; candidate evidence stores review-safe summaries, not raw tool payloads.
• Fail closed for artifact writes. Materialization requires approval; activation requires materialized drafts and defaults to supersede_with_backup; only refuses when the policy is not supersede_with_backup.
• Duplicate suppression. The curator should not append semantic duplicate candidates for the same learned behavior.

Observer Daemon & Behavioral Instincts

The candidate queue is fed by a background observer daemon that runs as a four-layer orchestrator: (1) hooks/observe/main.js captures every tool call to ~/.arcforge/observations/{project}/observations.jsonl; (2) the daemon assembles recent observation windows into a batch; (3) it invokes the LLM curator (claude --model haiku --print --output-format json) to produce candidate proposals; (4) it ingests those proposals into the review queue. The daemon never writes instinct .md files directly — only the dashboard's activation gate does.

Set SKILL_ROOT from ARCFORGE_ROOT (fallback default below when unset):

: "${ARCFORGE_ROOT:=$HOME/.agents/arcforge}"
: "${SKILL_ROOT:=$ARCFORGE_ROOT/skills/arc-learning}"
if [ ! -d "$SKILL_ROOT" ]; then
  echo "ERROR: SKILL_ROOT=$SKILL_ROOT does not exist. Set ARCFORGE_ROOT or SKILL_ROOT manually." >&2
  exit 1
fi

Task	Command
Daemon status	bash "${SKILL_ROOT}/scripts/observer-daemon.sh" status
Start daemon	bash "${SKILL_ROOT}/scripts/observer-daemon.sh" start
Stop daemon	bash "${SKILL_ROOT}/scripts/observer-daemon.sh" stop
View instincts	node "${SKILL_ROOT}/scripts/instinct.js" status --project {p}
Confirm pattern	node "${SKILL_ROOT}/scripts/instinct.js" confirm {id} --project {p}
Contradict pattern	node "${SKILL_ROOT}/scripts/instinct.js" contradict {id} --project {p}

Confirming / Contradicting

When a user agrees or disagrees with an auto-detected pattern: run the confirm/contradict CLI, show the updated confidence, and explain the change. Always offer the chance to validate or reject — do not present instincts as fixed.

Confidence Lifecycle

Confidence is metadata on the candidate / activated instinct record. It does not drive runtime auto-loading; it informs which records the dashboard and arc-recalling surface.

Auto-detected by daemon: confidence 0.5
Confirmed → +0.05 (cap 0.9)
Contradicted → -0.10 (floor 0.1), -0.05 for manual/reflection sources
No activity → -0.02/week, -0.01/week for manual/reflection sources

>= 0.7 → Surfaced prominently in dashboard / arc-recalling
0.3-0.7 → Listed as summary
< 0.3 → Silent;  < 0.15 → Archived

Daemon Safety

• Re-entrancy guard: checks a .analyzing.lock file (30-minute stale TTL) before running the LLM curator; concurrent runs are blocked automatically.
• Watchdog: OBSERVER_DAEMON_WATCHDOG_SECS (default 120s) prevents a hung curator call from blocking subsequent runs.
• Skip filter: ARCFORGE_OBSERVE_SKIP_PATHS and .eval-trials/ paths are excluded from capture to keep eval noise out of the queue.

When to Use

• The user explicitly asks to enable project learning.
• Repeated observations suggest a reusable project workflow, especially a release/preflight/checklist skill.
• You need to review, approve, reject, inspect, materialize, or activate a learning candidate.
• The user asks what patterns have been noticed, wants the instinct status view, or confirms/contradicts a detected pattern.
• You want a conservative self-improvement path that preserves human review before behavior changes.

When NOT to Use

• Learning has not been explicitly enabled.
• The user wants to save a single known preference or fact; use the appropriate memory/skill workflow instead.
• The user wants to capture session reflections (use arc-journaling) or analyze diary entries (use arc-reflecting).
• The pattern is not supported by the current learning system; keep it as a manual plan or skill change.
• The action would perform a destructive release step such as tag, push, package publish, or GitHub release creation without explicit user approval.

Legacy Compatibility

The supported surface is the arcforge learn ... lifecycle above. Do not bypass candidate approval, inactive draft materialization, or explicit activation gates with ad-hoc scripts — combining related instincts into a higher-level candidate is the dashboard's Evolve action.