@cassiomc1/forgeloop 2.1.0 → 2.3.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 (67) hide show
  1. package/CONTRIBUTING.md +22 -2
  2. package/DOCS_INDEX.md +4 -13
  3. package/ENG/sec-code-eng.md +1 -1
  4. package/ENG/test-code-eng.md +32 -1
  5. package/LOOP_SYSTEM_DESIGN.md +2 -3
  6. package/QUALITY_SCORECARD.md +0 -1
  7. package/README.md +19 -48
  8. package/THIRD_PARTY_NOTICES.md +0 -15
  9. package/completions/_forgeloop +7 -1
  10. package/completions/forgeloop.bash +13 -1
  11. package/completions/forgeloop.fish +51 -1
  12. package/docs/AGENT_PROTOCOL_SUMMARY.md +7 -1
  13. package/docs/ARTIFACT_REFERENCE.md +1 -0
  14. package/docs/CLI_REFERENCE.md +111 -3
  15. package/docs/CODE_ATTESTATION.md +16 -7
  16. package/docs/DOCUMENTATION_GUIDE.md +10 -28
  17. package/docs/PACKAGE_CONTENTS.md +0 -3
  18. package/docs/RELEASE_CHECKLIST.md +81 -15
  19. package/docs/REVISION_PROVIDERS.md +3 -6
  20. package/docs/TROUBLESHOOTING.md +11 -0
  21. package/docs/documentation-manifest.json +0 -13
  22. package/package.json +2 -6
  23. package/schemas/config.schema.json +1 -0
  24. package/scripts/CI_VALIDATORS.md +2 -2
  25. package/src/cli.js +31 -0
  26. package/src/commands/assess.js +36 -0
  27. package/src/commands/attestation-create.js +21 -1
  28. package/src/commands/complete.js +3 -0
  29. package/src/commands/evidence-export.js +17 -0
  30. package/src/commands/evidence-publish.js +22 -0
  31. package/src/commands/evidence-verify.js +36 -0
  32. package/src/commands/sync-pull.js +111 -0
  33. package/src/commands/sync-push.js +52 -0
  34. package/src/core/assessment/facts.js +146 -0
  35. package/src/core/assessment/plan.js +133 -0
  36. package/src/core/audit.js +7 -0
  37. package/src/core/cli-command-definitions.js +88 -0
  38. package/src/core/command-executors.js +42 -5
  39. package/src/core/config.js +44 -37
  40. package/src/core/error-codes.js +70 -0
  41. package/src/core/evidence/auto-export.js +61 -0
  42. package/src/core/evidence/bundle-format.js +74 -0
  43. package/src/core/evidence/export.js +184 -0
  44. package/src/core/evidence/markdown.js +40 -0
  45. package/src/core/evidence/publish.js +187 -0
  46. package/src/core/evidence/verify.js +179 -0
  47. package/src/core/integration-invocation-policy.js +5 -2
  48. package/src/core/sync/merge.js +135 -0
  49. package/src/core/sync/remote.js +124 -0
  50. package/src/core/sync/snapshot.js +129 -0
  51. package/docs/assets/diagrams/forgeloop-code-attestation-flow.html +0 -13852
  52. package/docs/assets/diagrams/forgeloop-code-attestation-flow.receipt.json +0 -37
  53. package/docs/assets/diagrams/forgeloop-code-attestation-flow.svg +0 -5055
  54. package/docs/assets/diagrams/forgeloop-engineering-flow.html +0 -13837
  55. package/docs/assets/diagrams/forgeloop-engineering-flow.receipt.json +0 -37
  56. package/docs/assets/diagrams/forgeloop-engineering-flow.svg +0 -5011
  57. package/docs/assets/diagrams/forgeloop-verification-trust-flow.html +0 -13795
  58. package/docs/assets/diagrams/forgeloop-verification-trust-flow.receipt.json +0 -37
  59. package/docs/assets/diagrams/forgeloop-verification-trust-flow.svg +0 -4997
  60. package/docs/diagrams/README.md +0 -103
  61. package/docs/diagrams/forgeloop-code-attestation-flow.workflow.json +0 -451
  62. package/docs/diagrams/forgeloop-engineering-flow.workflow.json +0 -459
  63. package/docs/diagrams/forgeloop-verification-trust-flow.workflow.json +0 -398
  64. package/docs/diagrams/manifest.json +0 -84
  65. package/docs/diagrams/reviews/forgeloop-code-attestation-flow.review.json +0 -20
  66. package/docs/diagrams/reviews/forgeloop-engineering-flow.review.json +0 -20
  67. package/docs/diagrams/reviews/forgeloop-verification-trust-flow.review.json +0 -20
