@cassiomc1/forgeloop 1.12.0 → 1.13.0

package/.github/copilot-instructions.md

@@ -13,7 +13,7 @@ Use these instructions across the repository while preserving local rules.
 - Select context with [`GUIDE_ROUTER.md`](../GUIDE_ROUTER.md) and report activated guide IDs.
 - For repository-wide textual discovery, prefer `forgeloop search` and treat its results as discovery only; do not use them as verification evidence or scope authority.
 - Respect the latest request, scope, and higher-level instructions.
-- Make the smallest coherent change; validate with specific and regression checks.
+- Make the smallest coherent change; use `npm run verify:fast` while editing and `npm run verify:prepush` before a PR, then validate with proportional 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: discover existing tasks first with `forgeloop task-list --json`; if an existing task is selected or identifiable, use `forgeloop next --task <id> --json` before creating another task, reconcile continuity when present, and inspect the checkout. A change of harness, model, provider, IDE, process, terminal, or session does not create a new task. Legacy singleton state such as `.forgeloop/work-state.json` is compatibility-only, not the primary modern discovery mechanism.

package/AGENTS.md

@@ -11,7 +11,7 @@ Do not treat ForgeLoop as vendor-specific, optional, or to follow only "in spiri
 1. Inspect [`PROJECT_PROFILE.md`](./PROJECT_PROFILE.md). Confirm facts from sources; initialize if in `template` mode.
 1. Use [`GUIDE_ROUTER.md`](./GUIDE_ROUTER.md) to select relevant guides and report activated guide IDs.
 1. For repository-wide textual discovery, prefer `forgeloop search` and treat its results as discovery only; do not use them as verification evidence or scope authority.
-1. Make the smallest coherent change, run specific checks, and proportional regression checks.
+1. Make the smallest coherent change; use `npm run verify:fast` while editing and `npm run verify:prepush` before a PR, then run 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 creating or activating new lifecycle state: discover existing tasks first with `forgeloop task-list --json`; if an existing task is selected or identifiable, use `forgeloop next --task <id> --json` before creating another task, reconcile continuity when present, and inspect the checkout. A change of harness, model, provider, IDE, process, terminal, or session does not create a new task. Legacy singleton state such as `.forgeloop/work-state.json` is compatibility-only, not the primary modern discovery mechanism.

package/CLAUDE.md

@@ -13,7 +13,7 @@ When working in this repository:
 1. Verify [`PROJECT_PROFILE.md`](./PROJECT_PROFILE.md) against real sources; initialize if in `template` mode.
 1. Consult [`GUIDE_ROUTER.md`](./GUIDE_ROUTER.md), select relevant guides, and announce their IDs.
 1. For repository-wide textual discovery, prefer `forgeloop search` and treat its results as discovery only; do not use them as verification evidence or scope authority.
-1. Make small changes, run specific checks, and run proportional regression checks.
+1. Make small changes; use `npm run verify:fast` while editing and `npm run verify:prepush` before a PR, then 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: discover existing tasks first with `forgeloop task-list --json`; if an existing task is selected or identifiable, use `forgeloop next --task <id> --json` before creating another task, reconcile continuity when present, and inspect the checkout. A change of harness, model, provider, IDE, process, terminal, or session does not create a new task. Legacy singleton state such as `.forgeloop/work-state.json` is compatibility-only, not the primary modern discovery mechanism.

package/CONTRIBUTING.md

