@cassiomc1/forgeloop 0.1.0

package/LOOP_SYSTEM_DESIGN.md

@@ -0,0 +1,394 @@
+# Universal Engineering Loop — System Design
+
+**Status:** Implemented; repository checks validate the system contract.
+
+## Objective
+
+Turn this collection into a portable instruction kit for future projects. After the kit is copied into a repository, requests handled by a compatible agent enter a cycle of discovery, guide selection, execution, verification, and correction.
+
+The system should use every guide that materially helps the task without loading irrelevant documents or replacing project-specific instructions with generic defaults.
+
+## Primary decisions
+
+- The package supports Codex, Claude Code, Cursor, GitHub Copilot, Antigravity,
+  OpenCode, Hermes, Pi, Command Code, and Freebuff.
+- Codex, Claude Code, Cursor, and GitHub Copilot use native entry files; the
+  other six agents consume the shared `AGENTS.md` entry point.
+- The portable instruction layer uses Markdown and each agent's native instruction mechanism; the optional local Node CLI validates and installs the kit without an agent runtime or third-party dependency.
+- English is the only language used by repository content and guide metadata.
+- The agent uses all applicable guides, not every file indiscriminately.
+- Design, planning, test-first, and review process gates live in the canonical loop and scale with task risk instead of becoming unconditional boilerplate in every adapter or architecture note.
+- The persistent project profile stores only verifiable facts and never secrets, tokens, or credentials.
+- The loop continues while safe progress is possible. Repetition without new evidence triggers hypothesis reassessment or a blocked result, not infinite retries.
+- Third-party provenance and reuse boundaries remain part of every portable copy.
+- Qwen-MM-Plugins is an optional, task-scoped capability extension: the agent checks native support first, installs the smallest missing capability when needed, and verifies it before use; it is not a package or runtime dependency.
+
+## Alternatives considered
+
+### One large file
+
+Combining the loop, routing rules, and technical content would simplify copying but increase context use, duplicate guide material, and make maintenance harder. This option was rejected.
+
+### Thin adapters with canonical modules
+
+Small entry points for each agent, one central loop, one router, and specialized guides preserve modularity and allow the agent to load only relevant context. This is the selected architecture.
+
+### Generated configuration
+
+A tool could detect the stack and generate instructions automatically, but that would add installation, compatibility, and maintenance costs before the need is proven. It may become a later enhancement but is outside the first version.
+
+## Architecture
+
+The ForgeLoop system is organized around three observable control surfaces:
+deterministic routing, checkpointed state, and evidence that can be inspected by
+the compatible harness.
+
+```text
+                            FORGELOOP
+                                │
+                  ┌─────────────┼─────────────┐
+                  │             │             │
+               ROUTING        STATE        EVIDENCE
+                  │             │             │
+                  ▼             ▼             ▼
+            deterministic   checkpoint    observable
+              decisions       facts         claims
+                  │             │             │
+                  │       ┌─────┴─────┐       │
+                  │       │           │       │
+                  │   repository   contract   │
+                  │       │           │       │
+                  │       └─────┬─────┘       │
+                  │             │             │
+                  │          freshness        │
+                  │             │             │
+                  └───────┬─────┴─────┬───────┘
+                          │           │
+                          ▼           ▼
+                    CONFORMANCE   DELEGATION
+                          │           │
+                          └─────┬─────┘
+                                ▼
+                    VALID / STALE / INVALID
+                                │
+                                ▼
+                        compatible harness
+```
+
+```text
+User request
+    |
+    v
+Nearest agent adapter
+    |
+    +--> LOOP_ENGINEERING.md
+    |        |
+    |        +--> PROJECT_PROFILE.md
+    |        +--> GUIDE_ROUTER.md
+    |                  |
+    |                  +--> ENG/*.md
+    |
+    +--> repository-specific instructions
+    |
+    v
+Discovery -> contract -> route
+                              |
+                              v
+          proportional design -> plan -> change -> targeted check -> regression -> review
+                              ^                                                   |
+                              +--------------- diagnosis and correction ----------+
+    |
+    v
+Final result with evidence and limitations
+```
+
+The canonical loop keeps proportional design, planning, implementation,
+testing, and review visible between routing and delivery. Architecture names
+the order of those stages without duplicating the detailed operating rules that
+belong in `LOOP_ENGINEERING.md`.
+
+## Components and responsibilities
+
+### `AGENTS.md`
+
+Primary entry point for Codex and agents that recognize repository instructions. It stays short and requires the loop, profile, and router to be read before execution.
+
+### `CLAUDE.md`
+
+Adapter for Claude Code. It points to the same canonical source and does not repeat loop rules.
+
+### `.github/copilot-instructions.md`
+
+GitHub Copilot adapter. It activates the same operational contract while preserving more specific instructions in the destination project.
+
+### `.cursor/rules/project-loop.mdc`
+
+Always-applicable Cursor adapter. It delegates decisions to the loop and router.
+
+### `AGENT_COMPATIBILITY.md`
+
+Human-readable support matrix for all ten agents. It explains each native entry
+file, the shared `AGENTS.md` compatibility contract, official documentation,
+precedence caveats, and the deterministic verification boundary.
+
+### `LOOP_ENGINEERING.md`
+
+Canonical operational cycle. It defines:
+
+- discovery of repository state and nearby instructions;
+- capability discovery and task-scoped Qwen-MM-Plugins installation;
+- conversion of the request into an execution contract;
+- risk assessment and authority boundaries;
+- guide selection;
+- proportional design, planning, test-first, and review gates for behavior,
+  architecture, and instruction changes;
+- small coherent changes;
+- delivery-specific verification;
+- evidence-driven diagnosis and root-cause correction;
+- final regression checks;
+- success and stop conditions;
+- handling of destructive actions and external authority.
+
+The loop is also the only place that defines harness-conditional behavior such
+as native isolation, independent review, and capability fallback rules. The
+system design references those boundaries but does not restate their detailed
+criteria.
+
+### Capability extensions
+
+The capability protocol is a narrow extension of the canonical loop. It asks
+the agent to inspect native model and harness support, reuse an existing
+callable tool, install only the smallest missing Qwen-MM-Plugins capability
+when the task requires it, check API and system prerequisites, verify
+registration, and then use the tool. Keyless multimodal reading is the default;
+API-backed operations remain disabled until their documented credentials or
+service endpoints are configured. The kit links to the upstream project but
+does not bundle its source, MCP server, model, or dependencies.
+
+### `GUIDE_ROUTER.md`
+
+Canonical map between request or project signals and applicable guides. Each route records:
+
+- activation signals;
+- exclusions;
+- normal guide combinations;
+- useful search targets;
+- expected verification evidence.
+
+### `PROJECT_PROFILE.md`
+
+Durable context for a destination project. The template captures:
+
+- confirmed stack and versions;
+- package manager and official commands;
+- architecture and relevant directories;
+- external services and risk surfaces;
+- test, lint, build, and release commands;
+- documentation and UI conventions;
+- constraints, decisions, and unverified items;
+- a source for every durable fact.
+
+The profile changes only when discovery reveals a real project change; it is not a task diary. In this source repository, `profile-mode: template` keeps it as a reusable template. After copying it into a code repository, the first cycle may change the mode to `project` and fill only confirmed facts.
+
+### `DELEGATION_PROTOCOL.md`
+
+The delegation document defines serializable task briefs, write ownership,
+dependencies, normalized results, reviewer independence, and inline fallback.
+It does not add agent personas, a scheduler, or a provider runtime.
+
+### `ORCHESTRATOR_INTEGRATION.md`
+
+The integration contract is the graph-readiness boundary. It names the
+serializable phases, transitions, invariants, artifact schemas, host
+responsibilities, and inline fallback in one canonical document. It does not
+implement a graph runtime or duplicate the detailed operational rules in
+`LOOP_ENGINEERING.md`.
+
+### `THREAT_MODEL.md`
+
+The threat model records path, symlink, artifact, secret, stale-state,
+publication, schema, dependency, and resource-limit boundaries with their
+mitigations, residual limitations, and executable evidence.
+
+### `ENG/*.md`
+
+Eight canonical guides cover:
+
+- clean code;
+- testing;
+- security;
+- performance;
+- design;
+- accessibility;
+- premium website production;
+- web games.
+
+Each guide has exact English frontmatter and a stable guide ID.
+
+### `THIRD_PARTY_NOTICES.md`
+
+Records external provenance, trademarks, licenses, and reuse boundaries. It is required in the repository and in every portable copy.
+
+## Initial routing matrix
+
+| Work type | Guide set |
+| --- | --- |
+| Documentation | Related domain and documentation checks |
+| General code or bug fix | `clean`, `test`; add `security` or `performance` when the surface requires it |
+| Backend, API, authentication, or data | `clean`, `test`, `security`; add `performance` for critical paths |
+| Web, mobile, or desktop interface | `clean`, `test`, `design`, `accessibility`; add `security` and `performance` according to product risk |
+| Complete site or landing page | `premium`, `design`, `accessibility`, `clean`, `test`, `security`, `performance` |
+| Web game | `games`, `clean`, `test`, `security`, `performance`, `accessibility`; add `design` for UI or visual direction |
+| HTML video or motion | `design`, `accessibility`, `performance`, `test`, `security`; use HyperFrames only when requested or already available |
+| Infrastructure or CI/CD | `security`, `test`; add `performance` when availability or cost changes |
+
+Routing uses the request and files actually affected. A single word in the repository is not enough to activate a stack or guide.
+
+## Execution flow
+
+1. Read the agent adapter and the nearest instructions for the scoped directory.
+2. Inspect manifests, configuration, documentation, tests, CI, and Git state.
+3. Confirm or update the project profile with sourced facts.
+4. Convert the request into an objective, deliverables, constraints, risks, checks, and a stop condition.
+5. Select the guide set in the router.
+6. Read only the required sections of each guide.
+7. Apply proportional design and plan gates before behavior, architecture, or instruction changes.
+8. Establish a baseline and reproduce the problem when applicable.
+9. Make the smallest coherent change that satisfies the objective.
+10. Run the targeted check first, then proportional regression checks.
+11. Use the loop's review gate after regression when the task or harness calls for self-review or independent review.
+12. On failure, collect evidence, identify the root cause, and repeat with a targeted correction.
+13. Finish only with current evidence, explicit limitations, and no unrelated changes.
+
+## Canonical workflow state model
+
+The protocol represents the engineering loop with serializable conceptual
+states rather than an executable graph:
+
+```text
+RECEIVED → DISCOVERING → CONTRACT_READY → ROUTED
+                                      ├→ DESIGNING → PLANNED
+                                      └→ PLANNED
+PLANNED → EXECUTING → VERIFYING
+VERIFYING ├→ DIAGNOSING → CORRECTING → VERIFYING
+          └→ REVIEWING → COMPLETE
+Any non-terminal state → BLOCKED when a genuine blocker is evidenced
+```
+
+| From | Condition | To |
+| --- | --- | --- |
+| `RECEIVED` | context is required | `DISCOVERING` |
+| `DISCOVERING` | sufficient sourced context | `CONTRACT_READY` |
+| `CONTRACT_READY` | route is resolved | `ROUTED` |
+| `ROUTED` | design decision is required | `DESIGNING` |
+| `ROUTED` | no design gate is required | `PLANNED` |
+| `DESIGNING` | design is approved | `PLANNED` |
+| `PLANNED` | task work begins | `EXECUTING` |
+| `EXECUTING` | targeted check is ready | `VERIFYING` |
+| `VERIFYING` | a check fails | `DIAGNOSING` |
+| `DIAGNOSING` | a fix hypothesis exists | `CORRECTING` |
+| `CORRECTING` | the fix is applied | `VERIFYING` |
+| `VERIFYING` | checks pass | `REVIEWING` |
+| `REVIEWING` | contract and quality are accepted | `COMPLETE` |
+| any non-terminal state | a genuine external blocker is evidenced | `BLOCKED` |
+
+State invariants are machine-validatable: `COMPLETE` requires verification
+evidence, `BLOCKED` requires a blocker category, `CORRECTING` requires a
+diagnosed hypothesis, and `REVIEWING` cannot claim independent review from the
+same identity as the implementer. Simple documentation tasks may skip design,
+delegation, and full regression when the contract records why those states are
+not applicable.
+
+## Precedence and conflicts
+
+The system respects this order:
+
+1. platform and safety rules;
+2. the user's latest explicit request;
+3. more specific and nearer repository or directory instructions;
+4. applicable legal, security, and data-preservation requirements;
+5. confirmed project profile facts;
+6. router decisions;
+7. general guide recommendations.
+
+A guide never authorizes installation, publication, deletion, migration, or an external change that the user did not place in scope.
+
+## Failures and stop conditions
+
+- **Missing tool:** use an available equivalent only when it provides compatible evidence; otherwise request approval or report the check as not run.
+- **Missing guide or broken link:** continue only with conservative defaults and disclose the limitation.
+- **Missing credential:** report the blocked capability without exposing or inventing a credential.
+- **Conflicting instructions:** apply precedence, choose the most conservative interpretation, and record any material decision.
+- **Repeated failure without new evidence:** stop repeating the same action, reassess the hypothesis, and use another diagnostic method.
+- **External or destructive action:** proceed only with explicit authority and an exact validated target.
+
+## Validation of the instruction system
+
+The documentation workflow verifies:
+
+- every file referenced by an adapter exists;
+- repository-relative links resolve;
+- exactly eight canonical English guides exist;
+- guide IDs, filenames, frontmatter keys, and `language: en` match the catalog;
+- no legacy language tree or bilingual metadata remains;
+- all route contracts contain valid guide IDs;
+- the canonical phase list, transition rows, state invariants, reason-code
+  language, graph-readiness evidence, and no-runtime boundary are present;
+- Markdown and frontmatter are valid;
+- secrets and credential-like assignments are absent;
+- `THIRD_PARTY_NOTICES.md` is present.
+
+The validator also exercises six routing scenarios:
+
+1. premium landing page;
+2. authenticated API;
+3. bug fix without UI;
+4. mobile app with UI;
+5. multiplayer web game;
+6. documentation-only change.
+
+## Distribution
+
+The npm CLI installs the kit into the current directory or an existing
+directory selected with `--path` when the package is available in the npm
+registry. If it is not available yet, the same commands can run as
+`node src/cli.js ...` from a repository checkout. A user may also download the
+repository or a release archive and copy these items while preserving their
+relative structure:
+
+- the four native agent adapters plus `AGENT_COMPATIBILITY.md`;
+- the shared `AGENTS.md` entry point for the six compatible agents;
+- `LOOP_ENGINEERING.md`;
+- `GUIDE_ROUTER.md`;
+- `PROJECT_PROFILE.md`;
+- `THIRD_PARTY_NOTICES.md`;
+- `LICENSE` and `LICENSE-DOCS.md`;
+- the `ENG/` guide directory.
+
+The README explains the file set, activation behavior, current/relative/absolute
+target installation, first-run profile flow, local validation commands, and safe
+update practice.
+
+## Out of scope
+
+- remote prompt services or databases;
+- mandatory orchestration frameworks;
+- infinite or unattended execution beyond agent limits;
+- automatic installation of unrelated tools or provider runtimes; task-scoped
+  Qwen-MM-Plugins capability installation remains governed by the canonical
+  capability protocol and host approval controls;
+- automatic modification of global computer files;
+- duplication of complete guides inside adapters;
+- versioned logs for every request.
+
+## Acceptance criteria
+
+- The repository and its maintained content are English-only.
+- All ten supported agents have a documented entry into one canonical loop,
+  with native adapters distinguished from shared `AGENTS.md` compatibility.
+- The router selects every relevant guide and excludes irrelevant guides in the six defined scenarios.
+- The profile contains verifiable facts, sources, and real commands without secrets.
+- The loop requires evidence before completion claims and exits safely when blocked.
+- Structural, Markdown, link, and secret checks pass locally and in CI.
+- Portable-copy instructions always include third-party notices.
+- The package does not alter destination commands, dependencies, or behavior without need and applicable authority.

