pantheon-opencode 1.6.0-beta.9 → 1.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (131) hide show
  1. package/AGENTS.global.md +118 -0
  2. package/AGENTS.md +18 -168
  3. package/CHANGELOG.md +126 -376
  4. package/README.md +83 -610
  5. package/README.pt-BR.md +120 -345
  6. package/bin/pantheon-init.mjs +366 -132
  7. package/commands/pantheon-deepwork.md +14 -3
  8. package/commands/pantheon-vision.md +61 -12
  9. package/package.json +19 -11
  10. package/plugin.json +1 -1
  11. package/pyproject.toml +6 -2
  12. package/scripts/_pantheon_paths.py +24 -0
  13. package/scripts/build-agents-md.mjs +368 -69
  14. package/scripts/changelog-merge.mjs +161 -0
  15. package/scripts/check-plugin-v2-coverage.mjs +11 -8
  16. package/scripts/docs-check-changelog.mjs +204 -0
  17. package/scripts/docs-link-check.mjs +314 -0
  18. package/scripts/docs-media.mjs +157 -0
  19. package/scripts/doctor.mjs +828 -40
  20. package/scripts/install/agents-md.mjs +2 -2
  21. package/scripts/install/backup.mjs +648 -0
  22. package/scripts/install/cli-ui.mjs +303 -72
  23. package/scripts/install/component-selection.mjs +61 -0
  24. package/scripts/install/config-migration.mjs +583 -27
  25. package/scripts/install/exit-codes.mjs +26 -0
  26. package/scripts/install/file-inventory.mjs +555 -0
  27. package/scripts/install/health-check.mjs +31 -25
  28. package/scripts/install/interactive.mjs +78 -383
  29. package/scripts/install/migrate.mjs +49 -25
  30. package/scripts/install/model-picker.mjs +218 -250
  31. package/scripts/install/opencode-version.mjs +83 -21
  32. package/scripts/install/opencode.mjs +1413 -154
  33. package/scripts/install/plan-artifact.mjs +517 -0
  34. package/scripts/install/plan.mjs +475 -0
  35. package/scripts/install/plugin.mjs +214 -27
  36. package/scripts/install/prompt-result.mjs +2 -0
  37. package/scripts/install/shared.mjs +256 -99
  38. package/scripts/install/state.mjs +63 -8
  39. package/scripts/install/strings.mjs +60 -4
  40. package/scripts/install/venv.mjs +90 -47
  41. package/scripts/install/verify.mjs +128 -0
  42. package/scripts/install/vision-prompt.mjs +173 -0
  43. package/scripts/install-mcp.mjs +2 -2
  44. package/scripts/manifest-inventory.mjs +49 -3
  45. package/scripts/mcp_persistence.py +1535 -1050
  46. package/scripts/memory_mcp.py +12 -843
  47. package/scripts/node-engine-policy.mjs +85 -0
  48. package/scripts/package-evidence.mjs +10 -2
  49. package/scripts/postinstall.mjs +26 -26
  50. package/scripts/probe-pantheon-cost.mjs +118 -19
  51. package/scripts/prune.mjs +9 -3
  52. package/scripts/reconcile.mjs +325 -0
  53. package/scripts/release-gates.mjs +682 -0
  54. package/scripts/restore.mjs +222 -0
  55. package/scripts/run-node-tests.mjs +24 -8
  56. package/scripts/sync-artifacts.mjs +19 -7
  57. package/scripts/sync-tui.mjs +5 -1
  58. package/scripts/test-opencode-v2-sandbox.sh +36 -123
  59. package/scripts/uninstall.mjs +369 -34
  60. package/scripts/update.mjs +164 -0
  61. package/scripts/validate-node-engine-policy.mjs +13 -0
  62. package/scripts/version-check.mjs +34 -1
  63. package/scripts/versioning.mjs +23 -3
  64. package/scripts/vision-status.mjs +682 -0
  65. package/skills-lock.json +8 -8
  66. package/src/agents/aphrodite.md +13 -10
  67. package/src/agents/apollo.md +4 -5
  68. package/src/agents/athena.md +74 -46
  69. package/src/agents/demeter.md +10 -7
  70. package/src/agents/gaia.md +0 -1
  71. package/src/agents/hephaestus.md +4 -3
  72. package/src/agents/hermes.md +10 -9
  73. package/src/agents/iris.md +6 -1
  74. package/src/agents/mnemosyne.md +10 -4
  75. package/src/agents/nyx.md +4 -4
  76. package/src/agents/prometheus.md +12 -11
  77. package/src/agents/talos.md +6 -0
  78. package/src/agents/zeus.md +84 -56
  79. package/src/instructions/agent-return-format.instructions.md +12 -41
  80. package/src/instructions/memory-protocol.instructions.md +5 -11
  81. package/src/instructions/test-economy.instructions.md +12 -0
  82. package/src/instructions/yagni.instructions.md +6 -15
  83. package/src/instructions/zeus-anti-stall.instructions.md +6 -6
  84. package/src/instructions/zeus-communication-rules.instructions.md +6 -6
  85. package/src/instructions/zeus-council-synthesis.instructions.md +11 -12
  86. package/src/instructions/zeus-memory-operations.instructions.md +13 -7
  87. package/src/instructions/zeus-timeout-retry.instructions.md +36 -10
  88. package/src/mcp/_pantheon_paths.py +24 -0
  89. package/src/mcp/mcp_codemap_module.py +86 -18
  90. package/src/mcp/mcp_persistence.py +1535 -1050
  91. package/src/mcp/memory_mcp.py +444 -94
  92. package/src/mcp/pantheon_vision.py +285 -41
  93. package/src/mcp/requirements-mcp.txt +5 -0
  94. package/src/pantheon/context-pruner.ts +541 -0
  95. package/src/pantheon/cost-command.ts +814 -60
  96. package/src/pantheon/goal-loop.ts +11 -8
  97. package/src/pantheon/memory-context.ts +1017 -0
  98. package/src/pantheon/model-agents.ts +19 -0
  99. package/src/pantheon/model-command.ts +218 -56
  100. package/src/pantheon/model-pricing.ts +536 -0
  101. package/src/pantheon/presets.mjs +2 -0
  102. package/src/pantheon/task-result-guard.ts +50 -14
  103. package/src/pantheon/v2-bounded-read.ts +640 -0
  104. package/src/pantheon/v2-delegation-enforce.ts +133 -6
  105. package/src/pantheon/v2-execute-after.ts +135 -24
  106. package/src/pantheon/v2-model-overrides.ts +275 -0
  107. package/src/pantheon/v2-tools.ts +89 -35
  108. package/src/pantheon/v2-unsupported.mjs +2 -3
  109. package/src/pantheon/v2-vision.ts +622 -0
  110. package/src/pantheon/vision-local.ts +531 -0
  111. package/src/pantheon/vision.ts +1160 -115
  112. package/src/plugin-v2.ts +654 -162
  113. package/src/plugin.ts +15 -11
  114. package/src/plugins/tui/dist/tui-v2.d.ts +1029 -2
  115. package/src/plugins/tui/dist/tui-v2.d.ts.map +1 -1
  116. package/src/plugins/tui/dist/tui-v2.js +3742 -85
  117. package/src/plugins/tui/dist/tui.js +1 -1
  118. package/src/plugins/tui/package-lock.json +6 -6
  119. package/src/plugins/tui/package.json +5 -4
  120. package/src/plugins/tui/src/index-v2.tsx +4314 -50
  121. package/src/plugins/tui/tsconfig.typecheck.json +5 -0
  122. package/src/routing.yml +50 -5
  123. package/src/skills/agent-coordination/SKILL.md +7 -2
  124. package/src/skills/artifact-management/SKILL.md +5 -1
  125. package/src/skills/auto-continue/SKILL.md +14 -6
  126. package/src/skills/codemap/SKILL.md +1 -1
  127. package/src/skills/memory-bank/SKILL.md +21 -13
  128. package/src/skills/session-goal/SKILL.md +12 -22
  129. package/src/skills/spec-driven-development/SKILL.md +3 -1
  130. package/src/skills/worktrees/SKILL.md +30 -11
  131. package/scripts/probe-context-rehydrate.mjs +0 -263
