@cassiomc1/forgeloop 1.12.0 → 1.13.0

package/THIRD_PARTY_NOTICES.md

@@ -1,8 +1,9 @@
 # Third-Party Notices
 
 This file records provenance and reuse boundaries for the external URLs cited
-by the README and guides. A citation is a reference, not a declaration that a
-resource is a dependency, bundled material, or available for reuse.
+by the README and guides. A citation is a reference, not by itself a
+declaration that a resource is a dependency, bundled material, or available
+for reuse.
 
 ## Collection license
 
@@ -100,11 +101,12 @@ dependencies, version, and distribution conditions before adoption.
 ### Runtime and validator boundary
 
 The distributed CLI and repository validators use Node.js and Python standard
-libraries plus the JSON Schema documents shipped in this repository. No
-third-party runtime package, agent, provider, plugin, remote trace service, or
-model is bundled or installed by `ForgeLoop`. A future host that adds one of
-those capabilities must review its own license, dependency tree, credentials,
-network behavior, and distribution terms separately.
+libraries plus the JSON Schema documents shipped in this repository. The core
+CLI has one approved runtime package, `smol-toml`, for structural Cargo
+manifest parsing; it is not used as an agent, provider, plugin, remote trace
+service, or model. Every future runtime capability must review its own license,
+dependency tree, credentials, network behavior, and distribution terms
+separately.
 
 ## Visual, gradient, and gallery references
 
@@ -213,6 +215,16 @@ or make its prescriptive examples universal.
 
 ## Runtime dependencies with upstream notices
 
+### smol-toml 1.8.0
+
+- Project/source: [squirrelchat/smol-toml](https://github.com/squirrelchat/smol-toml).
+- License declared by the upstream package: BSD-3-Clause.
+- Use in this collection: bounded structural parsing of Rust `Cargo.toml`
+  manifests without executing Cargo or evaluating project code.
+- Boundary: the exact version is pinned in `package.json` and
+  `package-lock.json`; the dependency has no role in routing authority beyond
+  the parser result and is not exposed as a public ForgeLoop integration.
+
 ### Microsoft tgrep
 
 - Project: [microsoft/tgrep](https://github.com/microsoft/tgrep).

package/completions/_forgeloop

@@ -42,7 +42,7 @@ case $words[2] in
   inspect) _arguments '--contract-file[current JSON contract used for freshness comparison]' '--help[show this help]' '--json[emit structured output as JSON]' '--path[target project directory (default: current directory)]' '--task[task ID to operate on (when omitted, resolved from context or single active task)]' '--version[show the installed package version]' ;;
   metrics) _arguments '--help[show this help]' '--json[emit trajectory metrics as JSON]' '--path[target project directory (default: current directory)]' '--task[task ID to operate on (when omitted, resolved from context or single active task)]' '--version[show the installed package version]' ;;
   migrate-protocol) _arguments '--dry-run[show migration actions without writing or deleting artifacts]' '--help[show this help]' '--json[emit structured migration result as JSON]' '--path[target project directory (default: current directory)]' '--to[target supported protocol version]' '--version[show the installed package version]' ;;
-  next) _arguments '--compact[emit a bounded next-action projection]' '--help[show this help]' '--json[emit structured output as JSON]' '--path[target project directory (default: current directory)]' '--task[task ID to operate on (when omitted, resolved from context or single active task)]' '--version[show the installed package version]' ;;
+  next) _arguments '--compact[emit a bounded next-action projection]' '--explain[include bounded read-only blocker and recovery explanation]' '--help[show this help]' '--json[emit structured output as JSON]' '--path[target project directory (default: current directory)]' '--task[task ID to operate on (when omitted, resolved from context or single active task)]' '--version[show the installed package version]' ;;
   policy) _arguments '--help[show this help]' '--json[emit structured output as JSON]' '--path[target project directory (default: current directory)]' '--task[task ID to operate on (when omitted, resolved from context or single active task)]' '--version[show the installed package version]' ;;
   policy-diff) _arguments '--after[path to after policy JSON]' '--before[path to before policy JSON]' '--help[show this help]' '--json[emit structured output as JSON]' '--path[target project directory (default: current directory)]' '--task[task ID to operate on (when omitted, resolved from context or single active task)]' '--version[show the installed package version]' ;;
   policy-discover) _arguments '--help[show this help]' '--json[emit structured output as JSON]' '--path[target project directory (default: current directory)]' '--version[show the installed package version]' '--write[persist discovered policy to .forgeloop/policy/discovery.json]' ;;
