@cassiomc1/forgeloop 0.1.15 → 1.0.0

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

@@ -1163,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

@@ -301,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. |