arc-learning

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 but do not read or write the candidate queue — use the dashboard instead.

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 or CLI.
• 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 refuses to overwrite existing active artifacts.
• Duplicate suppression. The curator should not append semantic duplicate candidates for the same learned behavior.

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.
• 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 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.