@@ -74,8 +74,8 @@ case $words[2] in
   run-check) _arguments '--[exact command argv to classify, execute, and attest]' '--details[additional structured check details]' '--help[show this help]' '--id[stable check identifier]' '--json[emit structured output as JSON]' '--path[target project directory (default: current directory)]' '--requirement[completion requirement covered by the check]' '--scope-ref[current verification-scope.json to bind to execution evidence]' '--task[task ID to operate on (when omitted, resolved from context or single active task)]' '--timeout-ms[maximum command duration before termination]' '--version[show the installed package version]' ;;
   search) _arguments '--after-context[lines of context after matches]' '--before-context[lines of context before matches]' '--context[lines of context before and after matches]' '--files-with-matches[return matching file paths only]' '--fixed-strings[treat the pattern as a literal string]' '--glob[include files matching a glob]' '--help[show this help]' '--ignore-case[search case-insensitively]' '--json[emit normalized provider-neutral search JSON]' '--max-count[maximum matches per file]' '--path[target project directory (default: current directory)]' '--smart-case[use case-insensitive search only for lowercase patterns]' '--stats[include observed native search statistics]' '--type[include files of a tgrep type]' '--version[show the installed package version]' '--word-regexp[match whole words only]' ;;
   status) _arguments '--contract-file[current JSON contract used for freshness comparison]' '--help[show this help]' '--json[emit structured output as JSON]' '--path[target project directory (default: current directory)]' '--task[task ID to operate on (when omitted, resolved from context or single active task)]' '--version[show the installed package version]' ;;
-  task-create) _arguments '--claim[scoped file path or directory prefix claimed for mutation]' '--contract-file[path to initial contract file]' '--help[show this help]' '--json[emit structured output as JSON]' '--path[target project directory (default: current directory)]' '--task[task ID to operate on (when omitted, resolved from context or single active task)]' '--version[show the installed package version]' ;;
-  task-list) _arguments '--help[show this help]' '--json[emit structured output as JSON]' '--path[target project directory (default: current directory)]' '--version[show the installed package version]' ;;
+  task-create) _arguments '--claim[scoped file path or directory prefix claimed for mutation]' '--contract-file[path to initial contract file]' '--help[show this help]' '--json[emit structured output as JSON]' '--path[target project directory (default: current directory)]' '--preset[bounded contract preset: documentation, bug, feature, or release]' '--preview[preview the contract without creating lifecycle state]' '--task[task ID to operate on (when omitted, resolved from context or single active task)]' '--version[show the installed package version]' ;;
+  task-list) _arguments '--active[only return healthy tasks with active ownership and a non-terminal phase]' '--help[show this help]' '--json[emit structured output as JSON]' '--limit[maximum tasks to return]' '--offset[number of sorted tasks to skip]' '--path[target project directory (default: current directory)]' '--phase[only return tasks in this lifecycle phase]' '--version[show the installed package version]' ;;
   task-lock-status) _arguments '--help[show this help]' '--json[emit structured output as JSON]' '--path[target project directory (default: current directory)]' '--task[task ID to operate on (when omitted, resolved from context or single active task)]' '--version[show the installed package version]' ;;
   task-migrate) _arguments '--dry-run[show planned migration actions without moving files]' '--help[show this help]' '--json[emit structured output as JSON]' '--path[target project directory (default: current directory)]' '--version[show the installed package version]' ;;
   task-recover) _arguments '--acknowledge-recovery[acknowledge release of claims for a STALE or ABANDONED task (required; not host attestation)]' '--help[show this help]' '--json[emit structured output as JSON]' '--operator-authorized[deprecated alias for --acknowledge-recovery; does not attest operator authority]' '--path[target project directory (default: current directory)]' '--task[task ID to operate on (when omitted, resolved from context or single active task)]' '--version[show the installed package version]' ;;

package/completions/forgeloop.bash

@@ -140,7 +140,7 @@ _forgeloop() {
     inspect) COMPREPLY=( $(compgen -W '--contract-file --help --json --path --task --version' -- "$cur") );;
     metrics) COMPREPLY=( $(compgen -W '--help --json --path --task --version' -- "$cur") );;
     migrate-protocol) COMPREPLY=( $(compgen -W '--dry-run --help --json --path --to --version' -- "$cur") );;
-    next) COMPREPLY=( $(compgen -W '--compact --help --json --path --task --version' -- "$cur") );;
+    next) COMPREPLY=( $(compgen -W '--compact --explain --help --json --path --task --version' -- "$cur") );;
     policy) COMPREPLY=( $(compgen -W '--help --json --path --task --version' -- "$cur") );;
     policy-diff) COMPREPLY=( $(compgen -W '--after --before --help --json --path --task --version' -- "$cur") );;
     policy-discover) COMPREPLY=( $(compgen -W '--help --json --path --version --write' -- "$cur") );;
@@ -172,8 +172,8 @@ _forgeloop() {
     run-check) COMPREPLY=( $(compgen -W '-- --details --help --id --json --path --requirement --scope-ref --task --timeout-ms --version' -- "$cur") );;
     search) COMPREPLY=( $(compgen -W '--after-context --before-context --context --files-with-matches --fixed-strings --glob --help --ignore-case --json --max-count --path --smart-case --stats --type --version --word-regexp' -- "$cur") );;
     status) COMPREPLY=( $(compgen -W '--contract-file --help --json --path --task --version' -- "$cur") );;