package/ORCHESTRATOR_INTEGRATION.md

@@ -0,0 +1,106 @@
+# Orchestrator integration contract
+
+`ForgeLoop` is a portable protocol, not an orchestrator. A compatible harness
+may map these serializable contracts to its own state machine, worker pool, or
+review primitive without adding that framework to the package.
+
+## Canonical workflow diagram
+
+```text
+RECEIVED → DISCOVERING → CONTRACT_READY → ROUTED
+                                      ├→ DESIGNING → PLANNED
+                                      └→ PLANNED
+PLANNED → EXECUTING → VERIFYING
+VERIFYING ├→ DIAGNOSING → CORRECTING → VERIFYING
+          └→ REVIEWING → COMPLETE
+Any non-terminal state → BLOCKED when a genuine blocker is evidenced
+```
+
+## Phase names
+
+- `RECEIVED`
+- `DISCOVERING`
+- `CONTRACT_READY`
+- `ROUTED`
+- `DESIGNING`
+- `PLANNED`
+- `EXECUTING`
+- `VERIFYING`
+- `DIAGNOSING`
+- `CORRECTING`
+- `REVIEWING`
+- `COMPLETE`
+- `BLOCKED`
+
+## Canonical transition table
+
+| From | Condition | To |
+| --- | --- | --- |
+| `RECEIVED` | context is required | `DISCOVERING` |
+| `DISCOVERING` | sufficient sourced context | `CONTRACT_READY` |
+| `CONTRACT_READY` | route is resolved | `ROUTED` |
+| `ROUTED` | design decision is required | `DESIGNING` |
+| `ROUTED` | no design gate is required | `PLANNED` |
+| `DESIGNING` | design is approved | `PLANNED` |
+| `PLANNED` | task work begins | `EXECUTING` |
+| `EXECUTING` | targeted check is ready | `VERIFYING` |
+| `VERIFYING` | a check fails | `DIAGNOSING` |
+| `DIAGNOSING` | a fix hypothesis exists | `CORRECTING` |
+| `CORRECTING` | the fix is applied | `VERIFYING` |
+| `VERIFYING` | checks pass | `REVIEWING` |
+| `REVIEWING` | contract and quality are accepted | `COMPLETE` |
+| `Any non-terminal state` | a genuine external blocker is evidenced | `BLOCKED` |
+
+The host may skip proportional phases, but it must preserve the state
+invariants and record why a skipped phase was not applicable.
+
+## State invariants
+
+- `COMPLETE` requires verification evidence current to the task.
+- `BLOCKED` requires blocker evidence, a category, and a safe next action.
+- `CORRECTING` requires a diagnosed hypothesis and a changed evidence basis.
+- `REVIEWING` cannot claim independent review when reviewer and implementer
+  identities are equal.
+- A retry requires new evidence or a changed hypothesis.
+
+## Serializable interfaces
+
+The following JSON Schemas define the boundaries a host may implement:
+
+- `schemas/routing-input.schema.json` and
+  `schemas/routing-result.schema.json` define deterministic guide selection
+  after semantic signals are declared.
+- `schemas/work-state.schema.json` defines local checkpoint/resume data.
+- `schemas/execution-receipt.schema.json` defines structured evidence and
+  explicit publication state.
+- `schemas/task-brief.schema.json` and
+  `schemas/delegated-result.schema.json` define optional delegation.
+- `schemas/evidence.schema.json` defines the shared evidence vocabulary.
+
+`src/core/conformance.js` validates relationships that individual schemas
+cannot express: route/state protocol versions, route/state guide sets,
+state/receipt contract fingerprints, and delegated-result/task-brief IDs. Its
+statuses are `VALID`, `INCOMPLETE`, `STALE`, `INCONSISTENT`, and `INVALID`.
+`forgeloop validate-protocol` is read-only and reports the exact failed
+invariant.
+
+Every artifact is JSON-compatible, carries `schemaVersion: 1` and
+`protocolVersion: 1`, and contains no executable callbacks, provider-specific
+tool objects, credentials, hidden prompts, or remote database references.
+
+## Host responsibilities
+
+The compatible harness owns model execution, tool execution, scheduling,
+parallelism, lifecycle, isolation, and any remote services. It must pass
+validated inputs to the protocol, preserve file ownership, report unavailable
+capabilities, and never turn local success into an unverified publication
+claim.
+
+## No-runtime boundary
+
+The protocol does not provide a graph runtime.
+The protocol does not provide a provider adapter.
+The protocol does not provide a scheduler.
+No runtime required: inline execution is the valid fallback when the host has
+no subagents or worktrees. A future host may add those capabilities outside the
+package, but must preserve the serialized contracts and explicit limitations.

