@cassiomc1/forgeloop 2.1.0 → 2.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- 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 +19 -48
- package/THIRD_PARTY_NOTICES.md +0 -15
- package/completions/_forgeloop +7 -1
- package/completions/forgeloop.bash +13 -1
- package/completions/forgeloop.fish +51 -1
- package/docs/AGENT_PROTOCOL_SUMMARY.md +7 -1
- package/docs/ARTIFACT_REFERENCE.md +1 -0
- package/docs/CLI_REFERENCE.md +111 -3
- package/docs/CODE_ATTESTATION.md +16 -7
- package/docs/DOCUMENTATION_GUIDE.md +10 -28
- package/docs/PACKAGE_CONTENTS.md +0 -3
- package/docs/RELEASE_CHECKLIST.md +81 -15
- package/docs/REVISION_PROVIDERS.md +3 -6
- package/docs/TROUBLESHOOTING.md +11 -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 +31 -0
- package/src/commands/assess.js +36 -0
- package/src/commands/attestation-create.js +21 -1
- package/src/commands/complete.js +3 -0
- package/src/commands/evidence-export.js +17 -0
- package/src/commands/evidence-publish.js +22 -0
- package/src/commands/evidence-verify.js +36 -0
- package/src/commands/sync-pull.js +111 -0
- package/src/commands/sync-push.js +52 -0
- package/src/core/assessment/facts.js +146 -0
- package/src/core/assessment/plan.js +133 -0
- package/src/core/audit.js +7 -0
- package/src/core/cli-command-definitions.js +88 -0
- package/src/core/command-executors.js +42 -5
- package/src/core/config.js +44 -37
- package/src/core/error-codes.js +70 -0
- package/src/core/evidence/auto-export.js +61 -0
- package/src/core/evidence/bundle-format.js +74 -0
- package/src/core/evidence/export.js +184 -0
- package/src/core/evidence/markdown.js +40 -0
- package/src/core/evidence/publish.js +187 -0
- package/src/core/evidence/verify.js +179 -0
- package/src/core/integration-invocation-policy.js +5 -2
- package/src/core/sync/merge.js +135 -0
- package/src/core/sync/remote.js +124 -0
- package/src/core/sync/snapshot.js +129 -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
|
@@ -405,6 +405,7 @@ Local ForgeLoop configuration settings and policy bindings.
|
|
|
405
405
|
- `mode` *(string, required, enum: `off`, `optional`, `required`)*
|
|
406
406
|
- `revisionProvider` *(string, required, minLength: 1)*
|
|
407
407
|
- `requireCompleteCoverage` *(boolean, required)*
|
|
408
|
+
- `autoExportEvidence` *(boolean, optional)*
|
|
408
409
|
- `coverage` *(object, required)*
|
|
409
410
|
- `exclude` *(array<string>, required)*
|
|
410
411
|
- `signing` *(object, required)*
|
package/docs/CLI_REFERENCE.md
CHANGED
|
@@ -158,6 +158,42 @@ destination is never replaced. External attachments are not included.
|
|
|
158
158
|
|
|
159
159
|
<!-- END FORGELOOP GENERATED: cli:storage-backup:options -->
|
|
160
160
|
|
|
161
|
+
### `sync-push`
|
|
162
|
+
|
|
163
|
+
Uploads an encrypted backup of this project's ForgeLoop state to the cloud-sync
|
|
164
|
+
remote so another machine can continue the work. The snapshot is encrypted on
|
|
165
|
+
this machine with `FORGELOOP_SYNC_KEY`; `FORGELOOP_SYNC_TOKEN` authenticates the
|
|
166
|
+
request. A push based on a remote version this machine has not pushed or pulled
|
|
167
|
+
is refused with `E_SYNC_CONFLICT`. See [`CLOUD_SYNC.md`](./CLOUD_SYNC.md).
|
|
168
|
+
|
|
169
|
+
<!-- BEGIN FORGELOOP GENERATED: cli:sync-push:options -->
|
|
170
|
+
|
|
171
|
+
- `--path <directory>`: target project directory (default: current directory)
|
|
172
|
+
- `--remote <url>`: sync endpoint (default: https://forgeloop.monster/api/sync)
|
|
173
|
+
- `--repo <owner/name>`: repository the snapshot belongs to (default: from the git origin)
|
|
174
|
+
- `--json`: emit the push result as JSON
|
|
175
|
+
|
|
176
|
+
<!-- END FORGELOOP GENERATED: cli:sync-push:options -->
|
|
177
|
+
|
|
178
|
+
### `sync-pull`
|
|
179
|
+
|
|
180
|
+
Downloads, decrypts and verifies the repository's snapshot, then activates it
|
|
181
|
+
through `storage-restore`: into a fresh project, or over existing local state
|
|
182
|
+
only with `--replace-active`. Requires `--writers-quiesced`.
|
|
183
|
+
|
|
184
|
+
<!-- BEGIN FORGELOOP GENERATED: cli:sync-pull:options -->
|
|
185
|
+
|
|
186
|
+
- `--path <directory>`: target project directory (default: current directory)
|
|
187
|
+
- `--remote <url>`: sync endpoint (default: https://forgeloop.monster/api/sync)
|
|
188
|
+
- `--repo <owner/name>`: repository the snapshot belongs to (default: from the git origin)
|
|
189
|
+
- `--replace-active`: replace existing local state; the outgoing state is retained and archived
|
|
190
|
+
- `--merge`: combine whole tasks three-way with local state instead of replacing it
|
|
191
|
+
- `--dry-run`: with --merge, report the per-task plan without changing anything
|
|
192
|
+
- `--writers-quiesced`: assert that all writers have been externally stopped
|
|
193
|
+
- `--json`: emit the pull and restore result as JSON
|
|
194
|
+
|
|
195
|
+
<!-- END FORGELOOP GENERATED: cli:sync-pull:options -->
|
|
196
|
+
|
|
161
197
|
## Semantic decision projections
|
|
162
198
|
|
|
163
199
|
### `decision-status`
|
|
@@ -239,6 +275,19 @@ question-set categories.
|
|
|
239
275
|
|
|
240
276
|
<!-- END FORGELOOP GENERATED: cli:semantic-plan:options -->
|
|
241
277
|
|
|
278
|
+
### `assess`
|
|
279
|
+
|
|
280
|
+
Assesses an existing repository read-only and emits a guide-routed review plan
|
|
281
|
+
for frontend and backend code. It never executes target code; see
|
|
282
|
+
[`ASSESSMENT.md`](./ASSESSMENT.md).
|
|
283
|
+
|
|
284
|
+
<!-- BEGIN FORGELOOP GENERATED: cli:assess:options -->
|
|
285
|
+
|
|
286
|
+
- `--path <directory>`: target project directory (default: current directory)
|
|
287
|
+
- `--json`: emit the repository assessment plan as JSON
|
|
288
|
+
|
|
289
|
+
<!-- END FORGELOOP GENERATED: cli:assess:options -->
|
|
290
|
+
|
|
242
291
|
### `test-inventory`
|
|
243
292
|
|
|
244
293
|
Discovers deterministic test units and stable test IDs.
|
|
@@ -327,8 +376,8 @@ error codes. Default output and default JSON remain unchanged.
|
|
|
327
376
|
|
|
328
377
|
| Category | Commands |
|
|
329
378
|
| --- | --- |
|
|
330
|
-
| **Setup & Maintenance** | [`storage-restore-resume`](#storage-restore-resume), [`storage-restore`](#storage-restore), [`storage-migration-status`](#storage-migration-status), [`storage-migration-resume`](#storage-migration-resume), [`storage-rollback`](#storage-rollback), [`storage-rollback-resume`](#storage-rollback-resume), [`storage-migrate`](#storage-migrate), [`storage-backup`](#storage-backup), [`contract-revise`](#contract-revise), [`init`](#init), [`index-setup`](#index-setup), [`index-start`](#index-start), [`index-stop`](#index-stop), [`index-rebuild`](#index-rebuild), [`update`](#update), [`checkpoint-revalidate`](#checkpoint-revalidate), [`task-migrate`](#task-migrate), [`migrate-protocol`](#migrate-protocol), [`task-unlock`](#task-unlock), [`task-recover`](#task-recover), [`task-abandon`](#task-abandon), [`task-repair-contract-bootstrap`](#task-repair-contract-bootstrap), [`task-migrate-contract-bootstrap-repair`](#task-migrate-contract-bootstrap-repair), [`task-repair-legacy-recovery`](#task-repair-legacy-recovery), [`task-resume`](#task-resume) |
|
|
331
|
-
| **Inspection & Diagnostics** | [`protocol-info`](#protocol-info), [`decision-status`](#decision-status), [`decision-show`](#decision-show), [`context-plan`](#context-plan), [`model-route`](#model-route), [`semantic-plan`](#semantic-plan), [`test-inventory`](#test-inventory), [`test-utility`](#test-utility), [`test-prune-plan`](#test-prune-plan), [`doctor`](#doctor), [`index-status`](#index-status), [`search`](#search), [`metrics`](#metrics), [`usage-record`](#usage-record), [`efficiency`](#efficiency), [`eval`](#eval), [`history`](#history), [`trace`](#trace), [`reflect`](#reflect), [`progress`](#progress), [`profile-interview`](#profile-interview), [`inspect`](#inspect), [`status`](#status), [`validate-state`](#validate-state), [`validate-protocol`](#validate-protocol) |
|
|
379
|
+
| **Setup & Maintenance** | [`storage-restore-resume`](#storage-restore-resume), [`storage-restore`](#storage-restore), [`storage-migration-status`](#storage-migration-status), [`storage-migration-resume`](#storage-migration-resume), [`storage-rollback`](#storage-rollback), [`storage-rollback-resume`](#storage-rollback-resume), [`storage-migrate`](#storage-migrate), [`storage-backup`](#storage-backup), [`sync-push`](#sync-push), [`sync-pull`](#sync-pull), [`contract-revise`](#contract-revise), [`init`](#init), [`index-setup`](#index-setup), [`index-start`](#index-start), [`index-stop`](#index-stop), [`index-rebuild`](#index-rebuild), [`update`](#update), [`checkpoint-revalidate`](#checkpoint-revalidate), [`task-migrate`](#task-migrate), [`migrate-protocol`](#migrate-protocol), [`task-unlock`](#task-unlock), [`task-recover`](#task-recover), [`task-abandon`](#task-abandon), [`task-repair-contract-bootstrap`](#task-repair-contract-bootstrap), [`task-migrate-contract-bootstrap-repair`](#task-migrate-contract-bootstrap-repair), [`task-repair-legacy-recovery`](#task-repair-legacy-recovery), [`task-resume`](#task-resume) |
|
|
380
|
+
| **Inspection & Diagnostics** | [`protocol-info`](#protocol-info), [`decision-status`](#decision-status), [`decision-show`](#decision-show), [`context-plan`](#context-plan), [`model-route`](#model-route), [`semantic-plan`](#semantic-plan), [`test-inventory`](#test-inventory), [`assess`](#assess), [`test-utility`](#test-utility), [`test-prune-plan`](#test-prune-plan), [`doctor`](#doctor), [`index-status`](#index-status), [`search`](#search), [`metrics`](#metrics), [`usage-record`](#usage-record), [`efficiency`](#efficiency), [`eval`](#eval), [`history`](#history), [`trace`](#trace), [`reflect`](#reflect), [`progress`](#progress), [`profile-interview`](#profile-interview), [`inspect`](#inspect), [`status`](#status), [`validate-state`](#validate-state), [`validate-protocol`](#validate-protocol) |
|
|
332
381
|
| **Verification & Completion** | [`test-prune-probe`](#test-prune-probe), [`quality-baseline`](#quality-baseline), [`quality-verify`](#quality-verify), [`quality-status`](#quality-status), [`prepare-completion`](#prepare-completion), [`run-check`](#run-check), [`record-check`](#record-check), [`record-terminal-result`](#record-terminal-result), [`audit`](#audit), [`report`](#report), [`validate-receipt`](#validate-receipt), [`verify-scope`](#verify-scope) |
|
|
333
382
|
| **Lifecycle & State** | [`discover`](#discover), [`contract-create`](#contract-create), [`gate-record`](#gate-record), [`gate-revalidate`](#gate-revalidate), [`activate`](#activate), [`route`](#route), [`preflight`](#preflight), [`advance`](#advance), [`next`](#next), [`record-diagnosis`](#record-diagnosis), [`record-intervention`](#record-intervention), [`record-hypothesis-disposition`](#record-hypothesis-disposition), [`record-decision-criterion`](#record-decision-criterion), [`complete`](#complete), [`clear-state`](#clear-state), [`reconcile-closure`](#reconcile-closure), [`task-create`](#task-create), [`task-list`](#task-list), [`task-show`](#task-show), [`task-lock-status`](#task-lock-status), [`task-scope`](#task-scope) |
|
|
334
383
|
| **Cross-Harness Continuity** | [`continuity`](#continuity), [`record-continuity`](#record-continuity), [`reconcile-continuity`](#reconcile-continuity), [`clear-continuity`](#clear-continuity), [`handoff-create`](#handoff-create), [`handoff-list`](#handoff-list), [`handoff-show`](#handoff-show) |
|
|
@@ -337,7 +386,7 @@ error codes. Default output and default JSON remain unchanged.
|
|
|
337
386
|
| **workspace** | [`workspace-bind`](#workspace-bind), [`workspace-status`](#workspace-status) |
|
|
338
387
|
| **task** | [`handoff-accept`](#handoff-accept) |
|
|
339
388
|
| **scope** | [`responsibility-set`](#responsibility-set), [`responsibility-status`](#responsibility-status) |
|
|
340
|
-
| **attestation** | [`attestation-create`](#attestation-create), [`attestation-verify`](#attestation-verify), [`attestation-status`](#attestation-status), [`attestation-verify-range`](#attestation-verify-range) |
|
|
389
|
+
| **attestation** | [`attestation-create`](#attestation-create), [`attestation-verify`](#attestation-verify), [`attestation-status`](#attestation-status), [`evidence-export`](#evidence-export), [`evidence-publish`](#evidence-publish), [`evidence-verify`](#evidence-verify), [`attestation-verify-range`](#attestation-verify-range) |
|
|
341
390
|
|
|
342
391
|
<!-- END FORGELOOP GENERATED: cli-command-index -->
|
|
343
392
|
|
|
@@ -764,6 +813,65 @@ Reports local attestation status and trust level without network access.
|
|
|
764
813
|
forgeloop attestation-status --task task-001 --json
|
|
765
814
|
```
|
|
766
815
|
|
|
816
|
+
### `evidence-export`
|
|
817
|
+
|
|
818
|
+
Exports a completed task's attestation as a portable, redacted evidence bundle
|
|
819
|
+
to commit with the change. See [`EVIDENCE_BUNDLES.md`](./EVIDENCE_BUNDLES.md).
|
|
820
|
+
|
|
821
|
+
<!-- BEGIN FORGELOOP GENERATED: cli:evidence-export:options -->
|
|
822
|
+
|
|
823
|
+
- `--path <directory>`: target project directory (default: current directory)
|
|
824
|
+
- `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
|
|
825
|
+
- `--dir <path>`: tracked evidence directory (default: .forgeloop-evidence)
|
|
826
|
+
- `--json`: emit the export result as JSON
|
|
827
|
+
|
|
828
|
+
<!-- END FORGELOOP GENERATED: cli:evidence-export:options -->
|
|
829
|
+
|
|
830
|
+
### `evidence-publish`
|
|
831
|
+
|
|
832
|
+
Opt-in. Uploads redacted evidence bundles to the team dashboard (default
|
|
833
|
+
`https://forgeloop.monster/api/evidence`), authenticated by
|
|
834
|
+
`FORGELOOP_SYNC_TOKEN`. Bundles wait in an offline queue under the user
|
|
835
|
+
config directory until the remote accepts them, and every run retries the
|
|
836
|
+
queue. Exits `1` while anything stays queued or was rejected. See
|
|
837
|
+
[`EVIDENCE_BUNDLES.md`](./EVIDENCE_BUNDLES.md).
|
|
838
|
+
|
|
839
|
+
<!-- BEGIN FORGELOOP GENERATED: cli:evidence-publish:options -->
|
|
840
|
+
|
|
841
|
+
- `--path <directory>`: target project directory (default: current directory)
|
|
842
|
+
- `--task <id>`: publish this task's exported bundle
|
|
843
|
+
- `--all`: publish every bundle in the evidence directory
|
|
844
|
+
- `--dir <path>`: tracked evidence directory (default: .forgeloop-evidence)
|
|
845
|
+
- `--remote <url>`: evidence endpoint (default: https://forgeloop.monster/api/evidence)
|
|
846
|
+
- `--repo <owner/name>`: repository the bundles belong to (default: from the git origin)
|
|
847
|
+
- `--json`: emit the publish result as JSON
|
|
848
|
+
|
|
849
|
+
<!-- END FORGELOOP GENERATED: cli:evidence-publish:options -->
|
|
850
|
+
|
|
851
|
+
### `evidence-verify`
|
|
852
|
+
|
|
853
|
+
Verifies committed evidence bundles for a revision range without local
|
|
854
|
+
ForgeLoop state. Unsigned bundles yield `INTEGRITY_ONLY`; signatures under the
|
|
855
|
+
verifier's policy yield `ATTESTED`.
|
|
856
|
+
|
|
857
|
+
<!-- BEGIN FORGELOOP GENERATED: cli:evidence-verify:options -->
|
|
858
|
+
|
|
859
|
+
- `--path <directory>`: target project directory (default: current directory)
|
|
860
|
+
- `--revision-provider <provider>`: revision provider (default: git)
|
|
861
|
+
- `--base <revision>`: base revision of the verified range
|
|
862
|
+
- `--head <revision>`: head revision of the verified range
|
|
863
|
+
- `--dir <path>`: tracked evidence directory (default: .forgeloop-evidence)
|
|
864
|
+
- `--exclude <path>`: changed path or dir/** excluded from coverage (verifier policy) (repeatable)
|
|
865
|
+
- `--allow-partial-coverage`: report uncovered changed paths without failing
|
|
866
|
+
- `--require-signature`: require a valid Sigstore signature for every bundle used
|
|
867
|
+
- `--identity <identity>`: exact signer identity policy
|
|
868
|
+
- `--issuer <issuer>`: exact signer issuer policy
|
|
869
|
+
- `--trusted-root <path>`: trusted signing root path
|
|
870
|
+
- `--format <text|markdown>`: human output format (default: text)
|
|
871
|
+
- `--json`: emit the verification result as JSON
|
|
872
|
+
|
|
873
|
+
<!-- END FORGELOOP GENERATED: cli:evidence-verify:options -->
|
|
874
|
+
|
|
767
875
|
### `attestation-verify-range`
|
|
768
876
|
|
|
769
877
|
Verifies attestation coverage for an opaque revision range through the
|
package/docs/CODE_ATTESTATION.md
CHANGED
|
@@ -40,13 +40,9 @@ state, and ledger fingerprints. Configured coverage exclusions must be
|
|
|
40
40
|
explicit and are still reported; an excluded path is not silently represented
|
|
41
41
|
as covered source content.
|
|
42
42
|
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
It also shows why verification scope and attestation coverage are separate
|
|
47
|
-
questions.
|
|
48
|
-
|
|
49
|
-
Its canonical source is `docs/diagrams/forgeloop-code-attestation-flow.workflow.json`.
|
|
43
|
+
Verification scope and attestation coverage are separate questions: scope
|
|
44
|
+
decides what a check runs against, and coverage decides which changed paths a
|
|
45
|
+
statement binds.
|
|
50
46
|
|
|
51
47
|
## Completion flow
|
|
52
48
|
|
|
@@ -85,6 +81,12 @@ forgeloop attestation-status --task <taskId> --json
|
|
|
85
81
|
forgeloop attestation-verify --task <taskId> --ref HEAD --json
|
|
86
82
|
```
|
|
87
83
|
|
|
84
|
+
With mode `required`, `forgeloop complete --task <taskId>` also creates the
|
|
85
|
+
statement and exports the evidence bundle automatically; see
|
|
86
|
+
[`EVIDENCE_BUNDLES.md`](./EVIDENCE_BUNDLES.md). `attestation-create` returns
|
|
87
|
+
the existing statement (`reused: true`) when one already binds the current
|
|
88
|
+
manifest.
|
|
89
|
+
|
|
88
90
|
`attestation-verify` and `attestation-verify-range` are read-only. They never
|
|
89
91
|
write verification records or append ledger events.
|
|
90
92
|
|
|
@@ -140,6 +142,13 @@ distinguished from invalid attestations by the stable exit-code contract:
|
|
|
140
142
|
See [`REVISION_PROVIDERS.md`](./REVISION_PROVIDERS.md) and
|
|
141
143
|
[`SIGNING_PROVIDERS.md`](./SIGNING_PROVIDERS.md) for extension boundaries.
|
|
142
144
|
|
|
145
|
+
## Verifying in pull-request CI
|
|
146
|
+
|
|
147
|
+
Attestations live in the local `.forgeloop/` state. To verify them in CI,
|
|
148
|
+
export each completed task with `forgeloop evidence-export` and commit the
|
|
149
|
+
bundle; `forgeloop evidence-verify` then checks the range without local state.
|
|
150
|
+
See [`EVIDENCE_BUNDLES.md`](./EVIDENCE_BUNDLES.md).
|
|
151
|
+
|
|
143
152
|
## Receipt availability in repository CI
|
|
144
153
|
|
|
145
154
|
The repository audit workflow checks supplied task receipts individually with
|
|
@@ -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,74 @@ 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
|
|
46
|
+
|
|
47
|
+
`2.2.0` is a minor release of the core package. It adds `forgeloop assess`,
|
|
48
|
+
`evidence-export` and `evidence-verify` with ledger metrics, and the cloud-sync
|
|
49
|
+
`sync-push` and `sync-pull` commands, with their error codes. Its runtime
|
|
50
|
+
changes are bound by
|
|
51
|
+
[`stable-2.2.0-writer-review.json.gz`](../benchmarks/storage-sqlite/stable-2.2.0-writer-review.json.gz),
|
|
52
|
+
a delta review against 2.1.0:
|
|
53
|
+
|
|
54
|
+
- Every changed module keeps identical filesystem bindings.
|
|
55
|
+
- 23 added bindings, all in new modules, each have an explicit role.
|
|
56
|
+
- `sync-pull` is a tenth explicit maintenance-admission command; a test proves
|
|
57
|
+
that it leaves a project under retained maintenance unchanged.
|
|
58
|
+
|
|
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:
|
|
68
|
+
|
|
69
|
+
```bash
|
|
70
|
+
npm view @cassiomc1/forgeloop version dist-tags --json
|
|
71
|
+
npm run release:identity -- --version 2.2.0 --release-commit <release-tag-commit>
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
## Stable 2.1.0 publication — 2026-11-14
|
|
8
75
|
|
|
9
76
|
`2.1.0` is a minor release of the core package (the published error registry
|
|
10
77
|
gains every emitted code, 159 of them as `PUBLIC_UNCLASSIFIED`). Its runtime
|
|
@@ -15,12 +82,16 @@ disposition for every changed, added and removed module.
|
|
|
15
82
|
`scripts/check-release-channel.mjs` selects the review by exact package version
|
|
16
83
|
and never falls back to an earlier report.
|
|
17
84
|
|
|
18
|
-
|
|
19
|
-
`
|
|
20
|
-
`
|
|
85
|
+
Published from tag `v2.1.0` (commit `bbf0f2a30d356812834c85098179250f07d78842`)
|
|
86
|
+
through `npm-publish.yml` with trusted OIDC publishing: npm `latest` is `2.1.0`,
|
|
87
|
+
`dist.integrity` is
|
|
88
|
+
`sha512-Kcv3h+k8SUVfohiHOHsvgaXwf8OitwDn6f62Mgm5hu3TKR7WKTOHhuLAf5q+oKPmzZ33pJDP3iXBhOJyCyrRKg==`,
|
|
89
|
+
the provenance statement is in the Sigstore transparency log (index
|
|
90
|
+
3890066512), and `release:identity` returns `RELEASE_IDENTITY_VALID`.
|
|
91
|
+
ForgeLoopAudit vendors this exact archive. Hosted parity, native Windows, rollback drills and
|
|
21
92
|
registry-user audits from 2.0.0 are not carried forward as evidence for these
|
|
22
|
-
bytes; the review records them as not repeated or post-publication.
|
|
23
|
-
|
|
93
|
+
bytes; the review records them as not repeated or post-publication. Re-check
|
|
94
|
+
the published identity with:
|
|
24
95
|
|
|
25
96
|
```bash
|
|
26
97
|
npm view @cassiomc1/forgeloop version dist-tags --json
|
|
@@ -202,9 +273,8 @@ acceptance additionally requires every item below:
|
|
|
202
273
|
- [ ] README catalog and architecture fallback identify the C, C++, Java, SQL,
|
|
203
274
|
Go, TypeScript, PHP, and Swift specialists and explain their bounded
|
|
204
275
|
structural evidence and same-root composition rules.
|
|
205
|
-
- [ ]
|
|
206
|
-
|
|
207
|
-
completion evidence.
|
|
276
|
+
- [ ] `LOOP_SYSTEM_DESIGN.md` explains project detection as routing context,
|
|
277
|
+
not verification or completion evidence.
|
|
208
278
|
- [ ] Positive clean-room package routing selects `flutter`, `clean`, and
|
|
209
279
|
`test` for a Flutter root.
|
|
210
280
|
- [ ] Documentation-only mentions, lockfiles, hosted packages, malformed
|
|
@@ -242,8 +312,8 @@ deployment, and live data migration remain separate actions.
|
|
|
242
312
|
- [ ] `npm run verify:prepush` passes before the release pull request; MCP
|
|
243
313
|
setup, when needed, was run explicitly with `npm run mcp:setup`.
|
|
244
314
|
- [ ] Ordinary PR validation uses `.github/workflows/pr-core.yml` with the
|
|
245
|
-
unchanged required contexts `audit`, `CodeQL`, `
|
|
246
|
-
|
|
315
|
+
unchanged required contexts `audit`, `CodeQL`, `Documentation
|
|
316
|
+
validation`, `validate (22)`, `tarball smoke (ubuntu-latest)`, and
|
|
247
317
|
`dependency-review`.
|
|
248
318
|
- [ ] `validate (22)` is always present and fails closed on an applicable
|
|
249
319
|
prerequisite failure, cancellation, or unexpected skip.
|
|
@@ -328,10 +398,6 @@ deployment, and live data migration remain separate actions.
|
|
|
328
398
|
- [ ] `npm run coverage` passes the configured global and critical-module gates.
|
|
329
399
|
- [ ] `npm run docs:check`, `npm run docs:generated:check`,
|
|
330
400
|
`npm run docs:conformance`, and `npm run docs:examples:check` pass.
|
|
331
|
-
- [ ] `npm run docs:diagrams:check` and `npm run docs:diagram:inventory` pass;
|
|
332
|
-
every active diagram has typed source, dark-first animated HTML/SVG,
|
|
333
|
-
reduced-motion handling, a deterministic receipt, a text fallback, and
|
|
334
|
-
a current source-bound visual review.
|
|
335
401
|
- [ ] `npm run completions:check` and `npm run summary:check` pass.
|
|
336
402
|
- [ ] Workspace binding, handoff, responsibility, verification scope, revision,
|
|
337
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
|
@@ -1583,12 +1583,16 @@ canonical task state.
|
|
|
1583
1583
|
| `E_EMULATED_SERVICES_VERSION_UNSUPPORTED` | 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. |
|
|
1584
1584
|
| `E_EVENT_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. |
|
|
1585
1585
|
| `E_EVIDENCE_BLOCKED` | 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. |
|
|
1586
|
+
| `E_EVIDENCE_BUNDLE_INVALID` | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. | Inspect the structured command result, correct the named boundary or artifact, then retry the canonical command. |
|
|
1586
1587
|
| `E_EVIDENCE_COVERAGE_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. |
|
|
1587
1588
|
| `E_EVIDENCE_COVERAGE_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. |
|
|
1589
|
+
| `E_EVIDENCE_EXPORT_UNAVAILABLE` | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. | Inspect the structured command result, correct the named boundary or artifact, then retry the canonical command. |
|
|
1588
1590
|
| `E_EVIDENCE_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. |
|
|
1589
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. |
|
|
1590
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. |
|
|
1591
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. |
|
|
1592
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. |
|
|
1593
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. |
|
|
1594
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. |
|
|
@@ -1861,6 +1865,13 @@ canonical task state.
|
|
|
1861
1865
|
| `E_STRUCTURAL_QUALITY_SOURCE_DRIFT` | Structural-quality evidence did not satisfy its provider, artifact, comparison, or lifecycle boundary. | Ensure the worktree is not mutated during provider observation and rerun quality-baseline or quality-verify. |
|
|
1862
1866
|
| `E_STRUCTURAL_QUALITY_SOURCE_FINGERPRINT_UNAVAILABLE` | Structural-quality evidence did not satisfy its provider, artifact, comparison, or lifecycle boundary. | Repair unreadable or unsafe source material before structural-quality evidence can be trusted. |
|
|
1863
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. |
|
|
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. |
|
|
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. |
|
|
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. |
|
|
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. |
|
|
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. |
|
|
1874
|
+
| `E_SYNC_UNAUTHORIZED` | The sync remote rejected FORGELOOP_SYNC_TOKEN, or the token is not allowed for this repository. | Use a token whose SHA-256 hash the remote owner configured for this repository. |
|
|
1864
1875
|
| `E_TARGET_REQUIRED` | 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
1876
|
| `E_TASK_ABANDON_AUTHORIZATION_REQUIRED` | task-abandon requires explicit caller acknowledgement and never grants completion or publication authority. | Re-run task-abandon with --acknowledge-abandonment after confirming the explicit task identity and intended claim release. |
|
|
1866
1877
|
| `E_TASK_ABANDON_INCONSISTENT` | Explicit abandonment was refused because canonical ownership or append-only ledger evidence is inconsistent. | Repair and validate the task descriptor, recovery artifact, and ledger through their dedicated protocol paths before retrying. |
|
|
@@ -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
|