-    task-create) COMPREPLY=( $(compgen -W '--claim --contract-file --help --json --path --task --version' -- "$cur") );;
-    task-list) COMPREPLY=( $(compgen -W '--help --json --path --version' -- "$cur") );;
+    task-create) COMPREPLY=( $(compgen -W '--claim --contract-file --help --json --path --preset --preview --task --version' -- "$cur") );;
+    task-list) COMPREPLY=( $(compgen -W '--active --help --json --limit --offset --path --phase --version' -- "$cur") );;
     task-lock-status) COMPREPLY=( $(compgen -W '--help --json --path --task --version' -- "$cur") );;
     task-migrate) COMPREPLY=( $(compgen -W '--dry-run --help --json --path --version' -- "$cur") );;
     task-recover) COMPREPLY=( $(compgen -W '--acknowledge-recovery --help --json --operator-authorized --path --task --version' -- "$cur") );;

package/completions/forgeloop.fish

@@ -258,6 +258,7 @@ complete -c forgeloop -f -n '__fish_seen_subcommand_from migrate-protocol' -l 'p
 complete -c forgeloop -f -n '__fish_seen_subcommand_from migrate-protocol' -l 'to' -d 'target supported protocol version'
 complete -c forgeloop -f -n '__fish_seen_subcommand_from migrate-protocol' -l 'version' -d 'show the installed package version'
 complete -c forgeloop -f -n '__fish_seen_subcommand_from next' -l 'compact' -d 'emit a bounded next-action projection'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from next' -l 'explain' -d 'include bounded read-only blocker and recovery explanation'
 complete -c forgeloop -f -n '__fish_seen_subcommand_from next' -l 'help' -d 'show this help'
 complete -c forgeloop -f -n '__fish_seen_subcommand_from next' -l 'json' -d 'emit structured output as JSON'
 complete -c forgeloop -f -n '__fish_seen_subcommand_from next' -l 'path' -d 'target project directory (default: current directory)'
@@ -512,11 +513,17 @@ complete -c forgeloop -f -n '__fish_seen_subcommand_from task-create' -l 'contra
 complete -c forgeloop -f -n '__fish_seen_subcommand_from task-create' -l 'help' -d 'show this help'
 complete -c forgeloop -f -n '__fish_seen_subcommand_from task-create' -l 'json' -d 'emit structured output as JSON'
 complete -c forgeloop -f -n '__fish_seen_subcommand_from task-create' -l 'path' -d 'target project directory (default: current directory)'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from task-create' -l 'preset' -d 'bounded contract preset: documentation, bug, feature, or release'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from task-create' -l 'preview' -d 'preview the contract without creating lifecycle state'
 complete -c forgeloop -f -n '__fish_seen_subcommand_from task-create' -l 'task' -d 'task ID to operate on (when omitted, resolved from context or single active task)'
 complete -c forgeloop -f -n '__fish_seen_subcommand_from task-create' -l 'version' -d 'show the installed package version'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from task-list' -l 'active' -d 'only return healthy tasks with active ownership and a non-terminal phase'
 complete -c forgeloop -f -n '__fish_seen_subcommand_from task-list' -l 'help' -d 'show this help'
 complete -c forgeloop -f -n '__fish_seen_subcommand_from task-list' -l 'json' -d 'emit structured output as JSON'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from task-list' -l 'limit' -d 'maximum tasks to return'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from task-list' -l 'offset' -d 'number of sorted tasks to skip'
 complete -c forgeloop -f -n '__fish_seen_subcommand_from task-list' -l 'path' -d 'target project directory (default: current directory)'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from task-list' -l 'phase' -d 'only return tasks in this lifecycle phase'
 complete -c forgeloop -f -n '__fish_seen_subcommand_from task-list' -l 'version' -d 'show the installed package version'
 complete -c forgeloop -f -n '__fish_seen_subcommand_from task-lock-status' -l 'help' -d 'show this help'
 complete -c forgeloop -f -n '__fish_seen_subcommand_from task-lock-status' -l 'json' -d 'emit structured output as JSON'

package/docs/AGENT_PROTOCOL_SUMMARY.md

@@ -7,7 +7,7 @@
 ForgeLoop is a portable protocol and support CLI for verifiable engineering workflows. It records and validates task state, contracts, routing, checks, evidence, continuity, and optional code attestations. It does not become an agent scheduler, delegation service, source-control authority, or secret manager.
 
 Protocol version: 1
-Package version: 1.12.0
+Package version: 1.13.0
 
 ## Canonical loop
 
@@ -19,6 +19,32 @@ Package version: 1.12.0
 6. Run forgeloop complete; accept completion only when the validator returns VALID.
 7. Run forgeloop next again and follow the returned lifecycle action to a terminal state or an explicit blocker.
 
