@cassiomc1/forgeloop 1.0.0 → 1.1.0

package/docs/CROSS_HARNESS_CONTINUITY.md

@@ -0,0 +1,198 @@
+# Cross-Harness Execution Continuity
+
+This guide explains how to resume and transfer ForgeLoop tasks across different AI harnesses, IDEs, terminals, and agent runtimes without losing lifecycle state or re-explaining context.
+
+---
+
+## 1. Core Invariants
+
+1. **Harness identity $\neq$ Task identity**
+2. **Session identity $\neq$ Task identity**
+
+Switching between execution environments (for example Codex $\rightarrow$ Claude Code, Claude Code $\rightarrow$ Cursor, or terminal A $\rightarrow$ terminal B) **does not create a new ForgeLoop task**.
+
+```text
+┌──────────────┐       ┌──────────────┐       ┌──────────────┐
+│  Harness A   │       │  Harness B   │       │  Developer   │
+│ (Claude Code)│       │   (Cursor)   │       │  (Terminal)  │
+└──────┬───────┘       └──────┬───────┘       └──────┬───────┘
+       │                      │                      │
+       └───────────────┬──────┴──────────────────────┘
+                       ▼
+         ┌───────────────────────────────────────────────┐
+         │              ForgeLoop Task                   │
+         │ .forgeloop/task-state/<taskKey>/work-state.json│
+         │ .forgeloop/task-state/<taskKey>/continuity.json│
+         │            Hash-chained Event Log             │
+         └───────────────────────────────────────────────┘
+```
+
+When a new harness starts in a repository where an active task exists, it must discover the existing task, reconcile continuity when present, inspect the checkout, and proceed from the recorded state rather than overwriting the contract.
+
+Key continuity invariants:
+
+- **Continuity is optional**: A missing `continuity.json` file does not invalidate an otherwise resumable task.
+- **Continuity is non-authoritative**: It provides operational resume hints, not lifecycle truth.
+- **Continuity is not evidence**: It cannot satisfy contract verification requirements.
+- **Task identity survives harness changes**: Work state remains the single source of lifecycle truth.
+- **Stale continuity cannot authorize transitions**: Forward lifecycle progression requires valid work-state checkpoints.
+
+---
+
+## 2. Source-of-Truth Hierarchy
+
+| Layer | File / Source | Responsibility | Trust Level |
+| --- | --- | --- | --- |
+| **Task Descriptor** | `.forgeloop/task-state/<taskKey>/task.json` | Task ID, write claims, and task registration | Descriptor authority |
+| **Lifecycle Checkpoint** | `.forgeloop/task-state/<taskKey>/work-state.json` | Current phase, cycle, active guides, preflight binding | Canonical lifecycle truth |
+| **Operational Continuity** | `.forgeloop/task-state/<taskKey>/continuity.json` | Active focus, remaining items, known issues, inspect-first paths | Operational context only (non-evidence) |
+| **Implementation Truth** | Git checkout / filesystem | Actual source code and files | Ground truth for changes |
+| **Task Intent** | `.forgeloop/task-state/<taskKey>/contract.json` | Objectives, constraints, deliverables, verification requirements | Contract authority |
+| **Execution Guidance** | `.forgeloop/task-state/<taskKey>/routing-result.json` | Deterministically selected engineering guides | Guidance |
+| **Verification Provenance** | `.forgeloop/task-state/<taskKey>/executions/*.json` | Attested process execution records | Verification truth |
+| **Next Action** | `forgeloop next` | Deterministic computation of the valid next command | Control authority |
+
+> [!IMPORTANT]
+> `continuity.json` provides operational resume context to make transitions smooth. It is **never verification evidence** and **never grants authority**.
+
+---
+
+## 3. Cross-Harness Workflow
+
+```text
+HARNESS A (Finishing / Pausing)
+   │
+   ├── Commits or edits code in checkout
+   ├── Updates work-state via ForgeLoop CLI
+   └── Records operational handoff: `forgeloop record-continuity --task <id>`
+          │
+          ▼
+      Shared Checkout (.forgeloop/task-state/<taskKey>/)
+          │
+          ▼
+HARNESS B (Starting / Taking Over)
+   │
+   ├── 1. Discovers tasks: `forgeloop task-list --json`
+   ├── 2. Inspects state: `forgeloop status --task <id> --json`
+   ├── 3. Reads continuity: `forgeloop continuity --task <id> --json`
+   ├── 4. Reconciles continuity: `forgeloop reconcile-continuity --task <id> --json`
+   ├── 5. Inspects modified files: `forgeloop inspect --task <id> --json`
+   └── 6. Asks for next action: `forgeloop next --task <id> --json`
+          │
+          ▼
+     Continues execution without duplicating planning
+```
+
+---
+
+## 4. Harness A — Recording Handoff Context
+
+Before pausing, exiting, or transferring control, Harness A records its work in progress:
+
+```bash
+forgeloop record-continuity \
+  --task auth-feature \
+  --focus-id auth-refresh \
+  --focus-summary "Implement refresh-token rotation" \
+  --remaining "tests:Add refresh token expiration tests" \
+  --remaining "docs:Document token rotation in API guide" \
+  --known-issue "rotation:Old token revocation requires redis TTL sync" \
+  --changed-area src/auth \
+  --changed-area tests/auth \
+  --inspect-first src/auth/refresh-token.js \
+  --resume-note "Access-token validation is done; continue with refresh-token rotation in src/auth/refresh-token.js."
+```
+
+### Options Breakdown
+
+- `--task <id>`: Target task identifier (or set `FORGELOOP_TASK`).
+- `--focus-id <id>`: Short identifier for the active sub-task.
+- `--focus-summary <text>`: Concise summary of what is currently being worked on.
+- `--remaining <id:summary>`: Remaining work items (repeatable).
+- `--known-issue <id:summary>`: Discovered blockers or edge cases to address (repeatable).
+- `--changed-area <path>`: Directories or file trees modified during this session (repeatable).
+- `--inspect-first <path>`: Recommended starting file for the next harness to read first.
+- `--resume-note <text>`: Operational note explaining immediate context to the next actor.
+
+---
+
+## 5. Harness B — Resuming the Task
+
+When Harness B starts in the repository:
+
+### Step 1: Select and Check Task Status
+
+If multiple tasks are active, select the target task explicitly using `--task` or `FORGELOOP_TASK`:
+
+```bash
+export FORGELOOP_TASK="auth-feature"
+
+forgeloop status --json
+```
+
+Or with explicit flag:
+
+```bash
+forgeloop status --task auth-feature --json
+```
+
+Verify that the task exists and observe the current lifecycle phase (e.g. `EXECUTING` or `VERIFYING`). If multiple tasks exist and no selector is provided, ForgeLoop returns `E_TASK_AMBIGUOUS`.
+
+### Step 2: Read Continuity Context
+
+```bash
+forgeloop continuity --task auth-feature --json
+```
+
+Examine the handoff note, focus ID, remaining items, and inspect-first recommendations.
+
+### Step 3: Reconcile Continuity with Work State
+
+```bash
+forgeloop reconcile-continuity --task auth-feature --json
+```
+
+Reconciliation validates that `continuity.json` matches the current `work-state.json` fingerprint and was not corrupted by external changes.
+
+### Step 4: Inspect Checkout Changes
+
+```bash
+forgeloop inspect --task auth-feature --json
+```
+
+Review modified and newly created files against the contract deliverables and task claims.
+
+### Step 5: Query Next Lifecycle Action
+
+```bash
+forgeloop next --task auth-feature --json
+```
+
+Follow the deterministic action returned by ForgeLoop (e.g. `CONTINUE_IMPLEMENTATION`, `ENTER_VERIFYING`, or `RECORD_CHECK`).
+
+---
+
+## 6. Stale, Inconsistent, or Missing Handoffs
+
+ForgeLoop handles edge cases deterministically:
+
+| Scenario | Condition | Protocol Behavior | Recommended Action |
+| --- | --- | --- | --- |
+| **Fresh Handoff** | Matching state fingerprint & clean checkout | `VALID` | Continue directly via `forgeloop next` |
+| **Checkout Drift** | State fresh, but files modified out-of-band | `CONTINUITY_RECONCILED` | Run `reconcile-continuity`, inspect diff, continue |
+| **Stale Continuity** | Continuity references older work-state | `STALE_CONTINUITY` | Reconcile or clear continuity (`clear-continuity`), rely on `work-state.json` |
+| **Missing Continuity** | `work-state.json` exists, `continuity.json` absent | `VALID_STATE` | Normal resume from `work-state.json` (continuity is optional) |
+| **Multiple Active Tasks** | No `--task` or `FORGELOOP_TASK` supplied | `E_TASK_AMBIGUOUS` | List tasks with `task-list` and supply `--task` |
+| **Different Task ID** | Contract / state ID mismatch | `TASK_MISMATCH` | Do not merge contexts; complete or clear previous state |
+| **Malformed State** | Corrupted JSON or invalid hash chain | `INVALID` | Fails closed; inspect errors via `forgeloop doctor --json` |
+
+---
+
+## 7. Discovery Adapter Integration
+
+Every discovery adapter (`AGENTS.md`, `CLAUDE.md`, `.cursor/rules/project-loop.mdc`, `.github/copilot-instructions.md`) reinforces this invariant:
+
+> Before creating or activating new lifecycle state:
+> Discover task namespaces with ForgeLoop; if exactly one active task is healthy it may be selected implicitly; if multiple active tasks exist, select with `--task` or `FORGELOOP_TASK`.
+> Inspect the existing task, reconcile continuity when present, inspect the checkout, and run `forgeloop next`.
+> A change of harness, model, provider, IDE, process, terminal, or session does not create a new task.

