pantheon-opencode 1.6.0-beta.1 → 1.6.0-beta.10

package/src/plugins/tui/src/index.tsx

@@ -5,9 +5,9 @@
 /**
  * pantheon-tui — Pantheon TUI plugin for opencode.
  *
- * Bundled entry: `tsdown` emits `dist/tui.js`, and the package `exports`
- * (`./tui` → ./dist/tui.js, `./server` → ./dist/server.js) is the ONLY load
- * path — no raw TSX copy is shipped. Because the bundle inlines relative
+ * V1 bundle: `tsdown` emits `dist/tui.js`, re-exported by root `tui.ts`.
+ * OpenCode V2 uses the separate `src/index-v2.tsx` entry and native CLI plugin
+ * API. No raw TSX implementation is shipped. Because the bundle inlines relative
  * imports, this entry may be split into modules without breaking the loader.
  *
  * Slots:
@@ -53,16 +53,7 @@ import { homedir } from 'node:os'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import type { TuiPlugin, TuiPluginApi, TuiPluginModule } from '@opencode-ai/plugin/tui'
-import {
-  createEffect,
-  createMemo,
-  createResource,
-  createSignal,
-  For,
-  onCleanup,
-  onMount,
-  Show,
-} from 'solid-js'
+import { createMemo, createResource, createSignal, For, onCleanup, onMount, Show } from 'solid-js'
 
 // ─── Double-load guard (mirrors src/pantheon/plugin-once.ts) ───────────────
 // Opencode merges global + project plugin paths, so this module can load twice
@@ -919,9 +910,9 @@ async function setupUsageBar(api: TuiPluginApi) {
  *      (filterDelegationsToSession) drops every non-focused report — the panel
  *      lists only the focused session.
  *
- *   3. REFRESH — session.created/updated/deleted/status events and
- *      message.part.updated/removed (via liveStore.version bumps) re-fetch
- *      children; a 1s safety poll (oh-my-opencode-slim pattern) re-fetches
+ *   3. REFRESH — session.created/updated/deleted/status events and live-store
+ *      subscription notifications re-fetch children; a 1s safety poll
+ *      (oh-my-opencode-slim pattern) re-fetches
  *      children + re-reads the md so the panel updates EVEN without events.
  *
  *   4. DIAGNOSTICS — every re-fetch logs
@@ -947,8 +938,8 @@ async function setupUsageBar(api: TuiPluginApi) {
  *      panel renders EMPTY — zero rows, zero errors.
  *
  * The live tool-part lifecycle helpers below remain (tested, exported) but
- * are no longer the source of truth: they feed a version signal that merely
- * re-triggers the children fetch. Everything is fail-open: a missing
+ * are no longer the source of truth: they update the shared live store, whose
+ * subscribers re-trigger the children fetch. Everything is fail-open: a missing
  * children API or directory yields [], and any unreadable input is skipped —
  * never crash. */
 
