@cassiomc1/forgeloop 0.1.16 → 1.1.0

package/.cursor/rules/project-loop.mdc

@@ -17,11 +17,12 @@ Do not treat ForgeLoop as vendor-specific, optional, or to follow only "in spiri
 5. Make the minimum change, run specific checks, and run proportional regression checks.
 6. Diagnose failures before fixing them; do not repeat attempts without new evidence.
 7. Request authority for unrelated actions, installations, and publications. Do not install a missing verification tool merely to satisfy a check. For missing Qwen-MM-Plugins, follow `LOOP_ENGINEERING.md`.
-8. After implementation begins, do not return a final result in `EXECUTING`: advance through `VERIFYING` → structured evidence → `REVIEWING` → execution receipt → validator-backed `COMPLETE`. If closure cannot be reached, report `BLOCKED` or `PARTIALLY VERIFIED`.
+8. Before creating or activating new lifecycle state: if `.forgeloop/work-state.json` exists, 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.
+9. After implementation begins, do not return a final result in `EXECUTING`: advance through `VERIFYING` → structured evidence → `REVIEWING` → execution receipt → validator-backed `COMPLETE`. If closure cannot be reached, report `BLOCKED` or `PARTIALLY VERIFIED`.
 
 After implementation work for the current task is complete, run `forgeloop next` before returning a final result. Follow the returned lifecycle action until ForgeLoop reaches a terminal state or an explicit blocker.
 
-9. Report only demonstrated results and checks.
+10. Report only demonstrated results and checks.
 
 Do not stop for non-blocking missing product details. When a safe, reversible
 local default exists, record it as an agent assumption and follow the Blocking vs Non-Blocking Decisions policy in `LOOP_ENGINEERING.md`.

package/.github/copilot-instructions.md

@@ -14,6 +14,7 @@ Use these instructions across the repository while preserving local rules.
 - Make the smallest coherent change; validate with specific and regression checks.
 - Diagnose causes before fixing failures; do not make unverified attempts.
 - Do not install software, publish, delete, or alter external state without authority. Do not install a missing verification tool merely to satisfy a check. For missing Qwen-MM-Plugins, follow `LOOP_ENGINEERING.md`.
+- Before creating or activating new lifecycle state: if `.forgeloop/work-state.json` exists, 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.
 - After implementation begins, do not return a final result in `EXECUTING`: advance through `VERIFYING` → structured evidence → `REVIEWING` → execution receipt → validator-backed `COMPLETE`. If closure cannot be reached, report `BLOCKED` or `PARTIALLY VERIFIED`.
 
 After implementation work for the current task is complete, run `forgeloop next` before returning a final result. Follow the returned lifecycle action until ForgeLoop reaches a terminal state or an explicit blocker.

package/AGENTS.md

@@ -12,7 +12,8 @@ Do not treat ForgeLoop as vendor-specific, optional, or to follow only "in spiri
 1. Make the smallest coherent change, run specific checks, and proportional regression checks.
 1. Diagnose failures before fixing; do not repeat attempts without new evidence.
 1. Do not install software, publish, delete, or migrate data without authority. Do not install a missing verification tool merely to satisfy a check. For missing Qwen-MM-Plugins, follow `LOOP_ENGINEERING.md`.
-1. Before implementation, create/validate `.forgeloop/current-contract.json`, persist routing, satisfy gates, and require `forgeloop preflight` to return `READY`.
+1. Before creating or activating new lifecycle state: if `.forgeloop/work-state.json` exists, 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.
+1. Before implementation, create/validate the task contract (`contract.json`), persist routing, satisfy gates, and require `forgeloop preflight` to return `READY`.
 1. Before claiming `COMPLETE`, require `forgeloop complete` to return `VALID`; otherwise report completion as not protocol-verified.
 1. After implementation begins, do not return a final result in `EXECUTING`: advance through `VERIFYING` → structured evidence → `REVIEWING` → execution receipt → validator-backed `COMPLETE`. If closure cannot be reached, report `BLOCKED` or `PARTIALLY VERIFIED`.
 1. After implementation work for the current task is complete, run `forgeloop next` before returning a final result. Follow the returned lifecycle action until ForgeLoop reaches a terminal state or an explicit blocker.

