opencode-wiki-historian 0.6.3 → 0.7.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 (56) hide show
  1. package/README.en.md +156 -42
  2. package/README.md +127 -360
  3. package/dist/anchor.js +4 -4
  4. package/dist/config.d.ts +3 -3
  5. package/dist/config.js +3 -3
  6. package/dist/index.d.ts +14 -4
  7. package/dist/index.js +21 -52
  8. package/dist/lint.d.ts +2 -2
  9. package/dist/lint.js +2 -2
  10. package/dist/maintain.d.ts +2 -2
  11. package/dist/maintain.js +7 -7
  12. package/dist/map.d.ts +1 -1
  13. package/dist/map.js +1 -1
  14. package/dist/migrate-apply.d.ts +1 -1
  15. package/dist/migrate-apply.js +1 -1
  16. package/dist/migrate-score.d.ts +2 -2
  17. package/dist/migrate-score.js +3 -3
  18. package/dist/migrate-store.d.ts +1 -1
  19. package/dist/migrate-store.js +1 -1
  20. package/dist/migrate.d.ts +2 -2
  21. package/dist/migrate.js +2 -2
  22. package/dist/prompts.d.ts +20 -0
  23. package/dist/prompts.js +46 -0
  24. package/dist/skills.d.ts +33 -0
  25. package/dist/skills.js +88 -0
  26. package/dist/surface.d.ts +1 -1
  27. package/dist/surface.js +2 -2
  28. package/dist/templates/evidence.d.ts +1 -1
  29. package/dist/templates/evidence.js +1 -1
  30. package/dist/templates/genres.d.ts +5 -5
  31. package/dist/templates/genres.js +7 -7
  32. package/dist/templates/skeletons.d.ts +3 -3
  33. package/dist/templates/skeletons.js +3 -3
  34. package/dist/tools/anchor.js +2 -2
  35. package/dist/tools/create.js +1 -1
  36. package/dist/tools/local.js +1 -1
  37. package/dist/tools/mutate.d.ts +1 -1
  38. package/dist/tools/mutate.js +1 -1
  39. package/dist/tools/shared.d.ts +3 -3
  40. package/dist/tools/shared.js +10 -10
  41. package/dist/tools.d.ts +2 -2
  42. package/dist/tools.js +2 -2
  43. package/dist/translate.d.ts +1 -1
  44. package/dist/translate.js +1 -1
  45. package/dist/v2.d.ts +114 -0
  46. package/dist/v2.js +249 -0
  47. package/dist/wiki/assets.d.ts +1 -1
  48. package/dist/wiki/assets.js +1 -1
  49. package/dist/wiki/client.d.ts +2 -3
  50. package/dist/wiki/client.js +2 -3
  51. package/dist/wiki/locale.d.ts +1 -1
  52. package/dist/wiki/locale.js +3 -3
  53. package/dist/wiki/pages.read.d.ts +1 -1
  54. package/dist/wiki/pages.write.d.ts +1 -1
  55. package/package.json +1 -1
  56. package/skills/historian/SKILL.md +2 -2
package/dist/config.js CHANGED
@@ -23,7 +23,7 @@ export const DEFAULT_BASE_URL = 'http://localhost:3000';
23
23
  export const DEFAULT_API_KEY_PATH = '~/.wikijs-api-key';
24
24
  /** Env leg of the endpoint chain: raw option → this env var → unset (''). */
25
25
  export const ENV_TRANSLATE_ENDPOINT = 'HISTORIAN_TRANSLATE_ENDPOINT';
26
- /** L-MACHINE-LOCAL (owner ruling 2026-10-01, 复核 2026-10-02): the portable
26
+ /** Package-portability rule (decided 2026-10-01, re-confirmed 2026-10-02): the portable
27
27
  * package must NOT pin the operator's model choice. Resolution is
28
28
  * explicit-option -> env leg -> unset (''), and an unset model fails loudly
29
29
  * at first translate call (see translate.ts), never silently defaults. */
@@ -32,9 +32,9 @@ export const ENV_TRANSLATE_MODEL = 'HISTORIAN_TRANSLATE_MODEL';
32
32
  export const DEFAULT_SECTIONS = [];
33
33
  export const DEFAULT_LOCALES = ['en', 'zh'];
34
34
  /** Reading loop is opt-in: activated only when configured true AND the local
35
- * sentinel confirms it (plan v3 todo 1; see src/loop-state.ts). */
35
+ * sentinel confirms it (see src/loop-state.ts). */
36
36
  export const DEFAULT_READING_LOOP = false;
37
- /** Capture reminders are opt-in (plan v2 todo 9). */
37
+ /** Capture reminders are opt-in. */
38
38
  export const DEFAULT_CAPTURE_ENABLED = false;
39
39
  // --- Resolution -------------------------------------------------------------
