pantheon-opencode 1.7.0 → 2.0.0-beta.2

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 (173) hide show
  1. package/AGENTS.global.md +2 -2
  2. package/AGENTS.md +3 -3
  3. package/CHANGELOG.md +85 -59
  4. package/README.md +74 -48
  5. package/README.pt-BR.md +19 -19
  6. package/bin/pantheon-init.mjs +11 -48
  7. package/package.json +9 -13
  8. package/plugin.json +2 -2
  9. package/pyproject.toml +1 -1
  10. package/scripts/build-agents-md.mjs +7 -6
  11. package/scripts/{check-plugin-v2-coverage.mjs → check-plugin-coverage.mjs} +7 -7
  12. package/scripts/{decision-router-v2-budget.mjs → decision-router-budget-gates.mjs} +1 -1
  13. package/scripts/{decision-router-v2-egress.mjs → decision-router-egress.mjs} +1 -1
  14. package/scripts/decision-router.mjs +2 -2
  15. package/scripts/docs-media.mjs +1 -1
  16. package/scripts/doctor.mjs +225 -136
  17. package/scripts/install/behavior-overrides.bundle.mjs +123 -0
  18. package/scripts/install/{v2-capabilities.mjs → capabilities.mjs} +7 -7
  19. package/scripts/install/config-migration.mjs +60 -253
  20. package/scripts/install/file-inventory.mjs +6 -4
  21. package/scripts/install/interactive.mjs +1 -1
  22. package/scripts/install/opencode-state.mjs +13 -12
  23. package/scripts/install/opencode-version.mjs +97 -162
  24. package/scripts/install/opencode.mjs +271 -428
  25. package/scripts/install/plan.mjs +1 -9
  26. package/scripts/install/plugin.mjs +19 -35
  27. package/scripts/install/shared.mjs +40 -1
  28. package/scripts/package-evidence.mjs +1 -4
  29. package/scripts/probe-pantheon-cost.mjs +1 -1
  30. package/scripts/reconcile.mjs +5 -7
  31. package/scripts/release-gates.mjs +22 -61
  32. package/scripts/setup-v2-config.mjs +10 -8
  33. package/scripts/setup.mjs +12 -22
  34. package/scripts/sync-tui.mjs +9 -17
  35. package/scripts/{test-opencode-v2-sandbox.sh → test-opencode-sandbox.sh} +9 -9
  36. package/scripts/update-skills-lock.mjs +24 -12
  37. package/scripts/update.mjs +17 -1
  38. package/scripts/validate-routing.mjs +79 -4
  39. package/scripts/validate-sandbox-install.mjs +3 -3
  40. package/skills-lock.json +25 -8
  41. package/src/agents/zeus.md +1 -0
  42. package/src/pantheon/behavior-overrides.ts +191 -0
  43. package/src/pantheon/{v2-bounded-read.ts → bounded-read.ts} +1 -1
  44. package/src/pantheon/cost-command.ts +1 -1
  45. package/src/pantheon/{v2-decision-contracts.ts → decision-contracts.ts} +3 -3
  46. package/src/pantheon/{v2-decision-points → decision-points}/p1-agent.ts +3 -3
  47. package/src/pantheon/{v2-decision-points → decision-points}/p10-claims.ts +2 -2
  48. package/src/pantheon/{v2-decision-points → decision-points}/p11-catalog.ts +2 -2
  49. package/src/pantheon/{v2-decision-points → decision-points}/p2-skill.ts +3 -3
  50. package/src/pantheon/{v2-decision-points → decision-points}/p3-complexity.ts +6 -6
  51. package/src/pantheon/{v2-decision-points → decision-points}/p4-memory.ts +2 -2
  52. package/src/pantheon/{v2-decision-points → decision-points}/p5-themis-verify.ts +2 -2
  53. package/src/pantheon/{v2-decision-points → decision-points}/p6-council.ts +3 -3
  54. package/src/pantheon/{v2-decision-points → decision-points}/p7-loop.ts +5 -5
  55. package/src/pantheon/{v2-decision-points → decision-points}/p8-guardrail.ts +2 -2
  56. package/src/pantheon/{v2-decision-points → decision-points}/p9-memory-compaction.ts +2 -2
  57. package/src/pantheon/{v2-decision-points.ts → decision-points.ts} +5 -5
  58. package/src/pantheon/{v2-decision-policy.ts → decision-policy.ts} +2 -2
  59. package/src/pantheon/{v2-decision-prompt-surface.ts → decision-prompt-surface.ts} +3 -3
  60. package/src/pantheon/{v2-decision-registry.ts → decision-registry.ts} +10 -13
  61. package/src/pantheon/{v2-decision-resource-ids.ts → decision-resource-ids.ts} +1 -1
  62. package/src/pantheon/{v2-decision-shadow.ts → decision-shadow.ts} +1 -1
  63. package/src/pantheon/{v2-decision-telemetry.ts → decision-telemetry.ts} +1 -1
  64. package/src/pantheon/{v2-execute-after.ts → execute-after.ts} +4 -4
  65. package/src/pantheon/goal-store.ts +7 -0
  66. package/src/pantheon/{v2-hook-engine.ts → hook-engine.ts} +3 -3
  67. package/src/pantheon/jev-decision-tool.ts +3 -3
  68. package/src/pantheon/jev-decisions.ts +12 -6
  69. package/src/pantheon/jev-escalation.ts +6 -6
  70. package/src/pantheon/jev-quality-score.ts +2 -2
  71. package/src/pantheon/jev-rank-verify.ts +2 -2
  72. package/src/pantheon/jev-risk-gate.ts +4 -4
  73. package/src/pantheon/local-decision-agents.ts +1 -1
  74. package/src/pantheon/local-decision-router.ts +1 -1
  75. package/src/pantheon/local-decision-tool.ts +2 -2
  76. package/src/pantheon/local-orchestration.ts +1 -1
  77. package/src/pantheon/model-command.ts +1 -1
  78. package/src/pantheon/{v2-vision.ts → native-vision.ts} +12 -15
  79. package/src/pantheon/pantheon-decision-catalog.ts +12 -0
  80. package/src/pantheon/{v2-shell-hooks.ts → shell-hooks.ts} +4 -4
  81. package/src/pantheon/{v2-tools.ts → tools.ts} +4 -4
  82. package/src/pantheon/{v2-unsupported.d.mts → unsupported.d.mts} +3 -3
  83. package/src/pantheon/{v2-unsupported.mjs → unsupported.mjs} +8 -8
  84. package/src/pantheon/update-notifier.ts +101 -0
  85. package/src/pantheon/vision-local.ts +12 -3
  86. package/src/pantheon/vision.ts +120 -2
  87. package/src/{plugin-v2 → plugin}/index.ts +7 -7
  88. package/src/plugin.ts +2870 -500
  89. package/src/plugins/hook-runner.ts +3 -3
  90. package/src/plugins/tui/dist/server.d.ts +23 -9
  91. package/src/plugins/tui/dist/server.d.ts.map +1 -1
  92. package/src/plugins/tui/dist/server.js +25 -12
  93. package/src/plugins/tui/dist/server.js.map +1 -1
  94. package/src/plugins/tui/dist/tui.d.ts +1023 -494
  95. package/src/plugins/tui/dist/tui.d.ts.map +1 -1
  96. package/src/plugins/tui/dist/tui.js +5612 -2086
  97. package/src/plugins/tui/dist/tui.js.map +1 -1
  98. package/src/plugins/tui/{index-v2.ts → index.ts} +1 -1
  99. package/src/plugins/tui/package-lock.json +2 -42
  100. package/src/plugins/tui/package.json +4 -10
  101. package/src/plugins/tui/src/cost-data.ts +1 -1
  102. package/src/plugins/tui/src/decision-router-state.ts +242 -0
  103. package/src/plugins/tui/src/doctor-state.ts +198 -0
  104. package/src/plugins/tui/src/index.tsx +4222 -2822
  105. package/src/plugins/tui/src/j1-gate-status.ts +85 -0
  106. package/src/plugins/tui/src/pantheon-settings-state.ts +245 -0
  107. package/src/plugins/tui/src/pantheon-settings.tsx +442 -0
  108. package/src/plugins/tui/src/preset-state.ts +143 -0
  109. package/src/plugins/tui/src/server.ts +23 -10
  110. package/src/plugins/tui/src/update-notice.ts +90 -0
  111. package/src/plugins/tui/src/update-status.ts +98 -0
  112. package/src/plugins/tui/tsconfig.typecheck.json +9 -2
  113. package/src/plugins/tui/tsdown.config.ts +3 -5
  114. package/src/plugins/tui/tui.ts +1 -2
  115. package/src/routing.yml +36 -0
  116. package/src/skills/README.md +16 -1
  117. package/src/skills/artifact-management/SKILL.md +10 -67
  118. package/src/skills/artifact-management/references/artifact-templates.md +71 -0
  119. package/src/skills/auto-continue/SKILL.md +10 -0
  120. package/src/skills/code-review-checklist/SKILL.md +11 -44
  121. package/src/skills/code-review-checklist/references/review-checklists.md +54 -0
  122. package/src/skills/instruction-forge/SKILL.md +57 -0
  123. package/src/skills/instruction-forge/references/agents-md-doctrine.md +50 -0
  124. package/src/skills/instruction-forge/references/eval-doctrine.md +37 -0
  125. package/src/skills/instruction-forge/references/skill-doctrine.md +62 -0
  126. package/src/skills/memory-bank/SKILL.md +11 -90
  127. package/src/skills/memory-bank/references/anti-patterns.md +33 -0
  128. package/src/skills/memory-bank/references/product-adoption.md +19 -0
  129. package/src/skills/memory-bank/references/storage-model.md +21 -0
  130. package/src/skills/memory-bank/references/structure-and-frequency.md +44 -0
  131. package/src/skills/reflect/SKILL.md +1 -0
  132. package/src/skills/session-goal/SKILL.md +7 -54
  133. package/src/skills/session-goal/references/goal-format.md +26 -0
  134. package/src/skills/session-goal/references/session-reuse.md +44 -0
  135. package/src/skills/tdd-with-agents/SKILL.md +11 -101
  136. package/src/skills/tdd-with-agents/references/advanced-testing-patterns.md +58 -0
  137. package/src/skills/tdd-with-agents/references/testing-by-layer.md +60 -0
  138. package/src/skills/visual-review-pipeline/SKILL.md +11 -120
  139. package/src/skills/visual-review-pipeline/references/findings-schema.md +49 -0
  140. package/src/skills/visual-review-pipeline/references/workflow-steps.md +111 -0
  141. package/scripts/hooks/log-session-start.sh +0 -48
  142. package/scripts/hooks/validate-post-conditions.sh +0 -21
  143. package/scripts/hooks/validate-talos-scope.sh +0 -50
  144. package/scripts/hooks/validate-tool-safety.sh +0 -49
  145. package/src/pantheon/goal-loop.ts +0 -314
  146. package/src/pantheon/idle-continuation.ts +0 -52
  147. package/src/pantheon/todo-preserve.ts +0 -301
  148. package/src/pantheon/tool-ceiling.ts +0 -159
  149. package/src/pantheon/v2-bridge.ts +0 -153
  150. package/src/plugin-v2.ts +0 -2954
  151. package/src/plugins/pantheon-hooks.ts +0 -1433
  152. package/src/plugins/tui/dist/server-v2.d.ts +0 -30
  153. package/src/plugins/tui/dist/server-v2.d.ts.map +0 -1
  154. package/src/plugins/tui/dist/server-v2.js +0 -33
  155. package/src/plugins/tui/dist/server-v2.js.map +0 -1
  156. package/src/plugins/tui/dist/tui-v2.d.ts +0 -1039
  157. package/src/plugins/tui/dist/tui-v2.d.ts.map +0 -1
  158. package/src/plugins/tui/dist/tui-v2.js +0 -4597
  159. package/src/plugins/tui/dist/tui-v2.js.map +0 -1
  160. package/src/plugins/tui/src/index-v2.tsx +0 -4496
  161. package/src/plugins/tui/src/server-v2.ts +0 -28
  162. package/src/plugins/tui/tui-v2.ts +0 -2
  163. /package/src/pantheon/{v2-decision-budget.ts → decision-budget.ts} +0 -0
  164. /package/src/pantheon/{v2-decision-egress.ts → decision-egress.ts} +0 -0
  165. /package/src/pantheon/{v2-decision-events.ts → decision-events.ts} +0 -0
  166. /package/src/pantheon/{v2-decision-heuristic.ts → decision-heuristic.ts} +0 -0
  167. /package/src/pantheon/{v2-decision-premises.ts → decision-premises.ts} +0 -0
  168. /package/src/pantheon/{v2-decision-rank.ts → decision-rank.ts} +0 -0
  169. /package/src/pantheon/{v2-decision-verify.ts → decision-verify.ts} +0 -0
  170. /package/src/pantheon/{v2-delegation-enforce.ts → delegation-policy.ts} +0 -0
  171. /package/src/pantheon/{v2-model-overrides.ts → model-overrides.ts} +0 -0
  172. /package/src/pantheon/{v2-native-decisions.ts → native-decisions.ts} +0 -0
  173. /package/src/plugins/tui/src/{opencode-v2.d.ts → opencode.d.ts} +0 -0
