@cassiomc1/forgeloop 0.1.14 → 0.1.16

package/.forgeloop/forgeloop.gitignore

@@ -1,2 +1,3 @@
 # Local resumable task state is untrusted, target-specific data.
 work-state.json
+executions/

package/DOCS_INDEX.md

@@ -0,0 +1,60 @@
+# Documentation index
+
+ForgeLoop keeps one canonical process and separates protocol behavior from
+integration and guide context. Use this map before editing documentation.
+
+## Ownership map
+
+| Need | Canonical source | Boundary |
+| --- | --- | --- |
+| Lifecycle, gates, planning, verification, and recovery | [`LOOP_ENGINEERING.md`](./LOOP_ENGINEERING.md) | Normative process for agents and developer workflows |
+| Capability levels, discovery, and degradation | [`PROTOCOL_INTEGRATION.md`](./PROTOCOL_INTEGRATION.md) | Vendor-neutral harness contract |
+| Durable project facts | [`PROJECT_PROFILE.md`](./PROJECT_PROFILE.md) | Target-specific facts only; no prompts or secrets |
+| Guide selection | [`GUIDE_ROUTER.md`](./GUIDE_ROUTER.md) | Deterministic routing and exclusions |
+| Architecture and safety boundaries | [`LOOP_SYSTEM_DESIGN.md`](./LOOP_SYSTEM_DESIGN.md) and [`THREAT_MODEL.md`](./THREAT_MODEL.md) | Design rationale and residual risk |
+| Artifact and phase schemas | [`schemas/`](./schemas/) and [`CONTRACT_COVERAGE.md`](./CONTRACT_COVERAGE.md) | Versioned machine-readable contract |
+| CLI/package behavior | [`src/`](./src/) and [`tests/`](./tests/) | Executable implementation and regression evidence |
+| Guide content | [`ENG/`](./ENG/) | Context-specific, English-only operational guides |
+| Diagram | [`docs/forgeloop-flow.mmd`](./docs/forgeloop-flow.mmd) | Canonical Mermaid source; SVG is generated output |
+
+`README.md` is intentionally a catalog and quickstart. Do not copy the full
+process into adapters or README sections; link to the canonical source.
+
+## Lifecycle reading order
+
+1. Read [`README.md`](./README.md) for scope and quickstart.
+2. Read [`LOOP_ENGINEERING.md`](./LOOP_ENGINEERING.md) for the process gates.
+3. Read [`PROTOCOL_INTEGRATION.md`](./PROTOCOL_INTEGRATION.md) for the active
+   runtime or harness boundary.
+4. Inspect [`PROJECT_PROFILE.md`](./PROJECT_PROFILE.md) and confirm facts from
+   the repository before using them.
+5. Use [`GUIDE_ROUTER.md`](./GUIDE_ROUTER.md) to select only relevant guides.
+6. Use [`LOOP_SYSTEM_DESIGN.md`](./LOOP_SYSTEM_DESIGN.md) and schemas when a
+   change affects protocol invariants or artifact shape.
+
+## Verification and release
+
+The Node regression suite, ESLint, c8, dependency policy, package boundary,
+and Mermaid render are the local executable checks. Python validators remain
+frozen CI-only compatibility tools because they cover historical Markdown,
+loop, and secret-scanning contracts that have not been migrated to Node. Their
+scope, exact commands, and migration boundary are recorded in
+[`scripts/CI_VALIDATORS.md`](./scripts/CI_VALIDATORS.md).
+
+The package has no runtime dependencies. Development dependencies are limited
+to ESLint, c8, and Mermaid CLI and are checked by
+`npm run dependency:policy`. GitHub Actions use `npm ci`, pinned action SHAs,
+CodeQL, dependency review, and generated-release notes; npm publication still
+uses trusted OIDC publishing and is not implied by local verification.
+
+## Editing rules
+
+- Keep lifecycle prose, the Mermaid source, and the text-only README fallback
+  synchronized.
+- Keep generated `docs/assets/forgeloop-flow.svg` synchronized with the Mermaid
+  source by running `npm run docs:flow` and `npm run docs:check`. CI validates
+  the source fingerprint instead of comparing renderer-specific SVG geometry.
+- Preserve the distinction between implemented behavior, local evidence, and
+  external publication or production state.
+- Run `npm run lint`, `npm run coverage`, `npm run pack:check`, and the Python
+  CI-only validators proportionally to the change.

package/EXECUTION_STATE.md

@@ -112,3 +112,12 @@ forgeloop clear-state
 `clear-state` affects only `.forgeloop/work-state.json` and prints the exact
 relative path it removed; it never deletes the directory, manifest, or project
 files.