@@ -0,0 +1,5 @@
1
+ {
2
+ "//": "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.",
3
+ "extends": "./tsconfig.build.json",
4
+ "include": ["src/index-v2.tsx", "src/opencode-v2.d.ts"]
5
+ }
package/src/routing.yml CHANGED
@@ -3,7 +3,7 @@ presets:
3
3
  go-free:
4
4
  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."
5
5
  vision:
6
- model: opencode/mimo-v2.5-free
6
+ model: opencode/mimo-v2.6-flash-free
7
7
  reasoning_effort: low
8
8
  providers:
9
9
  opencode:
@@ -72,6 +72,51 @@ presets:
72
72
  iris: { model: opencode-go/gpt-5.6-luna, reasoning_effort: low }
73
73
  mnemosyne: { model: opencode-go/gpt-5.6-luna, reasoning_effort: low }
74
74
  talos: { model: opencode-go/gpt-5.6-luna, reasoning_effort: low }
75
+ go-hybrid:
76
+ description: "OpenCode Go hybrid lineup: premium models for Zeus, Athena, Themis, and Hephaestus; the existing low-latency Go lineup for every other agent."
77
+ vision:
78
+ model: opencode-go/gpt-5.6-sol
79
+ reasoning_effort: high
80
+ providers:
81
+ opencode-go:
82
+ baseURL: https://opencode.ai/zen/go/v1
83
+ apiKeyEnv: PANTHEON_OPENCODE_API_KEY
84
+ agents:
85
+ zeus: { model: opencode-go/gpt-5.6-sol, reasoning_effort: medium }
86
+ athena: { model: opencode-go/deepseek-v4-pro, reasoning_effort: high }
87
+ themis: { model: opencode-go/qwen3.8-max, reasoning_effort: high }
88
+ hermes: { model: opencode-go/deepseek-v4-flash, reasoning_effort: medium }
89
+ aphrodite: { model: opencode-go/mimo-v2.5, reasoning_effort: low }
90
+ demeter: { model: opencode-go/gpt-5.6-luna, reasoning_effort: low }
91
+ prometheus: { model: opencode-go/deepseek-v4-flash, reasoning_effort: medium }
92
+ hephaestus: { model: opencode-go/gpt-5.6-terra, reasoning_effort: medium }
93
+ apollo: { model: opencode-go/gpt-5.6-luna-fast, reasoning_effort: low }
94
+ nyx: { model: opencode-go/gpt-5.6-luna-fast, reasoning_effort: low }
95
+ gaia: { model: opencode-go/gpt-5.6-luna-fast, reasoning_effort: low }
96
+ iris: { model: opencode-go/gpt-5.6-luna-fast, reasoning_effort: low }
97
+ mnemosyne: { model: opencode-go/gpt-5.6-luna-fast, reasoning_effort: low }
98
+ talos: { model: opencode-go/gpt-5.6-luna-fast, reasoning_effort: low }
99
+ anthropic:
100
+ description: "Anthropic direct provider profile using claude-sonnet-5-5 for every agent. Configure ANTHROPIC_API_KEY in your environment."
101
+ providers:
102
+ anthropic:
103
+ baseURL: https://api.anthropic.com/v1
104
+ apiKeyEnv: ANTHROPIC_API_KEY
105
+ agents:
106
+ zeus: { model: anthropic/claude-sonnet-5-5, reasoning_effort: medium }
107
+ athena: { model: anthropic/claude-sonnet-5-5, reasoning_effort: medium }
108
+ themis: { model: anthropic/claude-sonnet-5-5, reasoning_effort: medium }
109
+ hermes: { model: anthropic/claude-sonnet-5-5, reasoning_effort: medium }
110
+ aphrodite: { model: anthropic/claude-sonnet-5-5, reasoning_effort: medium }
111
+ demeter: { model: anthropic/claude-sonnet-5-5, reasoning_effort: medium }
112
+ prometheus: { model: anthropic/claude-sonnet-5-5, reasoning_effort: medium }
113
+ hephaestus: { model: anthropic/claude-sonnet-5-5, reasoning_effort: medium }
114
+ apollo: { model: anthropic/claude-sonnet-5-5, reasoning_effort: medium }
115
+ nyx: { model: anthropic/claude-sonnet-5-5, reasoning_effort: medium }
116
+ gaia: { model: anthropic/claude-sonnet-5-5, reasoning_effort: medium }
117
+ iris: { model: anthropic/claude-sonnet-5-5, reasoning_effort: medium }
118
+ mnemosyne: { model: anthropic/claude-sonnet-5-5, reasoning_effort: medium }
119
+ talos: { model: anthropic/claude-sonnet-5-5, reasoning_effort: medium }
75
120
  openai:
