pi-braid 0.40.1 → 0.40.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.
Files changed (105) hide show
  1. package/CONTRIBUTING.md +27 -3
  2. package/README.md +13 -13
  3. package/TOOLS.md +27 -3
  4. package/build-info.json +9 -0
  5. package/dist/extensions/cognitive/metacognition/handlers/claim-verification.js +7 -1
  6. package/dist/extensions/cognitive/metacognition/handlers/finalize.js +20 -0
  7. package/dist/extensions/cognitive/metacognition/handlers/hypothesize.d.ts +9 -0
  8. package/dist/extensions/cognitive/metacognition/handlers/hypothesize.js +13 -1
  9. package/dist/extensions/cognitive/metacognition/handlers/verify.js +35 -4
  10. package/dist/extensions/cognitive/topic-drift/index.js +19 -2
  11. package/dist/extensions/core/prompt-builder/inspect.js +9 -3
  12. package/dist/extensions/core/prompt-builder/top-level-extensions.d.ts +6 -5
  13. package/dist/extensions/core/prompt-builder/top-level-extensions.js +64 -29
  14. package/dist/extensions/enforcement/handlers/register-tool-result-formatting.d.ts +1 -1
  15. package/dist/extensions/enforcement/handlers/register-tool-result-formatting.js +1 -1
  16. package/dist/extensions/enforcement/handlers/turn-end-handler.js +1 -1
  17. package/dist/extensions/enforcement/self-state-claims.d.ts +1 -1
  18. package/dist/extensions/enforcement/self-state-claims.js +3 -2
  19. package/dist/extensions/manifest.js +2 -2
  20. package/dist/extensions/memory/context-manager/handlers/tool-batch-boundary.d.ts +22 -5
  21. package/dist/extensions/memory/context-manager/handlers/tool-batch-boundary.js +43 -11
  22. package/dist/extensions/memory/context-manager/handlers/tools/context-compress.js +174 -50
  23. package/dist/extensions/memory/context-manager/handlers/tools/context-inspect.js +7 -1
  24. package/dist/extensions/memory/context-manager/handlers/tools/context-navigate.js +4 -1
  25. package/dist/extensions/memory/memory-agent-bridge/explore-paths.d.ts +2 -24
  26. package/dist/extensions/memory/memory-agent-bridge/explore-paths.js +33 -2
  27. package/dist/extensions/memory/memory-agent-bridge/memory-store-tool.js +16 -0
  28. package/dist/extensions/memory/memory-agent-bridge/memory-tool.js +21 -9
  29. package/dist/extensions/memory/scratchpad/format.js +8 -2
  30. package/dist/extensions/memory/scratchpad/index.js +11 -2
  31. package/dist/extensions/memory/session-recall/index.js +19 -6
  32. package/dist/extensions/memory/three-memory-stores/episodes.d.ts +1 -1
  33. package/dist/extensions/memory/three-memory-stores/episodes.js +2 -2
  34. package/dist/extensions/orchestrator/index.js +73 -8
  35. package/dist/extensions/scheduling/timer/index.js +9 -1
  36. package/dist/extensions/self/error-tracking/index.js +8 -1
  37. package/dist/extensions/self/health-maintenance/handlers/session-health-tool.js +9 -2
  38. package/dist/extensions/self/health-maintenance/index.js +112 -9
  39. package/dist/lib/config/braid-settings.d.ts +21 -0
  40. package/dist/lib/config/braid-settings.js +36 -0
  41. package/dist/lib/constants/session-thresholds.d.ts +2 -3
  42. package/dist/lib/constants/session-thresholds.js +2 -3
  43. package/dist/lib/enforcement/turn-dedup.d.ts +2 -2
  44. package/dist/lib/enforcement/turn-dedup.js +2 -2
  45. package/dist/lib/harness/index.d.ts +1 -1
  46. package/dist/lib/harness/index.js +1 -1
  47. package/dist/lib/harness/types.d.ts +1 -1
  48. package/dist/lib/harness/types.js +1 -1
  49. package/dist/lib/orchestrator/index.d.ts +2 -2
  50. package/dist/lib/orchestrator/index.js +1 -1
  51. package/dist/lib/orchestrator/workers.d.ts +184 -2
  52. package/dist/lib/orchestrator/workers.js +521 -6
  53. package/dist/lib/utils/injection-tracker.js +1 -1
  54. package/docs/CONTEXT-POLICY.md +13 -5
  55. package/docs/LOCAL_DEV.md +31 -5
  56. package/docs/ROADMAP.md +10 -7
  57. package/docs/SETUP.md +3 -2
  58. package/package.json +11 -8
  59. package/skills/braid-reference/SKILL.md +23 -23
  60. package/skills/release-pipeline/SKILL.md +46 -37
  61. package/skills/subagent-orchestration/SKILL.md +51 -1
  62. package/src/extensions/cognitive/metacognition/handlers/claim-verification.ts +8 -1
  63. package/src/extensions/cognitive/metacognition/handlers/finalize.ts +21 -0
  64. package/src/extensions/cognitive/metacognition/handlers/hypothesize.ts +14 -1
  65. package/src/extensions/cognitive/metacognition/handlers/verify.ts +39 -5
  66. package/src/extensions/cognitive/topic-drift/index.ts +20 -2
  67. package/src/extensions/core/prompt-builder/AGENTS.md +1 -1
  68. package/src/extensions/core/prompt-builder/inspect.ts +10 -3
  69. package/src/extensions/core/prompt-builder/top-level-extensions.ts +68 -29
  70. package/src/extensions/enforcement/AGENTS.md +25 -19
  71. package/src/extensions/enforcement/handlers/register-tool-result-formatting.ts +1 -1
  72. package/src/extensions/enforcement/handlers/turn-end-handler.ts +1 -1
  73. package/src/extensions/enforcement/self-state-claims.ts +3 -2
  74. package/src/extensions/heartbeat/heartbeat-scheduler/AGENTS.md +6 -3
  75. package/src/extensions/manifest.ts +2 -2
  76. package/src/extensions/memory/AGENTS.md +13 -5
  77. package/src/extensions/memory/context-manager/handlers/tool-batch-boundary.ts +45 -11
  78. package/src/extensions/memory/context-manager/handlers/tools/context-compress.ts +202 -60
  79. package/src/extensions/memory/context-manager/handlers/tools/context-inspect.ts +8 -1
  80. package/src/extensions/memory/context-manager/handlers/tools/context-navigate.ts +4 -1
  81. package/src/extensions/memory/memory-agent-bridge/explore-paths.ts +37 -3
  82. package/src/extensions/memory/memory-agent-bridge/memory-store-tool.ts +16 -0
  83. package/src/extensions/memory/memory-agent-bridge/memory-tool.ts +22 -9
  84. package/src/extensions/memory/scratchpad/format.ts +8 -2
  85. package/src/extensions/memory/scratchpad/index.ts +12 -2
  86. package/src/extensions/memory/session-recall/index.ts +20 -8
  87. package/src/extensions/memory/three-memory-stores/episodes.ts +2 -2
  88. package/src/extensions/orchestrator/index.ts +100 -11
  89. package/src/extensions/scheduling/timer/AGENTS.md +7 -0
  90. package/src/extensions/scheduling/timer/index.ts +10 -1
  91. package/src/extensions/self/error-tracking/index.ts +9 -1
  92. package/src/extensions/self/health-maintenance/handlers/session-health-tool.ts +10 -2
  93. package/src/extensions/self/health-maintenance/index.ts +143 -14
  94. package/src/extensions/self/watchdog/AGENTS.md +1 -0
  95. package/src/lib/AGENTS.md +21 -21
  96. package/src/lib/config/braid-settings.ts +74 -0
  97. package/src/lib/constants/session-thresholds.ts +2 -3
  98. package/src/lib/enforcement/turn-dedup.ts +2 -2
  99. package/src/lib/harness/AGENTS.md +1 -1
  100. package/src/lib/harness/index.ts +1 -1
  101. package/src/lib/harness/types.ts +1 -1
  102. package/src/lib/orchestrator/index.ts +26 -0
  103. package/src/lib/orchestrator/workers.ts +705 -7
  104. package/src/lib/utils/AGENTS.md +1 -1
  105. package/src/lib/utils/injection-tracker.ts +1 -1
