Own generation sessions and run artifacts in interfacectl

AGENTS.md

@@ -17,6 +17,5 @@ Before proposing code changes, ensure the plan explicitly states:
 
 Repo-specific durability rules:
 - this repo is the canonical source of truth for CLI behavior, validator logic, extractor behavior, schema, and release provenance
-- the static preview files in `public/index.html` and `vercel.json` are repo-local preview infrastructure, not the primary product website
 - the public onboarding and richer product marketing site still live in `../surfaces-webapps/apps/interfacectl-web`
 - if a cross-repo task also requires consumer wiring, land and test the source change here first, then update `surfaces-webapps`

API.md

@@ -563,15 +563,19 @@ The output directory contains:
 | Path | Description |
 |------|-------------|
 | `manifest.json` | Bundle manifest with version, contract id/version, tool info, inputs, and file hashes |
-| `contract.normalized.json` | Normalized full contract (stable key order, same information as source) |
-| `surfaces/<surfaceId>.json` | One file per surface; surface data plus minimal metadata for runtime loading |
-| `constraints/motion.json` | Motion constraint category (other categories may be added later) |
+| `contract/normalized.json` | Normalized full contract kept for traceability and downstream validation |
+| `surfaces/<surfaceId>/generation.json` | Surface entrypoint for generators and adapter consumers |
+| `surfaces/<surfaceId>/sections.json` | Surface-local section slices and anatomy references |
+| `surfaces/<surfaceId>/components.json` | Shared component catalog referenced by sections |
+| `surfaces/<surfaceId>/constraints.json` | Cross-cutting contract-authoritative constraints for the surface |
+| `surfaces/<surfaceId>/repair-map.json` | Deterministic repair actions keyed by canonical finding codes |
+| `surfaces/<surfaceId>/authoring.json` | Optional authoring hints when the surface declares them |
 
 **Manifest fields**
 
 | Field | Description |
 |-------|-------------|
-| `bundleVersion` | Format version for this bundle (e.g. `"1.0"`) |
+| `bundleVersion` | Format version for this bundle (e.g. `"2.0"`) |
 | `contractId` | From the contract |
 | `contractVersion` | From the contract (`version` field) |
 | `schemaVersion` | Schema bundle identifier used by the CLI (e.g. `surfaces.web.contract@1`) |
@@ -583,6 +587,146 @@ No timestamps are included in the manifest so that bundles remain deterministic.
 
 ---
 