76
121
  description: "Pure OpenAI provider 2026: gpt-5.6-sol planners high, gpt-5.6-luna implementers high, gpt-5.6-luna-fast scouts low (fallback to luna low). Provider openai https://api.openai.com/v1 OPENAI_API_KEY. Pricing 2026."
77
122
  vision:
@@ -551,12 +596,12 @@ hashline:
551
596
  # with per-line sha256 tags (12#XJ|content); hashline_edit anchors edits to
552
597
  # those refs. Documentation mirror — the plugin resolves behavior in code.
553
598
  full_auto:
554
- enabled: false # opt-in: goal continuations are OFF by default
555
- max_continuations: 25 # hard cap on goal continuations per session
599
+ enabled: false # Documentation only; no runtime config enables the loop in this build.
600
+ max_continuations: 25 # Documented hard cap; routing.yml is not loaded for loop settings.
556
601
  # Full-auto only continues a task/scope explicitly authorized by the user.
557
602
  # It never authorizes auth/security gates, risky data/schema or destructive
558
603
  # operations, global config, broad permissions, production deploy, push, or merge.
559
604
  # Low-risk execution is proportional: no forced plan/discovery/council/artifact
560
- # for a bounded fix; use focused verification. Documentation mirror — runtime
561
- # behavior is implemented in the plugin (GOAL_LOOP_DEFAULTS).
605
+ # for a bounded fix; use focused verification. This section documents guards
606
+ # and defaults only; the plugin uses GOAL_LOOP_DEFAULTS directly.
562
607
  # Wave 3 (PR #46): one active goal per session (pending → in_progress → done).
@@ -34,8 +34,8 @@ Route tasks to optimized agents based on category instead of specifying agents m
34
34
 
35
35
  ```
36
36
  1. User describes feature
37
- 2. @athena creates PLAN with phases and agents
38
- 3. User approves PLAN (GATE 1)
37
+ 2. @athena returns the complete PLAN to Zeus (no approval prompt from the child session)
38
+ 3. Zeus displays the full PLAN in the main conversation, then asks the user to approve it (GATE 1)
39
39
  4. Zeus dispatches agents to phases (parallel when possible)
40
40
  5. Each agent: TDD cycle → writes IMPL artifact
41
41
  6. @themis reviews all phases (GATE 2)
@@ -67,6 +67,11 @@ All phase outputs go to `.pantheon/memory-bank/.tmp/`. See `skill: artifact-mana
67
67
 
68
68
  ## Safety Gates
69
69
 
70
+ For every requested plan, Gate 1 is not satisfied by a child-agent approval
71
+ question or a link to a hidden artifact: the complete plan must be visible in
72
+ the main conversation before Zeus asks for approval. If the user requests
73
+ changes, Zeus presents the complete revised plan and repeats Gate 1.
74
+
70
75
  | Gate | When | Why |
71
76
  |------|------|-----|
72
77
  | **GATE 1** | After PLAN | User confirms scope |