40
40
  /**
package/dist/index.d.ts CHANGED
@@ -1,12 +1,16 @@
1
1
  /**
2
- * opencode-historian plugin entry (todo 12).
2
+ * opencode-historian plugin entry (V1 host + V2 plugin-API port).
3
3
  *
4
- * Exports the V1 plugin object shape verified by the oracle:
5
- * export default { id: string, server: (input, options?) => Promise<Hooks> }
4
+ * Dual-generation default export (billion-context precedent):
5
+ * export default { id, setup(ctx), server(input, options?) }
6
+ * The V2 host (engine >= 2.2) consumes `setup` (src/v2.ts — the whole plugin
7
+ * must expose {id, effect|setup} or it is rejected with "Plugin must export
8
+ * a default definition..."); the V1 host consumes `server`. The id matches
9
+ * the npm package name (single source).
6
10
  *
7
11
  * The server() hook resolves plugin options and returns:
8
12
  * - config: mutates cfg.skills.paths to ship the bundled skills/ directory
9
- * and registers the /historian-capture command (todo 9)
13
+ * and registers the /historian-capture command
10
14
  * - tool: 11 historian_* tools wired by buildTools(opts)
11
15
  * - experimental.chat.system.transform: merges the historian-first reading
12
16
  * loop advisory into the LAST system block (single-block-safe append — a
@@ -17,6 +21,8 @@
17
21
  * (gated by opts.capture.enabled; reminder-only — the page write happens
18
22
  * through /historian-capture -> historian_page_create, never here)
19
23
  *
24
+ * Agent-facing text constants are single-sourced in src/prompts.ts.
25
+ *
20
26
  * Defensive: if resolveOptions throws (e.g. missing translate key), we catch
21
27
  * at the server() boundary, log once to console.error, and return hooks with
22
28
  * empty tools. The plugin registration itself must not crash opencode startup;
@@ -28,6 +34,10 @@ import type { PluginInput, PluginOptions, Hooks } from '@opencode-ai/plugin';
28
34
  type ServerFn = (input: PluginInput, options?: PluginOptions) => Promise<Hooks>;
29
35
  interface PluginExport {
30
36
  readonly id: string;
37
+ /** V2 host entry (engine >= 2.2): default export needs {id, setup|effect}. */
38
+ readonly setup: (ctx: import('./v2.js').V2Ctx, deps?: import('./v2.js').SetupDeps) => Promise<void>;
39
+ /** V1 host entry: {id, server(input, options) => Hooks}. Kept for hosts
40
+ * still loading plugins through the legacy `plugin` config key. */
31
41
  readonly server: ServerFn;
32
42
  }
33
43
  declare const plugin: PluginExport;
package/dist/index.js CHANGED
@@ -1,12 +1,16 @@
1
1
  /**
2
- * opencode-historian plugin entry (todo 12).
2
+ * opencode-historian plugin entry (V1 host + V2 plugin-API port).
3
3
  *
4
- * Exports the V1 plugin object shape verified by the oracle:
5
- * export default { id: string, server: (input, options?) => Promise<Hooks> }
4
+ * Dual-generation default export (billion-context precedent):
5
+ * export default { id, setup(ctx), server(input, options?) }
6
+ * The V2 host (engine >= 2.2) consumes `setup` (src/v2.ts — the whole plugin
7
+ * must expose {id, effect|setup} or it is rejected with "Plugin must export
8
+ * a default definition..."); the V1 host consumes `server`. The id matches
9
+ * the npm package name (single source).
6
10
  *
7
11
  * The server() hook resolves plugin options and returns:
8
12
  * - config: mutates cfg.skills.paths to ship the bundled skills/ directory
9
- * and registers the /historian-capture command (todo 9)
13
+ * and registers the /historian-capture command
10
14
  * - tool: 11 historian_* tools wired by buildTools(opts)
11
15
  * - experimental.chat.system.transform: merges the historian-first reading
12
16
  * loop advisory into the LAST system block (single-block-safe append — a
@@ -17,6 +21,8 @@
17
21
  * (gated by opts.capture.enabled; reminder-only — the page write happens
18
22
  * through /historian-capture -> historian_page_create, never here)
19
23
  *
24
+ * Agent-facing text constants are single-sourced in src/prompts.ts.
25
+ *
20
26
  * Defensive: if resolveOptions throws (e.g. missing translate key), we catch
21
27
  * at the server() boundary, log once to console.error, and return hooks with
22
28
  * empty tools. The plugin registration itself must not crash opencode startup;
@@ -29,10 +35,12 @@ import { homedir } from 'node:os';
29
35
  import { resolveOptions } from './config.js';
30
36
  import { isReadingLoopConfirmed, loopStatePath } from './loop-state.js';
31
37
  import { buildTools } from './tools.js';
38
+ import { setup } from './v2.js';
39
+ import { READING_LOOP_ADVISORY, CAPTURE_COMMAND_DESCRIPTION, CAPTURE_COMMAND_TEMPLATE, CAPTURE_TOAST_MESSAGE, } from './prompts.js';
32
40
  /** Resolve the absolute path to the bundled skills/ directory. Uses
33
41
  * import.meta.url so it works whether loaded from dist/ (compiled) or src/
34
- * (dev). The skills/ directory may not exist yet (todo 13 creates it) — that
35
- * is plan-sanctioned; the config hook must not throw on a nonexistent dir,
42
+ * (dev). The skills/ directory may not exist yet (the skills package creates it)
43
+ * — that is expected; the config hook must not throw on a nonexistent dir,
36
44
  * opencode will simply skip it. */
37
45
  const skillsDir = fileURLToPath(new URL('../skills/', import.meta.url));
