| name | aspirations-learning-gate |
| description | Enforces learning obligations inside the aspirations loop: the learning gate, retrieval gate, meta-learning signal, periodic reflection cadence, conclusion audit, and batch reflection. Use whenever a goal completes and the loop must verify that encoding, retrieval, and reflection actually happened before moving to the next goal. Catches sessions that ship commits without producing tree encodings or hypothesis resolutions. Internal sub-skill — never invoke directly. |
| user-invocable | false |
| parent-skill | aspirations |
| conventions | ["aspirations","tree-retrieval","retrieval-escalation","goal-schemas","working-memory"] |
| minimum_mode | autonomous |
| execution_history | {"total_invocations":0,"outcome_tracking":{"successful":0,"unsuccessful":0,"success_rate":0},"last_invocation":null} |
| revision_id | skill-bootstrap-aspirations-learning-gate-634fc1 |
| previous_revision_id | null |
/aspirations-learning-gate — Obligation Enforcement Gates
CRITICAL: This is the obligation enforcement sub-skill. It prevents the loop from
continuing without learning. If this sub-skill is skipped, knowledge debt accumulates
and the agent drifts into "busy but not learning" mode.
Abbreviation Policy
Mandatory writes for this obligation: see core/config/obligation-schema.yaml
→ obligations.learn. Abbreviation is permitted only when
context_budget.zone == tight. The zone is distance-to-autocompact, not raw
usage — see core/scripts/context-budget-status.py classify_zone for the
source of truth. Before abbreviating, Bash: bash core/scripts/context-budget-banner.sh and quote its output; the banner line
is the evidence that makes the "tight" claim verifiable. When abbreviating,
log TWO lines in the journal entry (in this order):
OBLIGATION ABBREVIATED: learn — {condition}
CTX: raw N% | of-autocompact N% | zone tight | headroom N tokens | env ... | updated ...
The banner line must be the actual output captured from the banner script in
this iteration. core/scripts/context-citation-audit.sh scans for the pair
and reports any tight-zone claim that lacks its banner line. Then satisfy
minimum_inline (sensory-buffer append OR reasoning-bank-add, then
wm-set loop_state). Otherwise invoke this Skill literally. Phase 9.5d
(below) audits the PREVIOUS iteration's abbreviation claims against the
context-budget state captured at that time; false claims accumulate in
agents/<agent>/session/obligation-audit.jsonl and 3+ in a session auto-file a
single Investigate: false-abbreviation-claims goal.
Step 0: Load Conventions — Bash: load-conventions.sh with each name from the conventions: front matter.
Inputs (from orchestrator)
goal: The executed goaloutcome_class: "routine" or "deep"goals_completed_this_session: Running counter (all goals)productive_goals_this_session: Running counter (productive outcomes only)batch_mode: Boolean (was this a batched execution?)prefetch_goals: Any pre-fetched research resultsgoals_since_last_tree_update: From session_signals — encoding drift counter
Outputs (to orchestrator)
all_gates_passed: Booleanmeta_signals_captured: Count of meta-learning signals
Phase 9.5: Learning Gate
For routine outcomes: Explicit bypass — no tree encoding needed.
For deep outcomes: The loop MUST NOT continue without confirming learning occurred.
IF outcome_class == "routine":
Log: "▸ Learning gate: PASS — routine outcome, no encoding needed"
ELIF outcome_class == "deep":
# Deep tier: tree write should have happened inline. Verify it did.
# Check 1: Was knowledge tree updated? (State Update Step 8)
# If no: complete it NOW — read _tree.yaml, find matching node,
# compress goal insight, edit node .md, propagate up chain.
# Check 2: Was journal entry written? (State Update Step 7)
# Check 3: Was working memory updated with goal context?
Bash: wm-read.sh active_context --json
# Verify active_context reflects current goal execution.
# ── HARDENED ESCAPE HATCH ─────────────────────────────────────────
# "No tree encoding needed" requires STRUCTURAL justification, not self-assessment.
# Valid reasons: goal was blocked/skipped, goal produced <100 chars of output,
# or encoding was coordination-deferred (queued to prevent multi-agent overwrite).
# Invalid: "findings already known", "nothing new" (for investigation goals).
IF tree_was_NOT_updated:
# Check if encoding was coordination-deferred (not a learning failure)
Bash: wm-read.sh encoding_queue --json
last_eq = encoding_queue[-1] if encoding_queue else null
IF last_eq AND last_eq.source_goal == goal.id AND last_eq.source_type == "coordination_deferred":
Log: "▸ Learning gate: PASS — encoding queued (coordination deferred to prevent overwrite)"
ELSE:
Bash: wm-read.sh sensory_buffer --json
related_items = [item for item in sensory_buffer
if item.encoding_score >= 0.40
AND (item.source_goal == goal.id OR item.category == goal.category)]
IF len(related_items) > 0:
Output: "▸ LEARNING GATE: rejected 'no insight' claim — {len(related_items)} high-value buffer items found for {goal.category}"
top = max(related_items, key=encoding_score)
node=$(bash core/scripts/tree-find-node.sh --text "{top.target_article or goal.category}" --leaf-only --top 1)
Read node.file
Compress top.observation into "Key Insights" section (1-3 sentences)
Edit node.file with updates
# T21 PostToolUse hook auto-bumps last_updated — no explicit
# `tree-update.sh --set last_updated` call required.
Output: "▸ LEARNING GATE: forced encoding to {node.key}"
ELIF goal produced <100 chars of output OR goal.status in (blocked, skipped):
Log: "▸ Learning gate: PASS — no encoding needed (insufficient output or blocked goal)"
ELSE:
Log: "▸ LEARNING GATE WARNING: no tree update despite substantive output — flagging as knowledge debt"
echo '{"node_key": "general", "reason": "deep_outcome_without_encoding", "source_goal": "'"${goal.id}"'", "priority": "HIGH", "created": "'"$(date +%Y-%m-%d)"'"}' | Bash: wm-append.sh knowledge_debt
# ── End hardened escape hatch ─────────────────────────────────────
Phase 9.5a: Meta-Learning Signal Capture
One question: "Did the way I learned from this goal suggest a better procedure?"
IF meta_insight_detected:
echo '{"date":"<today>","event":"meta_signal","goal_id":"<goal.id>",
"insight":"<insight>"}' | bash core/scripts/meta-log-append.sh
Phase 9.5b: Retrieval Gate (MANDATORY — runs for ALL outcomes)
Verify retrieval happened and utilization feedback completed.
NOTE: The utilization-gate.sh PreToolUse hook (Layer 3 programmatic enforcement)
handles the critical path — it auto-applies --all-unknown feedback before
state-update if Phase 4.26 was skipped. (Pre-2026-05-07 this used --all-noise,
which silently poisoned times_noise on unattested-but-relevant nodes.) This gate
is now a secondary check for escalation quality and retroactive retrieval when
retrieval itself was skipped entirely.
# Check session file first (primary source), fall back to WM manifest (legacy)
SESSION_FILE="agents/<agent>/session/retrieval-session.json"
IF session file exists:
IF utilization_pending == true:
# Hook should have caught this — run feedback as safety net
Bash: utilization-feedback.sh --goal {goal.id} --all-unknown
Output: "▸ RETRIEVAL GATE: forced utilization feedback for {goal.id}"
# else: already processed by Phase 4.26 or hook — pass
ELIF goal.category maps to existing tree nodes:
# RETRIEVAL WAS SKIPPED ENTIRELY — no session file written
Bash: load-execute-protocol.sh → IF path returned: Read it
Follow retrieval steps, then run Phase 4.26 utilization feedback
Output: "▸ RETRIEVAL GATE: forced retroactive retrieval for {goal.id}"
# Escalation quality check (per retrieval-escalation convention)
# Read WM manifest for enrichment data if available
Bash: wm-read.sh active_context.retrieval_manifest --json
IF retrieval_manifest exists AND retrieval_manifest.sufficient == false:
max_tier = max(retrieval_manifest.tiers_used or [1])
IF max_tier == 1 AND goal relates to codebase work:
Output: "▸ ESCALATION GAP: Tier 1 insufficient but Tier 2 (codebase) not attempted for {goal.id}"
IF max_tier <= 2 AND goal involves external knowledge:
Bash: session-mode-get.sh
IF mode != reader:
Output: "▸ ESCALATION GAP: Tiers 1-2 insufficient but Tier 3 (web) not attempted for {goal.id}"
# Escalation gaps are logged as learning signals for reflection, not hard blockers.
# ── Memory-utility curation scan (advisory, cadenced — g-115-1468 / Phase 1d) ──
# HOT-PATH HOME: core/config/iteration-close-digest.md § LEARNING-GATE bullet 7.
# This SKILL.md is the full-protocol copy for /boot, consolidation, and edge
# cases — NOT the hot path; keep both in sync. The earn-the-keep KPI flip:
# weight "was this later retrieved AND useful?" over "how much did we write?".
IF goals_completed_this_session % 20 == 0:
Bash: export MIND_AGENT=<agent>; source core/scripts/_paths.sh
FOR store in (reasoning-bank, guardrails):
Bash: py -3 core/scripts/retrieval_utility_report.py --store "$WORLD_DIR/{store}.jsonl"
# From each report: zero_hit_high_exposure (retrieved >=5x, never helpful —
# noise) + never_retrieved (dead weight). Write counts + a capped sample
# (first 25 ids each, per store) to the memory_curation_candidates WM slot
# (overwrite) for /reflect --curate-memory.
echo '{"reasoning-bank": {...}, "guardrails": {...}, "scanned_at": "<iso>"}' | Bash: wm-set.sh memory_curation_candidates
# ADVISORY ONLY — NEVER auto-retire (guard-707): low times_helpful is usually
# under-attestation, not zero value; retirement is a /reflect-gated decision.
# If goal genuinely has no matching tree nodes: pass silently.
Phase 9.5-exp: Experience Archival Gate (MANDATORY for deep outcomes)
Verify Phase 4.25 experience archival completed for non-routine outcomes.
IF outcome_class == "deep":
Bash: wm-read.sh active_context.experience_refs --json
IF experience_refs is empty, missing, or null:
Output: "▸ EXPERIENCE GATE CATCH: Phase 4.25 skipped for {goal.id} — writing recovery record"
experience_id = "exp-{goal.id}-recovery"
Write agents/<agent>/experience/{experience_id}.md with:
- Goal: {goal.title}
- Outcome: {outcome_summary}
- Note: Recovery record — Phase 4.25 was skipped during execution.
Full reasoning trace not available.
echo '<experience-json>' | bash core/scripts/experience-add.sh
Experience JSON:
id: "{experience_id}"
type: "goal_execution"
created: "{ISO timestamp}"
category: "{goal.category}"
summary: "Recovery: {goal.title} — {outcome_summary}"
goal_id: "{goal.id}"
tree_nodes_related: []
verbatim_anchors: []
content_path: "agents/<agent>/experience/{experience_id}.md"
Output: "▸ EXPERIENCE GATE: recovery record written"
ELSE:
Log: "▸ Experience gate: PASS"
Phase 9.5c: Unreflected Hypothesis Check (MANDATORY for all outcomes)
Bash: pipeline-read.sh --unreflected 2>/dev/null | python3 -c "import sys,json; d=json.load(sys.stdin); print(len(d))"
IF unreflected_count > 0:
Output: "▸ UNREFLECTED HYPOTHESES: {unreflected_count} resolved but unlearned"
invoke /review-hypotheses --learn
Phase 9.5d: Abbreviated-Obligation Audit (NON-BLOCKING)
Audit is performed by abbreviated-obligation-audit.sh --apply. The script
parses today's journal, regex-matches OBLIGATION ABBREVIATED: claims in
the current iteration's section, validates each against
obligation-schema.yaml + iteration-checkpoint.json, appends records to
agents/<agent>/session/obligation-audit.jsonl, and flags threshold_breached
when cumulative false claims reach the configured threshold.
Bash: bash core/scripts/abbreviated-obligation-audit.sh --apply
Read JSON result:
flags = []: no false claims; proceed
flags = ["false_claims"]: false claim(s) this iter — log, continue (non-blocking)
flags = ["false_claims", "threshold_breached"]:
file ONE `Investigate: false-abbreviation-claims`
goal if investigate_goal_already_exists is false
On threshold_breached, the LLM caller files the
Investigate: false-abbreviation-claims goal (script emits the flag; goal
creation stays with the LLM per the capability-before-user routing). Per-claim
detail is always logged to agents/<agent>/session/obligation-audit.jsonl
regardless of threshold state.
Why NOT read agents/<agent>/session/context-budget.json in the audit: it is
rewritten every statusLine fire. The banner line embedded in the journal
entry (captured AT claim time by context-budget-banner.sh) is the only
faithful claim-time capture. See rb-313, guard-301.
Post-Batch Reflection (when batch_mode is true)
Quick structured pause after all batch goals complete:
1. What patterns or connections emerged across the batch goals?
2. Any surprises or corrections that should become hypotheses?
→ If yes: add to working memory encoding_queue
3. Any knowledge tree nodes that need reconciliation across batch findings?
echo '<observation_json>' | Bash: wm-append.sh sensory_buffer
If any surprise > 7: form session-level hypothesis via pipeline-add.sh
Time budget: 1-2 minutes, not a deep reflection.
Phase 9.7: Periodic Reflection Checkpoint (every 5 goals)
IF goals_completed_this_session % 5 == 0:
# 5-question inline pause:
1. What patterns have I seen across the last 5 goals?
2. Any recurring surprises or corrections? → pipeline-add.sh
3. Any knowledge nodes growing stale? → wm-append.sh knowledge_debt
4. Conclusion audit: scan conclusions slot for stale/weak judgments
5. Encoding frequency check: how many goals since last tree update?
# Q5 Encoding Drift Detector:
# Uses the orchestrator's goals_since_last_tree_update counter (passed via inputs).
# Also checks encoding_queue and sensory_buffer for accumulated unencoded items.
IF goals_since_last_tree_update >= 3:
Output: "▸ ENCODING DRIFT DETECTED: {goals_since_last_tree_update} goals without tree update"
Bash: wm-read.sh sensory_buffer --json
Bash: wm-read.sh encoding_queue --json
high_value_items = [item for item in (sensory_buffer + encoding_queue)
if item.encoding_score >= 0.40]
IF len(high_value_items) > 0:
top = max(high_value_items, key=encoding_score)
node=$(bash core/scripts/tree-find-node.sh --text "{top.target_article or top.category}" --leaf-only --top 1)
IF node found:
Read node.file
Compress top.observation into "Key Insights" section (1-3 sentences)
Edit node.file with updates
# T21 PostToolUse hook auto-bumps last_updated.
Output: "▸ ENCODING DRIFT RECOVERY: forced encoding to {node.key} (score {top.encoding_score:.2f})"
ELSE:
echo '{"node_key": "general", "reason": "encoding_drift_checkpoint", "source_goal": "periodic-5-goal", "priority": "HIGH", "created": "'"$(date +%Y-%m-%d)"'"}' | Bash: wm-append.sh knowledge_debt
Output: "▸ ENCODING DRIFT WARNING: no encodable items found — logged HIGH-priority knowledge debt"
# Q6: Tree growth check (are decompose candidates accumulating?)
Bash: tree-read.sh --decompose-candidates
IF candidates output is non-empty (at least 1 candidate):
Output: "▸ TREE GROWTH CHECK: {len(candidates)} nodes ready for decomposition"
Invoke /tree maintain
Log: "TREE GROWTH: triggered /tree maintain from learning gate ({len(candidates)} candidates)"
# Q4 Conclusion Audit Detail:
Bash: wm-read.sh conclusions --json
FOR EACH conclusion:
# Re-verify stale blocking conclusions
IF conclusion.re_verify_at AND now >= re_verify_at AND outcome is null:
IF conclusion.blocks_goals is non-empty:
Run independent re-probe
IF contradicts: update outcome = "wrong", clear blockers
ELSE: extend re_verify_at += 30 minutes
# Flag low-evidence conclusions
real_signals = count(e for e in evidence if e.weight > 0)
IF real_signals < 2 AND blocks_goals non-empty AND outcome is null:
Log: "WEAK CONCLUSION: '{conclusion}' — {real_signals} signal(s) but blocks {N} goals"
echo '<observation_json>' | Bash: wm-append.sh sensory_buffer
Phase 9.8: Full-Cycle Reflection Obligation (every 15 productive goals)
Mandatory deep learning checkpoint that fires based on goal count, not goal selection.
This prevents full-cycle reflection from being perpetually deferred by higher-scoring
productive work in the goal selector.
# Threshold from meta/reflection-strategy.yaml → mode_preferences.full_cycle_cadence_goals (default 15)
IF productive_goals_this_session > 0 AND productive_goals_this_session % full_cycle_cadence_goals == 0:
# Team-aware deferral: if an orchestrator agent is active, defer to it
Bash: board-read.sh --channel coordination --since 1h --json 2>/dev/null
IF output contains messages from a non-self agent (e.g., "bravo"):
Log: "DEFERRED: full-cycle reflection — orchestrator agent active"
ELSE:
Output: "▸ REFLECTION OBLIGATION: 15 productive goals reached — running full-cycle"
invoke /review-hypotheses --learn (catch up on unreflected)
invoke /reflect --full-cycle (patterns, calibration, strategy)
Log: "OBLIGATION: full-cycle reflection after {productive_goals_this_session} productive goals"
Pre-Fetched Research Application
IF prefetch_goals had agents dispatched:
FOR EACH completed team agent research report:
Store findings as pre-gathered context for the goal
Execute goal with enriched context
Run full Phase 4-9 cycle for each prefetched goal
Shutdown team agents
Bash: pending-agents.sh deregister-team --team "research-{session}"
Loop Re-Entry (MANDATORY — last action of this skill)
After ALL gates and checks above are complete, this skill is the LAST phase of the
iteration. It MUST end with LOOP_CONTINUE to re-enter the aspirations loop.
# LOOP_CONTINUE: read-merge-write loop_state, then re-invoke the loop.
# This is the mechanical heartbeat — without this tool call, the session dies.
#
# READ-MERGE-WRITE, never a bare overwrite (g-115-1072). The bash gates
# (loop-state-bump-counters.py Phase 8; recurring-loop-state-mutate.py) are the
# SINGLE WRITERS for the counters + most signals — they wrote authoritative
# values to the WM FILE this iteration, invisible to the orchestrator's in-memory
# copy (synced at Phase -0.5). A bare `echo '<loop_state as JSON>' | wm-set.sh
# loop_state` from stale variables REVERTS them (goals_completed 47→46, dropped
# counted_goals). Slot-specific, so siblings like pending_phase_6_spark survive —
# the exact reversion signature. g-283 retired the per-iteration mirror but left
# THIS overwrite; this completes it. Same pattern as aspirations-all-blocked Step
# B3 and recurring-close.sh:166-170's documented contract.
Bash: wm-read.sh loop_state --json
merged = current_loop_state # fresh — carries bash-gate counters + signals
# g-115-1561: evolutions / last_evolution_at / alignment_check_at / touched are
# now BASH-OWNED (loop-state-bump-counters.py: --goal-id increments alignment +
# touched every close; --reset-alignment at aspirations-select; --evolution-fired
# at aspirations-evolve). They are NO LONGER overlaid here — overlaying the
# in-context copies would CLOBBER the bash writes (e.g. select fires
# --reset-alignment → disk=0 → iteration-close --goal-id → disk=1; a stale
# in-context overlay of 0 reverts it). The four were orphaned BECAUSE this
# LLM overlay was unreliable (zeta g-115-1557: touched=[] universally despite
# 68-76 goals); bash ownership is the fix. Only the circuit-breaker pair below
# stays LLM-owned (no bash writer yet — tracked separately).
# Mutate signals IN PLACE (preserve bash-owned subkeys — routine_*, productive_streak,
# *_cooldown_streak, *_tree_update; never replace merged.signals wholesale):
merged.signals.consecutive_goal_failures = session_signals.consecutive_goal_failures
merged.signals.last_failed_goal_id = session_signals.last_failed_goal_id
echo '<merged as JSON>' | Bash: wm-set.sh loop_state
Skill('aspirations') with args='loop'
NEVER end this skill with text output like "Returning to orchestrator."
NEVER skip the Skill() call. The orchestrator does NOT continue after this skill —
control flows directly from here to the next iteration via LOOP_CONTINUE.
Chaining
- Called by:
/aspirations orchestrator (Phase 12, every iteration — last phase before loop re-entry)
- Calls:
wm-read.sh, wm-append.sh, meta-log-append.sh, pipeline-add.sh, pipeline-read.sh, load-execute-protocol.sh, experience-add.sh (Phase 9.5-exp), /review-hypotheses --learn (Phase 9.5c)
- Returns: Does NOT return to orchestrator — calls LOOP_CONTINUE directly
- Reads: Working memory, retrieval manifest, conclusions
Return Protocol
See .claude/rules/return-protocol.md — last action must be a tool call, not text.
Structurally safe: the terminal action is LOOP_CONTINUE (Skill call to /aspirations
with args='loop'). Never add a text summary after LOOP_CONTINUE.