@@ -23,12 +23,16 @@ All ephemeral artifacts live in `.pantheon/memory-bank/.tmp/` — gitignored and
23
23
  │ ├── IMPL-phase1-hermes.md
24
24
  │ ├── IMPL-phase1-aphrodite.md
25
25
  │ └── REVIEW-<feature>.md
26
- ├── _notes/ ← COMMITTED — permanent ADRs
26
+ ├── _notes/ ← permanent ADRs; Git tracking follows repository policy
27
27
  │ └── ADR-<topic>.md
28
28
  ├── 01-active-context.md
29
29
  └── 02-progress-log.md
30
30
  ```
31
31
 
32
+ Memory Bank files are not automatically versioned or shared across clones.
33
+ Check the repository's ignore/commit policy before relying on `_tasks/` records
34
+ or other files being tracked; `_tasks/` may be Git-ignored.
35
+
32
36
  ---
33
37
 
34
38
  ## Artifact Types
@@ -55,16 +55,16 @@ Full-auto may continue only within a task and scope the user explicitly authoriz
55
55
  ## Implementation Pattern
56
56
 
57
57
  ```
58
- 1. Create todos only for multi-step work; a one-step fix needs no todo ceremony
59
- 2. Mark first todo in_progress
60
- 3. Complete work → mark completed immediately
61
- 4. Mark next todo in_progress → repeat
58
+ 1. Create a checklist only for multi-step work; a one-step fix needs no todo ceremony
59
+ 2. Use native todo operations only when a todo-write tool is visible in the active session; otherwise keep the checklist explicit in the conversation
60
+ 3. Mark work complete in the available checklist as soon as it is done
61
+ 4. Do not claim that the native todo list was updated when no todo-write tool is exposed
62
62
  5. Do NOT ask "should I continue?" between clear steps
63
63
  6. Stop at any applicable risk gate; do not require a plan/review gate for a low-risk edit
64
64
  7. After gate approval, resume with next todo
65
65
  ```
66
66
 
67
- **Never batch-complete todos.** Mark each completed as soon as done.
67
+ **Never batch-complete checklist items.** Mark each completed as soon as done; do not imply a tool call occurred unless it did.
68
68
 
69
69
  ---
70
70
 
@@ -107,6 +107,14 @@ Only expand to full cooldown when hitting a mandatory gate.
107
107
 
108
108
  ## Timeout & Retry Enforcement
109
109
 
110
+ Delegate through the root `subagent` tool observed in the Beta 10 runtime. `task()` is
111
+ host/API terminology, not an assumed root tool; call shape and background support are
112
+ runtime-dependent. Prefer synchronous dispatch unless the active schema exposes background
113
+ and the host provides an observable completion notification. Do not assume `task_status`,
114
+ `cancel_task`, or board-based tracking/recovery tools are available. When no completion
115
+ mechanism is observable, use synchronous dispatch or state the limitation; do not claim
116
+ that jobs are being tracked or recovered.
117
+
110
118
  When a delegated agent does not respond in time, enforce the timeout policy defined in
111
119
  `src/instructions/zeus-timeout-retry.instructions.md`.
112
120
 
@@ -128,7 +136,7 @@ When dispatching, set the expectation explicitly:
128
136
 
129
137
  ### Timeout Tracking Table
130
138
 
131
- Maintain a mental table of in-flight delegations:
139
+ Maintain an in-context (not persistent/native) checklist of delegations when needed:
132
140
 
133
141
  | Agent | Started | Timeout | Status | Partial OK? |
134
142
  |-------|---------|---------|--------|-------------|
@@ -50,5 +50,5 @@ Generate a hierarchical map of the codebase to understand its structure, key mod
50
50
  Antes de glob/grep manual, tente `code_query`:
51
51
  - `code_query("MyClass")` → busca FTS5 por entidade
52
52
  - Fallback para glob/grep se não indexado ou query vazia
53
- - `code_index("src/")` para indexação incremental (hash-based, skip se não mudou, force=true para re-index)
53
+ - `code_index` não está disponível sob os grants atuais: nenhum agente recebeu essa permissão. Os resultados de consulta dependem de um índice já existente.
54
54
  - `code_neighbors(entity_id, depth=2)` para grafo de imports/calls
@@ -12,12 +12,19 @@ Complete guide to Pantheon memory bank — structure, rules, optimization, and m
12
12
 
13
13
  ---
14
14
 
15
- ## Two-System Model
15
+ ## Actual Storage Model
16
16
 
17
17
  | System | Where | Owner | Lifetime | Purpose |
18
18
  |--------|-------|-------|----------|---------|
19
- | **Memory Bank** | `.pantheon/memory-bank/` | Team | Permanent, versioned | Project context: architecture, patterns, progress |
20
- | **VS Code `/memories/`** | `.vscode/` or workspace | Agent | Session/repo scoped | Atomic facts, conversation plans |
19
+ | **Durable Memory** | `pantheon-memory` MCP (SQLite `memory.db`) | Agents with the relevant tool grant | No entry TTL; retained until explicitly forgotten | Reusable facts and decisions |
20
+ | **Persistence** | `pantheon-persistence` MCP | Agents with the relevant tool grant | Optional, separate checkpoint/KV store; checkpoint TTLs apply | Explicit session/workflow checkpoints and temporary state |
21
+ | **Memory Bank** | `.pantheon/memory-bank/` | Team | Files persist in the working tree; Git tracking depends on repository ignore/commit policy | Project context: architecture, patterns, progress, ADRs |
22
+
23
+ Pantheon does not implement `/memories/repo/` or `/memories/session/` stores.
24
+ Memory Bank files are read explicitly or on demand through
25
+ `pantheon://memory-bank/{path}` from `pantheon-resources`; they are not
26
+ auto-loaded. Memory namespaces are organizational filters, not access-control
27
+ boundaries, and tools are available only when the active agent is granted them.
21
28
 
