@cassiomc1/forgeloop 2.2.0 → 2.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (58) hide show
  1. package/CONTRIBUTING.md +22 -2
  2. package/DOCS_INDEX.md +4 -13
  3. package/ENG/sec-code-eng.md +1 -1
  4. package/ENG/test-code-eng.md +32 -1
  5. package/LOOP_SYSTEM_DESIGN.md +2 -3
  6. package/QUALITY_SCORECARD.md +0 -1
  7. package/README.md +10 -42
  8. package/THIRD_PARTY_NOTICES.md +0 -15
  9. package/completions/_forgeloop +3 -2
  10. package/completions/forgeloop.bash +4 -2
  11. package/completions/forgeloop.fish +12 -1
  12. package/docs/AGENT_PROTOCOL_SUMMARY.md +3 -2
  13. package/docs/ARTIFACT_REFERENCE.md +1 -0
  14. package/docs/CLI_REFERENCE.md +24 -1
  15. package/docs/CODE_ATTESTATION.md +9 -7
  16. package/docs/DOCUMENTATION_GUIDE.md +10 -28
  17. package/docs/PACKAGE_CONTENTS.md +0 -3
  18. package/docs/RELEASE_CHECKLIST.md +52 -19
  19. package/docs/REVISION_PROVIDERS.md +3 -6
  20. package/docs/TROUBLESHOOTING.md +3 -0
  21. package/docs/documentation-manifest.json +0 -13
  22. package/package.json +2 -6
  23. package/schemas/config.schema.json +1 -0
  24. package/scripts/CI_VALIDATORS.md +2 -2
  25. package/src/cli.js +5 -0
  26. package/src/commands/attestation-create.js +21 -1
  27. package/src/commands/complete.js +3 -0
  28. package/src/commands/evidence-publish.js +22 -0
  29. package/src/commands/sync-pull.js +72 -7
  30. package/src/commands/sync-push.js +4 -1
  31. package/src/core/audit.js +7 -0
  32. package/src/core/cli-command-definitions.js +19 -1
  33. package/src/core/command-executors.js +19 -5
  34. package/src/core/config.js +44 -37
  35. package/src/core/error-codes.js +18 -0
  36. package/src/core/evidence/auto-export.js +61 -0
  37. package/src/core/evidence/bundle-format.js +4 -2
  38. package/src/core/evidence/export.js +5 -0
  39. package/src/core/evidence/publish.js +187 -0
  40. package/src/core/integration-invocation-policy.js +1 -0
  41. package/src/core/sync/merge.js +135 -0
  42. package/docs/assets/diagrams/forgeloop-code-attestation-flow.html +0 -13852
  43. package/docs/assets/diagrams/forgeloop-code-attestation-flow.receipt.json +0 -37
  44. package/docs/assets/diagrams/forgeloop-code-attestation-flow.svg +0 -5055
  45. package/docs/assets/diagrams/forgeloop-engineering-flow.html +0 -13837
  46. package/docs/assets/diagrams/forgeloop-engineering-flow.receipt.json +0 -37
  47. package/docs/assets/diagrams/forgeloop-engineering-flow.svg +0 -5011
  48. package/docs/assets/diagrams/forgeloop-verification-trust-flow.html +0 -13795
  49. package/docs/assets/diagrams/forgeloop-verification-trust-flow.receipt.json +0 -37
  50. package/docs/assets/diagrams/forgeloop-verification-trust-flow.svg +0 -4997
  51. package/docs/diagrams/README.md +0 -103
  52. package/docs/diagrams/forgeloop-code-attestation-flow.workflow.json +0 -451
  53. package/docs/diagrams/forgeloop-engineering-flow.workflow.json +0 -459
  54. package/docs/diagrams/forgeloop-verification-trust-flow.workflow.json +0 -398
  55. package/docs/diagrams/manifest.json +0 -84
  56. package/docs/diagrams/reviews/forgeloop-code-attestation-flow.review.json +0 -20
  57. package/docs/diagrams/reviews/forgeloop-engineering-flow.review.json +0 -20
  58. package/docs/diagrams/reviews/forgeloop-verification-trust-flow.review.json +0 -20
package/CONTRIBUTING.md CHANGED
@@ -16,8 +16,8 @@ aligned. Do not add vendor-specific runtime behavior: ForgeLoop uses canonical
16
16
  SQLite operational storage and explicit file interchange.
17
17
 
18
18
  The ordinary PR workflow is intentionally path-aware. `pr-core.yml` always
19
- publishes the ruleset contexts `audit`, `CodeQL`, `Verify generated Archify
20
- diagram`, `validate (22)`, `tarball smoke (ubuntu-latest)`, and
19
+ publishes the ruleset contexts `audit`, `CodeQL`, `Documentation validation`,
20
+ `validate (22)`, `tarball smoke (ubuntu-latest)`, and
21
21
  `dependency-review`; `validate (22)` fails closed if an applicable job fails
22
22
  or is skipped unexpectedly. Broader main-branch and release workflows provide
23
23
  the explicit cross-platform, package, Windows, documentation, and audit
@@ -52,6 +52,22 @@ The supported local Python command is `python3 -m unittest discover -s tests`.
52
52
  The frozen validators require Python 3.9 or newer and are compatibility tools
53
53
  used by CI; they are not a replacement for the Node test suite.
54
54
 
