@cassiomc1/forgeloop 0.1.1 → 0.1.3

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

@@ -13,6 +13,17 @@ alwaysApply: true
 6. Make the minimum change, run a specific check, and then run proportional regression checks.
 7. Diagnose failures before fixing them and do not repeat an attempt without new evidence.
 8. Request authority for unrelated external or destructive actions, installations, and publications. For a task-scoped missing Qwen-MM-Plugins capability, follow `LOOP_ENGINEERING.md`; API credentials and system dependencies remain separately gated.
-9. Report only demonstrated results and checks.
+9. After implementation begins, do not return a final result in `EXECUTING`: follow `VERIFYING` → structured evidence → `REVIEWING` → execution receipt → validator-backed `COMPLETE`; otherwise report `BLOCKED` or `PARTIALLY VERIFIED` with exact findings.
+
+After implementation work for the current task is complete, run `forgeloop next`
+before returning a final result. Follow the returned lifecycle action until
+ForgeLoop reaches a terminal state or an explicit blocker.
+
+10. Report only demonstrated results and checks.
+
+Do not stop for non-blocking missing product details. When a safe, reversible
+local default exists, record it as an agent assumption and follow the Blocking vs Non-Blocking Decisions policy in `LOOP_ENGINEERING.md`. Ask only for
+load-bearing, irreversible, externally consequential, unsafe, or real
+user/business decisions.
 
 The loop and router are canonical sources; do not duplicate domain rules.

package/.github/copilot-instructions.md

@@ -11,6 +11,17 @@ directory or file rules.
 - Make the smallest coherent change and validate it with a specific check followed by proportional regression checks.
 - Diagnose the cause before fixing a failure; do not make random attempts.
 - Do not install unrelated software, publish, delete, migrate, or alter external state without authority. For a task-scoped missing Qwen-MM-Plugins capability, follow `LOOP_ENGINEERING.md`; API credentials and system dependencies remain separately gated.
+- After implementation begins, do not return a final result in `EXECUTING`: follow `VERIFYING` → structured evidence → `REVIEWING` → execution receipt → validator-backed `COMPLETE`; otherwise report `BLOCKED` or `PARTIALLY VERIFIED` with exact findings.
+
+After implementation work for the current task is complete, run `forgeloop next`
+before returning a final result. Follow the returned lifecycle action until
+ForgeLoop reaches a terminal state or an explicit blocker.
+
 - Report the result, checks actually run, limitations, and publication state.
 
+Do not stop for non-blocking missing product details. When a safe, reversible
+local default exists, record it as an agent assumption and follow the Blocking vs Non-Blocking Decisions policy in `LOOP_ENGINEERING.md`. Ask only for
+load-bearing, irreversible, externally consequential, unsafe, or real
+user/business decisions.
+
 The loop and router are canonical; do not replicate domain rules here.

package/AGENTS.md

@@ -11,6 +11,18 @@ specific rule overrides them.
 6. Make the smallest coherent change, run specific checks, and then run proportional regression checks.
 7. Diagnose a failure before fixing it; do not repeat the same attempt without new evidence.
 8. Do not install unrelated software, publish, delete, migrate data, or change external systems without applicable authority. For a task-scoped missing Qwen-MM-Plugins capability, follow the discovery protocol in `LOOP_ENGINEERING.md`; API credentials and system dependencies remain separately gated.
-9. Finish with the result, checks actually run, limitations, and publication state.
+9. Before implementation, create/validate `.forgeloop/current-contract.json`, persist deterministic routing, satisfy mandatory gates, and require `forgeloop preflight` to return `READY`.
+10. Before claiming `COMPLETE`, require `forgeloop complete` to return `VALID`; otherwise report completion as not protocol-verified.
+11. After implementation begins, do not return a final result in `EXECUTING`: advance through `VERIFYING`, record structured evidence, reach `REVIEWING`, prepare/update the execution receipt, and require `forgeloop complete` to return `VALID`. If closure cannot be reached, report `BLOCKED` or `PARTIALLY VERIFIED` with exact findings.
+
+12. After implementation work for the current task is complete, run `forgeloop next`
+before returning a final result. Follow the returned lifecycle action until
+ForgeLoop reaches a terminal state or an explicit blocker.
+13. Finish with the result, checks actually run, limitations, and publication state.
+
+Do not stop for non-blocking missing product details. When a safe, reversible
+local default exists, record it as an agent assumption and follow the Blocking vs Non-Blocking Decisions policy in `LOOP_ENGINEERING.md`. Ask only for
+load-bearing, irreversible, externally consequential, unsafe, or real
+user/business decisions.
 
 The guides provide technical defaults; explicit requirements and project evidence prevail.