38
46
  /** Deduplicate an array of strings preserving first-occurrence order. Small
@@ -40,49 +48,9 @@ const skillsDir = fileURLToPath(new URL('../skills/', import.meta.url));
40
48
  function unique(items) {
41
49
  return [...new Set(items)];
42
50
  }
43
- /** Reading-loop advisory (plan v4 todo 8 / D6): the machine wiki is the
44
- * authoritative institutional memory; consult it index-first before acting,
45
- * prefer updating over duplicating, cite pages+dates, mark staleness.
46
- * Hard budget ≤8 lines (context-rot). Shipped text — generic wording only
47
- * (privacy-audit scans dist). */
48
- const READING_LOOP_ADVISORY = [
49
- 'You have a historian: a wiki.js knowledge base acting as this machine\'s authoritative institutional memory.',
50
- 'Before doing work that touches this machine\'s deployments, history, pitfalls, or decisions, consult it index-first:',
51
- '- Read the curated map before blind search: historian_read wiki-index or historian_map action:"show", then historian_search by topic;',
52
- '- PREFER UPDATE over CREATE: if a page may already exist, historian_read it first, then historian_page_update rather than creating a duplicate;',
53
- '- CITE evidence: name the wiki page URL and its date whenever you quote it;',
54
- '- MARK stale rows instead of silently overwriting: supersede or review-stamp contradictions (G5 ledger: check each row\'s verified date).',
55
- 'If you learn something new worth keeping, offer to record it as a page.',
56
- ].join('\n');
57
- /** /historian-capture command (plan v2 todo 9, upgraded by v4 todo-10 / D2+D3):
58
- * the always-available manual path from "notable session" to "G1 event page" —
59
- * trigger list, 四段式 evidence-chain body contract, evidence split, and the
60
- * draft→review→Active publish flow are the drive surface (idle toast is
61
- * non-observable; this template text is the contract). Registered regardless
62
- * of capture.enabled; the enabled-gated toast only nudges toward it.
63
- * Agent-facing instruction text, generic wording only (ships in the tarball).
64
- * Context-rot budget ≤~30 lines. */
65
- const CAPTURE_COMMAND_DESCRIPTION = '把本次会话记为史官事件页 / record this session as a historian event page';
66
- const CAPTURE_COMMAND_TEMPLATE = [
67
- 'Summarize the current session as a historian G1 event page — only if it produced capture-worthy knowledge.',
68
- '',
69
- '0. Capture triggers — proceed only if at least one matches, else say so and skip writing:',
70
- ' 事故闭环 incident closed with a root cause | 部署完成 deployment completed | bug修复合入 bugfix merged',
71
- ' | 探针结论 probe/eval conclusion | 被否决方案 rejected option (record the 否决理由 veto reason).',
72
- '1. Draft the body in the 四段式 evidence-chain order: 证据链/Evidence (what was observed, artifacts first)',
73
- ' → 方法/Method (how it was proven) → 修复手段/Fix (what changed, or the decision) → 函数级实现/Implementation (file:symbol detail).',
74
- "2. Run historian_map action:'show' to see existing sections, then choose a short factual path under one.",
75
- '3. Evidence split (G1 appendix contract): store the full 四段 material via historian_page_create with tier:"evidence"',
76
- ' under `_evidence/`; the main page body stays the cited/summarized form linking to those evidence pages.',
77
- '4. Carry SRE discipline in the 元数据表 metadata table rows: 影响/impact | 负责人/owner',
78
- ' | 后续动作/action items (owner + 优先级/priority + verifiable done-state) | 来源类型/source type.',
79
- '5. Pre-write self-check: create the page (genre "G1", 状态:draft, content included) so the 十项自检 scoring',
80
- ' advisory runs on the draft; fix its FAIL items via historian_page_update before publishing.',
81
- '6. Publish flow capture→review→Active: the page starts 状态:draft; once the self-check passes,',
82
- ' historian_page_update it to Active. The zh twin is auto-created.',
83
- '7. Echo both page URLs (en + zh) back to the user.',
84
- ].join('\n');
85
- const CAPTURE_TOAST_MESSAGE = '会话空闲:有值得留存的决定/修复/踩坑就跑 /historian-capture。Session idle — run /historian-capture if it produced decisions, fixes, or pitfalls worth keeping.';
51
+ // Agent-facing text constants (reading-loop advisory, capture command contract,
52
+ // capture reminder) live in src/prompts.ts — single source for both plugin
53
+ // generations (this V1 server() and the V2 setup() in v2.ts).
86
54
  async function server(input, options) {
87
55
  let opts;
88
56
  try {
@@ -137,7 +105,7 @@ async function server(input, options) {
137
105
  }
138
106
  }
139
107
  catch (err) {
140
- // A broken inject must never crash a chat request (plan v2 todo 8).
108
+ // A broken inject must never crash a chat request.
141
109
  console.error('[opencode-historian] reading-loop advisory skipped:', err instanceof Error ? err.message : err);
142
110
  }
143
111
  },
@@ -164,7 +132,7 @@ async function server(input, options) {
164
132
  });
165
133
  }
166
134
  catch (err) {
167
- // A failed reminder must never break the event stream (plan v2 todo 9).
135
+ // A failed reminder must never break the event stream.
168
136
  console.error('[opencode-historian] capture reminder skipped:', err instanceof Error ? err.message : err);
169
137
  }
170
138
  },
@@ -172,7 +140,8 @@ async function server(input, options) {
172
140
  return hooks;
173
141
  }
174
142
  const plugin = {
175
- id: 'opencode-historian',
143
+ id: 'opencode-wiki-historian',
144
+ setup,
176
145
  server,
177
146
  };
178
147
  export default plugin;