@@ -2631,18 +2622,88 @@ function DelegationRow(props: {
 
 /* ─── Main Sidebar View ──────────────────────────────────── */
 
-/** Plugin-level live delegation store shared with the event subscriptions
- *  in `tui()`: the map of live entries + a version signal bumped on every
- *  mutation. The View subscribes to the version (in an effect) to refresh the
- *  durable child list and also reads the map as an optimistic live source. */
+/** Plugin-level live delegation store shared by event subscriptions and View.
+ *  Mutations notify subscribers so the View can refresh its durable child
+ *  list while also reading the map as an optimistic live source. */
 export type LiveDelegationStore = {
   map: Map<string, LiveDelegationEntry>
-  /** Reactive version getter — View reads it inside an effect to re-fetch. */
-  version: () => number
-  /** Bump the version after a live mutation. */
+  /** Subscribe to invalidations consumed by the sidebar's refresh path. */
+  subscribe: (listener: () => void) => () => void
+  /** Notify sidebar subscribers after a live mutation. */
   bump: () => void
 }
 
+/** Create the observable live store shared by task events and the sidebar. */
+export function createLiveDelegationStore(): LiveDelegationStore {
+  const listeners = new Set<() => void>()
+  return {
+    map: new Map<string, LiveDelegationEntry>(),
+    subscribe(listener) {
+      listeners.add(listener)
+      return () => listeners.delete(listener)
+    },
+    bump() {
+      for (const listener of listeners) listener()
+    },
+  }
+}
+
+/** Register the live task-part events that invalidate the sidebar store. */
+export function registerLiveDelegationEvents(
+  api: TuiPluginApi,
+  liveStore: LiveDelegationStore,
+): () => void {
+  const unsubLive: (() => void)[] = []
+
+  try {
+    unsubLive.push(
+      api.event.on('message.part.updated', (event: unknown) => {
+        // SDK v2 shape: properties.part (v1 drift: properties.info.part).
+        const props = ((event as { properties?: unknown } | null)?.properties ?? {}) as {
+          part?: unknown
+          info?: { part?: unknown }
+        }
+        const part = (props.part ?? props.info?.part) as DelegationToolPart | undefined
+        if (part === undefined) return
+        // beta.6: track the live tool call per child session (panel's
+        // activity line). Fire-and-forget — display-only state.
+        const sample = extractToolActivity(part as Parameters<typeof extractToolActivity>[0])
+        if (sample !== null)
+          trackToolActivity(latestToolActivity, sample.sessionID, sample.activity)
+        if (reduceDelegationToolPart(liveStore.map, part)) liveStore.bump()
+      }),
+    )
+  } catch {
+    /* events API unavailable — children API + 1s poll cover the panel */
+  }
+
+  try {
+    unsubLive.push(
+      api.event.on('message.part.removed', (event: unknown) => {
+        // SDK v2 shape: properties.partID (v1 drift: properties.part.id).
+        const props = ((event as { properties?: unknown } | null)?.properties ?? {}) as {
+          partID?: string
+          part?: { id?: string }
+        }
+        const partID = props.partID ?? props.part?.id
+        if (partID !== undefined && removeDelegationEntry(liveStore.map, partID)) liveStore.bump()
+      }),
+    )
+  } catch {
+    /* events API unavailable — children API + 1s poll cover the panel */
+  }
+
+  return () => {
+    for (const unsub of unsubLive) {
+      try {
+        unsub()
+      } catch {
+        /* ignore */
+      }
+    }
+  }
+}
+
 function View(props: {
   api: TuiPluginApi
   sessionID: string | undefined
@@ -2758,7 +2819,7 @@ function View(props: {
   // means the event bus isn't delivering, and the 1s poll is what keeps
   // the panel honest.
   let eventRefreshCount = 0
-  // In-flight guard: overlap between the poll, events and the version effect
+  // In-flight guard: overlap between the poll, events and store subscribers
   // collapses into one fetch — no duplicate work, no duplicate entries.
   let delegationsInflight: Promise<void> | null = null
   const refreshDelegations = () => {
@@ -2910,14 +2971,17 @@ function View(props: {
       /* events API not available — the 1s poll still covers it */
     }
 
-    // message.part.updated/removed → liveStore.version() bumps (tui()):
-    // subscribe here so the panel ALSO re-fetches children when tool-part
-    // events DO arrive and the updated live row is rendered immediately.
-    createEffect(() => {
-      props.liveStore.version() // subscribe to live mutations
-      eventRefreshCount += 1
-      void refreshDelegations()
-    })
+    // Task-part events invalidate the same store the panel reads, refreshing
+    // children when those events arrive and making optimistic live rows visible.
+    cleanup.push(
+      props.liveStore.subscribe(() => {
+        eventRefreshCount += 1
+        void refreshDelegations()
+      }),
+    )
+    // Fetch the initial state; future updates use the store subscription above.
+    eventRefreshCount += 1
+    void refreshDelegations()
 
     // Safety poll (OMO-slim pattern): 1s re-fetch children + md + tick the
     // elapsed counter. Guarantees the panel updates even with zero events.
@@ -2935,8 +2999,8 @@ function View(props: {
     // compacting, so after a compaction/attach the live map would start
     // empty even though the session still holds the delegation tool parts.
     // Re-seed the live map from the session's existing parts (in message
-    // order) right after the subscriptions are registered — the version
-    // bump re-triggers the children fetch. Fail-open: if the SDK access is
+    // order) right after the subscriptions are registered — the store
+    // notification re-triggers the children fetch. Fail-open: if the SDK access is
     // unavailable we skip — the children API + the 1s poll keep the panel
     // working.
     try {
@@ -3072,61 +3136,18 @@ const tui: TuiPlugin = (api, _options, _meta) => {
   // Vendored feature (MIT): AI subscription usage gauges.
   void setupUsageBar(api) // async init — never blocks sidebar registration
 
-  // ── Live delegation store (tool-part tracker, kept as a REFRESH
-  // TRIGGER) ──
+  // ── Live delegation store (tool-part tracker + sidebar invalidation) ──
   // The Delegations panel's PRIMARY source is `api.client.session.children`
   // (delegations-sidebar pattern) — `message.part.updated` may not fire for
   // the native task tool on runtime 1.18.13 (the "(0)" symptom). The
-  // tool-part lifecycle below still tracks `task` parts and bumps a version
-  // signal the View subscribes to: when part events DO arrive, the panel
+  // tool-part lifecycle below still tracks `task` parts and invalidates the
+  // store subscription consumed by the View: when part events DO arrive, the panel
   // re-fetches children. Fail-open: if the events API is unavailable nothing
   // subscribes and the 1s safety poll keeps the panel working (never crash).
-  const [liveVersion, setLiveVersion] = createSignal(0)
-  const liveStore: LiveDelegationStore = {
-    map: new Map<string, LiveDelegationEntry>(),
-    version: liveVersion,
-    bump: () => setLiveVersion((v) => v + 1),
-  }
-  const unsubLive: (() => void)[] = []
-
-  try {
-    unsubLive.push(
-      api.event.on('message.part.updated', (event: any) => {
-        // SDK v2 shape: properties.part (v1 drift: properties.info.part).
-        const props = (event?.properties ?? {}) as { part?: unknown; info?: { part?: unknown } }
-        const part = (props.part ?? props.info?.part) as DelegationToolPart | undefined
-        if (part === undefined) return
-        // beta.6: track the live tool call per child session (panel's
-        // activity line). Fire-and-forget — display-only state.
-        const sample = extractToolActivity(part as any)
-        if (sample !== null)
-          trackToolActivity(latestToolActivity, sample.sessionID, sample.activity)
-        if (reduceDelegationToolPart(liveStore.map, part)) liveStore.bump()
-      }),
-    )
-  } catch {
-    /* events API unavailable — children API + 1s poll cover the panel */
-  }
-  try {
-    unsubLive.push(
-      api.event.on('message.part.removed', (event: any) => {
-        // SDK v2 shape: properties.partID (v1 drift: properties.part.id).
-        const props = (event?.properties ?? {}) as { partID?: string; part?: { id?: string } }
-        const partID = props.partID ?? props.part?.id
-        if (partID !== undefined && removeDelegationEntry(liveStore.map, partID)) liveStore.bump()
-      }),
-    )
-  } catch {
-    /* events API unavailable — children API + 1s poll cover the panel */
-  }
+  const liveStore = createLiveDelegationStore()
+  const unsubscribeLive = registerLiveDelegationEvents(api, liveStore)
   api.lifecycle.onDispose(() => {
-    for (const unsub of unsubLive) {
-      try {
-        unsub()
-      } catch {
-        /* ignore */
-      }
-    }
+    unsubscribeLive()
     liveStore.map.clear()
   })
 

package/src/plugins/tui/src/opencode-v2.d.ts

@@ -0,0 +1,13 @@
+declare module '@opencode/plugin/tui' {
+  export const Plugin: {
+    define<T>(plugin: T): T
+  }
+}
+
+declare module '@opencode/plugin' {
+  export const Plugin: {
+    define<T>(plugin: T): T
+  }
+}
+
+declare const __PANTHEON_VERSION__: string

package/src/plugins/tui/tsconfig.build.json

@@ -0,0 +1,5 @@
+{
+  "extends": "../../../tsconfig.json",
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}

package/src/plugins/tui/tsconfig.typecheck.json

@@ -0,0 +1,5 @@
+{
+  "//": "Typecheck gate for the V2 TUI entry only. `tsc --noEmit` at the package root was a no-op: with no tsconfig in this directory tsc walked up to the repo tsconfig.json, which excludes src/plugins/tui entirely — so nothing here was checked. tsdown bundles without type-checking, which is how an invalid event name (session.updated, absent from the OpenCode V2 event union) shipped in the V2 rewrite. This config points tsc at the V2 entry plus its ambient declarations so a type error in src/index-v2.tsx fails `npm run typecheck`. The V1 entry (src/index.tsx) is intentionally NOT included: it carries pre-existing type errors out of scope for the V2 gate. Keep this file strict JSON — the repo pre-commit `check-json` hook rejects comments.",
+  "extends": "./tsconfig.build.json",
+  "include": ["src/index-v2.tsx", "src/opencode-v2.d.ts"]
+}

package/src/plugins/tui/tsdown.config.ts

@@ -1,4 +1,5 @@
 import { readFileSync } from 'node:fs'
+import { appendFile, readdir, readFile } from 'node:fs/promises'
 import { join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import solid from 'rolldown-plugin-solid'
@@ -9,13 +10,31 @@ const pkg = JSON.parse(readFileSync(join(__dirname, 'package.json'), 'utf8')) as
   version: string
 }
 
+async function ensureDistArtifactsEndWithNewline(): Promise<void> {
+  const dist = join(__dirname, 'dist')
+  const entries = await readdir(dist, { withFileTypes: true })
+
+  await Promise.all(
+    entries
+      .filter((entry) => entry.isFile())
+      .map(async ({ name }) => {
+        const path = join(dist, name)
+        const contents = await readFile(path, 'utf8')
+        if (!contents.endsWith('\n')) await appendFile(path, '\n')
+      }),
+  )
+}
+
 export default defineConfig({
-  entry: { tui: 'src/index.tsx', server: 'src/server.ts' },
+  entry: { tui: 'src/index.tsx', 'tui-v2': 'src/index-v2.tsx', server: 'src/server.ts' },
   format: ['esm'],
   platform: 'node',
   outDir: 'dist',
   clean: true,
   outExtensions: () => ({ js: '.js' }),
+  dts: {
+    tsconfig: join(__dirname, 'tsconfig.build.json'),
+  },
   define: {
     __PANTHEON_VERSION__: JSON.stringify(pkg.version),
   },
@@ -28,6 +47,7 @@ export default defineConfig({
     }),
   ],
   deps: {
-    neverBundle: [/^@opencode-ai\//, /^@opentui\//, /^solid-js/],
+    neverBundle: [/^@opencode-ai\//, /^@opencode\//, /^@opentui\//, /^solid-js/],
   },
+  onSuccess: ensureDistArtifactsEndWithNewline,
 })

package/src/plugins/tui/tui-v2.ts

@@ -0,0 +1,2 @@
+// OpenCode V2's CLI loader resolves this root-level TUI entrypoint.
+export { default } from './dist/tui-v2.js'

package/src/plugins/tui/tui.ts

@@ -0,0 +1,3 @@
+// OpenCode V1 compatibility entrypoint. The V2 installer copies tui-v2.ts as
+// the installed root tui.ts instead.
+export { default } from './dist/tui.js'

package/src/routing.yml

@@ -3,7 +3,7 @@ presets:
   go-free:
     description: "Free-tier lineup via OpenCode Zen 2026: big-pickle orchestrator, nemotron-3-super-free planner, qwen3.6-plus-free reviewer, deepseek-v4-flash-free implementers, mimo-v2.5-free scouts. Only -free suffix models; quota, availability and pricing depend on Zen account. 2026 pricing verified."
     vision:
-      model: opencode/mimo-v2.5-free
+      model: opencode/mimo-v2.6-flash-free
       reasoning_effort: low
     providers:
       opencode:
@@ -99,7 +99,6 @@ presets:
 agents:
   zeus:
     role: Central orchestrator
-    max_steps: 40   # R4: step budget — at max_steps the agent is forced to summarize-and-stop. Tracker is permanent-per-process (no reset wiring).
     reasoning_effort: medium
     user_invocable: true
     can_delegate: true
@@ -137,7 +136,6 @@ agents:
     - incremental-implementation
   athena:
     role: Strategic planner
-    max_steps: 15   # R4: step budget — at max_steps the agent is forced to summarize-and-stop
     reasoning_effort: high
     user_invocable: true
     can_delegate: true
@@ -157,7 +155,6 @@ agents:
     - memory-bank
   apollo:
     role: Investigation scout
-    max_steps: 25   # R4: step budget — at max_steps the agent is forced to summarize-and-stop
     reasoning_effort: low
     user_invocable: false
     can_delegate: false
@@ -175,7 +172,6 @@ agents:
     - auto-continue
   hermes:
     role: Backend specialist
-    max_steps: 60   # R4: step budget — at max_steps the agent is forced to summarize-and-stop
     reasoning_effort: medium
     user_invocable: true
     can_delegate: true
@@ -198,7 +194,6 @@ agents:
     - incremental-implementation
   aphrodite:
     role: Frontend specialist
-    max_steps: 60   # R4: step budget — at max_steps the agent is forced to summarize-and-stop
     reasoning_effort: medium
     user_invocable: true
     can_delegate: false
@@ -219,7 +214,6 @@ agents:
     - file-prompts
   demeter:
     role: Database specialist
-    max_steps: 50   # R4: step budget — at max_steps the agent is forced to summarize-and-stop
     reasoning_effort: medium
     user_invocable: true
     can_delegate: false
@@ -239,7 +233,6 @@ agents:
     - incremental-implementation
   themis:
     role: Quality gate
-    max_steps: 25   # R4: step budget — at max_steps the agent is forced to summarize-and-stop
     reasoning_effort: high
     user_invocable: true
     can_delegate: false
@@ -261,7 +254,6 @@ agents:
     - context-compression
   prometheus:
     role: Infrastructure specialist
-    max_steps: 30   # R4: step budget — at max_steps the agent is forced to summarize-and-stop
     reasoning_effort: medium
     user_invocable: true
     can_delegate: false
@@ -280,7 +272,6 @@ agents:
     - incremental-implementation
   hephaestus:
     role: AI pipelines
-    max_steps: 50   # R4: step budget — at max_steps the agent is forced to summarize-and-stop
     reasoning_effort: medium
     user_invocable: true
     can_delegate: false
@@ -299,7 +290,6 @@ agents:
     - auto-continue
   nyx:
     role: Observability
-    max_steps: 25   # R4: step budget — at max_steps the agent is forced to summarize-and-stop
     reasoning_effort: low
     user_invocable: true
     can_delegate: false
@@ -318,7 +308,6 @@ agents:
     - auto-continue
   gaia:
     role: Remote sensing domain specialist
-    max_steps: 25   # R4: step budget — at max_steps the agent is forced to summarize-and-stop
     reasoning_effort: low
     user_invocable: false
     can_delegate: false
@@ -333,7 +322,6 @@ agents:
     - auto-continue
   iris:
     role: GitHub operations
-    max_steps: 20   # R4: step budget — at max_steps the agent is forced to summarize-and-stop
     reasoning_effort: low
     user_invocable: true
     can_delegate: false
@@ -351,7 +339,6 @@ agents:
     - artifact-management
   mnemosyne:
     role: Memory bank
-    max_steps: 20   # R4: step budget — at max_steps the agent is forced to summarize-and-stop
     reasoning_effort: low
     user_invocable: true
     can_delegate: false
@@ -375,7 +362,6 @@ agents:
     - session-goal
   talos:
     role: Hotfix agent
-    max_steps: 15   # R4: step budget — at max_steps the agent is forced to summarize-and-stop
     reasoning_effort: low
     user_invocable: true
     can_delegate: false
@@ -473,6 +459,8 @@ handoffs:
         (priority-aware, budget-allocated), archive IMPL/REVIEW to 02-progress-log.md,
         update _xref/index.md cross-references.'
 
+# Canonical explicit fallback map for Zeus timeout/retry policy. Evaluate
+# left-to-right; an absent agent entry means escalate (never guess a fallback).
 fallback_chains:
   apollo:
     - athena
@@ -529,11 +517,10 @@ background_job_board:
 background_delegation:
   timeout_ms: 900000        # 15 min
   poll_ms: 250
-  max_compaction_items: 10
   prune_ttl_ms: 86400000    # 24h
   read_only_agents: [apollo, gaia]
   session_max: 3
-  retry_count: 1
+  retry_count: 1              # one retry after an initial transient failure; no retry loops
 # ── O5: permission.task — glob rules for which subagents an agent may
 # invoke (last matching rule wins; deny removes the agent from the delegate
 # tool description entirely — prevents circular delegation at the
@@ -566,7 +553,10 @@ hashline:
 full_auto:
   enabled: false                 # opt-in: goal continuations are OFF by default
   max_continuations: 25          # hard cap on goal continuations per session
-  # Wave 3 (PR #46): full-auto goal loop. One active goal per session
-  # (pending → in_progress → done); while active, idle sessions are
-  # continued automatically toward the objective. Documentation mirror —
-  # the plugin resolves behavior in code (GOAL_LOOP_DEFAULTS).
+  # Full-auto only continues a task/scope explicitly authorized by the user.
+  # It never authorizes auth/security gates, risky data/schema or destructive
+  # operations, global config, broad permissions, production deploy, push, or merge.
+  # Low-risk execution is proportional: no forced plan/discovery/council/artifact
+  # for a bounded fix; use focused verification. Documentation mirror — runtime
+  # behavior is implemented in the plugin (GOAL_LOOP_DEFAULTS).
+  # Wave 3 (PR #46): one active goal per session (pending → in_progress → done).

package/src/skills/README.md

@@ -23,8 +23,8 @@ There are **20 skills** divided into **5 domains**.
    - Used by: Zeus, Apollo, Hephaestus, Nyx, Gaia
 
 4. **context-compression** — `context-compression/SKILL.md`
-   - Level 2 — Pantheon-native context compression with priority scoring, semantic summarization, budget allocation, and cross-references.
-   - Used by: Zeus, Mnemosyne, Themis
+   - Native compaction guidance and explicit checkpoint rules; no automatic compression MCP calls.
+   - Used by: Zeus, Mnemosyne
 
 5. **memory-bank** — `memory-bank/SKILL.md`
    - Memory bank rules, structure, and optimization — complete guide to Pantheon memory management.
@@ -124,7 +124,7 @@ The `SKILL.md` file contains YAML frontmatter with `name`, `description`, and pl
 | 1 | agent-coordination | Orchestration & Workflow | Zeus |
 | 2 | artifact-management | Orchestration & Workflow | Zeus, Mnemosyne, Iris |
 | 3 | auto-continue | Orchestration & Workflow | Zeus, Apollo, Hephaestus, Nyx, Gaia |
-| 4 | context-compression | Orchestration & Workflow | Zeus, Mnemosyne, Themis |
+| 4 | context-compression | Orchestration & Workflow | Zeus, Mnemosyne |
 | 5 | memory-bank | Orchestration & Workflow | Mnemosyne, Athena |
 | 6 | session-goal | Orchestration & Workflow | Zeus, Mnemosyne |
 | 7 | clonedeps | Development Tools | Hermes, Hephaestus |

package/src/skills/agent-coordination/SKILL.md

@@ -34,8 +34,8 @@ Route tasks to optimized agents based on category instead of specifying agents m
 
 ```
 1. User describes feature
-2. @athena creates PLAN with phases and agents
-3. User approves PLAN (GATE 1)
+2. @athena returns the complete PLAN to Zeus (no approval prompt from the child session)
+3. Zeus displays the full PLAN in the main conversation, then asks the user to approve it (GATE 1)
 4. Zeus dispatches agents to phases (parallel when possible)
 5. Each agent: TDD cycle → writes IMPL artifact
 6. @themis reviews all phases (GATE 2)
@@ -67,6 +67,11 @@ All phase outputs go to `.pantheon/memory-bank/.tmp/`. See `skill: artifact-mana
 
 ## Safety Gates
 
+For every requested plan, Gate 1 is not satisfied by a child-agent approval
+question or a link to a hidden artifact: the complete plan must be visible in
+the main conversation before Zeus asks for approval. If the user requests
+changes, Zeus presents the complete revised plan and repeats Gate 1.
+
 | Gate | When | Why |
 |------|------|-----|
 | **GATE 1** | After PLAN | User confirms scope |

package/src/skills/artifact-management/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: artifact-management
-description: "Structured artifact trail for feature implementations — plans, implementations, reviews, and decisions."
+description: "Structured artifacts for planned, multi-phase, or materially risky implementation work."
 context: fork
 globs: []
 alwaysApply: false
@@ -8,7 +8,7 @@ alwaysApply: false
 
 # Artifact Management
 
-Structured artifact trail system for documenting feature implementations. Defines what, where, and how agents produce phase outputs.
+Structured artifact trail for planned, multi-phase, or materially risky implementation work. Artifacts are not a prerequisite for simple fixes or read-only investigation.
 
 ---
 
@@ -55,6 +55,13 @@ All ephemeral artifacts live in `.pantheon/memory-bank/.tmp/` — gitignored and
 
 > **Zeus does NOT generate artifacts.** He orchestrates agents that generate them.
 
+## Proportional Use
+
+- Create PLAN/IMPL/REVIEW artifacts for planned multi-phase work or when risk, auditability, or an explicit request needs a durable phase trail.
+- A bounded, reversible fix should be investigated only as far as needed, implemented, verified with focused checks, and returned as a concise summary. Do not create PLAN, IMPL, or REVIEW artifacts for it.
+- Read-only lookup or trivial discovery needs no DISC artifact; use one only when findings are broad enough to be reused or drive a material decision.
+- The absence of an artifact never waives Themis review or human approval for auth/security, data/schema/migrations, production-impacting work, or sensitive actions.
+
 ---
 
 ## Templates
@@ -103,9 +110,9 @@ All ephemeral artifacts live in `.pantheon/memory-bank/.tmp/` — gitignored and
 
 ## Human Pause Points
 
-1. **After PLAN** → user reads `.tmp/PLAN-<feature>.md` and approves
-2. **After REVIEW** → user reads `.tmp/REVIEW-<feature>.md` and validates focus items
-3. **Before git commit** → user executes manually
+1. **After a required PLAN** → pause only when a material scope/risk decision needs approval.
+2. **After required REVIEW** → preserve auth/security/data/schema and other sensitive approval gates.
+3. **Before commit/push/merge/deploy or destructive/global action** → require explicit human approval.
 
 ---