+
+## Execution continuity companion
+
+`.forgeloop/work-state.json` remains the canonical checkpoint and owns phase,
+`completedSteps`, `pendingSteps`, failures, blockers, verification cycles, and
+required artifact fingerprints. `.forgeloop/continuity.json` is an optional
+companion containing only granular implementation-resume context. It is bound
+to the current task, contract fingerprint, work-state fingerprint, phase, and
+repository context and is always operational context rather than evidence.

package/LOOP_ENGINEERING.md

@@ -52,6 +52,7 @@ the supported ForgeLoop lifecycle commands or canonical ForgeLoop APIs:
 - `.forgeloop/work-state.json`
 - `.forgeloop/events.ndjson`
 - `.forgeloop/execution-receipt.json`
+- `.forgeloop/executions/<executionId>.json`
 - completion recovery metadata
 - canonical check/evidence state
 - terminal-result lifecycle state
@@ -117,11 +118,32 @@ Every verification command path is classified by resolution mode:
 | `LOCAL_EXECUTABLE` | `node scripts/test.js`, `python3 -m unittest`, `./bin/check` | No | No |
 | `LOCAL_PACKAGE_BINARY` | `./node_modules/.bin/tool`, `npm test`, `pnpm test`, `yarn test` | No | No |
 | `NON_INSTALLING_RESOLUTION` | `npx --no-install tool`, `npx --no tool` | No | No |
-| `INSTALL_CAPABLE_RESOLUTION` | `npx tool`, `pnpm dlx tool`, `yarn dlx tool`, `bunx tool`, `uvx tool`, `pipx run tool` | Yes | Yes (`E_INSTALLATION_AUTHORITY_REQUIRED`) |
+| `INSTALL_CAPABLE_RESOLUTION` | `npx tool`, `npm exec tool`, `npm x tool`, `pnpm dlx tool`, `yarn dlx tool`, `bunx tool`, `uvx tool`, `pipx run tool` | Yes | Yes (`E_INSTALLATION_AUTHORITY_REQUIRED`) |
 | `EXPLICIT_INSTALLATION` | `npm install tool`, `pnpm add tool`, `pip install tool`, `cargo install tool` | Yes | Yes (`E_INSTALLATION_AUTHORITY_REQUIRED`) |
 
 **Validator-enforced rule**: Any verification command executed via an installation-capable or explicit-installation resolution mode without a valid canonical installation authority grant is rejected by `record-check`, `audit`, and `complete` with error code `E_INSTALLATION_AUTHORITY_REQUIRED`, `E_AUTHORITY_INVALID`, `E_AUTHORITY_SCOPE_MISMATCH`, or `E_AUTHORITY_UNTRUSTED_SOURCE` and cannot contribute to `VALID` completion.
 
+Recognized command dispatchers (such as `npm test`, `npm start`, `npm stop`, `npm restart`, `npm run <script>`, `npm run-script <script>`, `npm rum <script>`, `npm urn <script>`) are classified by their effective package resolution behavior across recognized lifecycle scripts before process launch. npm invocation parsing recognizes options (e.g. `--silent`, `--loglevel=error`) before the subcommand. Recognized npm-script dispatch is resolved recursively before process launch. `npm restart` uses npm's restart-specific lifecycle semantics (`prerestart`, `prestop`, `stop`, `poststop`, `prestart`, `start`, `poststart`, `postrestart` when `restart` is absent; `prerestart`, `restart`, `postrestart` when `restart` is present) rather than generic pre/main/post handling. ForgeLoop fails closed (`mayInstall: true`) when recursive npm-script resolution encounters a cycle or exceeds its maximum resolution depth (16). ForgeLoop does not resolve npm workspace selection in `run-check` for `0.1.15`. npm script executions using `--workspace`, `-w`, `--workspaces`, or `--ws` fail closed (`E_COMMAND_RESOLUTION_AMBIGUOUS`) because the effective `package.json` execution context may differ from the current ForgeLoop target. Run ForgeLoop against the selected workspace directory directly instead. If any nested lifecycle script invokes an installation-capable command (such as `npx`, `npm exec`, or `pnpm dlx`), the execution is elevated to `INSTALL_CAPABLE_RESOLUTION` and blocked before launch without authority.
+
+**npm Classification Model**: npm classification is semantic and fail-closed. Unknown npm commands are not assumed safe. The classifier specifically identifies install-capable families including: `exec`/`x`, `install` aliases, `ci` aliases, `install-test` families, `install-ci-test` families, `update` aliases, `audit fix`, and conditional `init`/`create`/`innit` invocations. Unknown or ambiguous semantics fail closed (`E_COMMAND_RESOLUTION_AMBIGUOUS`).
+
+Use `forgeloop run-check --id <id> --requirement <requirement> -- <argv>` for
+observed command evidence. ForgeLoop preserves the exact argv vector, target
+cwd, resolution classification, timestamps, exit status, and task/check
+binding in `.forgeloop/executions/<executionId>.json` before recording the
+check. Resolution is classified before process launch; install-capable
+resolution is rejected without a valid host-attested authority, while
+`npx --no-install` remains a non-installing path and may fail honestly when a
+tool is absent. `run-check` launches the supplied argv without a shell.
+
+`forgeloop record-check` is serialization-only. Its `--command` value is
+metadata and is never executed. A `kind: command`, `evidenceKind: OBSERVED`
+check must carry `provenance: FORGELOOP_EXECUTED` and a valid `executionRef`;
+manual or actor-reported observations must use an explicit non-command kind or
+provenance and must not be upgraded to command execution evidence. Completion,
+audit, protocol validation, and bundles revalidate the referenced artifact and
+its task, check, requirement, cycle, cwd, status, and exit-code binding.
+
 Authority cannot be self-issued by the actor consuming it. Boolean fields inside verification evidence (such as `installationAuthorized: true`) are not sufficient proof of installation authority. Installation authority must be established via a canonical authority grant supplied by a host/operator trust boundary and referenced via `installationAuthorityRef`.
 
 The runtime authority context has two modes:
