@cassiomc1/forgeloop 1.2.3 → 1.3.0

package/AGENT_COMPATIBILITY.md

@@ -1,5 +1,9 @@
 # Deprecated filename
 
+> Deprecated since package `1.2.4`; retained as a repository compatibility stub.
+> It is not part of the public integration surface and is scheduled for removal
+> in the next compatibility-breaking release.
+
 ForgeLoop is vendor-neutral and does not use a supported-agent allowlist.
 
 The canonical integration contract is:

package/DOCS_INDEX.md

@@ -1,5 +1,12 @@
 # Documentation index
 
+The machine-readable inventory is
+[`docs/documentation-manifest.json`](./docs/documentation-manifest.json). It
+classifies every package-shipped document, names canonical concept owners, and
+records generated/deprecated-document metadata. Normative requirements and
+their implementation/test mappings are in
+[`docs/protocol-requirements.json`](./docs/protocol-requirements.json).
+
 ForgeLoop keeps one canonical process and separates protocol behavior from
 integration and guide context. Use this map before editing documentation.
 

package/EXECUTION_STATE.md

@@ -51,6 +51,14 @@ and rename it into place. The host filesystem's rename guarantee is the
 atomicity boundary; no database or remote state is involved. A truncated,
 malformed, or secret-bearing file is invalid and is never resumed silently.
 
+Lifecycle mutations that change more than one artifact use a task transaction
+under `.forgeloop/.txn/<transactionId>/`. The transaction records every staged
+replacement and append. Ledger appends validate a bounded tail checkpoint and
+stage only the new NDJSON suffix; if publication is interrupted, recovery
+truncates that suffix to its recorded pre-append size. A stale checkpoint never
+authorizes a new sequence number: ForgeLoop rebuilds it from the ledger before
+continuing.
+
 Before resuming, compare:
 
 - the task contract fingerprint;

package/LOOP_ENGINEERING.md

@@ -1275,7 +1275,7 @@ 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
+installation or external action. <a id="FL-CONT-001"></a> **FL-CONT-001 — A receiving harness MUST reconcile**
 continuity against the current work state and checkout before acting on it.
 
 ## Multi-task concurrent project state

package/LOOP_SYSTEM_DESIGN.md

@@ -218,6 +218,16 @@ The threat model records path, symlink, artifact, secret, stale-state,
 publication, schema, dependency, and resource-limit boundaries with their
 mitigations, residual limitations, and executable evidence.
 
+Persistent task mutations use a task lease lock and a recoverable transaction
+journal. State writes carry a monotonically increasing revision, while event
+appends are serialized and hash chained. The ledger keeps a validated tail
+checkpoint (`seq` and last hash), so a normal append stages and publishes only
+its new NDJSON suffix; a mismatched tail forces a full checkpoint rebuild. A
+crash during a multi-file publish leaves a journal that `doctor --fix` can roll
+back deterministically — including truncating an interrupted ledger suffix to
+its recorded pre-append size. It never permits a partial artifact set to be
+presented as a completed protocol state.
+
 ### `ENG/*.md`
 
 Nine canonical guides cover:

package/PROTOCOL_INTEGRATION.md

@@ -108,6 +108,36 @@ workflows that do not automatically discover one of the default files:
 
 A developer or custom automation can execute ForgeLoop identically to an AI agent.
 
+### Compatibility handshake
+
+Before a harness creates or resumes task state, it can read the complete
+machine-readable compatibility boundary:
+
+```bash
+forgeloop protocol-info --json
+```
+
+When a compatibility change requires persisted state conversion, inspect it
+before writing anything:
+
+```bash
+forgeloop migrate-protocol --to 1 --dry-run --json
+```
+
+`migrate-protocol` accepts only versions with an explicit migration in the
+installed release. Unsupported targets fail without rewriting state. The
+current protocol's only supported conversion is the receipt-backed legacy
+singleton-layout migration; a future protocol version must add its own
+validated migration before it can become an accepted `--to` value.
+
+The response separates package and protocol identity. `packageVersion` is the
+installed CLI version; `readsProtocol` and `writesProtocol` enumerate protocol
+versions supported by this CLI; `readsSchemaVersions` and
+`writesSchemaVersions` map every public artifact schema to its supported
+versions. A harness must not infer compatibility from the package version
+alone, and it must fail closed when its required protocol or schema version is
+absent from the relevant list.
+
 ## CLI resolution policy
 
 Lifecycle-owned protocol state must be managed through the project-local ForgeLoop CLI:

package/README.md

@@ -4,7 +4,13 @@
   <img src="./docs/assets/eng_readme_forgeloop.png" alt="ForgeLoop — Loop Engineering for AI Agents" width="100%">
 </p>
 
+[![CodeQL](https://github.com/cassiomc1/forgeloop/actions/workflows/codeql.yml/badge.svg?branch=main)](https://github.com/cassiomc1/forgeloop/actions/workflows/codeql.yml)
+[![Dependency review](https://github.com/cassiomc1/forgeloop/actions/workflows/dependency-review.yml/badge.svg?branch=main)](https://github.com/cassiomc1/forgeloop/actions/workflows/dependency-review.yml)
 [![Docs quality](https://github.com/cassiomc1/forgeloop/actions/workflows/docs-quality.yml/badge.svg?branch=main)](https://github.com/cassiomc1/forgeloop/actions/workflows/docs-quality.yml)
+[![ForgeLoop audit](https://github.com/cassiomc1/forgeloop/actions/workflows/forgeloop-audit.yml/badge.svg?branch=main)](https://github.com/cassiomc1/forgeloop/actions/workflows/forgeloop-audit.yml)
+[![Publish npm package](https://github.com/cassiomc1/forgeloop/actions/workflows/npm-publish.yml/badge.svg?branch=main)](https://github.com/cassiomc1/forgeloop/actions/workflows/npm-publish.yml)
+[![Package smoke](https://github.com/cassiomc1/forgeloop/actions/workflows/package-smoke.yml/badge.svg?branch=main)](https://github.com/cassiomc1/forgeloop/actions/workflows/package-smoke.yml)
+[![Release notes](https://github.com/cassiomc1/forgeloop/actions/workflows/release-notes.yml/badge.svg?branch=main)](https://github.com/cassiomc1/forgeloop/actions/workflows/release-notes.yml)
 
 ForgeLoop is a portable, vendor-neutral protocol for AI-assisted development
 and developer workflows. It turns an outcome into a contract, deterministic
@@ -52,6 +58,45 @@ frontmatter. Repository validators keep the catalog and metadata synchronized.
 
 ## Quickstart
 
+### Demonstração em 60 segundos
+
+Em um diretório descartável, inicialize o kit e crie uma tarefa isolada. O
+resultado é determinístico e pode ser inspecionado por qualquer harness
+compatível:
+
+```bash
+npx @cassiomc1/forgeloop init
+forgeloop task-create --task demo --claim src --json
+forgeloop route --task demo --work clean-code --json
+forgeloop preflight --task demo --json
+forgeloop next --task demo --json
+```
+
+O último comando informa a ação segura seguinte; ele não executa código nem
+agenda agentes.
+
+Antes de um harness criar ou retomar uma tarefa, ele pode confirmar a
+compatibilidade pública sem depender de detalhes internos:
+
+<!-- FORGELOOP EXAMPLE: readme:compatibility | exit=0 | json.protocolVersion=1 -->
+```bash
+forgeloop protocol-info --json
+```
+<!-- END FORGELOOP EXAMPLE -->
+
+### Responsabilidades
+
+| Responsabilidade | ForgeLoop | Harness ou desenvolvedor |
+| --- | --- | --- |
+| Validar contrato e rotas | Sim | Fornece intenção e sinais |
+| Implementar código | Não | Sim |
+| Registrar proveniência de comando | Sim, com `run-check` | Fornece comando e ambiente |
+| Validar conclusão | Sim | Fornece trabalho e evidência reais |
+| Agendar agentes ou inferência LLM | Não | Externo ao protocolo |
+
+Para uma troca concreta entre ferramentas, veja a
+[continuidade entre harnesses](./docs/CROSS_HARNESS_CONTINUITY.md).
+
 From a published package, initialize a target project with:
 
 ```bash
@@ -240,6 +285,9 @@ repository policy allows only ESLint, c8, and Mermaid CLI as development
 dependencies; `npm run dependency:policy` fails if runtime or unapproved
 dependencies appear.
 
+Para reportar vulnerabilidades ou contribuir com alterações, consulte
+[`SECURITY.md`](./SECURITY.md) e [`CONTRIBUTING.md`](./CONTRIBUTING.md).
+
 ## Autonomous blind-run isolation
 
 The repository does not claim a live blind conformance result for an external

package/THREAT_MODEL.md

@@ -17,6 +17,8 @@ remaining trust boundaries and their executable evidence.
 | Malicious work-state | Resumes stale, secret-bearing, or invalid work | `.forgeloop/work-state.json` | Schema/semantic checks, version checks, transition checks, contract/HEAD/artifact freshness, secret scan, size/depth bounds | Freshness cannot prove that an external process did not alter a file immediately afterward | `tests/work-state.test.js`, `tests/checkpoint-freshness.test.js`, `tests/security-limits.test.js` |
 | Forged preparation | Makes an agent's prose claim look like a completed preflight | Contract, route, gate, and preflight artifacts | Canonical SHA-256 fingerprints, guide-declared gate requirements, stale-artifact checks, and `E_*` failures | The CLI cannot stop a separate process from writing project files before preflight | `tests/protocol-artifacts.test.js`, `tests/preflight.test.js` |
 | Chronology rewrite | Hides execution before route, gates, or verification | `.forgeloop/events.ndjson` | Append-only local ledger, sequence numbers, hash chaining, and chronology validation without prompts or hidden reasoning | A privileged process can still replace the ledger after validation | `tests/lifecycle.test.js` |
+| Concurrent protocol mutation | Two writers read the same state or ledger tail and silently overwrite each other | Task state, task event ledger, and transaction journal | Mutations acquire a lease-bearing task lock, stage writes in `.forgeloop/.txn/`, preserve a recovery manifest, and publish only after the callback completes; state mutators use an expected revision, while ledger appends validate a tail checkpoint and stage only a synchronized suffix | The filesystem does not provide a multi-file atomic commit primitive; a process killed during append is recovered by truncating to the journaled pre-append size rather than treated as complete | `tests/state-revision.test.js`, `tests/concurrent-ledger.test.js`, `tests/scale-ledger.test.js`, `tests/transaction.test.js` |
+| Stale lock theft | A live process loses exclusive ownership because another process removes its lock | `.forgeloop/locks/<taskKey>.lock` | Locks record hostname, owner instance ID, heartbeat, and lease; inspection classifies `LIVE`, `STALE`, or `UNKNOWN`; ordinary recovery releases only an expired lease and `--force` is explicit | A malicious or separately privileged actor can still delete local locks | `tests/task-cli.test.js`, `tests/task-foundation.test.js` |
 | Lifecycle artifact repair | Direct state or receipt edits fabricate a legal recovery or terminal phase | Work state, receipt, evidence checks, and event ledger | New verification cycles record phase events and fingerprints; validators reject state/ledger divergence and future lifecycle evidence | Local artifacts are detection-oriented, not cryptographically tamper-proof against a privileged process rewriting every linked artifact | `tests/lifecycle-evidence-recovery.test.js`, `tests/completion-ergonomics.test.js` |
 | Unsupported profile fact | Turns an agent decision into a durable user fact | `PROJECT_PROFILE.md` and `.forgeloop/sources.json` | Source IDs, source-kind validation, unknown-reference rejection, and explicit misclassification failures | Arbitrary Markdown semantics still require a human or host-specific parser | `tests/profile-provenance.test.js`, `src/core/profile.js` |
 | Weak verification | Treats a vague or inferred claim as observed evidence | Receipt checks and coverage | Versioned check schema, contradictory-status rejection, observed-evidence requirements, and coverage matrix | Evidence remains local and declarative; it is not a remote attestation service | `tests/evidence-coverage.test.js`, `tests/completion.test.js` |
@@ -53,7 +55,7 @@ remaining trust boundaries and their executable evidence.
 | Lock regeneration or subdigest tampering | An actor modifies rules or baseline, omits subdigests, or regenerates `policy.lock` to hide tampering | Effective policy lock verification (`verifyPolicyLock`) | Lock derives deterministically from effective rules + baseline. Schema-invalid lock artifacts (malformed JSON or missing required fields such as `rulesDigest`/`baselineDigest`) fail closed with `E_POLICY_INVALID`; schema-valid locks whose semantic digest components (`algorithm`, `digest`, `rulesDigest`, `baselineDigest`) no longer match effective policy state fail with `E_POLICY_LOCK_MISMATCH` before any relocking. Changing only `capturedAt` does not change semantic identity | Explicit update commands (`policy-discover --write`, `baseline`) update lock after authorization | `tests/policy-hardening.test.js` |
 | Baseline re-record bypass | An actor uses `baseline --record` during an active task to convert newly introduced violations into tolerated debt | Active task baseline protection in `runBaseline` | `baseline --record` is rejected during active policy-bound tasks with `E_BASELINE_RECORD_DURING_ACTIVE_TASK`; only monotonic `--update` is permitted | Explicit `--policy-reset-authorized` flag required for intentional operator resets | `tests/policy-hardening.test.js` |
 | Legacy snapshot semantic confusion | A legacy task snapshot lacking baseline state is assumed to have empty baseline, creating false `WEAKEN` drift | Semantic baseline snapshotting in `policy-snapshot.json` | Snapshots retain full semantic baseline entries; snapshots lacking baseline state classify drift as `UNKNOWN` rather than inventing state | Modern tasks retain semantic baseline entries for exact diff | `tests/policy-hardening.test.js` |
-| Cross-task state confusion | Concurrent processes or alternative harnesses mutate or read the wrong task's state in a multi-task workspace | Task-scoped isolation in `.forgeloop/task-state/<taskKey>/` | Deterministic SHA-256 task directory namespacing, explicit `--task` / `FORGELOOP_TASK` selectors, file-level mutex locking (`.lock`), and claim overlap detection in `task-create` | Tasks must declare non-overlapping write claims or operate in isolated worktrees | `tests/task-namespace.test.js`, `tests/task-scope.test.js` |
+| Cross-task state confusion | Concurrent processes or alternative harnesses mutate or read the wrong task's state in a multi-task workspace | Task-scoped isolation in `.forgeloop/task-state/<taskKey>/` | Deterministic SHA-256 task directory namespacing, explicit `--task` / `FORGELOOP_TASK` selectors, separate file-level lease locks under `.forgeloop/locks/`, and claim overlap detection in `task-create` | Tasks must declare non-overlapping write claims or operate in isolated worktrees | `tests/task-namespace.test.js`, `tests/task-scope.test.js` |
 | Modern namespace descriptor deletion | Corruption or an attacker removes `task.json` from a modern task namespace (leaving contract/work-state/receipt/events), the resolver ignores the namespace, and stale legacy singleton state becomes authoritative | Descriptor boundary between modern task namespaces and the legacy singleton | Descriptor-less 64-hex directories are classified by contents: directories containing modern task artifacts (or empty directories) fail closed with `E_TASK_DESCRIPTOR_INVALID`; only directories containing exclusively the explicitly recognized legacy-incidental artifact (`policy-snapshot.json`) are ignored; `resolveTaskContext` fails closed when all namespaces are corrupt | A separately privileged process can rewrite task-state directories after validation | `tests/validate-receipt-task.test.js` |
 
 ## Boundary rules

package/docs/ARTIFACT_REFERENCE.md

@@ -287,6 +287,7 @@ The canonical, authoritative lifecycle work state. Represents current checkpoint
 - `failures` *(array<object>, required)*
 - `blockers` *(array<object>, required)*
 - `lastUpdated` *(string, required, minLength: 1)*
+- `revision` *(integer, optional, minimum: 0)*
 - `previousPhase` *(string, optional)*
 - `diagnosedHypothesis` *(string, optional, minLength: 1)*
 - `verificationEvidence` *(array<object>, optional)*
@@ -421,6 +422,16 @@ Attested command execution provenance artifact generated by `forgeloop run-check
 - `finishedAt` *(string, required, minLength: 1)*
 - `status` *(string, required, enum: `passed`, `failed`)*
 - `exitCode` *(integer or null, required)*
+- `durationMs` *(integer, optional, minimum: 0)*
+- `termination` *(string, optional, enum: `exit`, `signal`, `timeout`, `spawn-error`)*
+- `signal` *(string or null, optional)*
+- `stdoutSha256` *(string, optional, pattern: `^[a-f0-9]{64}$`)*
+- `stderrSha256` *(string, optional, pattern: `^[a-f0-9]{64}$`)*
+- `stdoutBytes` *(integer, optional, minimum: 0)*
+- `stderrBytes` *(integer, optional, minimum: 0)*
+- `outputTruncated` *(boolean, optional)*
+- `timeoutMs` *(integer, optional, minimum: 1)*
+- `terminationGraceMs` *(integer, optional, minimum: 1)*
 
 <!-- END FORGELOOP GENERATED: schema:execution -->
 

package/docs/CLI_REFERENCE.md

@@ -39,9 +39,9 @@ ForgeLoop uses a definition-driven command-line parser:
 
 | Category | Commands |
 | --- | --- |
-| **Setup & Maintenance** | [`init`](#init), [`update`](#update), [`task-migrate`](#task-migrate), [`task-unlock`](#task-unlock) |
-| **Inspection & Diagnostics** | [`doctor`](#doctor), [`progress`](#progress), [`profile-interview`](#profile-interview), [`inspect`](#inspect), [`status`](#status), [`validate-state`](#validate-state), [`validate-protocol`](#validate-protocol) |
-| **Lifecycle & State** | [`activate`](#activate), [`route`](#route), [`preflight`](#preflight), [`advance`](#advance), [`next`](#next), [`record-diagnosis`](#record-diagnosis), [`record-decision-criterion`](#record-decision-criterion), [`complete`](#complete), [`clear-state`](#clear-state), [`reconcile-closure`](#reconcile-closure), [`task-create`](#task-create), [`task-list`](#task-list), [`task-show`](#task-show), [`task-scope`](#task-scope) |
+| **Inspection & Diagnostics** | [`protocol-info`](#protocol-info), [`doctor`](#doctor), [`progress`](#progress), [`profile-interview`](#profile-interview), [`inspect`](#inspect), [`status`](#status), [`validate-state`](#validate-state), [`validate-protocol`](#validate-protocol) |
+| **Setup & Maintenance** | [`init`](#init), [`update`](#update), [`task-migrate`](#task-migrate), [`migrate-protocol`](#migrate-protocol), [`task-unlock`](#task-unlock) |
+| **Lifecycle & State** | [`activate`](#activate), [`route`](#route), [`preflight`](#preflight), [`advance`](#advance), [`next`](#next), [`record-diagnosis`](#record-diagnosis), [`record-decision-criterion`](#record-decision-criterion), [`complete`](#complete), [`clear-state`](#clear-state), [`reconcile-closure`](#reconcile-closure), [`task-create`](#task-create), [`task-list`](#task-list), [`task-show`](#task-show), [`task-lock-status`](#task-lock-status), [`task-scope`](#task-scope) |
 | **Cross-Harness Continuity** | [`continuity`](#continuity), [`record-continuity`](#record-continuity), [`reconcile-continuity`](#reconcile-continuity), [`clear-continuity`](#clear-continuity) |
 | **Verification & Completion** | [`prepare-completion`](#prepare-completion), [`run-check`](#run-check), [`record-check`](#record-check), [`record-terminal-result`](#record-terminal-result), [`audit`](#audit), [`report`](#report), [`validate-receipt`](#validate-receipt) |
 | **Policy & Auditing** | [`policy`](#policy), [`policy-discover`](#policy-discover), [`policy-status`](#policy-status), [`policy-diff`](#policy-diff), [`rule-verify`](#rule-verify), [`baseline`](#baseline), [`bundle`](#bundle) |
@@ -52,6 +52,30 @@ ForgeLoop uses a definition-driven command-line parser:
 
 ## 1. Setup & Maintenance
 
+### `protocol-info`
+
+Reports the public compatibility handshake required by external ForgeLoop harnesses.
+
+- **Purpose**: Publishes protocol/schema versioning, lifecycle metadata, command metadata, guide registry, and the documented error registry.
+- **When to use**: Before a harness creates or resumes a ForgeLoop task, and when verifying compatibility without reading internal source.
+- **Mutation**: Read-only.
+- **Options**:
+
+<!-- BEGIN FORGELOOP GENERATED: cli:protocol-info:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--json`: emit complete machine-readable protocol metadata
+
+<!-- END FORGELOOP GENERATED: cli:protocol-info:options -->
+
+- **Example**:
+
+  <!-- FORGELOOP EXAMPLE: cli-reference:protocol-info | exit=0 | json.commands.0.name=protocol-info -->
+  ```bash
+  forgeloop protocol-info --json
+  ```
+  <!-- END FORGELOOP EXAMPLE -->
+
 ### `init`
 
 Initializes ForgeLoop in a target repository.
@@ -407,6 +431,7 @@ Executes a verification command with ForgeLoop-attested provenance.
 - `--id <id>`: stable check identifier
 - `--requirement <id>`: completion requirement covered by the check
 - `--details <json>`: additional structured check details
+- `--timeout-ms <number>`: maximum command duration before termination
 - `-- <argv...>`: exact command argv to classify, execute, and attest
 - `--json`: emit structured output as JSON
 
@@ -1139,6 +1164,27 @@ Displays details of a specific task by ID or storage key.
   forgeloop task-show --task task-001 --json
   ```
 
+### `task-lock-status`
+
+Reports the lock owner and lease-based staleness classification for a specific task without mutating it.
+
+- **Mutation**: Read-only.
+- **Options**:
+
+<!-- BEGIN FORGELOOP GENERATED: cli:task-lock-status:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
+- `--json`: emit structured output as JSON
+
+<!-- END FORGELOOP GENERATED: cli:task-lock-status:options -->
+
+- **Example**:
+
+  ```bash
+  forgeloop task-lock-status --task task-001 --json
+  ```
+
 ### `task-scope`
 
 Updates or inspects write claims for a task.
@@ -1184,6 +1230,37 @@ Migrates a legacy 1.0 single-task `.forgeloop/` layout into a namespaced task di
   forgeloop task-migrate --json
   ```
 
+### `migrate-protocol`
+
+Plans or applies an explicitly supported persisted-state migration to a target
+protocol version.
+
+- **Purpose**: Provides a fail-closed compatibility migration surface. In the
+  current release, target protocol `1` either needs no change or converts a
+  detected legacy singleton layout through the verified `task-migrate` flow.
+- **When to use**: Before upgrading persisted ForgeLoop state when a release
+  documents a new protocol migration. Run the dry-run first and retain the
+  resulting migration receipt after applying a legacy conversion.
+- **Mutation**: Does not write with `--dry-run`. A supported legacy conversion
+  writes the namespaced task state and its `migration-receipt.json` before
+  removing legacy artifacts.
+- **Options**:
+
+<!-- BEGIN FORGELOOP GENERATED: cli:migrate-protocol:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--to <protocolVersion>`: target supported protocol version
+- `--dry-run`: show migration actions without writing or deleting artifacts
+- `--json`: emit structured migration result as JSON
+
+<!-- END FORGELOOP GENERATED: cli:migrate-protocol:options -->
+
+- **Example**:
+
+  ```bash
+  forgeloop migrate-protocol --to 1 --dry-run --json
+  ```
+
 ### `task-unlock`
 
 Forces the release of a stale task lock.
@@ -1197,6 +1274,7 @@ Forces the release of a stale task lock.
 - `--path <directory>`: target project directory (default: current directory)
 - `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
 - `--force`: force release of an orphaned task lock
+- `--stale-only`: release only a lock whose lease is expired
 - `--json`: emit structured output as JSON
 
 <!-- END FORGELOOP GENERATED: cli:task-unlock:options -->

package/docs/CROSS_HARNESS_CONTINUITY.md

@@ -29,6 +29,15 @@ Switching between execution environments (for example Codex $\rightarrow$ Claude
 
 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.
 
+Before it touches task state, a harness can verify the public compatibility
+handshake it will use for the handoff:
+
+<!-- FORGELOOP EXAMPLE: cross-harness:handshake | exit=0 | json.lifecycle.phases.0=RECEIVED -->
+```bash
+forgeloop protocol-info --json
+```
+<!-- END FORGELOOP EXAMPLE -->
+
 Key continuity invariants:
 
 - **Continuity is optional**: A missing `continuity.json` file does not invalidate an otherwise resumable task.
@@ -133,9 +142,11 @@ forgeloop status --json
 
 Or with explicit flag:
 
+<!-- FORGELOOP EXAMPLE: cross-harness:status | fixture=task:auth-feature | exit=0 | json.taskId=auth-feature -->
 ```bash
 forgeloop status --task auth-feature --json
 ```
+<!-- END FORGELOOP EXAMPLE -->
 
 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`.
 

package/docs/DOCUMENTATION_GUIDE.md

@@ -123,6 +123,21 @@ When writing documentation, use precise terms:
 
 Avoid ambiguous phrases like *"should generally"* or *"usually"* for behaviors that are strictly enforced by the validator.
 
+### Stable requirement IDs
+
+Every protocol-level `MUST` or `MUST NOT` has a stable `FL-<AREA>-<NNN>`
+anchor and an entry in [`protocol-requirements.json`](./protocol-requirements.json).
+Each map entry names its normative source, implementation validator, and at
+least one executable test. `npm run docs:check` rejects an unmapped normative
+requirement, an unused mapping, or a missing implementation/test target.
+
+### Documentation impact classification
+
+Classify each documentation-impacting change as one or more of: `NONE`,
+`REFERENCE_ONLY`, `OPERATIONAL`, `NORMATIVE`, `SCHEMA_COMPATIBILITY`,
+`MIGRATION`, or `SECURITY`. Changes that are normative, compatibility,
+migration, or security-sensitive require `npm run docs:check` before merge.
+
 ### Multi-Task Layout Rules
 
 - Canonical task-scoped paths are defined in `src/core/task-paths.js` under `.forgeloop/task-state/<taskKey>/`.
@@ -196,3 +211,5 @@ For documentation-impacting changes, verify each item before merging:
 - [ ] Did package-shipped documentation change?
 - [ ] Were generated reference docs updated (`npm run docs:generate`)?
 - [ ] Did documentation conformance CI pass (`npm run docs:check`)?
+- [ ] If normative language changed, are stable IDs and mappings current?
+- [ ] Is the documentation impact classification recorded in the PR?

package/docs/GETTING_STARTED.md

@@ -39,6 +39,15 @@ Core mental model:
 
 In your project repository:
 
+Confirm the installed CLI exposes the compatible protocol before creating
+state. This is read-only and safe to run in a fresh project directory.
+
+<!-- FORGELOOP EXAMPLE: getting-started:compatibility | exit=0 | json.compatibility.schemaVersion=1 -->
+```bash
+forgeloop protocol-info --json
+```
+<!-- END FORGELOOP EXAMPLE -->
+
 ```bash
 # Initialize ForgeLoop kit and discovery shims
 npx @cassiomc1/forgeloop init

package/docs/RECIPES.md

@@ -25,11 +25,15 @@ Concise, copy-paste friendly recipes for common ForgeLoop tasks.
 
 ### Recipe 1 — Start a New Task
 
+<!-- FORGELOOP EXAMPLE: recipes:create-task | exit=0 | json.taskId=task-001 -->
 ```bash
-# 1. Create a task with explicit claims
 forgeloop task-create --task task-001 --claim src --claim tests --json
+```
+<!-- END FORGELOOP EXAMPLE -->
 
+```bash
 # 2. Discover task state path and author contract under .forgeloop/task-state/<taskKey>/contract.json
+
 forgeloop task-show --task task-001 --json
 
 # 3. Route engineering guides