pantheon-opencode 1.6.3-beta.2 → 1.6.3-beta.21

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 (69) hide show
  1. package/AGENTS.global.md +1 -1
  2. package/AGENTS.md +1 -1
  3. package/CHANGELOG.md +143 -0
  4. package/README.md +21 -3
  5. package/README.pt-BR.md +1 -1
  6. package/bin/pantheon-init.mjs +46 -28
  7. package/package.json +1 -1
  8. package/plugin.json +2 -2
  9. package/pyproject.toml +1 -1
  10. package/scripts/decision-router-budget.mjs +103 -3
  11. package/scripts/decision-router-v2-budget.mjs +2 -2
  12. package/scripts/decision-router.mjs +88 -6
  13. package/scripts/install/cli-ui.mjs +2 -1
  14. package/scripts/install/decision-router-config.mjs +53 -0
  15. package/scripts/install/interactive.mjs +103 -9
  16. package/scripts/install/opencode.mjs +101 -30
  17. package/scripts/install/plugin.mjs +17 -0
  18. package/scripts/jev-live-probe.mjs +212 -0
  19. package/scripts/skill-search.mjs +273 -0
  20. package/scripts/sync-tui.mjs +11 -0
  21. package/skills-lock.json +1 -0
  22. package/src/agents/aphrodite.md +34 -1
  23. package/src/agents/apollo.md +227 -0
  24. package/src/agents/athena.md +26 -0
  25. package/src/agents/demeter.md +33 -0
  26. package/src/agents/gaia.md +24 -0
  27. package/src/agents/hephaestus.md +24 -0
  28. package/src/agents/hermes.md +33 -0
  29. package/src/agents/iris.md +24 -0
  30. package/src/agents/mnemosyne.md +25 -3
  31. package/src/agents/nyx.md +50 -22
  32. package/src/agents/prometheus.md +242 -1
  33. package/src/agents/talos.md +24 -0
  34. package/src/agents/themis.md +24 -0
  35. package/src/agents/zeus.md +67 -6
  36. package/src/pantheon/j-telemetry-file.ts +96 -0
  37. package/src/pantheon/j1-approvals.ts +123 -0
  38. package/src/pantheon/jev-decision-tool.ts +268 -34
  39. package/src/pantheon/jev-decisions.ts +92 -8
  40. package/src/pantheon/jev-escalation.ts +1 -1
  41. package/src/pantheon/jev-quality-score.ts +7 -2
  42. package/src/pantheon/jev-rank-verify.ts +661 -0
  43. package/src/pantheon/jev-risk-gate.ts +75 -8
  44. package/src/pantheon/local-decision-budget.ts +170 -3
  45. package/src/pantheon/local-decision-router.ts +16 -0
  46. package/src/pantheon/local-decision-turn.ts +39 -4
  47. package/src/pantheon/local-decision-usage-evidence.internal.ts +2 -2
  48. package/src/pantheon/pantheon-decision-catalog.ts +9 -2
  49. package/src/pantheon/v2-decision-budget.ts +4 -2
  50. package/src/plugin-v2.ts +94 -7
  51. package/src/plugins/tui/dist/server-v2.d.ts +14 -6
  52. package/src/plugins/tui/dist/server-v2.d.ts.map +1 -1
  53. package/src/plugins/tui/dist/server-v2.js +16 -9
  54. package/src/plugins/tui/dist/server-v2.js.map +1 -1
  55. package/src/plugins/tui/dist/tui-v2.d.ts.map +1 -1
  56. package/src/plugins/tui/dist/tui-v2.js +560 -4
  57. package/src/plugins/tui/dist/tui-v2.js.map +1 -1
  58. package/src/plugins/tui/dist/tui.js +1 -1
  59. package/src/plugins/tui/package-lock.json +2 -2
  60. package/src/plugins/tui/package.json +1 -1
  61. package/src/plugins/tui/src/index-v2.tsx +6 -0
  62. package/src/plugins/tui/src/server-v2.ts +14 -7
  63. package/src/plugins/tui/src/whats-new-highlights.ts +317 -0
  64. package/src/plugins/tui/src/whats-new-open.ts +120 -0
  65. package/src/plugins/tui/src/whats-new-state.ts +128 -0
  66. package/src/plugins/tui/src/whats-new.tsx +172 -0
  67. package/src/routing.yml +1 -0
  68. package/src/skills/README.md +1 -1
  69. package/src/skills/prompt-refinery/SKILL.md +41 -0
