@cassiomc1/forgeloop 2.2.0 → 2.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CONTRIBUTING.md +22 -2
- package/DOCS_INDEX.md +4 -13
- package/ENG/sec-code-eng.md +1 -1
- package/ENG/test-code-eng.md +32 -1
- package/LOOP_SYSTEM_DESIGN.md +2 -3
- package/QUALITY_SCORECARD.md +0 -1
- package/README.md +10 -42
- package/THIRD_PARTY_NOTICES.md +0 -15
- package/completions/_forgeloop +3 -2
- package/completions/forgeloop.bash +4 -2
- package/completions/forgeloop.fish +12 -1
- package/docs/AGENT_PROTOCOL_SUMMARY.md +3 -2
- package/docs/ARTIFACT_REFERENCE.md +1 -0
- package/docs/CLI_REFERENCE.md +24 -1
- package/docs/CODE_ATTESTATION.md +9 -7
- package/docs/DOCUMENTATION_GUIDE.md +10 -28
- package/docs/PACKAGE_CONTENTS.md +0 -3
- package/docs/RELEASE_CHECKLIST.md +52 -19
- package/docs/REVISION_PROVIDERS.md +3 -6
- package/docs/TROUBLESHOOTING.md +3 -0
- package/docs/documentation-manifest.json +0 -13
- package/package.json +2 -6
- package/schemas/config.schema.json +1 -0
- package/scripts/CI_VALIDATORS.md +2 -2
- package/src/cli.js +5 -0
- package/src/commands/attestation-create.js +21 -1
- package/src/commands/complete.js +3 -0
- package/src/commands/evidence-publish.js +22 -0
- package/src/commands/sync-pull.js +72 -7
- package/src/commands/sync-push.js +4 -1
- package/src/core/audit.js +7 -0
- package/src/core/cli-command-definitions.js +19 -1
- package/src/core/command-executors.js +19 -5
- package/src/core/config.js +44 -37
- package/src/core/error-codes.js +18 -0
- package/src/core/evidence/auto-export.js +61 -0
- package/src/core/evidence/bundle-format.js +4 -2
- package/src/core/evidence/export.js +5 -0
- package/src/core/evidence/publish.js +187 -0
- package/src/core/integration-invocation-policy.js +1 -0
- package/src/core/sync/merge.js +135 -0
- package/docs/assets/diagrams/forgeloop-code-attestation-flow.html +0 -13852
- package/docs/assets/diagrams/forgeloop-code-attestation-flow.receipt.json +0 -37
- package/docs/assets/diagrams/forgeloop-code-attestation-flow.svg +0 -5055
- package/docs/assets/diagrams/forgeloop-engineering-flow.html +0 -13837
- package/docs/assets/diagrams/forgeloop-engineering-flow.receipt.json +0 -37
- package/docs/assets/diagrams/forgeloop-engineering-flow.svg +0 -5011
- package/docs/assets/diagrams/forgeloop-verification-trust-flow.html +0 -13795
- package/docs/assets/diagrams/forgeloop-verification-trust-flow.receipt.json +0 -37
- package/docs/assets/diagrams/forgeloop-verification-trust-flow.svg +0 -4997
- package/docs/diagrams/README.md +0 -103
- package/docs/diagrams/forgeloop-code-attestation-flow.workflow.json +0 -451
- package/docs/diagrams/forgeloop-engineering-flow.workflow.json +0 -459
- package/docs/diagrams/forgeloop-verification-trust-flow.workflow.json +0 -398
- package/docs/diagrams/manifest.json +0 -84
- package/docs/diagrams/reviews/forgeloop-code-attestation-flow.review.json +0 -20
- package/docs/diagrams/reviews/forgeloop-engineering-flow.review.json +0 -20
- package/docs/diagrams/reviews/forgeloop-verification-trust-flow.review.json +0 -20
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`, `
|
|
20
|
-
|
|
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
|
|
184
|
-
|
|
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
|
|
201
|
-
|
|
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
|
package/ENG/sec-code-eng.md
CHANGED
|
@@ -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://
|
|
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
|
package/ENG/test-code-eng.md
CHANGED
|
@@ -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-
|
|
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.
|
package/LOOP_SYSTEM_DESIGN.md
CHANGED
|
@@ -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
|
-
(
|
|
391
|
-
|
|
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
|
|
package/QUALITY_SCORECARD.md
CHANGED
|
@@ -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.
|
|
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
|
-
<
|
|
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
|
|
442
|
-
|
|
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
|
-
[
|
|
461
|
-
|
|
462
|
-
|
|
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.
|
|
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
|
-
|
|
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
|
package/THIRD_PARTY_NOTICES.md
CHANGED
|
@@ -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).
|
package/completions/_forgeloop
CHANGED
|
@@ -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.
|
|
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,
|
|
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)*
|
package/docs/CLI_REFERENCE.md
CHANGED
|
@@ -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
|
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
|
|