From 31984befe94861a11adcebcb4074483ca88119a7 Mon Sep 17 00:00:00 2001 From: Mike Long Date: Fri, 6 Feb 2026 11:13:28 -0800 Subject: [PATCH] docs: phase alignment and scope clarification - Add document scope (CLI only; UI/operational out of scope) - Phase 2: traceability wording (stableId, contractRef, ruleRef) - Phase 4: framing-only runtime consumption; remove explain/ergonomics - Phase 5: tentative placeholder for ergonomics - Add status labels to plan docs - Add docs/plans/README.md phase index Co-authored-by: Cursor --- docs/plans/README.md | 14 ++++++ .../contract-first-enforcement-alignment.md | 49 +++++++++++++++---- docs/plans/phase-0-1-execution-plan.md | 3 +- docs/plans/phase-0-extraction-guardrails.md | 2 + .../phase-2-traceability-output-stability.md | 2 + .../plans/phase-3-compile-directory-bundle.md | 2 + .../phase-4-runtime-consumption-framing.md | 2 +- 7 files changed, 62 insertions(+), 12 deletions(-) create mode 100644 docs/plans/README.md diff --git a/docs/plans/README.md b/docs/plans/README.md new file mode 100644 index 0000000..75c37e7 --- /dev/null +++ b/docs/plans/README.md @@ -0,0 +1,14 @@ +# interfacectl phases + +Docs cleanup complete as of 2025-02-06. Further changes require intent. + +These phases apply only to the interfacectl CLI and its artifacts. + +- **Phase 0:** Contract baseline and extraction guardrails +- **Phase 1:** Generation-time gating (validate as canonical gate) +- **Phase 2:** Traceability and output stability +- **Phase 3:** Compile directory bundle +- **Phase 4:** Runtime consumption semantics (framing only) +- **Phase 5:** Ergonomics and developer affordances (tentative) + +Downstream consumers may define their own phase lifecycles independently. diff --git a/docs/plans/contract-first-enforcement-alignment.md b/docs/plans/contract-first-enforcement-alignment.md index 61c9358..0315c65 100644 --- a/docs/plans/contract-first-enforcement-alignment.md +++ b/docs/plans/contract-first-enforcement-alignment.md @@ -1,8 +1,19 @@ # Feature Plan Interfacectl — Contract-First Enforcement Alignment +**Status:** Execution plan (parent). + +## Document scope + +This plan defines phases for the interfacectl CLI and its artifacts only. +It governs contract schema, validation, enforcement semantics, and compile output. +UI behavior, human actionability, and operational workflows are out of scope. +Downstream consumers may define their own phased lifecycles independently. + +--- + ## Summary -Evolve interfacectl into a contract-first enforcement CLI that gates agent-driven interface changes at generation time and produces runtime-consumable enforcement artifacts. The repo already provides deterministic contract validation (`validate`), contract-vs-observed diff (`diff`), and policy-based enforcement (`enforce` with fail/fix/pr). Missing pieces: a single gating workflow that teams can adopt (e.g. `gate` or a clear recommendation), runtime bundle compilation (`compile`), and violation explainability (`explain`). The plan aligns existing behavior with the strategy and adds only what is needed for contract-first gating and runtime consumption. Interfacectl does not generate UI, act as a linter without contracts, or function as an observability tool. +Evolve interfacectl into a contract-first enforcement CLI that gates agent-driven interface changes at generation time and produces runtime-consumable enforcement artifacts. The repo already provides deterministic contract validation (`validate`), contract-vs-observed diff (`diff`), and policy-based enforcement (`enforce` with fail/fix/pr). Missing pieces: a single gating workflow that teams can adopt (e.g. `gate` or a clear recommendation) and runtime bundle compilation (`compile`). Violation explainability is deferred to Phase 5. The plan aligns existing behavior with the strategy and adds only what is needed for contract-first gating and runtime consumption. Interfacectl does not generate UI, act as a linter without contracts, or function as an observability tool. --- @@ -43,7 +54,7 @@ Migration: `allowedColors` is deprecated in favor of `color.sourceOfTruth` and ` ### 3. Violation handling - Violations are reported and, when used as a gate, cause non-zero exit codes (v1: 1/2; v2: 10/20/30 by category). - Each violation already has a stable code (e.g. `font.disallowed`, `section.missing`) and maps to a category (E0/E1/E2). The validator emits `DriftViolation` with `type`, `message`, and optional `details` (including `jsonPointer` for some checks). -- There is no `interfacectl explain` today; human-readable text is in command output and in the `message` field of JSON findings. Adding a dedicated explain command would centralize violation-code documentation. +- There is no `interfacectl explain` today; human-readable text is in command output and in the `message` field of JSON findings. Explainability is a possible Phase 5 scope. - Fail mode is the default for enforce; no silent failures. Advisory-only would require an explicit policy or flag, not the default. --- @@ -78,7 +89,7 @@ Migration: `allowedColors` is deprecated in favor of `color.sourceOfTruth` and ` 3. **Violation mapping:** Every finding in validate/diff/enforce JSON output includes a stable `code` and, where applicable, `category` (E0/E1/E2/E3). Violation types in `DriftViolationType` and the code map in `validate.ts` (e.g. `font.disallowed`) remain the single source of truth. 4. **Runtime bundle (new):** A command (e.g. `interfacectl compile`) produces a versioned artifact (format TBD) that runtime or edge systems can consume. Verifiable by running the command and checking output exists and passes a minimal schema check. 5. **Semantics consistency:** The same contract schema and compliance logic in `@surfaces/interfacectl-validator` are used for validate and for any future compile output; no duplicate semantics. -6. **Output:** All current commands support `--format json` and text; any new commands (gate, compile, explain) must support both where applicable. +6. **Output:** All current commands support `--format json` and text; any new commands (gate, compile) must support both where applicable. 7. **Fail fast:** Contract load failure, schema validation failure, or config load failure exits immediately with E0 (e.g. exit 10 in v2); no partial success. Already true in validate and enforce; preserve in new code. --- @@ -95,7 +106,7 @@ Migration: `allowedColors` is deprecated in favor of `color.sourceOfTruth` and ` Mitigation: Enforce only what the contract declares (surfaces, sections, constraints, color policy). Existing checks (fonts, colors, layout, motion, pageFrame) are all contract-defined. 4. **Command surface sprawl:** New commands could duplicate or blur semantics. - Mitigation: Keep core surface to validate, diff, enforce, and any new gate/compile/explain. Document in API.md which command to use for gating (validate vs enforce --mode fail) so "gate" is either an alias or a single recommended workflow. + Mitigation: Keep core surface to validate, diff, enforce, and any new gate/compile. Document in API.md which command to use for gating (validate vs enforce --mode fail) so "gate" is either an alias or a single recommended workflow. 5. **Repo-specific: two gating paths.** Validate runs contract compliance against descriptors; enforce --mode fail runs diff then policy. They can disagree (e.g. validate passes but diff has entries). Mitigation: Decide and document the canonical gating workflow (e.g. "use validate for compliance; use enforce for policy-on-diff") and, if adding `gate`, make it a thin wrapper that calls one or both explicitly. @@ -119,19 +130,37 @@ Migration: `allowedColors` is deprecated in favor of `color.sourceOfTruth` and ` - **New:** Either (a) add `interfacectl gate` as an alias that runs validate (and optionally enforce fail) with a fixed set of options, or (b) document in README/API.md the recommended gating command (e.g. "for CI, run `interfacectl validate --exit-codes v2`"). If adding `gate`, wire it in `packages/interfacectl-cli/src/index.ts` and keep it thin (no duplicate logic). - **CI:** Out of scope for this plan; follow-up can add an optional CI job that runs validate or enforce against a repo contract. -### Phase 2. Drift-relevant enforcement (already present; tighten semantics) +### Phase 2. Traceability and output stability - **Reuse:** Contract-backed checks exist in `evaluateSurfaceCompliance` (validator) and in diff (contract vs observed descriptors). Structured violation signals are already emitted: validate/diff/enforce JSON output with `code`, `category`, `findings`/`entries`. Drift risks are in `DiffOutput.driftRisks`. -- **New/minimal:** Ensure every diff entry that affects enforcement has a `rule` or contract path where possible (already in types; some entries may leave `rule` unset). No new checks unless they are deterministic and contract-backed. +- **New/minimal:** Phase 2 ensures all diff and enforce outputs are deterministically correlatable via `stableId`, `contractRef`, and `ruleRef` fields, without changing validation semantics or the contract schema. Ensure every diff entry that affects enforcement has a `rule` or contract path where possible (already in types; some entries may leave `rule` unset). No new checks unless they are deterministic and contract-backed. ### Phase 3. Runtime compilation (new work) - **New:** Implement a command (e.g. `interfacectl compile`) in `packages/interfacectl-cli`. Input: contract path (and optionally config). Output: a versioned bundle (e.g. JSON or a small artifact) that runtime or edge systems can load. Reuse: load contract and schema via same paths as validate; reuse `validateContractStructure` so only valid contracts compile. - **Scope:** Define bundle format (e.g. contract + metadata, no new semantics). One target initially; "multiple runtime targets" can be a later phase if needed. - **Location:** New command in `src/commands/compile.ts`, registered in `src/index.ts`. Validator may expose a small helper (e.g. "canonical contract shape for runtime") if useful; no duplicate compliance logic. -### Phase 4. Ergonomics and explainability (new and small improvements) -- **New:** Add `interfacectl explain ` (or similar) that prints a short description and remediation for a violation code. Data can live in a static map (code to text) in the CLI or in a small JSON file; no network call. Register in `src/index.ts`. -- **Optional:** Contract diffing with explicit breaking vs non-breaking classification would require defining rules (e.g. removal of required section = breaking) and adding a classification step to diff output; can be a follow-up. -- **Reuse:** Failure messages already exist in validator (`DriftViolation.message`) and in validate text output; improve only where unclear (e.g. add one-line remediation for common codes in explain). +### Phase 4. Runtime consumption semantics (framing only) + +Phase 4 defines who consumes the compiled bundle and what the contract means at runtime. This phase is framing-only. + +**In scope:** +- Documenting runtime consumption semantics. +- Clarifying how compiled artifacts may be interpreted by consumers. + +**Out of scope:** +- New CLI commands. +- Enforcement behavior at runtime. +- Explainability or ergonomics. +- Policy evaluation, remediation, or agent orchestration. + +See `phase-4-runtime-consumption-framing.md` for authoritative scope. + +### Phase 5. Ergonomics and developer affordances (tentative) + +Possible future scope includes explainability and developer tooling. +No scope is approved. +No implementation is planned. +Work in this phase is contingent on observing Phase 4 consumption patterns. --- diff --git a/docs/plans/phase-0-1-execution-plan.md b/docs/plans/phase-0-1-execution-plan.md index c6e2a47..a308daa 100644 --- a/docs/plans/phase-0-1-execution-plan.md +++ b/docs/plans/phase-0-1-execution-plan.md @@ -1,5 +1,6 @@ # Phase 0 and Phase 1 Execution Plan +**Status:** Execution plan. ## Purpose and scope @@ -9,7 +10,7 @@ This document defines the scope of Phase 0 and Phase 1 from docs/plans/contract- **In scope:** Phase 0 (contract baseline documentation and alignment) and Phase 1 (generation-time gating documentation and optional alias). No new enforcement logic; only documentation and, if chosen, a thin gate command. -**Out of scope for this plan:** Phase 2 (drift-relevant enforcement tightening), Phase 3 (runtime compile), Phase 4 (explain, contract diff breaking classification). Any code that implements compile, explain, or new validation rules is out of scope until a follow-up plan is approved. +**Out of scope for this plan:** Phase 2 (traceability), Phase 3 (runtime compile), Phase 4 (runtime consumption framing). Any code that implements compile or new validation rules is out of scope until a follow-up plan is approved. --- diff --git a/docs/plans/phase-0-extraction-guardrails.md b/docs/plans/phase-0-extraction-guardrails.md index cdc975a..cc4da60 100644 --- a/docs/plans/phase-0-extraction-guardrails.md +++ b/docs/plans/phase-0-extraction-guardrails.md @@ -1,5 +1,7 @@ # Phase 0 Extraction Guardrails +**Status:** Framing doc. + **Scope:** Contract extraction from Next.js app code (`interfacectl generate-contract`). Phase-scoped and revisitable. --- diff --git a/docs/plans/phase-2-traceability-output-stability.md b/docs/plans/phase-2-traceability-output-stability.md index e0f2ae9..2b0e365 100644 --- a/docs/plans/phase-2-traceability-output-stability.md +++ b/docs/plans/phase-2-traceability-output-stability.md @@ -1,5 +1,7 @@ # Phase 2 Traceability and Output Stability +**Status:** Execution plan. + ## Purpose Make diff and enforce outputs explainable and machine-correlatable over time. Reduce ambiguity without changing validation semantics or contract schema. diff --git a/docs/plans/phase-3-compile-directory-bundle.md b/docs/plans/phase-3-compile-directory-bundle.md index 7273a1f..db40db8 100644 --- a/docs/plans/phase-3-compile-directory-bundle.md +++ b/docs/plans/phase-3-compile-directory-bundle.md @@ -1,5 +1,7 @@ # Phase 3 Compile Directory Bundle +**Status:** Execution plan. + ## Purpose Add `interfacectl compile` to produce a deterministic directory bundle for runtime consumption. The bundle must be readable, composable, and diffable. This is a build artifact, not an enforcement engine. diff --git a/docs/plans/phase-4-runtime-consumption-framing.md b/docs/plans/phase-4-runtime-consumption-framing.md index 33eab27..ec5831b 100644 --- a/docs/plans/phase-4-runtime-consumption-framing.md +++ b/docs/plans/phase-4-runtime-consumption-framing.md @@ -1,6 +1,6 @@ # Phase 4: Runtime consumption framing -**Framing doc only.** No implementation. Defines what Phase 4 is allowed to be before any code exists, so the compile bundle does not quietly turn into runtime enforcement. +**Status:** Framing doc. No implementation. Defines what Phase 4 is allowed to be before any code exists, so the compile bundle does not quietly turn into runtime enforcement. If runtime consumption is implemented, it may live in a separate repository or consumer-specific project rather than in interfacectl itself. This document defines semantics only, not ownership of runtime code.