+## Project evidence and guide routing
+
+- The canonical guide registry is `src/config/guides.json`; the .NET
+  specialist has guide ID `dotnet` and resolves to
+  `ENG/dotnet-aspnetcore-development-eng.md`.
+- Project evidence schema v1 recognizes
+  structurally parsed Flutter, SDK-style .NET, Node.js, Rust, C, C++, Java,
+  SQL, Go, TypeScript, PHP, and Swift project evidence. SQL remains a bounded
+  owned-file overlay, while same-root language identities compose. ASP.NET Core
+  and ABP are conditional overlays recorded as reasons on `dotnet`; they
+  are not standalone guide IDs, and route validation requires each overlay to
+  include `dotnet`.
+- Project detection is bounded by 256
+  manifests, 64 solution files,
+  1048576 bytes per manifest,
+  256 supporting source files,
+  524288 bytes per source file,
+  4096 visited directories, and
+  20000 visited entries. It skips
+  symlinks and configured generated/vendor directories; exhausted budgets fail
+  closed rather than producing unbounded discovery.
+- Task ownership discovery is a separate exhaustive operation. Task-list
+  filters and pagination project the validated discovery result and do not
+  remove ledger or recovery evidence. See `GUIDE_ROUTER.md` and
+  `docs/CLI_REFERENCE.md` for the operator-facing contracts.
+
 ## Adaptive execution profiles
 
 `complianceMode` controls how strongly project policy is enforced. The
@@ -117,6 +143,33 @@ Phases: RECEIVED, DISCOVERING, CONTRACT_READY, ROUTED, DESIGNING, PLANNED, EXECU
 Protocol v1, schema v1, and Integration API v1 remain independent of these
 capability-family versions.
 
+## Guide registry
+
+| Guide | Path | Installable |
+| --- | --- | --- |
+| premium | ENG/premium-sites-studio-eng.md | yes |
+| clean | ENG/clean-code-eng.md | yes |
+| test | ENG/test-code-eng.md | yes |
+| security | ENG/sec-code-eng.md | yes |
+| design | ENG/design-code-eng.md | yes |
+| taste | ENG/taste-frontend-eng.md | yes |
+| performance | ENG/perf-code-eng.md | yes |
+| accessibility | ENG/accessibility-eng.md | yes |
+| games | ENG/games-code-design-web-eng.md | yes |
+| documentation | ENG/documentation-quality-eng.md | yes |
+| flutter | ENG/flutter-development-eng.md | yes |
+| dotnet | ENG/dotnet-aspnetcore-development-eng.md | yes |
+| nodejs | ENG/nodejs-backend-development-eng.md | yes |
+| rust | ENG/rust-development-eng.md | yes |
+| c | ENG/c-development-eng.md | yes |
+| cpp | ENG/cpp-development-eng.md | yes |
+| java | ENG/java-development-eng.md | yes |
+| sql | ENG/sql-development-eng.md | yes |
+| go | ENG/go-development-eng.md | yes |
+| typescript | ENG/typescript-development-eng.md | yes |
+| php | ENG/php-development-eng.md | yes |
+| swift | ENG/swift-development-eng.md | yes |
+
 ## Public artifact registry
 
 | Key | Scope | Path | Schema | Trust role |
@@ -223,7 +276,7 @@ capability-family versions.
 | complete | MUTATING | Evaluates verification receipt coverage, gates, and ledger integrity to authorize task completion. |
 | next | READ_ONLY | Returns deterministic next-action guidance and command recommendations based on active state. |
 | preflight | MUTATING | Evaluates pre-implementation contract, routing, and gates; synchronizes work state when READY. |
-| reconcile-closure | MUTATING | Refreshes the work-state checkpoint of an EXECUTING task whose objective is already satisfied in the current repository, after contract-bound executed evidence, so canonical completion can proceed. |
+| reconcile-closure | MUTATING | Refreshes the work-state checkpoint of an EXECUTING, VERIFYING, or REVIEWING task whose objective is already satisfied in the current repository, after contract-bound executed evidence, so canonical completion can proceed. |
 | record-decision-criterion | MUTATING | Records an append-only decision settlement criterion bound to the active contract fingerprint. |
 | record-diagnosis | MUTATING | Records an append-only diagnosis event or structured diagnostic case in the lifecycle event ledger. |
 | record-hypothesis-disposition | MUTATING | Records an evidence-bound hypothesis disposition update in the lifecycle event ledger. |

package/docs/CLI_REFERENCE.md

@@ -838,7 +838,7 @@ Updates the managed instruction kit to match the current ForgeLoop package versi
 
 Calculates and persists deterministic engineering guide routing.
 
