@cassiomc1/forgeloop 0.1.2 → 0.1.4

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

@@ -14,6 +14,11 @@ alwaysApply: true
 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. 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
@@ -22,3 +27,14 @@ load-bearing, irreversible, externally consequential, unsafe, or real
 user/business decisions.
 
 The loop and router are canonical sources; do not duplicate domain rules.
+
+## Pre-question decisions
+
+Before asking any product-detail question, classify it as `BLOCKING` or
+`NON_BLOCKING` using `LOOP_ENGINEERING.md`. For
+`NON_BLOCKING`, choose a safe reversible local default, record it in
+`current-contract.assumptions[]`, and continue. For `BLOCKING`, persist
+`current-contract.json` with `unresolvedDecisions[]` and a blocking reason
+before asking. Do not ask the user to choose among reversible local
+product-positioning alternatives; the canonical checklist and boundary remain
+in `LOOP_ENGINEERING.md`.

package/.github/copilot-instructions.md

@@ -12,6 +12,11 @@ directory or file rules.
 - 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
@@ -20,3 +25,14 @@ load-bearing, irreversible, externally consequential, unsafe, or real
 user/business decisions.
 
 The loop and router are canonical; do not replicate domain rules here.
+
+## Pre-question decisions
+
+Before asking any product-detail question, classify it as `BLOCKING` or
+`NON_BLOCKING` using `LOOP_ENGINEERING.md`. For
+`NON_BLOCKING`, choose a safe reversible local default, record it in
+`current-contract.assumptions[]`, and continue. For `BLOCKING`, persist
+`current-contract.json` with `unresolvedDecisions[]` and a blocking reason
+before asking. Do not ask the user to choose among reversible local
+product-positioning alternatives; the canonical checklist and boundary remain
+in `LOOP_ENGINEERING.md`.

package/AGENTS.md

@@ -14,7 +14,11 @@ specific rule overrides them.
 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. Finish with the result, checks actually run, limitations, and publication state.
+
+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
@@ -22,3 +26,14 @@ load-bearing, irreversible, externally consequential, unsafe, or real
 user/business decisions.
 
 The guides provide technical defaults; explicit requirements and project evidence prevail.
+
+## Pre-question decisions
+
+Before asking any product-detail question, classify it as `BLOCKING` or
+`NON_BLOCKING` using `LOOP_ENGINEERING.md`. For
+`NON_BLOCKING`, choose a safe reversible local default, record it in
+`current-contract.assumptions[]`, and continue. For `BLOCKING`, persist
+`current-contract.json` with `unresolvedDecisions[]` and a blocking reason
+before asking. Do not ask the user to choose among reversible local
+product-positioning alternatives; the canonical checklist and boundary remain
+in `LOOP_ENGINEERING.md`.

package/CLAUDE.md

@@ -10,7 +10,11 @@ When working in this repository:
 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. 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. Report current evidence, limitations, and publication state without claiming checks that were not run.
+
+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
@@ -18,3 +22,14 @@ 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.
+
+## Pre-question decisions
+
+Before asking any product-detail question, classify it as `BLOCKING` or
+`NON_BLOCKING` using `LOOP_ENGINEERING.md`. For
+`NON_BLOCKING`, choose a safe reversible local default, record it in
+`current-contract.assumptions[]`, and continue. For `BLOCKING`, persist
+`current-contract.json` with `unresolvedDecisions[]` and a blocking reason
+before asking. Do not ask the user to choose among reversible local
+product-positioning alternatives; the canonical checklist and boundary remain
+in `LOOP_ENGINEERING.md`.

package/LOOP_ENGINEERING.md

@@ -7,31 +7,162 @@
 ## Blocking vs Non-Blocking Decisions
 
 Classify every unresolved decision before deciding whether to ask the user.
+The question is a consequence of a `BLOCKING` classification, never a default
+response to ordinary uncertainty.
 