@@ -42,96 +42,6 @@ Use RED → GREEN → REFACTOR for behavior-changing implementation where a mean
42
42
 
43
43
  ---
44
44
 
45
- ## Testing by Layer
46
-
47
- ### Backend (Hermes)
48
- ```python
49
- # Unit: service logic
50
- def test_calculate_discount_applies_percentage():
51
- result = calculate_discount(100, 10)
52
- assert result == 90.0
53
-
54
- # Integration: API endpoint
55
- def test_get_user_returns_404_for_missing():
56
- response = client.get("/users/nonexistent")
57
- assert response.status_code == 404
58
-
59
- # Database: repository
60
- def test_user_repository_saves_and_retrieves():
61
- repo.save(User(id="1", name="Test"))
62
- assert repo.find("1").name == "Test"
63
- ```
64
-
65
- ### Frontend (Aphrodite)
66
- ```typescript
67
- // Test behavior, not implementation
68
- test('shows error message on invalid form', async () => {
69
- render(<LoginForm />)
70
- await userEvent.click(screen.getByText('Submit'))
71
- expect(screen.getByText('Email is required')).toBeInTheDocument()
72
- })
73
- ```
74
-
75
- ### Database (Demeter)
76
- ```python
77
- def test_migration_creates_users_table():
78
- alembic upgrade(head)
79
- assert inspector.has_table('users')
80
-
81
- def test_migration_rollback_drops_table():
82
- alembic upgrade(head)
83
- alembic downgrade(-1)
84
- assert not inspector.has_table('users')
85
- ```
86
-
87
- ---
88
-
89
- ## Advanced Testing Patterns
90
-
91
- ### E2E Testing (Playwright)
92
- ```typescript
93
- test('user can complete full signup flow', async ({ page }) => {
94
- await page.goto('/signup')
95
- await page.fill('[name="email"]', 'test@example.com')
96
- await page.fill('[name="password"]', 'secure123')
97
- await page.click('button[type="submit"]')
98
- await expect(page.locator('.welcome-banner')).toBeVisible()
99
- })
100
- ```
101
-
102
- ### Load Testing (k6/Locust)
103
- ```javascript
104
- // k6 script
105
- export const options = { vus: 50, duration: '30s' }
106
- export default function () {
107
- http.get('http://localhost:8000/api/users')
108
- }
109
- ```
110
-
111
- ### Contract Testing (Pact)
112
- ```python
113
- # Provider verifies consumer contract
114
- @pact.verify_provider
115
- def test_provider_satisfies_consumer_contract():
116
- # Verify all interactions from pact file
117
- pass
118
- ```
119
-
120
- ### Mutation Testing (high-risk/critical logic only)
121
- - Mutate source code (change `>` to `<`, remove conditions)
122
- - Run tests → should fail (mutation killed)
123
- - If tests pass → test is weak; improve it
124
-
125
- ### Visual Regression (visual behavior only)
126
- ```typescript
127
- test('homepage looks the same', async ({ page }) => {
128
- await page.goto('/')
129
- await expect(page).toHaveScreenshot('homepage.png')
130
- })
131
- ```
132
-
133
- ---
134
-
135
45
  ## Coverage Rules