package/PROJECT_PROFILE.md

@@ -0,0 +1,124 @@
+---
+language: en
+profile-mode: template
+profile-status: uninitialized
+last-confirmed: unknown
+---
+
+# Project Profile
+
+> Durable context for [Loop Engineering](./LOOP_ENGINEERING.md). Fill it only
+> with evidence from the target project.
+
+## Maintenance rules
+
+- Update a fact only after inspecting authoritative files, commands, or sources.
+- Preserve `profile-mode: template` while maintaining this source kit. In a target project with product code or manifests, change it to `project` during the first discovery cycle.
+- Record the source for every material fact.
+- Never store secrets, tokens, passwords, private keys, or raw credentials.
+- Preserve explicit project decisions until newer evidence replaces them.
+- Set `profile-status` to `verified` only when the stack, essential architecture, and critical commands have evidence.
+- Keep `language: en`; this kit has no alternate language variant.
+- Do not use this file as a task diary.
+
+## Product and objective
+
+| Field | Current state | Source |
+| --- | --- | --- |
+| Product | Not identified — confirm from the stated source | Source not identified |
+| Users | Not identified — confirm from the stated source | Source not identified |
+| Primary outcome | Not identified — confirm from the stated source | Source not identified |
+| Durable exclusions | Not identified — confirm from the stated source | Source not identified |
+
+## Confirmed stack
+
+| Layer | Technology and version | Source |
+| --- | --- | --- |
+| Frontend | Not identified — confirm from the stated source | Source not identified |
+| Backend | Not identified — confirm from the stated source | Source not identified |
+| Mobile | Not identified — confirm from the stated source | Source not identified |
+| Desktop | Not identified — confirm from the stated source | Source not identified |
+| Data | Not identified — confirm from the stated source | Source not identified |
+| Infrastructure | Not identified — confirm from the stated source | Source not identified |
+
+Record a missing manifest or configuration as verified absence. Do not infer a
+stack from technology names found only in documentation or examples.
+
+## Official commands
+
+| Purpose | Confirmed command | Source |
+| --- | --- | --- |
+| Installation | Not identified — confirm from the stated source | Source not identified |
+| Development | Not identified — confirm from the stated source | Source not identified |
+| Specific test | Not identified — confirm from the stated source | Source not identified |
+| Full test suite | Not identified — confirm from the stated source | Source not identified |
+| Lint and formatting | Not identified — confirm from the stated source | Source not identified |
+| Typecheck | Not identified — confirm from the stated source | Source not identified |
+| Build | Not identified — confirm from the stated source | Source not identified |
+| Additional validation | Not identified — confirm from the stated source | Source not identified |
+
+Never invent a command when the project already declares official scripts or
+automation.
+
+## Architecture and directories
+
+| Area | Path or responsibility | Source |
+| --- | --- | --- |
+| Primary entry point | Not identified — confirm from the stated source | Source not identified |
+| Domain | Not identified — confirm from the stated source | Source not identified |
+| Interfaces | Not identified — confirm from the stated source | Source not identified |
+| Persistence | Not identified — confirm from the stated source | Source not identified |
+| Tests | Not identified — confirm from the stated source | Source not identified |
+| Documentation | Not identified — confirm from the stated source | Source not identified |
+| CI/CD | Not identified — confirm from the stated source | Source not identified |
+
+## Supported platforms
+
+| Surface | Confirmed targets | Evidence |
+| --- | --- | --- |
+| Web | Not identified — confirm from the stated source | Source not identified |
+| Mobile | Not identified — confirm from the stated source | Source not identified |
+| Desktop | Not identified — confirm from the stated source | Source not identified |
+| Browsers and devices | Not identified — confirm from the stated source | Source not identified |
+| Accessibility requirements | Not identified — confirm from the stated source | Source not identified |
+
+## Services and risk surfaces
+
+| Item | Use and risk | Safe source |
+| --- | --- | --- |
+| Authentication and authorization | Not identified — confirm from the stated source | Source not identified |
+| External APIs | Not identified — confirm from the stated source | Source not identified |
+| Personal or sensitive data | Not identified — confirm from the stated source | Source not identified |
+| Uploads and files | Not identified — confirm from the stated source | Source not identified |
+| Payments | Not identified — confirm from the stated source | Source not identified |
+| Queues, webhooks, and jobs | Not identified — confirm from the stated source | Source not identified |
+| Deployment and production | Not identified — confirm from the stated source | Source not identified |
+
+Record only the mechanism and safe configuration location. Never copy credential
+values.
+
+## Constraints and decisions
+
+| Decision or constraint | State | Source |
+| --- | --- | --- |
+| Required conventions | Not identified — confirm from the stated source | Source not identified |
+| Compatibility | Not identified — confirm from the stated source | Source not identified |
+| Performance budgets | Not identified — confirm from the stated source | Source not identified |
+| Legal and license constraints | Not identified — confirm from the stated source | Source not identified |
+| Operations requiring approval | Not identified — confirm from the stated source | Source not identified |
+
+## Unverified items
+
+- Not identified — confirm from the stated source.
+
+Remove an item from this section only after adding evidence and moving it to the
+appropriate section.
+
+## Evidence
+
+| Date | Confirmed fact | Source or command | Scope |
+| --- | --- | --- | --- |
+| Not identified | Not identified — confirm from the stated source | Source not identified | Not identified |
+
+Keep evidence concise. Long outputs, temporary logs, and per-task history do not
+belong in this file.