-`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.
+### Pre-question decision classification
 
-`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.
+Before asking the user any product-detail question:
+
+1. Classify the unresolved detail as `BLOCKING` or `NON_BLOCKING`.
+2. If `NON_BLOCKING`, do not ask; choose the smallest reasonable reversible
+   local default, record it in `current-contract.assumptions[]`, and continue.
+3. If `BLOCKING`, record the detail in
+   `current-contract.unresolvedDecisions[]`, persist and validate the contract,
+   then ask the user with a blocking reason.
+
+In short, `NON_BLOCKING` means do not ask and record it in `current-contract.assumptions[]`; `BLOCKING` means persist the contract and ask the user with a blocking reason.
+
+There is no third `UNKNOWN → ask` path for ordinary reversible product
+ambiguity. The invariant is:
+
+```text
+QUESTION
+must never happen
+before CLASSIFICATION
+```
+
+### PRE-QUESTION CHECK
+
+Before asking the user, answer every item:
+
+```text
+[ ] Is this a real user/business fact?
+[ ] Is this sensitive?
+[ ] Is this authoritative?
+[ ] Does it affect external state?
+[ ] Is it destructive?
+[ ] Is it irreversible?
+[ ] Would a safe local reversible default materially misrepresent the user?
+```
+
+If all answers are `NO`, classify the detail as `NON_BLOCKING`, record an
+assumption, and continue. If any answer is `YES`, classify it as `BLOCKING`,
+persist the contract before clarification, and attach a blocking reason.
 
 ### 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.
+`NON_BLOCKING` applies when the choice is `SAFE + REVERSIBLE + LOCAL +
+NON-SENSITIVE + NON-AUTHORITATIVE + NON-DESTRUCTIVE` and does not assert a real
+user or business fact. Each recorded `ASSUMPTION` must include `value`, `reason`,
+`scope`, `reversible=true`, and `source=agent-default`. Do not place resolved
+safe assumptions in `unresolvedDecisions[]`, and never present an assumption as
+a verified user or business fact.
+
+Generally `NON_BLOCKING` when no real business fact is supplied:
+
+```text
+practice-area emphasis
+fictional positioning
+representative specialty mix
+tone of the fictional firm
+hero messaging
+section ordering
+fictional partner/attorney profiles
+fictional office location
+visual identity
+palette
+typography
+local fictional brand name
+local-only fictional identity
+fictional company name
+demo contact details
+demo phone number
+placeholder legal-service descriptions
+placeholder copy
+fictional testimonials
+temporary logo text
+local-only form behavior
+```
+
+These examples remain non-blocking only when they stay safe, reversible,
+local, non-sensitive, non-authoritative, and non-destructive. Do not hardcode
+one law-firm positioning into the protocol or tests.
+
+### Blocking boundary
 
-The assumption boundary is:
+`BLOCKING` applies when proceeding requires any of the following:
 
 ```text
-SAFE + REVERSIBLE + LOCAL + NON-SENSITIVE + NON-AUTHORITATIVE + NON-DESTRUCTIVE
+real legal business name
+real contact information
+real contact details
+real attorney identities
+credentials
+payment information
+payment data
+production endpoints
+production endpoint
+deployment target
+deployment/domain authority
+destructive operations
+destructive operation
+irreversible architecture
+irreversible architectural decision
+irreversible data decisions
+regulated or legal claims
+regulated/legal claim
+real compliance representations
+real business facts not safely inferable
 ```
 
-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.
+Blocking decisions must be written to
+`current-contract.unresolvedDecisions[]`. They make `preflight` return
+`BLOCKED`, but they do not prevent contract serialization.
+Unresolved blocking decisions are recorded in `current-contract.unresolvedDecisions[]`.
+
+### Question justification invariant
+
+Asking the user is allowed only when `blockingReason` is present and comes from
+a blocking category such as:
+
+A user question requires a `blockingReason`; a question without one is invalid.
+
+```text
+REAL_BUSINESS_FACT_REQUIRED
+SENSITIVE_VALUE_REQUIRED
+EXTERNAL_AUTHORITY_REQUIRED
+IRREVERSIBLE_DECISION_REQUIRED
+REGULATED_CLAIM_REQUIRED
+DESTRUCTIVE_ACTION_REQUIRED
+```
+
+Multiple reasonable aesthetic or positioning choices do not justify a question.
+The deterministic support helper in `src/core/decision-classification.js`
+validates this boundary; it does not use an LLM or parse natural language.
+
+### Contract-before-clarification sequence
+
+The operational order is:
+
+```text
+DISCOVERY
+    ↓
+classify unresolved details
+    ↓
+create and persist current-contract.json
+    ↓
+persist assumptions[] and unresolvedDecisions[]
+    ↓
+validate contract
+    ↓
+if unresolvedDecisions.length > 0
+    ↓
+ask user with blockingReason
+```
+
+No clarification stop is allowed before a serialized contract exists. A
+non-blocking ambiguity never becomes a contract blocker.
 
 ## Serialized protocol preparation
 