136
46
 
137
47
  - Follow a repository's explicit coverage threshold when the changed code is in its measurement scope; do not manufacture a coverage target for docs, formatting, or a tiny isolated edit.
@@ -141,17 +51,6 @@ test('homepage looks the same', async ({ page }) => {
141
51
 
142
52
  ---
143
53
 
144
- ## Agent Responsibilities
145
-
146
- | Agent | Tests |
147
- |-------|-------|
148
- | **Hermes** | Unit + integration for FastAPI endpoints, services, middleware |
149
- | **Aphrodite** | Component behavior tests with React Testing Library |
150
- | **Demeter** | Migration upgrade/downgrade, query correctness |
151
- | **Themis** | Reviews the changed surface, relevant edge/error cases, and applicable repository coverage requirements; always review sensitive/material changes |
152
-
153
- ---
154
-
155
54
  ## Workflow
156
55
 
157
56
  ```
@@ -173,3 +72,14 @@ test('homepage looks the same', async ({ page }) => {
173
72
  - ❌ Mocking everything (test real behavior where possible)
174
73
  - ❌ Skipping RED step (test must fail first)
175
74
  - ❌ Ignoring flaky tests (fix or delete)
75
+
76
+ ---
77
+
78
+ ## Routing
79
+
80
+ | Action / trigger | Reference |
81
+ |---|---|
82
+ | Writing tests for a specific layer (Hermes/Aphrodite/Demeter) or assigning per-agent test duties | [references/testing-by-layer.md](references/testing-by-layer.md) |
83
+ | When risk or surface warrants E2E, load, contract, mutation, or visual-regression testing | [references/advanced-testing-patterns.md](references/advanced-testing-patterns.md) |
84
+
85
+ A missing reference interrupts the action — read nothing in its place, never improvise from memory.
@@ -0,0 +1,58 @@
1
+ # TDD with Agents — Advanced Testing Patterns
2
+
3
+ Detail companion for `SKILL.md`. Advanced patterns are reserved for changes
4
+ that warrant them — read on demand only when the change's risk or surface
5
+ calls for that pattern. The TDD cycle, proportional rules, coverage rules,
6
+ and anti-patterns stay in `SKILL.md`.
7
+
8
+ ---
9
+
10
+ ## E2E Testing (Playwright)
11
+ ```typescript
12
+ test('user can complete full signup flow', async ({ page }) => {
13
+ await page.goto('/signup')
14
+ await page.fill('[name="email"]', 'test@example.com')
15
+ await page.fill('[name="password"]', 'secure123')
16
+ await page.click('button[type="submit"]')
17
+ await expect(page.locator('.welcome-banner')).toBeVisible()
18
+ })
19
+ ```
20
+
21
+ ---
22
+
23
+ ## Load Testing (k6/Locust)
24
+ ```javascript
25
+ // k6 script
26
+ export const options = { vus: 50, duration: '30s' }
27
+ export default function () {
28
+ http.get('http://localhost:8000/api/users')
29
+ }
30
+ ```
31
+
32
+ ---
33
+
34
+ ## Contract Testing (Pact)
35
+ ```python
36
+ # Provider verifies consumer contract
37
+ @pact.verify_provider
38
+ def test_provider_satisfies_consumer_contract():
39
+ # Verify all interactions from pact file
40
+ pass
41
+ ```
42
+
43
+ ---
44
+
45
+ ## Mutation Testing (high-risk/critical logic only)
46
+ - Mutate source code (change `>` to `<`, remove conditions)
47
+ - Run tests → should fail (mutation killed)
48
+ - If tests pass → test is weak; improve it
49
+
50
+ ---
51
+
52
+ ## Visual Regression (visual behavior only)
53
+ ```typescript
54
+ test('homepage looks the same', async ({ page }) => {
55
+ await page.goto('/')
56
+ await expect(page).toHaveScreenshot('homepage.png')
57
+ })
58
+ ```
@@ -0,0 +1,60 @@
1
+ # TDD with Agents — Testing by Layer
2
+
3
+ Detail companion for `SKILL.md`. Read on demand when writing tests for a
4
+ specific layer or assigning test duties in a delegation. The TDD cycle,
5
+ proportional rules, coverage rules, and workflow stay in `SKILL.md`.
6
+
7
+ ---
8
+
9
+ ## Testing by Layer
10
+
11
+ ### Backend (Hermes)
12
+ ```python
13
+ # Unit: service logic
14
+ def test_calculate_discount_applies_percentage():
15
+ result = calculate_discount(100, 10)
16
+ assert result == 90.0
17
+
18
+ # Integration: API endpoint
19
+ def test_get_user_returns_404_for_missing():
20
+ response = client.get("/users/nonexistent")
21
+ assert response.status_code == 404
22
+
23
+ # Database: repository
24
+ def test_user_repository_saves_and_retrieves():
25
+ repo.save(User(id="1", name="Test"))
26
+ assert repo.find("1").name == "Test"
27
+ ```
28
+
29
+ ### Frontend (Aphrodite)
30
+ ```typescript
31
+ // Test behavior, not implementation
32
+ test('shows error message on invalid form', async () => {
33
+ render(<LoginForm />)
34
+ await userEvent.click(screen.getByText('Submit'))
35
+ expect(screen.getByText('Email is required')).toBeInTheDocument()
36
+ })
37
+ ```
38
+
39
+ ### Database (Demeter)
40
+ ```python
41
+ def test_migration_creates_users_table():
42
+ alembic upgrade(head)
43
+ assert inspector.has_table('users')
44
+
45
+ def test_migration_rollback_drops_table():
46
+ alembic upgrade(head)
47
+ alembic downgrade(-1)
48
+ assert not inspector.has_table('users')
49
+ ```
50
+
51
+ ---
52
+
53
+ ## Agent Responsibilities
54
+
55
+ | Agent | Tests |
56
+ |-------|-------|
57
+ | **Hermes** | Unit + integration for FastAPI endpoints, services, middleware |
58
+ | **Aphrodite** | Component behavior tests with React Testing Library |
59
+ | **Demeter** | Migration upgrade/downgrade, query correctness |
60
+ | **Themis** | Reviews the changed surface, relevant edge/error cases, and applicable repository coverage requirements; always review sensitive/material changes |
@@ -7,11 +7,11 @@ description: "Automated visual review pipeline — Playwright screenshots, self-
7
7
 
8
8
  Automated visual review: Aphrodite captures screenshots via Playwright MCP → Self-analyzes for visual issues → Addresses findings in a loop.
9
9
 
10
- ## Overview
10
+ This pipeline enforces structured JSON output, iteration limits, and escalation criteria to prevent infinite fix loops.
11
11
 
12
- This pipeline establishes a formal workflow for detecting and resolving visual regressions and design issues. It enforces structured JSON output, iteration limits, and escalation criteria to prevent infinite fix loops.
12
+ ---
13
13
 
14
- ### Pipeline Flow
14
+ ## Loop Contract
15
15
 
16
16
  ```
17
17
  Aphrodite implements UI
@@ -25,43 +25,7 @@ Aphrodite self-analyzes (layout, contrast, responsive, accessibility)
25
25
  └─ verdict: fail + iteration = 3 → Zeus escalation
26
26
  ```
27
27
 
28
- ## Workflow Steps
29
-
30
- ### Step 1: Capture
31
- Aphrodite uses Playwright MCP to capture screenshots.
32
- - Navigate to target URL or render component
33
- - Capture full-page screenshot via `browser/screenshotPage`
34
- - Capture viewport-specific screenshots for responsive checks
35
- - Name files descriptively: `screenshot-iteration-N-component.png`
36
-
37
- ### Step 2: Analyze
38
- Aphrodite self-analyzes screenshots visually.
39
- - Examine screenshot(s) for visual issues
40
- - Identify problems in layout, contrast, responsive behavior, and accessibility
41
- - Return findings in the structured JSON schema (below)
42
- - Include iteration number in findings
43
- - Mark issues with `pass_if_fixed` IDs
44
-
45
- ### Step 3: Fix
46
- Aphrodite addresses each finding from self-analysis.
47
- - Triage findings by severity (critical → high → medium → low)
48
- - Fix each issue in component code
49
- - Commit changes with descriptive message
50
- - Re-capture screenshot for next iteration
51
-
52
- ### Step 4: Loop
53
- Repeat Steps 1-3 for up to **3 iterations**.
54
- - Each iteration must fix at least one `pass_if_fixed` issue
55
- - Track iteration count in findings object
56
- - If no progress detected (zero fixes applied), escalate immediately
57
- - Compare before/after screenshots to verify fixes
58
-
59
- ### Step 5: Escalate
60
- Zeus intervenes if issues persist after 3 iterations.
61
- - **Trigger:** 3 iterations exhausted or zero-progress detected
62
- - **Action:** Zeus coordinates manual review or architectural decision
63
-
64
- ## JSON Schema
28
+ ## Findings Contract (format safety — keep in core)
65
29
 
66
30
  Aphrodite must return findings in this exact structure:
67
31
 
@@ -85,44 +49,6 @@ Aphrodite must return findings in this exact structure:
85
49
  }
86
50
  ```
87
51
 
88
- ### Field Definitions
89
-
90
- | Field | Type | Description |
91
- |-------|------|-------------|
92
- | `verdict` | enum | `pass` = no issues, `fail` = blocking, `warn` = non-blocking |
93
- | `iteration` | int | Current iteration number (1-3) |
94
- | `max_iterations` | int | Always 3 |
95
- | `issues` | array | List of visual issues found |
96
- | `issues[].id` | string | Unique ID in format `VIS-NNN` |
97
- | `issues[].category` | enum | Issue category (see Categories) |
98
- | `issues[].severity` | enum | Severity level (see Severity) |
99
- | `issues[].description` | string | Clear description of the issue |
100
- | `issues[].screenshot_region` | string | Bounding box or region reference |
101
- | `issues[].recommendation` | string | Suggested fix |
102
- | `summary` | string | One-line overall assessment |
103
- | `pass_if_fixed` | string[] | Issue IDs that must be resolved to pass |
104
-
105
- ## Categories
106
-
107
- | Category | Description | Examples |
108
- |----------|-------------|---------|
109
- | `layout` | Positioning, alignment, overflow | Element misplaced, container overflow, z-index issues |
110
- | `contrast` | Color contrast, visibility | Text hard to read, low contrast ratio |
111
- | `responsive` | Mobile/tablet behavior | Elements break at specific breakpoints |
112
- | `missing_element` | Expected element not rendered | Button not visible, icon missing |
113
- | `typography` | Font, size, weight, spacing | Wrong font family, text truncation |
114
- | `spacing` | Margins, padding, gaps | Uneven spacing, cramped elements |
115
- | `accessibility` | ARIA, focus states, keyboard nav | Missing alt text, no focus ring |
116
-
117
- ## Severity Levels
118
-
119
- | Level | Description | Action Required |
120
- |-------|-------------|-----------------|
121
- | `critical` | Blocks user interaction or content | Must fix before merge |
122
- | `high` | Significant visual regression | Must fix before merge |
123
- | `medium` | Noticeable but not blocking | Fix in current sprint |
124
- | `low` | Minor polish item | Backlog, fix when convenient |
125
-
126
52
  ## Iteration Rules
127
53
 
128
54
  1. **Minimum progress:** Each iteration fixes at least one `pass_if_fixed` issue
@@ -131,14 +57,6 @@ Aphrodite must return findings in this exact structure:
131
57
  4. **Early exit:** If `verdict` is `pass`, stop iterating
132
58
  5. **Immediate escalation:** If zero issues fixed in an iteration, escalate to Zeus
133
59
 
134
- ### Progress Detection
135
- ```
136
- Iteration N:
137
- - Compare pass_if_fixed list to previous iteration
138
- - If any ID removed from pass_if_fixed → progress detected
139
- - If pass_if_fixed unchanged → zero progress → escalate
140
- ```
141
-
142
60
  ## Escalation Criteria
143
61
 
144
62
  Zeus must be invoked when:
@@ -148,13 +66,6 @@ Zeus must be invoked when:
148
66
  4. **Zero progress** — no `pass_if_fixed` issues resolved in an iteration
149
67
  5. **Conflicting fixes** — resolving one issue introduces another
150
68
 
151
- **Escalation format:**
152
- ```
153
- @zeus Visual review escalation: [component] failed after [N] iterations.
154
- Remaining issues: [list of unresolved pass_if_fixed IDs]
155
- Root cause: [backend | architectural | conflicting]
156
- ```
157
-
158
69
  ## MCP Requirements
159
70
 
160
71
  ### Playwright MCP (Required)
@@ -167,33 +78,13 @@ Root cause: [backend | architectural | conflicting]
167
78
  ```
168
79
  For UI implementation review, Aphrodite self-reviews.
169
80
 
170
- ## Integration Points
81
+ ---
171
82
 
172
- - **Code Review (Themis):** Visual review runs as part of frontend code review; findings feed into Themis's verdict.
173
- - **Artifact Protocol:** Visual review findings can attach to `IMPL-` artifacts. Escalation decisions documented in `_notes/`.
174
- - **Memory Bank:** Recurring visual issues documented in `01-active-context.md`. Architectural visual decisions recorded as `_notes/NOTE000X-*.md`.
83
+ ## Routing
175
84
 
176
- ## Example Workflow
85
+ | Action / trigger | Reference |
86
+ |---|---|
87
+ | Running the capture → analyze → fix loop, writing the escalation message, or wiring integrations | [references/workflow-steps.md](references/workflow-steps.md) |
88
+ | Classifying findings fields, issue categories, or severity levels | [references/findings-schema.md](references/findings-schema.md) |
177
89
 
178
- ```
179
- 1. Aphrodite captures screenshot of LoginButton
180
- → screenshot-iteration-1-login-button.png
181
-
182
- 2. Self-analysis returns:
183
- {
184
- "verdict": "fail", "iteration": 1,
185
- "issues": [{
186
- "id": "VIS-001", "category": "contrast", "severity": "high",
187
- "description": "White text on light blue bg, contrast ratio 2.1:1",
188
- "recommendation": "Darken background to #1a56db"
189
- }],
190
- "pass_if_fixed": ["VIS-001"]
191
- }
192
-
193
- 3. Fix contrast, re-capture → screenshot-iteration-2-login-button.png
194
-
195
- 4. Re-analysis: { "verdict": "pass", "iteration": 2, "issues": [],
196
- "summary": "All visual issues resolved", "pass_if_fixed": [] }
197
-
198
- 5. Pipeline complete — 2 iterations, all issues fixed.
199
- ```
90
+ A missing reference interrupts the action — read nothing in its place, never improvise from memory.
@@ -0,0 +1,49 @@
1
+ # Visual Review Pipeline — Findings Schema Detail
2
+
3
+ Detail companion for `SKILL.md`. Read on demand when classifying issues or
4
+ grading severity. The findings JSON structure itself, the loop contract,
5
+ iteration rules, and escalation triggers stay in `SKILL.md`.
6
+
7
+ ---
8
+
9
+ ## Field Definitions
10
+
11
+ | Field | Type | Description |
12
+ |-------|------|-------------|
13
+ | `verdict` | enum | `pass` = no issues, `fail` = blocking, `warn` = non-blocking |
14
+ | `iteration` | int | Current iteration number (1-3) |
15
+ | `max_iterations` | int | Always 3 |
16
+ | `issues` | array | List of visual issues found |
17
+ | `issues[].id` | string | Unique ID in format `VIS-NNN` |
18
+ | `issues[].category` | enum | Issue category (see Categories) |
19
+ | `issues[].severity` | enum | Severity level (see Severity) |
20
+ | `issues[].description` | string | Clear description of the issue |
21
+ | `issues[].screenshot_region` | string | Bounding box or region reference |
22
+ | `issues[].recommendation` | string | Suggested fix |
23
+ | `summary` | string | One-line overall assessment |
24
+ | `pass_if_fixed` | string[] | Issue IDs that must be resolved to pass |
25
+
26
+ ---
27
+
28
+ ## Categories
29
+
30
+ | Category | Description | Examples |
31
+ |----------|-------------|---------|
32
+ | `layout` | Positioning, alignment, overflow | Element misplaced, container overflow, z-index issues |
33
+ | `contrast` | Color contrast, visibility | Text hard to read, low contrast ratio |
34
+ | `responsive` | Mobile/tablet behavior | Elements break at specific breakpoints |
35
+ | `missing_element` | Expected element not rendered | Button not visible, icon missing |
36
+ | `typography` | Font, size, weight, spacing | Wrong font family, text truncation |
37
+ | `spacing` | Margins, padding, gaps | Uneven spacing, cramped elements |
38
+ | `accessibility` | ARIA, focus states, keyboard nav | Missing alt text, no focus ring |
39
+
40
+ ---
41
+
42
+ ## Severity Levels
43
+
44
+ | Level | Description | Action Required |
45
+ |-------|-------------|-----------------|
46
+ | `critical` | Blocks user interaction or content | Must fix before merge |
47
+ | `high` | Significant visual regression | Must fix before merge |
48
+ | `medium` | Noticeable but not blocking | Fix in current sprint |
49
+ | `low` | Minor polish item | Backlog, fix when convenient |
@@ -0,0 +1,111 @@
1
+ # Visual Review Pipeline — Workflow Steps
2
+
3
+ Detail companion for `SKILL.md`. Read on demand: running the capture → analyze
4
+ → fix loop, Playwright MCP setup/fallback, escalation message format,
5
+ integration points, or a worked example. The loop contract, findings schema,
6
+ iteration rules, and escalation triggers stay in `SKILL.md`.
7
+
8
+ ---
9
+
10
+ ## Workflow Steps
11
+
12
+ ### Step 1: Capture
13
+ Aphrodite uses Playwright MCP to capture screenshots.
14
+ - Navigate to target URL or render component
15
+ - Capture full-page screenshot via `browser/screenshotPage`
16
+ - Capture viewport-specific screenshots for responsive checks
17
+ - Name files descriptively: `screenshot-iteration-N-component.png`
18
+
19
+ ### Step 2: Analyze
20
+ Aphrodite self-analyzes screenshots visually.
21
+ - Examine screenshot(s) for visual issues
22
+ - Identify problems in layout, contrast, responsive behavior, and accessibility
23
+ - Return findings in the structured JSON schema (in `SKILL.md`)
24
+ - Include iteration number in findings
25
+ - Mark issues with `pass_if_fixed` IDs
26
+
27
+ ### Step 3: Fix
28
+ Aphrodite addresses each finding from self-analysis.
29
+ - Triage findings by severity (critical → high → medium → low)
30
+ - Fix each issue in component code
31
+ - Commit changes with descriptive message
32
+ - Re-capture screenshot for next iteration
33
+
34
+ ### Step 4: Loop
35
+ Repeat Steps 1-3 for up to **3 iterations**.
36
+ - Each iteration must fix at least one `pass_if_fixed` issue
37
+ - Track iteration count in findings object
38
+ - If no progress detected (zero fixes applied), escalate immediately
39
+ - Compare before/after screenshots to verify fixes
40
+
41
+ ### Step 5: Escalate
42
+ Zeus intervenes if issues persist after 3 iterations.
43
+ - **Trigger:** 3 iterations exhausted or zero-progress detected
44
+ - **Action:** Zeus coordinates manual review or architectural decision
45
+
46
+ **Escalation format:**
47
+ ```
48
+ @zeus Visual review escalation: [component] failed after [N] iterations.
49
+ Remaining issues: [list of unresolved pass_if_fixed IDs]
50
+ Root cause: [backend | architectural | conflicting]
51
+ ```
52
+
53
+ ---
54
+
55
+ ## Progress Detection
56
+
57
+ ```
58
+ Iteration N:
59
+ - Compare pass_if_fixed list to previous iteration
60
+ - If any ID removed from pass_if_fixed → progress detected
61
+ - If pass_if_fixed unchanged → zero progress → escalate
62
+ ```
63
+
64
+ ---
65
+
66
+ ## MCP Requirements
67
+
68
+ ### Playwright MCP (Required)
69
+ - Use `browser/screenshotPage` for full-page captures
70
+ - Use `browser/snapshot` for accessibility tree context
71
+ - Fallback: If Playwright MCP is unavailable, skip with warning:
72
+ ```
73
+ ⚠️ Playwright MCP unavailable — visual review skipped.
74
+ Install Playwright MCP server to enable visual review pipeline.
75
+ ```
76
+ For UI implementation review, Aphrodite self-reviews.
77
+
78
+ ---
79
+
80
+ ## Integration Points
81
+
82
+ - **Code Review (Themis):** Visual review runs as part of frontend code review; findings feed into Themis's verdict.
83
+ - **Artifact Protocol:** Visual review findings can attach to `IMPL-` artifacts. Escalation decisions documented in `_notes/`.
84
+ - **Memory Bank:** Recurring visual issues documented in `01-active-context.md`. Architectural visual decisions recorded as `_notes/NOTE000X-*.md`.
85
+
86
+ ---
87
+
88
+ ## Example Workflow
89
+
90
+ ```
91
+ 1. Aphrodite captures screenshot of LoginButton
92
+ → screenshot-iteration-1-login-button.png
93
+
94
+ 2. Self-analysis returns:
95
+ {
96
+ "verdict": "fail", "iteration": 1,
97
+ "issues": [{
98
+ "id": "VIS-001", "category": "contrast", "severity": "high",
99
+ "description": "White text on light blue bg, contrast ratio 2.1:1",
100
+ "recommendation": "Darken background to #1a56db"
101
+ }],
102
+ "pass_if_fixed": ["VIS-001"]
103
+ }
104
+
105
+ 3. Fix contrast, re-capture → screenshot-iteration-2-login-button.png
106
+
107
+ 4. Re-analysis: { "verdict": "pass", "iteration": 2, "issues": [],
108
+ "summary": "All visual issues resolved", "pass_if_fixed": [] }
109
+
110
+ 5. Pipeline complete — 2 iterations, all issues fixed.
111
+ ```
@@ -1,48 +0,0 @@
1
- #!/usr/bin/env bash
2
- # log-session-start.sh — Pantheon SessionStart Logging Hook
3
- # Logs session start with structured JSON.
4
- set -euo pipefail
5
-
6
- # Project-local by default; set XDG_STATE_HOME for system-wide logging
7
- # Anchor to PANTHEON_HOME or PANTHEON_PROJECT when available to avoid
8
- # CWD-dependent relative path ("logs/agent-sessions" wrote to cwd).
9
- if [ -n "${LOG_DIR:-}" ]; then
10
- LOG_DIR="$LOG_DIR"
11
- elif [ -n "${XDG_STATE_HOME:-}" ]; then
12
- LOG_DIR="$XDG_STATE_HOME/pantheon/hooks"
13
- elif [ -n "${PANTHEON_HOME:-}" ]; then
14
- LOG_DIR="$PANTHEON_HOME/logs/agent-sessions"
15
- elif [ -n "${PANTHEON_PROJECT:-}" ]; then
16
- LOG_DIR="$PANTHEON_PROJECT/logs/agent-sessions"
17
- else
18
- LOG_DIR="logs/agent-sessions"
19
- fi
20
- mkdir -p "$LOG_DIR"
21
-
22
- TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
23
- SESSION_ID="${SESSION_ID:-$(date +%s)}"
24
-
25
- # P2 (2026-08-06): platform was hardcoded 'unknown' — derive it from env
26
- # (OSTYPE) or detect via uname, with a clean 'linux' default. Never 'unknown'
27
- # on a supported OS.
28
- detect_platform() {
29
- case "${OSTYPE:-}" in
30
- linux*) echo "linux" && return ;;
31
- darwin*) echo "darwin" && return ;;
32
- msys* | mingw* | cygwin*) echo "windows" && return ;;
33
- esac
34
- case "$(uname -s 2>/dev/null)" in
35
- Linux) echo "linux" ;;
36
- Darwin) echo "darwin" ;;
37
- MINGW* | MSYS* | CYGWIN*) echo "windows" ;;
38
- *) echo "linux" ;;
39
- esac
40
- }
41
- PLATFORM="${PLATFORM:-$(detect_platform)}"
42
-
43
- cat >> "$LOG_DIR/sessions.log" << JSON
44
- {"event":"SessionStart","timestamp":"$TIMESTAMP","session_id":"$SESSION_ID","platform":"$PLATFORM"}
45
- JSON
46
-
47
- echo "[LOG] Session start logged → $LOG_DIR/sessions.log" >&2
48
- exit 0
@@ -1,21 +0,0 @@
1
- #!/usr/bin/env bash
2
- # validate-post-conditions.sh — Stop hook
3
- # Checks that Themis review was called after implementation
4
- set -euo pipefail
5
-
6
- # Read JSON input from stdin
7
- INPUT=$(cat)
8
- SESSION_ID=$(echo "$INPUT" | python3 -c "import sys,json; print(json.load(sys.stdin).get('session_id',''))" 2>/dev/null || echo "")
9
-
10
- REVIEW_DIR=".pantheon/memory-bank/.tmp"
11
- if [ -d "$REVIEW_DIR" ]; then
12
- REVIEW_COUNT=$(find "$REVIEW_DIR" -maxdepth 1 -name 'REVIEW-*' -type f 2>/dev/null | wc -l)
13
- if [ "$REVIEW_COUNT" -eq 0 ]; then
14
- echo "[POST-CONDITION] ⚠️ No REVIEW artifact found in $REVIEW_DIR/" >&2
15
- echo "[POST-CONDITION] 💡 Remember: implementation agents MUST call @themis for review" >&2
16
- else
17
- echo "[POST-CONDITION] ✅ $REVIEW_COUNT REVIEW artifact(s) found" >&2
18
- fi
19
- fi
20
-
21
- exit 0