@@ -1,103 +0,0 @@
1
- # Documentation diagrams
2
-
3
- ForgeLoop maintains three canonical P0 visuals in typed Archify workflow IR.
4
- The manifest is the governance source for their identities, canonical
5
- purposes, renderer mapping, artifact ownership, references, and review files:
6
-
7
- | Visual | Canonical purpose | Source | Explorer | SVG fallback |
8
- | --- | --- | --- | --- | --- |
9
- | Engineering Flow | `high-level-engineering-flow` | [`forgeloop-engineering-flow.workflow.json`](./forgeloop-engineering-flow.workflow.json) | [HTML](../assets/diagrams/forgeloop-engineering-flow.html) | [SVG](../assets/diagrams/forgeloop-engineering-flow.svg) |
10
- | Verification Trust Flow | `differential-verification-trust-boundary` | [`forgeloop-verification-trust-flow.workflow.json`](./forgeloop-verification-trust-flow.workflow.json) | [HTML](../assets/diagrams/forgeloop-verification-trust-flow.html) | [SVG](../assets/diagrams/forgeloop-verification-trust-flow.svg) |
11
- | Code Attestation Chain | `code-attestation-chain` | [`forgeloop-code-attestation-flow.workflow.json`](./forgeloop-code-attestation-flow.workflow.json) | [HTML](../assets/diagrams/forgeloop-code-attestation-flow.html) | [SVG](../assets/diagrams/forgeloop-code-attestation-flow.svg) |
12
-
13
- Each visual also has a deterministic [receipt directory](../assets/diagrams/)
14
- entry and a source-bound [review directory](./reviews/). The Engineering Flow
15
- is the conceptual lifecycle; the Verification Trust Flow explains the
16
- fail-closed Differential Verification boundary; and the Code Attestation Chain
17
- explains exact-content provenance, optional signing, and revision-range
18
- coverage. Their text fallbacks remain in
19
- [`README.md`](../../README.md#architecture-flow),
20
- [`REVISION_PROVIDERS.md`](../REVISION_PROVIDERS.md#differential-verification-scope),
21
- and [`CODE_ATTESTATION.md`](../CODE_ATTESTATION.md#completion-flow).
22
-
23
- The canonical sources set `meta.animation` to `trace`, so the explorers and
24
- SVGs trace workflow edges and emphasize active nodes. Use each explorer's
25
- Present, playback, and focus controls for the full animated experience; every
26
- SVG remains available for repository previews and text-only fallbacks.
27
-
28
- The JSON IR is the source of truth. Do not edit the generated HTML or SVG by
29
- hand. Run `npm run docs:diagrams` to regenerate the outputs and
30
- `npm run docs:diagrams:check` to validate the pinned renderer, source semantics,
31
- animation markers, artifact fingerprints, persistent review binding, manifest
32
- ownership, and GitHub-safe SVG constraints.
33
-
34
- The HTML view opens in Archify's dark presentation stage so the official flow
35
- is visible without scrolling; its Present and playback controls expose the
36
- animated trace, while reduced-motion preferences remain respected. The SVG
37
- fallback also carries the trace-capable styles and intentionally defaults to the
38
- dark presentation so it remains legible in repository previews; the adjacent text fallback in
39
- [`README.md`](../../README.md#architecture-flow) carries the same lifecycle
40
- semantics for text-only readers.
41
-
42
- Jev is shown only as a bounded semantic checkpoint outside lifecycle authority.
43
- Its invocation is mandatory where required, but its typed result cannot advance
44
- state, release claims, satisfy gates, create evidence, complete a task, or
45
- authorize publication. Advisory context, including the optional Ripwire adapter,
46
- is intentionally not drawn as a lifecycle node or transition. It is a
47
- host-injected, explicit, non-evidence input that can guide inspection while
48
- remaining outside state, authority, verification, completion, and next-action
49
- decisions. Its boundary is documented in
50
- [`ADVISORY_CONTEXT.md`](../ADVISORY_CONTEXT.md) and
51
- [`RIPWIRE_ADAPTER.md`](../RIPWIRE_ADAPTER.md).
52
-
53
- Archify is vendored at `vendor/archify/v2.15.0/archify` under its MIT license.
54
- The exact source commit and cryptographic vendor-tree hash are recorded in
55
- `vendor/archify/v2.15.0/PIN.json`; generated-file hashes are recorded in the
56
- receipt. A review file binds the current source and SVG fingerprints as a
57
- review assertion; the checker does not independently authenticate the reviewer
58
- or prove that a person inspected the rendered artifact.
59
-
60
- `PIN.json` uses ForgeLoop Archify PIN `schemaVersion: 2`. This version describes
61
- the metadata and integrity-declaration format and is independent of Archify's
62
- upstream release version. A future PIN format change must increment the schema
63
- version and update the validator before new files are accepted; it does not
64
- change the vendored tree digest.
65
-
66
- The ForgeLoop Archify wrapper is intentionally documentation-scoped. It reads
67
- canonical inputs only from `docs/diagrams/` and permits deliver outputs only
68
- under `docs/assets/diagrams/`.
69
-
70
- ForgeLoop governs five documentation-diagram categories: workflow,
71
- architecture, sequence, dataflow, and lifecycle. The current active set uses
72
- three workflow diagrams because the pinned wrapper currently maps only
73
- `workflow`. Governance support does not imply renderer support: a type requires
74
- an explicit renderer mapping before it can be added as an active diagram.
75
- Additional safety-boundary, resume, or provider visuals remain intentionally
76
- deferred until their mappings are proven.
77
-
78
- ## Current behavioral boundaries
79
-
80
- The engineering explorer describes structured obligations, project/task-bound
81
- transactions, and bounded refresh of blocked pre-execution checkpoints. Its
82
- later correction loop still returns through verification.
83
-
84
- The verification explorer distinguishes test filtering from a canonical
85
- verification scope and executed command evidence from explicit manual review.
86
- The attestation explorer distinguishes absent CI receipts (`NOT_VERIFIED`)
87
- from attestation trust levels and notes that payload compaction preserves
88
- transaction manifests and event history.
89
-
90
- These explanations are part of the JSON sources and generated explorers;
91
- matching textual fallbacks live in the README, revision-provider guide, and
92
- attestation guide. Re-render before renewing a visual review, then inspect
93
- the new output at desktop and narrow widths before binding the review hashes.
94
-
95
- The Repository Index and Persistent Search Transport are runtime discovery
96
- boundaries rather than lifecycle transitions. Their current CLI/API/MCP
97
- separation and local IPC sequence are documented in
98
- [`REPOSITORY_INDEX.md`](../REPOSITORY_INDEX.md) and
99
- [`PERSISTENT_SEARCH_TRANSPORT.md`](../PERSISTENT_SEARCH_TRANSPORT.md). They are
100
- intentionally not added as a fourth Archify workflow merely to increase the
101
- diagram count; the README hero provides the conceptual architecture overview,
102
- while these three governed visuals remain focused on lifecycle, verification,
103
- and attestation.
@@ -1,451 +0,0 @@
1
- {
2
- "schema_version": 1,
3
- "diagram_type": "workflow",
4
- "meta": {
5
- "title": "ForgeLoop Code Attestation Chain",
6
- "subtitle": "Exact content binding from valid completion to read-only trust results",
7
- "animation": "trace",
8
- "visual_preset": "signal-flow",
9
- "quality_profile": "showcase",
10
- "views": [
11
- {
12
- "id": "completion-to-manifest",
13
- "label": "Completion to manifest",
14
- "focus": [
15
- "complete",
16
- "receipt",
17
- "manifest",
18
- "captured"
19
- ],
20
- "note": "Completion and exact-content evidence bind to the project and task. No supplied CI receipt means NOT_VERIFIED."
21
- },
22
- {
23
- "id": "manifest-to-statement",
24
- "label": "Manifest to statement",
25
- "focus": [
26
- "manifest",
27
- "captured",
28
- "statement",
29
- "signing",
30
- "bundle"
31
- ],
32
- "note": "See how the deterministic code manifest becomes an in-toto Statement v1 and optional signature bundle."
33
- },
34
- {
35
- "id": "revision-range-coverage",
36
- "label": "Revision-range coverage",
37
- "focus": [
38
- "base",
39
- "provider",
40
- "changed",
41
- "attestations",
42
- "union",
43
- "range"
44
- ],
45
- "note": "Inspect the separate changed-path coverage question and its gap or conflict result."
46
- }
47
- ],
48
- "legend": {
49
- "mode": "auto",
50
- "entries": {
51
- "backend": {
52
- "label": "Protocol state"
53
- },
54
- "database": {
55
- "label": "Content/evidence"
56
- },
57
- "security": {
58
- "label": "Policy boundary"
59
- },
60
- "cloud": {
61
- "label": "Signer"
62
- },
63
- "messagebus": {
64
- "label": "Failure"
65
- },
66
- "external": {
67
- "label": "Completion"
68
- }
69
- }
70
- }
71
- },
72
- "lanes": [
73
- {
74
- "id": "completion",
75
- "label": "Completion Evidence"
76
- },
77
- {
78
- "id": "integrity",
79
- "label": "Content Integrity"
80
- },
81
- {
82
- "id": "providers",
83
- "label": "Provider Boundaries"
84
- },
85
- {
86
- "id": "verification",
87
- "label": "Read-Only Verification"
88
- },
89
- {
90
- "id": "results",
91
- "label": "Attestation Results"
92
- },
93
- {
94
- "id": "coverage",
95
- "label": "Revision-Range Coverage"
96
- },
97
- {
98
- "id": "exceptions",
99
- "label": "Gaps + Conflicts",
100
- "variant": "exception"
101
- }
102
- ],
103
- "phases": [
104
- {
105
- "id": "capture",
106
- "label": "Capture content",
107
- "fromCol": 0,
108
- "toCol": 1
109
- },
110
- {
111
- "id": "statement",
112
- "label": "Bind and sign",
113
- "fromCol": 2,
114
- "toCol": 3,
115
- "variant": "emphasis"
116
- },
117
- {
118
- "id": "range",
119
- "label": "Evaluate coverage",
120
- "fromCol": 4,
121
- "toCol": 5,
122
- "variant": "dashed"
123
- }
124
- ],
125
- "groups": [
126
- {
127
- "id": "completion_binding",
128
- "label": "Completion transaction",
129
- "lane": "integrity",
130
- "fromCol": 0,
131
- "toCol": 3,
132
- "variant": "emphasis"
133
- },
134
- {
135
- "id": "signer_boundary",
136
- "label": "Optional external signer",
137
- "lane": "providers",
138
- "fromCol": 4,
139
- "toCol": 5,
140
- "variant": "security"
141
- },
142
- {
143
- "id": "coverage_boundary",
144
- "label": "Coverage is a separate question",
145
- "lane": "coverage",
146
- "fromCol": 0,
147
- "toCol": 5,
148
- "variant": "dashed"
149
- }
150
- ],
151
- "mainPath": [
152
- "complete",
153
- "receipt",
154
- "manifest",
155
- "captured",
156
- "statement",
157
- "signing",
158
- "bundle",
159
- "verify"
160
- ],
161
- "nodes": [
162
- {
163
- "id": "complete",
164
- "lane": "completion",
165
- "col": 0,
166
- "type": "external",
167
- "label": "VALID",
168
- "sublabel": "completion",
169
- "width": 52
170
- },
171
- {
172
- "id": "receipt",
173
- "lane": "completion",
174
- "col": 1,
175
- "type": "database",
176
- "label": "Receipt",
177
- "sublabel": "ledger",
178
- "width": 54
179
- },
180
- {
181
- "id": "manifest",
182
- "lane": "integrity",
183
- "col": 2,
184
- "type": "database",
185
- "label": "Manifest",
186
- "sublabel": "SHA-256",
187
- "tag": "exact",
188
- "width": 60
189
- },
190
- {
191
- "id": "captured",
192
- "lane": "integrity",
193
- "col": 3,
194
- "type": "security",
195
- "label": "Captured",
196
- "sublabel": "transaction",
197
- "width": 68
198
- },
199
- {
200
- "id": "statement",
201
- "lane": "providers",
202
- "col": 4,
203
- "type": "backend",
204
- "label": "in-toto v1",
205
- "sublabel": "statement",
206
- "width": 72
207
- },
208
- {
209
- "id": "signing",
210
- "lane": "providers",
211
- "col": 5,
212
- "type": "cloud",
213
- "label": "Signer",
214
- "sublabel": "optional",
215
- "tag": "Cosign",
216
- "width": 58
217
- },
218
- {
219
- "id": "bundle",
220
- "lane": "verification",
221
- "col": 5,
222
- "type": "database",
223
- "label": "Bundle",
224
- "sublabel": "policy-bound",
225
- "width": 66
226
- },
227
- {
228
- "id": "verify",
229
- "lane": "results",
230
- "col": 5,
231
- "type": "security",
232
- "label": "Verify",
233
- "sublabel": "read-only",
234
- "tag": "no mutation",
235
- "width": 62
236
- },
237
- {
238
- "id": "base",
239
- "lane": "coverage",
240
- "col": 0,
241
- "type": "cloud",
242
- "label": "Base",
243
- "sublabel": "revision",
244
- "width": 52
245
- },
246
- {
247
- "id": "provider",
248
- "lane": "coverage",
249
- "col": 1,
250
- "type": "backend",
251
- "label": "Rev",
252
- "sublabel": "provider",
253
- "width": 52
254
- },
255
- {
256
- "id": "changed",
257
- "lane": "coverage",
258
- "col": 2,
259
- "type": "database",
260
- "label": "Paths",
261
- "sublabel": "changed",
262
- "width": 52
263
- },
264
- {
265
- "id": "attestations",
266
- "lane": "coverage",
267
- "col": 3,
268
- "type": "backend",
269
- "label": "Attest",
270
- "sublabel": "valid",
271
- "width": 42
272
- },
273
- {
274
- "id": "union",
275
- "lane": "coverage",
276
- "col": 4,
277
- "type": "database",
278
- "label": "Union",
279
- "sublabel": "digests",
280
- "width": 42
281
- },
282
- {
283
- "id": "range",
284
- "lane": "coverage",
285
- "col": 5,
286
- "type": "security",
287
- "label": "Range",
288
- "sublabel": "coverage",
289
- "tag": "no gaps",
290
- "width": 58
291
- },
292
- {
293
- "id": "boundary",
294
- "lane": "exceptions",
295
- "col": 3,
296
- "type": "security",
297
- "label": "Boundary",
298
- "sublabel": "scope/coverage",
299
- "tag": "important",
300
- "width": 74
301
- },
302
- {
303
- "id": "gap",
304
- "lane": "exceptions",
305
- "col": 5,
306
- "type": "messagebus",
307
- "label": "Gap",
308
- "sublabel": "fail closed",
309
- "width": 60
310
- }
311
- ],
312
- "edges": [
313
- {
314
- "id": "complete-receipt",
315
- "from": "complete",
316
- "to": "receipt",
317
- "variant": "emphasis"
318
- },
319
- {
320
- "id": "receipt-manifest",
321
- "from": "receipt",
322
- "to": "manifest",
323
- "variant": "security",
324
- "route": "drop",
325
- "fromSide": "bottom",
326
- "toSide": "top"
327
- },
328
- {
329
- "id": "manifest-captured",
330
- "from": "manifest",
331
- "to": "captured",
332
- "variant": "emphasis"
333
- },
334
- {
335
- "id": "captured-statement",
336
- "from": "captured",
337
- "to": "statement",
338
- "variant": "security",
339
- "route": "drop",
340
- "fromSide": "bottom",
341
- "toSide": "top"
342
- },
343
- {
344
- "id": "statement-signing",
345
- "from": "statement",
346
- "to": "signing",
347
- "variant": "dashed",
348
- "fromSide": "bottom",
349
- "toSide": "top",
350
- "route": "drop"
351
- },
352
- {
353
- "id": "signing-bundle",
354
- "from": "signing",
355
- "to": "bundle",
356
- "variant": "security",
357
- "route": "drop",
358
- "fromSide": "bottom",
359
- "toSide": "top"
360
- },
361
- {
362
- "id": "bundle-verify",
363
- "from": "bundle",
364
- "to": "verify",
365
- "variant": "emphasis"
366
- },
367
- {
368
- "id": "base-provider",
369
- "from": "base",
370
- "to": "provider",
371
- "variant": "dashed"
372
- },
373
- {
374
- "id": "provider-changed",
375
- "from": "provider",
376
- "to": "changed",
377
- "variant": "security"
378
- },
379
- {
380
- "id": "changed-attestations",
381
- "from": "changed",
382
- "to": "attestations",
383
- "variant": "emphasis"
384
- },
385
- {
386
- "id": "attestations-union",
387
- "from": "attestations",
388
- "to": "union",
389
- "variant": "dashed"
390
- },
391
- {
392
- "id": "union-range",
393
- "from": "union",
394
- "to": "range",
395
- "variant": "security"
396
- },
397
- {
398
- "id": "manifest-boundary",
399
- "from": "manifest",
400
- "to": "boundary",
401
- "variant": "dashed",
402
- "role": "branch",
403
- "fromSide": "left",
404
- "toSide": "left",
405
- "route": "return-left",
406
- "channelX": 44
407
- },
408
- {
409
- "id": "union-gap",
410
- "from": "union",
411
- "to": "gap",
412
- "variant": "security",
413
- "role": "error",
414
- "fromSide": "right",
415
- "toSide": "left",
416
- "route": "outside-right",
417
- "channelX": 550
418
- }
419
- ],
420
- "cards": [
421
- {
422
- "dot": "rose",
423
- "title": "Trust Levels",
424
- "items": [
425
- "PROCESSED is a minimum reported level; MISSING, DISABLED, and INVALID remain separate statuses",
426
- "VERIFIED means completion, evidence, manifest, and content bindings validate",
427
- "ATTESTED additionally requires a valid external signature policy",
428
- "No supplied CI receipt means NOT_VERIFIED, not a trust level"
429
- ]
430
- },
431
- {
432
- "dot": "cyan",
433
- "title": "Exact Content",
434
- "items": [
435
- "The manifest records one SHA-256 digest per changed source entry",
436
- "The in-toto statement binds the manifest to completion evidence",
437
- "Read-only verification never rewrites task state or ledger events",
438
- "Compaction preserves transaction manifests and event history"
439
- ]
440
- },
441
- {
442
- "dot": "emerald",
443
- "title": "Coverage Boundary",
444
- "items": [
445
- "Revision-range coverage asks whether changed paths have valid attestations",
446
- "Gaps and conflicting task digests fail closed",
447
- "Verification Scope \u2260 Attestation Coverage"
448
- ]
449
- }
450
- ]
451
- }