@cassiomc1/forgeloop 1.0.0 → 1.1.0

package/GUIDE_ROUTER.md

@@ -51,6 +51,7 @@ project commands.
 | `performance` | [Performance](./ENG/perf-code-eng.md) | Measurement, diagnosis, budgets, and optimization |
 | `accessibility` | [Accessibility](./ENG/accessibility-eng.md) | WCAG, keyboard access, focus, semantics, and assistive technology |
 | `games` | [Web games](./ENG/games-code-design-web-eng.md) | Architecture and operation of 2D, 3D, and procedural web games |
+| `documentation` | [Documentation quality](./ENG/documentation-quality-eng.md) | Accuracy, architecture, freshness, accessibility, and verifiable technical documentation |
 
 ## Domain rules
 
@@ -190,11 +191,26 @@ rg -n '^## |game loop|procedural|input|assets|audio|multiplayer|WASM|PWA|CI/CD'
 
 **Expected evidence:** verifiable simulation, determinism when promised, capability fallbacks, budgets, accessibility, and release gates.
 
+### `documentation` — technical documentation quality
+
+**Activate when:** creating, modifying, reviewing, or restructuring README files, tutorials, how-to guides, technical reference, API/CLI/configuration documentation, architecture documentation, troubleshooting, migration guides, runbooks, or other project documentation; also activate when an implementation change explicitly affects a documentation surface.
+
+**Do not activate merely because:** source code contains comments, a task description mentions documentation in passing, or code examples appear in an unrelated domain document without changing project documentation.
+
+**Usually combine with:** the domain whose behavior is documented. Add `test` when commands, examples, generated docs, or executable references need verification; add `security` for authentication, authorization, secrets, privacy, or sensitive examples; use `accessibility` when the published documentation surface itself has accessibility requirements.
+
+```bash
+rg -n '^## |accuracy|completeness|Diátaxis|tutorial|how-to|reference|explanation|README|API|CLI|configuration|architecture|freshness|accessibility|Definition of Done' ENG/documentation-quality-eng.md
+```
+
+**Expected evidence:** documentation purpose and audience are clear, factual claims are cross-checked against canonical project sources, changed documentation surfaces are complete, relevant examples/links/builds are validated when available, and unavailable required checks are recorded as `NOT_VERIFIED`.
+
 ## Work-type matrix
 
 | Work | Primary guide | Common complements | Exclude when |
 | --- | --- | --- | --- |
-| Documentation change | Relevant domain | `test` only for executable examples or commands | No software behavior exists |
+| Documentation change | `documentation` | Relevant domain; `test` for executable examples/commands; `security` for trust-sensitive docs | No documentation artifact or documented contract changes |
+| UI copy or microcopy | `design` | `accessibility` | Users cannot observe the change |
 | Code or bug without UI | `clean` | `test`; risk may add `security` or `performance` | The surface is unchanged |
 | Backend, API, or data | `clean` | `test`, `security`; `performance` for a critical path | That layer does not exist |
 | Web, mobile, or desktop UI | `design` | `accessibility`, `clean`, `test`; risk defines the rest | Users cannot observe the change |
@@ -214,12 +230,12 @@ the repository.
 
 The first routing contract is versioned as `schemaVersion: 1`. It accepts:
 
-- `workType`: `documentation`, `code`, `bug`, `refactor`, `backend`, `api`,
+- `workType`: `documentation`, `ui-copy`, `code`, `bug`, `refactor`, `backend`, `api`,
   `api-auth`, `complete-website`, `mobile-ui`, `web-game`, `html-video`,
   `infrastructure`, `security-review`, `performance`, `accessibility`,
   `test-only`, `dependency-update`, or `release`;
 - `surfaces`: `ui`, `forms`, `api`, `auth`, `data`, `database`, `mobile`,
-  `desktop`, `game`, `video`, `ci`, `config`, or `critical-path`;
+  `desktop`, `game`, `video`, `ci`, `config`, `critical-path`, or `documentation`;
 - `risks`: `untrusted-input`, `personal-data`, `secrets`, `external-service`,
   `publication`, `critical-path`, `performance`, or `accessibility`;
 - `platforms`: `web`, `mobile`, `desktop`, `server`, `ci`, or
