daftari 1.32.0 → 3.0.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 (200) hide show
  1. package/CHANGELOG.md +123 -1
  2. package/README.md +472 -342
  3. package/dist/access/rbac.d.ts +1 -0
  4. package/dist/access/rbac.d.ts.map +1 -1
  5. package/dist/access/rbac.js +16 -0
  6. package/dist/access/rbac.js.map +1 -1
  7. package/dist/asof/index.d.ts.map +1 -1
  8. package/dist/asof/index.js +23 -2
  9. package/dist/asof/index.js.map +1 -1
  10. package/dist/asof/report.d.ts.map +1 -1
  11. package/dist/asof/report.js +24 -0
  12. package/dist/asof/report.js.map +1 -1
  13. package/dist/asof/snapshot.d.ts +7 -1
  14. package/dist/asof/snapshot.d.ts.map +1 -1
  15. package/dist/asof/snapshot.js +28 -1
  16. package/dist/asof/snapshot.js.map +1 -1
  17. package/dist/backfill/derive.d.ts.map +1 -1
  18. package/dist/backfill/derive.js +8 -0
  19. package/dist/backfill/derive.js.map +1 -1
  20. package/dist/canary/fixtures.d.ts +12 -0
  21. package/dist/canary/fixtures.d.ts.map +1 -0
  22. package/dist/canary/fixtures.js +132 -0
  23. package/dist/canary/fixtures.js.map +1 -0
  24. package/dist/canary/index.d.ts +16 -0
  25. package/dist/canary/index.d.ts.map +1 -0
  26. package/dist/canary/index.js +105 -0
  27. package/dist/canary/index.js.map +1 -0
  28. package/dist/canary/run.d.ts +39 -0
  29. package/dist/canary/run.d.ts.map +1 -0
  30. package/dist/canary/run.js +266 -0
  31. package/dist/canary/run.js.map +1 -0
  32. package/dist/canary/stats.d.ts +36 -0
  33. package/dist/canary/stats.d.ts.map +1 -0
  34. package/dist/canary/stats.js +143 -0
  35. package/dist/canary/stats.js.map +1 -0
  36. package/dist/canon/index.d.ts +15 -0
  37. package/dist/canon/index.d.ts.map +1 -0
  38. package/dist/canon/index.js +167 -0
  39. package/dist/canon/index.js.map +1 -0
  40. package/dist/canon/resolve.d.ts +12 -0
  41. package/dist/canon/resolve.d.ts.map +1 -0
  42. package/dist/canon/resolve.js +67 -0
  43. package/dist/canon/resolve.js.map +1 -0
  44. package/dist/canon/topic.d.ts +20 -0
  45. package/dist/canon/topic.d.ts.map +1 -0
  46. package/dist/canon/topic.js +81 -0
  47. package/dist/canon/topic.js.map +1 -0
  48. package/dist/canon/types.d.ts +37 -0
  49. package/dist/canon/types.d.ts.map +1 -0
  50. package/dist/canon/types.js +9 -0
  51. package/dist/canon/types.js.map +1 -0
  52. package/dist/cli.d.ts.map +1 -1
  53. package/dist/cli.js +6 -0
  54. package/dist/cli.js.map +1 -1
  55. package/dist/court/index.d.ts.map +1 -1
  56. package/dist/court/index.js +48 -0
  57. package/dist/court/index.js.map +1 -1
  58. package/dist/court/triage.d.ts +5 -0
  59. package/dist/court/triage.d.ts.map +1 -0
  60. package/dist/court/triage.js +71 -0
  61. package/dist/court/triage.js.map +1 -0
  62. package/dist/curation/lint-voice.d.ts +3 -0
  63. package/dist/curation/lint-voice.d.ts.map +1 -0
  64. package/dist/curation/lint-voice.js +87 -0
  65. package/dist/curation/lint-voice.js.map +1 -0
  66. package/dist/curation/lint.d.ts +5 -1
  67. package/dist/curation/lint.d.ts.map +1 -1
  68. package/dist/curation/lint.js +41 -5
  69. package/dist/curation/lint.js.map +1 -1
  70. package/dist/curation/read-heat.d.ts +16 -0
  71. package/dist/curation/read-heat.d.ts.map +1 -0
  72. package/dist/curation/read-heat.js +52 -0
  73. package/dist/curation/read-heat.js.map +1 -0
  74. package/dist/curation/structural.d.ts +1 -1
  75. package/dist/curation/structural.d.ts.map +1 -1
  76. package/dist/curation/structural.js +8 -7
  77. package/dist/curation/structural.js.map +1 -1
  78. package/dist/curation/tension-triage.d.ts +57 -0
  79. package/dist/curation/tension-triage.d.ts.map +1 -0
  80. package/dist/curation/tension-triage.js +155 -0
  81. package/dist/curation/tension-triage.js.map +1 -0
  82. package/dist/curation/validity.d.ts +20 -0
  83. package/dist/curation/validity.d.ts.map +1 -0
  84. package/dist/curation/validity.js +191 -0
  85. package/dist/curation/validity.js.map +1 -0
  86. package/dist/fence/detect.d.ts +10 -0
  87. package/dist/fence/detect.d.ts.map +1 -0
  88. package/dist/fence/detect.js +161 -0
  89. package/dist/fence/detect.js.map +1 -0
  90. package/dist/fence/index.d.ts +22 -0
  91. package/dist/fence/index.d.ts.map +1 -0
  92. package/dist/fence/index.js +117 -0
  93. package/dist/fence/index.js.map +1 -0
  94. package/dist/frontmatter/schema.d.ts.map +1 -1
  95. package/dist/frontmatter/schema.js +28 -1
  96. package/dist/frontmatter/schema.js.map +1 -1
  97. package/dist/frontmatter/types.d.ts +6 -1
  98. package/dist/frontmatter/types.d.ts.map +1 -1
  99. package/dist/frontmatter/types.js +8 -0
  100. package/dist/frontmatter/types.js.map +1 -1
  101. package/dist/holders/registry.d.ts +8 -0
  102. package/dist/holders/registry.d.ts.map +1 -0
  103. package/dist/holders/registry.js +18 -0
  104. package/dist/holders/registry.js.map +1 -0
  105. package/dist/holders/types.d.ts +10 -0
  106. package/dist/holders/types.d.ts.map +1 -0
  107. package/dist/holders/types.js +2 -0
  108. package/dist/holders/types.js.map +1 -0
  109. package/dist/index.d.ts.map +1 -1
  110. package/dist/index.js +10 -6
  111. package/dist/index.js.map +1 -1
  112. package/dist/interview/questions.d.ts.map +1 -1
  113. package/dist/interview/questions.js +41 -9
  114. package/dist/interview/questions.js.map +1 -1
  115. package/dist/resources.d.ts +27 -0
  116. package/dist/resources.d.ts.map +1 -0
  117. package/dist/resources.js +169 -0
  118. package/dist/resources.js.map +1 -0
  119. package/dist/search/current-source.d.ts +1 -0
  120. package/dist/search/current-source.d.ts.map +1 -1
  121. package/dist/search/current-source.js +3 -1
  122. package/dist/search/current-source.js.map +1 -1
  123. package/dist/search/hybrid.d.ts +6 -1
  124. package/dist/search/hybrid.d.ts.map +1 -1
  125. package/dist/search/hybrid.js +23 -4
  126. package/dist/search/hybrid.js.map +1 -1
  127. package/dist/search/reindex.d.ts.map +1 -1
  128. package/dist/search/reindex.js +48 -13
  129. package/dist/search/reindex.js.map +1 -1
  130. package/dist/search/valid-at-source.d.ts +25 -0
  131. package/dist/search/valid-at-source.d.ts.map +1 -0
  132. package/dist/search/valid-at-source.js +131 -0
  133. package/dist/search/valid-at-source.js.map +1 -0
  134. package/dist/serve/index.d.ts.map +1 -1
  135. package/dist/serve/index.js +58 -89
  136. package/dist/serve/index.js.map +1 -1
  137. package/dist/server.d.ts +3 -1
  138. package/dist/server.d.ts.map +1 -1
  139. package/dist/server.js +159 -11
  140. package/dist/server.js.map +1 -1
  141. package/dist/sleep/cycle.d.ts.map +1 -1
  142. package/dist/sleep/cycle.js +38 -6
  143. package/dist/sleep/cycle.js.map +1 -1
  144. package/dist/storage/index-db.d.ts +7 -1
  145. package/dist/storage/index-db.d.ts.map +1 -1
  146. package/dist/storage/index-db.js +133 -8
  147. package/dist/storage/index-db.js.map +1 -1
  148. package/dist/tools/canon.d.ts +3 -0
  149. package/dist/tools/canon.d.ts.map +1 -0
  150. package/dist/tools/canon.js +177 -0
  151. package/dist/tools/canon.js.map +1 -0
  152. package/dist/tools/consumes.d.ts.map +1 -1
  153. package/dist/tools/consumes.js +47 -1
  154. package/dist/tools/consumes.js.map +1 -1
  155. package/dist/tools/curation.d.ts +4 -0
  156. package/dist/tools/curation.d.ts.map +1 -1
  157. package/dist/tools/curation.js +647 -3
  158. package/dist/tools/curation.js.map +1 -1
  159. package/dist/tools/edge-staleness.d.ts.map +1 -1
  160. package/dist/tools/edge-staleness.js +115 -0
  161. package/dist/tools/edge-staleness.js.map +1 -1
  162. package/dist/tools/edges.d.ts.map +1 -1
  163. package/dist/tools/edges.js +94 -0
  164. package/dist/tools/edges.js.map +1 -1
  165. package/dist/tools/read.d.ts +14 -0
  166. package/dist/tools/read.d.ts.map +1 -1
  167. package/dist/tools/read.js +385 -6
  168. package/dist/tools/read.js.map +1 -1
  169. package/dist/tools/receipt.d.ts +1 -1
  170. package/dist/tools/receipt.d.ts.map +1 -1
  171. package/dist/tools/receipt.js +147 -2
  172. package/dist/tools/receipt.js.map +1 -1
  173. package/dist/tools/search.d.ts.map +1 -1
  174. package/dist/tools/search.js +456 -5
  175. package/dist/tools/search.js.map +1 -1
  176. package/dist/tools/staged-actions.d.ts +7 -0
  177. package/dist/tools/staged-actions.d.ts.map +1 -1
  178. package/dist/tools/staged-actions.js +106 -2
  179. package/dist/tools/staged-actions.js.map +1 -1
  180. package/dist/tools/themes.d.ts.map +1 -1
  181. package/dist/tools/themes.js +120 -0
  182. package/dist/tools/themes.js.map +1 -1
  183. package/dist/tools/tier1.d.ts.map +1 -1
  184. package/dist/tools/tier1.js +56 -0
  185. package/dist/tools/tier1.js.map +1 -1
  186. package/dist/tools/tier2.d.ts.map +1 -1
  187. package/dist/tools/tier2.js +111 -1
  188. package/dist/tools/tier2.js.map +1 -1
  189. package/dist/tools/witness.d.ts.map +1 -1
  190. package/dist/tools/witness.js +93 -0
  191. package/dist/tools/witness.js.map +1 -1
  192. package/dist/tools/write.d.ts +8 -0
  193. package/dist/tools/write.d.ts.map +1 -1
  194. package/dist/tools/write.js +391 -3
  195. package/dist/tools/write.js.map +1 -1
  196. package/dist/utils/config.d.ts +2 -0
  197. package/dist/utils/config.d.ts.map +1 -1
  198. package/dist/utils/config.js +74 -0
  199. package/dist/utils/config.js.map +1 -1
  200. package/package.json +5 -2
