From 790312c01984335f97d7e9e052a1c434c5b2c13f Mon Sep 17 00:00:00 2001 From: Mike Long Date: Thu, 5 Feb 2026 09:55:23 -0800 Subject: [PATCH] docs(phase0): document extraction guardrails and flow - Add structured 'How extraction works' section: input, method, output paths, validation - Clarify filesystem + regex extraction, no AST - Output: contracts/generated/.contract.json and .extraction.json - validate-extracted compares policy to extracted reality Co-authored-by: Cursor --- docs/plans/phase-0-extraction-guardrails.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/plans/phase-0-extraction-guardrails.md b/docs/plans/phase-0-extraction-guardrails.md index cdc975a..c1a557f 100644 --- a/docs/plans/phase-0-extraction-guardrails.md +++ b/docs/plans/phase-0-extraction-guardrails.md @@ -2,6 +2,15 @@ **Scope:** Contract extraction from Next.js app code (`interfacectl generate-contract`). Phase-scoped and revisitable. +## How extraction works + +- **Input:** Next.js app directory (contains `app/`). +- **Method:** Filesystem walk + regex. No JSX, TypeScript, or CSS parsing. +- **Output:** + - `contracts/generated/.contract.json` — schema-valid contract with extracted facts under `x_extracted`. + - `contracts/generated/.extraction.json` — machine-readable extraction report and warnings. +- **Validation:** `validate-extracted` compares policy expectations (`surfaces[].phase0` in the policy contract) to extracted reality and fails CI on mismatch. + --- ## No heavy AST in Phase 0