package/dist/lint.d.ts CHANGED
@@ -1,9 +1,9 @@
1
1
  /**
2
2
  * Body lint: one fence-aware pass over a page body producing the structural
3
- * facts every hard gate and surface detector reuses (plan v0.5.0 #6).
3
+ * facts every hard gate and surface detector reuses.
4
4
  * Pure functions, zero wiki I/O — the deep scanner injects bodies, the write
5
5
  * tools lint drafts before they hit the API. This is the module the
6
- * architecture-page audit (HANDOFF Issue #6) forced into existence: nothing
6
+ * architecture-page audit forced into existence: nothing
7
7
  * here was optional before, which is exactly how a page with five empty
8
8
  * sections shipped for three days claiming `状态: Active`.
9
9
  */
package/dist/lint.js CHANGED
@@ -1,9 +1,9 @@
1
1
  /**
2
2
  * Body lint: one fence-aware pass over a page body producing the structural
3
- * facts every hard gate and surface detector reuses (plan v0.5.0 #6).
3
+ * facts every hard gate and surface detector reuses.
4
4
  * Pure functions, zero wiki I/O — the deep scanner injects bodies, the write
5
5
  * tools lint drafts before they hit the API. This is the module the
6
- * architecture-page audit (HANDOFF Issue #6) forced into existence: nothing
6
+ * architecture-page audit forced into existence: nothing
7
7
  * here was optional before, which is exactly how a page with five empty
8
8
  * sections shipped for three days claiming `状态: Active`.
9
9
  */
@@ -1,5 +1,5 @@
1
1
  /**
2
- * Maintain curation report (plan todo-7, D3 CURATE / D12): deterministic
2
+ * Maintain curation report: deterministic
3
3
  * metric sweeps over already-fetched map rows (tier-1 light) plus optional
4
4
  * injected page-body reads (deep). The chronology.ts precedent holds here —
5
5
  * no client, no fs, no wiki logic: pure functions over MapRow-shaped input and
@@ -151,7 +151,7 @@ export declare const DUP_TITLE_THRESHOLD = 0.75;
151
151
  /** Stamp label incl. the 上次验证 variant (the set lint.ts STAMP_RE tests) — one
152
152
  * line-level source of truth for the honesty rule shared by surface + freshness. */
153
153
  export declare const STAMP_LINE_RE: RegExp;
154
- /** A stamp that confesses the review never executed (swarm-A P2 "stamp honesty"):
154
+ /** A stamp that confesses the review never executed ("stamp honesty"):
155
155
  * it must not exempt the claim ledger (surface) nor reset the cadence clock
156
156
  * (dueForReview). Matched per stamp line, never page-wide — "baseline" is a
157
157
  * common GPU-benchmark noun outside a stamp. */
package/dist/maintain.js CHANGED
@@ -1,5 +1,5 @@
1
1
  /**
2
- * Maintain curation report (plan todo-7, D3 CURATE / D12): deterministic
2
+ * Maintain curation report: deterministic
3
3
  * metric sweeps over already-fetched map rows (tier-1 light) plus optional
4
4
  * injected page-body reads (deep). The chronology.ts precedent holds here —
5
5
  * no client, no fs, no wiki logic: pure functions over MapRow-shaped input and
@@ -22,16 +22,16 @@ export const MAINTAIN_SCHEMA = 'historian.maintain.v3';
22
22
  export const DUP_TITLE_THRESHOLD = 0.75;
23
23
  const DAY_MS = 86_400_000;
24
24
  const DEFAULT_TOP_N = 10;
25
- /** Genres whose pages must carry the D4 last-verified stamp (G6 how-to joins
26
- * this set when todo-2 lands it — string membership, no type coupling). */
27
- // D4 freshness applies to knowledge-fact pages: G5 today; 'G6' is listed
25
+ /** Genres whose pages must carry the last-verified stamp (G6 how-to joins
26
+ * this set when its genre lane lands — string membership, no type coupling). */
27
+ // Freshness applies to knowledge-fact pages: G5 today; 'G6' is listed
28
28
  // pre-emptively so the deep sweep lights up when the genre lane lands.
29
29
  const FRESHNESS_GENRES = ['G5', 'G6'];
30
30
  const STAMP_RE = /上次核实|last verified/i;
31
31
  /** Stamp label incl. the 上次验证 variant (the set lint.ts STAMP_RE tests) — one
32
32
  * line-level source of truth for the honesty rule shared by surface + freshness. */
33
33
  export const STAMP_LINE_RE = /上次核实|上次验证|last verified/i;
34
- /** A stamp that confesses the review never executed (swarm-A P2 "stamp honesty"):
34
+ /** A stamp that confesses the review never executed ("stamp honesty"):
35
35
  * it must not exempt the claim ledger (surface) nor reset the cadence clock
36
36
  * (dueForReview). Matched per stamp line, never page-wide — "baseline" is a
37
37
  * common GPU-benchmark noun outside a stamp. */
@@ -224,7 +224,7 @@ function sectionDist(rows) {
224
224
  .map(([section, v]) => ({ section, paths: v.paths.size, rows: v.rows }))
225
225
  .sort((a, b) => b.paths - a.paths || cmpStr(a.section, b.section));
226
226
  }