@@ -215,6 +215,23 @@ export function copyPluginFiles(
215
215
  else result.skipped++
216
216
  }
217
217
 
218
+ // CHANGELOG.md — the copy's one-time "What's new" window reads the release
219
+ // highlights for the running version from its own installed root. Best
220
+ // effort: a missing source simply means no window (the TUI fails open).
221
+ // src/plugins/tui → src/plugins → src → the package root, which ships
222
+ // CHANGELOG.md in its npm `files` allow-list.
223
+ const changelogSrc = join(srcDir, '..', '..', '..', 'CHANGELOG.md')
224
+ if (existsSync(changelogSrc)) {
225
+ const changelogStatus = writeIfChanged(
226
+ join(dstDir, 'CHANGELOG.md'),
227
+ readFileSync(changelogSrc, 'utf8'),
228
+ dryRun,
229
+ { recorder },
230
+ )
231
+ if (changelogStatus === 'created') result.created++
232
+ else result.skipped++
233
+ }
234
+
218
235
  return result
219
236
  }
220
237
 
@@ -0,0 +1,212 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * jev-live-probe.mjs — operator-run live measurement for the Jev decision
4
+ * route (config-only route check + live scorecard).
5
+ *
6
+ * The ping resolves the configured route without contacting a provider. The
7
+ * scorecard talks to the HOST's decisions API through `opencode api` (the same
8
+ * route the plugin uses), so no credentials cross this script and each live
9
+ * call is billed to the user's configured route. Operator-run by design: the
10
+ * J2 scorecard is the consented live-model measurement; the offline harness
11
+ * measures plumbing only.
12
+ *
13
+ * Usage:
14
+ * node scripts/jev-live-probe.mjs --ping # config-only route resolution; no provider call
15
+ * node scripts/jev-live-probe.mjs --scorecard # N scenarios, dated scorecard
16
+ */
17
+
18
+ import { spawnSync } from 'node:child_process'
19
+ import { writeFileSync } from 'node:fs'
20
+ import { pathToFileURL } from 'node:url'
21
+ import {
22
+ DECISION_ROUTER_MODELS,
23
+ readUserDecisionRouterConfig,
24
+ } from './install/decision-router-config.mjs'
25
+
26
+ const HOST_TIMEOUT_MS = 30_000
27
+
28
+ /** Config provider IDs translated to the host's native Decisions provider IDs. */
29
+ export const HOST_PROVIDERS = Object.freeze({
30
+ 'typesafe-jev': 'typesafe-ai',
31
+ 'opencode-console-jev': 'opencode',
32
+ 'openrouter-jev': 'openrouter',
33
+ 'vercel-gateway-jev': 'vercel-ai-gateway',
34
+ 'cloudflare-workers-jev': 'cloudflare-workers-ai',
35
+ })
36
+
37
+ /** Live scenarios: state → the skill a correct picker would choose. */
38
+ const SCENARIOS = [
39
+ { state: 'Investigate why the payment webhook drops events under load', expect: 'apollo' },
40
+ { state: 'Plan the database migration for the new billing table', expect: 'athena' },
41
+ { state: 'Review the auth flow for security gaps before the release', expect: 'themis' },
42
+ { state: 'Implement the retry queue endpoint for the notifications service', expect: 'hermes' },
43
+ { state: 'Set up the CI pipeline for the new monorepo layout', expect: 'prometheus' },
44
+ { state: 'Audit the permissions matrix across all specialists', expect: 'themis' },
45
+ { state: 'Design the caching layer for the read-heavy dashboard', expect: 'athena' },
46
+ { state: 'none — greet the user and ask what they want', expect: 'none' },
47
+ // Zero-dispatch agents' domains (roster-reform evidence batch)
48
+ { state: 'Write the SQL indexes and stored procedures for the orders schema', expect: 'demeter' },
49
+ { state: 'Process the satellite imagery tiles and classify land use', expect: 'gaia' },
50
+ {
51
+ state: 'Integrate the new LLM provider SDK and wire the prompt templates',
52
+ expect: 'hephaestus',
53
+ },
54
+ { state: 'Migrate the open issues to the new milestone labels via the API', expect: 'iris' },
55
+ { state: 'Decide which stale session summaries are worth keeping', expect: 'mnemosyne' },
56
+ { state: 'Fuzz the input parser with malformed payloads to find crashes', expect: 'nyx' },
57
+ { state: 'Fix the typo that makes the CLI parse --verbose as the output path', expect: 'talos' },
58
+ { state: 'Polish the onboarding screen layout and micro-interactions', expect: 'aphrodite' },
59
+ ]
60
+
61
+ function callDecisions(modelRef, state) {
62
+ const payload = JSON.stringify({
63
+ model: modelRef,
64
+ input: [{ type: 'text', text: state }],
65
+ questions: [
66
+ {
67
+ type: 'choice',
68
+ name: 'pick',
69
+ instructions:
70
+ 'Pick the single best specialist for this task, or none. Required skills beat preferred ones; judge from the state alone.',
71
+ choices: [
72
+ { value: 'apollo', description: 'read-only investigation and research' },
73
+ { value: 'athena', description: 'planning and architecture' },
74
+ { value: 'themis', description: 'security, review and compliance gates' },
75
+ { value: 'hermes', description: 'backend implementation' },
76
+ { value: 'prometheus', description: 'infrastructure, Docker, CI and model providers' },
77
+ { value: 'hephaestus', description: 'AI tooling and model integration' },
78
+ { value: 'demeter', description: 'databases and data layer' },
79
+ { value: 'gaia', description: 'remote sensing and geospatial' },
80
+ { value: 'iris', description: 'GitHub operations and automation' },
81
+ { value: 'aphrodite', description: 'UI and frontend craft' },
82
+ { value: 'mnemosyne', description: 'memory curation and recall' },
83
+ { value: 'nyx', description: 'observability, tracing and cost analytics; chaos testing' },
84
+ { value: 'talos', description: 'hotfix express lane - small direct fixes, no ceremony' },
85
+ { value: 'none', description: 'no specialist fits' },
86
+ ],
87
+ },
88
+ ],
89
+ })
90
+ const result = spawnSync(
91
+ 'opencode',
92
+ ['api', 'POST', '/api/experimental/generate/decisions', '-d', payload],
93
+ {
94
+ encoding: 'utf8',
95
+ timeout: HOST_TIMEOUT_MS,
96
+ },
97
+ )
98
+ if (result.status !== 0) {
99
+ return { ok: false, raw: (result.stderr || result.stdout || '').slice(0, 300) }
100
+ }
101
+ try {
102
+ return { ok: true, data: JSON.parse(result.stdout) }
103
+ } catch {
104
+ return { ok: false, raw: result.stdout.slice(0, 300) }
105
+ }
106
+ }
107
+
108
+ function answerChoice(data) {
109
+ const answers = data?.data?.answers ?? data?.answers
110
+ if (!Array.isArray(answers)) return null
111
+ const pick = answers.find((a) => a.name === 'pick')
112
+ return pick?.choice ?? null
113
+ }
114
+
115
+ /** Resolve the configured explicit route without probing the provider. */
116
+ export function resolveConfiguredRoute(config) {
117
+ if (!config?.enabled || config.selection?.mode !== 'explicit') {
118
+ throw new Error('the router must be enabled with an explicit selection')
119
+ }
120
+ const { provider, model } = config.selection
121
+ const hostProvider = HOST_PROVIDERS[provider]
122
+ if (
123
+ !Object.hasOwn(HOST_PROVIDERS, provider) ||
124
+ !DECISION_ROUTER_MODELS[provider]?.includes(model)
125
+ ) {
126
+ throw new Error(`unknown or unsupported selection: ${provider}/${model}`)
127
+ }
128
+ return { providerID: hostProvider, id: model }
129
+ }
130
+
131
+ /** Report the configured route only; deliberately makes no Decisions call. */
132
+ export function pingConfiguredRoute(config, { stdout = console.log } = {}) {
133
+ const modelRef = resolveConfiguredRoute(config)
134
+ stdout(`✅ configured route: ${modelRef.providerID}/${modelRef.id} (no live provider call)`)
135
+ return modelRef
136
+ }
137
+
138
+ function main(args = process.argv.slice(2)) {
139
+ if (args.includes('--ping')) {
140
+ try {
141
+ pingConfiguredRoute(readUserDecisionRouterConfig())
142
+ process.exit(0)
143
+ } catch (error) {
144
+ console.error(
145
+ `❌ route unresolved: ${error instanceof Error ? error.message : String(error)}`,
146
+ )
147
+ process.exit(1)
148
+ }
149
+ }
150
+
151
+ if (args.includes('--scorecard')) {
152
+ // Route from the user's decision-router config (explicit selection only).
153
+ let cfg
154
+ let modelRef
155
+ try {
156
+ cfg = readUserDecisionRouterConfig()
157
+ modelRef = resolveConfiguredRoute(cfg)
158
+ } catch (error) {
159
+ console.error(error instanceof Error ? error.message : String(error))
160
+ process.exit(1)
161
+ }
162
+
163
+ const rows = []
164
+ let totalCost = 0
165
+ for (const scenario of SCENARIOS) {
166
+ const r = callDecisions(modelRef, scenario.state)
167
+ if (!r.ok) {
168
+ rows.push({ state: scenario.state, expect: scenario.expect, got: `ERROR: ${r.raw}` })
169
+ continue
170
+ }
171
+ const cost = r.data?.cost ?? 0
172
+ totalCost += Number(cost) || 0
173
+ rows.push({ state: scenario.state, expect: scenario.expect, got: answerChoice(r.data), cost })
174
+ }
175
+
176
+ const date = new Date().toISOString().slice(0, 10)
177
+ const out = [
178
+ `# Live J2 scorecard — ${date}`,
179
+ '',
180
+ `Route: \`${modelRef.providerID}/${modelRef.id}\`. Operator-run via \`opencode api\``,
181
+ `(consented route, billed to the user). ${rows.length} scenarios; agreement between the`,
182
+ 'live model and the expected pick is the metric — this measures the MODEL,',
183
+ 'unlike the offline harness that measures the plumbing.',
184
+ '',
185
+ '| state (truncated) | expect | live | cost |',
186
+ '| --- | --- | --- | --- |',
187
+ ...rows.map(
188
+ (r) =>
189
+ `| ${r.state.slice(0, 48)}${r.state.length > 48 ? '…' : ''} | ${r.expect} | ${r.got ?? '—'} | ${r.cost ?? '—'} |`,
190
+ ),
191
+ '',
192
+ totalCost > 0
193
+ ? `Total cost: $${totalCost.toFixed(6)} (sum of route-reported costs). Honest caveat: one run is a smoke`
194
+ : `Total cost: NOT reported by the route (the cost field came empty on every call — QA beta.20). Honest caveat: one run is a smoke`,
195
+ 'measurement, not a calibration — a claim about model quality needs',
196
+ 'repeated runs and a bigger scenario set.',
197
+ '',
198
+ ].join('\n')
199
+ const outPath = `bench/results/j2-live-scorecard-${date}.md`
200
+ writeFileSync(outPath, out)
201
+ console.log(`✅ live scorecard written: ${outPath} (total $${totalCost.toFixed(6)})`)
202
+ process.exit(0)
203
+ }
204
+
205
+ console.error('usage: node scripts/jev-live-probe.mjs --ping | --scorecard')
206
+ process.exit(1)
207
+ }
208
+
209
+ const invokedDirectly =
210
+ process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href
211
+
212
+ if (invokedDirectly) main()
@@ -0,0 +1,273 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * skill-search.mjs — read-only search over the open skills ecosystem
4
+ * (skills.sh via the `skills` CLI) for the discovery pipeline documented in
5
+ * `docs/reference/native-decisions.md` and `src/agents/zeus.md`.
6
+ *
7
+ * The ladder this tool serves: installed skills first (one Jev
8
+ * `mode: "skills"` call answers over the local pool); only when nothing fits
9
+ * does the agent search the ecosystem, rank what came back with one typed
10
+ * Jev choice question, and PROPOSE the project-scoped install to the user —
11
+ * Pantheon never installs, and third-party skills are untrusted instructions.
12
+ *
13
+ * The `skills find` CLI prints ANSI-colored human text; this wrapper strips
14
+ * the escapes and emits the parseable contract (`owner/repo@skill`,
15
+ * install count, skills.sh URL) as JSON — the same contract the agent-side
16
+ * inline parse follows. Read-only: it never adds, updates, or removes
17
+ * skills, and no credentials cross it.
18
+ *
19
+ * Usage:
20
+ * node scripts/skill-search.mjs "<query>" [--limit 5] [--owner <owner>] [--raw]
21
+ */
22
+
23
+ import { spawnSync } from 'node:child_process'
24
+ import { pathToFileURL } from 'node:url'
25
+
26
+ const FIND_TIMEOUT_MS = 60_000
27
+ const DEFAULT_LIMIT = 5
28
+ /** SGR escape sequences are matched via the ESC codepoint (lint-clean, same semantics). */
29
+ const ANSI_SGR = new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, 'g')
30
+ const SKILL_LINE =
31
+ /^([A-Za-z0-9._-]+\/[A-Za-z0-9._-]+@[A-Za-z0-9._-]+)\s+([\d.,]+)\s*([KM]?)\s+installs$/
32
+ const URL_LINE = /^└?\s*(https:\/\/skills\.sh\/\S+)$/
33
+
34
+ /** '578.8K' / '1.2M' / '489' → absolute integer installs (K=1e3, M=1e6). */
35
+ export function parseInstallCount(digits, suffix) {
36
+ const base = Number(String(digits).replaceAll(',', ''))
37
+ if (!Number.isFinite(base)) return null
38
+ if (suffix === 'K') return Math.round(base * 1_000)
39
+ if (suffix === 'M') return Math.round(base * 1_000_000)
40
+ return Math.round(base)
41
+ }
42
+
43
+ /** Remove SGR escape sequences so the text lines become parseable. */
44
+ export function stripAnsi(text) {
45
+ return String(text).replace(ANSI_SGR, '')
46
+ }
47
+
48
+ /**
49
+ * Parse `skills find` output into ordered entries {skill, installs, url?}.
50
+ * `limit` (default 5) caps the result; entries keep the CLI's printed order
51
+ * (the ecosystem's own ranking), never re-sorted here.
52
+ */
53
+ export function parseSkillSearchOutput(raw, { limit = DEFAULT_LIMIT } = {}) {
54
+ const lines = stripAnsi(raw)
55
+ .split('\n')
56
+ .map((line) => line.trim())
57
+ .filter((line) => line.length > 0)
58
+ const found = []
59
+ for (const line of lines) {
60
+ const skillMatch = line.match(SKILL_LINE)
61
+ if (skillMatch !== null) {
62
+ if (found.length >= limit) continue
63
+ found.push({
64
+ skill: skillMatch[1],
65
+ installs: parseInstallCount(skillMatch[2], skillMatch[3]),
66
+ url: undefined,
67
+ })
68
+ continue
69
+ }
70
+ const urlMatch = line.match(URL_LINE)
71
+ if (urlMatch !== null && found.length > 0) {
72
+ const last = found[found.length - 1]
73
+ if (last.url === undefined) last.url = urlMatch[1]
74
+ }
75
+ }
76
+ return found
77
+ }
78
+
79
+ /** Run the ecosystem search once and return parsed entries. */
80
+ export function searchSkills(query, { limit = DEFAULT_LIMIT, owner, spawn = spawnSync } = {}) {
81
+ const args = ['skills', 'find', String(query)]
82
+ if (owner !== undefined) args.push('--owner', String(owner))
83
+ const result = spawn('npx', args, {
84
+ encoding: 'utf8',
85
+ timeout: FIND_TIMEOUT_MS,
86
+ stdio: ['ignore', 'pipe', 'pipe'],
87
+ })
88
+ if (result.error !== undefined) {
89
+ return { ok: false, error: `skills search failed to start: ${result.error.message}` }
90
+ }
91
+ const raw = `${result.stdout ?? ''}`
92
+ if (result.status !== 0 && raw.trim() === '') {
93
+ return { ok: false, error: `skills search exited ${result.status}` }
94
+ }
95
+ const entries = parseSkillSearchOutput(raw, { limit })
96
+ // Field finding (beta.13 §9): skills.sh intermittently answers "No skills
97
+ // found" (exit 0) for queries that succeed on retry — an empty result is
98
+ // AMBIGUOUS between "nothing exists" and "degraded". Retry once on empty;
99
+ // when still empty the callers treat it as not-found (the cascade moves on).
100
+ if (entries.length === 0) {
101
+ const retry = spawn('npx', args, {
102
+ encoding: 'utf8',
103
+ timeout: FIND_TIMEOUT_MS,
104
+ stdio: ['ignore', 'pipe', 'pipe'],
105
+ })
106
+ const retryRaw = `${retry.stdout ?? ''}`
107
+ const retried = parseSkillSearchOutput(retryRaw, { limit })
108
+ if (retried.length > 0)
109
+ return { ok: true, entries: retried, raw: retryRaw, emptyIsAmbiguous: false }
110
+ return { ok: true, entries: [], raw, emptyIsAmbiguous: true }
111
+ }
112
+ return { ok: true, entries, raw, emptyIsAmbiguous: false }
113
+ }
114
+
115
+ const GITHUB_TIMEOUT_MS = 30_000
116
+ const ANTHROPIC_SKILLS_REPO = 'anthropics/skills'
117
+
118
+ /**
119
+ * Tier 1: the canonical Anthropic catalog. Highest trust (curated upstream),
120
+ * checked first so the canonical `pdf`/`docx`/`xlsx`/`mcp-builder` skills
121
+ * outrank the third-party clones that skills.sh's ranking can surface.
122
+ * Matches query tokens against catalog entry names; returns one entry per
123
+ * matched name.
124
+ */
125
+ export function searchAnthropicCatalog(query, { limit = DEFAULT_LIMIT, spawn = spawnSync } = {}) {
126
+ const result = spawn(
127
+ 'gh',
128
+ ['api', `repos/${ANTHROPIC_SKILLS_REPO}/contents/skills`, '--jq', '.[].name'],
129
+ { encoding: 'utf8', timeout: GITHUB_TIMEOUT_MS, stdio: ['ignore', 'pipe', 'pipe'] },
130
+ )
131
+ if (result.error !== undefined || result.status !== 0) {
132
+ return { ok: false, error: 'anthropic catalog lookup failed (gh api)' }
133
+ }
134
+ const tokens = String(query)
135
+ .toLowerCase()
136
+ .split(/[^a-z0-9]+/)
137
+ .filter((token) => token.length > 2)
138
+ const names = String(result.stdout ?? '')
139
+ .split('\n')
140
+ .map((name) => name.trim())
141
+ .filter((name) => name.length > 0)
142
+ const matched = names.filter((name) => {
143
+ const lower = name.toLowerCase()
144
+ return tokens.some((token) => lower.includes(token))
145
+ })
146
+ return {
147
+ ok: true,
148
+ entries: matched.slice(0, limit).map((name) => ({
149
+ skill: `${ANTHROPIC_SKILLS_REPO}@${name}`,
150
+ installs: null,
151
+ url: `https://github.com/${ANTHROPIC_SKILLS_REPO}/tree/main/skills/${name}`,
152
+ source: 'anthropic',
153
+ })),
154
+ }
155
+ }
156
+
157
+ /**
158
+ * Tier 3: raw GitHub code search over every `SKILL.md` (the widest net —
159
+ * orders of magnitude beyond the skills.sh index, and the weakest trust:
160
+ * every hit is unreviewed third-party instructions).
161
+ */
162
+ export function searchGithubSkills(query, { limit = DEFAULT_LIMIT, spawn = spawnSync } = {}) {
163
+ const terms = String(query)
164
+ .split(/\s+/)
165
+ .filter((term) => term.length > 1)
166
+ .slice(0, 3)
167
+ .map((term) => encodeURIComponent(term))
168
+ .join('+')
169
+ if (terms === '') return { ok: true, entries: [] }
170
+ const result = spawn(
171
+ 'gh',
172
+ ['api', `search/code?q=filename:SKILL.md+${terms}&per_page=${Math.min(limit, 10)}`],
173
+ { encoding: 'utf8', timeout: GITHUB_TIMEOUT_MS, stdio: ['ignore', 'pipe', 'pipe'] },
174
+ )
175
+ if (result.error !== undefined || result.status !== 0) {
176
+ return { ok: false, error: 'github code search failed (gh api)' }
177
+ }
178
+ let parsed
179
+ try {
180
+ parsed = JSON.parse(String(result.stdout ?? '{}'))
181
+ } catch {
182
+ return { ok: false, error: 'github code search returned non-JSON output' }
183
+ }
184
+ const items = Array.isArray(parsed.items) ? parsed.items : []
185
+ return {
186
+ ok: true,
187
+ entries: items.slice(0, limit).map((item) => {
188
+ const repo = String(item?.repository?.full_name ?? 'unknown/repo')
189
+ const path = String(item?.path ?? 'SKILL.md')
190
+ const name = path.split('/')[Math.max(0, path.split('/').length - 2)] ?? 'skill'
191
+ return {
192
+ skill: `${repo}@${name}`,
193
+ installs: null,
194
+ url: `https://github.com/${repo}/blob/main/${path}`,
195
+ source: 'github',
196
+ }
197
+ }),
198
+ }
199
+ }
200
+
201
+ /**
202
+ * The trust cascade: anthropic (canonical) → skills-sh (install-count
203
+ * signal, unreviewed) → github (widest, least trusted). Tier order is the
204
+ * recommendation order; callers may narrow with `sources`.
205
+ */
206
+ export const SKILL_SEARCH_SOURCES = Object.freeze(['anthropic', 'skills-sh', 'github'])
207
+
208
+ export function searchSkillSources(
209
+ query,
210
+ { limit = DEFAULT_LIMIT, owner, sources = SKILL_SEARCH_SOURCES, spawn = spawnSync } = {},
211
+ ) {
212
+ const perTier = Math.max(1, Math.ceil(limit / sources.length))
213
+ const out = []
214
+ const failures = []
215
+ for (const source of sources) {
216
+ const result =
217
+ source === 'anthropic'
218
+ ? searchAnthropicCatalog(query, { limit: perTier, spawn })
219
+ : source === 'skills-sh'
220
+ ? searchSkills(query, { limit: perTier, owner, spawn })
221
+ : source === 'github'
222
+ ? searchGithubSkills(query, { limit: perTier, spawn })
223
+ : { ok: false, error: `unknown source: ${source}` }
224
+ if (result.ok) out.push(...result.entries.map((entry) => ({ ...entry, source })))
225
+ else failures.push(`${source}: ${result.error}`)
226
+ }
227
+ return { ok: failures.length < sources.length, entries: out.slice(0, limit), failures }
228
+ }
229
+
230
+ function main(args = process.argv.slice(2)) {
231
+ const get = (flag) => {
232
+ const i = args.indexOf(flag)
233
+ return i >= 0 ? args[i + 1] : undefined
234
+ }
235
+ const query = args.find((a) => !a.startsWith('--'))
236
+ if (query === undefined) {
237
+ console.error(
238
+ 'usage: node scripts/skill-search.mjs "<query>" [--limit 5(total, merged across tiers)] [--sources anthropic,skills-sh,github] [--owner <owner>] [--raw]',
239
+ )
240
+ process.exit(1)
241
+ }
242
+ const sourcesArg = get('--sources')
243
+ const sources =
244
+ sourcesArg === undefined
245
+ ? SKILL_SEARCH_SOURCES
246
+ : sourcesArg
247
+ .split(',')
248
+ .map((s) => s.trim())
249
+ .filter((s) => s.length > 0)
250
+ const result = searchSkillSources(query, {
251
+ limit: Number(get('--limit') ?? DEFAULT_LIMIT),
252
+ owner: get('--owner'),
253
+ sources,
254
+ })
255
+ if (args.includes('--raw')) {
256
+ const skillsSh = result.entries.filter((e) => e.source === 'skills-sh')
257
+ console.log(JSON.stringify(skillsSh, null, 1))
258
+ return
259
+ }
260
+ if (result.failures.length > 0) {
261
+ for (const failure of result.failures) console.error(`warning: ${failure}`)
262
+ }
263
+ if (result.entries.length === 0 && result.failures.length === sources.length) {
264
+ console.error('all sources failed')
265
+ process.exit(1)
266
+ }
267
+ console.log(JSON.stringify(result.entries, null, 1))
268
+ }
269
+
270
+ const invokedDirectly =
271
+ process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href
272
+
273
+ if (invokedDirectly) main()
@@ -106,6 +106,17 @@ export function copyPluginFiles(srcDir, dstDir, version) {
106
106
  else result.skipped++
107
107
  }