@@ -236,9 +252,8 @@ error.
 Every selected guide has stable reason codes such as
 `WORK_COMPLETE_WEBSITE`, `SURFACE_UI`, `RISK_UNTRUSTED_INPUT`, and
 `CHANGE_EXECUTABLE_CONFIG`. Exclusions use stable codes such as
-`NO_TRUST_BOUNDARY` and `NO_MEASURABLE_PERFORMANCE_RISK`. Documentation-only
-input records `DOCUMENTATION_DOMAIN_GUIDE_REQUIRED` instead of activating
-technical guides automatically.
+`NO_TRUST_BOUNDARY`, `NO_MEASURABLE_PERFORMANCE_RISK`, and
+`NO_DOCUMENTATION_SURFACE`.
 
 Platform signals are contextual, not automatic guide activators:
 
@@ -302,9 +317,9 @@ Verify the game loop, authoritative server, reconciliation, input, assets, fallb
 
 ### Documentation
 
-<!-- route:documentation=domain -->
+<!-- route:documentation=documentation -->
 
-`domain` means the single domain guide implicated by the change. Verify Markdown, links, paths, commands, and examples.
+Verify Markdown, links, paths, commands, and examples.
 
 ## Route changes
 

package/LOOP_ENGINEERING.md

@@ -4,6 +4,31 @@
 > technical rules remain in the guides selected through
 > [`GUIDE_ROUTER.md`](./GUIDE_ROUTER.md).
 