@@ -72,20 +203,44 @@ 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
-    ↓ advance
-VERIFYING
-    ↓ run checks and record structured evidence
-REVIEWING
-    ↓ prepare/update the execution receipt
-forgeloop complete
+    ↓ 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

package/QUALITY_SCORECARD.md

@@ -15,7 +15,10 @@ policy are all present.
 | 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. |
-| 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. |
+| 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 — structural | Blocking vs Non-Blocking Decisions policy, classify-before-ask invariant, PRE-QUESTION CHECK, explicit ASSUMPTION / source=agent-default recording, contract-before-clarification ordering, deterministic reason-code helper, and positive/negative tests. |
+| Pre-contract autonomy — cross-agent live robustness | Independent live-agent behavior across fresh package installs, exact blind prompts, one-process/no-subagent topology, and separate evidence for non-blocking continuation versus blocking clarification. Structural coverage does not imply live cross-agent robustness. |
 | 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. |
@@ -35,6 +38,18 @@ policy are all present.
 - Literal graph runtime and runtime multi-agent orchestration are `N/A by
   design`; compatible harnesses own those capabilities.
 
+## Blind-run conformance position
+
+| Dimension | Classification |
+| --- | --- |
+| Pre-contract autonomy — structural | IMPLEMENTED / LOCAL TESTS PASS — 369 Node tests and 42 Python tests, with focused autonomy/conformance checks green |
+| Pre-contract autonomy — cross-agent live robustness | NOT_PROVEN — the prior third blind run was reported as PASS, the fourth blind run failed on a non-blocking question, and the fifth blind run is pending a newly published package |
+| Execution → Verification | REPRODUCED FAILURE in fourth blind run before implementation |
+| Verification serialization | NOT_REACHED in fourth blind run |
+| Review transition | NOT_REACHED in fourth blind run |
+| Receipt generation | NOT_REACHED in fourth blind run |
+| Full conformance | PARTIAL |
+
 ## Evidence matrix
 
 The score is evidence-backed only when the contract and its executable proof
@@ -51,7 +66,8 @@ are both present:
 | 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` |
+| Pre-contract autonomy — structural | `LOOP_ENGINEERING.md`, `src/core/decision-classification.js`, `CLAUDE.md`, `AGENTS.md`, `.github/copilot-instructions.md`, `.cursor/rules/project-loop.mdc` | `tests/decision-classification.test.js`, `tests/autonomy-policy.test.js`, `tests/preflight.test.js` |
+| Pre-contract autonomy — cross-agent live robustness | Prior third blind-run result reported in the hardening brief, `conformance/runs/2026-08-13-codex-fourth-live.md`, and the exact blind request | `tests/conformance-scenarios.test.js`; fifth run remains pending publication and execution |
 
 The implementation references above are local observations. OS runners,
 remote links, provider sessions, publication, and deployment remain `Not

package/README.md

@@ -137,6 +137,8 @@ Protocol-support commands are local and do not invoke an agent or model:
 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
@@ -155,6 +157,25 @@ 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

package/conformance/README.md

@@ -8,6 +8,7 @@ Run a scenario in a disposable target using the Standard profile first:
 
 ```bash
 npx @cassiomc1/forgeloop preflight --json
+npx @cassiomc1/forgeloop next --json
 npx @cassiomc1/forgeloop audit --json
 npx @cassiomc1/forgeloop complete --json
 ```
@@ -15,12 +16,16 @@ npx @cassiomc1/forgeloop complete --json
 The expected post-implementation path is:
 
 ```text
-EXECUTING
+implementation
+→ forgeloop next
 → advance --to VERIFYING
+→ forgeloop next
 → prepare-completion
-→ record-check for each observed check
+→ forgeloop next
+→ checks + record-check
+→ forgeloop next
 → advance --to REVIEWING
-→ audit
+→ forgeloop next
 → complete
 ```