@cassiomc1/forgeloop 1.2.1 → 1.2.3

package/docs/DOCUMENTATION_GUIDE.md

@@ -35,6 +35,10 @@ Documentation routing   -> DOCS_INDEX.md
 
 Operational documentation must explain canonical behavior, not redefine it.
 
+Canonical phase and transition inventories must be derived from `WORK_PHASES`
+and `WORK_TRANSITIONS`; do not maintain independent hand-written transition
+enums when a generated or mechanically validated representation is available.
+
 ---
 
 ## 3. Generated Documentation Provenance & Pipeline
@@ -60,10 +64,11 @@ cross-platform CI (.github/workflows/docs-quality.yml)
 | Fact Category | Canonical Machine Source | Generated Target File | Generated Region Marker |
 | --- | --- | --- | --- |
 | **Artifact Inventory** | `ARTIFACT_REGISTRY` (`src/core/artifact-registry.js`) | `docs/ARTIFACT_REFERENCE.md` | `<!-- BEGIN FORGELOOP GENERATED: artifact-registry -->` |
-| **Artifact Fields** (12 schemas) | `schemas/*.schema.json` | `docs/ARTIFACT_REFERENCE.md` | `<!-- BEGIN FORGELOOP GENERATED: schema:<name> -->` |
+| **Artifact Fields** | `schemas/*.schema.json` | `docs/ARTIFACT_REFERENCE.md` | `<!-- BEGIN FORGELOOP GENERATED: schema:<name> -->` |
 | **CLI Command Index** | `CLI_COMMAND_DEFINITIONS` (`src/core/cli-command-definitions.js`) | `docs/CLI_REFERENCE.md` | `<!-- BEGIN FORGELOOP GENERATED: cli-command-index -->` |
 | **CLI Common Options** | `CLI_COMMAND_DEFINITIONS` (`src/core/cli-command-definitions.js`) | `docs/CLI_REFERENCE.md` | `<!-- BEGIN FORGELOOP GENERATED: cli-common-options -->` |
-| **CLI Command Options** (27 commands) | `CLI_COMMAND_DEFINITIONS` (`src/core/cli-command-definitions.js`) | `docs/CLI_REFERENCE.md` | `<!-- BEGIN FORGELOOP GENERATED: cli:<command>:options -->` |
+| **CLI Command Options** | `CLI_COMMAND_DEFINITIONS` (`src/core/cli-command-definitions.js`) | `docs/CLI_REFERENCE.md` | `<!-- BEGIN FORGELOOP GENERATED: cli:<command>:options -->` |
+| **Work-State Transitions** | `WORK_PHASES` / `WORK_TRANSITIONS` (`src/core/protocol.js`) | `ORCHESTRATOR_INTEGRATION.md` | `<!-- BEGIN FORGELOOP GENERATED: work-transitions -->` |
 | **Public Error Codes** | `PUBLIC_ERROR_CODES` (`src/core/error-codes.js`) | `docs/TROUBLESHOOTING.md` | `<!-- BEGIN FORGELOOP GENERATED: public-error-codes -->` |
 | **Architecture Flow** | `docs/forgeloop-flow.mmd` | `docs/assets/forgeloop-flow.svg` | Verified via embedded SHA-256 fingerprint |
 