@@ -509,7 +531,7 @@ prepare-completion
     ↓
 run applicable project checks
     ↓
-record observed results with record-check
+run commands with run-check; record manual observations with record-check
     ↓ forgeloop next
 advance --to REVIEWING
     ↓ forgeloop next
@@ -524,10 +546,11 @@ subsequent `record-check` operations; completion remains invalid until required
 observed evidence, review state, chronology, and validator requirements are
 satisfied.
 
-The host agent runs applicable checks after the receipt exists, records their
-observed results with `record-check`, and queries `forgeloop next` before each
-subsequent lifecycle action. `record-check` records results already observed by
-the agent; it never executes the supplied command text.
+The host agent runs applicable checks after the receipt exists, uses `run-check`
+for commands, and uses `record-check` for manual or non-command observations.
+`run-check` records exact command provenance; `record-check` records supplied
+metadata only and never executes its `--command` value. Query `forgeloop next`
+before each subsequent lifecycle action.
 
 Continue until the terminal outcome is either validator-backed `COMPLETE` or
 an explicitly reported `BLOCKED` / `PARTIALLY VERIFIED` result with exact
@@ -1140,3 +1163,18 @@ Publication:
 Never claim that a test, build, platform, device, or integration passed without
 a compatible check. The final response must distinguish local implementation
 from external publication.
+
+## Cross-harness execution continuity
+
+A change of model, provider, IDE, process, terminal, or context window does not
+create a new task when a valid resumable ForgeLoop task already exists.
+`work-state.json` remains the sole owner of lifecycle progress. An optional
+`.forgeloop/continuity.json` may record bounded granular implementation context
+such as current focus, remaining implementation work, known issues, and paths
+to inspect first.
+
+`CONTINUITY_CONTEXT_IS_NOT_EVIDENCE`: continuity may guide inspection but can
+never satisfy verification coverage, publication, production readiness, or
+completion. `CONTINUITY_CANNOT_GRANT_AUTHORITY`: continuity cannot authorize an
+installation or external action. The receiving harness MUST reconcile
+continuity against the current work state and checkout before acting on it.

package/LOOP_SYSTEM_DESIGN.md

@@ -399,3 +399,11 @@ update practice.
 - Structural, Markdown, link, and secret checks pass locally and in CI.
 - Portable-copy instructions always include third-party notices.
 - The package does not alter destination commands, dependencies, or behavior without need and applicable authority.
+
+## Cross-harness continuity boundary
+
+Execution continuity is intentionally a companion artifact, not a second state
+machine and not a general memory subsystem. Work state owns lifecycle truth;
+the checkout owns implementation truth; checks/executions own verification
+truth; completion owns certification. Continuity only narrows what a receiving
+executor should inspect and continue.

package/PROTOCOL_INTEGRATION.md

@@ -128,6 +128,7 @@ The following protocol artifacts are strictly owned by ForgeLoop:
 - `.forgeloop/work-state.json`
 - `.forgeloop/events.ndjson`
 - `.forgeloop/execution-receipt.json`
+- `.forgeloop/executions/<executionId>.json`
 - Canonical check, evidence, and terminal-result state
 
 If the required CLI or API capability cannot be resolved:
@@ -140,6 +141,38 @@ If the required CLI or API capability cannot be resolved:
 
 Report the corresponding ForgeLoop dimension as `NOT_VERIFIED` / `E_FORGELOOP_CLI_UNAVAILABLE`.
 