package/docs/DOCUMENTATION_GUIDE.md

@@ -0,0 +1,161 @@
+# ForgeLoop Documentation Guide
+
+This guide explains how to maintain, write, and safely modify ForgeLoop documentation.
+
+---
+
+## 1. Canonical Ownership Model
+
+ForgeLoop strictly separates normative protocol definitions from operational documentation to avoid contradictory rules.
+
+| Area | Location | Responsibility | Rule |
+| --- | --- | --- | --- |
+| **Normative Protocol** | Root (`LOOP_ENGINEERING.md`, `PROTOCOL_INTEGRATION.md`, `LOOP_SYSTEM_DESIGN.md`, `THREAT_MODEL.md`, `EXECUTION_STATE.md`) | Canonical authority for protocol rules, schemas, state transitions, and security | Never duplicate normative rules in sub-documents; link back to root files. |
+| **Operational & Reference** | `docs/` (`GETTING_STARTED.md`, `CROSS_HARNESS_CONTINUITY.md`, `CLI_REFERENCE.md`, `ARTIFACT_REFERENCE.md`, `TROUBLESHOOTING.md`, `RECIPES.md`) | Tutorials, command reference, handoff workflows, and troubleshooting | Explains how to operate the system. Links to normative sources for formal specifications. |
+| **Domain Engineering** | `ENG/` (`clean-code-eng.md`, `design-code-eng.md`, `test-code-eng.md`, etc.) | Domain-specific implementation and quality standards | Frontmatter must adhere to `validate_loop_system.py` standards. |
+| **Consumer Documentation Quality** | [`ENG/documentation-quality-eng.md`](../ENG/documentation-quality-eng.md) | Quality standards for documentation work in projects using ForgeLoop | Governs client/consumer project documentation tasks via guide routing. |
+| **Visual Architecture** | `docs/forgeloop-flow.mmd` | Canonical architecture diagram source | Rendered SVG committed at `docs/assets/forgeloop-flow.svg`. |
+| **Documentation Index** | `DOCS_INDEX.md` | Single repository index and ownership map | Updated whenever documentation structure changes. |
+
+---
+
+## 2. Documentation Source-of-Truth Rules
+
+When updating documentation, always derive content from its authoritative source:
+
+```text
+CLI syntax truth        -> CLI registry / parser (src/cli.js, src/core/cli-command-definitions.js, src/core/cli-metadata.js)
+Artifact shape truth    -> JSON schemas (schemas/*.schema.json, src/core/artifact-registry.js)
+Lifecycle truth         -> protocol / state machine (src/core/protocol.js)
+Reason-code truth       -> exported protocol constants (src/core/error-codes.js, src/core/protocol.js)
+Guide registry truth    -> canonical guide registry (src/config/guides.json)
+Package contents truth  -> package.json + package tests (tests/package.test.js)
+Documentation routing   -> DOCS_INDEX.md
+```
+
+Operational documentation must explain canonical behavior, not redefine it.
+
+---
+
+## 3. Generated Documentation Provenance & Pipeline
+
+ForgeLoop mechanically enforces documentation freshness using deterministic generator targets. If public facts change and documentation regions are not refreshed, CI fails.
+
+```text
+runtime facts
+    ↓
+canonical registries / schemas
+    ↓
+deterministic generators (scripts/generate_documentation_reference.mjs)
+    ↓
+generated Markdown regions (<!-- BEGIN FORGELOOP GENERATED: ... -->)
+    ↓
+semantic conformance checks (scripts/validate_documentation_conformance.mjs)
+    ↓
+cross-platform CI (.github/workflows/docs-quality.yml)
+```
+
+### Provenance Mapping Table
+
+| Fact Category | Canonical Machine Source | Generated Target File | Generated Region Marker |
+| --- | --- | --- | --- |
+| **Artifact Inventory** | `ARTIFACT_REGISTRY` (`src/core/artifact-registry.js`) | `docs/ARTIFACT_REFERENCE.md` | `<!-- BEGIN FORGELOOP GENERATED: artifact-registry -->` |
+| **Artifact Fields** (12 schemas) | `schemas/*.schema.json` | `docs/ARTIFACT_REFERENCE.md` | `<!-- BEGIN FORGELOOP GENERATED: schema:<name> -->` |
+| **CLI Command Index** | `CLI_COMMAND_DEFINITIONS` (`src/core/cli-command-definitions.js`) | `docs/CLI_REFERENCE.md` | `<!-- BEGIN FORGELOOP GENERATED: cli-command-index -->` |
+| **CLI Common Options** | `CLI_COMMAND_DEFINITIONS` (`src/core/cli-command-definitions.js`) | `docs/CLI_REFERENCE.md` | `<!-- BEGIN FORGELOOP GENERATED: cli-common-options -->` |
+| **CLI Command Options** (27 commands) | `CLI_COMMAND_DEFINITIONS` (`src/core/cli-command-definitions.js`) | `docs/CLI_REFERENCE.md` | `<!-- BEGIN FORGELOOP GENERATED: cli:<command>:options -->` |
+| **Public Error Codes** | `PUBLIC_ERROR_CODES` (`src/core/error-codes.js`) | `docs/TROUBLESHOOTING.md` | `<!-- BEGIN FORGELOOP GENERATED: public-error-codes -->` |
+| **Architecture Flow** | `docs/forgeloop-flow.mmd` | `docs/assets/forgeloop-flow.svg` | Verified via embedded SHA-256 fingerprint |
+
+### Maintenance Workflow
+
+Whenever CLI definitions, schemas, or error codes change:
+
+```bash
+# 1. Regenerate all deterministic documentation regions
+npm run docs:generate
+
+# 2. Run the test suite (includes parser parity and unit tests)
+npm test
+
+# 3. Verify freshness, diagram fingerprints, and semantic conformance
+npm run docs:check
+```
+
+---
+
+## 4. Documentation Conformance Matrix
+
+| Documentation Area | Canonical Machine Source | Conformance Validator |
+| --- | --- | --- |
+| **CLI commands & flags** | `CLI_COMMAND_METADATA` (`src/core/cli-metadata.js`) & `src/cli.js` | `scripts/validate_documentation_conformance.mjs` |
+| **Artifact paths** | `ARTIFACT_REGISTRY` & `task-paths.js` | `scripts/validate_documentation_conformance.mjs` |
+| **Artifact fields & types** | `schemas/*.schema.json` | `scripts/validate_documentation_conformance.mjs` |
+| **Enums & consts** | `schemas/*.schema.json` | `scripts/validate_documentation_conformance.mjs` |
+| **Lifecycle phases** | `WORK_PHASES` (`src/core/protocol.js`) | `scripts/validate_documentation_conformance.mjs` |
+| **Stable error codes** | `PUBLIC_ERROR_CODES` (`src/core/error-codes.js`) | `scripts/validate_documentation_conformance.mjs` |
+| **Discovery resume rules** | `DISCOVERY_SURFACES` & `nativeShim` | `scripts/validate_documentation_conformance.mjs` |
+| **Operational path freshness** | `OPERATIONAL_DOCUMENTS` & `task-paths.js` | `scripts/validate_documentation_conformance.mjs` |
+| **Package-shipped docs** | `package.json` (`files`) | `tests/package.test.js` |
+| **Architecture diagram** | `docs/forgeloop-flow.mmd` | `scripts/check-generated-diagram.mjs` |
+
+---
+
+## 5. Normative Language Conventions
+
+When writing documentation, use precise terms:
+
+- **MUST / MUST NOT**: Strict protocol requirements enforced by schemas or CLI algorithms.
+- **SHOULD / SHOULD NOT**: Strong interoperability recommendations for harnesses.
+- **MAY**: Optional behaviors or flags.
+- **Illustrative**: Non-normative examples provided for human understanding.
+
+Avoid ambiguous phrases like *"should generally"* or *"usually"* for behaviors that are strictly enforced by the validator.
+
+### Multi-Task Layout Rules
+
+- Canonical task-scoped paths are defined in `src/core/task-paths.js` under `.forgeloop/task-state/<taskKey>/`.
+- Operational guides (`README.md`, `GETTING_STARTED.md`, `RECIPES.md`, `CROSS_HARNESS_CONTINUITY.md`, `TROUBLESHOOTING.md`) must document namespaced paths by default.
+- Legacy ForgeLoop 1.0 singleton paths (e.g. `.forgeloop/current-contract.json`) are permitted **only** inside explicit legacy migration regions:
+
+  ```markdown
+  <!-- BEGIN FORGELOOP LEGACY LAYOUT EXAMPLE -->
+  ...
+  <!-- END FORGELOOP LEGACY LAYOUT EXAMPLE -->
+  ```
+
+- `scripts/validate_documentation_conformance.mjs` mechanically rejects any singleton task path outside these markers.
+
+---
+
+## 6. Linking Conventions
+
+- **Relative Links Only**: Always use relative markdown links for repository files (e.g. `[`LOOP_ENGINEERING.md`](../LOOP_ENGINEERING.md)`).
+- **Valid Targets**: Every relative link must point to an existing file and is validated by `python3 scripts/validate_markdown.py`.
+- **Anchors**: Anchor links should match standard GitHub heading slugs.
+
+---
+
+## 7. Mermaid Diagrams and SVG Generation
+
+1. **Source is Canonical**: Diagram source files live in `.mmd` files (e.g. `docs/forgeloop-flow.mmd`). Never modify SVG files directly.
+2. **Local Committed SVGs**: Generated SVGs are committed locally in `docs/assets/`. Never hotlink externally rendered diagram images.
+3. **Self-Contained & GitHub-Safe**: Generated SVGs must not import external stylesheets (e.g. `@import url(...)`), must not embed `<script>` or `<foreignObject>`, and must be visible via standard Markdown image syntax (`![alt](./path.svg)`).
+4. **Fingerprint Verification**: Generated SVGs embed a `data-forgeloop-source-sha256` attribute verified by `npm run docs:check`.
+
+---
+
+## 8. Documentation Change Checklist for Pull Requests
+
+For documentation-impacting changes, verify each item before merging:
+
+- [ ] Did CLI behavior change?
+- [ ] Did any schema field change?
+- [ ] Did any enum or status change?
+- [ ] Did any lifecycle transition change?
+- [ ] Did any artifact mutation rule change?
+- [ ] Did any stable reason/error code change?
+- [ ] Did cross-harness resume behavior change?
+- [ ] Did package-shipped documentation change?
+- [ ] Were generated reference docs updated (`npm run docs:generate`)?
+- [ ] Did documentation conformance CI pass (`npm run docs:check`)?