@@ -0,0 +1,90 @@
+# Contributing to ForgeLoop
+
+## Before opening a pull request
+
+Run `npm run verify:prepush` before opening a pull request. For fast feedback,
+use `npm run test:quick` or `npm run verify:fast`; the full suite and coverage
+gate are run once by the local pre-push tier and by one sharded PR-core lane.
+The default `npm test` command is the complete no-coverage suite. `npm run test:ci`
+uses the same discovered test files with two Node test workers for two-core CI
+runners; PR Node 24 divides that same set into four deterministic shards and
+aggregates coverage without rerunning tests. `npm run test:watch` provides
+local watch mode. Run `npm run mcp:setup` explicitly when MCP checks are in
+scope. Keep CLI metadata, generated
+references, schemas, completions, summaries, and conformance scenarios
+aligned. Do not add vendor-specific runtime behavior: ForgeLoop remains a
+file-backed protocol and support CLI.
+
+The ordinary PR workflow is intentionally path-aware. `pr-core.yml` always
+publishes the ruleset contexts `audit`, `CodeQL`, `Verify generated Archify
+diagram`, `validate (22)`, `tarball smoke (ubuntu-latest)`, and
+`dependency-review`; `validate (22)` fails closed if an applicable job fails
+or is skipped unexpectedly. Broader main-branch and release workflows provide
+the explicit cross-platform, package, Windows, documentation, and audit
+coverage that is not duplicated on every pull request.
+
+## Protocol changes
+
+Any persisted artifact or lifecycle change must preserve the published schema
+compatibility policy, add valid and invalid fixtures, update `protocol-info`,
+and include a recovery path for interrupted writes. A breaking protocol change
+requires a new explicit protocol version and migration plan.
+
+## Documentation & MCP verification
+
+- Follow [`docs/DOCUMENTATION_GUIDE.md`](./docs/DOCUMENTATION_GUIDE.md); run
+  `npm run docs:generate`, `npm run completions:generate`, and
+  `npm run summary:generate` before `npm run docs:check` when canonical
+  registries change.
+- Changes under `integrations/mcp/` require `npm run mcp:test`, and package
+  changes require `npm run mcp:pack:check`.
+- `npm run mcp:test` never installs dependencies. If the MCP package is not
+  set up, run `npm run mcp:setup` explicitly when installation is authorized.
+
+## Frozen repository validators
+
+The supported local Python command is `python3 -m unittest discover -s tests`.
+The frozen validators require Python 3.9 or newer and are compatibility tools
+used by CI; they are not a replacement for the Node test suite.
+
+## Release and performance checks
+
+Use `npm run coverage` followed by `npm run critical-coverage:check` for
+coverage gates; coverage is intentionally not part of the default test command
+or the PR unit-test job. `npm run performance:check` measures the median
+startup time of the read-only `protocol-info` command using a broad
+shared-runner budget.
+Historical link exclusions in `.lychee.toml` are reviewed manually at least
+quarterly and must not be removed automatically.
+
+On native Windows, local antivirus scanning can dominate repeated Node process
+startup. If permitted by local security policy, ask IT to exclude the trusted
+`node.exe` executable, this repository root, and its `node_modules` directory
+from Windows Defender real-time scanning. Do not disable protection globally or
+apply exclusions to untrusted directories. If native Windows remains slow,
+WSL2 is a supported alternative for local development; retain native Windows
+CI for Windows-specific path and process behavior.
+
+## Review expectations
+
+PRs must explain the task contract, verification evidence, migration impact,
+and compatibility impact. Never commit secrets, external credentials, or
+unverified publication claims.
+
+## Focused verification and maintenance
+
+`npm test -- tests/transaction.test.js` runs a selected file. Directories select
+all nested test files; helpers and fixtures are excluded. Name filters such as
+`npm test -- --test-name-pattern='transaction' tests/transaction.test.js` are
+forwarded to Node. Unsupported options and unmatched selectors fail explicitly.
+
+Run `npm run complexity:check` with lint. Reductions are welcome; increases to
+the committed hotspot budget require an explicit explanation and review.
+TypeScript and YAML are development-only dependencies for packed-consumer and
+semantic workflow verification; the core runtime has no npm dependencies.
+
+Transaction payload maintenance is opt-in:
+`npm run transactions:compact -- --path /path/to/project --retain-days 7`
+previews the operation; add `--apply` to compact eligible payloads. Manifests,
+ledgers, recent transactions, and ambiguous outcomes remain intact. See the
+[Astra implementation record](docs/ASTRA_IMPLEMENTATION.md) for boundaries.

package/DOCS_INDEX.md

@@ -1,10 +1,11 @@
 # Documentation index
 
-The machine-readable inventory is
+The repository's machine-readable documentation inventory is
 [`docs/documentation-manifest.json`](./docs/documentation-manifest.json). It
-classifies every package-shipped document, names canonical concept owners, and
-records generated/deprecated-document metadata. Normative requirements and
-their implementation/test mappings are in
+classifies maintained documentation, names canonical concept owners, and
+records generated/deprecated-document metadata. The package file list and
+guide registry additionally define the shipped consumer surface. Normative
+requirements and their implementation/test mappings are in
 [`docs/protocol-requirements.json`](./docs/protocol-requirements.json).
 
 ForgeLoop keeps one canonical process and separates protocol behavior from
@@ -49,11 +50,11 @@ integration and guide context. Use this map before editing documentation.
 | Capability levels, discovery, and degradation | [`PROTOCOL_INTEGRATION.md`](./PROTOCOL_INTEGRATION.md) | Vendor-neutral harness contract |
 | Host/orchestrator integration | [`ORCHESTRATOR_INTEGRATION.md`](./ORCHESTRATOR_INTEGRATION.md) | Serializable phases, transition boundaries, host responsibilities, and no-runtime integration contract |
 | Durable project facts | [`PROJECT_PROFILE.md`](./PROJECT_PROFILE.md) | Target-specific facts only; no prompts or secrets |