-- **Purpose**: Selects relevant technical guides (e.g. `clean`, `test`, `security`, `design`) from declared work attributes and bounded structural project evidence such as an affected Flutter SDK dependency.
+- **Purpose**: Selects relevant technical guides (e.g. `clean`, `test`, `security`, `design`) from declared work attributes and bounded structural project evidence such as an affected Flutter SDK dependency, supported .NET project, confirmed Node.js backend runtime, valid Rust Cargo package/workspace, recognized C/C++, Java, Go, TypeScript, PHP, or Swift project, or owned SQL artifact. ASP.NET Core and ABP are conditional reasons on the `dotnet` specialist, not standalone guides; SQL is a host-project overlay.
 - **When to use**: During discovery before preflight.
 - **Mutation**: Writes `.forgeloop/task-state/<taskKey>/routing-result.json`.
 - **Options**:
@@ -982,6 +982,7 @@ Computes the deterministic next action required by the protocol.
 - `--path <directory>`: target project directory (default: current directory)
 - `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
 - `--compact`: emit a bounded next-action projection
+- `--explain`: include bounded read-only blocker and recovery explanation
 - `--json`: emit structured output as JSON
 
 <!-- END FORGELOOP GENERATED: cli:next:options -->
@@ -1970,12 +1971,12 @@ Clears canonical work-state checkpoint for the current task.
 
 ### `reconcile-closure`
 
-Reconciles the checkpoint of an EXECUTING task whose objective is already satisfied in the current repository.
+Reconciles the checkpoint of an EXECUTING, VERIFYING, or REVIEWING task whose objective is already satisfied in the current repository.
 
-- **Purpose**: Refresh the work-state repository fingerprint of a stale EXECUTING task after repository movement, using executed contract-bound evidence that the objective is present, so the canonical completion pipeline can close it.
-- **When to use**: When a task is stuck in EXECUTING with `E_REPOSITORY_CHANGED` / `E_STATE_REVALIDATION_REQUIRED` and its objective was already satisfied by other changes in the current repository.
-- **Mutation**: Appends a `CHECKPOINT_RECONCILED` ledger event (previous/current repository fingerprints plus evidence) and refreshes the work-state repository fingerprint. Phase stays EXECUTING; claims release only through canonical `COMPLETE`.
-- **Safety Note**: Refuses non-EXECUTING tasks, fresh checkpoints, contract or artifact drift, invalid ledgers, unknown requirements, and failing evidence.
+- **Purpose**: Refresh the work-state repository fingerprint of a stale EXECUTING, VERIFYING, or REVIEWING task after repository movement, using executed contract-bound evidence that the objective is present, so the canonical completion pipeline can close it.
+- **When to use**: When a task is stuck in EXECUTING, VERIFYING, or REVIEWING with `E_REPOSITORY_CHANGED` / `E_STATE_REVALIDATION_REQUIRED` and its objective was already satisfied by other changes in the current repository. A REVIEWING task also needs authorized completion recovery.
+- **Mutation**: Appends a `CHECKPOINT_RECONCILED` ledger event (previous/current repository fingerprints plus evidence) and refreshes the work-state repository fingerprint. The phase stays unchanged until the canonical pipeline advances it; claims release only through canonical `COMPLETE`.
+- **Safety Note**: Refuses other phases, fresh checkpoints, contract or artifact drift, invalid ledgers, unknown requirements, and failing evidence.
 - **Options**:
 
 <!-- BEGIN FORGELOOP GENERATED: cli:reconcile-closure:options -->
@@ -2016,6 +2017,8 @@ Initializes a new isolated task namespace with write claims and contract.
 - `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
 - `--claim <path>`: scoped file path or directory prefix claimed for mutation (repeatable)
 - `--contract-file <path>`: path to initial contract file
+- `--preset <name>`: bounded contract preset: documentation, bug, feature, or release
+- `--preview`: preview the contract without creating lifecycle state
 - `--json`: emit structured output as JSON
 
 <!-- END FORGELOOP GENERATED: cli:task-create:options -->
@@ -2034,6 +2037,12 @@ Initializes a new isolated task namespace with write claims and contract.
 
   `--contract-file` points to a contract JSON that is validated and copied into the task namespace.
 
+  Use `--preset documentation|bug|feature|release --preview` for a bounded,
+  read-only contract proposal. Preview validates claims and creates no task
+  namespace or project-claims lock; repeat without `--preview` after reviewing
+  the proposal. Presets record unresolved decisions when concrete deliverables
+  are not supplied and do not publish or deploy release artifacts.
+
 ### `task-list`
 
 Lists all tasks discovered in `.forgeloop/task-state/`.
@@ -2045,14 +2054,27 @@ Lists all tasks discovered in `.forgeloop/task-state/`.
 <!-- BEGIN FORGELOOP GENERATED: cli:task-list:options -->
 
 - `--path <directory>`: target project directory (default: current directory)