package/QUALITY_SCORECARD.md

@@ -0,0 +1,54 @@
+# ForgeLoop quality scorecard
+
+This scorecard measures evidence-backed protocol quality. A dimension reaches
+10/10 only when its documented contract, deterministic structure, positive and
+negative checks, failure behavior, portability boundary, and compatibility
+policy are all present.
+
+| Dimension | 10/10 evidence |
+| --- | --- |
+| Loop engineering | Failure taxonomy, retry rule, invariants, evidence categories, and semantic tests in `LOOP_ENGINEERING.md`. |
+| Routing | `src/core/router.js`, versioned route schemas, reason codes, exclusions, and positive/negative fixtures. |
+| Workflow model | Canonical phases, transition table, state invariants, proportional skips, and `LOOP_SYSTEM_DESIGN.md`. |
+| Protocol executability | Versioned JSON schemas, semantic cross-artifact conformance, dependency-free validation, and compatibility fixtures. |
+| Graph readiness | Serializable state/transition contracts and `ORCHESTRATOR_INTEGRATION.md`; no runtime required. |
+| Portability | Node 20/22/24 Linux depth, OS smoke coverage, path/line-ending fixtures, and adapter compatibility evidence. |
+| Observability | `inspect`/`status`/`validate-protocol` shared derived state classification, real schema health, shared evidence, rich doctor findings, receipts, and no telemetry. |
+| Resume/checkpoint | Atomic local state, contract/HEAD/artifact freshness, age warning, schema/secret validation, status, safe validation, and bounded clearing without persisting derived freshness fields. |
+| Multi-agent coordination | Self-contained briefs, write/write and write/read ownership checks, dependency-set validation, reviewer independence, normalized results, and inline fallback. |
+| Security boundaries | Realpath containment, bounded untrusted JSON, threat model, nested secret scanning, publication evidence, and explicit authority rules. |
+| Maintenance quality | Small modules, built-in runtime, deterministic JSON contracts, malformed/version fixtures, package gates, and backward-compatible protocol versions. |
+
+## Score rules
+
+- `Observed` evidence is a command result, file, hash, or test output available
+  in the current checkout.
+- `Inferred` evidence is a reasoned consequence of observed evidence and must
+  be labeled as inference.
+- `Not verified` means the check was not run or the target is outside the
+  available environment.
+- `Blocked` means a genuine external condition prevents safe progress.
+- A passing local check never implies that a branch was pushed, a pull request
+  was merged, or a deployment succeeded.
+- Literal graph runtime and runtime multi-agent orchestration are `N/A by
+  design`; compatible harnesses own those capabilities.
+
+## Evidence matrix
+
+The score is evidence-backed only when the contract and its executable proof
+are both present:
+
+| Dimension | Implementation evidence | Executable evidence |
+| --- | --- | --- |
+| Routing | `src/core/router.js`, route schemas, stable reason codes, and exclusions | `tests/router.test.js`, `tests/fixtures/routes/` |
+| Observability | `src/core/receipt.js`, `src/core/inspect.js`, `src/core/evidence.js`, and schema health | `tests/observability.test.js`, `tests/receipt-semantics.test.js`, `tests/schema-health.test.js` |
+| Resume/checkpoint | `src/core/work-state.js`, `EXECUTION_STATE.md`, shared loaded-state classifier, contract/artifact classifiers, and atomic writes | `tests/work-state.test.js`, `tests/checkpoint-freshness.test.js`, status, validate-state, and validate-protocol tests |
+| Delegation | `src/core/delegation.js`, delegation-set validator, and `DELEGATION_PROTOCOL.md` | `tests/delegation.test.js`, `tests/delegation-set.test.js` |
+| Portability | `ORCHESTRATOR_INTEGRATION.md`, adapter compatibility, and OS smoke workflow | `tests/portability.test.js`, package checks |
+| Graph readiness | Serializable phase/transition mapping in `ORCHESTRATOR_INTEGRATION.md` | Python semantic validator and workflow-policy tests |
+| Security boundary | realpath containment, bounded JSON, `THREAT_MODEL.md`, secret-free artifacts, authority and no-runtime rules | `tests/security-limits.test.js`, Markdown/loop validators, and `scripts/scan_secrets.py` |
+| Cross-artifact conformance | `src/core/conformance.js`, `classifyLoadedWorkState`, and `forgeloop validate-protocol --contract-file` | `tests/conformance.test.js`, `tests/validate-protocol-cli.test.js`, and protocol fixtures covering precedence and stale evidence |
+
+The implementation references above are local observations. OS runners,
+remote links, provider sessions, publication, and deployment remain `Not
+verified` unless their own checks produce current evidence.