opencode-wiki-historian 0.5.1 → 0.5.3
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.
- package/dist/anchor.d.ts +63 -0
- package/dist/anchor.js +186 -0
- package/dist/lint.d.ts +19 -2
- package/dist/lint.js +73 -10
- package/dist/maintain.d.ts +44 -1
- package/dist/maintain.js +235 -1
- package/dist/migrate.js +2 -2
- package/dist/surface.d.ts +1 -1
- package/dist/surface.js +15 -1
- package/dist/templates/genres.js +3 -3
- package/dist/templates/skeletons.js +28 -18
- package/dist/tools/anchor.d.ts +10 -0
- package/dist/tools/anchor.js +90 -0
- package/dist/tools/local.js +32 -5
- package/dist/tools/shared.d.ts +3 -2
- package/dist/tools/shared.js +4 -3
- package/dist/tools.js +2 -0
- package/dist/wiki/pages.write.d.ts +6 -0
- package/dist/wiki/pages.write.js +24 -1
- package/package.json +1 -1
- package/skills/historian/SKILL.md +2 -2
- package/skills/historian/references/adapting-your-own-wiki.md +1 -1
- package/skills/historian/references/genres.md +4 -4
- package/skills/historian/references/rules.md +5 -4
package/dist/maintain.js
CHANGED
|
@@ -17,7 +17,7 @@ import { classifyGenre } from './templates/genres.js';
|
|
|
17
17
|
import { isInternalPath } from './tools/shared.js';
|
|
18
18
|
import { normalize } from './migrate-score.js';
|
|
19
19
|
// --- Constants --------------------------------------------------------------
|
|
20
|
-
export const MAINTAIN_SCHEMA = 'historian.maintain.
|
|
20
|
+
export const MAINTAIN_SCHEMA = 'historian.maintain.v3';
|
|
21
21
|
/** Trigram-Jaccard bar for calling two (different-path) titles near-duplicates. */
|
|
22
22
|
export const DUP_TITLE_THRESHOLD = 0.75;
|
|
23
23
|
const DAY_MS = 86_400_000;
|
|
@@ -28,9 +28,43 @@ const DEFAULT_TOP_N = 10;
|
|
|
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
|
+
/** Stamp label incl. the 上次验证 variant (the set lint.ts STAMP_RE tests) — one
|
|
32
|
+
* line-level source of truth for the honesty rule shared by surface + freshness. */
|
|
33
|
+
export const STAMP_LINE_RE = /上次核实|上次验证|last verified/i;
|
|
34
|
+
/** A stamp that confesses the review never executed (swarm-A P2 "stamp honesty"):
|
|
35
|
+
* it must not exempt the claim ledger (surface) nor reset the cadence clock
|
|
36
|
+
* (dueForReview). Matched per stamp line, never page-wide — "baseline" is a
|
|
37
|
+
* common GPU-benchmark noun outside a stamp. */
|
|
38
|
+
export const CONFESSIONAL_STAMP_RE = /(not re-run|未复跑|未复核|baseline)/i;
|
|
31
39
|
const REVIEW_LABEL_RE = /^(复核周期|复核期限|复核日期|review[-_ ]?by|review[-_ ]?due)$/i;
|
|
32
40
|
const ISO_DATE_RE = /\d{4}-\d{2}-\d{2}/;
|
|
33
41
|
const REDIRECT_RE = /^>\s*Redirect:/i;
|
|
42
|
+
/** Table column headers that carry the per-row last-verified date (G5 ledger card). */
|
|
43
|
+
const STAMP_COL_RE = /^(?:上次核实于?|上次验证于?|last verified)$/i;
|
|
44
|
+
/** Metadata row naming the review cadence — its value is a DURATION, unlike the
|
|
45
|
+
* ISO-date 复核期限/review-by row REVIEW_LABEL_RE owns. */
|
|
46
|
+
const CADENCE_LABEL_RE = /^(?:复核周期|复核节奏|review[-_ ]?cadence|cadence)$/i;
|
|
47
|
+
/** Ledger command-column headers: zh 复核命令/验证命令/命令/用法\/命令,
|
|
48
|
+
* en Re-check command / Verify command(s) / Command(s) / Usage \/ Command. */
|
|
49
|
+
const COMMAND_COL_RE = /^(?:命令|用法\s*\/\s*命令|复核命令|验证命令|commands?|usage\s*\/\s*commands?|re[-_ ]?check[-_ ]?commands?|verify[-_ ]?commands?)$/i;
|
|
50
|
+
const DASH_CELL_RE = /^:?-{2,}:?$/;
|
|
51
|
+
const NULLISH_CELL_RE = /^(?:—|–|-|n\/?a|待补充|todo|\?)$/i;
|
|
52
|
+
/** Action-item table column labels (header-anchored; the table is identified
|
|
53
|
+
* by carrying all three of these columns — see overdueActionsOf). */
|
|
54
|
+
const ACTION_COL_RE = /^(?:\*\*)?(?:措施|action)(?:\*\*)?$/i;
|
|
55
|
+
const DUE_COL_RE = /^(?:\*\*)?(?:期限|due|deadline)(?:\*\*)?$/i;
|
|
56
|
+
const STATUS_COL_RE = /^(?:\*\*)?(?:状态|status)(?:\*\*)?$/i;
|
|
57
|
+
/** Closed first (fail-quiet on neutral cells like 未完成), then open. */
|
|
58
|
+
const CLOSED_STATUS_RE = /已完成|^完成$|已取消|不做|done|closed|resolved|cancelled|wont.?fix/i;
|
|
59
|
+
const OPEN_STATUS_RE = /待办|进行中|todo|pending|in.?progress|open/i;
|
|
60
|
+
/** Cadence floors when a stamped page carries no parseable metadata row:
|
|
61
|
+
* G5 machine-state ledgers 7d (weekly re-run — the round-1 plan supersedes the
|
|
62
|
+
* older 30d skeleton hint), G4 concepts and G6 how-tos 90d (the G6 skeleton's
|
|
63
|
+
* own 复核周期 example "如每 90 天"); G1 postmortems 30d — their action items
|
|
64
|
+
* carry due dates and rot inside a quarter; G2/G3 have no cadence guidance, so
|
|
65
|
+
* the conservative quarterly 90d default applies. */
|
|
66
|
+
const GENRE_CADENCE_DAYS = { G1: 30, G5: 7, G4: 90, G6: 90 };
|
|
67
|
+
const DEFAULT_CADENCE_DAYS = 90;
|
|
34
68
|
// --- Title similarity (trigram core copied from migrate-score.ts:289, where it
|
|
35
69
|
// --- is private with a 0.95 roundtrip bar; maintain needs its own threshold) ---
|
|
36
70
|
function titleGrams(s) {
|
|
@@ -204,6 +238,168 @@ function reviewByOf(body) {
|
|
|
204
238
|
}
|
|
205
239
|
return null;
|
|
206
240
|
}
|
|
241
|
+
// --- dueForReview (cadence × stamp join; advisory only) --------------------------
|
|
242
|
+
function tableCells(line) {
|
|
243
|
+
const t = line.trim();
|
|
244
|
+
return t.startsWith('|') ? t.split('|').map((c) => c.trim()) : null;
|
|
245
|
+
}
|
|
246
|
+
const isSeparatorRow = (cells) => cells.some((c) => c !== '' && DASH_CELL_RE.test(c));
|
|
247
|
+
/** Every (date, confesses-non-execution) attestation in a body, two real shapes:
|
|
248
|
+
* a stamp LABEL line carrying its ISO date (metadata rows, quote stamps, struck
|
|
249
|
+
* history — the cockpit / 09-08-sweep forms) and each date under a
|
|
250
|
+
* 上次核实于/Last verified table column (the G5 card's per-row ledger dates). */
|
|
251
|
+
function stampEntriesOf(body) {
|
|
252
|
+
const out = [];
|
|
253
|
+
let dateCol = -1;
|
|
254
|
+
for (const line of body.split('\n')) {
|
|
255
|
+
const lineDate = STAMP_LINE_RE.test(line) ? line.match(ISO_DATE_RE) : null;
|
|
256
|
+
if (lineDate !== null)
|
|
257
|
+
out.push({ ms: Date.parse(lineDate[0]), confessional: CONFESSIONAL_STAMP_RE.test(line) });
|
|
258
|
+
const cells = tableCells(line);
|
|
259
|
+
if (cells === null) {
|
|
260
|
+
dateCol = -1;
|
|
261
|
+
continue;
|
|
262
|
+
}
|
|
263
|
+
if (isSeparatorRow(cells))
|
|
264
|
+
continue;
|
|
265
|
+
// A `| 上次核实 | 2026-01-01 |` label row carries its own date (line rule above
|
|
266
|
+
// owns it) — only a date-less header row arms the column extraction, else the
|
|
267
|
+
// next value row (any label!) would be mis-read as a ledger date.
|
|
268
|
+
const h = ISO_DATE_RE.test(line) ? -1 : cells.findIndex((c) => STAMP_COL_RE.test(c));
|
|
269
|
+
if (h >= 0) {
|
|
270
|
+
dateCol = h;
|
|
271
|
+
continue;
|
|
272
|
+
}
|
|
273
|
+
const cell = dateCol >= 0 ? cells[dateCol] : undefined;
|
|
274
|
+
if (cell !== undefined) {
|
|
275
|
+
const m = cell.match(ISO_DATE_RE);
|
|
276
|
+
if (m !== null)
|
|
277
|
+
out.push({ ms: Date.parse(m[0]), confessional: CONFESSIONAL_STAMP_RE.test(cell) });
|
|
278
|
+
}
|
|
279
|
+
}
|
|
280
|
+
return out.filter((e) => !Number.isNaN(e.ms));
|
|
281
|
+
}
|
|
282
|
+
/** '30天' / '每 30 天' / 'every 30 days' / '7d' / '2 weeks' / bare '14' → days.
|
|
283
|
+
* Dates, TODOs and prose return null — no cadence is ever fabricated. */
|
|
284
|
+
function parseDays(text) {
|
|
285
|
+
const t = text.trim();
|
|
286
|
+
const w = t.match(/(\d{1,3})\s*(?:weeks?|wks?|w\b|周)/i);
|
|
287
|
+
if (w !== null)
|
|
288
|
+
return Number(w[1]) * 7;
|
|
289
|
+
const d = t.match(/(\d{1,4})\s*(?:days?|d\b|天|日)/i);
|
|
290
|
+
if (d !== null)
|
|
291
|
+
return Number(d[1]);
|
|
292
|
+
return /^\d{1,3}$/.test(t) ? Number(t) : null;
|
|
293
|
+
}
|
|
294
|
+
function cadenceDaysOf(body) {
|
|
295
|
+
for (const line of body.split('\n')) {
|
|
296
|
+
const cells = tableCells(line);
|
|
297
|
+
if (cells === null || cells.length < 3 || !CADENCE_LABEL_RE.test(cells[1] ?? ''))
|
|
298
|
+
continue;
|
|
299
|
+
for (const cell of cells.slice(2)) {
|
|
300
|
+
const days = parseDays(cell);
|
|
301
|
+
if (days !== null)
|
|
302
|
+
return days;
|
|
303
|
+
}
|
|
304
|
+
}
|
|
305
|
+
return null;
|
|
306
|
+
}
|
|
307
|
+
/** Re-check commands from ledger verification tables (see COMMAND_COL_RE):
|
|
308
|
+
* backticks stripped, empty/nullish cells skipped, order kept, duplicates dropped. */
|
|
309
|
+
function verifyCommandsOf(body) {
|
|
310
|
+
const out = [];
|
|
311
|
+
let cmdCol = -1;
|
|
312
|
+
for (const line of body.split('\n')) {
|
|
313
|
+
const cells = tableCells(line);
|
|
314
|
+
if (cells === null) {
|
|
315
|
+
cmdCol = -1;
|
|
316
|
+
continue;
|
|
317
|
+
}
|
|
318
|
+
if (isSeparatorRow(cells))
|
|
319
|
+
continue;
|
|
320
|
+
const h = cells.findIndex((c) => COMMAND_COL_RE.test(c));
|
|
321
|
+
if (h >= 0) {
|
|
322
|
+
cmdCol = h;
|
|
323
|
+
continue;
|
|
324
|
+
}
|
|
325
|
+
const cell = cmdCol >= 0 ? cells[cmdCol] : undefined;
|
|
326
|
+
if (cell === undefined)
|
|
327
|
+
continue;
|
|
328
|
+
const cmd = cell.replace(/^`([\s\S]*)`$/, '$1').trim();
|
|
329
|
+
if (cmd !== '' && !NULLISH_CELL_RE.test(cmd) && !out.includes(cmd))
|
|
330
|
+
out.push(cmd);
|
|
331
|
+
}
|
|
332
|
+
return out;
|
|
333
|
+
}
|
|
334
|
+
/** The join (swarm-B P-dueForReview, stamp honesty as its immune system): due
|
|
335
|
+
* when the newest HONEST stamp is at or past the cadence (a weekly card is due
|
|
336
|
+
* again on day 7), or when every stamp confesses non-execution — a confession
|
|
337
|
+
* records intent, not verification, so it never exempts the page. A struck old
|
|
338
|
+
* confessional stamp beside a fresh honest one (supersede-keeping-struck-old)
|
|
339
|
+
* runs on the honest clock. */
|
|
340
|
+
function dueForReviewOf(body, genre, now) {
|
|
341
|
+
const entries = stampEntriesOf(body);
|
|
342
|
+
if (entries.length === 0)
|
|
343
|
+
return null;
|
|
344
|
+
const honest = entries.filter((e) => !e.confessional);
|
|
345
|
+
const clock = honest.length > 0 ? honest : entries;
|
|
346
|
+
const stampAge = Math.floor((now.getTime() - Math.max(...clock.map((e) => e.ms))) / DAY_MS);
|
|
347
|
+
const cadence = cadenceDaysOf(body) ?? GENRE_CADENCE_DAYS[genre] ?? DEFAULT_CADENCE_DAYS;
|
|
348
|
+
if (honest.length > 0 && stampAge < cadence)
|
|
349
|
+
return null;
|
|
350
|
+
return { stampAge, cadence, verifyCommands: verifyCommandsOf(body) };
|
|
351
|
+
}
|
|
352
|
+
/** Flattens a markdown cell to one ≤80-char line for report display. */
|
|
353
|
+
function flattenCell(cell) {
|
|
354
|
+
const flat = cell.replace(/[*_`]|<[^>]*>/g, '').replace(/\s+/g, ' ').trim();
|
|
355
|
+
return flat.length > 80 ? `${flat.slice(0, 77)}…` : flat;
|
|
356
|
+
}
|
|
357
|
+
/** Finds open action items past due in any G1-shaped action table (header must
|
|
358
|
+
* carry 措施/期限/状态 columns). Undated (TBD) rows are skipped here — they are
|
|
359
|
+
* a different defect owned by the authoring gate, not the ageing sweep. */
|
|
360
|
+
export function overdueActionsOf(body, now) {
|
|
361
|
+
const hits = [];
|
|
362
|
+
const lines = body.split('\n');
|
|
363
|
+
let colAction = -1, colDue = -1, colStatus = -1, inTable = false;
|
|
364
|
+
for (const line of lines) {
|
|
365
|
+
const cells = tableCells(line);
|
|
366
|
+
if (cells === null) {
|
|
367
|
+
inTable = false;
|
|
368
|
+
colAction = colDue = colStatus = -1;
|
|
369
|
+
continue;
|
|
370
|
+
}
|
|
371
|
+
if (cells.every((c) => DASH_CELL_RE.test(c.trim())))
|
|
372
|
+
continue;
|
|
373
|
+
const a = cells.findIndex((c) => ACTION_COL_RE.test(c.trim()));
|
|
374
|
+
const d = cells.findIndex((c) => DUE_COL_RE.test(c.trim()));
|
|
375
|
+
const s = cells.findIndex((c) => STATUS_COL_RE.test(c.trim()));
|
|
376
|
+
if (a !== -1 && d !== -1 && s !== -1) {
|
|
377
|
+
colAction = a;
|
|
378
|
+
colDue = d;
|
|
379
|
+
colStatus = s;
|
|
380
|
+
inTable = true;
|
|
381
|
+
continue;
|
|
382
|
+
}
|
|
383
|
+
if (!inTable || colAction < 0 || cells.length <= Math.max(colDue, colStatus))
|
|
384
|
+
continue;
|
|
385
|
+
const status = cells[colStatus].trim();
|
|
386
|
+
if (CLOSED_STATUS_RE.test(status) || !OPEN_STATUS_RE.test(status))
|
|
387
|
+
continue;
|
|
388
|
+
const dueMatch = cells[colDue].match(ISO_DATE_RE);
|
|
389
|
+
if (dueMatch === null)
|
|
390
|
+
continue;
|
|
391
|
+
const t = Date.parse(dueMatch[0]);
|
|
392
|
+
if (Number.isNaN(t) || t >= now.getTime())
|
|
393
|
+
continue;
|
|
394
|
+
hits.push({
|
|
395
|
+
action: flattenCell(cells[colAction]),
|
|
396
|
+
due: dueMatch[0],
|
|
397
|
+
daysOverdue: Math.floor((now.getTime() - t) / DAY_MS),
|
|
398
|
+
status,
|
|
399
|
+
});
|
|
400
|
+
}
|
|
401
|
+
return hits;
|
|
402
|
+
}
|
|
207
403
|
// --- buildMaintainReport --------------------------------------------------------
|
|
208
404
|
export async function buildMaintainReport(input, opts = {}) {
|
|
209
405
|
const now = opts.now ?? new Date();
|
|
@@ -222,11 +418,15 @@ export async function buildMaintainReport(input, opts = {}) {
|
|
|
222
418
|
localeCount.set(r.path, (localeCount.get(r.path) ?? 0) + 1);
|
|
223
419
|
let redirects = { available: false, count: 0, stubs: [] };
|
|
224
420
|
let freshness = null;
|
|
421
|
+
let dueForReview = null;
|
|
422
|
+
let overdueActions = null;
|
|
225
423
|
if (deep && opts.readBody !== undefined) {
|
|
226
424
|
const readBody = opts.readBody;
|
|
227
425
|
const stubs = [];
|
|
228
426
|
const missing = [];
|
|
229
427
|
const expired = [];
|
|
428
|
+
const due = [];
|
|
429
|
+
const overdue = [];
|
|
230
430
|
let scanned = 0;
|
|
231
431
|
let unreadable = 0;
|
|
232
432
|
for (const r of kept) {
|
|
@@ -242,6 +442,11 @@ export async function buildMaintainReport(input, opts = {}) {
|
|
|
242
442
|
continue; // stubs are pointers — exempt from the freshness-stamp rule
|
|
243
443
|
}
|
|
244
444
|
const genre = classifyGenre({ title: r.title, body }).genre;
|
|
445
|
+
const dfr = dueForReviewOf(body, genre, now);
|
|
446
|
+
if (dfr !== null)
|
|
447
|
+
due.push({ path: r.path, locale: r.locale, ...dfr });
|
|
448
|
+
for (const oa of overdueActionsOf(body, now))
|
|
449
|
+
overdue.push({ path: r.path, locale: r.locale, ...oa });
|
|
245
450
|
if (!FRESHNESS_GENRES.includes(genre))
|
|
246
451
|
continue;
|
|
247
452
|
if (!STAMP_RE.test(body))
|
|
@@ -256,6 +461,15 @@ export async function buildMaintainReport(input, opts = {}) {
|
|
|
256
461
|
}
|
|
257
462
|
redirects = { available: true, count: stubs.length, stubs };
|
|
258
463
|
freshness = { scanned, unreadable, missingLastVerified: missing, expiredReviewBy: expired };
|
|
464
|
+
dueForReview = due.sort((a, b) => b.stampAge - a.stampAge || cmpStr(a.path, b.path) || cmpStr(a.locale, b.locale));
|
|
465
|
+
const repByPath = new Map();
|
|
466
|
+
const overdueSorted = overdue.sort((a, b) => cmpStr(a.path, b.path) || cmpStr(a.locale, b.locale));
|
|
467
|
+
for (const o of overdueSorted)
|
|
468
|
+
if (!repByPath.has(o.path))
|
|
469
|
+
repByPath.set(o.path, o.locale);
|
|
470
|
+
overdueActions = overdueSorted
|
|
471
|
+
.filter((o) => o.locale === repByPath.get(o.path))
|
|
472
|
+
.sort((a, b) => b.daysOverdue - a.daysOverdue || cmpStr(a.path, b.path));
|
|
259
473
|
}
|
|
260
474
|
return {
|
|
261
475
|
schema: MAINTAIN_SCHEMA,
|
|
@@ -278,6 +492,8 @@ export async function buildMaintainReport(input, opts = {}) {
|
|
|
278
492
|
redirects,
|
|
279
493
|
sections: sectionDist(kept),
|
|
280
494
|
freshness,
|
|
495
|
+
dueForReview,
|
|
496
|
+
overdueActions,
|
|
281
497
|
};
|
|
282
498
|
}
|
|
283
499
|
// --- renderMaintainMarkdown -----------------------------------------------------
|
|
@@ -350,6 +566,24 @@ export function renderMaintainMarkdown(r) {
|
|
|
350
566
|
for (const e of r.freshness.expiredReviewBy)
|
|
351
567
|
L.push(` - review overdue: \`${e.path}\` (${e.locale}) since ${e.reviewBy} (${fmt(e.daysExpired)}d)`);
|
|
352
568
|
}
|
|
569
|
+
if (r.dueForReview !== null) {
|
|
570
|
+
L.push('', `## 到期复核 Due for review(deep,advisory)`, '');
|
|
571
|
+
L.push(`- ${fmt(r.dueForReview.length)} 条 —仅提示,机器不代写;复核由人或复核协议执行`);
|
|
572
|
+
for (const d of r.dueForReview) {
|
|
573
|
+
const why = d.stampAge >= d.cadence
|
|
574
|
+
? `戳龄 ${fmt(d.stampAge)}d ≥ 周期 ${fmt(d.cadence)}d`
|
|
575
|
+
: `confessional stamp(自称未复跑),周期 ${fmt(d.cadence)}d 未到亦列`;
|
|
576
|
+
const cmds = d.verifyCommands.length > 0 ? ` · ${d.verifyCommands.map((c) => '`' + c + '`').join(' ')}` : '';
|
|
577
|
+
L.push(` - \`${d.locale}/${d.path}\` — ${why}${cmds}`);
|
|
578
|
+
}
|
|
579
|
+
}
|
|
580
|
+
if (r.overdueActions !== null) {
|
|
581
|
+
L.push('', '## 逾期行动项 Overdue action items(deep,advisory)', '');
|
|
582
|
+
L.push(`- ${fmt(r.overdueActions.length)} 条开着的行动项已过期限(孪生页按路径去重,en 优先)—仅提示,处置由人或复核协议执行`);
|
|
583
|
+
for (const o of r.overdueActions) {
|
|
584
|
+
L.push(` - \`${o.locale}/${o.path}\` — "${o.action}" 期限 ${o.due}(逾期 ${fmt(o.daysOverdue)}d,状态:${o.status})`);
|
|
585
|
+
}
|
|
586
|
+
}
|
|
353
587
|
L.push('', '## Machine-readable JSON', '', '```json', JSON.stringify(r, null, 2), '```', '');
|
|
354
588
|
return L.join('\n');
|
|
355
589
|
}
|
package/dist/migrate.js
CHANGED
|
@@ -39,8 +39,8 @@ const RULES = [
|
|
|
39
39
|
'R4 句长约束: zh sentences ≤20 chars; en sentences ≤25 words.',
|
|
40
40
|
'R5 表格判据: ≥3-field structured data → table; pairs → description list.',
|
|
41
41
|
'R6 来源列: comparison/timeline tables carry a source column.',
|
|
42
|
-
'R7
|
|
43
|
-
'R8
|
|
42
|
+
'R7 时间线四列: event timelines are exactly 时间|阶段|事件|来源.',
|
|
43
|
+
'R8 行动项八列: action items use the eight columns 措施|优先级|类型|负责人|期限|验证|跟踪|状态.',
|
|
44
44
|
];
|
|
45
45
|
export function reformatSystemFor(lang) {
|
|
46
46
|
return [
|
package/dist/surface.d.ts
CHANGED
|
@@ -11,7 +11,7 @@
|
|
|
11
11
|
* tier costs nothing beyond the map baseline, the deep tier reads every body
|
|
12
12
|
* once (caller pools the reads).
|
|
13
13
|
*/
|
|
14
|
-
import type
|
|
14
|
+
import { type MaintainRow } from './maintain.js';
|
|
15
15
|
import type { Locale } from './wiki/pages.read.js';
|
|
16
16
|
import type { NavSnapshot } from './wiki/nav.js';
|
|
17
17
|
export declare const SURFACE_SCHEMA: "historian.surface.v1";
|
package/dist/surface.js
CHANGED
|
@@ -14,6 +14,7 @@
|
|
|
14
14
|
import { isInternalPath } from './tools/shared.js';
|
|
15
15
|
import { lintBody } from './lint.js';
|
|
16
16
|
import { classifyGenre } from './templates/genres.js';
|
|
17
|
+
import { CONFESSIONAL_STAMP_RE, STAMP_LINE_RE } from './maintain.js';
|
|
17
18
|
export const SURFACE_SCHEMA = 'historian.surface.v1';
|
|
18
19
|
const MACHINE_SEG_RE = /^_/;
|
|
19
20
|
// nav targets carry a leading slash and may pre-pend the locale segment
|
|
@@ -111,6 +112,13 @@ function resolveTargetPath(baseUrl, rawHref) {
|
|
|
111
112
|
return { path: t.slice(3), locale: 'en' };
|
|
112
113
|
return { path: t, locale: 'en' };
|
|
113
114
|
}
|
|
115
|
+
/** True when EVERY stamp-bearing line confesses non-execution — see the
|
|
116
|
+
* ledgerClaims rule in buildDeep. Lines are the unit of judgement because a
|
|
117
|
+
* struck old stamp beside a fresh honest one must keep the exemption. */
|
|
118
|
+
function isConfessionalStamp(body) {
|
|
119
|
+
const stampLines = body.split('\n').filter((l) => STAMP_LINE_RE.test(l));
|
|
120
|
+
return stampLines.length > 0 && stampLines.every((l) => CONFESSIONAL_STAMP_RE.test(l));
|
|
121
|
+
}
|
|
114
122
|
async function scanBodies(input) {
|
|
115
123
|
if (input.readBody === undefined)
|
|
116
124
|
return [];
|
|
@@ -252,7 +260,13 @@ function buildDeep(input, scans) {
|
|
|
252
260
|
.map((s) => ({ path: s.row.path, cjkRatio: Number(s.lint.cjkRatio.toFixed(3)) }));
|
|
253
261
|
const ledgerClaims = [];
|
|
254
262
|
for (const s of ok) {
|
|
255
|
-
|
|
263
|
+
// Stamp honesty (swarm-A P2): a stamp that only ever confesses the review
|
|
264
|
+
// never ran ("…(content not re-run)"/未复跑/未复核/baseline) is not evidence —
|
|
265
|
+
// claiming review without execution must not suppress the claim ledger.
|
|
266
|
+
// Any single non-confessional stamp line (incl. supersede-keeping-struck-old)
|
|
267
|
+
// exempts exactly as before.
|
|
268
|
+
const exempt = s.lint.hasStamp && !isConfessionalStamp(s.body);
|
|
269
|
+
if (s.lint.isRedirectStub || !isFrontPath(s.row.path) || exempt)
|
|
256
270
|
continue;
|
|
257
271
|
const genre = classifyGenre({ title: s.row.title, body: s.body }).genre;
|
|
258
272
|
if (!(genre === 'G4' || genre === 'G5' || genre === 'G6'))
|
package/dist/templates/genres.js
CHANGED
|
@@ -188,7 +188,7 @@ export function selfReviewChecklist(genre) {
|
|
|
188
188
|
const items = [
|
|
189
189
|
{
|
|
190
190
|
id: 1,
|
|
191
|
-
label: '导言占比 10–15
|
|
191
|
+
label: '导言占比 10–15% 且 3–5 句:导言 ≈ 正文的 10–15%,每个重要小节在导言至少占一句(lead ≈10–15% of body, 3–5 sentences; every major section ≥1 sentence in lead)',
|
|
192
192
|
kind: 'content',
|
|
193
193
|
appliesTo: 'all',
|
|
194
194
|
},
|
|
@@ -212,13 +212,13 @@ export function selfReviewChecklist(genre) {
|
|
|
212
212
|
},
|
|
213
213
|
{
|
|
214
214
|
id: 5,
|
|
215
|
-
label: '
|
|
215
|
+
label: '时间线每行有阶段与来源列(触发/影响/发现/缓解/恢复),仅日志可证事实(timeline rows carry phase + source columns; log-verifiable facts only)',
|
|
216
216
|
kind: 'genre-specific',
|
|
217
217
|
appliesTo: ['G1'],
|
|
218
218
|
},
|
|
219
219
|
{
|
|
220
220
|
id: 6,
|
|
221
|
-
label: '
|
|
221
|
+
label: '行动项八列 = 措施|优先级|类型|负责人|期限|验证|跟踪|状态;元数据表带复核期限(action items: eight columns with priority + tracking; metadata carries review-by)',
|
|
222
222
|
kind: 'genre-specific',
|
|
223
223
|
appliesTo: ['G1'],
|
|
224
224
|
},
|
|
@@ -44,7 +44,10 @@ export const G1_ZH = `# 页面标题(占位:写完后替换为实际标题
|
|
|
44
44
|
| --- | --- |
|
|
45
45
|
| 影响范围 | <!-- 哪些服务/用户/区域受影响 --> |
|
|
46
46
|
| 持续时间 | <!-- 起止时间,如 2026-09-01 14:02–15:47 (UTC+8) --> |
|
|
47
|
+
| 关键时间 | <!-- 影响开始 → 被发现 → 被缓解 → 已恢复(UTC);发现延迟=被发现−影响开始 --> |
|
|
48
|
+
| 发现方式 | <!-- 告警/人工/日志回放:谁、何时、如何发现 --> |
|
|
47
49
|
| 严重度 | <!-- P0/P1/P2(或 S1–S4),并写明判定依据 --> |
|
|
50
|
+
| 复核期限 | YYYY-MM-DD <!-- 行动项回查日期;到期页进入 maintain 深扫队列 --> |
|
|
48
51
|
|
|
49
52
|
## 背景
|
|
50
53
|
|
|
@@ -52,11 +55,11 @@ export const G1_ZH = `# 页面标题(占位:写完后替换为实际标题
|
|
|
52
55
|
|
|
53
56
|
## 时间线
|
|
54
57
|
|
|
55
|
-
<!-- 只记可查证事实:以日志/告警为准,不以口述为准;相邻事件 ≠
|
|
58
|
+
<!-- 只记可查证事实:以日志/告警为准,不以口述为准;相邻事件 ≠ 因果关系。每行必须填阶段与来源列;阶段取词:触发/影响/发现/缓解/恢复。 -->
|
|
56
59
|
|
|
57
|
-
| 时间 | 事件 | 来源 |
|
|
58
|
-
| --- | --- | --- |
|
|
59
|
-
| YYYY-MM-DD HH:MM | <!-- 发生了什么 --> | <!-- 告警/日志/commit 链接 --> |
|
|
60
|
+
| 时间 | 阶段 | 事件 | 来源 |
|
|
61
|
+
| --- | --- | --- | --- |
|
|
62
|
+
| YYYY-MM-DD HH:MM | <!-- 阶段 --> | <!-- 发生了什么 --> | <!-- 告警/日志/commit 链接 --> |
|
|
60
63
|
|
|
61
64
|
## 量化影响
|
|
62
65
|
|
|
@@ -75,6 +78,8 @@ export const G1_ZH = `# 页面标题(占位:写完后替换为实际标题
|
|
|
75
78
|
4. Why: <!-- 第 4 层 -->
|
|
76
79
|
5. Why: <!-- 第 5 层:收敛到根本原因 -->
|
|
77
80
|
|
|
81
|
+
**复发检查**:<!-- 检索既往事件页:同根因/同触发面是否发生过?有则链接前例;首次则明示"未见前例"。 -->
|
|
82
|
+
|
|
78
83
|
## 处置
|
|
79
84
|
|
|
80
85
|
| 类别 | 措施 | 完成时间 |
|
|
@@ -84,11 +89,11 @@ export const G1_ZH = `# 页面标题(占位:写完后替换为实际标题
|
|
|
84
89
|
|
|
85
90
|
## 行动项
|
|
86
91
|
|
|
87
|
-
| 措施 | 类型 | 负责人 | 期限 | 验证 | 状态 |
|
|
88
|
-
| --- | --- | --- | --- | --- | --- |
|
|
89
|
-
| <!-- 做什么 --> | <!-- prevent/mitigate/process --> | <!-- 负责人 --> | YYYY-MM-DD | <!-- 如何证明已完成 --> | <!-- 待办/进行中/已完成 --> |
|
|
92
|
+
| 措施 | 优先级 | 类型 | 负责人 | 期限 | 验证 | 跟踪 | 状态 |
|
|
93
|
+
| --- | --- | --- | --- | --- | --- | --- | --- |
|
|
94
|
+
| <!-- 做什么 --> | <!-- P0/P1/P2 --> | <!-- prevent/mitigate/process --> | <!-- 负责人 --> | YYYY-MM-DD | <!-- 如何证明已完成 --> | <!-- issue/页面路径,无则 — --> | <!-- 待办/进行中/已完成 --> |
|
|
90
95
|
|
|
91
|
-
<!-- 每个根因主题至少一个 prevent
|
|
96
|
+
<!-- 每个根因主题至少一个 prevent 行动项;验证列必须可检查,否则行动项不算完成;期限列必须 ISO 日期,未定先定日期再入表(TBD 项对老化清扫永久隐形);逾期的开项由 maintain 深扫点名。 -->
|
|
92
97
|
|
|
93
98
|
## 教训
|
|
94
99
|
|
|
@@ -135,7 +140,10 @@ export const G1_EN = `# Page Title (placeholder: replace with the real title, mu
|
|
|
135
140
|
| --- | --- |
|
|
136
141
|
| Blast radius | <!-- services/users/regions affected --> |
|
|
137
142
|
| Duration | <!-- start–end, e.g. 2026-09-01 14:02–15:47 (UTC+8) --> |
|
|
143
|
+
| Key timestamps | <!-- impact start → detected → mitigated → recovered (UTC); detection lag = detected − start --> |
|
|
144
|
+
| Detected by | <!-- alert / human / log replay: who, when, how --> |
|
|
138
145
|
| Severity | <!-- P0/P1/P2 (or S1–S4) with the basis for the rating --> |
|
|
146
|
+
| Review-by | YYYY-MM-DD <!-- action-item sweep date; expired pages enter the maintain deep queue --> |
|
|
139
147
|
|
|
140
148
|
## Background
|
|
141
149
|
|
|
@@ -143,11 +151,11 @@ export const G1_EN = `# Page Title (placeholder: replace with the real title, mu
|
|
|
143
151
|
|
|
144
152
|
## Timeline
|
|
145
153
|
|
|
146
|
-
<!-- Verifiable facts only: log/alert-based, not memory-based; adjacent events ≠ causation. Every row
|
|
154
|
+
<!-- Verifiable facts only: log/alert-based, not memory-based; adjacent events ≠ causation. Every row fills the phase and source columns; phase vocabulary: trigger/impact/detection/mitigation/recovery. -->
|
|
147
155
|
|
|
148
|
-
| Time | Event | Source |
|
|
149
|
-
| --- | --- | --- |
|
|
150
|
-
| YYYY-MM-DD HH:MM | <!-- what happened --> | <!-- alert/log/commit link --> |
|
|
156
|
+
| Time | Phase | Event | Source |
|
|
157
|
+
| --- | --- | --- | --- |
|
|
158
|
+
| YYYY-MM-DD HH:MM | <!-- phase --> | <!-- what happened --> | <!-- alert/log/commit link --> |
|
|
151
159
|
|
|
152
160
|
## Quantified Impact
|
|
153
161
|
|
|
@@ -166,6 +174,8 @@ export const G1_EN = `# Page Title (placeholder: replace with the real title, mu
|
|
|
166
174
|
4. Why: <!-- layer 4 -->
|
|
167
175
|
5. Why: <!-- layer 5: converges on the root cause -->
|
|
168
176
|
|
|
177
|
+
**Recurrence check**: <!-- search prior incident pages: same root cause or trigger before? Link the precedent; if first seen, say so. -->
|
|
178
|
+
|
|
169
179
|
## Remediation
|
|
170
180
|
|
|
171
181
|
| Kind | Action | Done |
|
|
@@ -175,11 +185,11 @@ export const G1_EN = `# Page Title (placeholder: replace with the real title, mu
|
|
|
175
185
|
|
|
176
186
|
## Action Items
|
|
177
187
|
|
|
178
|
-
| Action | Type | Owner | Due | Verification | Status |
|
|
179
|
-
| --- | --- | --- | --- | --- | --- |
|
|
180
|
-
| <!-- what to do --> | <!-- prevent/mitigate/process --> | <!-- owner --> | YYYY-MM-DD | <!-- how to prove it is done --> | <!-- todo/in progress/done --> |
|
|
188
|
+
| Action | Priority | Type | Owner | Due | Verification | Tracking | Status |
|
|
189
|
+
| --- | --- | --- | --- | --- | --- | --- | --- |
|
|
190
|
+
| <!-- what to do --> | <!-- P0/P1/P2 --> | <!-- prevent/mitigate/process --> | <!-- owner --> | YYYY-MM-DD | <!-- how to prove it is done --> | <!-- issue/page link, or — --> | <!-- todo/in progress/done --> |
|
|
181
191
|
|
|
182
|
-
<!-- At least one prevent item per root-cause theme; an action item without a checkable verification is not done. -->
|
|
192
|
+
<!-- At least one prevent item per root-cause theme; an action item without a checkable verification is not done; the Due column must carry an ISO date — set a date before entering the table (TBD rows are permanently invisible to the ageing sweep); open items past due are named by the maintain deep sweep. -->
|
|
183
193
|
|
|
184
194
|
## Lessons
|
|
185
195
|
|
|
@@ -599,7 +609,7 @@ export const G6_ZH = `# 如何做某事(占位:目标句式标题,须与
|
|
|
599
609
|
|
|
600
610
|
| 元数据 | 值 |
|
|
601
611
|
| --- | --- |
|
|
602
|
-
| 状态 | <!--
|
|
612
|
+
| 状态 | draft <!-- 必须与顶部 状态/Status 头同 token;改状态时两处一起改 --> |
|
|
603
613
|
| 上次核实 | <!-- YYYY-MM-DD,在哪套环境按本页步骤重跑过 --> |
|
|
604
614
|
| 复核周期 | <!-- 如每 90 天,到期重跑本页步骤 --> |
|
|
605
615
|
| 被取代于 | <!-- 新手册路径,无则填 — --> |
|
|
@@ -648,7 +658,7 @@ export const G6_EN = `# How to Do X (placeholder: goal-titled heading, must matc
|
|
|
648
658
|
|
|
649
659
|
| Field | Value |
|
|
650
660
|
| --- | --- |
|
|
651
|
-
| Status | <!--
|
|
661
|
+
| Status | draft <!-- must carry the SAME token as the 状态/Status header above; change both together --> |
|
|
652
662
|
| Last verified | <!-- YYYY-MM-DD and the environment the steps were re-run in --> |
|
|
653
663
|
| Review by | <!-- e.g. every 90 days; re-run the steps when due --> |
|
|
654
664
|
| Superseded by | <!-- path of the newer manual, or — --> |
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* historian_anchor — seal a human order/approval from the engine session store
|
|
3
|
+
* into an _evidence/anchors wiki page, and verify a sealed anchor later.
|
|
4
|
+
* Core logic (store reads, hashing, verdicts) lives in ../anchor.ts; this
|
|
5
|
+
* wrapper only adds the wiki persistence leg. Evidence tier ⇒ monolingual en,
|
|
6
|
+
* unpublished-friendly, per the G1 appendix contract.
|
|
7
|
+
*/
|
|
8
|
+
import { type ToolDefinition } from '@opencode-ai/plugin';
|
|
9
|
+
import { type ToolDeps } from './shared.js';
|
|
10
|
+
export declare function makeAnchorTool(deps: ToolDeps): ToolDefinition;
|
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* historian_anchor — seal a human order/approval from the engine session store
|
|
3
|
+
* into an _evidence/anchors wiki page, and verify a sealed anchor later.
|
|
4
|
+
* Core logic (store reads, hashing, verdicts) lives in ../anchor.ts; this
|
|
5
|
+
* wrapper only adds the wiki persistence leg. Evidence tier ⇒ monolingual en,
|
|
6
|
+
* unpublished-friendly, per the G1 appendix contract.
|
|
7
|
+
*/
|
|
8
|
+
import { tool } from '@opencode-ai/plugin';
|
|
9
|
+
import { readPage } from '../wiki/pages.read.js';
|
|
10
|
+
import { createPage } from '../wiki/pages.write.js';
|
|
11
|
+
import { errEnvelope, okJson, pageDeps, URL_MANDATE } from './shared.js';
|
|
12
|
+
import { defaultDbPath, renderSealPage, sealAnchor, verifyAnchor } from '../anchor.js';
|
|
13
|
+
const s = tool.schema;
|
|
14
|
+
const ARGS = {
|
|
15
|
+
action: s.enum(['seal', 'verify']),
|
|
16
|
+
slug: s.string().optional().describe('Evidence page name under _evidence/anchors/<slug> (default: canon-sha prefix).'),
|
|
17
|
+
session_id: s.string().optional().describe('Engine session id (ses_...).'),
|
|
18
|
+
session_title: s.string().optional().describe('Unique substring of the session title when the id is unknown.'),
|
|
19
|
+
index: s.number().int().optional().describe("Message ordinal — 1-based (matches receipt ordinal); negative counts from the end."),
|
|
20
|
+
body: s.string().optional().describe('Claimed exact body text — located by unique canonical match; repeated bodies come back body-ambiguous on purpose.'),
|
|
21
|
+
label: s.string().optional().describe('Free-form label for the seal page heading.'),
|
|
22
|
+
};
|
|
23
|
+
function extractReceipt(content) {
|
|
24
|
+
const m = content.match(/```json historian-anchor\n([\s\S]*?)\n```/);
|
|
25
|
+
if (m === null)
|
|
26
|
+
return undefined;
|
|
27
|
+
try {
|
|
28
|
+
return JSON.parse(m[1]);
|
|
29
|
+
}
|
|
30
|
+
catch {
|
|
31
|
+
return undefined;
|
|
32
|
+
}
|
|
33
|
+
}
|
|
34
|
+
export function makeAnchorTool(deps) {
|
|
35
|
+
return tool({
|
|
36
|
+
description: 'Historian anchor (g12b-3 in the memory seat): action:"seal" locates a human order/approval message in the engine session store ' +
|
|
37
|
+
'(by session_id/session_title + index or unique body match), hashes it (raw + canonical, closed normalization list) and writes an ' +
|
|
38
|
+
'_evidence/anchors/<slug> receipt page; action:"verify" re-reads the store against a sealed page and returns MATCH/MISMATCH/ABSENT with drift fields. ' +
|
|
39
|
+
'Read-only against the store; the wiki page is the durable receipt. ' + URL_MANDATE,
|
|
40
|
+
args: ARGS,
|
|
41
|
+
execute: async (raw) => {
|
|
42
|
+
const a = raw;
|
|
43
|
+
const dbPath = defaultDbPath(deps.homeDir);
|
|
44
|
+
const now = new Date().toISOString();
|
|
45
|
+
const pd = pageDeps(deps);
|
|
46
|
+
try {
|
|
47
|
+
if (a.action === 'seal') {
|
|
48
|
+
const r = sealAnchor({
|
|
49
|
+
dbPath,
|
|
50
|
+
sessionId: a.session_id,
|
|
51
|
+
sessionTitle: a.session_title,
|
|
52
|
+
index: a.index,
|
|
53
|
+
body: a.body,
|
|
54
|
+
now,
|
|
55
|
+
});
|
|
56
|
+
if ('ok' in r)
|
|
57
|
+
return errEnvelope(new Error(`anchor: ${r.error}${r.detail !== undefined ? ` — ${r.detail}` : ''}`));
|
|
58
|
+
const slug = a.slug ?? r.canon_sha256.slice(0, 12);
|
|
59
|
+
const path = `_evidence/anchors/${slug}`;
|
|
60
|
+
const created = await createPage(pd, {
|
|
61
|
+
path,
|
|
62
|
+
locale: 'en',
|
|
63
|
+
title: `Anchor seal ${slug}${a.label !== undefined ? ` — ${a.label}` : ''}`,
|
|
64
|
+
content: renderSealPage(r, a.label),
|
|
65
|
+
tags: ['anchor-seal', 'g12b-3'],
|
|
66
|
+
isPublished: true,
|
|
67
|
+
twin: false,
|
|
68
|
+
});
|
|
69
|
+
return okJson({ verdict: 'SEALED', slug, receipt: r, page: { path, pageId: created.pageId } });
|
|
70
|
+
}
|
|
71
|
+
// verify
|
|
72
|
+
if (a.slug === undefined)
|
|
73
|
+
return errEnvelope(new Error('anchor: verify needs the sealed slug'));
|
|
74
|
+
const page = await readPage(pd.client, `_evidence/anchors/${a.slug}`, 'en');
|
|
75
|
+
if (page === null)
|
|
76
|
+
return errEnvelope(new Error(`anchor: seal page absent — ${a.slug}`));
|
|
77
|
+
const stored = extractReceipt(page.content);
|
|
78
|
+
if (stored === undefined)
|
|
79
|
+
return errEnvelope(new Error(`anchor: seal page unparseable — ${a.slug}`));
|
|
80
|
+
const v = verifyAnchor(stored, { dbPath, now });
|
|
81
|
+
if ('ok' in v)
|
|
82
|
+
return errEnvelope(new Error(`anchor: ${v.error}${v.detail !== undefined ? ` — ${v.detail}` : ''}`));
|
|
83
|
+
return okJson({ verdict: v.verdict, drift: v.drift, stored: v.stored, current: v.current ?? null, page: { path: `_evidence/anchors/${a.slug}` } });
|
|
84
|
+
}
|
|
85
|
+
catch (e) {
|
|
86
|
+
return errEnvelope(e instanceof Error ? e : new Error(String(e).slice(0, 300)));
|
|
87
|
+
}
|
|
88
|
+
},
|
|
89
|
+
});
|
|
90
|
+
}
|