loopforge 3.7.0 → 3.8.1

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 (151) hide show
  1. package/LICENSE +21 -21
  2. package/README.md +171 -157
  3. package/dist/audit.d.ts +53 -1
  4. package/dist/audit.d.ts.map +1 -1
  5. package/dist/audit.js +106 -22
  6. package/dist/audit.js.map +1 -1
  7. package/dist/canonical-state.d.ts +75 -69
  8. package/dist/canonical-state.d.ts.map +1 -1
  9. package/dist/canonical-state.js +276 -168
  10. package/dist/canonical-state.js.map +1 -1
  11. package/dist/cli.d.ts.map +1 -1
  12. package/dist/cli.js +111 -12
  13. package/dist/cli.js.map +1 -1
  14. package/dist/cognitive-facts.d.ts +13 -0
  15. package/dist/cognitive-facts.d.ts.map +1 -1
  16. package/dist/cognitive-facts.js +30 -16
  17. package/dist/cognitive-facts.js.map +1 -1
  18. package/dist/cognitive-governance.d.ts +30 -6
  19. package/dist/cognitive-governance.d.ts.map +1 -1
  20. package/dist/cognitive-governance.js +74 -18
  21. package/dist/cognitive-governance.js.map +1 -1
  22. package/dist/committed-round.d.ts +109 -24
  23. package/dist/committed-round.d.ts.map +1 -1
  24. package/dist/committed-round.js +235 -52
  25. package/dist/committed-round.js.map +1 -1
  26. package/dist/contract-items.d.ts +55 -0
  27. package/dist/contract-items.d.ts.map +1 -0
  28. package/dist/contract-items.js +180 -0
  29. package/dist/contract-items.js.map +1 -0
  30. package/dist/enforcement-gate.d.ts +43 -20
  31. package/dist/enforcement-gate.d.ts.map +1 -1
  32. package/dist/enforcement-gate.js +269 -378
  33. package/dist/enforcement-gate.js.map +1 -1
  34. package/dist/engine.d.ts +11 -6
  35. package/dist/engine.d.ts.map +1 -1
  36. package/dist/engine.js +102 -67
  37. package/dist/engine.js.map +1 -1
  38. package/dist/evidence-claims.d.ts +4 -4
  39. package/dist/evidence-claims.d.ts.map +1 -1
  40. package/dist/evidence-claims.js +16 -14
  41. package/dist/evidence-claims.js.map +1 -1
  42. package/dist/evidence-provider.d.ts +91 -90
  43. package/dist/evidence-provider.d.ts.map +1 -1
  44. package/dist/evidence-provider.js +349 -160
  45. package/dist/evidence-provider.js.map +1 -1
  46. package/dist/explain.d.ts +76 -0
  47. package/dist/explain.d.ts.map +1 -0
  48. package/dist/explain.js +127 -0
  49. package/dist/explain.js.map +1 -0
  50. package/dist/generate-schema.js +250 -53
  51. package/dist/generate-schema.js.map +1 -1
  52. package/dist/index.d.ts +8 -7
  53. package/dist/index.d.ts.map +1 -1
  54. package/dist/index.js +7 -6
  55. package/dist/index.js.map +1 -1
  56. package/dist/loop-compiler.d.ts +41 -40
  57. package/dist/loop-compiler.d.ts.map +1 -1
  58. package/dist/loop-compiler.js +275 -515
  59. package/dist/loop-compiler.js.map +1 -1
  60. package/dist/loop-extras-parser.d.ts +0 -1
  61. package/dist/loop-extras-parser.d.ts.map +1 -1
  62. package/dist/loop-extras-parser.js +0 -4
  63. package/dist/loop-extras-parser.js.map +1 -1
  64. package/dist/loop-projection.d.ts.map +1 -1
  65. package/dist/loop-projection.js +3 -1
  66. package/dist/loop-projection.js.map +1 -1
  67. package/dist/mcp/round-lifecycle.d.ts +40 -21
  68. package/dist/mcp/round-lifecycle.d.ts.map +1 -1
  69. package/dist/mcp/round-lifecycle.js +173 -120
  70. package/dist/mcp/round-lifecycle.js.map +1 -1
  71. package/dist/mcp/server.d.ts.map +1 -1
  72. package/dist/mcp/server.js +63 -10
  73. package/dist/mcp/server.js.map +1 -1
  74. package/dist/mcp/session.d.ts +53 -7
  75. package/dist/mcp/session.d.ts.map +1 -1
  76. package/dist/mcp/session.js +240 -139
  77. package/dist/mcp/session.js.map +1 -1
  78. package/dist/mcp/submission-boundary.d.ts +89 -0
  79. package/dist/mcp/submission-boundary.d.ts.map +1 -0
  80. package/dist/mcp/submission-boundary.js +203 -0
  81. package/dist/mcp/submission-boundary.js.map +1 -0
  82. package/dist/mcp/tools.d.ts.map +1 -1
  83. package/dist/mcp/tools.js +377 -125
  84. package/dist/mcp/tools.js.map +1 -1
  85. package/dist/policy-metrics.js +2 -2
  86. package/dist/policy-metrics.js.map +1 -1
  87. package/dist/policy.d.ts +65 -95
  88. package/dist/policy.d.ts.map +1 -1
  89. package/dist/policy.js +151 -39
  90. package/dist/policy.js.map +1 -1
  91. package/dist/prompt-assembler.d.ts +7 -33
  92. package/dist/prompt-assembler.d.ts.map +1 -1
  93. package/dist/prompt-assembler.js +313 -473
  94. package/dist/prompt-assembler.js.map +1 -1
  95. package/dist/prompt-policy.d.ts +1 -4
  96. package/dist/prompt-policy.d.ts.map +1 -1
  97. package/dist/prompt-policy.js +6 -7
  98. package/dist/prompt-policy.js.map +1 -1
  99. package/dist/protocol.d.ts +411 -168
  100. package/dist/protocol.d.ts.map +1 -1
  101. package/dist/protocol.js +23 -69
  102. package/dist/protocol.js.map +1 -1
  103. package/dist/replay.js +2 -2
  104. package/dist/replay.js.map +1 -1
  105. package/dist/round-contract.d.ts +69 -57
  106. package/dist/round-contract.d.ts.map +1 -1
  107. package/dist/round-contract.js +104 -64
  108. package/dist/round-contract.js.map +1 -1
  109. package/dist/round-coordinator.d.ts +55 -16
  110. package/dist/round-coordinator.d.ts.map +1 -1
  111. package/dist/round-coordinator.js +179 -57
  112. package/dist/round-coordinator.js.map +1 -1
  113. package/dist/round-driver.d.ts +7 -5
  114. package/dist/round-driver.d.ts.map +1 -1
  115. package/dist/round-driver.js +2 -1
  116. package/dist/round-driver.js.map +1 -1
  117. package/dist/round-facts.d.ts +96 -0
  118. package/dist/round-facts.d.ts.map +1 -0
  119. package/dist/round-facts.js +216 -0
  120. package/dist/round-facts.js.map +1 -0
  121. package/dist/round-transaction.d.ts +23 -9
  122. package/dist/round-transaction.d.ts.map +1 -1
  123. package/dist/round-transaction.js +99 -22
  124. package/dist/round-transaction.js.map +1 -1
  125. package/dist/self-eval.d.ts +127 -11
  126. package/dist/self-eval.d.ts.map +1 -1
  127. package/dist/self-eval.js +517 -36
  128. package/dist/self-eval.js.map +1 -1
  129. package/dist/subgoal-state.d.ts +77 -0
  130. package/dist/subgoal-state.d.ts.map +1 -0
  131. package/dist/subgoal-state.js +198 -0
  132. package/dist/subgoal-state.js.map +1 -0
  133. package/dist/token-utils.d.ts +52 -19
  134. package/dist/token-utils.d.ts.map +1 -1
  135. package/dist/token-utils.js +83 -72
  136. package/dist/token-utils.js.map +1 -1
  137. package/dist/verification-gate.d.ts +27 -46
  138. package/dist/verification-gate.d.ts.map +1 -1
  139. package/dist/verification-gate.js +308 -557
  140. package/dist/verification-gate.js.map +1 -1
  141. package/dist/version.d.ts +5 -0
  142. package/dist/version.d.ts.map +1 -0
  143. package/dist/version.js +5 -0
  144. package/dist/version.js.map +1 -0
  145. package/dist/workspace.d.ts +9 -0
  146. package/dist/workspace.d.ts.map +1 -1
  147. package/dist/workspace.js +17 -0
  148. package/dist/workspace.js.map +1 -1
  149. package/loop_policy.json +17 -25
  150. package/package.json +7 -7
  151. package/skills/perception/SKILL.md +266 -64