55
+ ## Honest tests
56
+
57
+ `npm run test:landmines` keeps new tests free of the landmines described in
58
+ [`ENG/test-code-eng.md`](./ENG/test-code-eng.md#honest-tests-test-landmines):
59
+
60
+ - behaviour-replacing mocks and patched globals;
61
+ - fixed sleeps;
62
+ - retries and raised per-test timeouts.
63
+
64
+ Existing occurrences are listed with an exact count per file in
65
+ `scripts/test-landmines-allowlist.json`, and the list may only shrink:
66
+
67
+ - **New occurrence:** the check fails. Use the honest alternative instead.
68
+ - **Occurrence removed:** the check also fails until you lower the
69
+ allowance to match.
70
+
55
71
  ## Release and performance checks
56
72
 
57
73
  Use `npm run coverage` followed by `npm run critical-coverage:check` for
@@ -59,6 +75,10 @@ coverage gates; coverage is intentionally not part of the default test command
59
75
  or the PR unit-test job. `npm run performance:check` measures the median
60
76
  startup time of the read-only `protocol-info` command using a broad
61
77
  shared-runner budget.
78
+ The external link check (Lychee) runs only in the npm publication workflow,
79
+ not on pull requests or pushes to `main`. Its network failures would
80
+ otherwise block unrelated changes. Run
81
+ `lychee --config .lychee.toml './**/*.md'` locally after changing links.
62
82
  Historical link exclusions in `.lychee.toml` are reviewed manually at least
63
83
  quarterly and must not be removed automatically.
64
84
 
package/DOCS_INDEX.md CHANGED
@@ -78,9 +78,6 @@ integration and guide context. Use this map before editing documentation.
78
78
  | Artifact and phase schemas | [`schemas/`](./schemas/) and [`CONTRACT_COVERAGE.md`](./CONTRACT_COVERAGE.md) | Versioned machine-readable contract |
79
79
  | CLI/package behavior | [`src/`](./src/) and [`tests/`](./tests/) | Executable implementation and regression evidence |
80
80
  | Guide content | [`ENG/`](./ENG/) | Context-specific, English-only operational guides, including Flutter, .NET, Node.js, Rust, C, C++, Java, SQL, Go, TypeScript, PHP, Swift, and Python specialist guides; Python is documentation-only and is not yet selected automatically by the router; ASP.NET Core and ABP remain .NET overlays |
81
- | Diagram governance | [`docs/diagrams/manifest.json`](./docs/diagrams/manifest.json) | Authoritative taxonomy, renderer mapping, canonical purposes, artifact ownership, and references |
82
- | Diagram maintainer entrypoint | [`docs/diagrams/README.md`](./docs/diagrams/README.md) | Typed Archify source, animated HTML explorer, animated SVG fallback, review, and regeneration workflow |
83
- | Engineering flow diagram | [`docs/assets/diagrams/forgeloop-engineering-flow.html`](./docs/assets/diagrams/forgeloop-engineering-flow.html) | Conceptual lifecycle from request through validator-backed completion |
84
81
  | Verification Trust Flow | [`docs/REVISION_PROVIDERS.md`](./docs/REVISION_PROVIDERS.md#differential-verification-scope) | Claims, changed paths, trusted checker capability, exact argv, and observed evidence |
85
82
  | Code Attestation Chain | [`docs/CODE_ATTESTATION.md`](./docs/CODE_ATTESTATION.md#completion-flow) | Completion, exact-content manifest, in-toto statement, optional signing, and range coverage |
86
83
  | Real Execution Proof of Concept (PoC) | [`poc/README.md`](./poc/README.md) | Non-normative, reproducible public engineering workload, audit evidence, and technical audit. Normative behavior remains owned by [`LOOP_ENGINEERING.md`](./LOOP_ENGINEERING.md). |
@@ -118,7 +115,6 @@ is historical evidence and is not part of the published core package.
118
115
  | **Understanding provider extensions** | [`docs/PROVIDER_ARCHITECTURE.md`](./docs/PROVIDER_ARCHITECTURE.md) → [`docs/PROVIDERS.md`](./docs/PROVIDERS.md) |
119
116
  | **Understanding verification trust** | [`docs/REVISION_PROVIDERS.md`](./docs/REVISION_PROVIDERS.md#differential-verification-scope) |
120
117
  | **Understanding attestation trust** | [`docs/CODE_ATTESTATION.md`](./docs/CODE_ATTESTATION.md#trust-levels) |
121
- | **Maintaining generated diagrams** | [`docs/diagrams/README.md`](./docs/diagrams/README.md) |
122
118
  | **Documentation contributor** | [`docs/DOCUMENTATION_GUIDE.md`](./docs/DOCUMENTATION_GUIDE.md) |
123
119
  | **Release maintainer (current)** | [`docs/RELEASE_CHECKLIST.md`](./docs/RELEASE_CHECKLIST.md) |
124
120
  | **Release maintainer (historical 1.5/MCP)** | [`docs/RELEASE_CHECKLIST_1_5_MCP.md`](./docs/RELEASE_CHECKLIST_1_5_MCP.md) |
@@ -148,7 +144,6 @@ is historical evidence and is not part of the published core package.
148
144
  - **Audit the npm package boundary**: [`docs/PACKAGE_CONTENTS.md`](./docs/PACKAGE_CONTENTS.md)
149
145
  - **Verify source-content attestations**: [`docs/CODE_ATTESTATION.md`](./docs/CODE_ATTESTATION.md)
150
146
  - **Understand narrow verification and checker binding**: [`docs/REVISION_PROVIDERS.md`](./docs/REVISION_PROVIDERS.md#differential-verification-scope)
151
- - **Inspect the governed diagrams**: [`docs/diagrams/README.md`](./docs/diagrams/README.md)
152
147
  - **Understand mandatory Jev semantics**: [`docs/SEMANTIC_DECISION_PLANE.md`](./docs/SEMANTIC_DECISION_PLANE.md)
153
148
  - **Understand model routing**: [`docs/MODEL_ROUTING.md`](./docs/MODEL_ROUTING.md)
154
149
  - **Review test utility and pruning safety**: [`docs/TEST_INTELLIGENCE.md`](./docs/TEST_INTELLIGENCE.md) and [`docs/TEST_PRUNING.md`](./docs/TEST_PRUNING.md)
@@ -180,8 +175,8 @@ process into adapters or README sections; link to the canonical source.
180
175
  ## Verification and release
181
176
 
182
177
  The Node regression suite, ESLint, c8, dependency policy, package boundary,
183
- attestation coverage, generated summaries/completions, and Archify diagram
184
- render are the local executable checks. Python validators remain
178
+ attestation coverage, and generated summaries/completions are the local
179
+ executable checks. Python validators remain
185
180
  frozen CI-only compatibility tools because they cover historical Markdown,
186
181
  loop, and secret-scanning contracts that have not been migrated to Node. Their
187
182
  scope, exact commands, and migration boundary are recorded in
@@ -197,12 +192,8 @@ and is not implied by local verification.
197
192
 
198
193
  ## Editing rules
199
194
 
200
- - Keep lifecycle prose, the typed Archify source, generated outputs, and the
201
- text-only README fallback synchronized.
202
- - Keep the generated HTML, SVG, and receipt synchronized with the Archify
203
- source by running `npm run docs:diagrams` and `npm run docs:check`. CI
204
- validates the renderer pin, source fingerprint, artifact hashes, and SVG
205
- safety constraints.
195
+ - Keep lifecycle prose and the text-only README fallback synchronized, and
196
+ run `npm run docs:check` after documentation changes.
206
197
  - Preserve the distinction between implemented behavior, local evidence, and
207
198
  external publication or production state.
208
199
  - Run `npm run lint`, `npm run coverage`, `npm run pack:check`, and the Python
@@ -723,5 +723,5 @@ data independently of that choice.
723
723
  - ChaCha20-Poly1305, RFC 8439: https://datatracker.ietf.org/doc/html/rfc8439
724
724
  - GitHub Actions: use full-length commit SHA: https://docs.github.com/en/actions/reference/security/secure-use
725
725
  - GitHub artifact attestations: https://docs.github.com/en/actions/how-tos/secure-your-work/use-artifact-attestations/use-artifact-attestations
726
- - Apple Platform Security Guide: https://support.apple.com/guide/security/
726
+ - Apple Platform Security Guide: https://help.apple.com/pdf/security/en_US/apple-platform-security-guide.pdf
727
727
  - Microsoft Security Development Lifecycle (SDL): https://www.microsoft.com/sdl
@@ -3,7 +3,7 @@ name: test-code-eng
3
3
  language: en
4
4
  description: "Risk-based testing strategy and tools for modern languages and platforms."
5
5
  version: "2026.09"
6
- last-reviewed: "2026-10-17"
6
+ last-reviewed: "2026-11-17"
7
7
  guide-id: test
8
8
  completion-evidence:
9
9
  - tests
@@ -221,6 +221,36 @@ Document hardware, region, build, configuration, dataset, and interference. Sepa
221
221
  - Expose flakiness count and rate per test/suite. Exceeding the local budget fails the gate or blocks suite expansion according to the recorded policy.
222
222
  - Fix synchronization, isolation, state, dependency, and environment; do not use increasing `sleep` as a solution. Remove a redundant test only with proof of equivalent coverage.
223
223
 
224
+ ## Honest tests: test landmines
225
+
226
+ Coding agents optimise for green checks. Left alone, they replace the
227
+ dependency under test, sleep until a race usually goes their way, retry the
228
+ flake, and raise the timeout. Each of these passes CI, and none of them
229
+ proves the behaviour. Treat the following as landmines: a change that adds
230
+ one fails review unless the record explains why no honest alternative
231
+ exists.
232
+
233
+ | Landmine | Instead |
234
+ | --- | --- |
235
+ | **Test doubles that replace real behaviour**: module, method or property mocks, patched globals, prototypes, clocks or `fetch`, hand-written fake responses for your own code. | Run the real implementation. Inject real collaborators, use a local server or emulator for the network, and use fakes only at true external boundaries you do not own. Observation-only spies are fine. |
236
+ | **Fixed sleeps**: awaiting a fixed real-time delay in a test or hook. | Await the operation or an event it emits. Control time with the framework's mock clock, such as `t.mock.timers` or `vi.useFakeTimers`. |
237
+ | **Unsignaled polling**: polling spy or recorder state until a deadline. | Await the signal (a promise, an event, a callback) that the state changed. |
238
+ | **Flake masking**: retries and raised per-test timeouts. | Fix the race, isolation or state. A test that passes only on rerun or with more time is a flake to fix (see the previous section). |
239
+ | **Unchecked network**: a request mock that lets unmatched requests reach the real network. | Fail on unhandled requests, for example MSW `onUnhandledRequest: "error"`. |
240
+
241
+ **Adoption in an existing suite.** Enforce these rules mechanically. Record
242
+ today's occurrences as an exact count per file, and fail both on a file
243
+ above its allowance (a new landmine) and on a file below it (a stale
244
+ allowance to lower). The list then only shrinks.
245
+
246
+ - **JavaScript and TypeScript with Oxlint:** use
247
+ [`@interfere/landmines`](https://github.com/interfere-inc/landmines). Its
248
+ rules target Vitest and MSW.
249
+ - **Other stacks:** encode the same rules in a small repository check.
250
+ - **ForgeLoop:** this repository does this with `npm run test:landmines`
251
+ (`scripts/check-test-landmines.mjs`), which runs in the fast, local and
252
+ pre-push tiers.
253
+
224
254
  ## CI cadence and evidence
225
255
 
226
256
  | Event | Expected gates |
@@ -296,6 +326,7 @@ Time-sensitive statements in this revision were verified on **2026-08-08**. Reva
296
326
  - [W3C — WebDriver](https://www.w3.org/TR/webdriver2/): standardized protocol used by drivers.
297
327
  - [Grafana k6 — thresholds](https://grafana.com/docs/k6/latest/using-k6/thresholds/) and [test types](https://grafana.com/docs/k6/latest/testing-guides/test-types/): pass/fail criteria, percentiles, smoke, spike, and soak.
298
328
  - [Playwright — retries](https://playwright.dev/docs/test-retries): distinguishes passed, flaky, and failed-after-retry outcomes.
329
+ - [interfere-inc/landmines](https://github.com/interfere-inc/landmines) (MIT): lint rules against test doubles, fixed sleeps, unsignaled polling and flake masking in AI-written tests, with per-file allowances that only shrink.
299
330
  - [VCR.py — filtering sensitive data](https://vcrpy.readthedocs.io/en/latest/advanced.html#filter-sensitive-data-from-the-request): filtering headers, query, body, and responses before recording.
300
331
  - [Prisma — expand-and-contract migrations](https://docs.prisma.io/docs/guides/database/data-migration): expand, migrate data, and contract sequence for production.
301
332
  - [Stryker — mutation testing](https://stryker-mutator.io/docs/): mutants used to evaluate the suite's detection ability.
@@ -387,9 +387,8 @@ in a revision range are covered. These relationships are intentionally not
387
387
  interchangeable.
388
388
 
389
389
  The [Verification Trust Flow](./docs/REVISION_PROVIDERS.md#differential-verification-scope)
390
- (`docs/diagrams/forgeloop-verification-trust-flow.workflow.json`) and [Code
391
- Attestation Chain](./docs/CODE_ATTESTATION.md#completion-flow) diagrams provide
392
- the focused visual fallbacks for these two boundaries.
390
+ and the [Code Attestation Chain](./docs/CODE_ATTESTATION.md#completion-flow)
391
+ describe these two boundaries in detail.
393
392
 
394
393
  ## Precedence and conflicts
395
394
 
@@ -55,7 +55,6 @@ an external runner, pull request, or publication boundary.
55
55
  | SigningProvider | `docs/SIGNING_PROVIDERS.md` | `src/core/signing/provider.js`, `src/core/signing/registry.js` | Sigstore bundle and signing provider contracts | `tests/signing-provider.test.js`, `tests/signing-provider-conformance.test.js` | Invalid provider, missing signature, and policy mismatch cases | Local conformance; external signer pending | VERIFIED / NOT_ATTESTED |
56
56
  | Revision-range coverage | `docs/CODE_ATTESTATION.md` | `src/core/attestation-coverage.js` | `schemas/attestation-verification-result.schema.json` | `tests/attestation-coverage.test.js`, `tests/attestation-e2e.test.js` | Missing, conflicting, stale, and incomplete coverage cases | Local range checks; external revision range pending | VERIFIED / NOT_ATTESTED |
57
57
  | Generic CI attestation | `integrations/generic-ci/verify.sh`, `docs/UNIVERSAL_INTEGRATION.md` | Generic CI verification and evidence boundary | CI verification outputs and attestation inputs | `tests/generic-ci-attestation.test.js` | Invalid or incomplete CI evidence cases | Pull-request workflow evidence required for ATTESTED | VERIFIED / NOT_ATTESTED |
58
- | Documentation diagrams | `docs/diagrams/manifest.json`, `docs/DOCUMENTATION_GUIDE.md`, `docs/diagrams/forgeloop-code-attestation-flow.workflow.json` | Typed Archify workflow sources and pinned renderer wrapper | Generated HTML/SVG/receipt/review artifacts | `tests/documentation-diagrams.test.js`, `tests/documentation-diagram-manifest.test.js`, `tests/documentation-portability.test.js` | Stale output, missing review, unsupported renderer, orphan, reduced-motion, and deterministic-generation cases | Local renderer and structural accessibility checks; visual review is source-bound | VERIFIED / NOT_ATTESTED |
59
58
 
60
59
  ## Score rules
61
60
 
package/README.md CHANGED
@@ -80,7 +80,7 @@ See the [23-guide maintenance map](./docs/GUIDE_MAINTENANCE.md) for review scope
80
80
  ## Distribution and license
81
81
 
82
82
  GitHub hosts source and issues. The core npm package is public; the MCP
83
- companion has restricted distribution. Stable `2.1.0` is on npm `latest` with
83
+ companion has restricted distribution. Stable `2.2.0` is on npm `latest` with
84
84
  provenance and verified release identity.
85
85
  ForgeLoop-owned source and documentation are licensed under the
86
86
  [PolyForm Noncommercial License 1.0.0](./LICENSE): free for noncommercial use.
@@ -433,46 +433,18 @@ See [`docs/CLI_REFERENCE.md`](./docs/CLI_REFERENCE.md) and [`LOOP_SYSTEM_DESIGN.
433
433
 
434
434
  ## Architecture flow
435
435
 
436
- <a href="./docs/assets/diagrams/forgeloop-engineering-flow.html">
437
- <img src="./docs/assets/forgeloop-lifecycle-animated.svg" alt="Animated ForgeLoop evidence-first loop: Contract, Route, Preflight, Execute, Evidence, Review, VALID, with an evidence-only correction loop" width="100%">
438
- </a>
436
+ <img src="./docs/assets/forgeloop-lifecycle-animated.svg" alt="Animated ForgeLoop evidence-first loop: Contract, Route, Preflight, Execute, Evidence, Review, VALID, with an evidence-only correction loop" width="100%">
439
437
 
440
438
  *Animation: the rail pulses through each step in order. It loops forever and
441
- respects reduced-motion settings. Select the image to open the full animated
442
- interactive explorer.*
443
-
444
- The canonical source is the typed Archify workflow
445
- [`docs/diagrams/forgeloop-engineering-flow.workflow.json`](./docs/diagrams/forgeloop-engineering-flow.workflow.json).
446
- The committed animated interactive explorer is
447
- [`docs/assets/diagrams/forgeloop-engineering-flow.html`](./docs/assets/diagrams/forgeloop-engineering-flow.html),
448
- which traces it. The
449
- detailed, self-contained SVG fallback is
450
- [`docs/assets/diagrams/forgeloop-engineering-flow.svg`](./docs/assets/diagrams/forgeloop-engineering-flow.svg),
451
- and the deterministic hash receipt is
452
- [`docs/assets/diagrams/forgeloop-engineering-flow.receipt.json`](./docs/assets/diagrams/forgeloop-engineering-flow.receipt.json).
453
- The governance source is [`docs/diagrams/manifest.json`](./docs/diagrams/manifest.json),
454
- and the source-bound visual approval is kept in
455
- [`docs/diagrams/reviews/forgeloop-engineering-flow.review.json`](./docs/diagrams/reviews/forgeloop-engineering-flow.review.json).
439
+ respects reduced-motion settings.*
440
+
456
441
  The broader architecture and the CLI-only search boundary are in
457
442
  [`LOOP_SYSTEM_DESIGN.md`](./LOOP_SYSTEM_DESIGN.md) and
458
443
  [`PERSISTENT_SEARCH_TRANSPORT.md`](./docs/PERSISTENT_SEARCH_TRANSPORT.md).
459
-
460
- [Open the animated ForgeLoop evidence-first engineering flow](./docs/assets/diagrams/forgeloop-engineering-flow.html)
461
-
462
- Two focused, source-bound workflow
463
- diagrams complement it. The [Verification Trust Flow source](./docs/diagrams/forgeloop-verification-trust-flow.workflow.json),
464
- [animated explorer](./docs/assets/diagrams/forgeloop-verification-trust-flow.html),
465
- [SVG fallback](./docs/assets/diagrams/forgeloop-verification-trust-flow.svg),
466
- [receipt](./docs/assets/diagrams/forgeloop-verification-trust-flow.receipt.json),
467
- and [visual review](./docs/diagrams/reviews/forgeloop-verification-trust-flow.review.json)
468
- show fail-closed verification. The [Code Attestation Chain
469
- source](./docs/diagrams/forgeloop-code-attestation-flow.workflow.json),
470
- [animated explorer](./docs/assets/diagrams/forgeloop-code-attestation-flow.html),
471
- [SVG fallback](./docs/assets/diagrams/forgeloop-code-attestation-flow.svg),
472
- [receipt](./docs/assets/diagrams/forgeloop-code-attestation-flow.receipt.json),
473
- and [visual review](./docs/diagrams/reviews/forgeloop-code-attestation-flow.review.json)
474
- show exact content binding, optional signing, and separate revision-range
475
- coverage.
444
+ Fail-closed verification is described in
445
+ [`docs/REVISION_PROVIDERS.md`](./docs/REVISION_PROVIDERS.md#differential-verification-scope).
446
+ Exact content binding, optional signing and revision-range coverage are
447
+ described in [`docs/CODE_ATTESTATION.md`](./docs/CODE_ATTESTATION.md#completion-flow).
476
448
 
477
449
  Text-only fallback: discovery creates the contract and route; parsed project
478
450
  manifests/build metadata select the corresponding language specialist; owned
@@ -538,8 +510,7 @@ Install-capable verification requires trusted host authority; see
538
510
  [`THREAT_MODEL.md`](./THREAT_MODEL.md).
539
511
 
540
512
  c8, ESLint, TypeScript, and YAML remain development-only. The dependency
541
- policy rejects unapproved runtime or development dependencies. Archify is
542
- vendored at `vendor/archify/v2.15.0/` rather than installed as a package.
513
+ policy rejects unapproved runtime or development dependencies.
543
514
 
544
515
  To report vulnerabilities or contribute changes, see
545
516
  [`SECURITY.md`](./SECURITY.md) and [`CONTRIBUTING.md`](./CONTRIBUTING.md).
@@ -609,7 +580,6 @@ npm run lint
609
580
  npm run coverage
610
581
  npm run pack:check
611
582
  npm run dependency:policy
612
- npm run docs:diagrams
613
583
  npm run docs:check
614
584
  npm run completions:check
615
585
  npm run summary:check
@@ -622,9 +592,7 @@ npm run changelog:check
622
592
  src/ npm CLI and protocol implementation
623
593
  schemas/ versioned artifact schemas
624
594
  ENG/ package-source engineering guides
625
- docs/diagrams/ typed Archify diagram source and inventory
626
- docs/assets/diagrams/ committed HTML, SVG, and generation receipt
627
- scripts/ checks, renderer, release identity, CI notes
595
+ scripts/ checks, release identity, CI notes
628
596
  tests/ Node and Python regression coverage
629
597
  .forgeloop/ project-scoped configuration
630
598
  .forgeloop/task-state/ isolated live task protocol state
@@ -64,21 +64,6 @@ inclusion does not install, bundle, or declare any project as a dependency of
64
64
  this collection. Check the specific project's current license, terms,
65
65
  dependencies, version, and distribution conditions before adoption.
66
66
 
67
- ### Archify v2.15.0 — vendored documentation renderer
68
-
69
- - Project/source: [tt-a1i/archify](https://github.com/tt-a1i/archify/tree/v2.15.0).
70
- - Pinned source commit: `e1ac748f19cf805e44bf74fb93c796662152e273`.
71
- - License declared by the upstream project: MIT; the vendored license is at
72
- `vendor/archify/v2.15.0/archify/LICENSE`.
73
- - Use in this collection: deterministic generation and validation of the
74
- typed workflow diagram under `docs/diagrams/`.
75
- - Boundary: this is a documentation-only vendored toolchain, not a ForgeLoop
76
- runtime dependency. It is not installed from a registry, and its exact pin,
77
- source, license, and raw-byte tree hashes are recorded in
78
- `vendor/archify/v2.15.0/PIN.json`; output hashes are recorded in the receipt.
79
- The vendor integrity check rejects modified, missing, extra, renamed, or
80
- symlinked files before the renderer is trusted.
81
-
82
67
  ### Superpowers
83
68
 
84
69
  - Project: [Superpowers](https://github.com/obra/superpowers).
@@ -1,7 +1,7 @@
1
1
  #compdef forgeloop
2
2
  # Generated by scripts/generate-shell-completions.mjs. Do not edit.
3
3
  _arguments \
4
- '1:command:(action-authorize action-propose action-reconcile action-record action-show action-verify activate advance approval-request approval-resolve assess attestation-create attestation-status attestation-verify attestation-verify-range audit baseline bundle checkpoint-revalidate clear-continuity clear-state complete context-plan continuity contract-create contract-revise decision-show decision-status discover doctor efficiency eval evidence-export evidence-verify gate-record gate-revalidate handoff-accept handoff-create handoff-list handoff-show history index-rebuild index-setup index-start index-status index-stop init inspect metrics migrate-protocol model-route next policy policy-diff policy-discover policy-status preflight prepare-completion profile-interview progress protocol-info quality-baseline quality-status quality-verify reconcile-closure reconcile-continuity record-check record-continuity record-decision-criterion record-diagnosis record-hypothesis-disposition record-intervention record-terminal-result reflect report responsibility-set responsibility-status route rule-verify run-action run-check search semantic-plan status storage-backup storage-migrate storage-migration-resume storage-migration-status storage-restore storage-restore-resume storage-rollback storage-rollback-resume sync-pull sync-push task-abandon task-create task-list task-lock-status task-migrate task-migrate-contract-bootstrap-repair task-recover task-repair-contract-bootstrap task-repair-legacy-recovery task-resume task-scope task-show task-unlock test-inventory test-prune-plan test-prune-probe test-utility trace update usage-record validate-protocol validate-receipt validate-state verify-scope workspace-bind workspace-status)' \
4
+ '1:command:(action-authorize action-propose action-reconcile action-record action-show action-verify activate advance approval-request approval-resolve assess attestation-create attestation-status attestation-verify attestation-verify-range audit baseline bundle checkpoint-revalidate clear-continuity clear-state complete context-plan continuity contract-create contract-revise decision-show decision-status discover doctor efficiency eval evidence-export evidence-publish evidence-verify gate-record gate-revalidate handoff-accept handoff-create handoff-list handoff-show history index-rebuild index-setup index-start index-status index-stop init inspect metrics migrate-protocol model-route next policy policy-diff policy-discover policy-status preflight prepare-completion profile-interview progress protocol-info quality-baseline quality-status quality-verify reconcile-closure reconcile-continuity record-check record-continuity record-decision-criterion record-diagnosis record-hypothesis-disposition record-intervention record-terminal-result reflect report responsibility-set responsibility-status route rule-verify run-action run-check search semantic-plan status storage-backup storage-migrate storage-migration-resume storage-migration-status storage-restore storage-restore-resume storage-rollback storage-rollback-resume sync-pull sync-push task-abandon task-create task-list task-lock-status task-migrate task-migrate-contract-bootstrap-repair task-recover task-repair-contract-bootstrap task-repair-legacy-recovery task-resume task-scope task-show task-unlock test-inventory test-prune-plan test-prune-probe test-utility trace update usage-record validate-protocol validate-receipt validate-state verify-scope workspace-bind workspace-status)' \
5
5
  '*::options:->options'
6
6
  case $words[2] in
7
7
  action-authorize) _arguments '--action[durable action ID]' '--approval[current fingerprint-bound approval]' '--help[show this help]' '--json[emit structured output as JSON]' '--path[target project directory (default: current directory)]' '--task[task ID to operate on (when omitted, resolved from context or single active task)]' '--version[show the installed package version]' ;;
@@ -37,6 +37,7 @@ case $words[2] in
37
37
  efficiency) _arguments '--baseline[optional comparable efficiency baseline JSON]' '--help[show this help]' '--json[emit efficiency metrics as JSON]' '--path[target project directory (default: current directory)]' '--task[task ID to operate on (when omitted, resolved from context or single active task)]' '--version[show the installed package version]' ;;
38
38
  eval) _arguments '--help[show this help]' '--json[emit evaluation as JSON]' '--path[target project directory (default: current directory)]' '--scenario[project-local trajectory scenario JSON]' '--task[task ID to operate on (when omitted, resolved from context or single active task)]' '--version[show the installed package version]' ;;
39
39
  evidence-export) _arguments '--dir[tracked evidence directory (default: .forgeloop-evidence)]' '--help[show this help]' '--json[emit the export result as JSON]' '--path[target project directory (default: current directory)]' '--task[task ID to operate on (when omitted, resolved from context or single active task)]' '--version[show the installed package version]' ;;
40
+ evidence-publish) _arguments '--all[publish every bundle in the evidence directory]' '--dir[tracked evidence directory (default: .forgeloop-evidence)]' '--help[show this help]' '--json[emit the publish result as JSON]' '--path[target project directory (default: current directory)]' '--remote[evidence endpoint (default: https://forgeloop.monster/api/evidence)]' '--repo[repository the bundles belong to (default: from the git origin)]' '--task[publish this task'\"'\"'s exported bundle]' '--version[show the installed package version]' ;;
40
41
  evidence-verify) _arguments '--allow-partial-coverage[report uncovered changed paths without failing]' '--base[base revision of the verified range]' '--dir[tracked evidence directory (default: .forgeloop-evidence)]' '--exclude[changed path or dir/** excluded from coverage (verifier policy)]' '--format[human output format (default: text)]' '--head[head revision of the verified range]' '--help[show this help]' '--identity[exact signer identity policy]' '--issuer[exact signer issuer policy]' '--json[emit the verification result as JSON]' '--path[target project directory (default: current directory)]' '--require-signature[require a valid Sigstore signature for every bundle used]' '--revision-provider[revision provider (default: git)]' '--trusted-root[trusted signing root path]' '--version[show the installed package version]' ;;
41
42
  gate-record) _arguments '--artifact[project-relative evidence artifact]' '--assumption[approved local assumption]' '--decision[caller-recorded gate decision]' '--evidence-file[bounded local descriptive evidence JSON]' '--gate[required gate name]' '--help[show this help]' '--json[emit structured gate output as JSON]' '--path[target project directory (default: current directory)]' '--status[satisfied, unverified, or blocked]' '--task[task ID to operate on (when omitted, resolved from context or single active task)]' '--unknown[known unresolved item]' '--version[show the installed package version]' ;;
42
43
  gate-revalidate) _arguments '--acknowledge-stale[explicitly acknowledge refresh of stale gate artifacts inside active task claims]' '--gate[satisfied gate to refresh after safe artifact drift]' '--help[show this help]' '--json[emit structured gate revalidation output as JSON]' '--path[target project directory (default: current directory)]' '--task[task ID to operate on (when omitted, resolved from context or single active task)]' '--version[show the installed package version]' ;;
@@ -96,7 +97,7 @@ case $words[2] in
96
97
  storage-restore-resume) _arguments '--expected-owner[exact retained maintenance owner UUID]' '--help[show this help]' '--json[emit restore recovery metadata]' '--operation[exact retained restore journal operation UUID]' '--path[target project directory (default: current directory)]' '--replace-active[explicitly select active replacement with retained outgoing authority]' '--version[show the installed package version]' '--writers-quiesced[assert that all writers have been externally stopped]' ;;
97
98
  storage-rollback) _arguments '--destination[retained published migration directory relative to the project]' '--help[show this help]' '--json[emit restoration and target-validation metadata]' '--legacy-root[clean supported pinned legacy checkout used for actual target validation]' '--native-writes-excluded[assert that native writes have been excluded since migration; snapshot equality alone does not prove this]' '--path[target project directory (default: current directory)]' '--version[show the installed package version]' '--writers-quiesced[assert that all writers, including older clients, have been externally stopped and excluded]' ;;
98
99
  storage-rollback-resume) _arguments '--destination[retained migration with recorded rollback preparation, staging or publication]' '--expected-owner[exact retained dead local owner reported by storage-migration-status]' '--help[show this help]' '--json[emit restoration and target-validation metadata]' '--legacy-root[clean supported pinned legacy checkout used for actual target validation]' '--native-writes-excluded[assert that native writes have been excluded since migration; snapshot equality alone does not prove this]' '--path[target project directory (default: current directory)]' '--version[show the installed package version]' '--writers-quiesced[assert that all writers, including older clients, have been externally stopped and excluded]' ;;
99
- sync-pull) _arguments '--help[show this help]' '--json[emit the pull and restore result as JSON]' '--path[target project directory (default: current directory)]' '--remote[sync endpoint (default: https://forgeloop.monster/api/sync)]' '--replace-active[replace existing local state; the outgoing state is retained and archived]' '--repo[repository the snapshot belongs to (default: from the git origin)]' '--version[show the installed package version]' '--writers-quiesced[assert that all writers have been externally stopped]' ;;
100
+ sync-pull) _arguments '--dry-run[with --merge, report the per-task plan without changing anything]' '--help[show this help]' '--json[emit the pull and restore result as JSON]' '--merge[combine whole tasks three-way with local state instead of replacing it]' '--path[target project directory (default: current directory)]' '--remote[sync endpoint (default: https://forgeloop.monster/api/sync)]' '--replace-active[replace existing local state; the outgoing state is retained and archived]' '--repo[repository the snapshot belongs to (default: from the git origin)]' '--version[show the installed package version]' '--writers-quiesced[assert that all writers have been externally stopped]' ;;
100
101
  sync-push) _arguments '--help[show this help]' '--json[emit the push result as JSON]' '--path[target project directory (default: current directory)]' '--remote[sync endpoint (default: https://forgeloop.monster/api/sync)]' '--repo[repository the snapshot belongs to (default: from the git origin)]' '--version[show the installed package version]' ;;
101
102
  task-abandon) _arguments '--acknowledge-abandonment[explicitly acknowledge abandonment of an active task (required; not completion authority)]' '--help[show this help]' '--json[emit structured abandonment output as JSON]' '--path[target project directory (default: current directory)]' '--task[task ID to operate on (when omitted, resolved from context or single active task)]' '--version[show the installed package version]' ;;
102
103
  task-create) _arguments '--claim[scoped file path or directory prefix claimed for mutation]' '--contract-file[path to initial contract file]' '--help[show this help]' '--json[emit structured output as JSON]' '--path[target project directory (default: current directory)]' '--preset[bounded contract preset: documentation, bug, feature, or release]' '--preview[preview the contract without creating lifecycle state]' '--task[task ID to operate on (when omitted, resolved from context or single active task)]' '--version[show the installed package version]' ;;
@@ -39,6 +39,7 @@ _forgeloop() {
39
39
  efficiency) command="efficiency" ;;
40
40
  eval) command="eval" ;;
41
41
  evidence-export) command="evidence-export" ;;
42
+ evidence-publish) command="evidence-publish" ;;
42
43
  evidence-verify) command="evidence-verify" ;;
43
44
  gate-record) command="gate-record" ;;
44
45
  gate-revalidate) command="gate-revalidate" ;;
@@ -129,7 +130,7 @@ _forgeloop() {
129
130
  esac
130
131
  done
131
132
  if [[ -z "\${command}" && "\${cur}" != -* ]]; then
132
- COMPREPLY=( $(compgen -W 'action-authorize action-propose action-reconcile action-record action-show action-verify activate advance approval-request approval-resolve assess attestation-create attestation-status attestation-verify attestation-verify-range audit baseline bundle checkpoint-revalidate clear-continuity clear-state complete context-plan continuity contract-create contract-revise decision-show decision-status discover doctor efficiency eval evidence-export evidence-verify gate-record gate-revalidate handoff-accept handoff-create handoff-list handoff-show history index-rebuild index-setup index-start index-status index-stop init inspect metrics migrate-protocol model-route next policy policy-diff policy-discover policy-status preflight prepare-completion profile-interview progress protocol-info quality-baseline quality-status quality-verify reconcile-closure reconcile-continuity record-check record-continuity record-decision-criterion record-diagnosis record-hypothesis-disposition record-intervention record-terminal-result reflect report responsibility-set responsibility-status route rule-verify run-action run-check search semantic-plan status storage-backup storage-migrate storage-migration-resume storage-migration-status storage-restore storage-restore-resume storage-rollback storage-rollback-resume sync-pull sync-push task-abandon task-create task-list task-lock-status task-migrate task-migrate-contract-bootstrap-repair task-recover task-repair-contract-bootstrap task-repair-legacy-recovery task-resume task-scope task-show task-unlock test-inventory test-prune-plan test-prune-probe test-utility trace update usage-record validate-protocol validate-receipt validate-state verify-scope workspace-bind workspace-status' -- "$cur") )
133
+ COMPREPLY=( $(compgen -W 'action-authorize action-propose action-reconcile action-record action-show action-verify activate advance approval-request approval-resolve assess attestation-create attestation-status attestation-verify attestation-verify-range audit baseline bundle checkpoint-revalidate clear-continuity clear-state complete context-plan continuity contract-create contract-revise decision-show decision-status discover doctor efficiency eval evidence-export evidence-publish evidence-verify gate-record gate-revalidate handoff-accept handoff-create handoff-list handoff-show history index-rebuild index-setup index-start index-status index-stop init inspect metrics migrate-protocol model-route next policy policy-diff policy-discover policy-status preflight prepare-completion profile-interview progress protocol-info quality-baseline quality-status quality-verify reconcile-closure reconcile-continuity record-check record-continuity record-decision-criterion record-diagnosis record-hypothesis-disposition record-intervention record-terminal-result reflect report responsibility-set responsibility-status route rule-verify run-action run-check search semantic-plan status storage-backup storage-migrate storage-migration-resume storage-migration-status storage-restore storage-restore-resume storage-rollback storage-rollback-resume sync-pull sync-push task-abandon task-create task-list task-lock-status task-migrate task-migrate-contract-bootstrap-repair task-recover task-repair-contract-bootstrap task-repair-legacy-recovery task-resume task-scope task-show task-unlock test-inventory test-prune-plan test-prune-probe test-utility trace update usage-record validate-protocol validate-receipt validate-state verify-scope workspace-bind workspace-status' -- "$cur") )
133
134
  return
134
135
  fi
135
136
  case "\${command}" in
@@ -166,6 +167,7 @@ _forgeloop() {
166
167
  efficiency) COMPREPLY=( $(compgen -W '--baseline --help --json --path --task --version' -- "$cur") );;
167
168
  eval) COMPREPLY=( $(compgen -W '--help --json --path --scenario --task --version' -- "$cur") );;
168
169
  evidence-export) COMPREPLY=( $(compgen -W '--dir --help --json --path --task --version' -- "$cur") );;
170
+ evidence-publish) COMPREPLY=( $(compgen -W '--all --dir --help --json --path --remote --repo --task --version' -- "$cur") );;
169
171
  evidence-verify) COMPREPLY=( $(compgen -W '--allow-partial-coverage --base --dir --exclude --format --head --help --identity --issuer --json --path --require-signature --revision-provider --trusted-root --version' -- "$cur") );;
170
172
  gate-record) COMPREPLY=( $(compgen -W '--artifact --assumption --decision --evidence-file --gate --help --json --path --status --task --unknown --version' -- "$cur") );;
171
173
  gate-revalidate) COMPREPLY=( $(compgen -W '--acknowledge-stale --gate --help --json --path --task --version' -- "$cur") );;
@@ -225,7 +227,7 @@ _forgeloop() {
225
227
  storage-restore-resume) COMPREPLY=( $(compgen -W '--expected-owner --help --json --operation --path --replace-active --version --writers-quiesced' -- "$cur") );;
226
228
  storage-rollback) COMPREPLY=( $(compgen -W '--destination --help --json --legacy-root --native-writes-excluded --path --version --writers-quiesced' -- "$cur") );;
227
229
  storage-rollback-resume) COMPREPLY=( $(compgen -W '--destination --expected-owner --help --json --legacy-root --native-writes-excluded --path --version --writers-quiesced' -- "$cur") );;
228
- sync-pull) COMPREPLY=( $(compgen -W '--help --json --path --remote --replace-active --repo --version --writers-quiesced' -- "$cur") );;
230
+ sync-pull) COMPREPLY=( $(compgen -W '--dry-run --help --json --merge --path --remote --replace-active --repo --version --writers-quiesced' -- "$cur") );;
229
231
  sync-push) COMPREPLY=( $(compgen -W '--help --json --path --remote --repo --version' -- "$cur") );;
230
232
  task-abandon) COMPREPLY=( $(compgen -W '--acknowledge-abandonment --help --json --path --task --version' -- "$cur") );;
231
233
  task-create) COMPREPLY=( $(compgen -W '--claim --contract-file --help --json --path --preset --preview --task --version' -- "$cur") );;
@@ -1,5 +1,5 @@
1
1
  # Generated by scripts/generate-shell-completions.mjs. Do not edit.
2
- complete -c forgeloop -f -n '__fish_use_subcommand' -a 'action-authorize action-propose action-reconcile action-record action-show action-verify activate advance approval-request approval-resolve assess attestation-create attestation-status attestation-verify attestation-verify-range audit baseline bundle checkpoint-revalidate clear-continuity clear-state complete context-plan continuity contract-create contract-revise decision-show decision-status discover doctor efficiency eval evidence-export evidence-verify gate-record gate-revalidate handoff-accept handoff-create handoff-list handoff-show history index-rebuild index-setup index-start index-status index-stop init inspect metrics migrate-protocol model-route next policy policy-diff policy-discover policy-status preflight prepare-completion profile-interview progress protocol-info quality-baseline quality-status quality-verify reconcile-closure reconcile-continuity record-check record-continuity record-decision-criterion record-diagnosis record-hypothesis-disposition record-intervention record-terminal-result reflect report responsibility-set responsibility-status route rule-verify run-action run-check search semantic-plan status storage-backup storage-migrate storage-migration-resume storage-migration-status storage-restore storage-restore-resume storage-rollback storage-rollback-resume sync-pull sync-push task-abandon task-create task-list task-lock-status task-migrate task-migrate-contract-bootstrap-repair task-recover task-repair-contract-bootstrap task-repair-legacy-recovery task-resume task-scope task-show task-unlock test-inventory test-prune-plan test-prune-probe test-utility trace update usage-record validate-protocol validate-receipt validate-state verify-scope workspace-bind workspace-status'
2
+ complete -c forgeloop -f -n '__fish_use_subcommand' -a 'action-authorize action-propose action-reconcile action-record action-show action-verify activate advance approval-request approval-resolve assess attestation-create attestation-status attestation-verify attestation-verify-range audit baseline bundle checkpoint-revalidate clear-continuity clear-state complete context-plan continuity contract-create contract-revise decision-show decision-status discover doctor efficiency eval evidence-export evidence-publish evidence-verify gate-record gate-revalidate handoff-accept handoff-create handoff-list handoff-show history index-rebuild index-setup index-start index-status index-stop init inspect metrics migrate-protocol model-route next policy policy-diff policy-discover policy-status preflight prepare-completion profile-interview progress protocol-info quality-baseline quality-status quality-verify reconcile-closure reconcile-continuity record-check record-continuity record-decision-criterion record-diagnosis record-hypothesis-disposition record-intervention record-terminal-result reflect report responsibility-set responsibility-status route rule-verify run-action run-check search semantic-plan status storage-backup storage-migrate storage-migration-resume storage-migration-status storage-restore storage-restore-resume storage-rollback storage-rollback-resume sync-pull sync-push task-abandon task-create task-list task-lock-status task-migrate task-migrate-contract-bootstrap-repair task-recover task-repair-contract-bootstrap task-repair-legacy-recovery task-resume task-scope task-show task-unlock test-inventory test-prune-plan test-prune-probe test-utility trace update usage-record validate-protocol validate-receipt validate-state verify-scope workspace-bind workspace-status'
3
3
  complete -c forgeloop -f -n '__fish_seen_subcommand_from action-authorize' -l 'action' -d 'durable action ID'
4
4
  complete -c forgeloop -f -n '__fish_seen_subcommand_from action-authorize' -l 'approval' -d 'current fingerprint-bound approval'
5
5
  complete -c forgeloop -f -n '__fish_seen_subcommand_from action-authorize' -l 'help' -d 'show this help'
@@ -225,6 +225,15 @@ complete -c forgeloop -f -n '__fish_seen_subcommand_from evidence-export' -l 'js
225
225
  complete -c forgeloop -f -n '__fish_seen_subcommand_from evidence-export' -l 'path' -d 'target project directory (default: current directory)'
226
226
  complete -c forgeloop -f -n '__fish_seen_subcommand_from evidence-export' -l 'task' -d 'task ID to operate on (when omitted, resolved from context or single active task)'
227
227
  complete -c forgeloop -f -n '__fish_seen_subcommand_from evidence-export' -l 'version' -d 'show the installed package version'
228
+ complete -c forgeloop -f -n '__fish_seen_subcommand_from evidence-publish' -l 'all' -d 'publish every bundle in the evidence directory'
229
+ complete -c forgeloop -f -n '__fish_seen_subcommand_from evidence-publish' -l 'dir' -d 'tracked evidence directory (default: .forgeloop-evidence)'
230
+ complete -c forgeloop -f -n '__fish_seen_subcommand_from evidence-publish' -l 'help' -d 'show this help'
231
+ complete -c forgeloop -f -n '__fish_seen_subcommand_from evidence-publish' -l 'json' -d 'emit the publish result as JSON'
232
+ complete -c forgeloop -f -n '__fish_seen_subcommand_from evidence-publish' -l 'path' -d 'target project directory (default: current directory)'
233
+ complete -c forgeloop -f -n '__fish_seen_subcommand_from evidence-publish' -l 'remote' -d 'evidence endpoint (default: https://forgeloop.monster/api/evidence)'
234
+ complete -c forgeloop -f -n '__fish_seen_subcommand_from evidence-publish' -l 'repo' -d 'repository the bundles belong to (default: from the git origin)'
235
+ complete -c forgeloop -f -n '__fish_seen_subcommand_from evidence-publish' -l 'task' -d 'publish this task\'s exported bundle'
236
+ complete -c forgeloop -f -n '__fish_seen_subcommand_from evidence-publish' -l 'version' -d 'show the installed package version'
228
237
  complete -c forgeloop -f -n '__fish_seen_subcommand_from evidence-verify' -l 'allow-partial-coverage' -d 'report uncovered changed paths without failing'
229
238
  complete -c forgeloop -f -n '__fish_seen_subcommand_from evidence-verify' -l 'base' -d 'base revision of the verified range'
230
239
  complete -c forgeloop -f -n '__fish_seen_subcommand_from evidence-verify' -l 'dir' -d 'tracked evidence directory (default: .forgeloop-evidence)'
@@ -675,8 +684,10 @@ complete -c forgeloop -f -n '__fish_seen_subcommand_from storage-rollback-resume
675
684
  complete -c forgeloop -f -n '__fish_seen_subcommand_from storage-rollback-resume' -l 'path' -d 'target project directory (default: current directory)'
676
685
  complete -c forgeloop -f -n '__fish_seen_subcommand_from storage-rollback-resume' -l 'version' -d 'show the installed package version'
677
686
  complete -c forgeloop -f -n '__fish_seen_subcommand_from storage-rollback-resume' -l 'writers-quiesced' -d 'assert that all writers, including older clients, have been externally stopped and excluded'
687
+ complete -c forgeloop -f -n '__fish_seen_subcommand_from sync-pull' -l 'dry-run' -d 'with --merge, report the per-task plan without changing anything'
678
688
  complete -c forgeloop -f -n '__fish_seen_subcommand_from sync-pull' -l 'help' -d 'show this help'
679
689
  complete -c forgeloop -f -n '__fish_seen_subcommand_from sync-pull' -l 'json' -d 'emit the pull and restore result as JSON'
690
+ complete -c forgeloop -f -n '__fish_seen_subcommand_from sync-pull' -l 'merge' -d 'combine whole tasks three-way with local state instead of replacing it'
680
691
  complete -c forgeloop -f -n '__fish_seen_subcommand_from sync-pull' -l 'path' -d 'target project directory (default: current directory)'
681
692
  complete -c forgeloop -f -n '__fish_seen_subcommand_from sync-pull' -l 'remote' -d 'sync endpoint (default: https://forgeloop.monster/api/sync)'
682
693
  complete -c forgeloop -f -n '__fish_seen_subcommand_from sync-pull' -l 'replace-active' -d 'replace existing local state; the outgoing state is retained and archived'
@@ -7,7 +7,7 @@
7
7
  ForgeLoop is a portable protocol and support CLI for verifiable engineering workflows. It records and validates task state, contracts, routing, checks, evidence, continuity, and optional code attestations. It does not become an agent scheduler, delegation service, source-control authority, or secret manager.
8
8
 
9
9
  Protocol version: 1
10
- Package version: 2.2.0
10
+ Package version: 2.3.0
11
11
 
12
12
  ## Canonical loop
13
13
 
@@ -241,6 +241,7 @@ capability-family versions.
241
241
  | attestation-verify | READ_ONLY | Verifies a task attestation and current revision without mutating task state. |
242
242
  | attestation-verify-range | READ_ONLY | Verifies complete attestation coverage for an opaque revision range through a provider-neutral contract. |
243
243
  | evidence-export | MUTATING | Exports a completed task's attestation as a portable, redacted evidence bundle to commit with the change. |
244
+ | evidence-publish | MUTATING | 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. |
244
245
  | evidence-verify | READ_ONLY | Verifies committed evidence bundles for a revision range without local ForgeLoop state; signatures raise the level from INTEGRITY_ONLY to ATTESTED. |
245
246
 
246
247
  ### continuity
@@ -344,7 +345,7 @@ capability-family versions.
344
345
  | storage-restore-resume | MUTATING | Adopts an exact dead local maintenance owner and resumes restore. Incomplete snapshots and prior rebuild intents are retained before rebuilding from bound source; completed preparation requires source parity/domain validation. Use --replace-active for preparation or publication replacement recovery. Conflicting intents and retained handoff locks remain refused. |
345
346
  | storage-rollback | MUTATING | Conditionally restores preserved source before native writes, retaining original native bytes and validating every task with the supported pinned legacy target before release. Failures retain exclusion; post-write restoration is refused. |
346
347
  | storage-rollback-resume | MUTATING | Resumes recorded rollback preparation, staging or publication under exact dead-owner adoption, revalidates native/source locations, and validates every task with the pinned target before release. Unbound attempts remain refused. |
347
- | sync-pull | MUTATING | Downloads, decrypts and verifies the repository's sync snapshot, then activates it through storage-restore: into a fresh project, or replacing local state only with --replace-active. |
348
+ | sync-pull | MUTATING | 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. |
348
349
  | sync-push | MUTATING | Uploads a client-side encrypted (FORGELOOP_SYNC_KEY) backup of this project's ForgeLoop state to the sync remote, authenticated by FORGELOOP_SYNC_TOKEN. A push based on a stale remote version is refused with E_SYNC_CONFLICT. |
349
350
  | task-abandon | MUTATING | Explicitly abandons an active non-terminal task; records append-only evidence and releases claims without completion authority. |
350
351
  | task-migrate | MUTATING | Migrates legacy singleton task state into SQLite with retained source and verified publication evidence. |
@@ -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)*
@@ -187,6 +187,8 @@ only with `--replace-active`. Requires `--writers-quiesced`.
187
187
  - `--remote <url>`: sync endpoint (default: https://forgeloop.monster/api/sync)
188
188
  - `--repo <owner/name>`: repository the snapshot belongs to (default: from the git origin)
189
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
190
192
  - `--writers-quiesced`: assert that all writers have been externally stopped
191
193
  - `--json`: emit the pull and restore result as JSON
192
194
 
@@ -384,7 +386,7 @@ error codes. Default output and default JSON remain unchanged.
384
386
  | **workspace** | [`workspace-bind`](#workspace-bind), [`workspace-status`](#workspace-status) |
385
387
  | **task** | [`handoff-accept`](#handoff-accept) |
386
388
  | **scope** | [`responsibility-set`](#responsibility-set), [`responsibility-status`](#responsibility-status) |
387
- | **attestation** | [`attestation-create`](#attestation-create), [`attestation-verify`](#attestation-verify), [`attestation-status`](#attestation-status), [`evidence-export`](#evidence-export), [`evidence-verify`](#evidence-verify), [`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) |
388
390
 
389
391
  <!-- END FORGELOOP GENERATED: cli-command-index -->
390
392
 
@@ -825,6 +827,27 @@ to commit with the change. See [`EVIDENCE_BUNDLES.md`](./EVIDENCE_BUNDLES.md).
825
827
 
826
828
  <!-- END FORGELOOP GENERATED: cli:evidence-export:options -->
827
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
+
828
851
  ### `evidence-verify`
829
852
 
830
853
  Verifies committed evidence bundles for a revision range without local
@@ -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
- The [Code Attestation Chain](./assets/diagrams/forgeloop-code-attestation-flow.html)
44
- is the interactive visual fallback for this sequence, with a
45
- [self-contained SVG](./assets/diagrams/forgeloop-code-attestation-flow.svg).
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