@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.
- package/CONTRIBUTING.md +22 -2
- package/DOCS_INDEX.md +4 -13
- package/ENG/sec-code-eng.md +1 -1
- package/ENG/test-code-eng.md +32 -1
- package/LOOP_SYSTEM_DESIGN.md +2 -3
- package/QUALITY_SCORECARD.md +0 -1
- package/README.md +10 -42
- package/THIRD_PARTY_NOTICES.md +0 -15
- package/completions/_forgeloop +3 -2
- package/completions/forgeloop.bash +4 -2
- package/completions/forgeloop.fish +12 -1
- package/docs/AGENT_PROTOCOL_SUMMARY.md +3 -2
- package/docs/ARTIFACT_REFERENCE.md +1 -0
- package/docs/CLI_REFERENCE.md +24 -1
- package/docs/CODE_ATTESTATION.md +9 -7
- package/docs/DOCUMENTATION_GUIDE.md +10 -28
- package/docs/PACKAGE_CONTENTS.md +0 -3
- package/docs/RELEASE_CHECKLIST.md +52 -19
- package/docs/REVISION_PROVIDERS.md +3 -6
- package/docs/TROUBLESHOOTING.md +3 -0
- package/docs/documentation-manifest.json +0 -13
- package/package.json +2 -6
- package/schemas/config.schema.json +1 -0
- package/scripts/CI_VALIDATORS.md +2 -2
- package/src/cli.js +5 -0
- package/src/commands/attestation-create.js +21 -1
- package/src/commands/complete.js +3 -0
- package/src/commands/evidence-publish.js +22 -0
- package/src/commands/sync-pull.js +72 -7
- package/src/commands/sync-push.js +4 -1
- package/src/core/audit.js +7 -0
- package/src/core/cli-command-definitions.js +19 -1
- package/src/core/command-executors.js +19 -5
- package/src/core/config.js +44 -37
- package/src/core/error-codes.js +18 -0
- package/src/core/evidence/auto-export.js +61 -0
- package/src/core/evidence/bundle-format.js +4 -2
- package/src/core/evidence/export.js +5 -0
- package/src/core/evidence/publish.js +187 -0
- package/src/core/integration-invocation-policy.js +1 -0
- package/src/core/sync/merge.js +135 -0
- package/docs/assets/diagrams/forgeloop-code-attestation-flow.html +0 -13852
- package/docs/assets/diagrams/forgeloop-code-attestation-flow.receipt.json +0 -37
- package/docs/assets/diagrams/forgeloop-code-attestation-flow.svg +0 -5055
- package/docs/assets/diagrams/forgeloop-engineering-flow.html +0 -13837
- package/docs/assets/diagrams/forgeloop-engineering-flow.receipt.json +0 -37
- package/docs/assets/diagrams/forgeloop-engineering-flow.svg +0 -5011
- package/docs/assets/diagrams/forgeloop-verification-trust-flow.html +0 -13795
- package/docs/assets/diagrams/forgeloop-verification-trust-flow.receipt.json +0 -37
- package/docs/assets/diagrams/forgeloop-verification-trust-flow.svg +0 -4997
- package/docs/diagrams/README.md +0 -103
- package/docs/diagrams/forgeloop-code-attestation-flow.workflow.json +0 -451
- package/docs/diagrams/forgeloop-engineering-flow.workflow.json +0 -459
- package/docs/diagrams/forgeloop-verification-trust-flow.workflow.json +0 -398
- package/docs/diagrams/manifest.json +0 -84
- package/docs/diagrams/reviews/forgeloop-code-attestation-flow.review.json +0 -20
- package/docs/diagrams/reviews/forgeloop-engineering-flow.review.json +0 -20
- 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,
|
|
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
|
|
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.
|
|
213
|
+
## 7. Diagrams
|
|
218
214
|
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
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
|
|
239
|
-
`
|
|
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
|
package/docs/PACKAGE_CONTENTS.md
CHANGED
|
@@ -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.
|
|
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
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
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
|
-
- [ ]
|
|
239
|
-
|
|
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`, `
|
|
279
|
-
|
|
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
|
|
107
|
-
|
|
108
|
-
|
|
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
|
package/docs/TROUBLESHOOTING.md
CHANGED
|
@@ -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.
|
|
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"],
|
package/scripts/CI_VALIDATORS.md
CHANGED
|
@@ -79,7 +79,7 @@ ruleset's exact required contexts:
|
|
|
79
79
|
|
|
80
80
|
- `audit`
|
|
81
81
|
- `CodeQL`
|
|
82
|
-
- `
|
|
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
|
|
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 };
|
package/src/commands/complete.js
CHANGED
|
@@ -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
|
-
|
|
14
|
-
|
|
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
|
-
|
|
32
|
-
return { status: "PULLED",
|
|
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,
|
|
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",
|