+- `--phase <phase>`: only return tasks in this lifecycle phase
+- `--active`: only return healthy tasks with active ownership and a non-terminal phase
+- `--limit <number>`: maximum tasks to return
+- `--offset <number>`: number of sorted tasks to skip
 - `--json`: emit structured output as JSON
 
 <!-- END FORGELOOP GENERATED: cli:task-list:options -->
 
+  Results are sorted by task ID. `--phase` and `--active` filter the
+  presentation only; ownership and corruption checks still run for every
+  discovered task before filtering. `--limit` and `--offset` provide bounded
+  pagination and return `total` and `hasMore` in JSON. Listing never removes
+  ledger or recovery evidence. Discovery itself is exhaustive for valid task
+  namespaces because ownership and conflict correctness must not depend on a
+  page limit.
+
 - **Example**:
 
   ```bash
   forgeloop task-list --json
+  forgeloop task-list --active --limit 20 --offset 0 --json
   ```
 
 ### `task-show`

package/docs/DOCUMENTATION_GUIDE.md

@@ -79,7 +79,8 @@ generated Markdown regions (<!-- BEGIN FORGELOOP GENERATED: ... -->)
     ↓
 semantic conformance checks (scripts/validate_documentation_conformance.mjs)
     ↓
-cross-platform CI (.github/workflows/docs-quality.yml)
+documentation validation (.github/workflows/docs.yml) and the PR aggregator
+(.github/workflows/pr-core.yml)
 ```
 
 ### Provenance Mapping Table

package/docs/GETTING_STARTED.md

@@ -49,11 +49,61 @@ forgeloop next --task task-contact-form-001 --compact --json
 forgeloop task-show --task task-contact-form-001 --compact --json
 ```
 
+When the task shape is known but a full contract has not been written yet,
+use a bounded preset preview. Preview is read-only and records unresolved
+decisions instead of guessing project facts:
+
+```bash
+forgeloop task-create --task task-contact-form-001 \
+  --claim src/components --claim tests \
+  --preset feature --preview --json
+```
+
+After reviewing the proposed contract, repeat the command without
+`--preview` to create the namespace and persist the same validated contract.
+The supported presets are `documentation`, `bug`, `feature`, and `release`.
+The release preset retains an independently verified publication requirement;
+it does not publish or deploy anything.
+
+For a bounded explanation of a blocked or recovery-sensitive next action, opt
+in with `--explain`. The explanation is read-only and derived from canonical
+reason codes and artifact references:
+
+```bash
+forgeloop next --task task-contact-form-001 --explain --json
+```
+
 These commands do not bypass contracts, gates, verification, provenance,
 lifecycle phases, or validator-backed completion. Usage telemetry is optional,
 never estimated, and never verification evidence; `efficiency --task` compares
 only against a metadata-compatible local baseline.
 
+### Project-aware guide routing
+
+ForgeLoop selects specialist context from bounded structural evidence in the
+affected project scope. A parsed `pubspec.yaml` with
+`dependencies.flutter.sdk: flutter` selects `flutter`. A parsed SDK-style
+`*.csproj`, `*.fsproj`, or `*.vbproj` using the supported .NET SDK allowlist
+selects the single `dotnet` guide. Web/Razor/Blazor or
+`Microsoft.AspNetCore.App` evidence adds an ASP.NET Core routing reason, and a
+`Volo.Abp.*` package reference adds an ABP routing reason; neither overlay is a
+standalone guide ID, and each requires `dotnet` in project evidence.
+
+Bounded structural inspectors also recognize Go modules/workspaces, valid
+TypeScript configs, Composer/PHP projects, Java Maven/Gradle/Bazel roots,
+SwiftPM/Xcode/native Swift roots, and explicit C/C++ build/source evidence.
+Meaningful SQL migrations and schemas are scoped overlays. Build, compiler,
+package-manager, database, lockfile, generated, and vendor artifacts are not
+executed or promoted beyond their documented evidence contract.
+
+Mentions in prose, source snippets, Dockerfiles, lockfiles, package names,
+malformed manifests, and unrelated monorepo roots are insufficient. Mixed
+Flutter/.NET roots stay isolated. Shared MSBuild/NuGet files apply only to
+descendant confirmed .NET projects, and `.sln`/`.slnx` claims use exact
+membership. Discovery skips symlinks and is bounded; see
+[`GUIDE_ROUTER.md`](../GUIDE_ROUTER.md) for the exact allowlist, reason codes,
+and numeric limits.
+
 ---
 
 ## 2. Prerequisites
@@ -395,8 +445,17 @@ forgeloop complete --task auth-feature --json
 
 # Inspect active tasks
 forgeloop task-list --json