22
29
  ---
23
30
 
@@ -39,6 +46,10 @@ Complete guide to Pantheon memory bank — structure, rules, optimization, and m
39
46
  └── NOTE0001-topic.md ← Architectural decisions, findings
40
47
  ```
41
48
 
49
+ Memory Bank files are not automatically synchronized across clones. In
50
+ particular, `_tasks/` records may be Git-ignored; only files tracked and
51
+ committed under the repository's policy are shared through Git.
52
+
42
53
  ### File Update Frequency
43
54
 
44
55
  | File | Fill when | Update frequency |
@@ -64,13 +75,9 @@ Complete guide to Pantheon memory bank — structure, rules, optimization, and m
64
75
 
65
76
  ---
66
77
 
67
- ## Session → Active Context Graduation
78
+ ## Session → Project Context Graduation
68
79
 
69
80
  ```
70
- During sprint:
71
- Athena writes plan → /memories/session/sprint-plan.md (ephemeral)
72
- Agents track wip → /memories/session/wip.md (ephemeral)
73
-
74
81
  At sprint close:
75
82
  @mnemosyne consolidates → .pantheon/memory-bank/01-active-context.md
76
83
  → .pantheon/memory-bank/02-progress-log.md (appended)
@@ -87,8 +94,9 @@ At sprint close:
87
94
  | Milestone completions | Any agent | `02-progress-log.md` (append) |
88
95
  | Task records | Mnemosyne (on request) | `_tasks/TASK000X-*.md` |
89
96
  | Architecture decisions | Mnemosyne (on request) | `_notes/NOTE000X-*.md` |
90
- | Atomic facts | Any agent | `/memories/repo/` |
91
- | Conversation plans | Athena / any agent | `/memories/session/` |
97
+ | Reusable durable fact or decision | Agent with explicit `memory_store` grant, when retention is warranted | `pantheon-memory` |
98
+ | Conversation-only goal | Current session instructions / `/pantheon-focus` | Not durable; no `/memories/session/` store |
99
+ | Project narrative and ADRs | Mnemosyne on explicit request | `.pantheon/memory-bank/` |
92
100
 
93
101
  ---
94
102
 
@@ -143,10 +151,10 @@ At sprint close → explicit @mnemosyne invocation
143
151
 
144
152
  ### ❌ Duplicating information
145
153
  ```
146
- # Wrong: Stack in 00-project.md AND /memories/repo/stack.json
154
+ # Wrong: duplicate the same fact in both durable Memory and a project document
147
155
 
148
- # Right: Atomic facts → /memories/repo/ (auto-loaded)
149
- Narrative context → 00-project.md (explicit read)
156
+ # Right: Durable reusable fact → pantheon-memory (when warranted and granted)
157
+ Narrative context → 00-project.md (read on demand)
150
158
  ```
151
159
 
152
160
  ---
@@ -72,28 +72,18 @@ Before each major delegation or decision, run this quick check:
72
72
 
73
73
  ## Cross-Session Continuity
74
74
 
75
- V2 does not provide durable goal tools. `/pantheon-focus` only anchors the current
76
- conversation and must not be described as surviving compaction or a new
77
- session. For multi-phase work that needs persistent checkpoints, use
78
- `/pantheon-deepwork`; otherwise ask before writing a goal to a project file.
79
-
80
- In V1, use the implemented goal tools when they are available and explicitly
81
- authorized. Do not infer that their presence in one host generation means they
82
- exist in V2.
83
-
84
- Historical path example (not a V2 runtime command):
85
-
86
- ```
87
- /memories/session/current-goal.md
88
-
89
- # Active Session Goal
90
- Goal: Implement JWT authentication
91
- Started: 2026-05-15
92
- Status: Phase 2 of 3 (backend done, frontend in progress)
93
- Next: POST /auth/refresh endpoint
94
- ```
95
-
96
- This file-based approach requires explicit authorization and is not automatic.
75
+ The V2 plugin does not register the V1 `pantheon_goal_*` tools. `/pantheon-focus`
76
+ only anchors the current conversation and must not be described as surviving
77
+ compaction or a new session. For multi-phase work that needs persistent
78
+ checkpoints, use `/pantheon-deepwork`; otherwise ask before writing a goal to a
79
+ project file.
80
+
81
+ Pantheon does not implement a `/memories/session/` filesystem store. The V1
82
+ goal tools are deprecated legacy manual record tools: stored goals are not
83
+ automatically continued in the current build. Durable manual goals are
84
+ available through the separate Persistence MCP `goal_*` surface in this branch;
85
+ do not present it as released or as part of the V2 plugin. `/pantheon-focus`
86
+ remains a non-persistent conversation anchor.
97
87
 
98
88
  ---