@@ -10,16 +10,19 @@
10
10
  // write-path tools.
11
11
  import { canRatify, canRead, hasAnyRead } from "../access/rbac.js";
12
12
  import { CONSOLIDATE_AGENT } from "../consolidate/constants.js";
13
- import { LINT_CHECKS, runLint, } from "../curation/lint.js";
13
+ import { clip, LINT_CHECKS, LINT_SUMMARY_DETAIL_CHARS, LINT_SUMMARY_TOP_FINDINGS, runLint, TIER0_LINT_CHECKS, } from "../curation/lint.js";
14
+ import { renderLedgerKeeper } from "../curation/lint-voice.js";
14
15
  import { readProvenanceLog } from "../curation/provenance.js";
15
- import { sweepExpiredActions } from "../curation/staged-actions.js";
16
- import { addTension, LOGGABLE_TENSION_KINDS, listTensions, RESOLUTION_KINDS, resolveTension, } from "../curation/tension.js";
16
+ import { STAGED_ACTION_TYPES, sweepExpiredActions } from "../curation/staged-actions.js";
17
+ import { addTension, LOGGABLE_TENSION_KINDS, listTensions, RESOLUTION_KINDS, resolveTension, TENSION_KINDS, } from "../curation/tension.js";
17
18
  import { canSeeTension, sourceReadable, visibleTensions } from "../curation/tension-access.js";