+## Navigation
+
+- [Protocol Applicability](#protocol-applicability)
+- [Blocking vs Non-Blocking Decisions](#blocking-vs-non-blocking-decisions)
+- [External Workflow Compatibility](#external-workflow-compatibility)
+- [Serialized Protocol Preparation](#serialized-protocol-preparation)
+- [Completion Validation & Chronology](#completion-validation-and-chronology)
+- [Post-Implementation Closure](#post-implementation-closure)
+- [Independent Completion Dimensions](#independent-completion-dimensions)
+- [Failure Taxonomy & Invariants](#failure-taxonomy-retry-and-loop-invariants)
+- [Workflow State Semantics](#workflow-state-semantics)
+- [Execution Contract](#execution-contract)
+- [Project Discovery](#project-discovery)
+- [Capability Discovery & Authority](#capability-discovery-and-on-demand-extensions)
+- [Guide Selection](#guide-selection)
+- [Design & Implementation Gates](#design-and-implementation-gates)
+- [Proportional Planning](#proportional-planning)
+- [Execution Loop](#execution-loop)
+- [Verification & Regression](#verification-and-regression)
+- [Evidence-Driven Correction](#evidence-driven-correction)
+- [Precedence & Stop Conditions](#precedence)
+- [Final Delivery](#final-delivery)
+- [Cross-Harness Continuity](#cross-harness-execution-continuity)
+- [Multi-Task Concurrent Project State](#multi-task-concurrent-project-state)
+
 ## Protocol applicability
 
 ForgeLoop is a project-local engineering protocol.
@@ -48,11 +73,11 @@ name is unknown.
 Lifecycle-owned ForgeLoop artifacts must be created or mutated only through
 the supported ForgeLoop lifecycle commands or canonical ForgeLoop APIs:
 
-- `.forgeloop/preflight.json`
-- `.forgeloop/work-state.json`
-- `.forgeloop/events.ndjson`
-- `.forgeloop/execution-receipt.json`
-- `.forgeloop/executions/<executionId>.json`
+- `.forgeloop/task-state/<taskKey>/preflight.json`
+- `.forgeloop/task-state/<taskKey>/work-state.json`
+- `.forgeloop/task-state/<taskKey>/events.ndjson`
+- `.forgeloop/task-state/<taskKey>/execution-receipt.json`
+- `.forgeloop/task-state/<taskKey>/executions/<executionId>.json`
 - completion recovery metadata
 - canonical check/evidence state
 - terminal-result lifecycle state
@@ -130,7 +155,7 @@ Recognized command dispatchers (such as `npm test`, `npm start`, `npm stop`, `np
 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
+binding in `.forgeloop/task-state/<taskKey>/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
@@ -157,7 +182,7 @@ ForgeLoop validates authority semantics, while the host defines the trust bounda
 
 ### Stale receipt recovery invariant
 
-Every recovery action returned by `forgeloop next` must be executable from the state that produced it. When work state changes legitimately after preparing a completion receipt, `forgeloop prepare-completion` refreshes the receipt and re-binds it to current state and changed paths without requiring manual deletion of `.forgeloop/execution-receipt.json`.
+Every recovery action returned by `forgeloop next` must be executable from the state that produced it. When work state changes legitimately after preparing a completion receipt, `forgeloop prepare-completion` refreshes the receipt and re-binds it to current state and changed paths without requiring manual deletion of `.forgeloop/task-state/<taskKey>/execution-receipt.json`.
 
 ### Conformance profile escalation policy
 
@@ -435,9 +460,9 @@ If the harness cannot disable a mandatory approval workflow, record
 
 ForgeLoop keeps the agent responsible for implementation while making the
 pre-implementation contract observable. Before executable changes, the target
-should contain a schema-valid `.forgeloop/current-contract.json` and a persisted
-`.forgeloop/routing-result.json`. Guide metadata can declare mandatory gates;
-those gates are recorded under `.forgeloop/gates/` and are checked by:
+should contain a schema-valid task contract (`.forgeloop/task-state/<taskKey>/contract.json`) and a persisted
+`.forgeloop/task-state/<taskKey>/routing-result.json`. Guide metadata can declare mandatory gates;
+those gates are recorded under `.forgeloop/task-state/<taskKey>/gates/` and are checked by:
 
 ```text
 forgeloop preflight
@@ -720,7 +745,7 @@ proportional phases, but:
 Resume rules are conservative: revalidate branch, HEAD, contract fingerprint,
 protocol version, and required artifacts before continuing; never rerun a
 completed destructive or publication action automatically; rerun cheap
-verification when state is stale; and clear only `.forgeloop/work-state.json`
+verification when state is stale; and clear only task work state (`.forgeloop/task-state/<taskKey>/work-state.json`)
 when abandoned state must be removed.
 
 ## Execution contract
@@ -1169,7 +1194,7 @@ from external publication.
 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
+`.forgeloop/task-state/<taskKey>/continuity.json` may record bounded granular implementation context
 such as current focus, remaining implementation work, known issues, and paths
 to inspect first.
 
@@ -1178,3 +1203,43 @@ 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.
+
+## Multi-task concurrent project state
+
+ForgeLoop supports isolated, concurrent tasks within the same repository workspace.
+Multiple active tasks can progress simultaneously without artifact collisions or state
+corruption through three fundamental protocol mechanisms:
+
+1. **Deterministic Task Namespacing**:
+   Each task is identified by a canonical string `taskId` and an immutable, filesystem-safe
+   `taskKey` derived as `SHA-256(taskId)` in 64 lowercase hexadecimal characters. All
+   task-scoped artifacts (`task.json`, `contract.json`, `routing-result.json`,
+   `preflight.json`, `work-state.json`, `events.ndjson`, `execution-receipt.json`,
+   `continuity.json`, gates, and execution records) are stored strictly under
+   `.forgeloop/task-state/<taskKey>/`. Shared repository configuration and sources
+   (`config.json`, `sources.json`) remain at `.forgeloop/`.
+
+2. **Scoped Write Claims & Conflict Prevention**:
+   Every task declares explicit project-relative directory or file path prefixes
+   (`writeClaims`) in its `task.json` descriptor.
+   - When creating a task (`forgeloop task-create --task <id> --claim <path>`),
+     ForgeLoop asserts that claimed paths have no pre-existing uncommitted changes
+     (`E_TASK_SCOPE_DIRTY`) and do not overlap with active write claims of any other
+     non-`COMPLETE` task (`E_TASK_SCOPE_CONFLICT`).
+   - Once execution begins (`EXECUTING` through `COMPLETE`), write claims are immutable
+     (`E_TASK_SCOPE_FROZEN`).
+   - At verification and completion, Git modifications are validated to ensure no changes
+     escaped the task's declared scope (`E_TASK_CHANGE_OUTSIDE_SCOPE`).
+
+3. **Per-Task Exclusive Mutex Locking**:
+   Mutating lifecycle commands (`advance`, `preflight`, `run-check`, `complete`, etc.)
+   acquire an exclusive filesystem lock at `.forgeloop/task-state/<taskKey>/.lock` using
+   atomic creation flags (`wx`). Concurrent mutations on the same task reject with
+   `E_TASK_LOCKED`. Read-only commands (`status`, `audit`, `inspect`, `continuity`) bypass
+   locking. Stale locks can be cleared with `forgeloop task-unlock --task <id> --force`.
+
+4. **Task Resolution & Legacy Migration**:
+   Commands select their target task via `--task <id>`, the `FORGELOOP_TASK` environment
+   variable, or implicit single-task fallback. If multiple active tasks exist without a
+   selector, ForgeLoop fails closed with `E_TASK_AMBIGUOUS`. Legacy ForgeLoop 1.0 single-task
+   layouts can be migrated into namespaced layout using `forgeloop task-migrate`.

package/PROTOCOL_INTEGRATION.md

@@ -124,11 +124,11 @@ The resolved CLI must match the installed project's package identity.
 
 The following protocol artifacts are strictly owned by ForgeLoop:
 
-- `.forgeloop/preflight.json`
-- `.forgeloop/work-state.json`
-- `.forgeloop/events.ndjson`
-- `.forgeloop/execution-receipt.json`
-- `.forgeloop/executions/<executionId>.json`
+- `.forgeloop/task-state/<taskKey>/preflight.json`
+- `.forgeloop/task-state/<taskKey>/work-state.json`
+- `.forgeloop/task-state/<taskKey>/events.ndjson`
+- `.forgeloop/task-state/<taskKey>/execution-receipt.json`
+- `.forgeloop/task-state/<taskKey>/executions/<executionId>.json`
 - Canonical check, evidence, and terminal-result state
 
 If the required CLI or API capability cannot be resolved:
@@ -149,7 +149,7 @@ Command verification has two explicit paths:
   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
+  `.forgeloop/task-state/<taskKey>/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`
@@ -309,3 +309,6 @@ 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.
+
+For the practical handoff and multi-tool takeover sequence, see
+[`docs/CROSS_HARNESS_CONTINUITY.md`](./docs/CROSS_HARNESS_CONTINUITY.md).

package/README.md

@@ -4,9 +4,9 @@
 
 ForgeLoop is a portable, vendor-neutral protocol for AI-assisted development
 and developer workflows. It turns an outcome into a contract, deterministic
-routing, resumable state, evidence-backed verification, recovery, and
-validator-backed completion. It is a protocol/support CLI, not an agent or LLM
-runtime.
+routing, resumable state, evidence-backed verification, recovery, cross-harness
+continuity, and validator-backed completion. It is a protocol/support CLI, not
+an agent or LLM runtime, not an agent framework, and not a graph orchestrator.
 
 The operational sources are indexed in [`DOCS_INDEX.md`](./DOCS_INDEX.md).
 [`LOOP_ENGINEERING.md`](./LOOP_ENGINEERING.md) is the canonical process;
@@ -15,6 +15,19 @@ levels and discovery; [`PROJECT_PROFILE.md`](./PROJECT_PROFILE.md) stores
 durable project facts; and [`GUIDE_ROUTER.md`](./GUIDE_ROUTER.md) selects only
 relevant guides.
 
+## Where should I start?
+
+- **New to ForgeLoop** → [`docs/GETTING_STARTED.md`](./docs/GETTING_STARTED.md)
+- **Full protocol specification** → [`LOOP_ENGINEERING.md`](./LOOP_ENGINEERING.md)
+- **Integrating an AI harness** → [`PROTOCOL_INTEGRATION.md`](./PROTOCOL_INTEGRATION.md)
+- **Continuing another harness's task** → [`docs/CROSS_HARNESS_CONTINUITY.md`](./docs/CROSS_HARNESS_CONTINUITY.md)
+- **CLI command reference** → [`docs/CLI_REFERENCE.md`](./docs/CLI_REFERENCE.md)
+- **Artifact & schema reference** → [`docs/ARTIFACT_REFERENCE.md`](./docs/ARTIFACT_REFERENCE.md)
+- **Operational recipes** → [`docs/RECIPES.md`](./docs/RECIPES.md)
+- **Troubleshooting & error codes** → [`docs/TROUBLESHOOTING.md`](./docs/TROUBLESHOOTING.md)
+- **System architecture & safety** → [`LOOP_SYSTEM_DESIGN.md`](./LOOP_SYSTEM_DESIGN.md) & [`THREAT_MODEL.md`](./THREAT_MODEL.md)
+- **Documentation index & ownership** → [`DOCS_INDEX.md`](./DOCS_INDEX.md)
+
 ## Catalog
 
 | Topic | Guide |
@@ -28,6 +41,7 @@ relevant guides.
 | Performance | [`ENG/perf-code-eng.md`](./ENG/perf-code-eng.md) |
 | Accessibility | [`ENG/accessibility-eng.md`](./ENG/accessibility-eng.md) |
 | Web games | [`ENG/games-code-design-web-eng.md`](./ENG/games-code-design-web-eng.md) |
+| Documentation quality | [`ENG/documentation-quality-eng.md`](./ENG/documentation-quality-eng.md) |
 
 Each guide declares its name, language, version, and review date in
 frontmatter. Repository validators keep the catalog and metadata synchronized.
@@ -42,8 +56,9 @@ npx @cassiomc1/forgeloop doctor
 ```
 
 The CLI installs canonical documents under `.forgeloop/kit/`, keeps small
-native discovery shims at the project root, and stores mutable contract, route,
-gate, state, event, receipt, and execution artifacts under `.forgeloop/`.
+native discovery shims at the project root, stores project-scoped
+configuration under `.forgeloop/`, and stores task-scoped protocol artifacts
+under `.forgeloop/task-state/<taskKey>/`.
 `update` preserves target-specific profile facts and locally modified files.
 
 Before npm publication, the same source checkout can be exercised without a
@@ -66,26 +81,28 @@ request → discovery → contract → routing → plan → execution
               └──── evidence-only rejection / next cycle
 ```
 
-The harness writes a schema-valid `.forgeloop/current-contract.json`, required
-gate artifacts, and routing. `preflight` must return `PREFLIGHT_READY` before
-implementation. ForgeLoop then records an append-only event ledger and protects
-the lifecycle with contract, route, repository, and artifact fingerprints.
+The harness writes a schema-valid task contract under
+`.forgeloop/task-state/<taskKey>/contract.json`, required gate artifacts, and
+routing. `preflight` must return `PREFLIGHT_READY` before implementation.
+ForgeLoop then records an append-only event ledger and protects the lifecycle
+with contract, route, repository, and artifact fingerprints.
 
 Typical local commands are:
 
 ```bash
-forgeloop route --work complete-website --surface ui --risk untrusted-input
-forgeloop activate
-forgeloop preflight --json
-forgeloop next --json
-forgeloop advance --to PLANNED
-forgeloop advance --to EXECUTING
-forgeloop advance --to VERIFYING
-forgeloop prepare-completion --json
-forgeloop run-check --json --id tests --requirement tests -- npm test
-forgeloop advance --to REVIEWING
-forgeloop audit --json
-forgeloop complete --json
+forgeloop task-create --task example-task --claim src --claim tests --json
+forgeloop route --task example-task --work complete-website --surface ui --risk untrusted-input
+forgeloop activate --task example-task
+forgeloop preflight --task example-task --json
+forgeloop next --task example-task --json
+forgeloop advance --task example-task --to PLANNED
+forgeloop advance --task example-task --to EXECUTING
+forgeloop advance --task example-task --to VERIFYING
+forgeloop prepare-completion --task example-task --json
+forgeloop run-check --task example-task --json --id tests --requirement tests -- npm test
+forgeloop advance --task example-task --to REVIEWING
+forgeloop audit --task example-task --json
+forgeloop complete --task example-task --json
 ```
 
 `advance` changes protocol phase only; it never runs target commands.
@@ -103,6 +120,42 @@ falling back to discovery. Delegation artifacts are required only when
 delegation is present in the execution history; ForgeLoop does not provide a
 graph runtime, agent runtime, or hidden prompt store.
 
+### Cross-harness continuity
+
+ForgeLoop preserves task state when switching between AI coding tools, IDEs, or terminals:
+
+```bash
+forgeloop status --task example-task --json
+forgeloop continuity --task example-task --json
+forgeloop reconcile-continuity --task example-task --json
+forgeloop next --task example-task --json
+```
+
+See [`docs/CROSS_HARNESS_CONTINUITY.md`](./docs/CROSS_HARNESS_CONTINUITY.md) for full handoff and recovery procedures.
+
+### Multi-task concurrent project state
+
+ForgeLoop supports isolated, concurrent tasks within the same repository via deterministic SHA-256 namespacing, per-task mutex locking, and write-claim conflict detection:
+
+```bash
+# Create an isolated task claiming specific directories
+forgeloop task-create --task auth-feature --claim src/auth --claim tests/auth --json
+
+# List active and completed tasks
+forgeloop task-list --json
+
+# Run standard lifecycle commands targeting the task
+forgeloop route --task auth-feature --work clean-code --surface backend
+forgeloop preflight --task auth-feature --json
+forgeloop advance --task auth-feature --to EXECUTING
+forgeloop complete --task auth-feature --json
+
+# Migrate legacy 1.0 single-task layout
+forgeloop task-migrate --json
+```
+
+See [`docs/CLI_REFERENCE.md`](./docs/CLI_REFERENCE.md) and [`LOOP_SYSTEM_DESIGN.md`](./LOOP_SYSTEM_DESIGN.md) for architecture details.
+
 ## Architecture flow
 
 The canonical source is [`docs/forgeloop-flow.mmd`](./docs/forgeloop-flow.mmd),
@@ -110,9 +163,7 @@ and the committed render is [`docs/assets/forgeloop-flow.svg`](./docs/assets/for
 The broader architecture and boundaries are in
 [`LOOP_SYSTEM_DESIGN.md`](./LOOP_SYSTEM_DESIGN.md).
 
-<p align="center">
-  <img src="./docs/assets/forgeloop-flow.svg" alt="ForgeLoop evidence-first engineering flow" width="100%" />
-</p>
+![ForgeLoop evidence-first engineering flow](./docs/assets/forgeloop-flow.svg)
 
 Text-only fallback: discovery creates the contract and route; required gates
 and `PREFLIGHT_READY` authorize execution; verification creates structured
@@ -189,15 +240,6 @@ configuration file, never in Git, `.forgeloop/kit/PROJECT_PROFILE.md`, or
 copied instruction files. ForgeLoop does not vendor Qwen code or install it
 through `init`, `update`, or `doctor`.
 
-## Cross-harness continuity
-
-ForgeLoop can optionally persist bounded execution-continuity context for a
-resumable task so another compatible harness can reconcile the current checkout
-and continue without replacing the task contract. Continuity is operational
-context only; it is never verification evidence or authority. See
-[`EXECUTION_STATE.md`](./EXECUTION_STATE.md) and
-[`LOOP_ENGINEERING.md`](./LOOP_ENGINEERING.md).
-
 ## Release and maintenance
 
 The release workflow uses [npm trusted publishing](https://docs.npmjs.com/trusted-publishers)
@@ -236,16 +278,17 @@ src/                    npm CLI and protocol implementation
 schemas/                versioned artifact schemas
 ENG/                    package-source engineering guides
 docs/forgeloop-flow.mmd canonical Mermaid source
-docs/assets/             committed diagram render
+docs/assets/            committed diagram render
 scripts/                checks, renderer, release identity, CI notes
 tests/                  Node and Python regression coverage
-.forgeloop/              local protocol ledger and mutable artifacts
-DOCS_INDEX.md            documentation map and ownership boundaries
+.forgeloop/             project-scoped ForgeLoop configuration
+.forgeloop/task-state/  isolated live task protocol state
+DOCS_INDEX.md           documentation map and ownership boundaries
 ```
 
-The source repository keeps canonical documents at the root. A bootstrapped
-target uses the hidden kit layout; mutable protocol artifacts remain directly
-under `.forgeloop/`.
+Project-scoped configuration remains under `.forgeloop/`.
+Task-scoped mutable protocol state is stored under
+`.forgeloop/task-state/<taskKey>/`.
 
 For document ownership, guide routing, capability degradation, and integration
 details, start at [`DOCS_INDEX.md`](./DOCS_INDEX.md).