99
89
 
@@ -12,7 +12,9 @@ description: "Define requirements via spec-first before any code — PRD, edge c
12
12
  2. **PRD** — Escreva um documento de requisitos: objetivo, personas, fluxos, regras de negócio, critérios de aceitação
13
13
  3. **Edge Cases** — Mapeie entradas inválidas, concorrência, falhas de API, estados vazios
14
14
  4. **Technical Spec** — Decisões de arquitetura: componentes, dados, API contracts, deploy
15
- 5. **Approval** — Apresente ao usuário antes de codar. "É isso mesmo?"
15
+ 5. **Approval** — Apresente o plano completo ao usuário antes de codar. Se o
16
+ planejamento veio de um subagente, devolva o plano integral ao orquestrador
17
+ para que ele o exiba na conversa principal antes de pedir aprovação.
16
18
 
17
19
  ## Anti-patterns
18
20
  - ❌ Pular direto pra implementação
@@ -16,28 +16,47 @@ Use git worktrees to create isolated working directories for parallel or experim
16
16
 
17
17
  ## Setup
18
18
 
19
+ Use this persistent external default for new worktrees:
20
+
21
+ ```text
22
+ <project-parent>/.pantheon-worktrees/<exact-repository-directory-basename>/<task>
23
+ ```
24
+
25
+ Resolve the project directory to an absolute path, then use its exact final
26
+ directory basename as the repository component; spaces are valid and must not
27
+ be normalized into a potentially colliding slug. For example, a project at
28
+ `/home/user/My Project` uses
29
+ `/home/user/.pantheon-worktrees/My Project/feature-name`. Replace
30
+ `<task>` with a short descriptive task name. This keeps worktrees outside
31
+ the project and reuses the same location across agent sessions.
32
+
19
33
  ```bash
20
- # Create a worktree
21
- git worktree add ../project-feature-x feature-x
34
+ # Create a worktree at the recommended external location
35
+ git worktree add "/home/user/.pantheon-worktrees/My Project/feature-name" task-branch
36
+
37
+ # List worktrees and their absolute paths
38
+ git worktree list --porcelain
22
39
 
23
- # List worktrees
24
- git worktree list
40
+ # Only after the user explicitly authorizes removal, remove that exact worktree
41
+ git worktree remove "/home/user/.pantheon-worktrees/My Project/feature-name"
25
42
 
26
- # Remove a worktree
27
- git worktree remove ../project-feature-x
43
+ # Only after the user explicitly authorizes branch deletion
44
+ git branch -d task-branch
28
45
  ```
29
46
 
30
47
  ## Workflow
31
48
 
32
- 1. Create worktree: `git worktree add ../<name> <branch>`
49
+ 1. Resolve the project directory to an absolute path and create the worktree at `<project-parent>/.pantheon-worktrees/<exact-repository-directory-basename>/<task>`.
33
50
  2. Work in the worktree directory
34
51
  3. Commit and push from within the worktree
35
- 4. Clean up: `git worktree remove ../<name>`
36
- 5. Delete branch if no longer needed
52
+ 4. Leave the worktree and branch in place when the task is done unless the user explicitly authorizes removal or deletion.
53
+ 5. If authorized, remove only the exact worktree path above; delete its branch only with separate explicit user authorization.
37
54
 
38
55
  ## Rules
39
56
  - Never create worktrees inside the main project directory
40
- - Name worktrees descriptively: `../project-auth-refactor`
41
- - Remove worktrees when done (they consume disk space)
57
+ - Use the persistent external default `<project-parent>/.pantheon-worktrees/<exact-repository-directory-basename>/<task>`
58
+ - Use the exact repository directory basename (spaces included); do not normalize it into a lossy slug
59
+ - Name worktrees descriptively, for example `feature-name` or `auth-refactor`
60
+ - Never remove a worktree or delete a branch unless the user explicitly authorizes that action
42
61
  - Worktrees share the same git history — pushing from a worktree is the same as pushing from main
43
62
  - Escalate to @iris for branch management if unsure
