@cassiomc1/forgeloop 2.2.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 (58) 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 +10 -42
  8. package/THIRD_PARTY_NOTICES.md +0 -15
  9. package/completions/_forgeloop +3 -2
  10. package/completions/forgeloop.bash +4 -2
  11. package/completions/forgeloop.fish +12 -1
  12. package/docs/AGENT_PROTOCOL_SUMMARY.md +3 -2
  13. package/docs/ARTIFACT_REFERENCE.md +1 -0
  14. package/docs/CLI_REFERENCE.md +24 -1
  15. package/docs/CODE_ATTESTATION.md +9 -7
  16. package/docs/DOCUMENTATION_GUIDE.md +10 -28
  17. package/docs/PACKAGE_CONTENTS.md +0 -3
  18. package/docs/RELEASE_CHECKLIST.md +52 -19
  19. package/docs/REVISION_PROVIDERS.md +3 -6
  20. package/docs/TROUBLESHOOTING.md +3 -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 +5 -0
  26. package/src/commands/attestation-create.js +21 -1
  27. package/src/commands/complete.js +3 -0
  28. package/src/commands/evidence-publish.js +22 -0
  29. package/src/commands/sync-pull.js +72 -7
  30. package/src/commands/sync-push.js +4 -1
  31. package/src/core/audit.js +7 -0
  32. package/src/core/cli-command-definitions.js +19 -1
  33. package/src/core/command-executors.js +19 -5
  34. package/src/core/config.js +44 -37
  35. package/src/core/error-codes.js +18 -0
  36. package/src/core/evidence/auto-export.js +61 -0
  37. package/src/core/evidence/bundle-format.js +4 -2
  38. package/src/core/evidence/export.js +5 -0
  39. package/src/core/evidence/publish.js +187 -0
  40. package/src/core/integration-invocation-policy.js +1 -0
  41. package/src/core/sync/merge.js +135 -0
  42. package/docs/assets/diagrams/forgeloop-code-attestation-flow.html +0 -13852
  43. package/docs/assets/diagrams/forgeloop-code-attestation-flow.receipt.json +0 -37
  44. package/docs/assets/diagrams/forgeloop-code-attestation-flow.svg +0 -5055
  45. package/docs/assets/diagrams/forgeloop-engineering-flow.html +0 -13837
  46. package/docs/assets/diagrams/forgeloop-engineering-flow.receipt.json +0 -37
  47. package/docs/assets/diagrams/forgeloop-engineering-flow.svg +0 -5011
  48. package/docs/assets/diagrams/forgeloop-verification-trust-flow.html +0 -13795
  49. package/docs/assets/diagrams/forgeloop-verification-trust-flow.receipt.json +0 -37
  50. package/docs/assets/diagrams/forgeloop-verification-trust-flow.svg +0 -4997
  51. package/docs/diagrams/README.md +0 -103
  52. package/docs/diagrams/forgeloop-code-attestation-flow.workflow.json +0 -451
  53. package/docs/diagrams/forgeloop-engineering-flow.workflow.json +0 -459
  54. package/docs/diagrams/forgeloop-verification-trust-flow.workflow.json +0 -398
  55. package/docs/diagrams/manifest.json +0 -84
  56. package/docs/diagrams/reviews/forgeloop-code-attestation-flow.review.json +0 -20
  57. package/docs/diagrams/reviews/forgeloop-engineering-flow.review.json +0 -20
  58. package/docs/diagrams/reviews/forgeloop-verification-trust-flow.review.json +0 -20
@@ -14,7 +14,6 @@ ForgeLoop strictly separates normative protocol definitions from operational doc
14
14
  | **Operational & Reference** | `docs/` (`GETTING_STARTED.md`, `CROSS_HARNESS_CONTINUITY.md`, `CLI_REFERENCE.md`, `ARTIFACT_REFERENCE.md`, `TROUBLESHOOTING.md`, `RECIPES.md`, `REPOSITORY_INDEX.md`, `PERSISTENT_SEARCH_TRANSPORT.md`) | Tutorials, command reference, handoff workflows, repository search, transport behavior, and troubleshooting | Explains how to operate the system. Links to normative sources for formal specifications. |
15
15
  | **Domain Engineering** | `ENG/` (`clean-code-eng.md`, `design-code-eng.md`, `test-code-eng.md`, etc.) | Domain-specific implementation and quality standards | Frontmatter must adhere to `validate_loop_system.py` standards. |
16
16
  | **Consumer Documentation Quality** | [`ENG/documentation-quality-eng.md`](../ENG/documentation-quality-eng.md) | Quality standards for documentation work in projects using ForgeLoop | Governs client/consumer project documentation tasks via guide routing. |
17
- | **Visual Architecture** | `docs/diagrams/manifest.json` + the three typed workflow sources under `docs/diagrams/` | Governance metadata and canonical typed Archify workflow sources | Animated HTML explorers, animated SVG fallbacks, deterministic receipts, and source-bound human reviews are committed under `docs/assets/diagrams/` and `docs/diagrams/reviews/`. |
18
17
  | **Documentation Index** | `DOCS_INDEX.md` | Single repository index and ownership map | Updated whenever documentation structure changes. |
19
18
 
20
19
  ---
@@ -78,8 +77,7 @@ either consolidated into a canonical document and deleted or moved to the
78
77
  history index with their current owner links.
79
78
 
80
79
  Repository and npm decisions are separate. GitHub may retain reproducible
81
- benchmarks, PoC evidence, source-bound diagram artifacts, vendored renderer
82
- sources, and historical records that consumers do not need. The npm package
80
+ benchmarks, PoC evidence, and historical records that consumers do not need. The npm package
83
81
  ships only intentional runtime, integration, legal, harness, and canonical user
84
82
  documentation surfaces. `npm run repository:hygiene` enforces explicit root,
85
83
  tracked-state, visual-ownership, benchmark-run-set, and scratch-output policy;
@@ -119,7 +117,6 @@ documentation validation (.github/workflows/docs.yml) and the PR aggregator
119
117
  | **CLI Command Options** | `CLI_COMMAND_DEFINITIONS` (`src/core/cli-command-definitions.js`) | `docs/CLI_REFERENCE.md` | `<!-- BEGIN FORGELOOP GENERATED: cli:<command>:options -->` |
120
118
  | **Work-State Transitions** | `WORK_PHASES` / `WORK_TRANSITIONS` (`src/core/protocol.js`) | `ORCHESTRATOR_INTEGRATION.md` | `<!-- BEGIN FORGELOOP GENERATED: work-transitions -->` |