+## Trusted command provenance
+
+Command verification has two explicit paths:
+
+- `forgeloop run-check --id <id> --requirement <requirement> -- <argv>` owns
+  execution. It classifies the exact argv before launch, uses a non-shell
+  process boundary, records the target cwd, resolution mode, timestamps,
+  exit status, and task/check binding in
+  `.forgeloop/executions/<executionId>.json`, then records an `OBSERVED` check
+  with `provenance: FORGELOOP_EXECUTED`.
+- `forgeloop record-check` owns serialization only. `--command` is metadata and
+  is never launched. A `kind: command` check with `evidenceKind: OBSERVED`
+  requires both `executionRef` and `FORGELOOP_EXECUTED`; manual or actor-reported
+  observations use their explicit non-command/provenance values and remain
+  distinguishable from process execution.
+
+`run-check` rejects install-capable resolution before process launch unless the
+host supplies a valid trusted authority context. `npm exec` and `npm x` are
+installation-capable resolution paths. Recognized command dispatchers (such as
+`npm test`, `npm restart`, `npm run`, `npm rum`, `npm urn`) are resolved
+recursively across recognized lifecycle scripts before launch with cycle
+detection, leading option normalization, and restart-specific lifecycle fallback.
+npm workspace script executions (`--workspace`, `-w`, `--workspaces`, `--ws`) fail
+closed before launch with `E_COMMAND_RESOLUTION_AMBIGUOUS` because the effective
+`package.json` context cannot be proven from the root target. Unknown npm command semantics are rejected before execution rather than downgraded to local execution. ForgeLoop uses an explicit non-installing allowlist instead of assuming that unrecognized npm commands are safe. `npx --no-install` is
+an allowed non-installing resolution and can return a normal failed result when
+the requested tool is unavailable. Completion, audit, `validate-protocol`, and task
+bundles revalidate execution references rather than trusting duplicated check
+metadata. Invalid or missing references return `E_EXECUTION_REF_INVALID`; an
+observed command without ForgeLoop provenance returns
+`E_COMMAND_PROVENANCE_UNATTESTED`.
+
 ## Missing tool capability
 
 A missing tool is a capability gap, not installation authority.
@@ -268,3 +301,11 @@ External planning, interview, or review workflows (such as `/grill-me`, `/plan`,
 review gates) may assist in clarifying requirements, but they must not silently
 redefine ForgeLoop `NON_BLOCKING` decisions as `BLOCKING` in autonomous mode.
 Consult `LOOP_ENGINEERING.md#external-workflow-interaction` for the complete boundary.
+
+## Harness and session continuity
+
+Harness identity is not task identity. Session identity is not task identity.
+A compatible environment reopening a resumable task SHOULD inspect the current
+work state, reconcile optional execution continuity, inspect the checkout, and
+continue the existing lifecycle instead of replacing the contract merely
+because the executor changed.

package/QUALITY_SCORECARD.md

@@ -23,6 +23,8 @@ policy are all present.
 | Autonomous-mode precedence — structural | Explicit `autonomousMode=true` boundary, explicit interactive opt-in, preservation of `NON_BLOCKING`, and no silent workflow-induced mode switch. |
 | Pre-contract autonomy — cross-agent live robustness | Independent live-agent behavior across fresh package installs, exact blind prompts, one-process/no-subagent topology, and separate evidence for non-blocking continuation versus blocking clarification. Structural coverage does not imply live cross-agent robustness. |
 | Resume/checkpoint | Atomic local state, contract/HEAD/artifact freshness, age warning, schema/secret validation, status, safe validation, and bounded clearing without persisting derived freshness fields. |
+| Cross-harness execution continuity — structural | Optional bounded continuity artifact, task/contract/work-state binding, deterministic reconciliation, current-checkout precedence, non-evidence/non-authority semantics, next/status/inspect integration, bundle portability, and cross-process regression coverage. |
+| Cross-harness live continuity | A fresh Harness B resumes an interrupted Harness A task with no manual user summary and reaches validator-backed completion; structural coverage alone does not prove this dimension. |
 | Protocol activation resumability | `PREFLIGHT_READY` durably creates or reconciles `work-state.json`, preserves blocked history, and exposes a dedicated repair code when the checkpoint is missing. |
 | Artifact ↔ lifecycle reconciliation | Contract, route, gates, state, preflight, activation events, fingerprints, and append-only hash chronology agree at READY; audit and validate-protocol detect divergence. |
 | Planned vs present profile truth | `PROJECT_PROFILE.md` distinguishes planned template fields from observed target facts, with hidden-kit bootstrap and legacy migration checks. |