@@ -1,263 +0,0 @@
1
- #!/usr/bin/env node
2
- import { spawnSync } from 'node:child_process'
3
- /**
4
- * Offline/ambiental probe for context_rehydrate and context_session_summary.
5
- *
6
- * The Python child imports the installed persistence server and exercises the
7
- * real FastMCP tools against a temporary SQLite database. No OpenCode command,
8
- * network call, LLM, or user database is involved. Missing package/runtime is
9
- * NOT_TESTED/AMBIENTAL rather than a false PASS.
10
- */
11
- import { existsSync, mkdtempSync, rmSync } from 'node:fs'
12
- import { tmpdir } from 'node:os'
13
- import { join } from 'node:path'
14
- import { fileURLToPath } from 'node:url'
15
-
16
- const requestedVersion = valueFor('--version')
17
- const jsonOutput = process.argv.includes('--json')
18
- const runtime = fileURLToPath(new URL('./mcp_persistence.py', import.meta.url))
19
-
20
- function valueFor(name) {
21
- const index = process.argv.indexOf(name)
22
- return index >= 0 ? process.argv[index + 1] : undefined
23
- }
24
-
25
- function emit(status, detail, checks = []) {
26
- const result = { status, version: requestedVersion, detail, checks }
27
- if (jsonOutput) process.stdout.write(JSON.stringify(result))
28
- else process.stdout.write(`${status}: ${detail}\n`)
29
- if (status === 'FAIL') process.exitCode = 1
30
- }
31
-
32
- function unavailable(detail) {
33
- emit('NOT_TESTED', detail)
34
- }
35
-
36
- function pythonCandidates() {
37
- const venvPython = process.env.HOME
38
- ? join(process.env.HOME, '.config', 'opencode', '.venv', 'bin', 'python')
39
- : undefined
40
- return [process.env.PANTHEON_PYTHON, venvPython, 'python3'].filter(Boolean)
41
- }
42
-
43
- const PYTHON_HARNESS = `
44
- import asyncio
45
- import importlib.util
46
- import json
47
- import os
48
- import sys
49
- from pathlib import Path
50
-
51
- runtime_path = Path(sys.argv[1]).resolve()
52
- db_root = Path(sys.argv[2]).resolve()
53
- sys.path.insert(0, str(runtime_path.parent))
54
- sys.argv = [str(runtime_path), "--global-db", str(db_root / "global.db"),
55
- "--project-db", str(db_root / "project.db")]
56
-
57
- spec = importlib.util.spec_from_file_location("probe_mcp_persistence", runtime_path)
58
- if spec is None or spec.loader is None:
59
- raise RuntimeError("could not load persistence runtime")
60
- module = importlib.util.module_from_spec(spec)
61
- spec.loader.exec_module(module)
62
-
63
-
64
- async def call(name, arguments):
65
- result = await module.mcp.call_tool(name, arguments)
66
- structured = getattr(result, "structured_content", None)
67
- if structured is not None:
68
- metadata = getattr(result, "meta", None) or {}
69
- if metadata.get("fastmcp", {}).get("wrap_result"):
70
- return structured.get("result") if isinstance(structured, dict) else structured
71
- return structured
72
- if isinstance(result, tuple):
73
- structured = result[1]
74
- if structured is not None:
75
- if isinstance(structured, dict) and "result" in structured:
76
- return structured["result"]
77
- return structured
78
- result = result[0]
79
- if isinstance(result, dict):
80
- return result
81
- if not result:
82
- return None
83
- text = getattr(result[0], "text", str(result[0]))
84
- try:
85
- return json.loads(text)
86
- except (TypeError, ValueError, json.JSONDecodeError):
87
- return text
88
-
89
-
90
- async def main():
91
- checks = []
92
- slug = "context-rehydrate-probe"
93
- session_id = "synthetic-session"
94
- checkpoint = {
95
- "version": 1,
96
- "goal": {"id": "probe-goal", "objective": "verify context recovery",
97
- "status": "in_progress"},
98
- "phase": {"current": 2, "total": 3, "name": "offline validation"},
99
- "delegations": {"in_flight": [{"alias": "apo-probe", "agent": "apollo",
100
- "task_id": "probe-task"}]},
101
- }
102
- tail = ["phase 1 complete", "phase 2 payload validated"]
103
-
104
- # context_save creates the real session-qualified latest pointer. Keeping
105
- # tail under its own key also tests the runtime's latest/tail fallback.
106
- await call("context_save", {"slug": slug, "key": "tail",
107
- "content": json.dumps(tail),
108
- "session_id": session_id})
109
- await call("context_save", {"slug": slug, "key": "phase:2",
110
- "content": json.dumps(checkpoint),
111
- "session_id": session_id})
112
- latest = await call("context_get", {"slug": slug, "key": "latest",
113
- "session_id": session_id})
114
- stored_tail = await call("context_get", {"slug": slug, "key": "tail",
115
- "session_id": session_id})
116
- if latest is None or stored_tail is None:
117
- raise AssertionError("synthetic latest/tail checkpoint payload is null")
118
- checks.append("synthetic latest/tail/goal/phase/delegation checkpoint: PASS")
119
-
120
- os.environ.pop("PANTHEON_COMPACTION", None)
121
- os.environ.pop("PANTHEON_SESSION_END_SUMMARY", None)
122
- blocks = await call("context_rehydrate", {"slug": slug,
123
- "session_id": session_id})
124
- summary = await call("context_session_summary", {"slug": slug,
125
- "session_id": session_id})
126
- if not isinstance(blocks, list) or not blocks:
127
- raise AssertionError("context_rehydrate returned a null/empty payload")
128
- if not isinstance(summary, str) or not summary:
129
- raise AssertionError("context_session_summary returned a null/empty payload")
130
- for fragment in ("verify context recovery", "phase 2/3", "apo-probe",
131
- "phase 2 payload validated"):
132
- if not any(fragment in block for block in blocks) and fragment not in summary:
133
- raise AssertionError(f"payload is missing {fragment!r}")
134
- checks.append("context_rehydrate non-null payload: PASS")
135
- checks.append("context_session_summary non-null payload: PASS")
136
-
137
- missing_blocks = await call("context_rehydrate", {"slug": "probe-absent",
138
- "session_id": session_id})
139
- missing_summary = await call("context_session_summary", {"slug": "probe-absent",
140
- "session_id": session_id})
141
- if missing_blocks is not None or missing_summary is not None:
142
- raise AssertionError("absent checkpoint must return null payloads")
143
- checks.append("absence returns null: PASS")
144
-
145
- expired_slug = "context-expired-probe"
146
- await call("context_save", {"slug": expired_slug, "key": "phase:1",
147
- "content": json.dumps(checkpoint), "ttl": 1,
148
- "session_id": session_id})
149
- # Use the public TTL contract (positive seconds) and let the entry expire;
150
- # negative TTLs are rejected by validation and must not be special-cased.
151
- await asyncio.sleep(1.2)
152
- expired_blocks = await call("context_rehydrate", {"slug": expired_slug,
153
- "session_id": session_id})
154
- expired_summary = await call("context_session_summary", {"slug": expired_slug,
155
- "session_id": session_id})
156
- if expired_blocks is not None or expired_summary is not None:
157
- raise AssertionError("expired checkpoint must return null payloads")
158
- checks.append("expiration returns null: PASS")
159
-
160
- invalid_slug = "context-invalid-probe"
161
- await call("context_save", {"slug": invalid_slug, "key": "phase:1",
162
- "content": "not-json", "session_id": session_id})
163
- invalid_blocks = await call("context_rehydrate", {"slug": invalid_slug,
164
- "session_id": session_id})
165
- invalid_summary = await call("context_session_summary", {"slug": invalid_slug,
166
- "session_id": session_id})
167
- if invalid_blocks is not None or invalid_summary is not None:
168
- raise AssertionError("invalid checkpoint must return null payloads")
169
- checks.append("invalid payload returns null: PASS")
170
-
171
- os.environ["PANTHEON_COMPACTION"] = "off"
172
- switched_blocks = await call("context_rehydrate", {"slug": slug,
173
- "session_id": session_id})
174
- if switched_blocks is not None:
175
- raise AssertionError("PANTHEON_COMPACTION=off must return null")
176
- os.environ.pop("PANTHEON_COMPACTION", None)
177
- os.environ["PANTHEON_SESSION_END_SUMMARY"] = "off"
178
- switched_summary = await call("context_session_summary", {"slug": slug,
179
- "session_id": session_id})
180
- if switched_summary is not None:
181
- raise AssertionError("PANTHEON_SESSION_END_SUMMARY=off must return null")
182
- checks.append("kill-switches return null: PASS")
183
- print(json.dumps({"checks": checks}))
184
-
185
-
186
- asyncio.run(main())
187
- `
188
-
189
- async function main() {
190
- if (requestedVersion !== 'v1' && requestedVersion !== 'v2') {
191
- emit('FAIL', 'usage: --version v1|v2 [--json]')
192
- return
193
- }
194
- if (!existsSync(runtime)) {
195
- unavailable('installed package does not include mcp_persistence.py')
196
- return
197
- }
198
-
199
- const root = mkdtempSync(join(tmpdir(), 'pantheon-context-probe-'))
200
- const dbRoot = join(root, 'db')
201
- const python = pythonCandidates().find((candidate) =>
202
- candidate.includes('/') ? existsSync(candidate) : true,
203
- )
204
- if (!python) {
205
- rmSync(root, { recursive: true, force: true })
206
- unavailable('Python persistence runtime is not available')
207
- return
208
- }
209
-
210
- try {
211
- const child = spawnSync(python, ['-c', PYTHON_HARNESS, runtime, dbRoot], {
212
- encoding: 'utf8',
213
- timeout: 30000,
214
- env: process.env,
215
- })
216
- if (child.error) {
217
- const detail = child.error instanceof Error ? child.error.message : String(child.error)
218
- if (/EACCES|permission denied|not found/i.test(detail)) {
219
- emit('AMBIENTAL', `persistence runtime unavailable: ${detail}`)
220
- } else {
221
- unavailable(`persistence runtime unavailable: ${detail}`)
222
- }
223
- return
224
- }
225
- if (child.signal === 'SIGTERM') {
226
- emit('AMBIENTAL', 'persistence probe timed out after 30s')
227
- return
228
- }
229
- if (/IncompleteFieldDefinitionWarning|pydantic_settings/i.test(child.stderr)) {
230
- emit('FAIL', 'persistence probe emitted an incomplete pydantic_settings field warning')
231
- return
232
- }
233
- if (child.status !== 0) {
234
- const detail = `${child.stderr || child.stdout || 'persistence probe failed'}`.trim()
235
- if (
236
- /No module named|ModuleNotFoundError|can't open file|No such file|importerror/i.test(detail)
237
- ) {
238
- unavailable(`persistence runtime unavailable: ${detail.slice(0, 320)}`)
239
- } else {
240
- emit('FAIL', `offline persistence checks failed: ${detail.slice(0, 320)}`)
241
- }
242
- return
243
- }
244
-
245
- const lines = child.stdout.trim().split('\n').filter(Boolean)
246
- const payload = JSON.parse(lines.at(-1) || '')
247
- if (!Array.isArray(payload.checks) || payload.checks.length < 6) {
248
- emit('FAIL', 'offline persistence probe returned incomplete checks')
249
- return
250
- }
251
- emit(
252
- 'PASS',
253
- 'offline synthetic persistence checks passed; no LLM or user DB was used',
254
- payload.checks,
255
- )
256
- } catch (error) {
257
- emit('FAIL', error instanceof Error ? error.message : String(error))
258
- } finally {
259
- rmSync(root, { recursive: true, force: true })
260
- }
261
- }
262
-
263
- await main()