121
119
  | **Public Error Codes** | `PUBLIC_ERROR_CODES` (`src/core/error-codes.js`) | `docs/TROUBLESHOOTING.md` | `<!-- BEGIN FORGELOOP GENERATED: public-error-codes -->` |
122
- | **Architecture and trust diagrams** | `docs/diagrams/manifest.json` + typed workflow sources | Generated HTML/SVG/receipt/review files for Engineering Flow, Verification Trust Flow, and Code Attestation Chain | Verified via the pinned Archify renderer, trace-animation and reduced-motion markers, source/SVG fingerprints, artifact hashes, persistent review, and composition checks |
123
120
 
124
121
  ### Maintenance Workflow
125
122
 
@@ -132,7 +129,7 @@ npm run docs:generate
132
129
  # 2. Run the test suite (includes parser parity and unit tests)
133
130
  npm test
134
131
 
135
- # 3. Verify freshness, diagram fingerprints, and semantic conformance
132
+ # 3. Verify freshness and semantic conformance
136
133
  npm run docs:check
137
134
  ```
138
135
 
@@ -159,7 +156,6 @@ conformance checks detect omissions.
159
156
  | **Package-shipped docs and runtime** | `package.json` (`files`) + `docs/PACKAGE_CONTENTS.md` | `tests/package.test.js` + `scripts/package_smoke.mjs` |
160
157
  | **Repository Index contract** | `src/repository-index/*`, `src/core/cli-command-definitions.js`, `src/integration.js` | Repository Index unit/native tests + `scripts/verify-tgrep-manifest.mjs` |
161
158
  | **Persistent CLI search transport** | `src/persistent-transport/*`, `src/commands/repository-index.js`, `src/repository-index/search.js` | Persistent transport unit/native tests + Repository Index integration tests |
162
- | **Architecture and trust diagrams** | `docs/diagrams/manifest.json` plus each typed workflow source | `scripts/check-documentation-diagrams.mjs` and `scripts/documentation-diagram-inventory.mjs` |
163
159
 
164
160
  ---
165
161
 
@@ -214,30 +210,21 @@ migration, or security-sensitive require `npm run docs:check` before merge.
214
210
 
215
211
  ---
216
212
 
217
- ## 7. Archify Diagrams and Animated SVG Generation
213
+ ## 7. Diagrams
218
214
 
219
- 1. **Typed source is canonical**: The Engineering Flow, Verification Trust Flow, and Code Attestation Chain are authored in Archify workflow IR under `docs/diagrams/`; the high-level source is `docs/diagrams/forgeloop-engineering-flow.workflow.json`. Never modify generated HTML, SVG, or receipt files directly.
220
- 2. **Pinned local renderer**: Generation uses only the vendored Archify v2.15.0 source at the reviewed commit recorded in `docs/diagrams/manifest.json` and `vendor/archify/v2.15.0/PIN.json`.
221
- 3. **Animated committed outputs**: Every active source uses `meta.animation: "trace"`. Each interactive HTML is the primary animated explorer, and each self-contained SVG fallback carries trace-capable edge/node animation while remaining usable in repository previews. Deterministic receipts are committed under `docs/assets/diagrams/`.
222
- 4. **GitHub-safe SVG**: The SVG must not embed `<script>` or `<foreignObject>`, must expose accessible title/description metadata, and must remain visible through standard Markdown image syntax.
223
- 5. **Fingerprint and review verification**: The generated SVG embeds a `data-forgeloop-source-sha256` attribute, the outputs expose trace markers, and the receipt binds the source, HTML, and SVG hashes. The review at `docs/diagrams/reviews/` binds the current source and SVG hashes as a review assertion and is never generated or overwritten; the checker does not independently authenticate the reviewer. Run `npm run docs:diagrams:check` before review.
224
- 6. **Scoped wrapper**: The ForgeLoop Archify wrapper is intentionally documentation-scoped. It reads canonical inputs only from `docs/diagrams/` and permits deliver outputs only under `docs/assets/diagrams/`.
225
-
226
- ForgeLoop governs five documentation-diagram categories: workflow,
227
- architecture, sequence, dataflow, and lifecycle. The active repository set has
228
- three canonical workflow diagrams: the Engineering Flow, Verification Trust
229
- Flow, and Code Attestation Chain. The pinned wrapper currently maps only
230
- `workflow`; governance support does not imply renderer support, so a new type
231
- requires an explicit mapping and tests before activation.
215
+ The repository does not generate diagrams. Lifecycle, verification-trust and
216
+ attestation flows are described in prose in their canonical documents
217
+ (`LOOP_SYSTEM_DESIGN.md`, `docs/REVISION_PROVIDERS.md` and
218
+ `docs/CODE_ATTESTATION.md`). The only visuals are the README assets listed
219
+ below.
232
220
 
233
221
  ---
234
222
 
235
223
  ## 8. README Hero and Package Boundary
236
224
 
237
225
  README hero assets are branding/conceptual architecture illustrations. They are
238
- not the canonical protocol diagram. The typed Archify workflow under
239
- `docs/diagrams/` remains the canonical lifecycle architecture source, with
240
- generated outputs under `docs/assets/diagrams/`; the CLI-only persistent search
226
+ not a canonical protocol diagram. The lifecycle architecture is defined in
227
+ prose by `LOOP_SYSTEM_DESIGN.md`; the CLI-only persistent search
241
228
  transport is explained by `docs/PERSISTENT_SEARCH_TRANSPORT.md`. The current
242
229
  repository-only assets are `docs/assets/forgeloop-architecture.png`, the
243
230
  alternate [architecture SVG](./assets/forgeloop-architecture.svg), and
@@ -257,11 +244,6 @@ The README hero is intentionally GitHub-repository-only:
257
244
  packaged Markdown must be present in the package and covered by
258
245
  `tests/package.test.js`.
259
246
 
260
- Never edit or delete a generated diagram output independently of its source;
261
- regenerate all declared outputs from the typed workflow sources and keep each
262
- receipt and human-owned review binding in sync. Every diagram must also have a
263
- concise text fallback in the canonical document named by its manifest.
264
-
265
247
  ---
266
248
 
267
249
  ## 9. Documentation Change Checklist for Pull Requests
@@ -89,9 +89,6 @@ The published tarball includes the following consumer-facing groups:
89
89
  subpath remains unexported.
90
90
  The lifecycle recovery surface includes the explicit `task-abandon` command;
91
91
  it releases validated claims without asserting completion or publication.
92
- The typed diagram sources, generated HTML/SVG/receipt artifacts, and
93
- source-bound review records under `docs/diagrams/` are included together so
94
- the packaged documentation keeps its visual provenance.
95
92
  - **Release tooling:** the selected deterministic generators, validators,
96
93
  benchmark helpers, and shell completions needed by maintainers who consume
97
94
  the source kit.
@@ -4,7 +4,45 @@ This is the current release checklist for the PolyForm Noncommercial-licensed
4
4
  `@cassiomc1/forgeloop` package. It is a preparation and verification checklist;
5
5
  it does not authorize publication.
6
6
 
7
- ## Stable 2.2.0 candidate — 2026-11-16
7
+ ## Stable 2.3.0 candidate — 2026-11-18
8
+
9
+ `2.3.0` is a minor release of the core package.
10
+
11
+ - **Automatic evidence:** with attestation mode `required`, `complete`
12
+ exports the evidence bundle automatically and, with the `sigstore`
13
+ provider, signs it.
14
+ - **New commands and options:** the opt-in `evidence-publish` command with an
15
+ offline queue, and `sync-pull --merge`, a task-level three-way merge.
16
+ - **New error codes:** `E_SYNC_MERGE_CONFLICT`, `E_EVIDENCE_PUBLISH_CONFIG`
17
+ and `E_EVIDENCE_PUBLISH_UNAUTHORIZED`.
18
+
19
+ Its runtime changes are bound by
20
+ [`stable-2.3.0-writer-review.json.gz`](../benchmarks/storage-sqlite/stable-2.3.0-writer-review.json.gz),
21
+ a delta review against 2.2.0:
22
+
23
+ - 13 changed and 4 added modules each have a disposition.
24
+ - The 9 added filesystem bindings write only a user-config queue
25
+ (`evidence-publish`) or private OS temp staging (`sync-pull --merge`).
26
+ The live store changes only through existing transaction writers or
27
+ `storage-restore`.
28
+
29
+ Before dispatching `npm-publish.yml`:
30
+
31
+ 1. Merge the release commit to `main`.
32
+ 2. Tag it `v2.3.0`.
33
+ 3. Dispatch from that tag with channel `latest` and confirmation
34
+ `PUBLISH PUBLIC PACKAGE`. The external link check runs in that
35
+ workflow's `verify` job on the self-hosted Linux runner.
36
+
37
+ Windows, rollback drills, hosted parity and registry-user audits are recorded
38
+ as not repeated or post-publication. After publication run:
39
+
40
+ ```bash
41
+ npm view @cassiomc1/forgeloop version dist-tags --json
42
+ npm run release:identity -- --version 2.3.0 --release-commit <release-tag-commit>
43
+ ```
44
+
45
+ ## Stable 2.2.0 publication — 2026-11-16
8
46
 
9
47
  `2.2.0` is a minor release of the core package. It adds `forgeloop assess`,
10
48
  `evidence-export` and `evidence-verify` with ledger metrics, and the cloud-sync
@@ -18,15 +56,15 @@ a delta review against 2.1.0:
18
56
  - `sync-pull` is a tenth explicit maintenance-admission command; a test proves
19
57
  that it leaves a project under retained maintenance unchanged.
20
58
 
21
- Before dispatching `npm-publish.yml`:
22
-
23
- 1. Merge the release commit to `main`.
24
- 2. Tag it `v2.2.0`.
25
- 3. Dispatch from that tag with channel `latest` and confirmation
26
- `PUBLISH PUBLIC PACKAGE`.
27
-
28
- Windows, rollback drills, hosted parity and registry-user audits are recorded
29
- as not repeated or post-publication. After publication run:
59
+ Published from tag `v2.2.0` (commit `8b472a2fff30034a5d23a9a380250136930b5e67`)
60
+ through `npm-publish.yml` with trusted OIDC publishing: npm `latest` is `2.2.0`,
61
+ `dist.integrity` is
62
+ `sha512-UOCK/KJGUjsiQrpFmMwrFz1haoWKhbWlQ/aELO6Use0py+0fl+z7l75LOnN0m94j1C0jU3f6YjagwMcXmhAB2A==`,
63
+ the provenance statement is in the Sigstore transparency log (index
64
+ 3937130126), and `release:identity` returns `RELEASE_IDENTITY_VALID`.
65
+ ForgeLoopAudit vendors this exact archive. Windows, rollback drills, hosted
66
+ parity and registry-user audits are recorded as not repeated or
67
+ post-publication. Re-check the published identity with:
30
68
 
31
69
  ```bash
32
70
  npm view @cassiomc1/forgeloop version dist-tags --json
@@ -235,9 +273,8 @@ acceptance additionally requires every item below:
235
273
  - [ ] README catalog and architecture fallback identify the C, C++, Java, SQL,
236
274
  Go, TypeScript, PHP, and Swift specialists and explain their bounded
237
275
  structural evidence and same-root composition rules.
238
- - [ ] The canonical engineering-flow source and regenerated HTML/SVG diagram
239
- explain project detection as routing context, not verification or
240
- completion evidence.
276
+ - [ ] `LOOP_SYSTEM_DESIGN.md` explains project detection as routing context,
277
+ not verification or completion evidence.
241
278
  - [ ] Positive clean-room package routing selects `flutter`, `clean`, and
242
279
  `test` for a Flutter root.
243
280
  - [ ] Documentation-only mentions, lockfiles, hosted packages, malformed
@@ -275,8 +312,8 @@ deployment, and live data migration remain separate actions.
275
312
  - [ ] `npm run verify:prepush` passes before the release pull request; MCP
276
313
  setup, when needed, was run explicitly with `npm run mcp:setup`.
277
314
  - [ ] Ordinary PR validation uses `.github/workflows/pr-core.yml` with the
278
- unchanged required contexts `audit`, `CodeQL`, `Verify generated Archify
279
- diagram`, `validate (22)`, `tarball smoke (ubuntu-latest)`, and
315
+ unchanged required contexts `audit`, `CodeQL`, `Documentation
316
+ validation`, `validate (22)`, `tarball smoke (ubuntu-latest)`, and
280
317
  `dependency-review`.
281
318
  - [ ] `validate (22)` is always present and fails closed on an applicable
282
319
  prerequisite failure, cancellation, or unexpected skip.
@@ -361,10 +398,6 @@ deployment, and live data migration remain separate actions.
361
398
  - [ ] `npm run coverage` passes the configured global and critical-module gates.
362
399
  - [ ] `npm run docs:check`, `npm run docs:generated:check`,
363
400
  `npm run docs:conformance`, and `npm run docs:examples:check` pass.
364
- - [ ] `npm run docs:diagrams:check` and `npm run docs:diagram:inventory` pass;
365
- every active diagram has typed source, dark-first animated HTML/SVG,
366
- reduced-motion handling, a deterministic receipt, a text fallback, and
367
- a current source-bound visual review.
368
401
  - [ ] `npm run completions:check` and `npm run summary:check` pass.
369
402
  - [ ] Workspace binding, handoff, responsibility, verification scope, revision,
370
403
  manifest, statement, signature, and range-coverage tests pass.
@@ -103,15 +103,12 @@ and `CLAIMED` requests fail closed. A mismatched scoped argv is rejected
103
103
  before the checker process starts, and successful binding records the scope
104
104
  and capability fingerprints with the execution evidence.
105
105
 
106
- The [Verification Trust Flow](./assets/diagrams/forgeloop-verification-trust-flow.html)
107
- explorer and its [animated SVG fallback](./assets/diagrams/forgeloop-verification-trust-flow.svg)
108
- show the claims, provider changes, checker capability, fingerprints, exact
109
- argv, and observed evidence boundary. If no trusted checker exists, `AUTO`
106
+ The verification trust boundary covers the claims, provider changes, checker
107
+ capability, fingerprints, exact argv, and observed evidence. If no trusted
108
+ checker exists, `AUTO`
110
109
  falls back to `FULL`; an explicit `CHANGED` or `CLAIMED` request returns
111
110
  `E_VERIFICATION_SCOPE_UNRESOLVED` rather than guessing.
112
111
 
113
- The canonical source is `docs/diagrams/forgeloop-verification-trust-flow.workflow.json`.
114
-
115
112
  ## Error boundary
116
113
 
117
114
  Providers must expose stable ForgeLoop errors rather than requiring callers to
@@ -1591,6 +1591,8 @@ canonical task state.
1591
1591
  | `E_EVIDENCE_KIND_INVALID` | A ForgeLoop protocol validation or lifecycle condition was not satisfied. | Inspect the structured command result, correct the named artifact or prerequisite, then run forgeloop next --json. |
1592
1592
  | `E_EVIDENCE_MISSING` | Emitted by ForgeLoop but not yet curated; the code name is the contract and it carries no stable compatibility promise. | Inspect the structured command result, correct the named artifact or prerequisite, then run forgeloop next --json. |
1593
1593
  | `E_EVIDENCE_PARTIAL` | A ForgeLoop protocol validation or lifecycle condition was not satisfied. | Inspect the structured command result, correct the named artifact or prerequisite, then run forgeloop next --json. |
1594
+ | `E_EVIDENCE_PUBLISH_CONFIG` | evidence-publish is missing FORGELOOP_SYNC_TOKEN, has nothing to publish, or --remote, --repo or a task ID is invalid. | Set FORGELOOP_SYNC_TOKEN, pass --task <id> or --all with an https --remote and an owner/name --repo (or a GitHub git origin). |
1595
+ | `E_EVIDENCE_PUBLISH_UNAUTHORIZED` | The evidence remote rejected FORGELOOP_SYNC_TOKEN, or the token is not allowed for this repository. The bundles stay queued. | Use a token issued for this repository, then run evidence-publish again to retry the queue. |
1594
1596
  | `E_EVIDENCE_REQUIRED` | A ForgeLoop protocol validation or lifecycle condition was not satisfied. | Inspect the structured command result, correct the named artifact or prerequisite, then run forgeloop next --json. |
1595
1597
  | `E_EVIDENCE_STALE` | A ForgeLoop protocol validation or lifecycle condition was not satisfied. | Inspect the structured command result, correct the named artifact or prerequisite, then run forgeloop next --json. |
1596
1598
  | `E_EXECUTION_INVALID` | Emitted by ForgeLoop but not yet curated; the code name is the contract and it carries no stable compatibility promise. | Inspect the structured command result, correct the named artifact or prerequisite, then run forgeloop next --json. |
@@ -1865,6 +1867,7 @@ canonical task state.
1865
1867
  | `E_STRUCTURAL_QUALITY_TIMEOUT` | Structural-quality evidence did not satisfy its provider, artifact, comparison, or lifecycle boundary. | Use a responsive provider or a bounded timeout within the supported limit; never promote a timed-out scan. |
1866
1868
  | `E_SYNC_CONFIG` | Cloud sync is missing FORGELOOP_SYNC_TOKEN or a FORGELOOP_SYNC_KEY of at least 16 characters, or --remote or --repo is invalid. | Set both environment variables and pass an https --remote and an owner/name --repo, or a GitHub git origin. |
1867
1869
  | `E_SYNC_CONFLICT` | The remote snapshot changed since this machine last pushed or pulled, so the push was refused instead of overwriting it. | Run forgeloop sync-pull --writers-quiesced --replace-active to adopt the remote state, then continue and push again. |
1870
+ | `E_SYNC_MERGE_CONFLICT` | sync-pull --merge found tasks changed on both machines, or merged tasks would hold overlapping active claims, so nothing was changed. | Finish or abandon the task on one machine and sync it first, or run sync-pull --replace-active to adopt the remote state. |
1868
1871
  | `E_SYNC_REMOTE` | The sync remote is unreachable, has no snapshot for this repository, or refused the request. | Check --remote and network access, push a first snapshot, or retry later. |
1869
1872
  | `E_SYNC_SNAPSHOT_INVALID` | The remote snapshot could not be decrypted with FORGELOOP_SYNC_KEY, belongs to another repository, or its contents failed integrity checks. | Use the same FORGELOOP_SYNC_KEY as the pushing machine; never restore a snapshot that fails these checks. |
1870
1873
  | `E_SYNC_TOO_LARGE` | The encrypted snapshot exceeds the 4 MiB sync limit. | Sync a project with less retained state; cloud sync does not split snapshots. |
@@ -349,19 +349,6 @@
349
349
  ],
350
350
  "packaged": true
351
351
  },
352
- {
353
- "path": "docs/diagrams/README.md",
354
- "id": "documentation-diagrams",
355
- "class": "guide",
356
- "audience": [
357
- "maintainer",
358
- "integrator"
359
- ],
360
- "canonicalFor": [
361
- "documentation-diagrams"
362
- ],
363
- "packaged": true
364
- },
365
352
  {
366
353
  "path": "docs/RELEASE_CHECKLIST_1_4.md",
367
354
  "id": "release-checklist-1-4",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cassiomc1/forgeloop",
3
- "version": "2.2.0",
3
+ "version": "2.3.0",
4
4
  "description": "Evidence-first engineering protocol for AI coding environments and developer workflows",
5
5
  "repository": {
6
6
  "type": "git",
@@ -51,8 +51,6 @@
51
51
  "CONTRIBUTING.md",
52
52
  "docs/documentation-manifest.json",
53
53
  "docs/protocol-requirements.json",
54
- "docs/diagrams",
55
- "docs/assets/diagrams",
56
54
  "docs/GETTING_STARTED.md",
57
55
  "docs/CROSS_HARNESS_CONTINUITY.md",
58
56
  "docs/ADVISORY_CONTEXT.md",
@@ -136,9 +134,6 @@
136
134
  "pack:check": "node --test tests/package.test.js",
137
135
  "pack:smoke": "node scripts/package_smoke.mjs",
138
136
  "release:identity": "node scripts/verify_release_identity.mjs",
139
- "docs:diagrams": "node scripts/generate-documentation-diagrams.mjs",
140
- "docs:diagrams:check": "node scripts/check-documentation-diagrams.mjs",
141
- "docs:diagram:inventory": "node scripts/documentation-diagram-inventory.mjs --json",
142
137
  "docs:generate": "node scripts/generate_documentation_reference.mjs --write",
143
138
  "docs:generated:check": "node scripts/generate_documentation_reference.mjs --check",
144
139
  "docs:conformance": "node scripts/validate_documentation_conformance.mjs",
@@ -173,6 +168,7 @@
173
168
  "complexity:check": "node scripts/check-complexity.mjs",
174
169
  "repository-index:manifest": "node scripts/verify-tgrep-manifest.mjs",
175
170
  "repository:hygiene": "node scripts/check-repository-hygiene.mjs",
171
+ "test:landmines": "node scripts/check-test-landmines.mjs",
176
172
  "task-discovery:benchmark": "node scripts/benchmark-task-discovery.mjs",
177
173
  "storage:benchmark": "node scripts/benchmark-storage-sqlite.mjs",
178
174
  "storage:benchmark:diagnosis": "node scripts/benchmark-diagnosis-parity.mjs",
@@ -77,6 +77,7 @@
77
77
  "mode": { "enum": ["off", "optional", "required"] },
78
78
  "revisionProvider": { "type": "string", "minLength": 1 },
79
79
  "requireCompleteCoverage": { "type": "boolean" },
80
+ "autoExportEvidence": { "type": "boolean" },
80
81
  "coverage": {
81
82
  "type": "object",
82
83
  "required": ["exclude"],
@@ -79,7 +79,7 @@ ruleset's exact required contexts:
79
79
 
80
80
  - `audit`
81
81
  - `CodeQL`
82
- - `Verify generated Archify diagram`
82
+ - `Documentation validation`
83
83
  - `validate (22)`
84
84
  - `tarball smoke (ubuntu-latest)`
85
85
  - `dependency-review`
@@ -101,7 +101,7 @@ node scripts/ci-classify.mjs --all --json
101
101
  ```
102
102
 
103
103
  Documentation-only pull requests use quick core validation plus the
104
- documentation/diagram path; the Node 20 matrix steps do not install or run for
104
+ documentation path; the Node 20 matrix steps do not install or run for
105
105
  docs-only changes. Runtime and package changes use Node 20 compatibility checks
106
106
  and four Node 24 unit shards wrapped by the coverage gate, followed by a
107
107
  coverage-only aggregation. Repository Index changes retain the native reusable
package/src/cli.js CHANGED
@@ -578,6 +578,11 @@ export const COMMAND_HANDLERS = Object.freeze({
578
578
  renderJsonOr(options, result, (await import("./commands/evidence-export.js")).formatEvidenceExportResult);
579
579
  return 0;
580
580
  },
581
+ "evidence-publish": async ({ target, packageRoot, options }) => {
582
+ const { result, exitCode } = await COMMAND_EXECUTORS["evidence-publish"]({ target, packageRoot, options });
583
+ renderJsonOr(options, result, (await import("./commands/evidence-publish.js")).formatEvidencePublishResult);
584
+ return exitCode;
585
+ },
581
586
  "evidence-verify": async ({ target, packageRoot, options }) => {
582
587
  const { result, exitCode } = await COMMAND_EXECUTORS["evidence-verify"]({ target, packageRoot, options });
583
588
  const { formatEvidenceVerifyResult } = await import("./commands/evidence-verify.js");
@@ -1,4 +1,6 @@
1
- import { buildAttestationStatement, writeAttestationStatement } from "../core/attestation.js";
1
+ import { buildAttestationStatement, readAttestationStatement, writeAttestationStatement } from "../core/attestation.js";
2
+ import { readCodeManifest } from "../core/code-manifest.js";
3
+ import { taskAttestationStatementPath } from "../core/task-paths.js";
2
4
  import { withTaskTransaction } from "../core/transaction.js";
3
5
  import { assertTaskMutationAllowed } from "../core/task-claim-state.js";
4
6
  import { readWorkState } from "../core/work-state.js";
@@ -19,6 +21,24 @@ export async function runAttestationCreate({ target, packageRoot, taskId } = {})
19
21
  if (error.code !== "E_TASK_COMPLETE") throw error;
20
22
  });
21
23
  await assertWorkspaceBinding(target, { taskId, packageRoot, operation: "attestation-create" });
24
+ // complete may already have attested this cycle (automatic evidence
25
+ // export), and the exported bundle then sits in the worktree. The
26
+ // statement is immutable within a cycle, so return it unchanged while it
27
+ // still binds the current manifest instead of rebuilding.
28
+ const existing = await readAttestationStatement({ target, packageRoot, taskId }).catch(() => null);
29
+ if (existing) {
30
+ const manifest = await readCodeManifest({ target, packageRoot, taskId }).catch(() => null);
31
+ if (manifest && existing.value.predicate.content.manifestFingerprint === manifest.fingerprint) {
32
+ return {
33
+ path: taskAttestationStatementPath(taskId),
34
+ fingerprint: existing.fingerprint,
35
+ statement: existing.value,
36
+ statementFingerprint: existing.fingerprint,
37
+ manifestFingerprint: manifest.fingerprint,
38
+ reused: true,
39
+ };
40
+ }
41
+ }
22
42
  const built = await buildAttestationStatement({ target, packageRoot, taskId });
23
43
  const written = await writeAttestationStatement({ target, packageRoot, taskId, statement: built.statement });
24
44
  return { ...written, statementFingerprint: built.fingerprint, manifestFingerprint: built.manifest.fingerprint };
@@ -34,6 +34,9 @@ export function formatCompleteResult(result) {
34
34
  lines.push(`PUBLICATION: ${result.publicationStatus}`);
35
35
  lines.push(`PRODUCTION_READINESS: ${result.productionReadiness}`);
36
36
  }
37
+ const evidence = result.evidence;
38
+ if (evidence?.status === "EXPORTED") lines.push(`EVIDENCE: exported ${evidence.path} (commit it with the change)`);
39
+ else if (evidence?.status === "FAILED") lines.push(`EVIDENCE: export failed (${evidence.code}): ${evidence.message}`, `NEXT: ${evidence.next}`);
37
40
  for (const error of result.errors) {
38
41
  lines.push(`${error.code}: ${error.message}`);
39
42
  if (error.next) lines.push(`NEXT: ${error.next}`);
@@ -0,0 +1,22 @@
1
+ import { publishEvidence } from "../core/evidence/publish.js";
2
+
3
+ export async function runEvidencePublish({ target, taskId, all, evidenceDirectory, remote, repository, env, fetchImpl } = {}) {
4
+ return publishEvidence({
5
+ target,
6
+ taskIds: taskId ? [taskId] : [],
7
+ all: all === true,
8
+ ...(evidenceDirectory ? { directory: evidenceDirectory } : {}),
9
+ remote,
10
+ repository,
11
+ ...(env ? { env } : {}),
12
+ ...(fetchImpl ? { fetchImpl } : {}),
13
+ });
14
+ }
15
+
16
+ export function formatEvidencePublishResult(result) {
17
+ const lines = [`FORGELOOP EVIDENCE PUBLISH: ${result.status}`, `REMOTE: ${result.remote}`, `REPOSITORY: ${result.repository}`];
18
+ for (const item of result.results) lines.push(`${item.status} ${item.taskId}${item.message ? ` (${item.message})` : ""}`);
19
+ if (result.queued > 0) lines.push(`QUEUED: ${result.queued} bundle(s) stay queued; run forgeloop evidence-publish again to retry.`);
20
+ lines.push("");
21
+ return lines.join("\n");
22
+ }
@@ -1,17 +1,26 @@
1
- import { mkdtemp, rm } from "node:fs/promises";
1
+ import { cp, mkdtemp, rm } from "node:fs/promises";
2
2
  import os from "node:os";
3
3
  import path from "node:path";
4
4
 
5
- import { readSyncCredentials, remoteError, strongEtag, resolveRemote, resolveRepository, syncRequest, writeSyncState } from "../core/sync/remote.js";
5
+ import { readSyncCredentials, readSyncState, remoteError, strongEtag, resolveRemote, resolveRepository, syncRequest, writeSyncState } from "../core/sync/remote.js";
6
6
  import { MAX_SNAPSHOT_BYTES, openSnapshot, syncError, unpackDirectory } from "../core/sync/snapshot.js";
7
+ import { buildMergedBackup, classifyTasks, readDatabaseDigests } from "../core/sync/merge.js";
7
8
  import { runStorageRestore } from "./storage-restore.js";
8
9
 
9
10
  // Downloads, decrypts and restores the repository's snapshot. Remote state is
10
11
  // untrusted: it must decrypt and authenticate under FORGELOOP_SYNC_KEY, every
11
12
  // file digest must match, and activation goes through the verified
12
13
  // storage-restore path (a fresh project, or explicit --replace-active).
13
- export async function runSyncPull({ target, packageRoot, remote, repository, writersQuiesced = false, replaceActive = false, env = process.env, fetchImpl = fetch } = {}) {
14
- if (writersQuiesced !== true) throw syncError("E_STORAGE_MIGRATION_QUIESCENCE_REQUIRED", "Stop every ForgeLoop writer for this project, then pass --writers-quiesced");
14
+ // --merge keeps local work: whole tasks are combined three-way against the
15
+ // per-task digests recorded at the last push or pull, and the merged state is
16
+ // activated through the same replace-active restore.
17
+ function assertPullOptions({ writersQuiesced, replaceActive, merge, dryRun }) {
18
+ if (writersQuiesced !== true && !(merge && dryRun)) throw syncError("E_STORAGE_MIGRATION_QUIESCENCE_REQUIRED", "Stop every ForgeLoop writer for this project, then pass --writers-quiesced");
19
+ if (dryRun && !merge) throw syncError("E_SYNC_CONFIG", "--dry-run applies to --merge");
20
+ if (merge && replaceActive) throw syncError("E_SYNC_CONFIG", "Use either --merge or --replace-active");
21
+ }
22
+
23
+ async function fetchSnapshot({ target, remote, repository, env, fetchImpl }) {
15
24
  const { token, passphrase } = readSyncCredentials(env);
16
25
  const resolvedRemote = resolveRemote(remote);
17
26
  const resolvedRepository = await resolveRepository(target, repository);
@@ -22,20 +31,76 @@ export async function runSyncPull({ target, packageRoot, remote, repository, wri
22
31
  const body = Buffer.from(await response.arrayBuffer());
23
32
  if (body.length > MAX_SNAPSHOT_BYTES) throw syncError("E_SYNC_TOO_LARGE", "Remote snapshot exceeds the size limit");
24
33
  const { envelope, payload } = openSnapshot(body, { passphrase, repository: resolvedRepository });
34
+ return { remote: resolvedRemote, repository: resolvedRepository, etag, envelope, payload };
35
+ }
36
+
37
+ async function mergeSnapshot({ target, packageRoot, staging, source, remoteTasks, summary, snapshot, dryRun, writersQuiesced, env, recordPull }) {
38
+ const local = path.join(staging, "local");
39
+ await backupLocalState(target, local);
40
+ const previous = await readSyncState(target, { remote: snapshot.remote, repository: snapshot.repository, env });
41
+ const base = previous?.tasks && typeof previous.tasks === "object" ? previous.tasks : null;
42
+ const plan = classifyTasks({ local: readDatabaseDigests(path.join(local, "state.sqlite")), remote: remoteTasks, base });
43
+ const report = { ...summary, base: base ? "recorded" : "none", take: plan.take, keep: plan.keep, same: plan.same.length, conflicts: plan.conflicts };
44
+ if (dryRun) return { status: plan.conflicts.length > 0 ? "CONFLICT" : "PLANNED", ...report };
45
+ if (plan.conflicts.length > 0) {
46
+ throw Object.assign(syncError("E_SYNC_MERGE_CONFLICT", `Tasks changed on both machines cannot be merged: ${plan.conflicts.map((item) => item.taskId).join(", ")}`), { report });
47
+ }
48
+ if (plan.take.length === 0) {
49
+ await recordPull();
50
+ return { status: "UP_TO_DATE", ...report };
51
+ }
52
+ const workingCopy = path.join(staging, "working");
53
+ await cp(local, workingCopy, { recursive: true });
54
+ const merged = path.join(staging, "merged");
55
+ await buildMergedBackup({ localBackup: workingCopy, remoteBackup: source, take: plan.take.map((item) => item.taskId), destination: merged });
56
+ const restore = await runStorageRestore({ target, source: merged, writersQuiesced, replaceActive: true, packageRoot });
57
+ await recordPull();
58
+ return { status: "MERGED", ...report, restore };
59
+ }
25
60
 
61
+ export async function runSyncPull({ target, packageRoot, remote, repository, writersQuiesced = false, replaceActive = false, merge = false, dryRun = false, env = process.env, fetchImpl = fetch } = {}) {
62
+ assertPullOptions({ writersQuiesced, replaceActive, merge, dryRun });
63
+ const snapshot = await fetchSnapshot({ target, remote, repository, env, fetchImpl });
26
64
  const staging = await mkdtemp(path.join(os.tmpdir(), "forgeloop-sync-"));
27
65
  try {
28
66
  const source = path.join(staging, "backup");
29
- const files = await unpackDirectory(payload, source);
67
+ const files = await unpackDirectory(snapshot.payload, source);
68
+ const remoteTasks = readDatabaseDigests(path.join(source, "state.sqlite"));
69
+ const recordPull = () => (snapshot.etag
70
+ ? writeSyncState(target, { remote: snapshot.remote, repository: snapshot.repository, etag: snapshot.etag, direction: "pull", at: new Date().toISOString(), tasks: remoteTasks }, { env })
71
+ : null);
72
+ const summary = { repository: snapshot.repository, remote: snapshot.remote, etag: snapshot.etag, files: files.length, snapshotCreatedAt: snapshot.envelope.createdAt ?? null };
73
+ if (merge) return await mergeSnapshot({ target, packageRoot, staging, source, remoteTasks, summary, snapshot, dryRun, writersQuiesced, env, recordPull });
30
74
  const restore = await runStorageRestore({ target, source, writersQuiesced, replaceActive, packageRoot });
31
- if (etag) await writeSyncState(target, { remote: resolvedRemote, repository: resolvedRepository, etag, direction: "pull", at: new Date().toISOString() }, { env });
32
- return { status: "PULLED", repository: resolvedRepository, remote: resolvedRemote, etag, files: files.length, snapshotCreatedAt: envelope.createdAt ?? null, replaceActive, restore };
75
+ await recordPull();
76
+ return { status: "PULLED", ...summary, replaceActive, restore };
33
77
  } finally {
34
78
  await rm(staging, { recursive: true, force: true });
35
79
  }
36
80
  }
37
81
 
82
+ async function backupLocalState(target, destination) {
83
+ const { withProjectStorage } = await import("../storage/project-boundary.js");
84
+ const { getOperationalStore } = await import("../storage/operational-context.js");
85
+ const { backupProjectStorage } = await import("../storage/project-backup.js");
86
+ await withProjectStorage(target, () => {
87
+ const store = getOperationalStore(target);
88
+ if (!store) throw syncError("E_SYNC_CONFIG", "sync-pull --merge requires an existing SQLite project");
89
+ return backupProjectStorage(store.db, target, destination);
90
+ }, { readOnly: true, existingOnly: true });
91
+ }
92
+
38
93
  export function formatSyncPullResult(result) {
94
+ if (result.take !== undefined) {
95
+ const lines = [`FORGELOOP SYNC MERGE: ${result.status} (${result.repository})`, `BASE: ${result.base}`];
96
+ for (const item of result.take) lines.push(`TAKE ${item.taskId} (${item.reason})`);
97
+ for (const item of result.keep) lines.push(`KEEP ${item.taskId} (${item.reason})`);
98
+ for (const item of result.conflicts) lines.push(`CONFLICT ${item.taskId} (${item.reason})`);
99
+ lines.push(`SAME: ${result.same} task(s)`);
100
+ if (result.status === "MERGED") lines.push("The merged state is active (the outgoing state is retained). Run forgeloop sync-push to publish it.");
101
+ lines.push("");
102
+ return lines.join("\n");
103
+ }
39
104
  return [
40
105
  `FORGELOOP SYNC PULLED: ${result.repository}`,
41
106
  `SNAPSHOT: ${result.snapshotCreatedAt ?? "unknown time"} (${result.files} files, ETag ${result.etag ?? "unknown"})`,
@@ -4,6 +4,7 @@ import path from "node:path";
4
4
 
5
5
  import { readSyncCredentials, readSyncState, strongEtag, remoteError, resolveRemote, resolveRepository, syncRequest, writeSyncState } from "../core/sync/remote.js";
6
6
  import { packDirectory, sealSnapshot } from "../core/sync/snapshot.js";
7
+ import { readDatabaseDigests } from "../core/sync/merge.js";
7
8
  import { runStorageBackup } from "./storage-backup.js";
8
9
 
9
10
  // Uploads an encrypted, attachment-inclusive backup of this project's ForgeLoop
@@ -16,8 +17,10 @@ export async function runSyncPush({ target, packageRoot, remote, repository, env
16
17
  const staging = path.join(".forgeloop", `sync-staging-${randomUUID()}`);
17
18
  let body;
18
19
  let files;
20
+ let tasks;
19
21
  try {
20
22
  await runStorageBackup({ target, destination: staging, includeAttachments: true });
23
+ tasks = readDatabaseDigests(path.join(target, staging, "state.sqlite"));
21
24
  const payload = await packDirectory(path.join(target, staging));
22
25
  files = payload.files.length;
23
26
  const version = packageRoot ? JSON.parse(await readFile(path.join(packageRoot, "package.json"), "utf8")).version ?? null : null;
@@ -33,7 +36,7 @@ export async function runSyncPush({ target, packageRoot, remote, repository, env
33
36
  if (!response.ok) throw await remoteError(response);
34
37
  const result = await response.json().catch(() => ({}));
35
38
  const etag = strongEtag(typeof result.etag === "string" ? result.etag : response.headers.get("etag"));
36
- if (etag) await writeSyncState(target, { remote: resolvedRemote, repository: resolvedRepository, etag, direction: "push", at: new Date().toISOString() }, { env });
39
+ if (etag) await writeSyncState(target, { remote: resolvedRemote, repository: resolvedRepository, etag, direction: "push", at: new Date().toISOString(), tasks }, { env });
37
40
  return { status: "PUSHED", repository: resolvedRepository, remote: resolvedRemote, etag, files, bytes: body.length, firstPush: previous === null };
38
41
  }
39
42
 
package/src/core/audit.js CHANGED
@@ -13,6 +13,7 @@ import { readCodeManifest } from "./code-manifest.js";
13
13
  import { readAttestationStatement, validateAttestationStatement } from "./attestation.js";
14
14
  import { assertAttestationStatementBindings, verifyCodeManifestContent } from "./attestation-verifier.js";
15
15
  import { projectStructuralQualityStatus } from "./structural-quality/status.js";
16
+ import { DEFAULT_EVIDENCE_DIRECTORY } from "./evidence/bundle-format.js";
16
17
 
17
18
  function sortErrors(errors) {
18
19
  return [...errors].sort((left, right) => left.code.localeCompare(right.code)
@@ -48,6 +49,12 @@ async function compareChangedPaths(target, packageRoot, options = {}) {
48
49
  if (observed === null) {
49
50
  return { status: "NOT_VERIFIED", expected: receipt.changedPaths ?? [], observed: [], missing: [], unexpected: [] };
50
51
  }
52
+ // complete exports the task's own evidence bundle after the receipt is
53
+ // final; it is a protocol-owned derivative, not an unexpected change.
54
+ if (options.taskId) {
55
+ const ownBundle = `${DEFAULT_EVIDENCE_DIRECTORY}/${options.taskId}.json`;
56
+ observed = observed.filter((relativePath) => relativePath !== ownBundle);
57
+ }
51
58
  const expected = [...new Set(receipt.changedPaths ?? [])].sort();
52
59
  const missing = expected.filter((relativePath) => !observed.includes(relativePath));
53
60
  const unexpected = observed.filter((relativePath) => !expected.includes(relativePath));
@@ -174,11 +174,13 @@ export const CLI_COMMAND_DEFINITIONS = Object.freeze({
174
174
  "--remote": Object.freeze({ targetKey: "syncRemote", parseType: "string", takesValue: true, valueName: "url", missingValueMessage: "--remote requires a URL", description: "sync endpoint (default: https://forgeloop.monster/api/sync)" }),
175
175
  "--repo": Object.freeze({ targetKey: "syncRepository", parseType: "string", takesValue: true, valueName: "owner/name", missingValueMessage: "--repo requires owner/name", description: "repository the snapshot belongs to (default: from the git origin)" }),
176
176
  "--replace-active": Object.freeze({ targetKey: "replaceActive", parseType: "boolean", takesValue: false, description: "replace existing local state; the outgoing state is retained and archived" }),
177
+ "--merge": Object.freeze({ targetKey: "syncMerge", parseType: "boolean", takesValue: false, description: "combine whole tasks three-way with local state instead of replacing it" }),
178
+ "--dry-run": Object.freeze({ targetKey: "dryRun", parseType: "boolean", takesValue: false, description: "with --merge, report the per-task plan without changing anything" }),
177
179
  "--writers-quiesced": Object.freeze({ targetKey: "writersQuiesced", parseType: "boolean", takesValue: false, description: "assert that all writers have been externally stopped" }),
178
180
  "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit the pull and restore result as JSON" }),
179
181
  }),
180
182
  writes: [".forgeloop/storage-restores", ".forgeloop/state.sqlite", ".forgeloop/attachments", ".forgeloop/storage-version.json", ".forgeloop/.storage-maintenance", "<user config>/forgeloop/sync/<project>.json"], removes: [], mayExecuteExternalProcess: true,
181
- description: "Downloads, decrypts and verifies the repository's sync snapshot, then activates it through storage-restore: into a fresh project, or replacing local state only with --replace-active.",
183
+ description: "Downloads, decrypts and verifies the repository's sync snapshot, then activates it through storage-restore: into a fresh project, replacing local state with --replace-active, or merged task by task with local state with --merge.",
182
184
  }),
183
185
  "protocol-info": Object.freeze({
184
186
  name: "protocol-info",
@@ -1781,6 +1783,22 @@ export const CLI_COMMAND_DEFINITIONS = Object.freeze({
1781
1783
  writes: [".forgeloop-evidence/<taskId>.json"], removes: [], mayExecuteExternalProcess: false,
1782
1784
  description: "Exports a completed task's attestation as a portable, redacted evidence bundle to commit with the change.",
1783
1785
  }),
1786
+ "evidence-publish": Object.freeze({
1787
+ name: "evidence-publish",
1788
+ category: "attestation",
1789
+ mutation: "MUTATING",
1790
+ options: Object.freeze({
1791
+ ...CLI_COMMON_OPTIONS,
1792
+ "--task": Object.freeze({ targetKey: "taskId", parseType: "string", takesValue: true, valueName: "id", missingValueMessage: "--task requires a task ID", description: "publish this task's exported bundle" }),
1793
+ "--all": Object.freeze({ targetKey: "all", parseType: "boolean", takesValue: false, description: "publish every bundle in the evidence directory" }),
1794
+ "--dir": Object.freeze({ targetKey: "evidenceDirectory", parseType: "string", takesValue: true, valueName: "path", missingValueMessage: "--dir requires a path", description: "tracked evidence directory (default: .forgeloop-evidence)" }),
1795
+ "--remote": Object.freeze({ targetKey: "evidenceRemote", parseType: "string", takesValue: true, valueName: "url", missingValueMessage: "--remote requires a URL", description: "evidence endpoint (default: https://forgeloop.monster/api/evidence)" }),
1796
+ "--repo": Object.freeze({ targetKey: "evidenceRepository", parseType: "string", takesValue: true, valueName: "owner/name", missingValueMessage: "--repo requires owner/name", description: "repository the bundles belong to (default: from the git origin)" }),
1797
+ "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit the publish result as JSON" }),
1798
+ }),
1799
+ writes: ["<user config>/forgeloop/evidence-queue/<project>.json"], removes: [], mayExecuteExternalProcess: true,
1800
+ description: "Opt-in: uploads redacted evidence bundles to the team dashboard, authenticated by FORGELOOP_SYNC_TOKEN. Bundles wait in an offline queue outside the repository until the remote accepts them.",
1801
+ }),
1784
1802
  "evidence-verify": Object.freeze({
1785
1803
  name: "evidence-verify",
1786
1804
  category: "attestation",