227
- /** D4 review-by row inside a 元数据 markdown table (wiki.js has no front matter). */
227
+ /** Review-by row inside a 元数据 markdown table (wiki.js has no front matter). */
228
228
  function reviewByOf(body) {
229
229
  for (const line of body.split('\n')) {
230
230
  if (!line.trimStart().startsWith('|'))
@@ -331,7 +331,7 @@ function verifyCommandsOf(body) {
331
331
  }
332
332
  return out;
333
333
  }
334
- /** The join (swarm-B P-dueForReview, stamp honesty as its immune system): due
334
+ /** The dueForReview join (stamp honesty as its immune system): due
335
335
  * when the newest HONEST stamp is at or past the cadence (a weekly card is due
336
336
  * again on day 7), or when every stamp confesses non-execution — a confession
337
337
  * records intent, not verification, so it never exempts the page. A struck old
package/dist/map.d.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  /**
2
- * Locale-aware page map (todo 10): full cross-locale inventory with en/zh twin
2
+ * Locale-aware page map: full cross-locale inventory with en/zh twin
3
3
  * pairing, rendered as the markdown `_meta/page-map` cache page + local mirror.
4
4
  *
5
5
  * Intended readers: harness cache-read scripts, the admin UI, and
package/dist/map.js CHANGED
@@ -1,5 +1,5 @@
1
1
  /**
2
- * Locale-aware page map (todo 10): full cross-locale inventory with en/zh twin
2
+ * Locale-aware page map: full cross-locale inventory with en/zh twin
3
3
  * pairing, rendered as the markdown `_meta/page-map` cache page + local mirror.
4
4
  *
5
5
  * Intended readers: harness cache-read scripts, the admin UI, and
@@ -1,5 +1,5 @@
1
1
  /**
2
- * Migration engine — apply side (plan todo 14): the write pipeline. Order is
2
+ * Migration engine — apply side: the write pipeline. Order is
3
3
  * the safety contract: ① pre-image backup FIRST (before any write; both
4
4
  * locales, missing twin recorded null), ② per-locale upsert (present →
5
5
  * updatePage RMW; missing twin → auto-created via the translation engine,
@@ -1,5 +1,5 @@
1
1
  /**
2
- * Migration engine — apply side (plan todo 14): the write pipeline. Order is
2
+ * Migration engine — apply side: the write pipeline. Order is
3
3
  * the safety contract: ① pre-image backup FIRST (before any write; both
4
4
  * locales, missing twin recorded null), ② per-locale upsert (present →
5
5
  * updatePage RMW; missing twin → auto-created via the translation engine,
@@ -1,11 +1,11 @@
1
1
  /**
2
- * Deterministic self-review checklist scoring (plan todo 14/15): the 10-item
2
+ * Deterministic self-review checklist scoring: the 10-item
3
3
  * gate is scored by CODE on the reformatted draft — the LLM only restyles,
4
4
  * it never scores (an auditable gate). Verdict contract:
5
5
  * - items 1-8 (content) → 'pass' | 'fail' by the checks below
6
6
  * - items 4-6 are 'na' → when the page genre is not in appliesTo
7
7
  * - items 9-10 (post-write) → 'deferred' until after apply (they are FAIL
8
- * by construction pre-write; todo 15 writes them into the pilot report)
8
+ * by construction pre-write; the pilot report writes them after apply)
9
9
  *
10
10
  * Every threshold below is tolerant-but-real: it catches egregious
11
11
  * violations, never bikesheds a conformant page. Measured values ride in the
@@ -1,11 +1,11 @@
1
1
  /**
2
- * Deterministic self-review checklist scoring (plan todo 14/15): the 10-item
2
+ * Deterministic self-review checklist scoring: the 10-item
3
3
  * gate is scored by CODE on the reformatted draft — the LLM only restyles,
4
4
  * it never scores (an auditable gate). Verdict contract:
5
5
  * - items 1-8 (content) → 'pass' | 'fail' by the checks below
6
6
  * - items 4-6 are 'na' → when the page genre is not in appliesTo
7
7
  * - items 9-10 (post-write) → 'deferred' until after apply (they are FAIL
8
- * by construction pre-write; todo 15 writes them into the pilot report)
8
+ * by construction pre-write; the pilot report writes them after apply)
9
9
  *
10
10
  * Every threshold below is tolerant-but-real: it catches egregious
11
11
  * violations, never bikesheds a conformant page. Measured values ride in the
@@ -283,7 +283,7 @@ export function scoreChecklist(genre, draft) {
283
283
  }
284
284
  });
285
285
  }
286
- // --- Conformance signal (todo 14 roundtrip step ③) ---------------------------
286
+ // --- Conformance signal (migrate roundtrip step ③) ---------------------------
287
287
  /** Whitespace-normalized equality (the strong signal); otherwise trigram
288
288
  * Jaccard similarity ≥ 0.95. Deterministic, diff-based — never prose. */
289
289
  export function contentSimilar(a, b) {
@@ -1,5 +1,5 @@
1
1
  /**
2
- * Migrate persistence (plan todo 14): pre-image backup files + the
2
+ * Migrate persistence: pre-image backup files + the
3
3
  * path-level checkpoint. Both are plain JSON under the plan's 工件根
4
4
  * (results/ in the plugin repo; ~/.config/opencode in the home dir), with
5
5
  * tolerant reads — a corrupt/missing file degrades to an empty state,
@@ -1,5 +1,5 @@
1
1
  /**
2
- * Migrate persistence (plan todo 14): pre-image backup files + the
2
+ * Migrate persistence: pre-image backup files + the
3
3
  * path-level checkpoint. Both are plain JSON under the plan's 工件根
4
4
  * (results/ in the plugin repo; ~/.config/opencode in the home dir), with
5
5
  * tolerant reads — a corrupt/missing file degrades to an empty state,
package/dist/migrate.d.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  /**
2
- * Migration engine — reformat side (plan todo 14): LLM-driven genre restyle.
2
+ * Migration engine — reformat side: LLM-driven genre restyle.
3
3
  * The dry-run reads the page (en, else zh), classifies the genre (explicit
4
4
  * arg wins), reformats via the translate engine's Anthropic-compatible call
5
5
  * path (SAME-LANGUAGE restyle — the twin is translated at apply time, never
@@ -27,7 +27,7 @@ export interface MigrateDeps {
27
27
  export interface ReformatArgs {
28
28
  readonly path: string;
29
29
  readonly genre?: Genre;
30
- /** Pilot revise-loop seam (todo 15): corrective hints appended into the
30
+ /** Pilot revise-loop seam: corrective hints appended into the
31
31
  * restyle user prompt when a previous draft failed checklist items. */
32
32
  readonly reviseHints?: readonly string[];
33
33
  }
package/dist/migrate.js CHANGED
@@ -1,5 +1,5 @@
1
1
  /**
2
- * Migration engine — reformat side (plan todo 14): LLM-driven genre restyle.
2
+ * Migration engine — reformat side: LLM-driven genre restyle.
3
3
  * The dry-run reads the page (en, else zh), classifies the genre (explicit
4
4
  * arg wins), reformats via the translate engine's Anthropic-compatible call
5
5
  * path (SAME-LANGUAGE restyle — the twin is translated at apply time, never
@@ -61,7 +61,7 @@ export function reformatPromptFor(genre, lang, original) {
61
61
  original,
62
62
  ].join('\n');
63
63
  }
64
- /** Append pilot revise-loop hints to the restyle user prompt (todo 15 seam);
64
+ /** Append pilot revise-loop hints to the restyle user prompt;
65
65
  * absent hints leave the prompt byte-identical to the pre-seam form. */
66
66
  function appendReviseHints(prompt, hints) {
67
67
  if (hints === undefined || hints.length === 0)
@@ -0,0 +1,20 @@
1
+ /**
2
+ * Single source for every agent-facing text the plugin injects or registers
3
+ * (reading-loop advisory, /historian-capture command contract, capture
4
+ * reminder). Both plugin generations (V1 server() in index.ts, V2 setup() in
5
+ * v2.ts) import from here — text drift between the two surfaces is the bug
6
+ * class this module eliminates. Generic wording only: privacy-audit scans
7
+ * dist/ and these strings ship in the tarball.
8
+ */
9
+ /** Reading-loop advisory: the machine wiki is the
10
+ * authoritative institutional memory; consult it index-first before acting,
11
+ * prefer updating over duplicating, cite pages+dates, mark staleness.
12
+ * Hard budget ≤8 lines (context-rot). */
13
+ export declare const READING_LOOP_ADVISORY: string;
14
+ /** /historian-capture command:
15
+ * the always-available manual path from "notable session" to "G1 event page".
16
+ * Registered regardless of capture.enabled; the enabled-gated reminder only
17
+ * nudges toward it. Context-rot budget ≤~30 lines. */
18
+ export declare const CAPTURE_COMMAND_DESCRIPTION = "\u628A\u672C\u6B21\u4F1A\u8BDD\u8BB0\u4E3A\u53F2\u5B98\u4E8B\u4EF6\u9875 / record this session as a historian event page";
19
+ export declare const CAPTURE_COMMAND_TEMPLATE: string;
20
+ export declare const CAPTURE_TOAST_MESSAGE = "\u4F1A\u8BDD\u7A7A\u95F2\uFF1A\u6709\u503C\u5F97\u7559\u5B58\u7684\u51B3\u5B9A/\u4FEE\u590D/\u8E29\u5751\u5C31\u8DD1 /historian-capture\u3002Session idle \u2014 run /historian-capture if it produced decisions, fixes, or pitfalls worth keeping.";
@@ -0,0 +1,46 @@
1
+ /**
2
+ * Single source for every agent-facing text the plugin injects or registers
3
+ * (reading-loop advisory, /historian-capture command contract, capture
4
+ * reminder). Both plugin generations (V1 server() in index.ts, V2 setup() in
5
+ * v2.ts) import from here — text drift between the two surfaces is the bug
6
+ * class this module eliminates. Generic wording only: privacy-audit scans
7
+ * dist/ and these strings ship in the tarball.
8
+ */
9
+ /** Reading-loop advisory: the machine wiki is the
10
+ * authoritative institutional memory; consult it index-first before acting,
11
+ * prefer updating over duplicating, cite pages+dates, mark staleness.
12
+ * Hard budget ≤8 lines (context-rot). */
13
+ export const READING_LOOP_ADVISORY = [
14
+ 'You have a historian: a wiki.js knowledge base acting as this machine\'s authoritative institutional memory.',
15
+ 'Before doing work that touches this machine\'s deployments, history, pitfalls, or decisions, consult it index-first:',
16
+ '- Read the curated map before blind search: historian_read wiki-index or historian_map action:"show", then historian_search by topic;',
17
+ '- PREFER UPDATE over CREATE: if a page may already exist, historian_read it first, then historian_page_update rather than creating a duplicate;',
18
+ '- CITE evidence: name the wiki page URL and its date whenever you quote it;',
19
+ '- MARK stale rows instead of silently overwriting: supersede or review-stamp contradictions (G5 ledger: check each row\'s verified date).',
20
+ 'If you learn something new worth keeping, offer to record it as a page.',
21
+ ].join('\n');
22
+ /** /historian-capture command:
23
+ * the always-available manual path from "notable session" to "G1 event page".
24
+ * Registered regardless of capture.enabled; the enabled-gated reminder only
25
+ * nudges toward it. Context-rot budget ≤~30 lines. */
26
+ export const CAPTURE_COMMAND_DESCRIPTION = '把本次会话记为史官事件页 / record this session as a historian event page';
27
+ export const CAPTURE_COMMAND_TEMPLATE = [
28
+ 'Summarize the current session as a historian G1 event page — only if it produced capture-worthy knowledge.',
29
+ '',
30
+ '0. Capture triggers — proceed only if at least one matches, else say so and skip writing:',
31
+ ' 事故闭环 incident closed with a root cause | 部署完成 deployment completed | bug修复合入 bugfix merged',
32
+ ' | 探针结论 probe/eval conclusion | 被否决方案 rejected option (record the 否决理由 veto reason).',
33
+ '1. Draft the body in the 四段式 evidence-chain order: 证据链/Evidence (what was observed, artifacts first)',
34
+ ' → 方法/Method (how it was proven) → 修复手段/Fix (what changed, or the decision) → 函数级实现/Implementation (file:symbol detail).',
35
+ "2. Run historian_map action:'show' to see existing sections, then choose a short factual path under one.",
36
+ '3. Evidence split (G1 appendix contract): store the full 四段 material via historian_page_create with tier:"evidence"',
37
+ ' under `_evidence/`; the main page body stays the cited/summarized form linking to those evidence pages.',
38
+ '4. Carry SRE discipline in the 元数据表 metadata table rows: 影响/impact | 负责人/owner',
39
+ ' | 后续动作/action items (owner + 优先级/priority + verifiable done-state) | 来源类型/source type.',
40
+ '5. Pre-write self-check: create the page (genre "G1", 状态:draft, content included) so the 十项自检 scoring',
41
+ ' advisory runs on the draft; fix its FAIL items via historian_page_update before publishing.',
42
+ '6. Publish flow capture→review→Active: the page starts 状态:draft; once the self-check passes,',
43
+ ' historian_page_update it to Active. The zh twin is auto-created.',
44
+ '7. Echo both page URLs (en + zh) back to the user.',
45
+ ].join('\n');
46
+ export const CAPTURE_TOAST_MESSAGE = '会话空闲:有值得留存的决定/修复/踩坑就跑 /historian-capture。Session idle — run /historian-capture if it produced decisions, fixes, or pitfalls worth keeping.';
@@ -0,0 +1,33 @@
1
+ /**
2
+ * Skill-package discovery for the bundled skills/ directory (layout:
3
+ * skills/<name>/SKILL.md with `---` frontmatter carrying name/description).
4
+ *
5
+ * V1 ships the directory itself (config hook appends skills.paths); V2 must
6
+ * hand the host individual entries {id,name,description,path,content} via
7
+ * skill.transform — the host schema rejects entries without an id (observed
8
+ * SchemaError Missing key ["id"]), so id/name are guaranteed here from the
9
+ * frontmatter or, failing that, the package directory name.
10
+ *
11
+ * The frontmatter parser is deliberately a strict key:value subset (single
12
+ * line, optional surrounding quotes) — the shipped SKILL.md files use only
13
+ * that. A malformed or unreadable package is skipped with a console.error,
14
+ * never thrown: skill discovery must not take down plugin setup.
15
+ */
16
+ export interface SkillEntry {
17
+ readonly id: string;
18
+ readonly name: string;
19
+ readonly description: string;
20
+ readonly path: string;
21
+ readonly content: string;
22
+ }
23
+ export interface CollectDeps {
24
+ readonly log?: (message: string) => void;
25
+ }
26
+ /** Parse a leading `---` frontmatter block into flat string fields; returns
27
+ * the fields plus the body text after the block. No YAML dependency: lines
28
+ * are `key: value`, values may be wrapped in one layer of quotes. */
29
+ export declare function parseFrontmatter(raw: string): {
30
+ fields: Record<string, string>;
31
+ body: string;
32
+ };
33
+ export declare function collectSkillEntries(root: string, deps?: CollectDeps): SkillEntry[];
package/dist/skills.js ADDED
@@ -0,0 +1,88 @@
1
+ /**
2
+ * Skill-package discovery for the bundled skills/ directory (layout:
3
+ * skills/<name>/SKILL.md with `---` frontmatter carrying name/description).
4
+ *
5
+ * V1 ships the directory itself (config hook appends skills.paths); V2 must
6
+ * hand the host individual entries {id,name,description,path,content} via
7
+ * skill.transform — the host schema rejects entries without an id (observed
8
+ * SchemaError Missing key ["id"]), so id/name are guaranteed here from the
9
+ * frontmatter or, failing that, the package directory name.
10
+ *
11
+ * The frontmatter parser is deliberately a strict key:value subset (single
12
+ * line, optional surrounding quotes) — the shipped SKILL.md files use only
13
+ * that. A malformed or unreadable package is skipped with a console.error,
14
+ * never thrown: skill discovery must not take down plugin setup.
15
+ */
16
+ import { readdirSync, readFileSync, statSync } from 'fs';
17
+ import { join } from 'path';
18
+ /** Parse a leading `---` frontmatter block into flat string fields; returns
19
+ * the fields plus the body text after the block. No YAML dependency: lines
20
+ * are `key: value`, values may be wrapped in one layer of quotes. */
21
+ export function parseFrontmatter(raw) {
22
+ const fields = {};
23
+ const m = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(raw);
24
+ if (!m)
25
+ return { fields, body: raw };
26
+ for (const line of m[1].split(/\r?\n/)) {
27
+ const kv = /^([A-Za-z0-9_-]+):\s*(.*)$/.exec(line);
28
+ if (!kv)
29
+ continue;
30
+ let value = kv[2].trim();
31
+ if ((value.startsWith('"') && value.endsWith('"') && value.length > 1) ||
32
+ (value.startsWith("'") && value.endsWith("'") && value.length > 1)) {
33
+ value = value.slice(1, -1);
34
+ }
35
+ fields[kv[1]] = value;
36
+ }
37
+ return { fields, body: raw.slice(m[0].length) };
38
+ }
39
+ /** Find candidate SKILL.md files: root/SKILL.md plus one level of
40
+ * root/<dir>/SKILL.md. Sorted for deterministic registration order. */
41
+ function findSkillFiles(root) {
42
+ const found = [];
43
+ const direct = join(root, 'SKILL.md');
44
+ try {
45
+ if (statSync(direct).isFile())
46
+ found.push(direct);
47
+ }
48
+ catch {
49
+ /* root itself is not a skill package */
50
+ }
51
+ let names = [];
52
+ try {
53
+ names = readdirSync(root).sort();
54
+ }
55
+ catch {
56
+ return found; // skills/ may not exist (dev checkout without it) — skip silently
57
+ }
58
+ for (const name of names) {
59
+ const candidate = join(root, name, 'SKILL.md');
60
+ try {
61
+ if (statSync(candidate).isFile())
62
+ found.push(candidate);
63
+ }
64
+ catch {
65
+ /* not a skill directory */
66
+ }
67
+ }
68
+ return found;
69
+ }
70
+ export function collectSkillEntries(root, deps = {}) {
71
+ const log = deps.log ?? ((m) => console.error(m));
72
+ const entries = [];
73
+ for (const file of findSkillFiles(root)) {
74
+ try {
75
+ const { fields, body } = parseFrontmatter(readFileSync(file, 'utf8'));
76
+ const fallbackId = file.split(/[\\/]/).slice(-2)[0] || 'skill';
77
+ const id = fields.id || fields.name || fallbackId;
78
+ const name = fields.name || id;
79
+ const description = fields.description || `historian skill package: ${name}`;
80
+ const content = body.trim().length > 0 ? body : `# ${name}\n${description}`;
81
+ entries.push({ id, name, description, path: file, content });
82
+ }
83
+ catch (err) {
84
+ log(`[opencode-historian] skill package skipped (${file}): ${err instanceof Error ? err.message : String(err)}`);
85
+ }
86
+ }
87
+ return entries;
88
+ }
package/dist/surface.d.ts CHANGED
@@ -2,7 +2,7 @@
2
2
  * src/surface.ts — human-interface & content-hygiene detectors (V6.1).
3
3
  *
4
4
  * maintain.ts owns per-page G5/G6 freshness; this module owns the WIKI-WIDE
5
- * structural health of the human surface (HANDOFF issues #1-#6): navigation
5
+ * structural health of the human surface: navigation
6
6
  * hygiene, map-vs-live coverage, redirect-stub reachability, broken / stacked /
7
7
  * index-less links, orphans, twin divergence, zh-first language, unfinished
8
8
  * skeletons and claim ledgers that beg re-verification.
package/dist/surface.js CHANGED
@@ -2,7 +2,7 @@
2
2
  * src/surface.ts — human-interface & content-hygiene detectors (V6.1).
3
3
  *
4
4
  * maintain.ts owns per-page G5/G6 freshness; this module owns the WIKI-WIDE
5
- * structural health of the human surface (HANDOFF issues #1-#6): navigation
5
+ * structural health of the human surface: navigation
6
6
  * hygiene, map-vs-live coverage, redirect-stub reachability, broken / stacked /
7
7
  * index-less links, orphans, twin divergence, zh-first language, unfinished
8
8
  * skeletons and claim ledgers that beg re-verification.
@@ -260,7 +260,7 @@ function buildDeep(input, scans) {
260
260
  .map((s) => ({ path: s.row.path, cjkRatio: Number(s.lint.cjkRatio.toFixed(3)) }));
261
261
  const ledgerClaims = [];
262
262
  for (const s of ok) {
263
- // Stamp honesty (swarm-A P2): a stamp that only ever confesses the review
263
+ // Stamp honesty: a stamp that only ever confesses the review
264
264
  // never ran ("…(content not re-run)"/未复跑/未复核/baseline) is not evidence —
265
265
  // claiming review without execution must not suppress the claim ledger.
266
266
  // Any single non-confessional stamp line (incl. supersede-keeping-struck-old)
@@ -1,5 +1,5 @@
1
1
  /**
2
- * Machine-tier evidence page skeleton (v3 todo 5).
2
+ * Machine-tier evidence page skeleton.
3
3
  *
4
4
  * Evidence pages live under the internal namespaces (`_meta/`, `_evidence/`),
5
5
  * are hidden and monolingual — the wiki is their only store (no local mirror,