+
+# Filter and page the deterministic projection
+forgeloop task-list --phase EXECUTING --limit 20 --offset 0 --json
+forgeloop task-list --active --limit 20 --offset 20 --json
 ```
 
+Task discovery is exhaustive for ownership and conflict correctness. The
+`--phase` and `--active` options filter the presentation after validation;
+`--limit` and `--offset` page the sorted result and JSON includes `total` and
+`hasMore`. Listing is read-only and never removes ledger or recovery evidence.
+
 ---
 
 ## 6. What ForgeLoop Creates

package/docs/PACKAGE_CONTENTS.md

@@ -11,8 +11,9 @@ part of the consumer tarball.
 
 The package exposes the `forgeloop` executable from `src/cli.js` and the
 `@cassiomc1/forgeloop/integration` subpath from `src/integration.js`, with its
-declaration file. The package has no runtime dependencies and requires Node.js
-20 or newer.
+declaration file. The package has the approved exact `smol-toml` runtime
+dependency for bounded Cargo manifest parsing and requires Node.js 20 or
+newer.
 
 ## Included files
 
@@ -28,10 +29,16 @@ The published tarball includes the following consumer-facing groups:
   `src/repository-index/tgrep-manifest.json`; native engine binaries are
   provisioned outside the npm tarball.
 - **Specialist guidance:** every registered consumer guide under `ENG/`,
-  including `ENG/flutter-development-eng.md`, ships with the guide registry
-  and is resolved from a package-local path. The Flutter specialist is
-  selected only for an affected root with the structural SDK dependency
-  signal; the package does not install or invoke Flutter tooling.
+  including `ENG/flutter-development-eng.md`,
+  `ENG/dotnet-aspnetcore-development-eng.md`,
+  `ENG/nodejs-backend-development-eng.md`,
+  `ENG/rust-development-eng.md`, and the C, C++, Java, SQL, Go, TypeScript,
+  PHP, and Swift specialists, ships with the guide registry and is resolved
+  from package-local paths. Specialists are selected only from their bounded
+  structural primary evidence; SQL remains a scoped host-project overlay.
+  ASP.NET Core and ABP are conditional routing overlays on the `dotnet` guide,
+  not additional package guides. The package does not install or invoke
+  framework, compiler, build, package-manager, or database tooling.
 - **Initialization material:** the root protocol and integration documents,
   legal notices, the target profile template, and every path listed by
   `src/core/templates.js`. These files are read by `init` and `update`, so
@@ -44,7 +51,8 @@ The published tarball includes the following consumer-facing groups:
   generated local repositories and measurements are not.
 - **User documentation:** the getting-started, integration, CLI, artifact,
   Repository Index, Persistent Search Transport, troubleshooting, release,
-  package-boundary, and related reference pages.
+  package-boundary, and related reference pages, together with the
+  machine-readable documentation and protocol indexes and `CONTRIBUTING.md`.
   The advisory-context and Ripwire adapter guides ship with the corresponding
   public integration surface.
   The typed diagram sources, generated HTML/SVG/receipt artifacts, and
@@ -72,13 +80,17 @@ The tarball intentionally omits repository-only material:
 - the repository README hero PNG, which is a GitHub-only asset. The packaged
   README remains intentionally text-first around that relative repository
   image reference.
+- the execution PoC, its audit, and its evidence package. Packaged README and
+  index links to this repository-only material use GitHub URLs so they remain
+  truthful for npm consumers.
 
-The package test checks both required paths and these exclusion classes. It
+The package test checks all registered guide paths and these exclusion classes. It
 also enumerates `src/**/*.js` and fails if a maintained runtime module is
 missing from the candidate tarball or if a retired helper is reintroduced.
 The repository index remains a catalog: links from `DOCS_INDEX.md` to tests,
-proof-of-concept evidence, historical plans, and source trees may intentionally
-resolve only in the full repository and are not package dependencies.
+historical plans, and source trees may intentionally resolve only in the full
+repository and are not package dependencies. The canonical documentation and
+protocol indexes are included in the tarball.
 
 ## Verification and publication
 
@@ -91,10 +103,12 @@ npm run pack:smoke
 ```
 
 `pack:smoke` installs the candidate tarball into a temporary consumer and
-exercises the CLI, public Integration API, initialization, schemas, and
-packaged documentation references. The package-boundary tests also assert
-that every registered guide path, including the Flutter specialist, is
-present in the candidate. The tag-triggered publication workflow
+exercises the CLI, public Integration API, initialization, schemas, and the
+Structural Quality documentation's packaged diagram references. The
+package-boundary tests also assert
+that every registered guide path, including all language specialists, is
+present in the candidate. The tag-triggered publication
+workflow
 runs the same smoke gate before `npm publish --provenance --access public`.
 Publication therefore remains owned by the trusted GitHub Actions OIDC
 workflow; local package inspection proves the candidate boundary but does not

package/docs/RECIPES.md

@@ -35,6 +35,18 @@ Concise, copy-paste friendly recipes for common ForgeLoop tasks.
 
 ### Recipe 1 — Start a New Task
 
