@cassiomc1/forgeloop 1.1.1 → 1.2.2

package/README.md

@@ -1,7 +1,7 @@
 # ForgeLoop — Verifiable Engineering Protocol
 
 <p align="center">
-  <img src="./docs/assets/forgeloop-readme-banner.svg" alt="ForgeLoop — Verifiable Engineering Protocol" width="100%">
+  <img src="./docs/assets/eng_readme_forgeloop.png" alt="ForgeLoop — Loop Engineering for AI Agents" width="100%">
 </p>
 
 [![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)
@@ -96,7 +96,7 @@ Typical local commands are:
 ```bash
 forgeloop task-create --task example-task --claim src --claim tests --json
 forgeloop route --task example-task --work complete-website --surface ui --risk untrusted-input
-forgeloop activate --task example-task
+forgeloop activate
 forgeloop preflight --task example-task --json
 forgeloop next --task example-task --json
 forgeloop advance --task example-task --to PLANNED
@@ -112,10 +112,12 @@ forgeloop complete --task example-task --json
 `advance` changes protocol phase only; it never runs target commands.
 `run-check` classifies the exact argv before launch and records ForgeLoop-owned
 execution provenance. `record-check` stores an observation and never executes
-the text supplied to `--command`. `complete` validates the contract, route,
-gates, ledger, evidence, coverage, receipt, and freshness. `audit` is
-read-only. `report` exposes independent completion, publication, and
-production-readiness dimensions.
+the text supplied to `--command`. `record-diagnosis` appends an authoritative
+root-cause hypothesis to the event ledger. `progress` evaluates task
+progression and detects stalls deterministically. `complete` validates the
+contract, route, gates, ledger, evidence, coverage, receipt, and freshness.
+`audit` is read-only. `report` exposes independent completion, publication,
+and production-readiness dimensions.
 
 The status precedence is `INVALID` > `INCONSISTENT` > `STALE` > `INCOMPLETE` >
 `VALID`. A `READY` preflight is a resumable checkpoint: if its work state is
@@ -158,6 +160,38 @@ forgeloop complete --task auth-feature --json
 forgeloop task-migrate --json
 ```
 
+### Executable policy verification & brownfield baselines
+
+ForgeLoop enforces automated, non-interactive verification rules (`rules.json`) with zero interactive dependencies:
+
+```bash
+# Discover architecture conventions and candidate rules (read-only unless --write)
+forgeloop policy-discover --json
+
+# Inspect active policy verification status, baselines, and drift
+forgeloop policy-status --json
+
+# Record brownfield legacy debt into baseline to prevent blocking
+forgeloop baseline --record --json
+
+# Monotonically ratchet down resolved technical debt
+forgeloop baseline --update --json
+
+# Prove rule checker efficacy against synthetic mutation fixtures
+forgeloop rule-verify --rule SECURITY.NO_HARDCODED_SECRET --json
+```
+
+A policy-bound task captures its effective rules and semantic baseline in
+`.forgeloop/task-state/<taskKey>/policy-snapshot.json`. The project lock at
+`.forgeloop/policy/policy.lock` protects the effective rules plus baseline and
+must contain matching `algorithm`, `digest`, `rulesDigest`, and `baselineDigest`
+values. `capturedAt` is informational metadata and does not change semantic
+identity. During an active task, `baseline --update` may remove resolved debt,
+but `baseline --record` is blocked unless an operator explicitly supplies
+`--policy-reset-authorized`. Use `forgeloop next --task <id> --json` to receive
+semantic recovery such as `RESTORE_POLICY`, `REPAIR_CHECKER`, or
+`RESTORE_BASELINE` when verification detects drift or corruption.
+
 See [`docs/CLI_REFERENCE.md`](./docs/CLI_REFERENCE.md) and [`LOOP_SYSTEM_DESIGN.md`](./LOOP_SYSTEM_DESIGN.md) for architecture details.
 
 ## Architecture flow

package/TERMINOLOGY.md

@@ -25,3 +25,13 @@
 | Execution continuity | Bounded current-task implementation context used to resume the same ForgeLoop task across sessions or harnesses. |
 | Continuity artifact | `.forgeloop/continuity.json`; non-evidence operational context bound to canonical work state. |
 | Continuity reconciliation | Read-only comparison of continuity bindings and path hints against current canonical state and checkout. |
+| Executable policy rule | A structured rule with an automated checker evaluating constraints on code and artifacts. |
+| Policy discovery | Deterministic non-interactive inspection of codebase structure and conventions with confidence levels. |
+| Brownfield baseline | Cryptographically fingerprinted list of pre-existing policy violations tolerated without blocking progress. |
+| Violation fingerprint | SHA-256 hash uniquely identifying a violation by rule, file, and line/content hash. |
+| Monotonic ratchet | Invariant ensuring brownfield baseline debt only decreases as legacy violations are resolved. |
+| Mutation verification | Proving checker capability by asserting failure on intentionally mutated code fixtures. |
+| Proof digest | Cryptographic digest confirming a checker caught a mutation fixture. |
+| Inert check | A verification rule whose check target or scope does not exist or matches 0 files in the codebase. |
+| Policy drift | Divergence between task preflight snapshot policy and current workspace policy. |
+| Policy diff | Semantic classification of policy changes into `TIGHTEN`, `NEUTRAL`, `WEAKEN`, or `UNKNOWN`. |

package/THIRD_PARTY_NOTICES.md

@@ -13,6 +13,22 @@ review the applicable source terms before redistributing such material.
 
 ## Adapted and editorial sources
 
+### Elaya Design — Landing Page Design
+
+- Project:
+  [elayadesign/ai-design-skills](https://github.com/elayadesign/ai-design-skills).
+- Referenced skill:
+  [landing-page-design](https://github.com/elayadesign/ai-design-skills/blob/main/skills/landing-page-design/SKILL.md).
+- License declared by the upstream repository: MIT.
+- Use in this collection: editorial influence for landing-page strategy,
+  conversion structure, proof/objection placement, benefit-first copy, and
+  incremental section-by-section implementation.
+- Boundary: ForgeLoop does not adopt the upstream skill's complete prescriptive
+  visual system as a universal rule, and does not import its intake-question
+  workflow over ForgeLoop's own decision classification. The strategy concepts
+  are paraphrased; if substantial upstream text is copied or adapted in the
+  future, preserve the applicable MIT notice and attribution.
+
 ### A11Y.md
 
 - Project: [fecarrico/A11Y.md](https://github.com/fecarrico/A11Y.md).
@@ -56,6 +72,16 @@ dependencies, version, and distribution conditions before adoption.
   workflow boundaries and public discoverability only.
 - Boundary: this repository links to Superpowers as a reference; it is not a dependency of `ForgeLoop`, and `ForgeLoop` does not copy, bundle, install, or vendor any Superpowers source, skill, hook, plugin, runtime, dependency, credential, or provider.
 
+### React Doctor
+
+- Project: [millionco/react-doctor](https://github.com/millionco/react-doctor).
+- Use in this collection: optional target-project React diagnostic/verifier
+  reference.
+- Boundary: React Doctor is not a ForgeLoop runtime dependency or universal
+  completion gate. ForgeLoop does not automatically download, install, execute,
+  configure, or enable its CI/agent integrations. Verify current upstream
+  license, CLI, telemetry, network behavior, and dependencies before use.
+
 ### Runtime and validator boundary
 
 The distributed CLI and repository validators use Node.js and Python standard
@@ -87,14 +113,27 @@ network behavior, and distribution terms separately.
 
 ## Design reference sites
 
-The following nine sites are references in the design guide. None is a
+The following sites are references in the design guide. None is a
 dependency of this collection or a blanket permission to reuse code, assets,
 fonts, templates, or other material.
 
 - [21st.dev](https://21st.dev/): component and template registry; check the
   terms for the specific author, community contribution, or paid material.
+- [AIcss](https://www.aicss.dev/): AI-agent interface pattern and component
+  reference; verify current terms, provenance, dependencies, and reuse rights
+  for the exact block before copying or redistributing it.
 - [React Bits](https://reactbits.dev/): component and motion reference; keep
   public/free material, React Bits Pro, and dependency terms separate.
+- [beUI](https://beui.dev/) / source
+  [starc007/ui-components](https://github.com/starc007/ui-components):
+  React/Next.js animated component reference; verify current terms, license,
+  Motion/Tailwind dependencies, and accessibility/reduced-motion behavior before
+  adoption.
+- [Transition Kit](https://transition-kit.space/) / source
+  [AbdullahMukadam/Transition-kit](https://github.com/AbdullahMukadam/Transition-kit):
+  CSS-first page/theme transition reference around the View Transitions API;
+  verify current terms, browser compatibility, and fallback behavior before
+  adoption.
 - [Fancy Components](https://www.fancycomponents.dev/): component reference;
   verify the linked source license and each dependency before reuse.
 - [Motion Primitives](https://motion-primitives.com/): motion reference; keep
@@ -112,6 +151,24 @@ fonts, templates, or other material.
 - [cables.gl](https://cables.gl/): creative-coding and WebGL reference; check
   the tool, exported patches or operators, code, and third-party assets
   separately before distribution.
+- [VibePrompt](https://vibeprompts.dev/): optional UI-pattern and prompt
+  reference for comparing common page/component structures. ForgeLoop does not
+  bundle its prompts or snippets and does not make Tailwind a dependency.
+  Verify the site's current terms and the provenance/license of any prompt,
+  snippet, or substantial material before copying or redistributing it.
+- [Kitbitz](https://kitbitz.art/): optional illustration and visual-asset
+  reference. ForgeLoop does not bundle, mirror, or download its assets. Verify
+  the current first-party license and asset-specific terms before use; record
+  attribution when required and preserve asset provenance in the target
+  project. A catalog listing is not a permanent license statement.
+- [DesEngs](https://desengs.com/) / source
+  [remvze/desengs](https://github.com/remvze/desengs):
+  curated meta-directory for design-engineering resources. The upstream
+  DesEngs repository currently declares MIT for its own software/material
+  covered by that license. ForgeLoop uses the site only as an optional discovery
+  index and does not bundle or mirror its catalog. Each external resource linked
+  by DesEngs retains its own license, terms, authorship, dependencies, and
+  premium/free boundary; inspect the exact upstream source before adoption.
 
 ### Qwen-MM-Plugins
 

package/THREAT_MODEL.md

@@ -43,7 +43,18 @@ remaining trust boundaries and their executable evidence.
 | Recursive npm script dispatch | A recognized npm lifecycle script invokes another npm script, which later invokes an installation-capable resolver (e.g. `test` -> `npm run visual` -> `npx package`) | Recognized npm dispatcher semantics before ForgeLoop process launch | Recursive npm-script resolution with cycle detection, maximum depth (16), lifecycle hook inspection, restart special semantics, and fail-closed behavior when the resolver cannot prove the chain is non-installing | Opaque executables may spawn arbitrary descendants. Full descendant-process attestation requires host-level process controls and is outside this release | `tests/run-check.test.js`, `tests/verification-capability.test.js` |
 | npm invocation rewriting and workspace dispatch | npm configuration flags appear before the subcommand, or npm workspace selectors cause script execution to occur against a package.json different from the ForgeLoop target root | Raw npm argv versus effective npm command and execution context | Canonical npm invocation parsing, effective subcommand extraction, workspace flag detection across the full npm argv, and fail-closed workspace script handling when the selected package.json cannot be proven from the current target | ForgeLoop 0.1.15 intentionally does not implement full npm workspace resolution. Users should execute run-check from the selected workspace target directory | `tests/run-check.test.js`, `tests/verification-capability.test.js` |
 | Unclassified npm Install-Capable Command | The npm security classifier recognizes only a small denylist of package-mutating commands. Another official npm command or alias with install/update/bootstrap semantics falls through as a local package command | Effective npm command semantics versus ForgeLoop's command classifier | Semantic npm command classification with explicit install-capable families, explicit script-dispatch families, a deliberately small non-installing allowlist, and fail-closed behavior for unknown or ambiguous npm commands | Future npm commands are blocked until ForgeLoop explicitly classifies them | `tests/verification-capability.test.js`, `tests/run-check.test.js` |
-| npm Option Value Ambiguity | An unknown npm config option with a separate value appears before the effective subcommand, and a parser misinterprets the option value as the npm subcommand | Raw npm argv and unsupported config syntax | Recognize self-contained `--key=value`, explicitly supported options-with-value, and known boolean options. Unknown long option followed by a non-option token fails closed with `NPM_OPTION_VALUE_AMBIGUOUS` | Unsupported npm config grammar is intentionally rejected rather than guessed | `tests/verification-capability.test.js`, `tests/run-check.test.js` |
+| Policy weakening bypass | An actor weakens complexity or security thresholds mid-task to bypass verification failures | Task policy snapshot (`policy-snapshot.json`) and semantic policy diff | `policy-diff` classifies rule relaxations as `WEAKEN`, preflight snapshots enforce baseline digests, and `complete` blocks on `E_POLICY_WEAKENING` | A project operator with local filesystem access can authoritatively update project rules | `tests/policy-autonomy.test.js`, `tests/policy-hardening.test.js` |
+| Inert check evasion | An actor relies on an inert or non-matching checker to create false verification pass | Policy engine checker inspection | Scanned file counters and adapter target checks; unproven or inert project rules trigger `E_CHECK_INERT` | Discovered rules gracefully downgrade to advisory without stopping execution | `tests/policy-autonomy.test.js`, `tests/policy-hardening.test.js` |
+| Baseline debt expansion | An actor expands baseline tolerances during task execution to ignore new violations | Brownfield baseline (`baseline.json`) and violation fingerprints | SHA-256 violation fingerprinting by rule and file content; monotonic ratchet ensures baseline debt only decreases | Operators can intentionally re-record baselines using `forgeloop baseline --record --policy-reset-authorized` | `tests/policy-autonomy.test.js`, `tests/policy-hardening.test.js` |
+| Unproven mutation checker | A broken or mock checker passes regardless of code correctness | Mutation testing runner (`rule-verify`) | Mutation verification runs checks against synthetic mutant fixtures; failure to catch a mutation yields `CHECK_MUTATION_NOT_DETECTED` and `UNPROVEN` status | Mutation fixtures are maintained for standard built-in adapters | `tests/policy-autonomy.test.js`, `tests/policy-hardening.test.js` |
+| Checker crash interpreted as proof | A broken checker crashes with an exception and is erroneously treated as observing expected failure | Mutation verification runner (`rule-verify`) | Distinguish `ERROR` from `FAIL`; exceptions produce `observed: ERROR`, `CHECK_MUTATION_EXECUTION_ERROR`, and null `proofDigest` | Repaired checker must pass mutation test cleanly | `tests/policy-hardening.test.js` |
+| Policy corruption bypass | Malformed policy artifacts cause runtime errors that are silently ignored to bypass checks | Fail-closed policy evaluation in `audit` and `complete` | Explicit capability classification (`NOT_PRESENT`, `AVAILABLE`, `INVALID`); corrupt artifacts fail closed with `E_POLICY_INVALID` or `E_POLICY_EVALUATION_FAILED` | Absent policy in legacy targets remains compatible without blocking | `tests/policy-hardening.test.js` |
+| Partial initialization authority | Manifest is committed before executable-policy bootstrap completes, so a repository appears initialized while `discovery.json`/`baseline.json`/`policy.lock` are partial or absent | Manifest commit boundary during `forgeloop init` | Manifest-last commit authority: policy artifacts are written and verified (`detectPolicyCapability` = `AVAILABLE`, `verifyPolicyLock` = `VALID`) before the manifest is written; any bootstrap failure raises `E_POLICY_INITIALIZATION_FAILED` with no committed manifest; retry reconciles already-correct files and fails with a deterministic conflict on unowned divergent content; `dry-run` performs no writes | A trusted operator can still deliberately edit artifacts after initialization | `tests/init-policy.test.js` |
+| Lock regeneration or subdigest tampering | An actor modifies rules or baseline, omits subdigests, or regenerates `policy.lock` to hide tampering | Effective policy lock verification (`verifyPolicyLock`) | Lock derives deterministically from effective rules + baseline. Schema-invalid lock artifacts (malformed JSON or missing required fields such as `rulesDigest`/`baselineDigest`) fail closed with `E_POLICY_INVALID`; schema-valid locks whose semantic digest components (`algorithm`, `digest`, `rulesDigest`, `baselineDigest`) no longer match effective policy state fail with `E_POLICY_LOCK_MISMATCH` before any relocking. Changing only `capturedAt` does not change semantic identity | Explicit update commands (`policy-discover --write`, `baseline`) update lock after authorization | `tests/policy-hardening.test.js` |
+| Baseline re-record bypass | An actor uses `baseline --record` during an active task to convert newly introduced violations into tolerated debt | Active task baseline protection in `runBaseline` | `baseline --record` is rejected during active policy-bound tasks with `E_BASELINE_RECORD_DURING_ACTIVE_TASK`; only monotonic `--update` is permitted | Explicit `--policy-reset-authorized` flag required for intentional operator resets | `tests/policy-hardening.test.js` |
+| Legacy snapshot semantic confusion | A legacy task snapshot lacking baseline state is assumed to have empty baseline, creating false `WEAKEN` drift | Semantic baseline snapshotting in `policy-snapshot.json` | Snapshots retain full semantic baseline entries; snapshots lacking baseline state classify drift as `UNKNOWN` rather than inventing state | Modern tasks retain semantic baseline entries for exact diff | `tests/policy-hardening.test.js` |
+| Cross-task state confusion | Concurrent processes or alternative harnesses mutate or read the wrong task's state in a multi-task workspace | Task-scoped isolation in `.forgeloop/task-state/<taskKey>/` | Deterministic SHA-256 task directory namespacing, explicit `--task` / `FORGELOOP_TASK` selectors, file-level mutex locking (`.lock`), and claim overlap detection in `task-create` | Tasks must declare non-overlapping write claims or operate in isolated worktrees | `tests/task-namespace.test.js`, `tests/task-scope.test.js` |
+| Modern namespace descriptor deletion | Corruption or an attacker removes `task.json` from a modern task namespace (leaving contract/work-state/receipt/events), the resolver ignores the namespace, and stale legacy singleton state becomes authoritative | Descriptor boundary between modern task namespaces and the legacy singleton | Descriptor-less 64-hex directories are classified by contents: directories containing modern task artifacts (or empty directories) fail closed with `E_TASK_DESCRIPTOR_INVALID`; only directories containing exclusively the explicitly recognized legacy-incidental artifact (`policy-snapshot.json`) are ignored; `resolveTaskContext` fails closed when all namespaces are corrupt | A separately privileged process can rewrite task-state directories after validation | `tests/validate-receipt-task.test.js` |
 
 ## Boundary rules
 

package/docs/ARTIFACT_REFERENCE.md

@@ -25,6 +25,11 @@ All artifact schemas are defined in `schemas/*.schema.json`. Persisted artifact
 | `task-state/<task-key>/continuity.json` | `continuity` | Agent Or Harness | Mutable Handoff Notes | Non Evidence Handoff |
 | `task-state/<task-key>/execution-receipt.json` | `execution-receipt` | Protocol Compiled | Atomic Compilation | Evidence Compilation |
 | `task-state/<task-key>/executions/exec-<id>.json` | `execution` | Protocol Executed | Immutable Once Written | Execution Provenance |
+| `policy/rules.json` | `policy-rules` | Operator Or Agent | Mutable Configuration | Policy Specification |
+| `policy/discovery.json` | `policy-discovery` | Protocol Generated | Mutable On Discovery | Discovered Policy Specification |
+| `policy/baseline.json` | `policy-baseline` | Protocol Generated Or Operator | Monotonic Ratchet Down | Brownfield Baseline |
+| `policy/policy.lock` | `policy-lock` | Protocol Generated | Atomic Digest Compilation | Policy Integrity Lock |
+| `task-state/<task-key>/policy-snapshot.json` | `policy-snapshot` | Protocol Generated | Mutable Before Execution | Task Policy Attestation |
 
 <!-- END FORGELOOP GENERATED: artifact-registry -->
 
@@ -160,7 +165,7 @@ Discovered repository facts, platforms, runtimes, and dependencies.
 
 <!-- forgeloop-doc: schema=event artifact=.forgeloop/task-state/<task-key>/events.ndjson -->
 
-The append-only cryptographic event ledger. Each line is a single JSON event object.
+The append-only cryptographic event ledger. Each line is a single JSON event object. Records authoritative chronological events including lifecycle milestones (`TASK_RECEIVED`, `CONTRACT_VALIDATED`, `ROUTE_VALIDATED`, `PREFLIGHT_READY`, `EXECUTION_STARTED`, `VERIFICATION_STARTED`), evidence-backed diagnoses (`DIAGNOSIS_RECORDED`), and decision settlement criteria (`DECISION_CRITERION_RECORDED`).
 
 #### Canonical Line Fields
 
@@ -254,7 +259,7 @@ Pre-implementation gate approval artifact recording decisions, bound artifact ha
 
 <!-- forgeloop-doc: schema=work-state artifact=.forgeloop/task-state/<task-key>/work-state.json -->
 
-The canonical, authoritative lifecycle work state.
+The canonical, authoritative lifecycle work state. Represents current checkpoint and resume state (`phase`, `checks`, `verificationCycle`, `lastUpdated`). Note: `diagnosedHypothesis` is maintained as a backward-compatibility projection of the latest diagnosis from `events.ndjson`.
 
 #### Canonical Fields
 
@@ -440,3 +445,148 @@ Canonical task descriptor declaring task identity, key, timestamps, and write cl
 - `writeClaims` *(array<string>, required)*
 
 <!-- END FORGELOOP GENERATED: schema:task-descriptor -->
+
+---
+
+### 2.14 `policy/rules.json`
+
+<!-- forgeloop-doc: schema=policy-rules artifact=.forgeloop/policy/rules.json -->
+
+Repository-level executable policy rules declaring verification constraints.
+
+#### Canonical Fields
+
+<!-- BEGIN FORGELOOP GENERATED: schema:policy-rules -->
+
+- `schemaVersion` *(number, required, const: 1)*
+- `rules` *(array<object>, required)*
+  - `id` *(string, required, minLength: 1)*
+  - `severity` *(string, required, enum: `HIGH`, `MEDIUM`, `LOW`, `INFO`)*
+  - `source` *(string, required, enum: `builtin`, `discovered`, `project`)*
+  - `blocking` *(boolean, required)*
+  - `why` *(string, required, minLength: 1)*
+  - `fix` *(string, required, minLength: 1)*
+  - `confidence` *(string, optional, enum: `HIGH`, `MEDIUM`, `LOW`, `UNKNOWN`)*
+  - `scope` *(object, optional)*
+    - `includes` *(array<string>, optional)*
+    - `excludes` *(array<string>, optional)*
+  - `check` *(object, required)*
+    - `type` *(string, required, minLength: 1)*
+    - `adapter` *(string, optional)*
+    - `command` *(array<string>, optional)*
+    - `threshold` *(number, optional)*
+    - `parameters` *(object, optional)*
+
+<!-- END FORGELOOP GENERATED: schema:policy-rules -->
+
+---
+
+### 2.15 `policy/discovery.json`
+
+<!-- forgeloop-doc: schema=policy-discovery artifact=.forgeloop/policy/discovery.json -->
+
+Automated non-interactive discovery report recording inferred architecture, conventions, and confidence scores.
+
+#### Canonical Fields
+
+<!-- BEGIN FORGELOOP GENERATED: schema:policy-discovery -->
+
+- `schemaVersion` *(number, required, const: 1)*
+- `languages` *(array<string>, required)*
+- `testing` *(object, required)*
+  - `detected` *(boolean, required)*
+  - `command` *(array<string>, optional)*
+  - `framework` *(string, optional)*
+  - `confidence` *(string, required, enum: `HIGH`, `MEDIUM`, `LOW`, `UNKNOWN`)*
+- `linting` *(object, required)*
+  - `detected` *(boolean, required)*
+  - `command` *(array<string>, optional)*
+  - `tool` *(string, optional)*
+  - `confidence` *(string, required, enum: `HIGH`, `MEDIUM`, `LOW`, `UNKNOWN`)*
+- `architecture` *(object, required)*
+  - `value` *(string,null, optional)*
+  - `confidence` *(string, required, enum: `HIGH`, `MEDIUM`, `LOW`, `UNKNOWN`)*
+  - `enforcement` *(string, required, enum: `BLOCKING`, `ADVISORY`, `NONE`)*
+- `discoveredRules` *(array<object>, required)*
+
+<!-- END FORGELOOP GENERATED: schema:policy-discovery -->
+
+---
+
+### 2.16 `policy/baseline.json`
+
+<!-- forgeloop-doc: schema=policy-baseline artifact=.forgeloop/policy/baseline.json -->
+
+Brownfield policy baseline recording tolerated legacy violations by cryptographic fingerprint.
+
+#### Canonical Fields
+
+<!-- BEGIN FORGELOOP GENERATED: schema:policy-baseline -->
+
+- `schemaVersion` *(number, required, const: 1)*
+- `createdAt` *(string, required, minLength: 1)*
+- `entries` *(array<object>, required)*
+  - `ruleId` *(string, required, minLength: 1)*
+  - `fingerprints` *(array<string>, required)*
+  - `reviewBy` *(string, optional)*
+  - `details` *(array<object>, optional)*
+
+<!-- END FORGELOOP GENERATED: schema:policy-baseline -->
+
+---
+
+### 2.17 `policy/policy.lock`
+
+<!-- forgeloop-doc: schema=policy-lock artifact=.forgeloop/policy/policy.lock -->
+
+Cryptographic policy digest lock securing effective rules and baseline state.
+
+The lock protects the **effective policy** — built-in rules plus discovered
+rules plus project rules/overrides, combined with the baseline. `algorithm`,
+`digest`, `rulesDigest`, and `baselineDigest` all participate in lock integrity
+validation; a disagreement with the current effective policy produces
+`E_POLICY_LOCK_MISMATCH`. `capturedAt` is informational metadata only — it is
+not part of semantic policy identity, and changing it alone does not represent
+a policy change. A missing or malformed lock fails closed rather than being
+silently ignored.
+
+#### Canonical Fields
+
+<!-- BEGIN FORGELOOP GENERATED: schema:policy-lock -->
+
+- `schemaVersion` *(number, required, const: 1)*
+- `algorithm` *(string, required, const: `sha256`)*
+- `digest` *(string, required, minLength: 1)*
+- `rulesDigest` *(string, required)*
+- `baselineDigest` *(string, required)*
+- `capturedAt` *(string, optional)*
+
+<!-- END FORGELOOP GENERATED: schema:policy-lock -->
+
+---
+
+### 2.18 `task-state/<taskKey>/policy-snapshot.json`
+
+<!-- forgeloop-doc: schema=policy-snapshot artifact=.forgeloop/task-state/<task-key>/policy-snapshot.json -->
+
+Task-scoped immutable snapshot of effective policy captured during preflight to detect policy drift.
+
+A snapshot binds the task to the policy that was authorized at activation:
+`policyDigest`, the effective `rules`, semantic `baseline` entries, and
+`baselineDigest`. Later policy changes are classified by semantic diff as
+`TIGHTEN`, `NEUTRAL`, `WEAKEN`, or `UNKNOWN`. Modern snapshots carry the full
+semantic baseline; legacy snapshots without baseline state leave baseline
+comparison explicitly `UNKNOWN` rather than assuming an empty baseline.
+
+#### Canonical Fields
+
+<!-- BEGIN FORGELOOP GENERATED: schema:policy-snapshot -->
+
+- `schemaVersion` *(number, required, const: 1)*
+- `policyDigest` *(string, required, minLength: 1)*
+- `rules` *(array<string,object>, required)*
+- `baseline` *(object, optional)*
+- `baselineDigest` *(string, optional)*
+- `capturedAt` *(string, optional)*
+
+<!-- END FORGELOOP GENERATED: schema:policy-snapshot -->