18
19
  import { bucketHiddenDownstream, computeTensionBlast, } from "../curation/tension-blast.js";
19
20
  import { loadTensionClusters } from "../curation/tension-clusters.js";
21
+ import { loadTensionTriage } from "../curation/tension-triage.js";
20
22
  import { parseDocument } from "../frontmatter/parser.js";
21
23
  import { err, ok } from "../frontmatter/types.js";
22
24
  import { readFile, resolveVaultPath } from "../storage/local.js";
25
+ import { loadConfig } from "../utils/config.js";
23
26
  import { openIndexForAccessOrNull } from "./search.js";
24
27
  // Curation tools are open to any role with at least one read grant. A guest
25
28
  // (or any role with no read access) is denied.
@@ -278,6 +281,34 @@ export async function vaultTensionBlast(vaultRoot, args, access) {
278
281
  db?.close();
279
282
  }
280
283
  }
284
+ // ---------------------------------------------------------------------------
285
+ // vault_tension_triage
286
+ // ---------------------------------------------------------------------------
287
+ // The Tension Triage Card (v0): composes the LIVE tensions into a
288
+ // human-legible, cluster-grouped queue — each tension annotated with its
289
+ // blast and, per contested side, tier, confidence, and read-heat. Read-only,
290
+ // and deliberately computes NO composite severity score: ranking is the
291
+ // curator's job in v0 (legibility before automation).
292
+ //
293
+ // RBAC v0: the injected visibleTensions filter scopes which tensions appear;
294
+ // blast is the loader's count and hidden_downstream stays "none". The
295
+ // per-tension #217 kept/hidden recompute that vault_tension_blast performs is
296
+ // intentionally NOT replicated here — the triage card surfaces a coarse blast
297
+ // magnitude for legibility, not the full downstream list, so the exact-count
298
+ // disclosure the recompute guards against does not apply. (If parity is later
299
+ // wanted, filter the loaded docs to readable ones before blast.)
300
+ export async function vaultTensionTriage(vaultRoot, _args = {}, access) {
301
+ const allowed = requireReadAccess("vault_tension_triage", access);
302
+ if (!allowed.ok)
303
+ return allowed;
304
+ const db = access ? openIndexForAccessOrNull(vaultRoot) : null;
305
+ try {
306
+ return await loadTensionTriage(vaultRoot, new Date(), (entries) => visibleTensions(db, entries, access));
307
+ }
308
+ finally {
309
+ db?.close();
310
+ }
311
+ }
281
312
  export async function vaultLint(vaultRoot, args = {}, access) {
282
313
  const allowed = requireReadAccess("vault_lint", access);
283
314
  if (!allowed.ok)
@@ -382,6 +413,585 @@ export async function vaultProvenance(vaultRoot, args, access) {
382
413
  return ok({ path: filePath, count: history.length, history });
383
414
  }
384
415
  // ---------------------------------------------------------------------------
416
+ // Output schemas (spec 2026-07-26, Decision 3)
417
+ // ---------------------------------------------------------------------------
418
+ //
419
+ // JSON Schema 2020-12 for each handler's ok-value, derived from the return
420
+ // types above. Closed vocabularies reuse the source-of-truth constants so a
421
+ // rename there breaks this build instead of silently drifting the schema.
422
+ // Where a structure is open by construction — a free-form counts map, a
423
+ // verbatim frontmatter diff — the schema stays permissive rather than
424
+ // promising a shape the handler never guarantees.
425
+ // { key: integer } over a fixed vocabulary (byKind, byResolutionKind, ...).
426
+ function countsByKey(keys) {
427
+ const properties = {};
428
+ for (const key of keys)
429
+ properties[key] = { type: "integer" };
430
+ return { type: "object", properties, required: [...keys], additionalProperties: false };
431
+ }
432
+ const tensionResolutionSchema = {
433
+ type: "object",
434
+ properties: {
435
+ resolved_at: { type: "string", description: "ISO 8601 instant the tension was closed" },
436
+ resolved_by: { type: "string" },
437
+ kind: { type: "string", enum: [...RESOLUTION_KINDS] },
438
+ rationale: { type: "string" },
439
+ references: { type: "array", items: { type: "string" } },
440
+ },
441
+ required: ["resolved_at", "resolved_by", "kind"],
442
+ additionalProperties: false,
443
+ };
444
+ // One tension-log entry. `kinds` narrows the taxonomy to what the calling
445
+ // tool can actually return: vault_tension_log mints only loggable kinds,
446
+ // while vault_tension_resolve can close an entry of any kind (including the
447
+ // system-generated inter-proposal one and legacy unspecified entries).
448
+ function tensionEntrySchema(kinds) {
449
+ return {
450
+ type: "object",
451
+ properties: {
452
+ id: { type: "string", description: "e.g. 'tension-007'; absent on legacy entries" },
453
+ date: { type: "string", description: "YYYY-MM-DD" },
454
+ title: { type: "string" },
455
+ kind: { type: "string", enum: [...kinds] },
456
+ sourceA: { type: "string" },
457
+ claimA: { type: "string" },
458
+ sourceB: { type: "string" },
459
+ claimB: { type: "string" },
460
+ status: { type: "string", description: "'unresolved' | 'resolved'" },
461
+ loggedBy: { type: "string" },
462
+ decidedByPrincipal: { type: "string" },
463
+ resolved: { type: "boolean" },
464
+ resolution: tensionResolutionSchema,
465
+ },
466
+ required: [
467
+ "date",
468
+ "title",
469
+ "kind",
470
+ "sourceA",
471
+ "claimA",
472
+ "sourceB",
473
+ "claimB",
474
+ "status",
475
+ "loggedBy",
476
+ "resolved",
477
+ ],
478
+ additionalProperties: false,
479
+ };
480
+ }
481
+ const tensionClustersOutputSchema = {
482
+ type: "object",
483
+ properties: {
484
+ cluster_count: { type: "integer" },
485
+ clusters: {
486
+ type: "array",
487
+ items: {
488
+ type: "object",
489
+ properties: {
490
+ id: { type: "string", description: "cluster:<8 hex chars>" },
491
+ size: { type: "integer" },
492
+ documents: { type: "array", items: { type: "string" } },
493
+ tension_count: { type: "integer" },
494
+ kinds: countsByKey(TENSION_KINDS),
495
+ oldest_tension_age_days: { type: "number" },
496
+ newest_tension_age_days: { type: "number" },
497
+ },
498
+ required: [
499
+ "id",
500
+ "size",
501
+ "documents",
502
+ "tension_count",
503
+ "kinds",
504
+ "oldest_tension_age_days",
505
+ "newest_tension_age_days",
506
+ ],
507
+ additionalProperties: false,
508
+ },
509
+ },
510
+ },
511
+ required: ["cluster_count", "clusters"],
512
+ additionalProperties: false,
513
+ };
514
+ const tensionBlastOutputSchema = {
515
+ type: "object",
516
+ properties: {
517
+ contested_document: { type: ["string", "null"] },
518
+ cluster_id: { type: ["string", "null"] },
519
+ cluster_documents: { type: "array", items: { type: "string" } },
520
+ downstream: {
521
+ type: "array",
522
+ items: {
523
+ type: "object",
524
+ properties: {
525
+ path: { type: "string" },
526
+ dependency_type: { type: "string", enum: ["source", "link"] },
527
+ distance: { type: "integer" },
528
+ },
529
+ required: ["path", "dependency_type", "distance"],
530
+ additionalProperties: false,
531
+ },
532
+ },
533
+ primary_blast: { type: "integer", description: "docs reached via the 'sources' edge" },
534
+ advisory_blast: { type: "integer", description: "docs reached only via markdown links" },
535
+ max_depth: { type: "integer" },
536
+ hidden_downstream: {
537
+ type: "string",
538
+ enum: ["none", "some", "many"],
539
+ description: "Coarsened remainder of unreadable downstream docs — never an exact count",
540
+ },
541
+ },
542
+ required: [
543
+ "contested_document",
544
+ "cluster_id",
545
+ "cluster_documents",
546
+ "downstream",
547
+ "primary_blast",
548
+ "advisory_blast",
549
+ "max_depth",
550
+ "hidden_downstream",
551
+ ],
552
+ additionalProperties: false,
553
+ };
554
+ const triageReadHeatSchema = {
555
+ type: ["object", "null"],
556
+ properties: {
557
+ count: { type: "integer", description: "reads served within the window" },
558
+ last_read: {
559
+ type: ["string", "null"],
560
+ description: "ISO timestamp of the most recent in-window read",
561
+ },
562
+ instrumented: {
563
+ type: "boolean",
564
+ description: "false when the doc may predate the read log — its count is not trustworthy as coldness",
565
+ },
566
+ },
567
+ required: ["count", "last_read", "instrumented"],
568
+ additionalProperties: false,
569
+ };
570
+ const triageSideSchema = {
571
+ type: "object",
572
+ properties: {
573
+ path: { type: "string" },
574
+ claim: { type: "string" },
575
+ tier: { type: ["integer", "null"], description: "null when the doc is unknown or untiered" },
576
+ confidence: { type: ["string", "null"], enum: ["low", "medium", "high", null] },
577
+ read_heat: triageReadHeatSchema,
578
+ criticality: { type: ["string", "null"], enum: ["low", "medium", "high", null] },
579
+ provenance: {
580
+ type: ["string", "null"],
581
+ enum: ["direct", "synthesized", "inferred", null],
582
+ },
583
+ updated_by: { type: ["string", "null"] },
584
+ },
585
+ required: ["path", "claim", "tier", "confidence", "read_heat"],
586
+ additionalProperties: false,
587
+ };
588
+ const tensionTriageOutputSchema = {
589
+ type: "object",
590
+ properties: {
591
+ cluster_count: { type: "integer" },
592
+ tension_count: { type: "integer" },
593
+ clusters: {
594
+ type: "array",
595
+ items: {
596
+ type: "object",
597
+ properties: {
598
+ cluster_id: { type: "string", description: "cluster:<8 hex chars>" },
599
+ documents: { type: "array", items: { type: "string" } },
600
+ tensions: {
601
+ type: "array",
602
+ items: {
603
+ type: "object",
604
+ properties: {
605
+ id: { type: "string" },
606
+ title: { type: "string" },
607
+ kind: { type: "string", enum: [...TENSION_KINDS] },
608
+ age_days: { type: "number" },
609
+ a: triageSideSchema,
610
+ b: triageSideSchema,
611
+ primary_blast: { type: ["integer", "null"] },
612
+ advisory_blast: { type: ["integer", "null"] },
613
+ hidden_downstream: {
614
+ type: ["string", "null"],
615
+ enum: ["none", "some", "many", null],
616
+ },
617
+ },
618
+ required: [
619
+ "id",
620
+ "title",
621
+ "kind",
622
+ "age_days",
623
+ "a",
624
+ "b",
625
+ "primary_blast",
626
+ "advisory_blast",
627
+ "hidden_downstream",
628
+ ],
629
+ additionalProperties: false,
630
+ },
631
+ },
632
+ },
633
+ required: ["cluster_id", "documents", "tensions"],
634
+ additionalProperties: false,
635
+ },
636
+ },
637
+ },
638
+ required: ["cluster_count", "tension_count", "clusters"],
639
+ additionalProperties: false,
640
+ };
641
+ const lintFindingSchema = {
642
+ type: "object",
643
+ properties: { path: { type: "string" }, detail: { type: "string" } },
644
+ required: ["path", "detail"],
645
+ additionalProperties: false,
646
+ };
647
+ // `checks` is a Partial record — a filtered run carries exactly one key — so
648
+ // no check name is required, only known.
649
+ const lintChecksProperties = {};
650
+ for (const check of LINT_CHECKS) {
651
+ lintChecksProperties[check] = { type: "array", items: lintFindingSchema };
652
+ }
653
+ const strengthGroupStatsSchema = {
654
+ type: "object",
655
+ properties: {
656
+ count: { type: "integer" },
657
+ mean: { type: "number" },
658
+ median: { type: "number" },
659
+ p10: { type: "number" },
660
+ p90: { type: "number" },
661
+ variance: { type: "number" },
662
+ },
663
+ required: ["count", "mean", "median", "p10", "p90", "variance"],
664
+ additionalProperties: false,
665
+ };
666
+ const shadowLintItemSchema = {
667
+ type: "object",
668
+ properties: {
669
+ at: { type: "string" },
670
+ tool: { type: "string" },
671
+ action: { type: "string" },
672
+ targetPath: { type: "string" },
673
+ agent: { type: "string" },
674
+ impact: { type: "number" },
675
+ budget: { type: "number" },
676
+ },
677
+ required: ["at", "tool", "action", "targetPath", "agent", "impact", "budget"],
678
+ additionalProperties: false,
679
+ };
680
+ const reviewThroughputWindowSchema = {
681
+ type: "object",
682
+ properties: {
683
+ arrivals: { type: "integer" },
684
+ decisions: { type: "integer" },
685
+ expiries: { type: "integer" },
686
+ },
687
+ required: ["arrivals", "decisions", "expiries"],
688
+ additionalProperties: false,
689
+ };
690
+ const lintOutputSchema = {
691
+ type: "object",
692
+ properties: {
693
+ generatedAt: { type: "string" },
694
+ filter: {
695
+ type: ["string", "null"],
696
+ enum: [...LINT_CHECKS, null],
697
+ description: "The single check the report was restricted to, or null for all checks",
698
+ },
699
+ checks: {
700
+ type: "object",
701
+ properties: lintChecksProperties,
702
+ additionalProperties: false,
703
+ },
704
+ totalFindings: { type: "integer" },
705
+ // Vault-global by design (#217 decision C): counts only, no paths.
706
+ tensionHealth: {
707
+ type: "object",
708
+ properties: {
709
+ total: { type: "integer" },
710
+ byKind: countsByKey(TENSION_KINDS),
711
+ resolvedLifetime: { type: "integer" },
712
+ byResolutionKind: countsByKey(RESOLUTION_KINDS),
713
+ stableAcknowledged: { type: "integer" },
714
+ unspecifiedLegacy: { type: "integer" },
715
+ aging: {
716
+ type: "object",
717
+ properties: {
718
+ fresh: { type: "integer" },
719
+ aging: { type: "integer" },
720
+ stale: { type: "integer" },
721
+ staleByKind: countsByKey(TENSION_KINDS),
722
+ // Kind-keyed lint copy, present only for kinds with a nonzero
723
+ // stale count; `unspecified` never appears.
724
+ staleMessages: { type: "object", additionalProperties: { type: "string" } },
725
+ },
726
+ required: ["fresh", "aging", "stale", "staleByKind", "staleMessages"],
727
+ additionalProperties: false,
728
+ },
729
+ clusters: {
730
+ type: "object",
731
+ properties: {
732
+ count: { type: "integer" },
733
+ maxSize: { type: "integer" },
734
+ large: { type: "integer" },
735
+ aged: { type: "integer" },
736
+ },
737
+ required: ["count", "maxSize", "large", "aged"],
738
+ additionalProperties: false,
739
+ },
740
+ blastRadiusOfStaleTensions: { type: "integer" },
741
+ },
742
+ required: [
743
+ "total",
744
+ "byKind",
745
+ "resolvedLifetime",
746
+ "byResolutionKind",
747
+ "stableAcknowledged",
748
+ "unspecifiedLegacy",
749
+ "aging",
750
+ "clusters",
751
+ "blastRadiusOfStaleTensions",
752
+ ],
753
+ additionalProperties: false,
754
+ },
755
+ stagedActions: {
756
+ type: "array",
757
+ description: "Pending staged actions awaiting ratification, soonest-to-expire first",
758
+ items: {
759
+ type: "object",
760
+ properties: {
761
+ id: { type: "string" },
762
+ actionType: { type: "string", enum: [...STAGED_ACTION_TYPES] },
763
+ targetPath: { type: "string" },
764
+ ageDays: { type: "integer" },
765
+ expiresInDays: { type: "integer" },
766
+ rationale: { type: "string", description: "First sentence of the staged rationale" },
767
+ },
768
+ required: ["id", "actionType", "targetPath", "ageDays", "expiresInDays", "rationale"],
769
+ additionalProperties: false,
770
+ },
771
+ },
772
+ shadowActions: {
773
+ type: "object",
774
+ properties: {
775
+ total: { type: "integer" },
776
+ gated: { type: "integer" },
777
+ recentGated: { type: "array", items: shadowLintItemSchema },
778
+ gatedSurfaced: { type: "array", items: shadowLintItemSchema },
779
+ gatedCount: { type: "integer" },
780
+ },
781
+ required: ["total", "gated", "recentGated", "gatedSurfaced", "gatedCount"],
782
+ additionalProperties: false,
783
+ },
784
+ coverageEquity: {
785
+ type: "object",
786
+ properties: {
787
+ generatedAt: { type: "string" },
788
+ strengthDrift: {
789
+ type: "object",
790
+ properties: {
791
+ core: strengthGroupStatsSchema,
792
+ periphery: strengthGroupStatsSchema,
793
+ // Null when either group is empty — the gap is undefined, and a
794
+ // sentinel 0 would read as "no drift".
795
+ coreMinusPeripheryMedian: { type: ["number", "null"] },
796
+ belowTriggerCount: { type: "integer" },
797
+ },
798
+ required: ["core", "periphery", "coreMinusPeripheryMedian", "belowTriggerCount"],
799
+ additionalProperties: false,
800
+ },
801
+ backstopOverdue: {
802
+ type: "object",
803
+ properties: {
804
+ count: { type: "integer" },
805
+ stalest: {
806
+ type: "array",
807
+ items: {
808
+ type: "object",
809
+ properties: {
810
+ fromPath: { type: "string" },
811
+ toPath: { type: "string" },
812
+ daysOverdue: { type: "number" },
813
+ },
814
+ required: ["fromPath", "toPath", "daysOverdue"],
815
+ additionalProperties: false,
816
+ },
817
+ },
818
+ },
819
+ required: ["count", "stalest"],
820
+ additionalProperties: false,
821
+ },
822
+ actionMix: {
823
+ type: "object",
824
+ properties: {
825
+ // Open by construction: keyed by whatever action names the edge
826
+ // ops and staged-action log carry.
827
+ counts: { type: "object", additionalProperties: { type: "integer" } },
828
+ cheapLinkFraction: { type: "number" },
829
+ total: { type: "integer" },
830
+ },
831
+ required: ["counts", "cheapLinkFraction", "total"],
832
+ additionalProperties: false,
833
+ },
834
+ directionResolution: {
835
+ type: "object",
836
+ properties: {
837
+ directed: { type: "integer" },
838
+ symmetric: { type: "integer" },
839
+ unresolvedFraction: { type: "number" },
840
+ },
841
+ required: ["directed", "symmetric", "unresolvedFraction"],
842
+ additionalProperties: false,
843
+ },
844
+ },
845
+ required: [
846
+ "generatedAt",
847
+ "strengthDrift",
848
+ "backstopOverdue",
849
+ "actionMix",
850
+ "directionResolution",
851
+ ],
852
+ additionalProperties: false,
853
+ },
854
+ reviewThroughput: {
855
+ type: "object",
856
+ properties: {
857
+ lifetime: {
858
+ type: "object",
859
+ properties: {
860
+ proposals: { type: "integer" },
861
+ ratified: { type: "integer" },
862
+ rejected: { type: "integer" },
863
+ expired: { type: "integer" },
864
+ pending: { type: "integer" },
865
+ },
866
+ required: ["proposals", "ratified", "rejected", "expired", "pending"],
867
+ additionalProperties: false,
868
+ },
869
+ last7d: reviewThroughputWindowSchema,
870
+ last30d: reviewThroughputWindowSchema,
871
+ timeToDecisionDays: {
872
+ type: "object",
873
+ properties: {
874
+ p50: { type: ["number", "null"] },
875
+ p90: { type: ["number", "null"] },
876
+ },
877
+ required: ["p50", "p90"],
878
+ additionalProperties: false,
879
+ },
880
+ oldestPendingDays: { type: ["number", "null"] },
881
+ },
882
+ required: ["lifetime", "last7d", "last30d", "timeToDecisionDays", "oldestPendingDays"],
883
+ additionalProperties: false,
884
+ },
885
+ },
886
+ required: [
887
+ "generatedAt",
888
+ "filter",
889
+ "checks",
890
+ "totalFindings",
891
+ "tensionHealth",
892
+ "stagedActions",
893
+ "shadowActions",
894
+ "coverageEquity",
895
+ "reviewThroughput",
896
+ ],
897
+ additionalProperties: false,
898
+ };
899
+ const provenanceOutputSchema = {
900
+ type: "object",
901
+ properties: {
902
+ path: { type: "string" },
903
+ count: { type: "integer" },
904
+ history: {
905
+ type: "array",
906
+ description: "Provenance entries for this document, oldest first",
907
+ items: {
908
+ type: "object",
909
+ properties: {
910
+ timestamp: { type: "string" },
911
+ tool: { type: "string" },
912
+ file: { type: "string" },
913
+ agent: { type: "string", description: "Caller-claimed acting identity" },
914
+ action: { type: "string" },
915
+ principal: { type: "string", description: "Authenticated server identity (§11.6)" },
916
+ run_id: { type: "string" },
917
+ body_changed: { type: "boolean" },
918
+ // Per-field { before, after } over arbitrary frontmatter keys —
919
+ // open by construction, so the value shape stays unconstrained.
920
+ frontmatter_diff: { type: "object", additionalProperties: { type: "object" } },
921
+ reason: { type: "string" },
922
+ },
923
+ required: ["timestamp", "tool", "file", "agent", "action"],
924
+ additionalProperties: false,
925
+ },
926
+ },
927
+ },
928
+ required: ["path", "count", "history"],
929
+ additionalProperties: false,
930
+ };
931
+ // ---------------------------------------------------------------------------
932
+ // vault_lint summarizer
933
+ // ---------------------------------------------------------------------------
934
+ //
935
+ // Decision 3 names vault-wide lint output as a worst token offender: the full
936
+ // report is a wall. The `content` channel gets counts plus a handful of
937
+ // findings, one line each; the full report still rides the structured channel.
938
+ export function summarizeLint(value) {
939
+ const report = value;
940
+ const perCheck = [];
941
+ let certain = 0;
942
+ let advisory = 0;
943
+ const flat = [];
944
+ for (const check of LINT_CHECKS) {
945
+ const findings = report.checks[check] ?? [];
946
+ if (findings.length === 0)
947
+ continue;
948
+ perCheck.push(`${check} ${findings.length}`);
949
+ if (TIER0_LINT_CHECKS.includes(check))
950
+ certain += findings.length;
951
+ else
952
+ advisory += findings.length;
953
+ for (const finding of findings)
954
+ flat.push({ check, finding });
955
+ }
956
+ // Certain (tier-0) findings first; sort is stable, so within each severity
957
+ // the LINT_CHECKS order is preserved.
958
+ flat.sort((a, b) => Number(TIER0_LINT_CHECKS.includes(b.check)) - Number(TIER0_LINT_CHECKS.includes(a.check)));
959
+ const health = report.tensionHealth;
960
+ const lines = [
961
+ `vault_lint [${report.filter ?? "all checks"}] ${report.totalFindings} finding(s): ` +
962
+ `${certain} certain (tier-0), ${advisory} advisory — ${report.generatedAt}`,
963
+ perCheck.length > 0 ? `by check: ${perCheck.join(", ")}` : "by check: clean",
964
+ `tensions: ${health.total} logged, ${health.resolvedLifetime} resolved, ` +
965
+ `${health.stableAcknowledged} accepted; aging ${health.aging.fresh}/${health.aging.aging}/` +
966
+ `${health.aging.stale} fresh/aging/stale; ${health.clusters.count} cluster(s) ` +
967
+ `(${health.clusters.large} large, ${health.clusters.aged} aged); ` +
968
+ `stale blast ${health.blastRadiusOfStaleTensions}`,
969
+ `staged: ${report.stagedActions.length} pending, ` +
970
+ `${report.reviewThroughput.lifetime.expired} expired lifetime; ` +
971
+ `shadow: ${report.shadowActions.total} logged, ${report.shadowActions.gated} would-gate; ` +
972
+ `coverage: ${report.coverageEquity.backstopOverdue.count} backstop-overdue edge(s)`,
973
+ ];
974
+ const top = flat.slice(0, LINT_SUMMARY_TOP_FINDINGS);
975
+ if (top.length > 0) {
976
+ lines.push(`top ${top.length} of ${flat.length} finding(s):`);
977
+ for (const { check, finding } of top) {
978
+ lines.push(` [${check}] ${finding.path} — ${clip(finding.detail, LINT_SUMMARY_DETAIL_CHARS)}`);
979
+ }
980
+ }
981
+ return lines.join("\n");
982
+ }
983
+ // The vault_lint `content`-channel summary, choosing the voice from the vault's
984
+ // `lint_voice` config. Default (or on any config error) is the plain summary;
985
+ // `ledger_keeper` re-renders the SAME findings in the ledger-keeper register.
986
+ // The structured channel (the VaultLintResult itself) is untouched either way.
987
+ export function lintContentSummary(value, vaultRoot) {
988
+ const config = loadConfig(vaultRoot);
989
+ const voice = config.ok ? config.value.lintVoice : "plain";
990
+ return voice === "ledger_keeper"
991
+ ? renderLedgerKeeper(value)
992
+ : summarizeLint(value);
993
+ }
994
+ // ---------------------------------------------------------------------------
385
995
  // MCP tool definitions
386
996
  // ---------------------------------------------------------------------------
387
997
  export const curationTools = [
@@ -433,6 +1043,8 @@ export const curationTools = [
433
1043
  required: ["title", "sourceA", "claimA", "sourceB", "claimB", "agent", "kind"],
434
1044
  additionalProperties: false,
435
1045
  },
1046
+ // The entry as logged: id assigned, status 'unresolved', no resolution.
1047
+ outputSchema: tensionEntrySchema(LOGGABLE_TENSION_KINDS),
436
1048
  handler: (vaultRoot, args, access) => vaultTensionLog(vaultRoot, args, access),
437
1049
  },
438
1050
  {
@@ -473,6 +1085,8 @@ export const curationTools = [
473
1085
  required: ["id", "kind"],
474
1086
  additionalProperties: false,
475
1087
  },
1088
+ // The updated entry: status 'resolved' with the resolution block attached.
1089
+ outputSchema: tensionEntrySchema(TENSION_KINDS),
476
1090
  handler: (vaultRoot, args, access) => vaultTensionResolve(vaultRoot, args, access),
477
1091
  },
478
1092
  {
@@ -492,6 +1106,7 @@ export const curationTools = [
492
1106
  properties: {},
493
1107
  additionalProperties: false,
494
1108
  },
1109
+ outputSchema: tensionClustersOutputSchema,
495
1110
  handler: (vaultRoot, args, access) => vaultTensionClusters(vaultRoot, args, access),
496
1111
  },
497
1112
  {
@@ -529,8 +1144,34 @@ export const curationTools = [
529
1144
  },
530
1145
  additionalProperties: false,
531
1146
  },
1147
+ outputSchema: tensionBlastOutputSchema,
532
1148
  handler: (vaultRoot, args, access) => vaultTensionBlast(vaultRoot, args, access),
533
1149
  },