package/CLAUDE.md

@@ -14,6 +14,7 @@ When working in this repository:
 1. Make small changes, run specific checks, and run proportional regression checks.
 1. Investigate root causes before fixing failures; do not make unverified attempts.
 1. Request authority for unrelated installations, publications, deletions, or migrations. Do not install a missing verification tool merely to satisfy a check. For missing Qwen-MM-Plugins, follow `LOOP_ENGINEERING.md`.
+1. Before creating or activating new lifecycle state: if `.forgeloop/work-state.json` exists, 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.
 1. After implementation begins, do not return a final result in `EXECUTING`: advance through `VERIFYING` → structured evidence → `REVIEWING` → execution receipt → validator-backed `COMPLETE`. If closure cannot be reached, report `BLOCKED` or `PARTIALLY VERIFIED`.
 1. After implementation work for the current task is complete, run `forgeloop next` before returning a final result. Follow the returned lifecycle action until ForgeLoop reaches a terminal state or an explicit blocker.
 1. Report current evidence, limitations, and publication state without claiming checks that were not run.

package/DOCS_INDEX.md

@@ -7,6 +7,13 @@ integration and guide context. Use this map before editing documentation.
 
 | Need | Canonical source | Boundary |
 | --- | --- | --- |
+| Getting started tutorial | [`docs/GETTING_STARTED.md`](./docs/GETTING_STARTED.md) | First-time walkthrough from init to completion |
+| Cross-harness continuity | [`docs/CROSS_HARNESS_CONTINUITY.md`](./docs/CROSS_HARNESS_CONTINUITY.md) | Operational handoff and multi-tool resumption |
+| CLI command reference | [`docs/CLI_REFERENCE.md`](./docs/CLI_REFERENCE.md) | Full syntax, options, and JSON examples for all commands |
+| Artifact and schema reference | [`docs/ARTIFACT_REFERENCE.md`](./docs/ARTIFACT_REFERENCE.md) | Purpose, mutability, and trust classifications of `.forgeloop/` |
+| Troubleshooting and recovery | [`docs/TROUBLESHOOTING.md`](./docs/TROUBLESHOOTING.md) | Symptom-first recovery and stable error code reference |
+| Operational recipes | [`docs/RECIPES.md`](./docs/RECIPES.md) | Short copy-paste recipes for daily workflows |
+| Documentation guide | [`docs/DOCUMENTATION_GUIDE.md`](./docs/DOCUMENTATION_GUIDE.md) | Rules and checklist for modifying documentation |
 | 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 |
@@ -17,6 +24,35 @@ integration and guide context. Use this map before editing documentation.
 | 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 |
 