+### `prepare-generation`
+
+Resolves one compiled surface bundle into a single, agent-ready JSON payload for local workspace agents.
+
+**Synopsis:**
+```bash
+interfacectl prepare-generation --bundle-root <dir> --surface <id> [--out <path>]
+```
+
+**Description:**
+- Loads a compiled generation bundle and validates that the requested surface exists.
+- Resolves `generation.json`, `sections.json`, `components.json`, `constraints.json`, `repair-map.json`, optional `authoring.json`, and `contract/normalized.json`.
+- Emits one deterministic JSON document with summary text, checklist items, resolved generation guidance, sections, components, constraints, repairs, provenance, and source file paths.
+- Uses evidence refs only; it does not inline extracted observation payloads.
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `--bundle-root <dir>` | Path to the compiled generation bundle directory (required) |
+| `--surface <id>` | Surface identifier to resolve from the bundle (required) |
+| `--out <path>` | Optional output file path. When provided, the command writes the JSON payload to disk and suppresses the full stdout payload |
+
+**Exit Codes:**
+- `0`: Prepared payload written successfully
+- `10`: Invalid input, missing bundle files, unsupported bundle version, or unreadable compiled contract
+- `1`: Unexpected internal error
+
+**Output shape**
+
+The generated JSON document includes:
+
+| Field | Description |
+|-------|-------------|
+| `surface` | `{ surfaceId, displayName, type }` |
+| `bundle` | `{ root, version, manifestPath, sourcePaths }` |
+| `contract` | `{ id, version, normalizedPath }` |
+| `summary` | Human-readable text plus checklist/focus items and top repair priorities |
+| `generation` | Resolved `boundary`, `structure`, `layout`, `visual`, and `guidance` objects |
+| `sections` | Resolved section list for the target surface |
+| `components` | Resolved component catalog for the target surface |
+| `constraints` | Cross-cutting contract-authoritative constraints |
+| `repairMap` | Deterministic repair actions keyed by canonical finding codes |
+| `authoring` | Optional authoring hints when present in the source bundle |
+| `evidenceRefs` | Evidence refs only; no inline extracted payloads |
+
+---
+
+### `init-generation-session`
+
+Creates a tracked local-agent session from an already compiled bundle. The command copies the bundle into a session-local directory, prepares the canonical agent payload once, and writes `session.json`.
+
+**Synopsis:**
+```bash
+interfacectl init-generation-session --bundle-root <dir> --surface <id> --workspace-root <path> [--tool <codex|cursor>] [--session <id>] [--artifacts-root <path>]
+```
+
+**Description:**
+- Requires a compiled bundle and does not call `compile` implicitly.
+- Defaults session artifacts to `<workspaceRoot>/artifacts/generation-sessions/<surfaceId>/<sessionId>/`.
+- Writes `bundle/`, `prepared-input.json`, and `session.json`.
+- Canonical session schema lives at `packages/interfacectl-cli/schemas/generation-session.schema.json`.
+
+**Exit Codes:**
+- `0`: Session created successfully
+- `10`: Invalid input, unreadable bundle, duplicate session, or unreadable workspace root
+- `1`: Unexpected internal error
+
+---
+
+### `record-generation-attempt`
+
+Records one operator-reviewed attempt for a tracked session.
+
+**Synopsis:**
+```bash
+interfacectl record-generation-attempt --session-dir <path> --assessment-file <path>
+```
+
+**Description:**
+- Loads `session.json` from the provided session directory.
+- Validates the workspace against the frozen session bundle.
+- Writes:
+  - `attempts/<nnn>.validate.json`
+  - `attempts/<nnn>.assessment.json`
+  - `attempts/<nnn>.metadata.json`
+- Emits a canonical `generation` run into `contracts/generated/contract-runs.json` and rebuilds `contract-lineage.json`.
+- Canonical assessment schema lives at `packages/interfacectl-cli/schemas/generation-assessment.schema.json`.
+
+**Exit Codes:**
+- `0`: Attempt recorded successfully
+- `10`: Invalid input, missing session, invalid assessment payload, or unreadable files
+- `1`: Unexpected internal error
+
+---
+
+### `summarize-generation-session`
+
+Summarizes recorded attempts for one session.
+
+**Synopsis:**
+```bash
+interfacectl summarize-generation-session --session-dir <path>
+```
+
+**Description:**
+- Aggregates attempt count, first pass attempt, latest status, recurring finding codes, recurring repair codes, and the latest assessment.
+- Writes `summary.json` and `summary.md`.
+- Canonical summary schema lives at `packages/interfacectl-cli/schemas/generation-session-summary.schema.json`.
+
+**Exit Codes:**
+- `0`: Latest attempt is `pass`
+- `30`: Latest attempt is `warn` or `block`
+- `10`: Missing session or attempts, or invalid artifacts
+- `1`: Unexpected internal error
+
+---
+
+### `emit-run-artifact`
+
+Writes one canonical run record into `contracts/generated/contract-runs.json` and rebuilds `contract-lineage.json`.
+
+**Synopsis:**
+```bash
+interfacectl emit-run-artifact --workspace-root <path> --surface <id> --source <bootstrap|generation|ci|runtime> --status <pass|warn|fail|unknown> [--contract <path>] [--extraction-path <path>] [--report-path <path>] [--finding-codes <csv>] [--workspace-id <id>] [--idempotency-key <key>] [--created-at <timestamp>] [--run-id <id>]
+```
+
+**Description:**
+- Creates `contract-runs.json` and `contract-lineage.json` if they do not yet exist.
+- Uses canonical schema files:
+  - `packages/interfacectl-cli/schemas/contract-runs.schema.json`
+  - `packages/interfacectl-cli/schemas/contract-lineage.schema.json`
+- Dedupes by `(workspaceId, runId)` and `(workspaceId, idempotencyKey)` when provided.
+
+**Exit Codes:**
+- `0`: Run artifact emitted successfully
+- `10`: Invalid input
+
+---
+
 ### `generate-contract` (Phase 0)
 
 Extracts a deterministic contract artifact from a Next.js app by analyzing app code. **Extraction only** — no enforcement, no network calls. Output is schema-valid; extracted-only fields live under `x_extracted`.