1150
+ {
1151
+ name: "vault_tension_triage",
1152
+ title: "Tension triage card",
1153
+ annotations: { readOnlyHint: true },
1154
+ description: "Compose the vault's LIVE tensions into a human-legible triage card: " +
1155
+ "every unresolved, non-accepted tension grouped by cluster and " +
1156
+ "annotated for a curator deciding what to resolve. Each tension carries " +
1157
+ "its kind, age in days, and blast (primary_blast via 'sources' edges, " +
1158
+ "advisory_blast via markdown links); each contested side carries its " +
1159
+ "tier, confidence, and read-heat (in-window read count + recency, with " +
1160
+ "an 'instrumented' flag that distinguishes a genuinely cold doc from one " +
1161
+ "that predates the read log). Clusters are ordered by size descending, " +
1162
+ "tensions within a cluster by age descending. There is deliberately NO " +
1163
+ "composite severity score or ranking — legibility is the point; ranking " +
1164
+ "the queue is the human's call. Null tier/confidence/read-heat means the " +
1165
+ "doc is unknown; null blast means none was computed for that tension. " +
1166
+ "Read-only; never edits the tension log or any document.",
1167
+ inputSchema: {
1168
+ type: "object",
1169
+ properties: {},
1170
+ additionalProperties: false,
1171
+ },
1172
+ outputSchema: tensionTriageOutputSchema,
1173
+ handler: (vaultRoot, args, access) => vaultTensionTriage(vaultRoot, args, access),
1174
+ },
534
1175
  {
535
1176
  name: "vault_lint",
536
1177
  // Not read-only: the staged-action sweep (§11.2) expires actions past
@@ -563,6 +1204,8 @@ export const curationTools = [
563
1204
  },
564
1205
  additionalProperties: false,
565
1206
  },
1207
+ outputSchema: lintOutputSchema,
1208
+ summarize: lintContentSummary,
566
1209
  handler: (vaultRoot, args, access) => vaultLint(vaultRoot, args, access),
567
1210
  },
568
1211
  {
@@ -583,6 +1226,7 @@ export const curationTools = [
583
1226
  required: ["filePath"],
584
1227
  additionalProperties: false,
585
1228
  },
1229
+ outputSchema: provenanceOutputSchema,
586
1230
  handler: (vaultRoot, args, access) => vaultProvenance(vaultRoot, args, access),
587
1231
  },
588
1232
  ];