package/LICENSE CHANGED
@@ -1,21 +1,21 @@
1
- MIT License
2
-
3
- Copyright (c) 2026 LoopForge contributors
4
-
5
- Permission is hereby granted, free of charge, to any person obtaining a copy
6
- of this software and associated documentation files (the "Software"), to deal
7
- in the Software without restriction, including without limitation the rights
8
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
- copies of the Software, and to permit persons to whom the Software is
10
- furnished to do so, subject to the following conditions:
11
-
12
- The above copyright notice and this permission notice shall be included in all
13
- copies or substantial portions of the Software.
14
-
15
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
- SOFTWARE.
1
+ MIT License
2
+
3
+ Copyright (c) 2026 LoopForge contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,157 +1,171 @@
1
- # LoopForge
2
-
3
- **A context window is not memory. Memory needs a runtime.**
4
-
5
- > **v3.7.0** — `npm install -g loopforge`. Node.js ≥ 18. Zero runtime dependencies.
6
- > [中文文档](../README.zh-CN.md)
7
-
8
- ---
9
-
10
- ## The real problems with long-horizon tasks
11
-
12
- Any AI coding agent, given a long enough task, hits three walls. Not because the model isn't smart enough. Not because the context window isn't large enough. These are **architectural** problems.
13
-
14
- ### Problem 1: The summary cascade
15
-
16
- Context fills up → compress. Fills up again → compress again. The third compression is a summary of a summary of a summary. Every cycle evaporates information — critical constraints get silently deleted because the summarizer judged them "no longer relevant." Researchers found that after 3–4 summary cycles, constraint violation rates spike from 0% to 59%. The agent doesn't know what it forgot, because the forgetting itself was compressed away.
17
-
18
- ### Problem 2: Self-correction doesn't work
19
-
20
- Models cannot reliably improve themselves through introspection — they talk themselves out of correct answers. Effective recovery requires an **external verifier** — an independent observer that doesn't share the agent's context, doesn't participate in its reasoning, and only looks at inputs and outputs.
21
-
22
- ### Problem 3: Compound error (p^N)
23
-
24
- If each step succeeds with probability p, N sequential steps succeed with probability p^N. Frontier agents nail nearly 100% of tasks under 4 minutes but crater to under 10% on tasks over 4 hours. Small errors at each step become the correct input for the next step.
25
-
26
- **These three problems amplify each other. The summary cascade loses information → lost information becomes errors → the agent can't self-correct because those errors look reasonable within its own context.**
27
-
28
- ---
29
-
30
- ## What LoopForge does about it
31
-
32
- LoopForge runs outside the agent and owns the boundary between rounds. Its
33
- design has two explicit sources:
34
-
35
- - **One factual source:** committed typed round documents in the Vault.
36
- - **One cognitive source:** Canonical State compiled from those facts.
37
-
38
- `loopforge_next` accepts a structured evaluation. The core fields `success`,
39
- `output_summary`, `constraint_violations`, and `should_continue` are strict;
40
- optional fields are normalized. Invalid input returns `evaluation_invalid` and
41
- can be corrected with the same `roundId` without saving session state, writing
42
- a round, entering either gate, or changing metrics.
43
-
44
- Valid submissions pass through evidence collection, a verification gate
45
- organized into four domains (evaluation consistency, evidence integrity, plan
46
- & contract, progress & recovery), and an enforcement gate driven by one
47
- ordered strategy table across four action classes (evidence contradiction,
48
- contract & scope, plan drift, progress recovery). Only an allowed round joins
49
- committed history. The shared internal `CommittedRoundView` gives Replay,
50
- Audit, Metrics, contracts, the compiler, and gate history one decoder and one
51
- filtering policy. It does not create another storage format.
52
-
53
- The compiler evolves Canonical State from committed history, then derives
54
- focus, todo, phase, delegation, and handoff for prompts and status views. The
55
- next prompt therefore comes from typed cognitive state, not from a summary of
56
- the previous prompt.
57
-
58
- ```text
59
- Traditional: prompt -> summary -> next prompt -> another summary
60
- LoopForge: committed rounds -> Canonical State -> next prompt
61
- ```
62
-
63
- The verification gate compares claims with Git snapshots, test output, and
64
- configured command evidence. The enforcement gate can accept, reject,
65
- backtrack, or terminate. A rejected submission commits nothing. A stalled-
66
- progress evaluator can restore the last clean round, inject a diagnosis, and
67
- verify workspace restoration before work continues.
68
-
69
- ---
70
-
71
- ## What LoopForge is not
72
-
73
- - **Not a memory database.** The optional state file is derived. Committed
74
- rounds hold facts, and Canonical State supplies runtime cognition.
75
- - **Not a context compressor.** It recompiles prompts from typed state instead
76
- of compressing the prior prompt.
77
- - **Not a constraint tracker.** Constraints are one input to external judgment.
78
- - **Not an agent or unattended executor.** The external agent owns planning,
79
- code changes, and tool use. LoopForge governs round transitions.
80
-
81
- ---
82
-
83
- ## Install
84
-
85
- ```bash
86
- npm install -g loopforge
87
- loopforge init --client claude
88
- claude mcp add loopforge -- npx loopforge mcp
89
- ```
90
-
91
- Works with Claude Code, Codex CLI, or any MCP-compatible client.
92
-
93
- The MCP server path (`loopforge mcp`) is the primary integration. It provides
94
- the full cognitive infrastructure: verification gate, enforcement gate,
95
- backtrack, evidence collection, and crash recovery. The engine is also
96
- available as a library for custom integrations.
97
-
98
- ---
99
-
100
- ## Architecture
101
-
102
- ```text
103
- External agent
104
- -> structured evaluation
105
- -> evidence / verification / enforcement
106
- -> accept, reject, backtrack, or terminate
107
- reject / terminate: no round commit
108
- accept / stop / backtrack: commit transaction decision
109
- -> committed round documents [factual source]
110
- -> CommittedRoundView [shared read model]
111
- -> Replay [what happened]
112
- -> Audit / Metrics [evidence and diagnostics]
113
- -> Canonical State [cognitive source]
114
- -> DerivedCognitiveFacts
115
- -> prompt / state file / status
116
- -> external agent, next round
117
- ```
118
-
119
- ---
120
-
121
- ## Key capabilities
122
-
123
- - Structured evaluation with strict core fields, lenient optional normalization,
124
- and retryable `evaluation_invalid` responses.
125
- - One committed-round history for the compiler, contracts, gates, Replay,
126
- Audit, and Metrics.
127
- - One Canonical State for prompts, the optional state file, and current-status
128
- cognition.
129
- - Evidence-backed accept, reject, backtrack, and terminate decisions, including
130
- Round Contract and workspace-restore checks.
131
- - L0, L1, and L2 prompt density, five-state sub-goals, constraint lifecycle,
132
- milestones, and agent-requested emphasis or confusion points.
133
- - Separate Replay and Audit views. Replay answers what happened; Audit checks
134
- evidence and completeness.
135
- - Durable sessions with atomic round documents, sequence checks, owned locks,
136
- renewable leases, pause, resume, and idempotent recovery.
137
- - Nine MCP tools: `start`, `next`, `status`, `stop`, `pause`, `resume`, `replay`,
138
- `gate_check`, and `gate_resolve`.
139
- - Zero runtime dependencies. Policy controls thresholds, budgets, and intervals.
140
-
141
- ---
142
-
143
- ## Development
144
-
145
- ```bash
146
- npm run check
147
- npm test
148
- npm pack --dry-run --json
149
- ```
150
-
151
- The protocol schema in `../loopforge-protocol.json` is generated from `src/protocol.ts`. Do not edit it by hand.
152
-
153
- ---
154
-
155
- ## License
156
-
157
- MIT
1
+ # LoopForge
2
+
3
+ **A context window is not memory. Memory needs a runtime.**
4
+
5
+ > **Version per `package.json`** — `npm install -g loopforge`. Node.js ≥ 18. Zero runtime dependencies.
6
+ > [中文文档](../README.zh-CN.md)
7
+
8
+ ---
9
+
10
+ ## The real problems with long-horizon tasks
11
+
12
+ Any AI coding agent, given a long enough task, hits three walls. Not because the model isn't smart enough. Not because the context window isn't large enough. These are **architectural** problems.
13
+
14
+ ### Problem 1: The summary cascade
15
+
16
+ Context fills up → compress. Fills up again → compress again. The third compression is a summary of a summary of a summary. Every cycle evaporates information — critical constraints get silently deleted because the summarizer judged them "no longer relevant." Researchers found that after 3–4 summary cycles, constraint violation rates spike from 0% to 59%. The agent doesn't know what it forgot, because the forgetting itself was compressed away.
17
+
18
+ ### Problem 2: Self-correction doesn't work
19
+
20
+ Models cannot reliably improve themselves through introspection — they talk themselves out of correct answers. Effective recovery requires an **external verifier** — an independent observer that doesn't share the agent's context, doesn't participate in its reasoning, and only looks at inputs and outputs.
21
+
22
+ ### Problem 3: Compound error (p^N)
23
+
24
+ If each step succeeds with probability p, N sequential steps succeed with probability p^N. Frontier agents nail nearly 100% of tasks under 4 minutes but crater to under 10% on tasks over 4 hours. Small errors at each step become the correct input for the next step.
25
+
26
+ **These three problems amplify each other. The summary cascade loses information → lost information becomes errors → the agent can't self-correct because those errors look reasonable within its own context.**
27
+
28
+ ---
29
+
30
+ ## What LoopForge does about it
31
+
32
+ LoopForge runs outside the agent and owns the boundary between rounds. Its
33
+ design has two explicit sources:
34
+
35
+ - **One factual source:** committed typed round documents in the Vault.
36
+ - **One cognitive source:** Canonical State compiled from those facts.
37
+
38
+ `loopforge_next` accepts a structured evaluation. The core fields `success`,
39
+ `output_summary`, `constraint_violations`, and `should_continue` are strict;
40
+ optional fields are normalized. Invalid input returns `evaluation_invalid` and
41
+ can be corrected with the same `roundId` without saving session state, writing
42
+ a round, entering either gate, or changing metrics.
43
+
44
+ Valid submissions pass through evidence collection, a verification gate
45
+ organized into four domains (evaluation consistency, evidence integrity, plan
46
+ & contract, progress & recovery), and an enforcement gate driven by one
47
+ ordered strategy table — the row order is the priority, and each row names
48
+ the check it reacts to plus its escalation ladder. Only an allowed round joins
49
+ committed history. The shared internal `CommittedRoundView` gives Replay,
50
+ Audit, Metrics, contracts, the compiler, and gate history one decoder and one
51
+ filtering policy. It does not create another storage format.
52
+
53
+ The compiler evolves Canonical State from committed history, then derives
54
+ focus, todo, phase, delegation, and handoff for prompts and status views. The
55
+ next prompt therefore comes from typed cognitive state, not from a summary of
56
+ the previous prompt.
57
+
58
+ ```text
59
+ Traditional: prompt -> summary -> next prompt -> another summary
60
+ LoopForge: committed rounds -> Canonical State -> next prompt
61
+ ```
62
+
63
+ The verification gate compares claims with Git snapshots, test output, and
64
+ configured command evidence. The enforcement gate can accept, reject,
65
+ backtrack, or terminate. A rejected submission commits nothing. A stalled-
66
+ progress evaluator can restore the last clean round, inject a diagnosis, and
67
+ verify workspace restoration before work continues.
68
+
69
+ ---
70
+
71
+ ## What LoopForge is not
72
+
73
+ - **Not a memory database.** The optional state file is derived. Committed
74
+ rounds hold facts, and Canonical State supplies runtime cognition.
75
+ - **Not a context compressor.** It recompiles prompts from typed state instead
76
+ of compressing the prior prompt.
77
+ - **Not a constraint tracker.** Constraints are one input to external judgment.
78
+ - **Not an agent or unattended executor.** The external agent owns planning,
79
+ code changes, and tool use. LoopForge governs round transitions.
80
+
81
+ ---
82
+
83
+ ## Install
84
+
85
+ ```bash
86
+ npm install -g loopforge
87
+ loopforge init --client claude
88
+ claude mcp add loopforge -- npx loopforge mcp
89
+ ```
90
+
91
+ Works with Claude Code, Codex CLI, or any MCP-compatible client.
92
+
93
+ The MCP server path (`loopforge mcp`) is the primary integration. It provides
94
+ the full cognitive infrastructure: verification gate, enforcement gate,
95
+ backtrack, evidence collection, and crash recovery. The engine is also
96
+ available as a library for custom integrations.
97
+
98
+ ---
99
+
100
+ ## Architecture
101
+
102
+ ```text
103
+ External agent
104
+ -> structured evaluation
105
+ -> evidence / verification / enforcement
106
+ -> accept, reject, backtrack, or terminate
107
+ reject / terminate: no round commit
108
+ accept / stop / backtrack: commit transaction decision
109
+ -> committed round documents [factual source]
110
+ -> CommittedRoundView [shared read model]
111
+ -> Replay [what happened]
112
+ -> Audit / Metrics [evidence and diagnostics]
113
+ -> Canonical State [cognitive source]
114
+ -> DerivedCognitiveFacts
115
+ -> prompt / state file / status
116
+ -> external agent, next round
117
+ ```
118
+
119
+ ---
120
+
121
+ ## Key capabilities
122
+
123
+ - Structured evaluation with strict core fields, lenient optional normalization,
124
+ and retryable `evaluation_invalid` responses.
125
+ - One committed-round history for the compiler, contracts, gates, Replay,
126
+ Audit, and Metrics.
127
+ - One Canonical State for prompts, the optional state file, and current-status
128
+ cognition.
129
+ - Evidence-backed accept, reject, backtrack, and terminate decisions, including
130
+ Round Contract and workspace-restore checks. A backtrack carries a derived
131
+ Recovery Brief — trigger rule, restore point, redo round ID, failed
132
+ approaches, and falsified assumptions — sourced from committed rounds plus
133
+ the in-flight attempt (never rejected payloads); the redo reuses the round
134
+ ID and its commit retires the brief.
135
+ - L0, L1, and L2 prompt density, five-state sub-goals with explicit
136
+ `subgoal_updates` transitions (active `sg-` IDs only; done/canceled are
137
+ terminal), constraint lifecycle, milestones, and agent-requested emphasis
138
+ (by stable id or exact text) or confusion points. Prompts and the state file
139
+ render active sub-goals only, capped by policy; the state file is grouped
140
+ into Current / Recent / Historical Summary tiers with derived metadata
141
+ (round, attempt, state hash) and is byte-identical when regenerated from the
142
+ Vault — its content depends on committed facts, not on which prompt level
143
+ compiled.
144
+ - Separate Replay and Audit views. Replay answers what happened; Audit checks
145
+ evidence and completeness.
146
+ - Durable sessions with atomic round documents, sequence checks, owned locks,
147
+ renewable leases, pause, resume, and idempotent recovery.
148
+ - Nine MCP tools: `start`, `next`, `status`, `stop`, `pause`, `resume`, `replay`,
149
+ `gate_check`, and `gate_resolve`. The two gate tools are opt-in
150
+ (`policy.gate.enabled`, default false): hidden from `tools/list`, structured
151
+ preflight via `gate_check`, round-blocking on unapproved `gate_ids`
152
+ citations.
153
+ - Zero runtime dependencies. Policy controls thresholds, budgets, and intervals.
154
+
155
+ ---
156
+
157
+ ## Development
158
+
159
+ ```bash
160
+ npm run check
161
+ npm test
162
+ npm pack --dry-run --json
163
+ ```
164
+
165
+ The protocol schema in `../loopforge-protocol.json` is generated from `src/protocol.ts`. Do not edit it by hand.
166
+
167
+ ---
168
+
169
+ ## License
170
+
171
+ MIT
package/dist/audit.d.ts CHANGED
@@ -4,21 +4,39 @@
4
4
  * happened per round); audit is the assessment layer (which claims are
5
5
  * machine-verified, which gates were decided, is the sequence intact).