package/AGENT_COMPATIBILITY.md

@@ -4,6 +4,19 @@
 native entry point required by each supported agent. The package does not
 install an agent, configure a provider, or run a live model session.
 
+Compatibility has three distinct levels:
+
+- `ADAPTER_COMPATIBLE`: the harness recognizes the installed instruction entry
+  file.
+- `PROTOCOL_CAPABLE`: the harness can create the local contract, route, gates,
+  state, evidence, and receipt artifacts and run the validators.
+- `CONFORMANCE_VERIFIED`: a live run passed one of the scenarios under
+  `conformance/` for that harness/model combination.
+
+Reading `AGENTS.md` proves only instruction compatibility. It does not prove
+that an active session followed preflight, legal phase chronology, or completion
+validation.
+
 ## Optional capability extensions
 
 The installed loop can direct the active agent to inspect its native model and
@@ -143,5 +156,5 @@ ENG/
 schemas/
 ```
 
-See the main [README](https://github.com/cassiomc1/mdfiles#readme) for the complete `npx` installation,
+See the main [README](https://github.com/cassiomc1/forgeloop#readme) for the complete `npx` installation,
 diagnostic, first-run, and update workflow.

package/CLAUDE.md

@@ -9,6 +9,16 @@ When working in this repository:
 5. Make small changes, run a specific check, and then run proportional regression checks.
 6. Investigate the root cause of a failure before fixing it.
 7. Request authority for unrelated installation, publication, deletion, migration, or another external or destructive action. For a task-scoped missing Qwen-MM-Plugins capability, follow `LOOP_ENGINEERING.md`; API credentials and system dependencies remain separately gated.
-8. Report current evidence, limitations, and publication state without claiming checks that were not run.
+8. After implementation begins, do not return a final result in `EXECUTING`: follow `VERIFYING` → structured evidence → `REVIEWING` → execution receipt → validator-backed `COMPLETE`; otherwise report `BLOCKED` or `PARTIALLY VERIFIED` with exact findings.
+
+9. After implementation work for the current task is complete, run `forgeloop next`
+before returning a final result. Follow the returned lifecycle action until
+ForgeLoop reaches a terminal state or an explicit blocker.
+10. Report current evidence, limitations, and publication state without claiming checks that were not run.
+
+Do not stop for non-blocking missing product details. When a safe, reversible
+local default exists, record it as an agent assumption and follow the Blocking vs Non-Blocking Decisions policy in `LOOP_ENGINEERING.md`. Ask only for
+load-bearing, irreversible, externally consequential, unsafe, or real
+user/business decisions.
 
 Do not duplicate guide rules here; treat the loop and router as canonical sources.

package/ENG/accessibility-eng.md

@@ -4,6 +4,11 @@ language: en
 description: "Practical WCAG 2.2-oriented accessibility protocol for web, mobile, and desktop."
 version: "2026.09"
 last-reviewed: "2026-08-10"
+guide-id: accessibility
+completion-evidence:
+  - keyboard-navigation
+  - focus-management
+  - mobile-viewport
 ---
 
 # Accessibility as a Baseline (A11Y)

package/ENG/clean-code-eng.md

@@ -4,6 +4,7 @@ language: en
 description: "Practices for readable, observable, secure code operated by AI agents."
 version: "2026.09"
 last-reviewed: "2026-08-10"
+guide-id: clean
 ---
 
 # Clean Code for AI Agents

package/ENG/design-code-eng.md

@@ -4,6 +4,11 @@ language: en
 description: "Visual direction, UX, motion, and perceived performance for premium digital experiences."
 version: "2026.09"
 last-reviewed: "2026-08-10"
+guide-id: design
+requires-gates:
+  - design
+completion-evidence:
+  - visual-validation
 ---
 
 # Web Design Premium v2 — Practical Guidelines

package/ENG/games-code-design-web-eng.md

@@ -4,6 +4,12 @@ language: en
 description: "Architecture, design, testing, and operation of 2D, 3D, and procedural web games."
 version: "2026.09"
 last-reviewed: "2026-08-10"
+guide-id: games
+requires-gates:
+  - simulation
+completion-evidence:
+  - game-loop
+  - accessibility-validation
 ---
 
 # Web Game Development Guide — 2D, 3D, and Procedural Systems

package/ENG/perf-code-eng.md

@@ -4,6 +4,9 @@ language: en
 description: "Performance measurement, diagnosis, and improvement for web, mobile, desktop, APIs, and data."
 version: "2026.09"
 last-reviewed: "2026-08-10"
+guide-id: performance
+completion-evidence:
+  - performance-validation
 ---
 
 # Performance Guide for Web, Mobile, Desktop, and Database Development

package/ENG/premium-sites-studio-eng.md

@@ -4,6 +4,15 @@ language: en
 description: "Complete process for building premium websites at major design-studio quality."
 version: "2026.09"
 last-reviewed: "2026-08-10"
+guide-id: premium
+requires-gates:
+  - design
+  - quality
+completion-evidence:
+  - responsive-validation
+  - accessibility-validation
+  - build
+  - visual-validation
 ---
 
 # Premium Websites at Studio Level — Complete Process

package/ENG/sec-code-eng.md

@@ -4,6 +4,11 @@ language: en
 description: "Verifiable security guidance for web, mobile, desktop, APIs, and the software supply chain."
 version: "2026.09"
 last-reviewed: "2026-08-10"
+guide-id: security
+requires-gates:
+  - threat-boundary
+completion-evidence:
+  - security-validation
 ---
 
 # Security Guide for Web, Mobile, and Desktop Development

package/ENG/test-code-eng.md

@@ -4,6 +4,9 @@ language: en
 description: "Risk-based testing strategy and tools for modern languages and platforms."
 version: "2026.09"
 last-reviewed: "2026-08-10"
+guide-id: test
+completion-evidence:
+  - tests
 ---
 
 # Risk-Based Testing Guide by Language and Technology

package/GUIDE_ROUTER.md

@@ -24,6 +24,22 @@ Useful questions:
 
 ## Canonical catalog
 
+Guide frontmatter may declare protocol metadata in addition to its human
+description:
+
+```yaml
+guide-id: premium
+requires-gates:
+  - design
+completion-evidence:
+  - build
+```
+
+`requires-gates` contributes to `forgeloop preflight`; each
+`completion-evidence` identifier contributes to completion coverage. Metadata
+is descriptive and local: it does not authorize tools, remote services, or
+project commands.
+
 | ID | Guide | Responsibility |
 | --- | --- | --- |
 | `premium` | [Premium websites](./ENG/premium-sites-studio-eng.md) | End-to-end delivery of high-quality websites and web experiences |

package/LOOP_ENGINEERING.md

@@ -4,6 +4,141 @@
 > technical rules remain in the guides selected through
 > [`GUIDE_ROUTER.md`](./GUIDE_ROUTER.md).
 
+## Blocking vs Non-Blocking Decisions
+
+Classify every unresolved decision before deciding whether to ask the user.
+
+`NON_BLOCKING` applies when a safe local default exists, the choice is
+reversible, it does not change external state, it is not sensitive or
+authoritative, and it does not assert a real user or business fact. Examples
+include fictional company name, demo phone number, placeholder copy, temporary logo text,
+palette, typography, local-only fictional identity, fictional identity, demo
+contacts, visual defaults, section ordering, and local-only form behavior.
+
+`BLOCKING` applies when proceeding would require real legal business name,
+real contact details, credentials, payment data, production endpoint,
+deployment target, deployment or domain authority, destructive operation,
+irreversible architectural decision, irreversible data choice, regulated/legal claim,
+regulated claim, or another externally consequential/high-impact decision.
+
+### Safe assumption rule
+
+When a missing product detail is non-blocking, choose the smallest reasonable reversible default, explicitly classify it as an agent assumption, and record it in `current-contract.assumptions[]`. Each assumption must include `value`, `reason`, `scope`, `reversible=true`, and `source=agent-default`. Do not place resolved safe assumptions in unresolvedDecisions[]. Never present an assumption as a verified user or business fact.
+
+The assumption boundary is:
+
+```text
+SAFE + REVERSIBLE + LOCAL + NON-SENSITIVE + NON-AUTHORITATIVE + NON-DESTRUCTIVE
+```
+
+Record the choice with an explicit `ASSUMPTION` marker. Unresolved blocking decisions must be recorded in `current-contract.unresolvedDecisions[]`; they prevent `preflight` from returning `READY` and block `EXECUTING` until resolved, but do not prevent contract serialization.
+
+## Serialized protocol preparation
+
+ForgeLoop keeps the agent responsible for implementation while making the
+pre-implementation contract observable. Before executable changes, the target
+should contain a schema-valid `.forgeloop/current-contract.json` and a persisted
+`.forgeloop/routing-result.json`. Guide metadata can declare mandatory gates;
+those gates are recorded under `.forgeloop/gates/` and are checked by:
+
+```text
+forgeloop preflight
+```
+
+`preflight` validates local ForgeLoop artifacts only. It does not invoke the model, run project commands, or treat a prose declaration as evidence. A `READY` result is required before `EXECUTING` in standard and strict workflows. A non-empty `current-contract.unresolvedDecisions[]` causes `forgeloop preflight` to return `BLOCKED` with `E_CONTRACT_UNRESOLVED_DECISION`; a valid `current-contract.assumptions[]` list does not block preparation.
+
+## Completion validation and chronology
+
+`COMPLETE` is a validator result, not a string an agent may assign by itself.
+The local `events.ndjson` ledger records protocol milestones and hash links,
+without prompts, hidden reasoning, credentials, or arbitrary command output.
+The final validator checks the contract, route, state, gates, structured checks,
+evidence coverage, receipt consistency, freshness, and chronology:
+
+```text
+forgeloop audit --strict
+forgeloop complete
+```
+
+Every load-bearing success criterion must have `COVERED` evidence. A required
+`OBSERVED` check cannot be satisfied by `INFERRED`, `NOT_VERIFIED`, or
+`BLOCKED` evidence. If the validator cannot be run, use
+`COMPLETE (FORGELOOP COMPLETION NOT VERIFIED)` rather than claiming protocol
+validity.
+
+## Post-implementation closure
+
+Implementation finished is not task finished, and tests executed are not the
+same as verification recorded. After implementation begins, do not stop or
+return the final result while the ForgeLoop task remains in `EXECUTING`.
+
+ACT → QUERY NEXT → ACT → QUERY NEXT → … → TERMINAL
+
+At each lifecycle boundary, query persisted state with `forgeloop next` before
+choosing the next action. Always query after implementation, verification,
+correction, and review. The query is advisory and read-only; the host agent
+runs checks and applies the returned legal transition or repair action.
+
+```text
+POST-IMPLEMENTATION CLOSURE
+
+EXECUTING
+    ↓ forgeloop next
+advance --to VERIFYING
+    ↓ forgeloop next
+prepare-completion
+    ↓
+run applicable project checks
+    ↓
+record observed results with record-check
+    ↓ forgeloop next
+advance --to REVIEWING
+    ↓ forgeloop next
+complete
+    ↓ VALID
+COMPLETE
+```
+
+`prepare-completion` creates or refreshes the in-progress execution receipt.
+It does not claim completion. The receipt is the structured container used by
+subsequent `record-check` operations; completion remains invalid until required
+observed evidence, review state, chronology, and validator requirements are
+satisfied.
+
+The host agent runs applicable checks after the receipt exists, records their
+observed results with `record-check`, and queries `forgeloop next` before each
+subsequent lifecycle action. `record-check` records results already observed by
+the agent; it never executes the supplied command text.
+
+Continue until the terminal outcome is either validator-backed `COMPLETE` or
+an explicitly reported `BLOCKED` / `PARTIALLY VERIFIED` result with exact
+unresolved findings. Record verification evidence before review. If a required
+check fails, use `VERIFYING → DIAGNOSING → CORRECTING → VERIFYING`; do not skip
+the evidence recording step or replace it with prose.
+
+## Independent completion dimensions
+
+Local task completion, verification, publication, and production readiness are
+separate dimensions. A valid local result can therefore be reported as:
+
+```text
+TASK: COMPLETE
+VERIFICATION: VALID
+PUBLICATION: LOCAL_ONLY
+PRODUCTION_READINESS: NOT_VERIFIED
+```
+
+ForgeLoop does not execute commands from profiles, contracts, receipts, state,
+or policy artifacts. Publication and deployment require their own authority and
+observed evidence.
+
+Validators expose stable repair-oriented codes such as
+`E_CONTRACT_MISSING`, `E_ROUTE_STALE`, `E_GATE_UNVERIFIED`,
+`E_PHASE_CHRONOLOGY_INVALID`, `E_EVIDENCE_COVERAGE_PARTIAL`,
+`E_PROFILE_SOURCE_UNKNOWN`, `E_RECEIPT_ROUTE_MISMATCH`, and
+`E_PUBLICATION_CLAIM_UNVERIFIED`. Integrations should consume the code and
+artifact paths rather than parse human-readable prose.
+
 ## Core principle
 
 Never treat a request as an isolated instruction or the first plausible answer
@@ -92,6 +227,19 @@ The loop invariants are:
 8. no unrelated refactor during uncertain diagnosis;
 9. no secret in the profile, work state, receipt, or delegation artifacts;
 10. no independent-agent claim when only self-review occurred.
+11. no EXECUTING phase without a valid current contract.
+12. no EXECUTING phase without a valid route when routing is required.
+13. no EXECUTING phase while a mandatory pre-implementation gate is unsatisfied.
+14. no COMPLETE phase without evidence coverage for every required success criterion.
+15. no COMPLETE phase with stale contract, route, gate, state, or receipt fingerprints.
+16. selected guides must match across route, work state, and receipt.
+17. an agent decision cannot be recorded as a user fact.
+18. a required OBSERVED check cannot be satisfied by INFERRED evidence.
+19. BLOCKED evidence cannot be represented as PASSED.
+20. completion must be validated by the protocol, not only declared by the agent.
+21. protocol chronology must not permit execution before mandatory preflight events.
+22. publication status and production readiness must remain independent from local task completion.
+23. a task with implemented deliverables must not terminate in EXECUTING.
 
 The serializable phase and transition contract is maintained in
 [`ORCHESTRATOR_INTEGRATION.md`](./ORCHESTRATOR_INTEGRATION.md). It is a host
@@ -155,6 +303,13 @@ Do not interrupt the user for information that can be discovered safely in the
 project. Request a decision when legitimate alternatives produce materially
 different outcomes, authority is missing, or the action is destructive.
 
+Unknown non-blocking details do not prevent contract creation. Record them as
+reversible agent assumptions in `current-contract.assumptions[]` and continue.
+Unresolved blocking decisions, missing authority, and unsafe-to-infer facts
+must be serialized in `current-contract.unresolvedDecisions[]`; they prevent
+`preflight` from returning `READY` and block `EXECUTING` until resolved, not
+contract creation or serialization.
+
 ### Classify the request
 
 - **Answer, explain, or review:** inspect and report evidence; do not make implicit changes.
@@ -275,10 +430,14 @@ requirements, closer instructions, code evidence, or higher-level host rules.
 ### Design gate
 
 Before behavior, feature, architecture, or instruction changes, do proportional
-design after discovery. Work through one unresolved decision question at a
-time, surface meaningful alternatives with tradeoffs, and obtain approval
-before implementation. For small documentation maintenance, keep the treatment
-compact while still confirming the objective, boundaries, and verification.
+design after discovery. Classify unresolved design decisions before requesting
+approval. Require user approval only for load-bearing decisions whose
+alternatives materially change the requested product and cannot be resolved
+through a safe, reversible local default. For non-blocking prototype choices,
+choose a reasonable default, record the assumption, and continue. Retain
+approval for material alternatives and external or irreversible decisions. For
+small documentation maintenance, keep the treatment compact while still
+confirming the objective, boundaries, and verification.
 
 Use the [Execution contract](#execution-contract), [Project discovery](#project-discovery),
 [Guide selection](#guide-selection), and [Proportional planning](#proportional-planning)

package/ORCHESTRATOR_INTEGRATION.md

@@ -76,6 +76,15 @@ The following JSON Schemas define the boundaries a host may implement:
 - `schemas/task-brief.schema.json` and
   `schemas/delegated-result.schema.json` define optional delegation.
 - `schemas/evidence.schema.json` defines the shared evidence vocabulary.
+- `schemas/current-contract.schema.json`, `schemas/gate.schema.json`,
+  `schemas/preflight.schema.json`, and `schemas/source-registry.schema.json`
+  define preparation and provenance artifacts.
+- `schemas/check.schema.json` and `schemas/evidence-coverage.schema.json`
+  define observed verification and load-bearing success coverage.
+- `schemas/event.schema.json`, `schemas/activation.schema.json`,
+  `schemas/config.schema.json`, `schemas/policy.schema.json`, and
+  `schemas/task-bundle.schema.json` define chronology, mode, policy, and
+  handoff boundaries.
 
 `src/core/conformance.js` validates relationships that individual schemas
 cannot express: route/state protocol versions, route/state guide sets,
@@ -84,6 +93,12 @@ statuses are `VALID`, `INCOMPLETE`, `STALE`, `INCONSISTENT`, and `INVALID`.
 `forgeloop validate-protocol` is read-only and reports the exact failed
 invariant.
 
+The preparation and completion commands are also local validators:
+`preflight` must be `READY` before executable work, `audit` is a consistency
+report, and `complete` returns `VALID` only after current evidence, coverage,
+receipt relationships, and ledger chronology pass. None of these commands
+execute a project command or a model.
+
 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.

package/QUALITY_SCORECARD.md

@@ -14,6 +14,10 @@ policy are all present.
 | 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. |
+| Completion enforcement | Canonical contract, persisted route, guide-declared gates, preflight, phase ledger, structured checks, evidence coverage, `audit`, `report`, and `complete` validators. |
+| Agent lifecycle navigation | Read-only `forgeloop next` decisions, stable action/reason output, persisted-state safety, and adapter guidance at lifecycle boundaries. |
+| Execution → Verification handoff | Legal `EXECUTING` → `VERIFYING` transition, implementation-step reconciliation, and preservation of verification evidence. |
+| Pre-contract autonomy | Blocking vs Non-Blocking Decisions policy, explicit ASSUMPTION / source=agent-default recording, safe-boundary invariant, positive and negative tests, and a blind run showing non-blocking ambiguity continues while blocking ambiguity remains user-gated. |
 | 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. |
@@ -33,6 +37,16 @@ policy are all present.
 - Literal graph runtime and runtime multi-agent orchestration are `N/A by
   design`; compatible harnesses own those capabilities.
 
+## Third-run conformance position
+
+| Dimension | Classification |
+| --- | --- |
+| Execution → Verification | REPRODUCED FAILURE before this fix |
+| Verification serialization | NOT_REACHED |
+| Review transition | NOT_REACHED |
+| Receipt generation | NOT_REACHED |
+| Full conformance | PARTIAL |
+
 ## Evidence matrix
 
 The score is evidence-backed only when the contract and its executable proof
@@ -48,6 +62,8 @@ are both present:
 | 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 |
+| Protocol preparation and completion | `src/core/preflight.js`, `src/core/completion.js`, `src/core/events.js`, policy packs, and portable bundles | `tests/preflight.test.js`, `tests/completion.test.js`, `tests/lifecycle.test.js`, `tests/policy.test.js`, and `tests/bundle.test.js` |
+| Pre-contract autonomy | `LOOP_ENGINEERING.md`, `CLAUDE.md`, `AGENTS.md`, `.github/copilot-instructions.md`, `.cursor/rules/project-loop.mdc`, and the blind conformance artifacts | `tests/autonomy-policy.test.js`, `tests/conformance-scenarios.test.js` |
 
 The implementation references above are local observations. OS runners,
 remote links, provider sessions, publication, and deployment remain `Not