package/src/lib/AGENTS.md CHANGED
@@ -9,27 +9,27 @@ shared conventions.
9
9
 
10
10
  ## Subdirectory Index
11
11
 
12
- | Subdir | Purpose |
13
- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
14
- | [`ai/`](./ai/AGENTS.md) | LLM utilities - critic registry, model resolution, text classification, structured LLM call wrapper. |
15
- | [`memory/`](./memory/AGENTS.md) | Memory engine - the underlying storage and reasoning layer for memory-related extensions. |
16
- | [`config/`](./config/AGENTS.md) | Configuration loading and merging. |
17
- | [`constants/`](./constants/AGENTS.md) | Project-wide constants and enums. |
18
- | [`core/`](./core/AGENTS.md) | Foundation utilities - logger, event-name constants. Anything that's truly cross-cutting lives here. |
19
- | [`detection/`](./detection/AGENTS.md) | Detection primitives - degradation detection, topic-drift, context density, compression strategies. |
20
- | [`enforcement/`](./enforcement/AGENTS.md) | Cross-extension enforcement utilities - turn-dedup registry, whisper capping. |
21
- | [`events/`](./events/AGENTS.md) | Event-bus and channel infrastructure - consolidation, timer, turn-end coordination. |
22
- | [`reasoning/`](./reasoning/AGENTS.md) | Reasoning engines - dreamer (loop prediction), belief policy, MARS reflector, summarization, advice tracker. |
23
- | [`state/`](./state/AGENTS.md) | Per-extension state, session state, global state, checkpointing. |
24
- | [`store/`](./store/AGENTS.md) | Persistent stores - claims, evidence, conflicts, beliefs. |
25
- | [`types/`](./types/AGENTS.md) | Shared type definitions and result wrappers. |
26
- | [`utils/`](./utils/AGENTS.md) | Misc utilities - injection tracker, mutation queue, filter helpers, SOP extraction. |
27
- | [`cognitive/`](./cognitive/AGENTS.md) | Whisper-delivery libraries - project-relevant hints and active OpenSpec specs for the prompt. |
28
- | `errors/` | Unified LLM error classifier - provider-failure taxonomy (balance, rate-limit, context-window, transient). |
29
- | [`harness/`](./harness/AGENTS.md) | Self-harness loop - failure-trace collection, weakness mining, candidate proposal and validation. |
30
- | `orchestrator/` | Multi-agent coordination - file-lock registry, worker branches, conflict detection, merge verification. |
31
- | [`telemetry/`](./telemetry/AGENTS.md) | Bounded telemetry accumulators for the degradation-detection loop (drift signals, context/RSS heartbeat). |
32
- | `verification/` | Cross-file verification - downstream import tracing and derived-file coordination checks. |
12
+ | Subdir | Purpose |
13
+ | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
14
+ | [`ai/`](./ai/AGENTS.md) | LLM utilities - critic registry, model resolution, text classification, structured LLM call wrapper. |
15
+ | [`memory/`](./memory/AGENTS.md) | Memory engine - the underlying storage and reasoning layer for memory-related extensions. |
16
+ | [`config/`](./config/AGENTS.md) | Configuration loading and merging. |
17
+ | [`constants/`](./constants/AGENTS.md) | Project-wide constants and enums. |
18
+ | [`core/`](./core/AGENTS.md) | Foundation utilities - logger, event-name constants. Anything that's truly cross-cutting lives here. |
19
+ | [`detection/`](./detection/AGENTS.md) | Detection primitives - degradation detection, topic-drift, context density, compression strategies. |
20
+ | [`enforcement/`](./enforcement/AGENTS.md) | Cross-extension enforcement utilities - turn-dedup registry, whisper capping. |
21
+ | [`events/`](./events/AGENTS.md) | Event-bus and channel infrastructure - consolidation, timer, turn-end coordination. |
22
+ | [`reasoning/`](./reasoning/AGENTS.md) | Reasoning engines - dreamer (loop prediction), belief policy, MARS reflector, summarization, advice tracker. |
23
+ | [`state/`](./state/AGENTS.md) | Per-extension state, session state, global state, checkpointing. |
24
+ | [`store/`](./store/AGENTS.md) | Persistent stores - claims, evidence, conflicts, beliefs. |
25
+ | [`types/`](./types/AGENTS.md) | Shared type definitions and result wrappers. |
26
+ | [`utils/`](./utils/AGENTS.md) | Misc utilities - injection tracker, mutation queue, filter helpers, SOP extraction. |
27
+ | [`cognitive/`](./cognitive/AGENTS.md) | Whisper-delivery libraries - project-relevant hints and active OpenSpec specs for the prompt. |
28
+ | `errors/` | Unified LLM error classifier - provider-failure taxonomy (balance, rate-limit, context-window, transient). |
29
+ | [`harness/`](./harness/AGENTS.md) | Self-harness loop - failure-trace collection, weakness mining, candidate proposal and validation. |
30
+ | `orchestrator/` | Multi-agent coordination - file-lock registry, worker registry with close-time gate-row well-formedness, the production-write preflight read, and the population-stamp read the merge path compares against the repo, worker branches, conflict detection, merge verification. |
31
+ | [`telemetry/`](./telemetry/AGENTS.md) | Bounded telemetry accumulators for the degradation-detection loop (drift signals, context/RSS heartbeat). |
32
+ | `verification/` | Cross-file verification - downstream import tracing and derived-file coordination checks. |
33
33
 
