Menu
Start or resume session - loads state and continues work
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
First-run guided onboarding (teach the register → hunt → rest loop + a consented first hunt) OR reconfigure an existing install (shells `igris configure`). Branches on `igris onboarding status`. Usage: /setup
Guided project handoff — export a project's brain slice to a portable bundle, or import one with a preview/confirm ceremony. Usage: /handoff export <project> | /handoff import <bundle>
Release preparation - changelog generation, version bumps, release notes
Show system status report - briefs, session, blockers, git status
Search the brain's learnings with hybrid BM25+vector recall - filter by project or global, show ranked results (ID/title/snippet/score), and pull a learning into context. Usage: /search <query> [--project <slug> | --global] [--pull <id>] [--limit <N>]
Implement a brief with full workflow - usage: /hunt BR-008
| name | boot |
| tier | essential |
| description | Start or resume session - loads state and continues work |
| disable-model-invocation | false |
| allowed-tools | ["Read","Write","Edit","Glob","Grep","Bash","mcp__igris-brain__igris_session_file_update","mcp__igris-brain__igris_instance_remove","mcp__igris-brain__igris_brief_sync","mcp__igris-brain__igris_brief_create","mcp__igris-brain__igris_suggestion_list","mcp__igris-brain__igris_perception_review_pending"] |
| triggers | ["BOOT","AWAKEN","start session","resume session"] |
Initialize Igris AI and resume any pending work.
Run the detection verb first and read its JSON digest:
igris detect
The digest is the lifecycle handoff from the environment into Boot:
{ "harness": "claude|codex|gemini|opencode|antigravity|cursor|unknown",
"project_slug": "igris-ai",
"project_path": "/abs/project/path",
"brain_root": "~/.igris",
"brain_db": true,
"sqlite3": true,
"remote_brain": true,
"mode": "full|degraded-no-db|degraded-no-remote" }
Carry these fields forward:
detect.harness selects the harness-specific OS context file in §2.detect.project_slug is the <slug> used by Mount verbs below.detect.project_path is the absolute project path passed to session register.detect.brain_root is the runtime brain root for context reads.detect.mode / booleans drive degraded notices only; detection never blocks boot.Read <detect.brain_root>/core/os/INDEX.md first — this is the module map for what context to load. There is no monolith to slice: each row is a self-contained module, and the modules ARE the sections.
<detect.brain_root>/core/os/INDEX.mdtier is boot except USER — read each from <detect.brain_root>/core/os/<module>.md. The SOUL row lives at <detect.brain_root>/core/SOUL.md; the USER row is visible in the map but is deferred to Login (§3).on-demand / reference modules are NOT loaded here — pull them later when their consult_when fires.Harness-specific roster, if a row's harness equals detect.harness, read <detect.brain_root>/core/os/<file> for that row. If no row matches, this is a clean no-op (native-static harnesses need no file; unknown is not an error).Always-needed files (boot mechanics, not context modules):
<detect.brain_root>/config.json - Remote brain URL and API keyDegradation: if <detect.brain_root>/core/os/INDEX.md is absent, fall back to reading <detect.brain_root>/core/SOUL.md + <detect.brain_root>/USER.md + <detect.brain_root>/config.json, display one short degraded-context notice, and continue — never block session start.
Read <detect.brain_root>/USER.md. This is the Login layer: the machine-home operator profile and preferences. It is distinct from Boot's OS core so the operator layer can vary per machine without being shipped as core OS content.
Mount starts with the remote channel so restored session files are visible before handoff selection. Run the boot-sync verb and read its JSON digest:
igris boot-sync --project <detect.project_slug>
The boot-sync digest (stdout JSON — read these fields):
{ "degraded": false, // true ⟺ remote unconfigured
"brain_pull": { "ok": true, "summary": "5 learnings, 2 errors" },
"queue_drain": { "ok": true, "drained": 3 },
"session_files_pulled": 2, // session_files rows merged from the pull
"definitions_updated": { "agents": 1, "skills": 0, "rules": 2, "prompts": 0 },
"skipped": [] } // one-line reasons any part was skipped
Display from the digest:
brain_pull.summary → "Pulled {summary} from remote brain" (when brain_pull.ok).queue_drain.drained → "Drained {n} queued sync op(s)" (when > 0).session_files_pulled / definitions_updated → optional one-line restore/refresh summary.skipped[] → surface each as a one-line notice (e.g. "Brain pull skipped (remote unconfigured)").Degradation: the verb ALWAYS exits 0 and NEVER blocks session start. When degraded: true (remote unconfigured) or any part fails (ok: false, recorded in skipped[]), display the one-line notice and continue — a missing/unreachable remote is a local-only run, not an error. Each part is independent: a failed pull does not abort the drain or vice-versa.
What replaced what (FR-195): boot-sync subsumes the former §3.6 (
igris_brain_pull), §3.6.1 (igris_sync_queue_drain), §3.6.1.1 (igris sync datalocal drain), §3.6.2 (igris_session_file_pull), and §3.6.3 (igris_definition_pull) — five separate MCP/CLI calls collapsed into one verb. The_pull(VPS→local restore) vs_list(state-aware local enumerate) distinction that mattered when the skill called both is now internal: this Mount step owns the_pullside (restore), and §4.1 gather owns the_listside (classification). They no longer share a call site to conflate.
The session model is per-instance (see session_protocol.md): every instance owns one session/instances/<instance_id>.md file, keyed by its instance_id. There is no shared CURRENT_SESSION.md. /boot does NOT read a single fixed file — it gathers: it enumerates the project's session files + the live instance registry, classifies each file (the Lock-2/3 truth table), and picks THE handoff. As of FR-195 the entire enumerate→classify→pick algorithm is OWNED by the igris session gather verb — the skill does not re-derive it.
Run the gather verb and read its JSON digest:
igris session gather --project <detect.project_slug> [--self-instance-id <recovered-id>]
--self-instance-id is OPTIONAL — pass it only if THIS harness can locate its own prior per-instance file (an instance_id persisted in the harness's working dir / $CLAUDE_PROJECT_DIR heuristics, the G4 chicken-and-egg). The common case omits it; the verb leaves self_instance_id: null and §4.4's registration mints a fresh id. Gather is an observer — it never mints, never writes a session file (Lock-2 "nothing destructive in gather").session_files + the live instances registry, applies the Lock-2/3 truth table (LIVE SIBLING / ABANDONED LIVE / GENUINE HANDOFF), handles the FR-133 legacy CURRENT_SESSION.md-adoption fall-through, picks the newest GENUINE HANDOFF, and fetches content for THAT one only.The gather digest (stdout JSON — read these fields):
{ "degraded": false,
"handoff": { // null when fresh_start (no genuine handoff)
"instance_id": "…|null", // null for a legacy CURRENT_SESSION.md row
"filename": "instances/<id>.md|CURRENT_SESSION.md",
"mode": "REST MODE|null", // the handoff file's **Mode:** line
"resume_point": "…", // feeds §5's resume display
"next_steps": "…", // seeds §4.4's LIVE file (resume carry-forward)
"is_legacy": false }, // FR-133 legacy-adoption flag
"self_instance_id": "…|null", // recovered (G4) else null → §4.4 mints
"siblings": [{ "instance_id": "…", "current_brief": "…|null", "last_active": "…" }],
"crashed": [{ "instance_id": "…", "last_active": "…", "scratchpad": "session/…" }],
"fresh_start": false } // true ⟺ handoff is null
What the digest means for display (G5):
handoff.resume_point / handoff.next_steps → feed §5's resume display (only when handoff.mode == "REST MODE"; see §5).siblings[] → render a one-line-per-entry "Active siblings" list ("instance {short_id} ({liveness_status}) on {current_brief}, last activity {last_active}"). Same-machine alive is process-proof; unknown_remote / unknown_no_metadata is a coordination fallback, not a liveness proof.crashed[] → render a one-line-per-entry "Crashed scratchpads" list ("instance {short_id} crashed mid-session — scratchpad at {scratchpad}"). This is the ABANDONED LIVE surface (§4.3.1 below is the same set — display only, NEVER destructive: no auto-archive, no ownership clear; Lock 1).self_instance_id → carry to §4.4 (recovered id to reuse, or null to mint).All gather output is display-only — nothing destructive happens. The verb writes nothing to session_files and no longer treats activity age as liveness.
Degradation: when the brain DB is absent the verb emits { "degraded": true, "fresh_start": true, "handoff": null, … } and exits 0 — treat it as a fresh start (no resume). NEVER block session start on a degraded gather.
Ordering contract: boot-sync MUST run before gather, and gather MUST run BEFORE §4.4 register and BEFORE §4.5 housekeeping. The verbs are separate processes and do NOT enforce cross-process order — the skill's call sequence (boot-sync → gather → register → housekeeping → assess) is the contract. H0's Lock-2 "the legacy row was provably read before it is archived" holds ONLY because this skill ran gather before housekeeping.
Use the persona (from SOUL) loaded in §2 and user config (from USER.md) loaded in §3:
[PERSONA GREETING FROM soul context]
My capabilities:
- Brief management, session recovery, architecture enforcement
- Quality gates, protocol enforcement
A one-time orientation for a brand-new install. Verb-driven and harness-agnostic — ZERO per-harness branches.
Run the onboarding-status verb:
igris onboarding status --json
It prints { "completed": <bool>, "boot_welcomed": <bool>, "first_run": <bool> }. first_run is !completed.
first_run == true AND boot_welcomed == false: render the compact Welcome, then mark it shown so it never repeats:
Welcome to IGRIS — an AI engineering OS that runs on your harness.
It turns intent into shipped work through a simple loop:
register (capture the work) → hunt (build it, tested + reviewed) → rest (bank the session).
New here? Run /setup for a 2-minute guided first hunt.
igris onboarding welcomed
igris onboarding status is unavailable or errors (older CLI, degraded shell), degrade silently — render nothing, never block session start.If the igris-brain MCP server is available:
igris_memory_recall with the current project slug and context="session start, current project priorities"igris_project_register to update last_session_at for this projectigris_session_recall with days=2 to see recent cross-project activity### Cross-Project Context (last 48h)
- project-a: Worked on BR-012 (auth fix), BUILDING phase
- project-b: Completed FR-005 (dark mode)
If brain MCP is not available, skip this step silently. No errors, no warnings.
Per Lock 1, liveness is display-only and NOTHING auto-destroys a stale or dead instance. This section is a display of crashed/reclaimable scratchpads — it does NOT remove anything.
A clean /rest → /boot cycle leaves nothing stale: /rest already calls igris_instance_remove in its §2.5 "Close Instance Ownership" step, so the prior instance is gone from the registry by the time /boot runs. What this section surfaces is the genuine crash case — an instance that exited without /rest.
This is purely a display of the crashed[] list the §4.1 igris session gather digest ALREADY computed (the ABANDONED LIVE set — state='live' with an absent owner or a same-machine owner proven dead by PID/start-time). No new tool call is needed; the verb did the classification.
gather.crashed[], surface it: "reclaimable, unconfirmed — instance {short_id}, liveness {liveness_status}, last activity {last_active}; scratchpad at {scratchpad}".igris_instance_remove. Do NOT auto-archive its file. Do NOT clear its current_brief. Reclaim is an explicit operator action — never automatic.If gather was degraded (empty crashed[]), render nothing. Do NOT block session start.
This is a read of genuine crashes, not a destructive sweep. Multi-instance is valid; a live sibling is left alone (it shows in the §4.1 "Active siblings" list from gather.siblings[], not here).
Registration — the instance metadata upsert + the LIVE per-instance file write — is OWNED by the igris session register verb (FR-195, extended by FR-190). It mints-or-recovers the instance_id, writes the instance row with harness/PID/start-time metadata when available, and writes session/instances/<id>.md at state='live' with the contract line shape (**Instance ID:**, **Mode:** Active, **Active Brief:**) that the phase-guard fallback and /hunt parse. It seeds the LIVE file's "Next Steps" from gather's chosen handoff so the resume context carries forward.
Run the register verb AFTER §4.1 gather (the ordering contract — gather's outputs feed register):
igris session register --project <detect.project_slug> \
[--self-instance-id <gather.self_instance_id>] \
[--project-path <detect.project_path>] \
[--seed-next-steps "<gather.handoff.next_steps>"]
--self-instance-id — pass gather.self_instance_id when it was recovered (non-null); OMIT it to mint a fresh UUID. (This is the G4 recover-or-mint decision, now resolved by gather + register together.)--seed-next-steps — pass gather.handoff.next_steps when gather selected a genuine handoff (the resume carry-forward from §4.1). Omit on a fresh start.--project-path — the absolute project directory (the instance row's project_path field).The register digest (stdout JSON — read these fields):
{ "degraded": false,
"instance_id": "…", // recovered or freshly minted
"minted": true, // false ⟺ an existing id was recovered+refreshed
"live_file": "instances/<id>.md", // relative to the project session dir
"seeded_from_handoff": true } // true ⟺ Next Steps were carried from gather's handoff
instance_id forward — it is used for subsequent igris instance state work-lease updates (/hunt) and the ownership-close on /rest, and it is the <instance_id> §7 confirms the LIVE file for.Degradation: when the brain DB is absent the verb emits { "degraded": true, … } and exits 0 — display "Instance registration skipped (brain unavailable)" and continue. NEVER block session start.
The crash-robust, idempotent archive sweep (H0–H3) is OWNED by the igris housekeeping verb (FR-195). It is NOT a daemon, NOT scheduled — it runs once per /boot, AFTER gather (§4.1) and AFTER registration (§4.4), BEFORE the assessment surface (§4.6). The verb's H0–H3 are individually crash-robust and idempotent; running it twice is harmless and a crash mid-sweep leaves a consistent state (Lock 4 — session_protocol.md §5). The header-presence guard (idempotency) and per-file append-then-delete (crash-robustness) are the exact atomicity contracts that "cannot be enforced from a skill recipe" — which is why this is CODE, not inline markdown.
Run the housekeeping verb (the ordering contract requires it AFTER boot-sync + gather + register):
igris housekeeping --project <detect.project_slug>
What the verb does (faithful to the prior inline H0–H3):
CURRENT_SESSION.md row (instance_id IS NULL) that gather provably read this /boot: flip its DB state to archived (content carried through unchanged, instance_id untouched) and move session/CURRENT_SESSION.md → session/archive/CURRENT_SESSION-<updated_at>.md. The Lock-2 "read-before-archive" invariant holds because the skill ran gather FIRST (the ordering contract).rested file is archived only when a newer rested file from a different instance proves it was consumed. An ABANDONED LIVE file is NEVER archived here.session/archive/*.md files older than 30 days into session/archive/<YYYY-MM>.md month digests (header-guarded, append-then-delete).The housekeeping digest (stdout JSON — read these fields):
{ "degraded": false,
"h0_legacy_retired": false, // true ⟺ the legacy CURRENT_SESSION.md was retired this run
"h1_archived": ["<id>-<ts>.md"], // archive filenames produced by the supersession step
"h2_rolled": 4, // individual files folded by the 30-day roll
"h3_ceiling_rolled": 0, // individual files folded by the 150-ceiling valve
"noop": false } // true ⟺ nothing was touched (the common fresh-archive case)
noop: true, render nothing.Cost guard (preserved): the verb touches ONLY session/archive/ + the RESTED set + the one legacy row — NEVER LIVE files, NEVER the brief DB, NEVER the VPS. A fresh install with an empty archive is one list query + an empty dir read; noop: true.
Degradation: when the brain DB is absent the verb emits { "degraded": true, "noop": true, … } and exits 0 — there are no session files to sweep on a fresh start. NEVER block session start.
The MINIMAL system-assessment surface — brief-status summary + active blockers + git snapshot + active-instance count + upcoming goals — is OWNED by the igris assess verb (FR-195, decision D-A). It does the brief-dashboard summary SQL, reads session/BLOCKERS.md, runs git status, counts live instances, and lists goals due within 14 days. It DELIBERATELY OMITS suggestions (§4.10) and perception pending (§4.11) — those re-introduce ceremony noise and stay as the skill's own surfaces below; assess does not cover them.
Run the assess verb and render from its JSON digest:
igris assess --project <detect.project_slug>
The assess digest (stdout JSON — read these fields):
{ "degraded": false,
"briefs": { "total": 42, "by_status": { "Ready": 8, … }, "by_priority": { "P0": 1, … } },
"blockers": ["…"], // active blockers from session/BLOCKERS.md
"git": { "branch": "develop", "dirty": true, "ahead": 0 },
"active_instances": 3,
"goals_upcoming": [{ "goal_id": "GL-003", "title": "…", "deadline": "2026-05-01", "priority": "P1" }] }
Render the assessment from the digest:
briefs.by_status / briefs.by_priority → identify Ready briefs to work on (feeds §6 recommendations); show the aggregate counts.blockers[] → surface active blockers (if any).git → "On {branch}{, dirty}{, ahead N}".active_instances → "Active Instances: {n}".goals_upcoming[] → see §4.9 (the goals surface is now part of this digest).Degradation: when the brain DB is absent the verb emits { "degraded": true, "briefs": {total:0,…}, "goals_upcoming": [], "active_instances": 0, … } and exits 0 — it STILL reads blockers + git (those do not need the DB). NEVER block session start.
The project-context-docs presence check is a SOFT nudge, not a gate. It is owned
by the shared CLI primitive; /boot only renders the short signal.
Run:
igris context-docs inventory --project <detect.project_slug> --json 2>/dev/null || true
Read only these fields from the JSON digest:
{ "degraded": false,
"missing_applicable": ["api_pattern", "test_standards"],
"remediation": ["/ground api_pattern", "/ground test_standards"] }
If degraded is false and missing_applicable[] is non-empty, render exactly
one short line:
Context docs: missing applicable docs — /ground api_pattern · /ground test_standards
If the list is empty, unknown-only, the command is unavailable, or the JSON is
unparseable, render nothing. NEVER block boot, never author docs automatically,
and do not re-implement the applies_when logic here.
Run the existing CLI diagnostic in read-only mode after the regular assessment, with a short timeout so boot cannot hang:
timeout 5s igris doctor 2>/dev/null || true
Parse only the markdown drift table rows (| slug | path | drift-class | recommended-fix |). Count rows whose drift-class is not clean, and count the unique non-clean drift classes.
Render exactly one line when non-clean rows exist:
Igris Doctor: {issue_count} issue(s) across {class_count} drift class(es) - run /igris-doctor.
If the count is zero, render nothing. If igris doctor is unavailable, slow, or its output is unparsable, skip this section silently. /boot must never block on diagnostics, must never run igris doctor --fix, and must not reimplement doctor checks; the CLI verb remains the engine.
The upcoming-goals surface is now part of the §4.6 igris assess digest (goals_upcoming[] — active goals with a deadline within 14 days). Do NOT make a separate goal call; render from the digest.
For each entry in assess.goals_upcoming[], render:
## Goals approaching deadline
- GL-003 "Ship v6.1" — due 2026-05-01 (P1)
- GL-001 "Compliance audit" — due 2026-05-12 (P1)
Each entry carries goal_id / title / deadline / priority. (The prior "N briefs serving" sub-line is dropped — the assess digest is the MINIMAL D-A surface and does not carry serving_briefs_count; run /scan for full goal progress.)
If goals_upcoming[] is empty, render nothing — no "No goals" line. Token budget: ~120 tokens.
TD-102 / FR-118 / FR-191 (V7.1): This entire section is gated behind the
cognition.subconscious.enabledconfig flag, which defaults tofalse. The old rule-based engine had a 2% true-positive rate; FR-118 SHIPPED the redesign — the subconscious is now a cognition instance (digest → isolated LLM call → open-typed suggestions), and the rule detectors were deleted. Re-enable is just a flag flip — no schedule re-bootstrap needed.
Read <detect.brain_root>/config.json and check cognition.subconscious.enabled. If the
key is absent, treat as false. If false, skip this section silently — render
nothing (no suggestion MCP tools, no failure WARNING, no "disabled" notice).
Resume reading at §4.11.
Mirroring §4.11's perception failure pre-step. Before rendering the pending
suggestions, query the latest subconscious run so a recent LLM-run failure
surfaces prominently. The engine writes its lifecycle to event_log directly
under the cognition.subconscious component (NOT the legacy subconscious.*
bus events). Read the local DB via sqlite3 (same TD-080 rationale: the local
DB is the merged superset post-§4 pull; the igris_event_log MCP routes to
the remote and would miss this machine's local-only runs). The subconscious
runs whole-brain (no per-project slug), so this query is NOT slug-scoped:
command -v sqlite3 >/dev/null 2>&1 || return 0 # skip WARNING silently if absent
sqlite3 "<detect.brain_root>/memory/knowledge.db" \
"SELECT created_at, event_name, json_extract(payload, '\$.reason') AS reason
FROM event_log
WHERE component = 'cognition.subconscious'
ORDER BY created_at DESC LIMIT 1;" 2>/dev/null || true
If the latest row's event_name is 'cognition.subconscious.run_failed' AND no
later 'cognition.subconscious.run_succeeded' row exists (defensive follow-up
to confirm the failure has not self-recovered), prepend a single WARNING block.
The "no later success" check (substitute the failed row's created_at):
command -v sqlite3 >/dev/null 2>&1 || return 0
sqlite3 "<detect.brain_root>/memory/knowledge.db" \
"SELECT COUNT(*) FROM event_log
WHERE component = 'cognition.subconscious'
AND event_name = 'cognition.subconscious.run_succeeded'
AND created_at > '<failed_row_created_at>';" 2>/dev/null || true
A return of 0 confirms the failure is the latest terminal state.
## Subconscious WARNING
Latest subconscious run FAILED at 2026-06-24 06:00 (reason: timeout).
No new suggestions were produced on the last sweep.
Investigate: igris_event_log component='cognition.subconscious' limit=5
Suppression rules (do NOT render the WARNING when):
'cognition.subconscious.run_skipped' — skipping is normal
(disabled gate, cold-start grace, daily budget, min-digest-bytes).'cognition.subconscious.run_started' with no terminal event
yet (in-flight run; /scan surfaces the stuck-RUNNING case).'cognition.subconscious.run_succeeded' row exists with created_at newer
than the failed row.If sqlite3 is unavailable, the DB is missing, or the query errors, skip the
WARNING silently (2>/dev/null || true absorbs all three). Token budget: ~80
tokens.
If igris-brain MCP is available, call igris_suggestion_list with:
status = 'pending'project_slug = current project sluglimit = 3Token budget: bounded to <=3 rows by limit. Render at most ~120 tokens.
If results are returned, render:
## Suggestions ({total} pending)
- [{priority}] {title} ({source_module})
- [{priority}] {title} ({source_module})
- [{priority}] {title} ({source_module})
Use the total count from the response (may exceed limit) so the user
knows how many are queued in total. Format each row as:
- [{priority}] {title} ({source_module}) — keep it terse; the user can
run igris_suggestion_list directly for full details.
If zero results, render nothing — no "No suggestions" line. If the tool is unavailable (older brain), skip silently.
Gated behind cognition.janitor.enabled in ~/.igris/config.json (key absent =
false). If false, skip this line silently — the engine does not run.
When enabled, surface a one-line memory-hygiene health summary from the latest
cognition.janitor.* lifecycle event + the latest brain_maintenance_runs audit
row (same local-DB sqlite3 rationale as the subconscious block — the local DB
is the merged superset post-§4 pull; the janitor runs whole-brain, NOT
slug-scoped):
command -v sqlite3 >/dev/null 2>&1 || return 0 # skip silently if absent
sqlite3 "<detect.brain_root>/memory/knowledge.db" \
"SELECT status, merges_proposed, confidence_bumps, stale_rejected, finished_at
FROM brain_maintenance_runs ORDER BY id DESC LIMIT 1;" 2>/dev/null || true
Render one terse line (skip entirely if no maintenance rows exist yet). Merge
PROPOSALS surface through the pending-suggestions block above
(source_module='janitor'); this line is the engine-health summary only.
## Janitor
Last run 2026-07-02 04:00 — SUCCEEDED · merges_proposed=2 · confidence_bumps=1 · stale_rejected=3
If sqlite3 is unavailable, the DB is missing, or the query errors, skip the
line silently. Token budget: ~40 tokens.
Extraction happens in a detached background process at session-end (spawned
by session_end.sh / pre_compact.sh via perception_extract_and_persist.sh).
This section is purely a SELECT — it surfaces whatever the background process
has committed since the last boot. /boot does NOT drain any inbox.
Before rendering pending candidates, query the latest perception lifecycle
event so a recent failure surfaces prominently. TD-080 fix (Gap A): read
directly from the local DB via sqlite3 (NOT via igris_event_log MCP) so
this machine's local-only events surface here. The MCP tool routes to the
remote brain, which misses any perception runs that happened on this machine
since the last /rest. Post-§4 pull, the local DB is the merged superset.
Run (set $PROJECT_SLUG from detect.project_slug):
# Defense-in-depth (TD-080 Q-3): refuse to interpolate if slug doesn't match
# the registered slug shape. Belt-and-suspenders against any future code path
# that broadens slug sourcing (e.g., env var override). Same posture as the
# other defensive guards in this section — skip silently if the slug came
# from an unexpected source.
if [[ ! "$PROJECT_SLUG" =~ ^[a-z0-9_-]+$ ]]; then
return 0 # do not surface this section this run
fi
sqlite3 "<detect.brain_root>/memory/knowledge.db" \
"SELECT created_at, event_name, json_extract(payload, '\$.reason') AS reason
FROM event_log
WHERE component = 'perception' AND project_slug = '$PROJECT_SLUG'
ORDER BY created_at DESC LIMIT 1;"
If the latest row's event_name is 'perception.run_failed' AND no later
'perception.run_succeeded' row exists for the same project (defensive
follow-up to confirm the failure has not self-recovered), prepend a single
WARNING block before the pending list. Otherwise, render no warning and
proceed to the pending list as normal.
The defensive "no later success" check (substitute the failed row's
created_at):
# Defense-in-depth (TD-080 Q-3): refuse to interpolate if slug doesn't match
# the registered slug shape.
if [[ ! "$PROJECT_SLUG" =~ ^[a-z0-9_-]+$ ]]; then
return 0
fi
sqlite3 "<detect.brain_root>/memory/knowledge.db" \
"SELECT COUNT(*) FROM event_log
WHERE component = 'perception' AND project_slug = '$PROJECT_SLUG'
AND event_name = 'perception.run_succeeded'
AND created_at > '<failed_row_created_at>';"
A return of 0 confirms the failure is the latest terminal state.
Defensive guards (TD-080):
sqlite3 invocation with a command -v sqlite3 >/dev/null 2>&1
pre-check. If sqlite3 is absent on this machine, skip the WARNING silently.2>/dev/null || true shell pattern absorbs both cases.## Perception WARNING
Latest extraction FAILED at 2026-05-01 04:22 (reason: epipe_on_llm_stdin).
Recent session transcripts may not have produced learnings.
Investigate: tail ~/.igris/projects/{project}/session/perception_extract.log
Suppression rules (do NOT render the WARNING when):
'perception.run_skipped' — skipping is normal (60s
min-window, bytes gate, disabled gate).'perception.run_started' with no terminal event yet
(in-flight run; /scan handles the "stuck RUNNING" surface).'perception.run_succeeded' row exists with created_at newer than
the failed row.Token budget for the WARNING block: ~80 tokens. The pending list below remains unchanged in budget (~150 tokens). Total §4.11 upper bound: ~230 tokens.
If sqlite3 is unavailable or the DB file is missing, skip the WARNING silently.
TD-080 fix (Gap A): read directly from the local DB via sqlite3 (NOT
via igris_perception_review_pending MCP). Same rationale as the WARNING
above — local-only pending rows from this machine's recent extractions are
invisible to the remote-routed MCP tool. Post-§4 pull, the local DB is the
merged superset.
Run (set $PROJECT_SLUG from detect.project_slug):
# Defense-in-depth (TD-080 Q-3): refuse to interpolate if slug doesn't match
# the registered slug shape.
if [[ ! "$PROJECT_SLUG" =~ ^[a-z0-9_-]+$ ]]; then
return 0
fi
sqlite3 "<detect.brain_root>/memory/knowledge.db" \
"SELECT title, source_extractor, confidence
FROM learnings
WHERE project = '$PROJECT_SLUG' AND review_status = 'pending_review'
ORDER BY created_at DESC LIMIT 5;"
sqlite3 "<detect.brain_root>/memory/knowledge.db" \
"SELECT COUNT(*) FROM learnings
WHERE project = '$PROJECT_SLUG' AND review_status = 'pending_review';"
The first query returns the top 5 pending rows for the rendered list. The
second returns the total count (matches the total field the MCP tool used
to provide). Token budget: bounded to <=5 rows. Render at most ~150 tokens.
If results are returned, render:
## Pending Learnings ({total} pending review)
- [{source_extractor}, conf {confidence}] {title}
- [{source_extractor}, conf {confidence}] {title}
Use the total count from the response (may exceed limit) so the user
knows the queue depth. The source_extractor field values are typically
llm (from background extraction) or manual (from direct memory_store
calls). Legacy rows from pre-TD-066 extractions may render as
rule:learned_marker, rule:retry_chain, rule:blocker_resolution, or
rule:error_fingerprint — these are read-side compatible and surface
verbatim. Show approve and reject MCP tools as next-step hints once per
session, not per row.
If zero results, render nothing — no "No pending" line. If sqlite3 is
unavailable or the DB file is missing, skip silently (same defensive guards
as the WARNING block above).
If auto_approve_enabled=true is set in <detect.brain_root>/config.json's perception
section, the background extractor inserts new rows as approved directly
and they bypass this surface — they appear in recall/search immediately
without operator review. Default is opt-in (off).
If the §4.1 igris session gather digest selected a genuine handoff with handoff.mode == "REST MODE", display its resume point from the digest fields — handoff.resume_point and handoff.next_steps (the verb parsed these from the chosen handoff file's content), NOT from any fixed CURRENT_SESSION.md:
## Resuming Session
**Last Active:** [brief ID — from handoff.resume_point]
**Phase:** [phase — from handoff.resume_point]
**Next Steps:** [handoff.next_steps]
If gather.fresh_start is true (handoff is null), this is a fresh start — skip the resume display. (A legacy CURRENT_SESSION.md handoff with is_legacy: true is displayed identically — the resume is invisible to the user, exactly as pre-FR-126 /boot read it.)
## Recommended Actions
1. [Primary - resume current or start highest priority]
2. [Secondary - show status or review briefs]
3. [Tertiary - other relevant action]
igris session register (§4.4) already wrote this instance's LIVE per-instance file ~/.igris/projects/{project}/session/instances/<instance_id>.md at state='live' (where <instance_id> is register.instance_id from the §4.4 digest), seeded from the handoff. §7 is the end-of-boot confirm/refresh of THAT file — if the booting surfaced anything that should land in the LIVE scratchpad (or once a hunt starts and **Mode:** flips to HUNT MODE), update it directly via igris_session_file_update with project, filename=instances/<instance_id>.md, content, instance_id=<instance_id>, state='live'. On a plain boot with no further edits the register write already stands — no extra write is required.
The per-instance file replaces the old single CURRENT_SESSION.md. There is no Mode flip on a shared file; each instance owns and writes its own file freely.
Display: "Igris AI initialized. System ready."