108
108
 
109
+ // CHANGELOG.md — the copy's one-time "What's new" window reads the release
110
+ // highlights for the running version from its own installed root. Best
111
+ // effort: a missing source simply means no window (the TUI fails open).
112
+ // src/plugins/tui → src/plugins → src → package root.
113
+ const changelogSrc = join(srcDir, '..', '..', '..', 'CHANGELOG.md')
114
+ if (existsSync(changelogSrc)) {
115
+ if (writeIfChanged(join(dstDir, 'CHANGELOG.md'), readFileSync(changelogSrc, 'utf8'))) {
116
+ result.created++
117
+ } else result.skipped++
118
+ }
119
+
109
120
  const tuiEntry = join(srcDir, version === 'v2' ? 'tui-v2.ts' : 'tui.ts')
110
121
  if (existsSync(tuiEntry)) {
111
122
  if (writeIfChanged(join(dstDir, 'tui.ts'), readFileSync(tuiEntry, 'utf8'))) result.created++
package/skills-lock.json CHANGED
@@ -10,6 +10,7 @@
10
10
  "src/skills/incremental-implementation/SKILL.md": "7065ddb45da3c6b6751de07f290e92e6cb072e949a2e3aaae13ee7762f0a70fc",
11
11
  "src/skills/loop-engineering/SKILL.md": "f804e545821b9cca8fe0ec517307ed902446f28c2ca8ff9194c0f987cf7229e3",
12
12
  "src/skills/memory-bank/SKILL.md": "6c27623e5588b7ba44fbd0ea88e5061ed36894e1c7cbc88e50f003c2b463d9ff",
13
+ "src/skills/prompt-refinery/SKILL.md": "d2ed35b1d74ee1caef07b572ee7771e19019a9bc6ad40ea71c4b32dbccd256d9",
13
14
  "src/skills/reflect/SKILL.md": "4c7608c2a55cb8a50ac90fc0e2446bdf25e7914b1748cb7731c311d13c29dfdd",
14
15
  "src/skills/security-hardening/SKILL.md": "6d637e122421f7bc3b751f04854ad343a5a5d35249458bc8939233138fd3f20d",
15
16
  "src/skills/session-goal/SKILL.md": "2911157c8e020f62ca015a73a46f5427f41da71c83e624d6a1cecf7d64c64aea",
@@ -30,6 +30,30 @@ mcp_tools:
30
30
  pantheon-vision: [vision_describe, vision_ocr, vision_analyze]
31
31
  ---
32
32
 
33
+ ## MCP governance (identical ladder, grant-aware)
34
+
35
+ - Escalation order: session context first; the local selector answers free;
36
+ one typed `pantheon_jev_decide` question when genuinely ambiguous (Zeus
37
+ dispatches; a returned label is an advisory, never authorization); a
38
+ native MCP call is the LAST resort for state the session cannot
39
+ reconstruct.
40
+ - **Memory recall/search** — at most one selective query per turn, only when
41
+ prior project history could change the decision; never for context you
42
+ already hold. Every result rides in your context for the rest of the
43
+ session.
44
+ - **Memory store** (only where granted) — durable, reusable facts ONLY:
45
+ decisions with reasons, root causes, conventions, user preferences.
46
+ Session narration never stores: subtask summaries, delegation status and
47
+ debugging play-by-play go to a checkpoint or nowhere. Namespace per
48
+ project; update an existing key instead of duplicating.
49
+ - **Persistence checkpoints** (only where granted) — milestones only: would
50
+ losing this be expensive to redo? Never per turn; never re-save an
51
+ unchanged key.
52
+ - **Vision** (only where granted) — only when the turn carries an
53
+ addressable image; one pass per image; each call is real gateway spend.
54
+ - **Code-mode / infrastructure reads** — cheap and on demand; never for
55
+ decisions the ladder already answers.
56
+
33
57
  ## Verification Tiers
34
58
 
35
59
  Small bounded fix → change + one targeted proof, no ceremony. Material change → full test discipline. Match the tier to the change.
@@ -63,7 +87,7 @@ You are a frontend implementation specialist. You BUILD UI. You do NOT design ar
63
87
  1. Inspect relevant component/test/API files directly; when broad or unfamiliar discovery materially reduces risk, send the discovery need to Zeus for routing
64
88
  2. Read relevant frontend standards; load `skill: visual-review-pipeline` only when visual behavior changed
65
89
  3. Plan component/data flow when scope or risk warrants it; do not require a design phase for a bounded fix
66
- 4. For a supplied image/screenshot, use the original reference and Zeus's visual notes as acceptance context; call `vision_describe` if the image is addressable but not directly visible. Inspect the current state first and preserve unrelated existing work—do not delete or revert it just to match the reference unless that replacement is explicitly in scope.
90
+ 4. For a supplied image/screenshot, use the original reference and Zeus's visual notes as acceptance context; call `vision_describe` if the image is addressable but not directly visible. One pass per image: `vision_describe` for visual review, `vision_ocr` only when text extraction is the goal — never two vision calls on the same screenshot (each call is real gateway spend). Inspect the current state first and preserve unrelated existing work—do not delete or revert it just to match the reference unless that replacement is explicitly in scope.
67
91
  - Investigate beyond the assigned context only when necessary to resolve the task or when broader discovery materially reduces risk; verify changed behavior proportionally to its scope and risk, using focused checks for bounded changes and broader checks only when integration boundaries or risk warrant them.
68
92
 
69
93
  ### Implementation (TDD)
@@ -119,3 +143,12 @@ After implementing UI components:
119
143
 
120
144
  ## Skills
121
145
  Frontend: `tdd-with-agents`, `visual-review-pipeline`, `incremental-implementation`
146
+
147
+ ## Domain conventions doc
148
+
149
+ If this project has a real UI/frontend surface, keep `docs/ui/conventions.md` current as you
150
+ work: stack versions, decided patterns, the conventions this project actually
151
+ follows. Read it first when it exists; propose creating it when the surface
152
+ exists and the file does not. Update only what you changed — a stale
153
+ convention line is worse than a missing one. The next session starts from
154
+ this file, not from your memory.