34
34
  ## Conventions
35
35
 
@@ -66,6 +66,24 @@ interface BraidConfig {
66
66
  mode?: string;
67
67
  };
68
68
  };
69
+ /**
70
+ * Orchestrator-layer config. `closeGateWellFormedness` gates the close
71
+ * path's gate evidence at close time: every recorded `{cmd, exit}` row is
72
+ * read as a string (parse, first-token resolution, no top-level
73
+ * decoration) and a completed close's exits must be 0. No gate is re-run.
74
+ *
75
+ * Example:
76
+ * "braid": { "orchestrator": { "closeGateWellFormedness": "shadow" } }
77
+ */
78
+ orchestrator?: {
79
+ /**
80
+ * "shadow" (default) logs a failing row to the refusal log and lets the
81
+ * close proceed; "enforce" refuses the close naming the row, predicate
82
+ * and cmd; "off" skips the read entirely. An unknown value warns once
83
+ * and falls back to "shadow".
84
+ */
85
+ closeGateWellFormedness?: string;
86
+ };
69
87
  /**
70
88
  * Memory-layer config. Review-before-write quality gate on durable episode
71
89
  * writes: `writeGate` controls the per-site policies (repair/dedupe/reject)
@@ -415,6 +433,62 @@ export function getOverCorrectionGateConfig(): OverCorrectionGateConfig {
415
433
  return resolveOverCorrectionGate(readSettings().braid?.enforcement?.overCorrectionGate);
416
434
  }
417
435
 
436
+ // ── close-gate well-formedness (braid.orchestrator.closeGateWellFormedness) ──
437
+ // The close path reads every recorded gate evidence row {cmd, exit} against
438
+ // four string predicates before the row is stamped (see
439
+ // lib/orchestrator/workers.ts). Shipped default: shadow, so a failing row is
440
+ // logged and the close proceeds, and a first ship cannot refuse honest closes.
441
+
442
+ /** Close-gate modes: off (inert), shadow (log only), enforce (refuse). */
443
+ export type CloseGateWellFormednessMode = "off" | "shadow" | "enforce";
444
+
445
+ export interface CloseGateWellFormednessConfig {
446
+ mode: CloseGateWellFormednessMode;
447
+ }
448
+
449
+ /** Default mode: shadow; the validator logs before it is allowed to refuse. */
450
+ export const CLOSE_GATE_WELL_FORMEDNESS_DEFAULTS: CloseGateWellFormednessConfig = {
451
+ mode: "shadow",
452
+ };
453
+
454
+ /** Warned once per process about an invalid closeGateWellFormedness value. */
455
+ let _warnedInvalidCloseGateWellFormedness = false;
456
+
457
+ function _warnInvalidCloseGateWellFormedness(value: unknown): void {
458
+ if (_warnedInvalidCloseGateWellFormedness) return;
459
+ _warnedInvalidCloseGateWellFormedness = true;
460
+ _log.warn(
461
+ "Invalid braid.orchestrator.closeGateWellFormedness in settings.json - ignoring " +
462
+ 'and using the default (mode "shadow"). Expected "off" | "shadow" | "enforce".',
463
+ { value },
464
+ );
465
+ }
466
+
467
+ /**
468
+ * Pure resolver for braid.orchestrator.closeGateWellFormedness. Absent value
469
+ * ⇒ mode "shadow". A value outside the enum warns once and falls back to
470
+ * "shadow", so a typo can neither silently disarm the validator (off) nor
471
+ * arm it (enforce). Kept pure so the default merge is unit-testable without
472
+ * touching live settings.json.
473
+ */
474
+ export function resolveCloseGateWellFormedness(raw: unknown): CloseGateWellFormednessConfig {
475
+ if (raw === undefined || raw === null) return { ...CLOSE_GATE_WELL_FORMEDNESS_DEFAULTS };
476
+ if (raw === "off" || raw === "shadow" || raw === "enforce") return { mode: raw };
477
+ _warnInvalidCloseGateWellFormedness(raw);
478
+ return { ...CLOSE_GATE_WELL_FORMEDNESS_DEFAULTS };
479
+ }
480
+
481
+ /**
482
+ * Read the effective close-gate well-formedness mode from settings.json,
483
+ * fresh on every call (no caching), like the other readers. Default: mode
484
+ * "shadow".
485
+ */
486
+ export function getCloseGateWellFormedness(): CloseGateWellFormednessConfig {
487
+ return resolveCloseGateWellFormedness(
488
+ readSettings().braid?.orchestrator?.closeGateWellFormedness,
489
+ );
490
+ }
491
+
418
492
  /**
419
493
  * Read the braid.memory.writeGate block from settings.json.
420
494
  *
@@ -27,9 +27,8 @@ export const NUDGE_COOLDOWN_MS = 5 * 60 * 1000; // 5 minutes
27
27
  * retry end). Distinct from the 5-minute `NUDGE_COOLDOWN_MS` which is
28
28
  * a cross-session cap; this is the per-site rate-limit value.
29
29
  *
30
- * EW-7.8: promote to constant. The "remove" path (delete the field,
31
- * rely on NudgeManager) needs per-NudgeType cooldown decisions and
32
- * is deferred.
30
+ * Promote to constant is deferred: the "remove" path (delete the field,
31
+ * rely on NudgeManager) needs per-NudgeType cooldown decisions.
33
32
  */