README.md

@@ -147,14 +147,56 @@ interfacectl enforce [options]
 
 ### `compile`
 
-Compiles a validated interface contract into a deterministic, runtime-readable bundle. The bundle includes a manifest, a normalized contract, per-surface files, and per-constraint files for downstream tools to consume.
+Compiles a validated interface contract into a deterministic, generation-oriented bundle. The bundle includes a manifest, `contract/normalized.json`, and per-surface slices for downstream generators, adapters, and workbench consumers.
 
 This command does **not** perform enforcement or runtime gating. It produces a stable artifact intended for inspection, tooling, or future runtime consumption.
 
 ```bash
 interfacectl compile --contract <path> --out <dir>
 ```
 
+### `prepare-generation`
+
+Resolves one compiled surface bundle into a single, agent-ready JSON payload for local workspace agents. The payload includes bundle and contract provenance, resolved generation guidance, sections, components, constraints, repair actions, and optional authoring hints.
+
+```bash
+interfacectl prepare-generation --bundle-root <dir> --surface <id> [--out <path>]
+```
+
+Use this before local agent generation. Use `validate-generation` after code is written.
+
+### `init-generation-session`
+
+Freezes one compiled bundle revision into a tracked local generation session under `artifacts/generation-sessions/<surface>/<sessionId>/` inside the workspace root.
+
+```bash
+interfacectl init-generation-session --bundle-root <dir> --surface <id> --workspace-root <path> [--tool <codex|cursor>] [--session <id>] [--artifacts-root <path>]
+```
+
+### `record-generation-attempt`
+
+Validates one tracked session against the frozen bundle, records the validate payload and assessment, and emits a canonical `contract-runs.json` / `contract-lineage.json` update into the workspace.
+
+```bash
+interfacectl record-generation-attempt --session-dir <path> --assessment-file <path>
+```
+
+### `summarize-generation-session`
+
+Aggregates recorded attempts for one tracked session, writes `summary.json` and `summary.md`, and exits non-zero unless the latest attempt is `pass`.
+
+```bash
+interfacectl summarize-generation-session --session-dir <path>
+```
+
+### `emit-run-artifact`
+
+Writes one canonical run-artifact entry into `contracts/generated/contract-runs.json` and rebuilds `contract-lineage.json`.
+
+```bash
+interfacectl emit-run-artifact --workspace-root <path> --surface <id> --source <bootstrap|generation|ci|runtime> --status <pass|warn|fail|unknown> [--finding-codes <csv>]
+```
+
 ### `generate-contract` (Phase 0 expert command)
 
 Extracts a **deterministic contract artifact** from a Next.js app by analyzing app code and config. This is **contract extraction only** — no first-run classification, no design-system draft, and no onboarding summary. Prefer `interfacectl init` for the user-facing entry point.
@@ -201,6 +243,12 @@ interfacectl separates interface governance into clear phases:
 - **Compile**  
   Produces a deterministic, runtime-readable bundle (manifest, normalized contract, surfaces, constraints) that serves as the handoff point to other tools.
 
+- **Prepare generation**  
+  Resolves one surface from the bundle into a single local-agent payload.
+
+- **Generation sessions**  
+  Freezes one bundle revision, records local-agent attempts, and emits canonical run artifacts.
+
 - **Runtime consumption (framing only)**  
   Consumption semantics are documented in Phase 4. No runtime enforcement or loaders exist in this repo.
 

docs/ai-generator-adapter-api.md

@@ -1,8 +1,15 @@
 # AI Generator Adapter API
 
-This page defines the canonical request/response semantics for generator adapters built around `interfacectl` validation.
+This page defines the canonical request/response semantics for generator adapters built around `interfacectl` validation and the compiled generation bundle.
 
