@cassiomc1/forgeloop 1.1.1 → 1.2.2

package/docs/GETTING_STARTED.md

@@ -191,6 +191,8 @@ Output:
 
 When preflight returns `READY`, ForgeLoop synchronizes resumable work state (`.forgeloop/task-state/<taskKey>/work-state.json`) and preflight status (`.forgeloop/task-state/<taskKey>/preflight.json`). If preflight reports `BLOCKED`, inspect the required gates in the output and satisfy them first.
 
+If executable policy artifacts exist under `.forgeloop/policy/`, preflight also captures the effective rules and baseline into `.forgeloop/task-state/<taskKey>/policy-snapshot.json` so later policy drift can be detected. Malformed policy artifacts block preflight with `E_POLICY_INVALID`. See [LOOP_ENGINEERING.md](../LOOP_ENGINEERING.md#executable-policy--autonomy-preserving-invariants).
+
 ---
 
 ### Step 4 — Activate Session and Plan
@@ -198,10 +200,12 @@ When preflight returns `READY`, ForgeLoop synchronizes resumable work state (`.f
 Create a session activation marker and transition to `PLANNED`:
 
 ```bash
-forgeloop activate --task task-contact-form-001
+forgeloop activate
 forgeloop advance --task task-contact-form-001 --to PLANNED
 ```
 
+`activate` is session-scoped, not task-scoped: it records the current harness session (`.forgeloop/sessions/<sessionId>.json`) and does not accept `--task`.
+
 ---
 
 ### Step 5 — Implement
@@ -237,10 +241,36 @@ forgeloop run-check --task task-contact-form-001 --id lint --requirement "npm ru
 
 If a check fails:
 
-1. Do not repeat the failed check blindly.
-2. Formulate a diagnostic hypothesis.
-3. Apply the correction.
-4. Re-run `forgeloop run-check`.
+1. Advance to `DIAGNOSING`:
+
+   ```bash
+   forgeloop advance --task task-contact-form-001 --to DIAGNOSING
+   ```
+
+2. Record an append-only root-cause diagnosis in the event ledger:
+
+   ```bash
+   forgeloop record-diagnosis \
+     --task task-contact-form-001 \
+     --hypothesis="Form validation regex incorrectly rejects valid domain formats" \
+     --failure-class="VERIFICATION_FAILURE" \
+     --evidence-ref="unit-tests" \
+     --settled-by="All domain validation unit tests pass" \
+     --next-safe-action="Update email domain regex in ContactForm.jsx"
+   ```
+
+3. Advance to `CORRECTING` and apply the fix:
+
+   ```bash
+   forgeloop advance --task task-contact-form-001 --to CORRECTING
+   ```
+
+4. Re-enter `VERIFYING` (advances `verificationCycle` monotonically) and re-run checks:
+
+   ```bash
+   forgeloop advance --task task-contact-form-001 --to VERIFYING
+   forgeloop run-check --task task-contact-form-001 --id unit-tests --requirement "npm test passes for contact form" -- npm test
+   ```
 
 ---
 
@@ -271,7 +301,7 @@ Output:
 {
   "status": "VALID",
   "taskStatus": "COMPLETE",
-  "verificationStatus": "valid"
+  "verificationStatus": "VALID"
 }
 ```
 
@@ -316,9 +346,10 @@ Under `.forgeloop/task-state/<taskKey>/`:
 - `work-state.json`: lifecycle phase and resumption checkpoint;
 - `events.ndjson`: hash-chained append-only event ledger;
 - `executions/*.json`: provenance records for executed verification commands;
-- `execution-receipt.json`: completion evidence and coverage mapping.
+- `execution-receipt.json`: completion evidence and coverage mapping;
+- `policy-snapshot.json`: effective policy and baseline captured at preflight (created when executable policy is configured).
 
-Shared repository artifacts (`sources.json`, `config.json`) remain at `.forgeloop/`.
+Shared repository artifacts (`sources.json`, `config.json`) remain at `.forgeloop/`. When executable policy is configured, its shared artifacts live under `.forgeloop/policy/` (`rules.json`, `baseline.json`, `policy.lock`, `discovery.json`).
 
 ---
 

package/docs/RECIPES.md

@@ -18,6 +18,8 @@ Concise, copy-paste friendly recipes for common ForgeLoop tasks.
 10. [Final Verification Before Pull Request](#recipe-10--final-verification-before-pull-request)
 11. [Run Multi-Task Workflows Concurrently](#recipe-11--run-multi-task-workflows-concurrently)
 12. [Migrate Legacy 1.0 Single-Task Layout](#recipe-12--migrate-legacy-10-single-task-layout)
+13. [Record Decision Settlement Criteria](#recipe-13--record-decision-settlement-criteria)
+14. [Executable Policy, Baseline Ratchet, and Recovery](#recipe-14--executable-policy-baseline-ratchet-and-recovery)
 
 ---
 
@@ -37,7 +39,7 @@ forgeloop route --task task-001 --work code --surface api --risk untrusted-input
 forgeloop preflight --task task-001 --json
 
 # 5. Activate session and plan
-forgeloop activate --task task-001
+forgeloop activate
 forgeloop advance --task task-001 --to PLANNED
 forgeloop advance --task task-001 --to EXECUTING
 ```
@@ -98,16 +100,29 @@ export FORGELOOP_TASK="task-001"
 forgeloop run-check --id unit-tests --requirement "All tests pass" -- npm test
 # Output: status = failed
 
-# 2. Query next action (directs to DIAGNOSE)
-forgeloop next --json
+# 2. Advance to DIAGNOSING
+forgeloop advance --to DIAGNOSING
+
+# 3. Record append-only root-cause diagnosis in ledger
+forgeloop record-diagnosis \
+  --hypothesis="Edge case comparison operator <= instead of < in validator" \
+  --failure-class="VERIFICATION_FAILURE" \
+  --evidence-ref="unit-tests" \
+  --settled-by="Boundary test passes with status 400" \
+  --next-safe-action="Replace <= with < in validator.js"
 
-# 3. Formulate diagnosis and apply code fix in checkout
+# 4. Advance to CORRECTING and apply the fix
+forgeloop advance --to CORRECTING
+
+# 5. Re-enter VERIFYING (advances verificationCycle monotonically)
+forgeloop advance --to VERIFYING
 
-# 4. Re-run verification check
+# 6. Re-run verification check
 forgeloop run-check --id unit-tests --requirement "All tests pass" -- npm test
 
-# 5. Check audit
-forgeloop audit --json
+# 7. Advance to REVIEWING and complete
+forgeloop advance --to REVIEWING
+forgeloop complete --json
 ```
 
 ---
@@ -248,3 +263,47 @@ forgeloop task-migrate --json
 forgeloop task-list --json
 forgeloop status --json
 ```
+
+---
+
+### Recipe 13 — Record Decision Settlement Criteria
+
+```bash
+# 1. Record an append-only settlement criterion bound to the active contract
+forgeloop record-decision-criterion \
+  --task task-001 \
+  --decision="Which authentication provider should be used?" \
+  --settled-by="Use provider with native support for current JWT session tokens"
+
+# 2. Inspect next action (surfaces the guidance)
+forgeloop next --task task-001
+```
+
+---
+
+### Recipe 14 — Executable Policy, Baseline Ratchet, and Recovery
+
+```bash
+# 1. Discover architecture conventions and candidate rules
+#    (read-only observation; add --write to persist discovery and regenerate the lock)
+forgeloop policy-discover --json
+
+# 2. Record pre-existing debt into brownfield baseline
+forgeloop baseline --record --json
+
+# 3. Check policy verification status and lock integrity
+forgeloop policy-status --json
+
+# 4. Prove checker efficacy against mutation fixtures
+forgeloop rule-verify --rule SECURITY.NO_HARDCODED_SECRET --json
+
+# 5. Ratchet down baseline as debt is resolved during task
+forgeloop baseline --update --json
+
+# 6. If policy weakens mid-task, inspect next recovery action
+forgeloop next --task task-001 --json
+# Follow returned action (e.g. RESTORE_POLICY, REPAIR_CHECKER, REPAIR_POLICY)
+
+# Intentional operator-authorized baseline reset (not normal recovery)
+forgeloop baseline --record --policy-reset-authorized --json
+```

package/docs/TROUBLESHOOTING.md

@@ -8,6 +8,8 @@ This guide provides symptom-first recovery procedures for common ForgeLoop proto
 
 - [`preflight` is `BLOCKED`](#symptom-preflight-is-blocked)
 - [`forgeloop next` returns `RESOLVE_BLOCKER`](#symptom-forgeloop-next-returns-resolve_blocker)
+- [`forgeloop next` returns `RECORD_DIAGNOSIS`](#symptom-forgeloop-next-returns-record_diagnosis)
+- [Progress is `STALLED` or `forgeloop next` returns `CHANGE_STRATEGY`](#symptom-progress-is-stalled)
 - [Protocol state or contract is `STALE`](#symptom-state-or-contract-is-stale)
 - [Execution continuity is `STALE`](#symptom-continuity-is-stale)
 - [Multiple tasks ambiguous (`E_TASK_AMBIGUOUS`)](#symptom-multiple-tasks-ambiguous)
@@ -16,6 +18,11 @@ This guide provides symptom-first recovery procedures for common ForgeLoop proto
 - [Execution reference invalid (`E_EXECUTION_REF_INVALID`)](#symptom-execution-reference-invalid)
 - [`forgeloop complete` returns `INCOMPLETE`](#symptom-forgeloop-complete-returns-incomplete)
 - [`forgeloop complete` returns `INVALID`](#symptom-forgeloop-complete-returns-invalid)
+- [Policy lock mismatch (`E_POLICY_LOCK_MISMATCH`)](#symptom-policy-lock-mismatch)
+- [Invalid policy artifacts fail closed (`E_POLICY_INVALID`)](#symptom-invalid-policy-artifacts-fail-closed)
+- [Policy weakening detected (`E_POLICY_WEAKENING`)](#symptom-policy-weakening-detected)
+- [Baseline re-record blocked during active task (`E_BASELINE_RECORD_DURING_ACTIVE_TASK`)](#symptom-baseline-re-record-blocked-during-active-task)
+- [Mutation checker execution error (`E_CHECK_MUTATION_EXECUTION_ERROR`)](#symptom-mutation-checker-execution-error)
 - [Another harness cannot resume the task](#symptom-another-harness-cannot-resume)
 - [Stable Error & Reason Code Reference](#stable-error-and-reason-codes)
 
@@ -27,26 +34,30 @@ This guide provides symptom-first recovery procedures for common ForgeLoop proto
 
 #### What it means
 
-Pre-implementation gates (e.g. `design`, `threat-boundary`) are unsatisfied, missing, or referencing stale files.
+Pre-implementation gates (e.g. `design`, `threat-boundary`) are unsatisfied, missing, or referencing stale files, or the contract contains unresolved blocking decisions. ForgeLoop preserves specific preflight error codes (`E_CONTRACT_UNRESOLVED_DECISION`, `E_CONTRACT_STALE`, `E_ROUTE_STALE`, `E_GATE_UNVERIFIED`) in `reasons` instead of reducing them to generic readiness errors.
 
 #### Likely causes
 
-1. A gate required by an activated guide has no corresponding `.forgeloop/task-state/<taskKey>/gates/<gate>.json` file.
-2. The gate artifact references files whose SHA-256 hashes changed after the gate was satisfied.
-3. Contract `unresolvedDecisions` contains blocking decisions.
+1. A gate required by an activated guide has no corresponding `.forgeloop/task-state/<taskKey>/gates/<gate>.json` file (`E_GATE_UNVERIFIED`).
+2. The gate artifact references files whose SHA-256 hashes changed after the gate was satisfied (`E_GATE_STALE`).
+3. Contract `unresolvedDecisions` contains blocking decisions (`E_CONTRACT_UNRESOLVED_DECISION`).
 
 #### Inspect
 
 ```bash
 forgeloop task-show --task <id> --json
 forgeloop preflight --task <id> --json
+forgeloop next --task <id> --json
 ```
 
 #### Safe recovery
 
 1. If a gate is missing, satisfy required gates or create the gate artifact with status `"satisfied"`.
 2. If an artifact hash changed, update the artifact SHA-256 in the gate file.
-3. Re-run `forgeloop preflight --task <id> --json`.
+3. If `unresolvedDecisions` contains blocking items:
+   - Record settlement guidance with `forgeloop record-decision-criterion --decision="..." --settled-by="..."` to provide context.
+   - Resolve or remove the blocking decision in `contract.json`.
+4. Re-run `forgeloop preflight --task <id> --json`.
 
 #### Do not
 
@@ -77,7 +88,75 @@ forgeloop next --task <id> --json
 
 1. Check the `reasons` field in the `forgeloop next --json` output.
 2. Follow the suggested command in `commands` or `commandSpecs`.
-3. If in `VERIFYING` after a failure, record a hypothesis, apply the fix, and re-run `run-check`.
+3. If in `VERIFYING` after a failure, advance to `DIAGNOSING`, record a diagnosis with `forgeloop record-diagnosis`, and advance to `CORRECTING`.
+
+---
+
+### Symptom: `forgeloop next` returns `RECORD_DIAGNOSIS`
+
+#### What it means
+
+The task is in `DIAGNOSING` phase following a verification failure, but no append-only diagnosis event (`DIAGNOSIS_RECORDED`) has been recorded for the active verification cycle (`E_DIAGNOSIS_REQUIRED`).
+
+#### Likely causes
+
+1. A check failed in `VERIFYING` and the phase was advanced to `DIAGNOSING` without calling `record-diagnosis`.
+2. An attempt was made to advance directly to `CORRECTING` without recording an evidence-backed root cause hypothesis.
+
+#### Inspect
+
+```bash
+forgeloop status --task <id> --json
+forgeloop next --task <id> --json
+```
+
+#### Safe recovery
+
+Record an append-only diagnosis referencing at least one failed or blocked check from the current verification cycle:
+
+```bash
+forgeloop record-diagnosis --task <id> \
+  --hypothesis="Root cause explanation" \
+  --failure-class="VERIFICATION_FAILURE" \
+  --evidence-ref="failed-check-id" \
+  --settled-by="Observable condition that settles the hypothesis" \
+  --next-safe-action="Smallest safe action to address the hypothesis"
+```
+
+Then advance to `CORRECTING`:
+
+```bash
+forgeloop advance --task <id> --to CORRECTING
+```
+
+---
+
+### Symptom: Progress is `STALLED`
+
+#### What it means
+
+Deterministic progress evaluation detected that iterative correction cycles are not advancing (`E_PROGRESS_STALLED`). The latest diagnosis produced `informationGain: NONE` (signal `NO_DIAGNOSTIC_INFORMATION_GAIN`), or a specific contract requirement failed across 3+ verification cycles with an identical diagnosis (`REPEATED_FAILURE_WITH_SAME_DIAGNOSIS`).
+
+#### Likely causes
+
+1. A recorded diagnosis in a new cycle repeated the previous hypothesis with the exact same evidence references (`informationGain: NONE`). Note: technical retries within the *same* cycle are idempotent and do not cause stalls, but repeating in a *new* cycle does.
+2. The same requirement has repeatedly failed across 3 or more verification cycles with unchanged diagnostic hypotheses.
+3. Minor cosmetic changes were made to `settledBy` or `nextSafeAction` without changing the root hypothesis or evidence references.
+
+#### Inspect
+
+```bash
+forgeloop progress --task <id> --json
+forgeloop next --task <id> --json
+```
+
+#### Safe recovery
+
+1. When stalled, `forgeloop next` returns `nextAction: "CHANGE_STRATEGY"` with error code `E_PROGRESS_STALLED`.
+2. Do not repeat the same retry or correction action.
+3. Re-examine the failure evidence from a new angle or gather fresh diagnostic evidence.
+4. Formulate a genuinely new root-cause hypothesis with new evidence references and record it with `forgeloop record-diagnosis`.
+5. Once a diagnosis with positive information gain (`NEW_HYPOTHESIS`, `NEW_EVIDENCE`, `NEW_HYPOTHESIS_AND_EVIDENCE`) is recorded, `forgeloop next` returns `CORRECT` and status returns to `ADVANCING`.
 
 ---
 
@@ -116,6 +195,40 @@ forgeloop status --task <id> --json
 
 ---
 
+### Symptom: `EXECUTING` task is stale because the repository moved (`E_REPOSITORY_CHANGED`)
+
+#### What it means
+
+A task entered `EXECUTING` at an older checkout and the repository HEAD changed (commit, merge, or checkout). The work-state checkpoint fingerprint no longer matches, so transitions and completion are fail-closed with `E_REPOSITORY_CHANGED` / `E_STATE_REVALIDATION_REQUIRED`. This is intentional: execution must not silently continue against different code.
+
+If the task's objective is already satisfied by the current repository (for example, the work was merged by another change), the checkpoint can be reconciled with executed evidence:
+
+```bash
+forgeloop reconcile-closure --task <id> --id <verification-id> \
+  --requirement "<exact contract verification text>" -- <command>
+```
+
+`reconcile-closure` requires:
+
+1. The task is `EXECUTING`.
+2. The only drift is `REPOSITORY_CHANGED` (contract or required-artifact drift stays blocked).
+3. The append-only event ledger is valid.
+4. `--id` and `--requirement` exactly match a `VERIFICATION` item of the task contract, and the executed command exits 0, proving the objective is present in the current repository.
+
+It then appends a `CHECKPOINT_RECONCILED` ledger event (previous/current repository fingerprints plus the evidence) and refreshes the work-state repository fingerprint. Closure still goes through the canonical pipeline:
+
+```bash
+forgeloop advance --task <id> --to VERIFYING
+forgeloop prepare-completion --task <id>
+forgeloop run-check --task <id> --id <id> --requirement "<text>" -- <command>
+forgeloop advance --task <id> --to REVIEWING
+forgeloop complete --task <id>
+```
+
+Write claims release only when completion is validator-backed (`COMPLETE`).
+
+---
+
 ### Symptom: Continuity is `STALE`
 
 #### What it means
@@ -292,6 +405,133 @@ Inspect the specific error reported in `errors[]` and correct the inconsistent a
 
 ---
 
+### Symptom: Policy Lock Mismatch
+
+#### Error Code: `E_POLICY_LOCK_MISMATCH`
+
+#### What it means
+
+The persisted `.forgeloop/policy/policy.lock` digest or required subdigests (`rulesDigest`, `baselineDigest`, `algorithm`) do not match current effective rules or baseline.
+
+#### Inspect
+
+```bash
+forgeloop policy-status --json
+```
+
+#### Safe recovery
+
+1. If rules or baseline were legitimately modified, re-evaluate and update the lock via discovery/baseline commands:
+
+   ```bash
+   forgeloop policy-discover --write --json
+   forgeloop baseline --update --json
+   ```
+
+2. If modifications were unintentional, restore the previous `.forgeloop/policy/rules.json` or `.forgeloop/policy/baseline.json`.
+
+3. Follow `forgeloop next --json` if returned recovery action is `RESTORE_POLICY`.
+
+---
+
+### Symptom: Invalid Policy Artifacts Fail Closed
+
+#### Error Code: `E_POLICY_INVALID`
+
+#### What it means
+
+One or more executable policy artifacts (`.forgeloop/policy/rules.json`, `.forgeloop/policy/baseline.json`, `.forgeloop/policy/discovery.json`, or `.forgeloop/policy/policy.lock`) is present but malformed or fails schema validation. ForgeLoop does not silently ignore corrupt policy: preflight and completion fail closed.
+
+#### Inspect
+
+```bash
+forgeloop policy-status --json
+```
+
+#### Safe recovery
+
+1. Validate each policy artifact against its schema and repair the malformed JSON or invalid fields.
+
+2. Re-run preflight:
+
+   ```bash
+   forgeloop preflight --task <id> --json
+   ```
+
+3. Follow `forgeloop next --task <id> --json` if the returned recovery action is `REPAIR_POLICY`.
+
+---
+
+### Symptom: Policy Weakening Detected
+
+#### Error Code: `E_POLICY_WEAKENING`
+
+#### What it means
+
+Policy rules were relaxed or baseline debt expanded after the task policy snapshot was captured during preflight.
+
+#### Safe recovery
+
+1. Inspect the policy diff:
+
+   ```bash
+   forgeloop policy-diff --task <id> --json
+   ```
+
+2. Restore the original policy configuration captured in `.forgeloop/task-state/<taskKey>/policy-snapshot.json`.
+
+3. Re-query `forgeloop next --task <id> --json` (returns `RESTORE_POLICY`).
+
+---
+
+### Symptom: Baseline Re-Record Blocked During Active Task
+
+#### Error Code: `E_BASELINE_RECORD_DURING_ACTIVE_TASK`
+
+#### What it means
+
+`forgeloop baseline --record` was executed during an active task bound to a preflight policy snapshot. Re-recording during active tasks is blocked to prevent converting new violations into accepted debt.
+
+#### Safe recovery
+
+1. Fix newly introduced violations instead of recording them into baseline debt.
+
+2. If resolving legacy debt, use monotonic ratchet-down:
+
+   ```bash
+   forgeloop baseline --update --json
+   ```
+
+3. If an intentional full baseline re-recording is authorized by an operator, supply the explicit authority flag:
+
+   ```bash
+   forgeloop baseline --record --policy-reset-authorized --json
+   ```
+
+---
+
+### Symptom: Mutation Checker Execution Error
+
+#### Error Code: `E_CHECK_MUTATION_EXECUTION_ERROR`
+
+#### What it means
+
+A policy rule checker threw an unhandled exception while evaluating its synthetic mutation fixture during `rule-verify`. A crashing checker cannot prove its mutation detection efficacy.
+
+#### Safe recovery
+
+1. Inspect the checker error stack and adapter implementation:
+
+   ```bash
+   forgeloop rule-verify --rule <rule-id> --json
+   ```
+
+2. Repair the unhandled exception path in the checker adapter.
+
+3. Re-run `forgeloop rule-verify --rule <rule-id> --json` until the mutation is proven (`PROVEN`).
+
+---
+
 ### Symptom: Another Harness Cannot Resume
 
 #### Likely causes
@@ -341,5 +581,38 @@ forgeloop next --task <id> --json
 | `E_TASK_SCOPE_CONFLICT` | Task write claims overlap with another non-complete task in the same checkout. | Adjust write claims to non-overlapping paths or run tasks in separate worktrees. |
 | `E_TASK_SCOPE_DIRTY` | Claimed paths contain pre-existing uncommitted changes. | Commit or stash changes in claimed paths before defining or adopting the scope. |
 | `E_TASK_CHANGE_OUTSIDE_SCOPE` | Modified paths in repository exceed the declared task write claims. | Update write claims with forgeloop task-scope or revert out-of-scope modifications. |
+| `E_RECONCILE_NOT_STALE` | reconcile-closure was invoked for a work-state checkpoint that is already fresh. | No reconciliation is required; continue the normal lifecycle. |
+| `E_RECONCILE_PHASE_INVALID` | reconcile-closure was invoked for a task that is not EXECUTING. | reconcile-closure supports EXECUTING tasks whose objective is already satisfied. |
+| `E_RECONCILE_UNSUPPORTED_DRIFT` | Work-state drift includes kinds other than REPOSITORY_CHANGED (contract or required-artifact drift). | Resolve contract or artifact drift through their dedicated recovery surfaces; reconcile-closure only refreshes repository fingerprint drift. |
+| `E_RECONCILE_LEDGER_INVALID` | The append-only event ledger is not valid, so reconciliation cannot be recorded. | Inspect the ledger errors and repair before reconciling. |
+| `E_RECONCILE_REQUIREMENT_UNKNOWN` | The supplied check id and requirement text do not exactly match a contract verification item of type VERIFICATION. | Supply the exact id and requirement text of an existing contract verification item. |
+| `E_RECONCILE_EVIDENCE_FAILED` | The executed objective-satisfaction evidence command did not pass. | Inspect the execution artifact; reconciliation is refused until evidence passes in the current repository. |
+| `E_REPOSITORY_CHANGED` | The repository fingerprint (branch or HEAD) moved after the work-state checkpoint was recorded. | If the task objective is already satisfied in the current repository, run forgeloop reconcile-closure; otherwise resume from a checkpoint that matches the current repository. |
+| `E_STATE_REVALIDATION_REQUIRED` | The work-state checkpoint must be revalidated before the lifecycle can continue. | Run forgeloop reconcile-closure for externally satisfied EXECUTING tasks, or inspect the freshness reasons for other drift. |
+| `E_DIAGNOSIS_REQUIRED` | Current correction cycle has no append-only diagnosis record. | Run forgeloop record-diagnosis with current failed evidence before correcting. |
+| `E_DIAGNOSIS_INVALID` | Diagnosis record details or parameters are malformed. | Provide valid failureClass, hypothesis, evidenceRefs, settledBy, and nextSafeAction. |
+| `E_DIAGNOSIS_EVIDENCE_INVALID` | Referenced diagnosis evidence is missing or has no failed checks in the current cycle. | Reference at least one failed or blocked check ID from the active verification cycle. |
+| `E_DIAGNOSIS_CYCLE_MISMATCH` | Diagnosis verification cycle does not match the active work state verification cycle. | Record diagnosis for the current active verification cycle. |
+| `E_DIAGNOSIS_NO_NEW_INFORMATION` | The proposed retry repeats the previous hypothesis with the same evidence. | Change the hypothesis, collect independent evidence, or change strategy. |
+| `E_PROGRESS_STALLED` | Persisted correction history shows no new diagnostic information. | Use an independent check, revisit assumptions, or record a materially different diagnosis. |
+| `E_DECISION_CRITERION_INVALID` | Decision settlement criterion details or parameters are malformed. | Provide non-empty decision text and settledBy criterion. |
+| `E_DECISION_NOT_UNRESOLVED` | A settlement criterion referenced a decision not present in current unresolvedDecisions. | Use the exact current unresolved decision text or update the contract first. |
+| `E_CHECK_INERT` | An enabled check has no effective scope or target files. | Provide an applicable target scope, configure matching files, or mark the rule unsupported. |
+| `E_CHECK_MUTATION_NOT_DETECTED` | A blocking rule checker failed to detect an intentional mutation fixture. | Fix checker logic to properly identify target violations. |
+| `E_POLICY_DRIFT` | Active policy lock does not match the policy snapshot captured at task activation. | Re-verify affected checks or restore original policy. |
+| `E_POLICY_WEAKENING` | Policy rules were weakened during task execution without explicit authority. | Restore the original policy configuration. |
+| `E_POLICY_LOCK_INVALID` | Policy lockfile is missing, malformed, or corrupt. | Run forgeloop policy-status or regenerate policy.lock. |
+| `E_NEW_POLICY_VIOLATION` | New executable policy violation detected that is not present in brownfield baseline. | Fix the violation before completing the task. |
+| `E_BASELINE_EXPANSION` | Attempted unauthorized addition of new violations to brownfield baseline. | Resolve new violations rather than expanding the baseline. |
+| `E_POLICY_PROOF_STALE` | Mutation verification proof is stale due to checker or fixture modifications. | Re-run forgeloop rule-verify to refresh mutation proof. |
+| `E_CHECK_MUTATION_EXECUTION_ERROR` | A policy checker threw an unhandled exception while evaluating its mutation fixture. | Repair the checker execution path and rerun rule verification. |
+| `E_POLICY_EVALUATION_FAILED` | Policy evaluation threw an unexpected error during execution. | Inspect policy configuration and checker adapters for unhandled errors. |
+| `E_POLICY_INVALID` | Policy artifact is malformed, corrupt, or schema-invalid. | Validate and repair rules.json, baseline.json, or discovery.json against schema. |
+| `E_POLICY_SNAPSHOT_WRITE_FAILED` | Failed to persist task policy snapshot during preflight. | Ensure the target task directory is writable and repair filesystem permissions. |
+| `E_POLICY_LOCK_MISMATCH` | Persisted policy lock digest does not match current effective policy state. | Re-evaluate effective rules and update policy.lock or restore modified rules. |
+| `E_POLICY_DRIFT_UNKNOWN` | Task policy drift was detected but baseline snapshot details are unavailable. | Re-verify the task under the current policy state. |
+| `E_BASELINE_RECORD_DURING_ACTIVE_TASK` | Cannot re-record baseline during an active task with policy snapshot. | Resolve new violations or use monotonic baseline --update. |
+| `E_POLICY_INITIALIZATION_FAILED` | Executable policy bootstrap could not complete during initialization. | Repair the reported filesystem/schema error and rerun `forgeloop init`. Initialization is restartable while no committed manifest exists. |
+| `E_INIT_KIT_CONFLICT` | A canonical ForgeLoop kit destination already exists with content that does not match the shipped canonical template. | Inspect the conflicting `.forgeloop/kit/...` file. If it is stale or partial ForgeLoop output, remove or restore it and rerun `forgeloop init`. Do not overwrite unknown content automatically. |
 
 <!-- END FORGELOOP GENERATED: public-error-codes -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cassiomc1/forgeloop",
-  "version": "1.1.1",
+  "version": "1.2.2",
   "description": "Portable, verifiable engineering protocol for AI coding environments and developer workflows",
   "repository": {
     "type": "git",

package/schemas/policy-baseline.schema.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "forgeloop://schemas/policy-baseline.schema.json",
+  "title": "ForgeLoop policy baseline",
+  "type": "object",
+  "required": ["schemaVersion", "createdAt", "entries"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "createdAt": { "type": "string", "minLength": 1 },
+    "entries": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["ruleId", "fingerprints"],
+        "properties": {
+          "ruleId": { "type": "string", "minLength": 1 },
+          "fingerprints": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+          "reviewBy": { "type": "string" },
+          "details": { "type": "array", "items": { "type": "object" } }
+        },
+        "additionalProperties": true
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/policy-discovery.schema.json

@@ -0,0 +1,45 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "forgeloop://schemas/policy-discovery.schema.json",
+  "title": "ForgeLoop policy discovery result",
+  "type": "object",
+  "required": ["schemaVersion", "languages", "testing", "linting", "architecture", "discoveredRules"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "languages": { "type": "array", "items": { "type": "string" } },
+    "testing": {
+      "type": "object",
+      "required": ["detected", "confidence"],
+      "properties": {
+        "detected": { "type": "boolean" },
+        "command": { "type": "array", "items": { "type": "string" } },
+        "framework": { "type": "string" },
+        "confidence": { "enum": ["HIGH", "MEDIUM", "LOW", "UNKNOWN"] }
+      },
+      "additionalProperties": true
+    },
+    "linting": {
+      "type": "object",
+      "required": ["detected", "confidence"],
+      "properties": {
+        "detected": { "type": "boolean" },
+        "command": { "type": "array", "items": { "type": "string" } },
+        "tool": { "type": "string" },
+        "confidence": { "enum": ["HIGH", "MEDIUM", "LOW", "UNKNOWN"] }
+      },
+      "additionalProperties": true
+    },
+    "architecture": {
+      "type": "object",
+      "required": ["confidence", "enforcement"],
+      "properties": {
+        "value": { "type": ["string", "null"] },
+        "confidence": { "enum": ["HIGH", "MEDIUM", "LOW", "UNKNOWN"] },
+        "enforcement": { "enum": ["BLOCKING", "ADVISORY", "NONE"] }
+      },
+      "additionalProperties": true
+    },
+    "discoveredRules": { "type": "array", "items": { "type": "object" } }
+  },
+  "additionalProperties": false
+}

package/schemas/policy-lock.schema.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "forgeloop://schemas/policy-lock.schema.json",
+  "title": "ForgeLoop policy lockfile",
+  "type": "object",
+  "required": ["schemaVersion", "algorithm", "digest", "rulesDigest", "baselineDigest"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "algorithm": { "const": "sha256" },
+    "digest": { "type": "string", "minLength": 1 },
+    "rulesDigest": { "type": "string" },
+    "baselineDigest": { "type": "string" },
+    "capturedAt": { "type": "string" }
+  },
+  "additionalProperties": false
+}