@@ -82,6 +87,11 @@ npm test
 npm run docs:check
 ```
 
+Do not hard-code inventory totals in prose or headings. Counts of commands,
+schemas, fields, and public codes are derived from the registries and schemas;
+when those sources change, regenerate the reference documents and let the
+conformance checks detect omissions.
+
 ---
 
 ## 4. Documentation Conformance Matrix
@@ -93,9 +103,10 @@ npm run docs:check
 | **Artifact fields & types** | `schemas/*.schema.json` | `scripts/validate_documentation_conformance.mjs` |
 | **Enums & consts** | `schemas/*.schema.json` | `scripts/validate_documentation_conformance.mjs` |
 | **Lifecycle phases** | `WORK_PHASES` (`src/core/protocol.js`) | `scripts/validate_documentation_conformance.mjs` |
+| **Lifecycle transitions** | `WORK_TRANSITIONS` (`src/core/protocol.js`) + the special `BLOCKED` rule | `scripts/generate_documentation_reference.mjs` and `scripts/validate_documentation_conformance.mjs` |
 | **Stable error codes** | `PUBLIC_ERROR_CODES` (`src/core/error-codes.js`) | `scripts/validate_documentation_conformance.mjs` |
 | **Discovery resume rules** | `DISCOVERY_SURFACES` & `nativeShim` | `scripts/validate_documentation_conformance.mjs` |
-| **Operational path freshness** | `OPERATIONAL_DOCUMENTS` & `task-paths.js` | `scripts/validate_documentation_conformance.mjs` |
+| **Task-layout path freshness** | `TASK_LAYOUT_DOCUMENTS` & `task-paths.js` | `scripts/validate_documentation_conformance.mjs` |
 | **Package-shipped docs** | `package.json` (`files`) | `tests/package.test.js` |
 | **Architecture diagram** | `docs/forgeloop-flow.mmd` | `scripts/check-generated-diagram.mjs` |
 
@@ -116,6 +127,7 @@ Avoid ambiguous phrases like *"should generally"* or *"usually"* for behaviors t
 
 - Canonical task-scoped paths are defined in `src/core/task-paths.js` under `.forgeloop/task-state/<taskKey>/`.
 - Operational guides (`README.md`, `GETTING_STARTED.md`, `RECIPES.md`, `CROSS_HARNESS_CONTINUITY.md`, `TROUBLESHOOTING.md`) must document namespaced paths by default.
+- Architecture/integration documents (`LOOP_SYSTEM_DESIGN.md`, `ORCHESTRATOR_INTEGRATION.md`) are covered by the same task-layout conformance scope (`TASK_LAYOUT_DOCUMENTS`).
 - Legacy ForgeLoop 1.0 singleton paths (e.g. `.forgeloop/current-contract.json`) are permitted **only** inside explicit legacy migration regions:
 
   ```markdown
@@ -145,7 +157,32 @@ Avoid ambiguous phrases like *"should generally"* or *"usually"* for behaviors t
 
 ---
 
-## 8. Documentation Change Checklist for Pull Requests
+## 8. README Hero and Package Boundary
+
+README hero assets are branding/conceptual illustrations. They are not the
+canonical protocol diagram. `docs/forgeloop-flow.mmd` remains the canonical
+architecture flow source and `docs/assets/forgeloop-flow.svg` remains its
+generated render.
+
+The README hero is intentionally GitHub-repository-only:
+
+- `README.md` may reference `docs/assets/eng_readme_forgeloop.png`; GitHub
+  renders it from the repository.
+- The hero PNG is excluded from the npm package (`package.json` `files`), and
+  `tests/package.test.js` asserts that exclusion so it cannot be silently
+  re-included.
+- The packaged README is therefore not self-contained for that relative hero
+  path; do not claim otherwise.
+- If a portable hero is ever shipped, any relative README asset referenced by
+  packaged Markdown must be present in the package and covered by
+  `tests/package.test.js`.
+
+Never delete `docs/assets/forgeloop-flow.svg`; it is generator-owned output of
+the diagram workflow.
+
+---
+
+## 9. Documentation Change Checklist for Pull Requests
 
 For documentation-impacting changes, verify each item before merging:
 

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
@@ -297,7 +301,7 @@ Output:
 {
   "status": "VALID",
   "taskStatus": "COMPLETE",
-  "verificationStatus": "valid"
+  "verificationStatus": "VALID"
 }
 ```
 
@@ -342,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

@@ -19,6 +19,7 @@ Concise, copy-paste friendly recipes for common ForgeLoop tasks.
 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)
 
 ---
 
@@ -38,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
 ```
@@ -277,3 +278,32 @@ forgeloop record-decision-criterion \
 # 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

@@ -18,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)
 
@@ -190,6 +195,40 @@ forgeloop status --task <id> --json
 
 ---
 
+### Symptom: `EXECUTING`/`VERIFYING` 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` or `VERIFYING` (later phases are not reconcilable; work must return to a verification phase first).
+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
@@ -366,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
@@ -415,6 +581,14 @@ 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 or VERIFYING. | reconcile-closure supports EXECUTING or VERIFYING 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. |
@@ -423,5 +597,22 @@ forgeloop next --task <id> --json
 | `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.2.1",
+  "version": "1.2.3",
   "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
+}

package/schemas/policy-rules.schema.json

@@ -0,0 +1,48 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "forgeloop://schemas/policy-rules.schema.json",
+  "title": "ForgeLoop executable policy rules",
+  "type": "object",
+  "required": ["schemaVersion", "rules"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "rules": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "severity", "source", "blocking", "why", "fix", "check"],
+        "properties": {
+          "id": { "type": "string", "minLength": 1 },
+          "severity": { "enum": ["HIGH", "MEDIUM", "LOW", "INFO"] },
+          "source": { "enum": ["builtin", "discovered", "project"] },
+          "blocking": { "type": "boolean" },
+          "why": { "type": "string", "minLength": 1 },
+          "fix": { "type": "string", "minLength": 1 },
+          "confidence": { "enum": ["HIGH", "MEDIUM", "LOW", "UNKNOWN"] },
+          "scope": {
+            "type": "object",
+            "properties": {
+              "includes": { "type": "array", "items": { "type": "string" } },
+              "excludes": { "type": "array", "items": { "type": "string" } }
+            },
+            "additionalProperties": false
+          },
+          "check": {
+            "type": "object",
+            "required": ["type"],
+            "properties": {
+              "type": { "type": "string", "minLength": 1 },
+              "adapter": { "type": "string" },
+              "command": { "type": "array", "items": { "type": "string" } },
+              "threshold": { "type": "number" },
+              "parameters": { "type": "object" }
+            },
+            "additionalProperties": true
+          }
+        },
+        "additionalProperties": true
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/policy-snapshot.schema.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "forgeloop://schemas/policy-snapshot.schema.json",
+  "title": "ForgeLoop task policy snapshot",
+  "type": "object",
+  "required": ["schemaVersion", "policyDigest", "rules"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "policyDigest": { "type": "string", "minLength": 1 },
+    "rules": { "type": "array", "items": { "type": ["string", "object"] } },
+    "baseline": { "type": "object" },
+    "baselineDigest": { "type": "string" },
+    "capturedAt": { "type": "string" }
+  },
+  "additionalProperties": false
+}