34
33
  export const ERROR_TRACKING_NUDGE_COOLDOWN_MS = 60_000; // 1 minute
35
34
 
@@ -80,8 +80,8 @@ export const PER_SOURCE_CAP = 2;
80
80
  * caps than PER_SOURCE_CAP are NOT supported via overrides - if a
81
81
  * source needs a lower cap, add a new explicit value here.
82
82
  *
83
- * EW-7.13: drop the all-sources-share cap so high-priority sources
84
- * can get through during a degraded turn.
83
+ * Drop the all-sources-share cap so high-priority sources can get
84
+ * through during a degraded turn.
85
85
  */
86
86
  export const PER_SOURCE_CAP_OVERRIDES: Record<string, number> = {
87
87
  // Enforcement whispers are critical/high priority. A 3rd
@@ -1,6 +1,6 @@
1
1
  <!-- status: current -->
2
2
 
3
- # Self-Harness Loop (LP-1): src/lib/harness/
3
+ # Self-Harness Loop: src/lib/harness/
4
4
 
5
5
  Failure collection and weakness mining. `failure-trace-collector.ts` observes the
6
6
  tool-loop detector's per-session state (written by the enforcement extension on
@@ -1,5 +1,5 @@
1
1
  /**
2
- * Self-Harness Loop (LP-1) — Public API
2
+ * Self-Harness Loop — Public API
3
3
  *
4
4
  * Failure Trace Collection + Weakness Mining.
5
5
  *
@@ -1,5 +1,5 @@
1
1
  /**
2
- * Types for the Self-Harness Loop (LP-1).
2
+ * Types for the Self-Harness Loop.
3
3
  *
4
4
  * Failure signatures represent concrete failure events detected during
5
5
  * agent operation. Weakness clusters group similar signatures to identify
@@ -45,12 +45,25 @@ export {
45
45
  closeWorker,
46
46
  recordWorkerMerge,
47
47
  validateResultSchema,
48
+ locateResultSchema,
48
49
  evaluateWorker,
49
50
  checkWorker,
50
51
  computeWorkerStats,
51
52
  WORKER_EFFECT_EVIDENCE_FLAG,
52
53
  workerEffectEvidence,
53
54
  workerEffectEvidenceForEntry,
55
+ firstCommandToken,
56
+ findTopLevelDecoration,
57
+ findGateRowViolation,
58
+ closeGateRefusalLogPath,
59
+ logCloseGateRefusal,
60
+ parsePopulationStamp,
61
+ readPopulationStamps,
62
+ populationRefusalDetail,
63
+ productionWriteClassPath,
64
+ readProductionWriteClass,
65
+ readProductionWrites,
66
+ productionWriteRefusalDetail,
54
67
  } from "./workers.js";
55
68
 
56
69
  export type {
@@ -75,4 +88,17 @@ export type {
75
88
  WorkerEffectFacts,
76
89
  WorkerStats,
77
90
  WorkerLatencySummary,
91
+ GateRowPredicate,
92
+ GateRowViolation,
93
+ CloseGateRefusalRecord,
94
+ ResultSchemaLocation,
95
+ PopulationStamp,
96
+ PopulationVerdict,
97
+ PopulationRowRead,
98
+ PopulationRead,
99
+ PopulationCensus,
100
+ ProductionWriteRule,
101
+ ProductionWriteClass,
102
+ ProductionWriteRowRead,
103
+ ProductionWriteRead,
78
104
  } from "./workers.js";