+When the task shape is known but the final contract has not been written, first
+request a read-only preset proposal:
+
+```bash
+forgeloop task-create --task task-001 --claim src --claim tests \
+  --preset feature --preview --json
+```
+
+Review the bounded proposal, then repeat without `--preview` before continuing
+with the task workflow below. Preview creates no task namespace and acquires no
+project claim lock.
+
 <!-- FORGELOOP EXAMPLE: recipes:create-task | exit=0 | json.taskId=task-001 -->
 ```bash
 forgeloop task-create --task task-001 --claim src --claim tests --json
@@ -243,6 +255,12 @@ forgeloop task-create --task billing-feature --claim src/billing --claim tests/b
 # 3. List active tasks
 forgeloop task-list --json
 
+# 3a. Filter and page the read-only ownership-aware projection
+forgeloop task-list --active --limit 20 --offset 0 --json
+
+# 3b. Ask for a bounded blocker/recovery explanation when needed
+forgeloop next --task auth-feature --explain --json
+
 # 4. Work on task-1
 forgeloop route --task auth-feature --work clean-code --surface backend
 forgeloop preflight --task auth-feature --json
@@ -256,6 +274,11 @@ forgeloop complete --task auth-feature --json
 forgeloop task-unlock --task auth-feature --force --json
 ```
 
+`task-list` discovers all valid task namespaces before applying filters and
+pagination. Its JSON response reports `total` and `hasMore`; filtering does not
+skip ownership or corruption checks, and listing never deletes ledger or
+recovery evidence.
+
 ---
 
 ### Recipe 12 — Migrate Legacy 1.0 Single-Task Layout

package/docs/RELEASE_CHECKLIST.md

@@ -13,6 +13,17 @@ boundaries explicit:
       `ENG/flutter-development-eng.md` and explain that the specialist is
       selected only from a structurally parsed
       `dependencies.flutter.sdk: flutter` entry in affected scope.
+- [ ] README catalog and architecture fallback identify
+      `ENG/rust-development-eng.md` and explain that the specialist is
+      selected only from a structurally parsed `[package]` or `[workspace]`
+      table in an affected `Cargo.toml`.
+- [ ] README catalog and architecture fallback identify
+      `ENG/nodejs-backend-development-eng.md` and explain that Node.js
+      backend/runtime evidence is distinct from build, test, and configuration
+      tooling executed under Node.js.
+- [ ] README catalog and architecture fallback identify the C, C++, Java, SQL,
+      Go, TypeScript, PHP, and Swift specialists and explain their bounded
+      structural evidence and same-root composition rules.
 - [ ] The canonical engineering-flow source and regenerated HTML/SVG diagram
       explain project detection as routing context, not verification or
       completion evidence.
@@ -34,6 +45,22 @@ This branch prepares the candidate and its pull request. npm publication,
 tagging, GitHub Release, deployment, and merge remain separately authorized
 actions.
 
+## CI minimization validation
+
+- [ ] `npm run verify:fast` passes for edit-time feedback.
+- [ ] `npm run verify:prepush` passes before the release pull request; MCP
+      setup, when needed, was run explicitly with `npm run mcp:setup`.
+- [ ] Ordinary PR validation uses `.github/workflows/pr-core.yml` with the
+      unchanged required contexts `audit`, `CodeQL`, `Verify generated Archify
+      diagram`, `validate (22)`, `tarball smoke (ubuntu-latest)`, and
+      `dependency-review`.
+- [ ] `validate (22)` is always present and fails closed on an applicable
+      prerequisite failure, cancellation, or unexpected skip.
+- [ ] Path classification scenarios cover README-only, ordinary source,
+      Repository Index, package-export, and forced release validation.
+- [ ] Main-branch documentation, Node compatibility, package smoke, audit,
+      and Windows full-suite workflows remain available for broader validation.
+
 ## Contract and package identity
 
 - [ ] `package.json` and `package-lock.json` contain the same package version.
@@ -47,7 +74,7 @@ actions.
 - [ ] [`docs/PACKAGE_CONTENTS.md`](./PACKAGE_CONTENTS.md) matches the current
       `package.json` file list and documents intentional inclusions and
       exclusions.
-- [ ] The candidate tarball includes the registered Flutter guide and every
+- [ ] The candidate tarball includes every registered specialist guide and every
       other `src/config/guides.json` path; no repository-only guide state is
       packaged.
 - [ ] Every maintained `src/**/*.js` module is present in the candidate
@@ -70,7 +97,8 @@ actions.
 - [ ] Stale contract/route identity rejects handoff creation or acceptance.
 - [ ] An invalid event ledger projects `INCONSISTENT`.
 - [ ] Continuity lint remains non-authoritative and non-evidence.
-- [ ] `npm run dependency:policy` passes without adding runtime dependencies.
+- [ ] `npm run dependency:policy` passes with only the approved exact runtime
+      parser dependency and approved development dependencies.
 - [ ] `npm run lint` passes.
 - [ ] `npm test` passes.
 - [ ] `npm run benchmark:profiles:check` passes; absent provider/host history