6
6
  * Everything is derived from committed vault entries — audit never writes.
7
+ *
8
+ * v3.8: the CONTRACT ITEM axis is the primary completion basis. The criterion
9
+ * claims stay as an advisory second view — a criterion claim is an agent
10
+ * statement whose machine backing is mediated by the contract items, so it
11
+ * cannot be the completion signal. Both axes read the same committed-round
12
+ * model and the same item reducer the coordinator and explain use.
7
13
  */
8
14
  import type { LoopStore } from "./loop-store.js";
9
15
  import type { VaultEntry } from "./loop-store.js";
16
+ import type { ContractItemStatus } from "./protocol.js";
10
17
  export interface AuditRound {
11
18
  round: number;
12
19
  outcome: string;
13
20
  claims: Array<{
14
21
  text: string;
15
- status: "verified" | "unverified" | "no_evidence";
22
+ status: "verified" | "unverified";
16
23
  }>;
17
24
  checks: Array<{
18
25
  check: string;
19
26
  severity: string;
20
27
  verdict: "failed" | "warn" | "info";
21
28
  }>;
29
+ /** v3.8: the contract this round EXECUTED under and each item's status as of
30
+ * this round — the same derivation `explain` renders. */
31
+ contract: {
32
+ id: string;
33
+ declared_at_round: number;
34
+ closure: string;
35
+ items: Array<{
36
+ itemId: string;
37
+ status: ContractItemStatus;
38
+ }>;
39
+ } | null;
22
40
  }