-| Guide selection | [`GUIDE_ROUTER.md`](./GUIDE_ROUTER.md) | Deterministic routing and exclusions |
+| Guide selection | [`GUIDE_ROUTER.md`](./GUIDE_ROUTER.md) | Deterministic routing, project evidence, overlays, bounds, and exclusions |
 | Architecture and safety boundaries | [`LOOP_SYSTEM_DESIGN.md`](./LOOP_SYSTEM_DESIGN.md) and [`THREAT_MODEL.md`](./THREAT_MODEL.md) | Design rationale and residual risk |
 | Artifact and phase schemas | [`schemas/`](./schemas/) and [`CONTRACT_COVERAGE.md`](./CONTRACT_COVERAGE.md) | Versioned machine-readable contract |
 | CLI/package behavior | [`src/`](./src/) and [`tests/`](./tests/) | Executable implementation and regression evidence |
-| Guide content | [`ENG/`](./ENG/) | Context-specific, English-only operational guides, including the Flutter specialist |
+| Guide content | [`ENG/`](./ENG/) | Context-specific, English-only operational guides, including Flutter, .NET, Node.js, Rust, C, C++, Java, SQL, Go, TypeScript, PHP, and Swift specialists; ASP.NET Core and ABP remain .NET overlays |
 | Diagram governance | [`docs/diagrams/manifest.json`](./docs/diagrams/manifest.json) | Authoritative taxonomy, renderer mapping, canonical purposes, artifact ownership, and references |
 | Diagram maintainer entrypoint | [`docs/diagrams/README.md`](./docs/diagrams/README.md) | Typed Archify source, animated HTML explorer, animated SVG fallback, review, and regeneration workflow |
 | Engineering flow diagram | [`docs/assets/diagrams/forgeloop-engineering-flow.html`](./docs/assets/diagrams/forgeloop-engineering-flow.html) | Conceptual lifecycle from request through validator-backed completion |
@@ -151,11 +152,12 @@ loop, and secret-scanning contracts that have not been migrated to Node. Their
 scope, exact commands, and migration boundary are recorded in
 [`scripts/CI_VALIDATORS.md`](./scripts/CI_VALIDATORS.md).
 
-The package has no runtime dependencies. Development dependencies are limited
-to c8, ESLint, TypeScript, and YAML and are checked by
-`npm run dependency:policy`. GitHub Actions use `npm ci`, pinned action SHAs,
-CodeQL, dependency review, and generated-release notes; npm publication still
-uses trusted OIDC publishing and is not implied by local verification.
+The package uses the approved exact `smol-toml` runtime dependency for bounded
+Cargo manifest parsing. Development dependencies remain limited to c8, ESLint,
+TypeScript, and YAML and are checked by `npm run dependency:policy`. GitHub
+Actions use `npm ci`, pinned action SHAs, CodeQL, dependency review, and
+generated-release notes; npm publication still uses trusted OIDC publishing
+and is not implied by local verification.
 
 ## Editing rules
 

package/ENG/c-development-eng.md