-Consumer repos may materialize this contract as JSON Schema, typed interfaces, CLI wrappers, or HTTP endpoints, but they should not change the meaning of the fields or the `pass|warn|block` verdict model.
+For local workspace agents, the expected pre-generation handoff is `interfacectl prepare-generation`. Tracked session orchestration now also lives in `interfacectl` through `init-generation-session`, `record-generation-attempt`, and `summarize-generation-session`. This document covers the post-generation validation contract.
+
+JSON Schemas for this contract live in:
+
+- `packages/interfacectl-cli/schemas/generation-adapter-request.schema.json`
+- `packages/interfacectl-cli/schemas/generation-adapter-response.schema.json`
+
+Consumer repos may materialize this contract as CLI wrappers, HTTP endpoints, editor tasks, or MCP tools, but they should not change the meaning of the fields or the `pass|warn|block` verdict model.
 
 ## Request contract
 
@@ -12,6 +19,7 @@ Consumer repos may materialize this contract as JSON Schema, typed interfaces, C
   "tool": "codex|cursor|lovable|figma-make",
   "surfaceId": "reference-target-web",
   "mode": "workspace|descriptor",
+  "bundleRoot": "/absolute/path/to/compiled/bundle",
   "workspaceRoot": "/absolute/path/optional",
   "descriptor": [
     {
@@ -21,7 +29,6 @@ Consumer repos may materialize this contract as JSON Schema, typed interfaces, C
       "icons": [{ "value": "@heroicons/react/24/outline", "source": "generated.tsx" }]
     }
   ],
-  "contractPath": "/absolute/path/optional",
   "provenance": {
     "sessionId": "string",
     "userId": "string",
@@ -32,12 +39,10 @@ Consumer repos may materialize this contract as JSON Schema, typed interfaces, C
 
 Field notes:
 
-- `requestId` is caller-supplied when available and otherwise may be generated by the consumer.
-- `tool` identifies the caller for provenance and debugging; it does not change policy meaning.
-- `surfaceId` selects the governed surface within the target contract.
+- `bundleRoot` is required and must point to the output of `interfacectl compile`.
 - `mode=workspace` requires `workspaceRoot`.
 - `mode=descriptor` requires `descriptor`.
-- `contractPath` is an optional consumer override for contract resolution.
+- `contractPath` is no longer supported.
 - `provenance` is optional but recommended for auditability.
 
 Descriptor entries commonly include:
@@ -54,6 +59,12 @@ Descriptor entries commonly include:
   "requestId": "uuid",
   "status": "pass|warn|block",
   "surfaceId": "reference-target-web",
+  "bundle": {
+    "root": "/absolute/path/to/compiled/bundle",
+    "version": "2.0",
+    "manifestPath": "/absolute/path/to/compiled/bundle/manifest.json",
+    "surfacePath": "/absolute/path/to/compiled/bundle/surfaces/reference-target-web/generation.json"
+  },
   "contract": {
     "id": "surfaces.web",
     "version": "0.1.0"
@@ -92,12 +103,11 @@ Descriptor entries commonly include:
 
 Field notes:
 
-- `status` is the canonical verdict.
+- `bundle` captures the compiled bundle provenance that shaped the evaluation.
+- `contract` preserves canonical contract identity and version.
 - `coverage.generationGuard` is `true` when generation-time guard checks ran.
 - `coverage.fullValidate` is `true` only when a full validation pass ran.
-- Category-specific coverage flags state whether that policy area was actually evaluated for this request.
 - `findings` carry the structured remediation payload that tools should feed back into generation.
-- `timings` and `provenance` are additive operational metadata.
 
 ## Status semantics
 
@@ -111,17 +121,9 @@ Consumers must preserve these semantics even if they map the result onto repo-lo
 
 This contract is transport-agnostic.
 
-- CLI wrappers may emit JSON and map `block` to a non-zero exit code.
-- HTTP wrappers may map `block` to `422` or another non-success status.
-- Editor or MCP wrappers may return the payload directly.
-
-Transport choices are local. Verdict and finding meaning are canonical.
-
-## Versioning policy
-
-- Additive fields are backward compatible.
-- Breaking request/response changes require coordinated updates across canonical docs and consumer wrappers.
-- Consumers may add transport metadata, but they should not rename or reinterpret the canonical verdict fields.
+- `interfacectl validate-generation` emits JSON and maps `block` to exit code `30`.
+- `interfacectl serve-generation-adapter` maps `block` to HTTP `422`.
+- Consumer wrappers may bind `bundleRoot` out-of-band, but the canonical data model remains bundle-based.
 
 ## Related docs