23
41
  export interface AuditGate {
24
42
  gateId: string;
@@ -28,12 +46,42 @@ export interface AuditGate {
28
46
  decidedAt: string;
29
47
  round: number;
30
48
  }
49
+ /** v3.8: One contract's outcome over the loaned loop, keyed by its content-
50
+ * addressed id. Re-declaring the same contract later extends the same entry —
51
+ * the identity says it IS the same contract. */
52
+ export interface AuditContract {
53
+ contract_id: string;
54
+ declared_at_round: number;
55
+ first_active_round: number;
56
+ last_active_round: number;
57
+ closure: "open" | "verified" | "blocked";
58
+ closed_at_round: number | null;
59
+ /** Item statuses as of the last round the contract was execution-relevant. */
60
+ items: Array<{
61
+ itemId: string;
62
+ description: string;
63
+ status: ContractItemStatus;
64
+ }>;
65
+ }
66
+ export interface AuditContractSummary {
67
+ contracts: AuditContract[];
68
+ /** Contracts whose final closure is still `open`. */
69
+ open: number;
70
+ verifiedItems: number;
71
+ insufficientItems: number;
72
+ contradictedItems: number;
73
+ pendingItems: number;
74
+ }
31
75
  export interface AuditResult {
32
76
  loopId: string;
33
77
  verdict: "passed" | "incomplete" | "contradicted";
34
78
  rounds: AuditRound[];
35
79
  gates: AuditGate[];
36
80
  unresolvedUserGates: string[];
81
+ /** v3.8: the verification skeleton — the primary completion basis. */
82
+ contracts: AuditContractSummary;
83
+ /** Advisory second axis: criterion claims, not the completion signal.
84
+ * `declared` and `evidenced` are both DISTINCT-id counts, so they compare. */
37
85
  criteria: {
38
86
  declared: number;
39
87
  evidenced: number;
@@ -42,6 +90,10 @@ export interface AuditResult {
42
90
  sequenceComplete: boolean;
43
91
  /** False when no LoopStore was provided (sequence/provenance degraded). */
44
92
  provenanceAvailable: boolean;
93
+ /** v3.8: rounds whose persisted transaction carries a legacy schema
94
+ * version. They are NOT part of history (the version break is hard) — this
95
+ * list makes the loss visible instead of letting the loop look complete. */
96
+ legacyRounds: number[];
45
97
  }
46
98
  /** Build the audit from committed vault entries. Pure, read-only.
47
99
  * @param store Optional LoopStore — when provided, sequence integrity is
@@ -1 +1 @@
1
- {"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../src/audit.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAIjD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAIlD,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,UAAU,GAAG,YAAY,GAAG,aAAa,CAAA;KAAE,CAAC,CAAC;IACnF,MAAM,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC,CAAC;CACzF;AAED,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,OAAO,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,QAAQ,GAAG,YAAY,GAAG,cAAc,CAAC;IAClD,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B,QAAQ,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IACnE,gBAAgB,EAAE,OAAO,CAAC;IAC1B,2EAA2E;IAC3E,mBAAmB,EAAE,OAAO,CAAC;CAC9B;AAED;;oDAEoD;AACpD,wBAAgB,UAAU,CACxB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,UAAU,EAAE,EACrB,KAAK,CAAC,EAAE,SAAS,GAChB,WAAW,CA8Gb"}
1
+ {"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../src/audit.ts"],"names":[],"mappings":"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"}