@@ -0,0 +1,112 @@
+---
+name: c-development-eng
+language: en
+description: "Specialist guidance for production C libraries, services, embedded components, and native build systems."
+version: "2026.09"
+last-reviewed: "2026-09-12"
+guide-id: c
+requires-gates:
+  - threat-boundary
+completion-evidence:
+  - c-validation
+---
+
+# C Development Engineering Guide
+
+## Mission and activation
+
+Use this guide for C libraries, services, workers, embedded components, and
+native integrations. ForgeLoop confirms C from an explicit CMake or Meson C
+declaration, a native Bazel rule with owned implementation source, or a direct
+claim to an owned `.c` file. `.h`/`.inc` files, a Makefile alone, compiler
+flags, a Docker image, a package name, generated output, and vendored code are
+not C project identity. C and C++ may be confirmed at the same root.
+
+Detection is local, deterministic, bounded, and read-only. It does not invoke
+CMake, Meson, Make, Bazel, a compiler, a linker, a generator, or project code.
+
+## Authority and precedence
+
+Repository architecture, supported platforms, compiler configuration, ABI,
+warning policy, and minimum supported toolchain win over generic advice. Use
+the matching repository standard and toolchain first, then the ISO/WG14
+material and version-matched platform documentation. C23 (ISO/IEC 9899:2024)
+is the current published reference in the 2026-09 plan snapshot; C2y remains
+development work and is not an automatic migration target.
+
+## Project and standard discovery
+
+Read bounded build metadata and claimed/owned implementation files. Treat
+`project(app LANGUAGES C)`, `project(app C)`, `enable_language(C)`, and
+`project('app', 'c')` as explicit language evidence; CMake command names are
+case-insensitive. CMake's omitted language defaults are ambiguous to a static
+detector, so `project(app)` needs owned implementation source before it
+establishes C. A `cc_*` Bazel rule needs owned `.c` source because the rule may
+also build C++. A Makefile becomes meaningful
+only with owned implementation source.
+
+Keep the language standard, compiler mode (`-std=c23` versus `-std=gnu23`),
+library/ABI, target triple, libc, warning policy, sanitizer configuration, and
+runtime platform as separate decisions. A compiler's default is not a license
+to migrate the repository.
+
+## Architecture and semantics
+
+Make ownership, lifetime, storage duration, pointer validity, allocation and
+cleanup contracts explicit. Review array bounds, NUL termination, integer
+conversion, signed/unsigned behavior, overflow, alignment, provenance, strict
+aliasing, format strings, initialization, double-free, use-after-free, and
+partial-failure paths. Do not silence a warning with a cast unless the
+conversion is proven at the boundary.
+
+Keep transport, parsing, domain, persistence, platform, and FFI adapters
+separate where the repository does. Define an error convention that preserves
+the cause without leaking secrets, and make cleanup work on every return path.
+
+## I/O, concurrency, and security
+
+Bound file, socket, parser, decompression, allocation, and message sizes.
+Validate lengths before arithmetic and validate encodings and protocol state
+before use. Treat environment values, files, IPC, network input, format
+strings, and FFI data as hostile. Make timeouts, cancellation, signal handling,
+thread ownership, locking, atomics, and shutdown behavior explicit; never
+create unbounded work or share mutable state without a documented invariant.
+
+## Performance and portability
+
+Measure before optimizing. Preserve cache, allocation, syscall, and startup
+budgets with benchmarks or profiling evidence. Keep platform adapters narrow;
+document endianness, alignment, filesystem, clock, thread, and socket
+assumptions. Sanitizers, fuzzers, static analysis, and cross-compilation
+results are verification evidence, not project-detection evidence.
+
+## Build, dependency, and interop policy
+
+Keep compiler, linker, C library, SDK, feature, and generated-code versions
+reproducible. Review third-party code and license/ABI consequences without
+executing package-manager hooks during routing. For C++ or foreign-function
+boundaries, specify ownership, layout, calling convention, error translation,
+threading, and lifetime rules. Generated and vendored trees remain dependency
+boundaries.
+
+## Verification and Definition of Done
+
+Run the narrowest compiler, warning, sanitizer, static-analysis, unit,
+integration, fuzz, and cross-platform checks that prove the changed behavior,
+then the repository checks. Record the exact source mode, target, compiler,
+linker, sanitizer, and command. A missing tool is `NOT_VERIFIED`, not a pass.
+
+Before completion, confirm ownership and cleanup paths, malformed/partial input
+tests, resource and concurrency limits, security review, reproducibility, and
+the exact artifact or binary contract. ForgeLoop performs bounded structural
+native-project analysis, not preprocessing, compiler execution, ABI analysis,
+or linker resolution.
+
+## Official sources
+
+- [ISO/IEC JTC 1/SC 22/WG14](https://www.open-std.org/jtc1/sc22/wg14/)
+- [C23 project status](https://www.open-std.org/jtc1/sc22/wg14/www/projects)
+- [GNU C Library manual](https://sourceware.org/glibc/manual/latest/html_node/)
+- [CMake project languages](https://cmake.org/cmake/help/latest/command/project.html)
+- [Meson language reference](https://mesonbuild.com/Reference-manual_functions.html#project)
+- [Bazel C/C++ rules](https://bazel.build/reference/be/c-cpp)

package/ENG/cpp-development-eng.md

@@ -0,0 +1,109 @@
+---
+name: cpp-development-eng
+language: en
+description: "Specialist guidance for production C++ libraries, services, tools, and native build systems."
+version: "2026.09"
+last-reviewed: "2026-09-12"
+guide-id: cpp
+requires-gates:
+  - threat-boundary
+completion-evidence:
+  - cpp-validation
+---
+
+# C++ Development Engineering Guide
+
+## Mission and activation
+
+Use this guide for production C++ libraries, services, workers, tools, and
+native integrations. ForgeLoop confirms C++ from explicit CMake/Meson CXX or
+cpp declarations, a native Bazel rule with owned `.cc`, `.cpp`, `.cxx`, `.c++`,
+or `.C` source, or a direct claim to owned implementation source. Header-only
+files, a Makefile alone, compiler versions, flags, package metadata, generated
+output, and vendored code are insufficient without compatible project context.
+C and C++ may be confirmed at one root.
+
+Detection is bounded and static. It never executes a compiler, build generator,
+package manager, test binary, macro, or code-generation step.
+
+## Authority and precedence
+
+Repository architecture, standard mode, ABI, supported compilers, target
+platforms, and public compatibility policy win over generic best practice.
+Use WG21, the actual compiler documentation, and version-matched platform
+documentation after repository evidence. C++23 (ISO/IEC 14882:2024) is the
+published reference in the 2026-09 plan snapshot. C++26 compiler support is
+not permission to migrate a C++17/20/23 repository.
+
+## Project and standard discovery
+
+Treat `project(app LANGUAGES CXX)`, `enable_language(CXX)`, Meson's `cpp`
+language, and an owned-source-backed `cc_*` Bazel rule as structural evidence.
+CMake's default `project(app)` is ambiguous and requires owned implementation
+source before it confirms C or C++. A `.C` extension is the conventional
+case-sensitive C++ source form; `.h` remains ambiguous while `.hpp`, `.hh`,
+`.hxx`, and `.inl` are contextual headers.
+
+Keep language standard, compiler mode, standard library, ABI, target triple,
+runtime, visibility, exception/RTTI policy, and vendor toolset separate. Do
+not infer the repository standard from a host compiler's newest mode.
+
+## Architecture and semantics
+
+Make ownership and lifetime visible. Prefer RAII, value semantics, the rule of
+zero, narrow interfaces, and explicit move/copy contracts. Review references,
+temporary lifetime, dangling pointers, object slicing, virtual dispatch,
+destruction, allocator behavior, iterator invalidation, alignment, strict
+aliasing, undefined behavior, ODR/linkage, templates, concepts, ranges,
+coroutines, modules, and C interoperability.
+
+Do not mechanically replace every raw pointer with `shared_ptr`: raw pointers
+can correctly express non-owning references, C APIs, intrusive structures, or
+mapped memory. For public libraries, review symbols, layout, vtables,
+standard-library ABI, exception ABI, visibility, and compiler/runtime
+compatibility before changing types.
+
+## Errors, concurrency, I/O, and security
+
+Choose exceptions or error-return types deliberately and preserve causes.
+Specify `noexcept` and cancellation behavior at boundaries. Make thread
+ownership, atomics, memory ordering, locks, condition variables, queues,
+coroutine cancellation, and shutdown bounded and observable. Protect parsers,
+serialization, filesystem, IPC, network, environment, and FFI boundaries with
+length, encoding, authorization, timeout, and resource checks.
+
+## Performance and portability
+
+Measure allocation, cache, syscall, queue, startup, and latency changes with
+benchmarks or profiles. Keep platform adapters and compile-time feature
+selection explicit. Record endianness, alignment, filesystem, clock, locale,
+thread, linker, and standard-library assumptions. Sanitizers, fuzzing, and
+static analysis prove selected paths; they do not establish universal safety.
+
+## Build, dependencies, and interop
+
+Keep CMake/Meson/Bazel configuration, compiler/linker flags, generated code,
+package versions, and ABI policy reproducible. Treat build files as executable
+configuration and never run them during routing. At C, Objective-C, Rust,
+Swift, or other FFI boundaries document layout, ownership transfer, error
+translation, calling convention, thread rules, and lifetime.
+
+## Verification and Definition of Done
+
+Run focused compiler, warning, sanitizer, static-analysis, unit, integration,
+fuzz, ABI, and cross-platform checks for the exact target and standard, then
+the repository checks. Record compiler, standard library, linker, flags, and
+platform. Missing tooling is `NOT_VERIFIED`. Completion requires tested error,
+cleanup, concurrency, resource, and compatibility behavior plus reproducible
+packaging. ForgeLoop performs bounded structural native-project analysis, not
+template instantiation, preprocessing, ABI compatibility analysis, or build
+execution.
+
+## Official sources
+
+- [WG21 committee documents](https://www.open-std.org/jtc1/sc22/wg21/)
+- [GCC C++ dialect options](https://gcc.gnu.org/onlinedocs/gcc/C-Dialect-Options.html)
+- [Clang C++ language status](https://clang.llvm.org/cxx_status.html)
+- [CMake project languages](https://cmake.org/cmake/help/latest/command/project.html)
+- [Meson language reference](https://mesonbuild.com/Reference-manual_functions.html#project)
+- [Bazel C/C++ rules](https://bazel.build/reference/be/c-cpp)