+## Audience map
+
+| I am a... | Start here |
+| --- | --- |
+| **First-time user or developer** | [`docs/GETTING_STARTED.md`](./docs/GETTING_STARTED.md) |
+| **AI coding agent / harness** | [`AGENTS.md`](./AGENTS.md) → [`LOOP_ENGINEERING.md`](./LOOP_ENGINEERING.md) |
+| **Harness integrator** | [`PROTOCOL_INTEGRATION.md`](./PROTOCOL_INTEGRATION.md) |
+| **Resuming another tool / session** | [`docs/CROSS_HARNESS_CONTINUITY.md`](./docs/CROSS_HARNESS_CONTINUITY.md) |
+| **Looking up CLI commands** | [`docs/CLI_REFERENCE.md`](./docs/CLI_REFERENCE.md) |
+| **Inspecting `.forgeloop/` files** | [`docs/ARTIFACT_REFERENCE.md`](./docs/ARTIFACT_REFERENCE.md) |
+| **Fixing a broken or stale state** | [`docs/TROUBLESHOOTING.md`](./docs/TROUBLESHOOTING.md) |
+| **Looking for quick recipes** | [`docs/RECIPES.md`](./docs/RECIPES.md) |
+| **Documentation contributor** | [`docs/DOCUMENTATION_GUIDE.md`](./docs/DOCUMENTATION_GUIDE.md) |
+| **Protocol architect / maintainer** | [`LOOP_SYSTEM_DESIGN.md`](./LOOP_SYSTEM_DESIGN.md) + [`schemas/`](./schemas/) |
+| **Security auditor** | [`THREAT_MODEL.md`](./THREAT_MODEL.md) |
+| **Engineering guide author** | [`GUIDE_ROUTER.md`](./GUIDE_ROUTER.md) + [`ENG/`](./ENG/) |
+
+## Task map
+
+- **Start my first task**: [`docs/GETTING_STARTED.md`](./docs/GETTING_STARTED.md)
+- **Resume after switching tools**: [`docs/CROSS_HARNESS_CONTINUITY.md`](./docs/CROSS_HARNESS_CONTINUITY.md)
+- **Check CLI options and syntax**: [`docs/CLI_REFERENCE.md`](./docs/CLI_REFERENCE.md)
+- **Understand what `.forgeloop/` stores**: [`docs/ARTIFACT_REFERENCE.md`](./docs/ARTIFACT_REFERENCE.md)
+- **Fix a blocked, stale, or invalid state**: [`docs/TROUBLESHOOTING.md`](./docs/TROUBLESHOOTING.md)
+- **Find operational copy-paste commands**: [`docs/RECIPES.md`](./docs/RECIPES.md)
+- **Read the normative protocol specification**: [`LOOP_ENGINEERING.md`](./LOOP_ENGINEERING.md)
+- **Integrate a new AI environment**: [`PROTOCOL_INTEGRATION.md`](./PROTOCOL_INTEGRATION.md)
+- **Edit documentation safely**: [`docs/DOCUMENTATION_GUIDE.md`](./docs/DOCUMENTATION_GUIDE.md)
+
 `README.md` is intentionally a catalog and quickstart. Do not copy the full
 process into adapters or README sections; link to the canonical source.
 

package/ENG/design-code-eng.md