package/README.md

@@ -1,6 +1,6 @@
 # ForgeLoop — Instruction Guides for AI Agents
 
-[![Docs quality](https://github.com/cassiomc1/mdfiles/actions/workflows/docs-quality.yml/badge.svg?branch=main)](https://github.com/cassiomc1/mdfiles/actions/workflows/docs-quality.yml)
+[![Docs quality](https://github.com/cassiomc1/forgeloop/actions/workflows/docs-quality.yml/badge.svg?branch=main)](https://github.com/cassiomc1/forgeloop/actions/workflows/docs-quality.yml)
 
 An English-only collection of operational guides for AI agents and developers.
 It covers product strategy, code, testing, security, performance,
@@ -135,6 +135,20 @@ Protocol-support commands are local and do not invoke an agent or model:
 
 ```bash
 npx @cassiomc1/forgeloop route --work complete-website --surface ui --risk untrusted-input
+npx @cassiomc1/forgeloop activate
+npx @cassiomc1/forgeloop preflight --json
+npx @cassiomc1/forgeloop next
+npx @cassiomc1/forgeloop next --json
+npx @cassiomc1/forgeloop advance --to EXECUTING
+npx @cassiomc1/forgeloop advance --to VERIFYING
+npx @cassiomc1/forgeloop prepare-completion --json
+npx @cassiomc1/forgeloop record-check --id tests --requirement tests --status passed --evidence-kind OBSERVED --command "npm test" --result "exit 0" --json
+npx @cassiomc1/forgeloop advance --to REVIEWING
+npx @cassiomc1/forgeloop audit --json
+npx @cassiomc1/forgeloop complete --json
+npx @cassiomc1/forgeloop report
+npx @cassiomc1/forgeloop policy web-premium
+npx @cassiomc1/forgeloop bundle --task website-001 --json
 npx @cassiomc1/forgeloop inspect --json
 npx @cassiomc1/forgeloop status --json
 npx @cassiomc1/forgeloop status --contract-file .forgeloop/current-contract.json --json
@@ -143,7 +157,41 @@ npx @cassiomc1/forgeloop validate-receipt --file ./execution-receipt.json --json
 npx @cassiomc1/forgeloop validate-protocol --route-file ./routing-result.json --state-file .forgeloop/work-state.json --receipt-file ./execution-receipt.json --contract-file .forgeloop/current-contract.json --json
 ```
 
+The query-driven post-implementation path is:
+
+```text
+implementation
+→ forgeloop next
+→ advance --to VERIFYING
+→ forgeloop next
+→ prepare-completion
+→ forgeloop next
+→ checks + record-check
+→ forgeloop next
+→ advance --to REVIEWING
+→ forgeloop next
+→ complete
+```
+
+`forgeloop next` and `forgeloop next --json` read persisted state only. They do
+not run project checks or mutate protocol artifacts.
+
 `route` expands declared signals into deterministic guide IDs and reason codes.
+`activate` records a session marker without storing prompts or hidden reasoning.
+Before implementation, write the canonical contract, persist the route, create
+required gate artifacts under `.forgeloop/gates/`, and require `preflight` to
+return `READY`. `advance` enforces legal phase transitions; it never runs the
+project's commands. After implementation, advance to `VERIFYING`, use
+`prepare-completion` to create a safe receipt skeleton, and use `record-check`
+to serialize results that the agent has already observed. `record-check` never
+executes the supplied command text. Advance to `REVIEWING` before running
+`audit` and `complete`.
+`audit` is a read-only consistency check. `complete` validates the final
+contract, route, gates, phase ledger, structured evidence, coverage, receipt,
+and freshness before it can return `VALID`. `report` renders the same result as
+independent task, verification, publication, and production-readiness
+dimensions. `policy` selects a local strictness pack and `bundle` exports
+canonical protocol artifacts for handoff or review.
 `inspect`, `status`, and `validate-state` explain installation and resumable
 state; they do not execute commands from the target profile.
 `inspect` and `status` parse the target-local schemas and report `valid`,
@@ -165,6 +213,21 @@ Capability gaps and inline/non-Git degraded mode are defined in
 [`AGENT_COMPATIBILITY.md`](./AGENT_COMPATIBILITY.md); they are reported as
 limitations rather than treated as silent successes.
 
+### Live conformance modes
+
+Standard blind conformance uses the same mode throughout a run:
+
+```text
+forgeloop preflight
+→ forgeloop audit
+→ forgeloop complete
+```
+
+Strict blind conformance is a separate profile. First verify the target
+`PROJECT_PROFILE.md`, then use `--strict` consistently with `preflight`,
+`audit`, and `complete`. Do not evaluate a Standard run with Strict criteria
+unless that escalation is explicitly recorded.
+
 ### Protocol compatibility
 
 The npm package version is independent of protocol version. The current

package/THREAT_MODEL.md

@@ -14,6 +14,10 @@ remaining trust boundaries and their executable evidence.
 | Symlink escape | Redirects a managed path to another directory | Existing target parents and artifact paths | Reject symlinked targets, parents, and destinations before access | The check is not a filesystem lock | `tests/core.test.js`, `tests/portability.test.js`, `tests/fixtures/protocol/invalid/symlink-target.json` |
 | Malicious manifest | Causes unsafe update or false ownership claims | `.forgeloop/manifest.json` | Schema, hash, safe-path, and preserve-flag validation; conflicts remain visible | A trusted operator can still deliberately edit the manifest | `tests/cli.test.js`, `tests/core.test.js` |
 | Malicious work-state | Resumes stale, secret-bearing, or invalid work | `.forgeloop/work-state.json` | Schema/semantic checks, version checks, transition checks, contract/HEAD/artifact freshness, secret scan, size/depth bounds | Freshness cannot prove that an external process did not alter a file immediately afterward | `tests/work-state.test.js`, `tests/checkpoint-freshness.test.js`, `tests/security-limits.test.js` |
+| Forged preparation | Makes an agent's prose claim look like a completed preflight | Contract, route, gate, and preflight artifacts | Canonical SHA-256 fingerprints, guide-declared gate requirements, stale-artifact checks, and `E_*` failures | The CLI cannot stop a separate process from writing project files before preflight | `tests/protocol-artifacts.test.js`, `tests/preflight.test.js` |
+| Chronology rewrite | Hides execution before route, gates, or verification | `.forgeloop/events.ndjson` | Append-only local ledger, sequence numbers, hash chaining, and chronology validation without prompts or hidden reasoning | A privileged process can still replace the ledger after validation | `tests/lifecycle.test.js` |
+| Unsupported profile fact | Turns an agent decision into a durable user fact | `PROJECT_PROFILE.md` and `.forgeloop/sources.json` | Source IDs, source-kind validation, unknown-reference rejection, and explicit misclassification failures | Arbitrary Markdown semantics still require a human or host-specific parser | `tests/profile-provenance.test.js`, `src/core/profile.js` |
+| Weak verification | Treats a vague or inferred claim as observed evidence | Receipt checks and coverage | Versioned check schema, contradictory-status rejection, observed-evidence requirements, and coverage matrix | Evidence remains local and declarative; it is not a remote attestation service | `tests/evidence-coverage.test.js`, `tests/completion.test.js` |
 | Malicious receipt | Turns local claims into false publication or completion claims | Execution receipt JSON | Semantic evidence checks for completion, checks, review, push, commit, and deployment; explicit publication booleans | Evidence text is declarative and must still be reviewed for provenance | `tests/receipt-semantics.test.js`, `tests/observability.test.js` |
 | Malicious task brief | Grants a child task more authority than intended | Delegation brief JSON and host harness | Relative path boundaries, guide/verification/authority checks, secret-free validation, set validation, parent integration ownership | The host harness remains responsible for OS permissions and execution policy | `tests/delegation.test.js`, `tests/delegation-set.test.js` |
 | Artifact content exposure | Sensitive material enters portable artifacts or diagnostics | State, receipt, delegation, evidence, and repository text | Nested key/value detection, shaped marker patterns, scanner coverage, no content echo in errors | Content scanners cannot prove that an unknown encoding is harmless | `tests/security-limits.test.js`, `tests/test_scan_secrets.py`, `scripts/scan_secrets.py` |
@@ -33,3 +37,5 @@ remaining trust boundaries and their executable evidence.
 - Local checks do not imply remote publication, merge, deployment, or provider
   confirmation.
 - Credentials remain outside Git and outside protocol artifacts.
+- `preflight`, `audit`, `report`, and `complete` never execute commands copied
+  from a profile, contract, receipt, state, gate, policy, or bundle.