@@ -307,10 +307,40 @@ Canvas, WebGL, SVG displacement, and Liquid Glass effects follow the **normative
 - For charts and data visualization, consult [TanStack Charts](https://github.com/TanStack/charts); preserve responsiveness, contrast, keyboard readability, and never rely on color alone to communicate series or states.
 - For subtle interaction sounds, consult [Cuelume](https://cuelume-site.pages.dev/); provide volume/mute controls and never rely on audio to communicate essential information.
 
+### Architecture and diagram design — Beautiful Mermaid
+
+When a task benefits from a polished technical diagram — for example an
+architecture flow, lifecycle, state machine, sequence, class, ER, or other
+Mermaid-supported visualization — consider
+[Beautiful Mermaid by Craft](https://agents.craft.do/mermaid) as an optional
+design/rendering resource.
+
+Use the live editor at
+[agents.craft.do/mermaid/editor](https://agents.craft.do/mermaid/editor) to
+preview and refine Mermaid source and, when appropriate, export a polished SVG.
+
+Rules:
+
+- Mermaid source remains the canonical editable artifact when the project
+  already uses Mermaid-as-source.
+- Prefer improving diagram structure and semantics before styling.
+- Preserve technical accuracy; visual polish must never remove meaningful
+  states, branches, trust boundaries, failure paths, or labels.
+- Prefer local/versioned SVG assets for repository documentation rather than
+  hotlinking externally rendered images.
+- Treat Beautiful Mermaid as optional tooling, not as an implementation,
+  verification, authority, or completion dependency.
+- Do not install `beautiful-mermaid` merely to render a documentation asset
+  when the browser editor or an already available equivalent is sufficient.
+- If automated rendering is explicitly required, evaluate the open-source
+  `beautiful-mermaid` library separately under the project's dependency and
+  authorization policies before adding it.
+
 ## External design-reference map
 
 Select references for a product problem; they do not override project tokens or semantics. Check every adoption for keyboard and focus access, contrast, reduced motion, touch behavior, bundle/runtime cost, and fallback behavior. Cursor, canvas, 3D, audio, and decorative motion are progressive enhancement only. Do not copy source or assets; check the license and current terms for each exact resource, and treat a catalog listing as no transfer of rights.
 
+- **Technical diagrams and architecture flows**: for polished Mermaid-based architecture and workflow diagrams, use [Beautiful Mermaid by Craft](https://agents.craft.do/mermaid) when relevant; preserve canonical Mermaid source, local versioned SVG assets, and do not treat presentation tooling as a mandatory protocol gate or runtime dependency.
 - **Component source and interaction inspiration**: use [21st.dev](https://21st.dev/) to study components and interactions; inspect each source, dependency, community contribution, and premium-material term before adoption.
 - **Component and motion inspiration**: use [React Bits](https://reactbits.dev/) to study component and motion behavior; distinguish public/free material from React Bits Pro and inspect each source/dependency license.
 - **Component inspiration**: use [Fancy Components](https://www.fancycomponents.dev/) to study component composition; verify its terms separately from Motion, Tailwind, shadcn, or other dependencies.
@@ -514,3 +544,4 @@ Select references for a product problem; they do not override project tokens or
   - Rights: the gallery's images and works are distinct from external resources it merely indexes. Consult the [terms](https://liquidglassdesign.com/terms); do not rehost, redistribute, or directly use images or works commercially without permission. For each external prompt or code resource, verify its license, provenance, credits, compatibility, and maintenance individually before use; being indexed does not transfer rights.
 - Apple — Adopting Liquid Glass (official guidance for Apple platforms): https://developer.apple.com/documentation/TechnologyOverviews/adopting-liquid-glass
 - Liquid Glass React, SVG, and Studio (experimental implementations; assess license, compatibility, weight, and maintenance): https://github.com/rdev/liquid-glass-react | https://github.com/shuding/liquid-glass | https://github.com/iyinchao/liquid-glass-studio
+- Beautiful Mermaid (technical diagram design and rendering): https://agents.craft.do/mermaid | https://agents.craft.do/mermaid/editor | https://github.com/lukilabs/beautiful-mermaid

package/ENG/documentation-quality-eng.md

@@ -0,0 +1,400 @@
+---
+name: documentation-quality-eng
+language: en
+description: "Quality standards for accurate, task-oriented, maintainable, accessible, and verifiable technical documentation."
+version: "2026.09"
+last-reviewed: "2026-08-17"
+guide-id: documentation
+---
+
+# Documentation Quality for AI Agents
+
+> **Related documents**: use [`clean-code-eng.md`](./clean-code-eng.md) when software behavior or code structure changes; [`test-code-eng.md`](./test-code-eng.md) for executable examples and verification strategy; [`sec-code-eng.md`](./sec-code-eng.md) for secrets, authentication, authorization, privacy, and sensitive examples; [`accessibility-eng.md`](./accessibility-eng.md) when a published documentation surface has additional accessibility requirements. This guide owns documentation architecture, factual quality, freshness, maintainability, and reader usability.
+>
+> **Tooling policy**: identify the documentation surface, canonical sources, and existing project checks first. Prefer already available project-native tools. Ask for authorization before installing tooling or changing the environment. If a required check cannot be executed, record it as blocked or `NOT_VERIFIED`; never claim it passed.
+
+## Context
+
+Technical documentation is part of the product contract. A document can compile, render, and contain no broken links while still being wrong, incomplete, difficult to use, or stale. Treat documentation changes with the same evidence discipline as executable changes: identify the reader, identify the authoritative source, make the smallest coherent change, and verify what can be observed.
+
+## Documentation quality model
+
+Review documentation across independent dimensions:
+
+- **Accuracy** — facts match the implementation, public contract, schema, registry, configuration, or other authoritative source.
+- **Completeness** — the intended reader has enough information to complete the intended task.
+- **Consistency** — terminology, values, commands, and behavior do not contradict other authoritative documentation.
+- **Precision** — statements are specific enough to act on and verify.
+- **Usefulness** — the content serves a real reader need rather than filling a template.
+- **Freshness** — current supported behavior is documented and obsolete claims are removed or versioned.
+- **Findability** — readers can reach the content through predictable navigation and descriptive headings/links.
+- **Accessibility** — structure and meaning remain usable with assistive technology and without visual-only cues.
+- **Verifiability** — executable or machine-defined claims are checked against authoritative sources where feasible.
+- **Flow** — prerequisites, actions, results, and recovery guidance follow the reader's task without unrelated detours.
+
+Functional correctness is required before polish. A beautiful document that is inaccurate is not high-quality documentation.
+
+## Identify the reader and job
+
+Before writing, answer:
+
+- Who is the intended reader?
+- What are they trying to accomplish or understand?
+- What can they reasonably be expected to know?
+- What prerequisites must exist?
+- What is the expected result?
+- Which project source owns each factual claim?
+- Which checks can verify the result?
+
+Do not write from memory when the repository contains a more authoritative source.
+
+## Documentation modes
+
+Use the Diátaxis model as a practical mental model. Do not create empty structures merely to satisfy it.
+
+### Tutorial
+
+Use a tutorial for learning. Provide a controlled, safe path that produces a working result and helps the reader acquire familiarity. Keep optional branches and exhaustive reference material out of the main learning flow.
+
+### How-to guide
+
+Use a how-to guide for a real task. State the goal and prerequisites, provide ordered actions, show the expected result, and include verification or recovery where useful. Link to explanation rather than interrupting the procedure with long conceptual digressions.
+
+### Reference
+
+Use reference for authoritative technical facts: APIs, CLI commands, configuration, schemas, environment variables, statuses, and error codes. Prioritize accuracy, completeness, precision, neutrality, and predictable structure. Where possible, structure reference documentation to reflect the structure of the system it describes.
+
+### Explanation
+
+Use explanation for understanding: architecture, concepts, trade-offs, context, and why the system behaves as it does. Keep required operational steps in how-to material.
+
+## README quality
+
+A repository README should normally make it possible to answer:
+
+1. What is this project?
+2. Why would I use it?
+3. What are the prerequisites?
+4. How do I get a minimal working result?
+5. Where is deeper documentation?
+6. How do I get help or contribute when relevant?
+7. What license or support policy applies?
+
+Keep the README as an entry point. Move deep tutorials, reference, architecture, and troubleshooting to dedicated documents when they grow.
+
+## Canonical sources and docs-as-code
+
+Prefer one authoritative source for machine-defined facts.
+
+Examples:
+
+```text
+package scripts       -> documented development commands
+CLI registry          -> CLI reference
+OpenAPI description   -> HTTP API reference
+JSON Schema/types     -> configuration/reference fields
+error registry        -> error-code reference
+runtime config        -> environment-variable reference
+protocol constants    -> lifecycle/status reference
+```
+
+Generate or validate projections when practical. Do not manually copy the same factual table into multiple documents.
+
+## Generated and handwritten documentation
+
+Generated content must have an explicit owner and deterministic generation path. Edit the canonical source or generator, not the generated projection.
+
+Keep handwritten content for reader context, explanation, examples, and guidance that cannot be mechanically derived.
+
+If generated regions use markers, validation must fail closed on missing, duplicate, nested, malformed, or unknown regions rather than silently rewriting arbitrary content.
+
+## Documentation impact analysis
+
+For each task, assess whether it changes:
+
+- public behavior;
+- API or CLI syntax;
+- installation or prerequisites;
+- configuration or environment variables;
+- architecture or trust boundaries;
+- authentication or authorization;
+- errors or observable states;
+- deployment or operation;
+- version compatibility;
+- deprecations or migration steps;
+- examples or workflows.
+
+Update affected documentation in the same task when the change is required for correct use.
+
+## Freshness and timeless wording
+
+Avoid time-sensitive words such as `new`, `currently`, `latest`, `now`, or `soon` in evergreen technical documentation when they will age without adding information.
+
+Use explicit versions or dates when history or compatibility requires them.
+
+Release notes, migration histories, and announcements may intentionally use time-based language.
+
+## Writing style and terminology
+
+- Use direct, concise language.
+- Prefer active voice.
+- Use second person where it clarifies reader actions.
+- Prefer specific nouns and verbs over vague references.
+- Use one canonical term per concept.
+- Define acronyms when the intended audience may not know them.
+- Use sentence-case headings unless project style requires otherwise.
+- Avoid idioms, culture-specific jokes, unnecessary metaphors, and ambiguous language in globally consumed documentation.
+- Use normative `MUST`, `SHOULD`, and `MAY` only when the document is truly specifying requirement levels.
+
+## Procedures
+
+A procedure should normally include:
+
+```text
+goal
+prerequisites
+ordered actions
+expected result
+verification
+recovery/troubleshooting
+```
+
+Use numbered steps when order matters and imperative verbs for required actions.
+
+Do not hide a prerequisite after the step that depends on it.
+
+## Commands and code samples
+
+Runnable commands and copyable code must be safe and credible.
+
+- Validate examples when feasible.
+- Never invent successful command output.
+- Label illustrative output explicitly.
+- Use clear placeholders.
+- Never include real secrets, tokens, private keys, PII, or production credentials.
+- Explain destructive effects before the command.
+- Follow the project's language and formatting conventions.
+- Prefer real text over screenshots of terminal output or code.
+
+## API documentation
+
+For HTTP APIs, use a machine-readable description such as OpenAPI when the project already supports or benefits from it.
+
+Document relevant:
+
+- authentication and authorization;
+- operations and paths;
+- parameters;
+- request and response bodies;
+- status codes and errors;
+- pagination;
+- rate limits;
+- idempotency;
+- webhooks;
+- versioning;
+- deprecation;
+- examples.
+
+Do not require OpenAPI for projects without an HTTP API.
+
+## CLI documentation
+
+CLI reference should describe relevant:
+
+- usage;
+- commands;
+- arguments;
+- options;
+- aliases;
+- defaults;
+- repeatable options;
+- exit/error behavior;
+- examples;
+- shell-sensitive behavior;
+- configuration precedence.
+
+Derive or validate these facts from the CLI registry/parser when possible.
+
+## Configuration and environment documentation
+
+Document each public configuration item with relevant:
+
+```text
+name
+purpose
+type
+required/optional
+default
+allowed values
+safe example
+secret classification
+scope
+precedence
+reload/restart behavior
+```
+
+Keep `.env.example`, runtime configuration, and documentation consistent.
+
+## Architecture documentation
+
+Document the architecture at the smallest useful level.
+
+Cover relevant:
+
+- system context;
+- major runtime boundaries;
+- dependencies;
+- data flow;
+- trust boundaries;
+- storage;
+- external systems;
+- deployment topology;
+- important architectural decisions.
+
+Use diagrams only when they improve understanding. A context/container view is enough for many systems; do not generate every possible diagram level.
+
+For significant decisions, use an ADR or equivalent record containing context, decision, alternatives when useful, consequences, and status.
+
+## Troubleshooting and runbooks
+
+Write troubleshooting around observable symptoms or stable error codes.
+
+Prefer:
+
+```text
+symptom
+likely cause
+how to verify
+correction
+next diagnostic/escalation step
+```
+
+Operational runbooks should identify trigger, access prerequisites, safety checks, steps, verification, rollback, and escalation.
+
+## Accessibility
+
+- Use one clear title.
+- Maintain meaningful heading hierarchy.
+- Use descriptive link text instead of `click here`.
+- Provide text alternatives for informative images.
+- Do not put unique information only in screenshots or diagrams.
+- Do not use color, location, shape, or direction as the only semantic cue.
+- Use tables for tabular data, not layout.
+- Keep long content scannable.
+- Prefer real text for code and terminal output.
+
+## Security and sensitive information
+
+Documentation must not expose:
+
+```text
+tokens
+passwords
+private keys
+real credentials
+session identifiers
+personal data
+production connection strings
+internal secrets
+```
+
+Use explicitly fake examples. Authentication and authorization documentation must match actual server-side behavior and permissions.
+
+## Versioning, deprecation, and migration
+
+If the project has a versioned public API, keep its documentation precise and comprehensive enough to understand compatibility.
+
+Document breaking changes and deprecations. When users need action to upgrade, provide a migration guide with affected versions, prerequisites, steps, verification, rollback/recovery, and known incompatibilities.
+
+Do not promise removal dates or future behavior unless the project has committed to them.
+
+## Validation and evidence
+
+Use the project's own tools first.
+
+Possible checks include:
+
+- Markdown lint/validation;
+- internal link and anchor validation;
+- external link checks with an explicit network-failure policy;
+- documentation build;
+- code example execution or compilation;
+- OpenAPI/schema validation;
+- CLI/reference parity;
+- configuration/reference parity;
+- generated-document freshness;
+- diagram source/artifact parity;
+- README quick-start execution.
+
+Do not install optional tooling solely to satisfy this list.
+
+If a required check is unavailable, record it as blocked or `NOT_VERIFIED`. Never report an unexecuted check as passed.
+
+## Anti-patterns
+
+Avoid:
+
+- README as a dumping ground;
+- tutorials mixed with exhaustive reference;
+- procedures interrupted by unrelated explanation;
+- factual tables manually duplicated across files;
+- untested commands presented as guaranteed;
+- invented output;
+- screenshots of code or terminal text;
+- stale time-sensitive wording;
+- dead-end documents with no navigation;
+- manual edits to generated documentation;
+- undocumented breaking changes;
+- known required documentation deferred indefinitely after behavior changes.
+
+## Agent workflow
+
+For documentation work:
+
+1. Discover relevant documentation and project truth sources.
+2. Classify the reader need: tutorial, how-to, reference, or explanation.
+3. Identify the authoritative source for factual claims.
+4. Map documentation impact.
+5. Make the smallest coherent update.
+6. Run relevant project-native documentation checks.
+7. Inspect the diff from the intended reader's perspective.
+8. Cross-check facts against implementation or canonical machine sources.
+9. Record observed verification evidence through the project/ForgeLoop verification flow.
+10. Do not claim completion beyond the evidence.
+
+## Documentation Definition of Done
+
+Before completion verify:
+
+- [ ] Intended reader and purpose are clear.
+- [ ] Factual claims match authoritative project sources.
+- [ ] The documentation mode fits the reader need.
+- [ ] Required information is complete for the intended task.
+- [ ] Terminology is consistent.
+- [ ] Procedures are ordered and actionable.
+- [ ] Examples and commands are safe and validated when feasible.
+- [ ] Internal navigation and links are coherent.
+- [ ] Accessibility basics are satisfied.
+- [ ] No real secrets or sensitive data appear.
+- [ ] Generated/reference material is fresh.
+- [ ] Version/deprecation/migration impact is documented when applicable.
+- [ ] Relevant project-native checks have observed evidence.
+- [ ] Unavailable required checks are explicitly `NOT_VERIFIED` or blocked.
+- [ ] The completion claim does not exceed the evidence.
+
+## Sources and further reading
+
+This guide is an original operational synthesis informed by:
+
+- Diátaxis — https://diataxis.fr/
+- Diátaxis quality — https://diataxis.fr/quality/
+- Google Developer Documentation Style Guide — https://developers.google.com/style
+- Google accessible documentation guidance — https://developers.google.com/style/accessibility
+- Google code sample guidance — https://developers.google.com/style/code-samples
+- Google timeless documentation guidance — https://developers.google.com/style/timeless-documentation
+- GitHub repository documentation guidance — https://docs.github.com/en/repositories/creating-and-managing-repositories/best-practices-for-repositories
+- W3C WAI writing guidance — https://www.w3.org/WAI/tips/writing/
+- OpenAPI Specification — https://spec.openapis.org/oas/
+- Semantic Versioning — https://semver.org/
+- C4 model — https://c4model.com/
+- RFC 2119 — https://www.rfc-editor.org/rfc/rfc2119.html

package/EXECUTION_STATE.md

@@ -1,9 +1,13 @@
 # Execution state and resume protocol
 
+> Looking for a practical resume tutorial? See [`docs/CROSS_HARNESS_CONTINUITY.md`](./docs/CROSS_HARNESS_CONTINUITY.md).
+> Looking for artifact field definitions? See [`docs/ARTIFACT_REFERENCE.md`](./docs/ARTIFACT_REFERENCE.md).
+> Looking for stale-state recovery? See [`docs/TROUBLESHOOTING.md`](./docs/TROUBLESHOOTING.md).
+
 Compatible agents may persist a handoff checkpoint at:
 
 ```text
-.forgeloop/work-state.json
+.forgeloop/task-state/<taskKey>/work-state.json
 ```
 
 The file is local, ignored by Git, schema-versioned, and never a replacement
@@ -58,10 +62,10 @@ Any material difference produces `REVALIDATION_REQUIRED`. A non-Git target
 reports that branch/HEAD drift is not verifiable. Cheap checks may be rerun,
 but a completed destructive or publication action is never rerun automatically.
 
-The current contract is compared only when its JSON file is supplied:
+The current contract is compared when resolving the target task:
 
 ```bash
-forgeloop status --contract-file .forgeloop/current-contract.json --json
+forgeloop status --task <id> --json
 ```
 
 Without that file, contract comparison is `NOT_VERIFIED`; the status does not
@@ -69,16 +73,11 @@ claim full freshness. Required artifact hashes report missing or changed files.
 An optional age threshold may recommend cheap verification with
 `CHECKPOINT_OLD` without changing a fresh result.
 
-`inspect`, `status`, and `validate-protocol` use the same derived freshness
-classifier. Protocol validation can be run against the current route, state,
-receipt, and contract artifacts:
+Protocol validation can be run against the task artifacts:
 
 ```bash
 forgeloop validate-protocol \
-  --route-file .forgeloop/routing-result.json \
-  --state-file .forgeloop/work-state.json \
-  --receipt-file .forgeloop/execution-receipt.json \
-  --contract-file .forgeloop/current-contract.json \
+  --task <id> \
   --json
 ```
 
@@ -109,15 +108,26 @@ forgeloop clear-state
 
 `status` explains whether state is absent, fresh, or requires revalidation.
 `validate-state` performs schema and semantic checks without mutation.
-`clear-state` affects only `.forgeloop/work-state.json` and prints the exact
+`clear-state` affects only `work-state.json` for the target task 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,
+`work-state.json` under `.forgeloop/task-state/<taskKey>/` remains the canonical checkpoint and owns phase,
 `completedSteps`, `pendingSteps`, failures, blockers, verification cycles, and
-required artifact fingerprints. `.forgeloop/continuity.json` is an optional
+required artifact fingerprints. `continuity.json` under `.forgeloop/task-state/<taskKey>/` 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.
+
+## Resume decision table
+
+| Work State | Continuity | Repository HEAD | Action |
+| --- | --- | --- | --- |
+| Valid / Fresh | Fresh | Matches | Continue execution directly via `forgeloop next` |
+| Valid / Fresh | Missing | Matches | Continue from work-state checkpoint (continuity is optional) |
+| Valid / Fresh | Stale | Matches / Drifted | Run `forgeloop reconcile-continuity --json`, inspect diff, continue |
+| Stale | Any | Changed | Run `forgeloop route` and `forgeloop preflight` to revalidate |
+| Invalid / Corrupted | Any | Any | Fail closed; inspect errors via `forgeloop doctor --json` |
+| Different Task ID | Present | Any | Do not merge contexts; clear or finish previous task first |