#!/usr/bin/env python3 """Prepare, confirm, and verify a project-owned DESIGN.md baseline. The state file is a cache, not authority. Every public operation resolves paths against the supplied project root and ``verify`` re-hashes both the selected baseline and its first-party sources before returning a downstream binding. """ from __future__ import annotations import argparse import hashlib import json import os import re import sys import tempfile from datetime import datetime, timezone from pathlib import Path from typing import Any, Iterable SCHEMA = "design-baseline/v1" STATE_RELATIVE = Path("design-baseline/state.json") EVIDENCE_RELATIVE = Path("design-baseline/evidence.json") DRAFT_RELATIVE = Path("design-baseline/DESIGN.draft.md") CANDIDATES = (Path("DESIGN.md"), Path(".stitch/DESIGN.md")) # Provenance-minimal gate: an existing project DESIGN.md only has to carry # verifiable source provenance (path + SHA-256) to be bound. The other # section names are draft-template guidance (references/design-template.md), # not a structural contract imposed on adopted baselines (ADR-0012). Imposing # the full 9-section template on hand-written existing baselines falsely # rejected them and triggered needless regeneration. REQUIRED_SECTIONS = ( "Source Evidence & Confidence", ) _SKIP_DIRECTORIES = { ".git", ".scratch", ".next", ".nuxt", ".svelte-kit", "build", "coverage", "dist", "node_modules", "out", "target", "vendor", } _FRONTEND_SUFFIXES = { ".css", ".html", ".jsx", ".less", ".pcss", ".sass", ".scss", ".svelte", ".tsx", ".vue", } _CONFIG_NAMES = { "tailwind.config.js", "tailwind.config.cjs", "tailwind.config.mjs", "tailwind.config.ts", "theme.js", "theme.json", "theme.ts", "tokens.json", } _MAX_SOURCES = 32 _MAX_SOURCE_BYTES = 1024 * 1024 # Cap on state.json / DESIGN.md text reads (issue M2): these files live inside # the project tree and are attacker-influenced; an unbounded read_text lets a # planted multi-GB file OOM the verifying process. 4 MiB is far above any # legitimate baseline/state payload. _MAX_DOC_BYTES = 4 * 1024 * 1024 class BaselineError(RuntimeError): """Raised when a baseline cannot be safely prepared or verified.""" def _utc_now() -> str: return datetime.now(timezone.utc).isoformat(timespec="seconds").replace("+00:00", "Z") def _sha256(path: Path) -> str: digest = hashlib.sha256() with path.open("rb") as handle: for chunk in iter(lambda: handle.read(1024 * 1024), b""): digest.update(chunk) return digest.hexdigest() def _read_text_capped(path: Path, label: str) -> str: """Read a project-local text file with a hard size ceiling. state.json and DESIGN.md are attacker-influenced (writable by anyone with repo access); an unbounded ``read_text`` lets a planted multi-GB file OOM the verifying process (issue M2). Raise ``BaselineError`` on overflow. """ try: size = path.stat().st_size except OSError as error: raise BaselineError(f"{label} cannot be sized: {error}") from error if size > _MAX_DOC_BYTES: raise BaselineError(f"{label} exceeds {_MAX_DOC_BYTES} bytes") try: return path.read_text(encoding="utf-8-sig") except (OSError, UnicodeError) as error: raise BaselineError(f"{label} cannot be read: {error}") from error def _relative(path: Path, root: Path) -> str: return path.relative_to(root).as_posix() def _inside(path: Path, root: Path) -> bool: try: path.relative_to(root) except ValueError: return False return True def _roots(project_root: Path | str, run_root: Path | str) -> tuple[Path, Path]: project = Path(project_root).resolve() run = Path(run_root).resolve() if not project.is_dir(): raise BaselineError(f"project root is not a directory: {project}") if not _inside(run, project): raise BaselineError(f"run root escapes project root: {run}") return project, run def _atomic_write_text(path: Path, content: str) -> None: path.parent.mkdir(parents=True, exist_ok=True) descriptor, temporary_name = tempfile.mkstemp(prefix=f".{path.name}.", dir=path.parent) temporary = Path(temporary_name) try: with os.fdopen(descriptor, "w", encoding="utf-8", newline="\n") as handle: handle.write(content) handle.flush() os.fsync(handle.fileno()) os.replace(temporary, path) finally: if temporary.exists(): temporary.unlink() def _atomic_write_json(path: Path, value: dict[str, Any]) -> None: _atomic_write_text(path, json.dumps(value, indent=2, ensure_ascii=False) + "\n") def _candidate_files(project: Path) -> list[Path]: candidates: list[Path] = [] for relative in CANDIDATES: candidate = project / relative if candidate.is_symlink(): resolved = candidate.resolve() if not _inside(resolved, project): raise BaselineError(f"baseline candidate escapes project root: {relative.as_posix()}") raise BaselineError(f"baseline candidate must not be a symlink: {relative.as_posix()}") if candidate.is_file(): resolved = candidate.resolve() if not _inside(resolved, project): raise BaselineError(f"baseline candidate escapes project root: {relative.as_posix()}") candidates.append(candidate) return candidates def _iter_project_files(project: Path) -> Iterable[Path]: for directory, directory_names, file_names in os.walk(project, followlinks=False): directory_names[:] = sorted(name for name in directory_names if name not in _SKIP_DIRECTORIES) base = Path(directory) for name in sorted(file_names): path = base / name lower_name = name.lower() if path.suffix.lower() not in _FRONTEND_SUFFIXES and lower_name not in _CONFIG_NAMES: continue if path.is_symlink() or not path.is_file(): continue try: if path.stat().st_size > _MAX_SOURCE_BYTES: continue except OSError: continue resolved = path.resolve() if _inside(resolved, project): yield path def _collect_sources(project: Path) -> list[Path]: # Walk order is already deterministic (sorted dirs/names). Cap at # _MAX_SOURCES; no keyword ranking — ranking was speculative and did not # affect verify re-hash (ADR-0012 / ponytail review). sources: list[Path] = [] for path in _iter_project_files(project): sources.append(path) if len(sources) >= _MAX_SOURCES: break return sources def _unique(values: Iterable[str], limit: int = 24) -> list[str]: result: list[str] = [] seen: set[str] = set() for value in values: normalized = value.strip() if not normalized or normalized in seen: continue seen.add(normalized) result.append(normalized) if len(result) >= limit: break return result def _extract_evidence(project: Path, sources: list[Path]) -> dict[str, Any]: custom_properties: list[dict[str, str]] = [] colors: list[str] = [] fonts: list[str] = [] spacing: list[str] = [] radii: list[str] = [] motion: list[str] = [] components: list[str] = [] pages: list[str] = [] source_records: list[dict[str, str]] = [] color_pattern = re.compile( r"(?i)(?:#[0-9a-f]{3,8}\b|(?:rgb|hsl|hwb|lab|lch|oklab|oklch)\([^;{}]+\))" ) property_pattern = re.compile(r"--([a-zA-Z0-9_-]+)\s*:\s*([^;{}]+)") font_pattern = re.compile(r"(?i)font-family\s*:\s*([^;{}]+)") for path in sources: relative = _relative(path, project) source_records.append({"path": relative, "sha256": _sha256(path)}) try: text = path.read_text(encoding="utf-8-sig") except (OSError, UnicodeError): continue for name, value in property_pattern.findall(text): record = {"name": f"--{name}", "value": value.strip(), "source": relative} custom_properties.append(record) lowered = name.lower() if any(term in lowered for term in ("color", "background", "surface", "text", "primary", "accent")): colors.append(f"--{name}: {value.strip()}") if any(term in lowered for term in ("space", "gap", "padding", "margin")): spacing.append(f"--{name}: {value.strip()}") if any(term in lowered for term in ("radius", "round")): radii.append(f"--{name}: {value.strip()}") if any(term in lowered for term in ("motion", "duration", "ease", "transition")): motion.append(f"--{name}: {value.strip()}") colors.extend(color_pattern.findall(text)) fonts.extend(font_pattern.findall(text)) lowered_relative = relative.lower() if any(term in lowered_relative for term in ("component", "primitive", "shared", "/ui/")): components.append(relative) if any(term in lowered_relative for term in ("page", "route", "screen", "view")): pages.append(relative) return { "schema": "design-baseline-evidence/v1", "project_root": str(project), "sources": source_records, "tokens": custom_properties[:80], "colors": _unique(colors), "fonts": _unique(fonts, limit=12), "spacing": _unique(spacing, limit=16), "radii": _unique(radii, limit=12), "motion": _unique(motion, limit=12), "components": _unique(components, limit=16), "pages": _unique(pages, limit=12), } def _yaml_value(value: str) -> str: return json.dumps(value, ensure_ascii=False) def _token_value(evidence: dict[str, Any], terms: tuple[str, ...], fallback: str) -> str: for token in evidence["tokens"]: if any(term in token["name"].lower() for term in terms): return token["name"] if evidence["colors"] and terms == ("primary", "accent"): return evidence["colors"][0].split(":", 1)[0] return fallback def _observed_list(values: list[str], empty: str, limit: int = 8) -> list[str]: if not values: return [f"- [inferred confidence=low] {empty}"] return [f"- [observed] `{value}`" for value in values[:limit]] def _render_draft(project: Path, evidence: dict[str, Any]) -> str: project_name = project.name background = _token_value(evidence, ("background", "canvas"), "unresolved") surface = _token_value(evidence, ("surface", "card", "panel"), "unresolved") text = _token_value(evidence, ("text", "foreground"), "unresolved") primary = _token_value(evidence, ("primary", "accent"), "unresolved") source_paths = [item["path"] for item in evidence["sources"]] lines = [ "---", f"name: {_yaml_value(project_name)}", "colors:", f" background: {_yaml_value(background)}", f" surface: {_yaml_value(surface)}", f" text: {_yaml_value(text)}", f" primary: {_yaml_value(primary)}", "---", "", f"# Design System: {project_name}", "", "## Visual Theme & Atmosphere", "", "- [observed] Existing first-party theme, shared component, and page sources define the current visual baseline.", "- [inferred confidence=medium] Preserve the observed token vocabulary, density, and component conventions when adding new surfaces.", "", "## Color Palette & Roles", "", *_observed_list(evidence["colors"], "Color roles are not explicit in the inspected sources; confirm them before use."), "", "## Typography Rules", "", *_observed_list(evidence["fonts"], "Typography hierarchy is not explicit; infer only from representative rendered surfaces."), "- [inferred confidence=medium] Reuse the existing font stack and derive hierarchy from shared components before introducing new sizes.", "", "## Component Stylings", "", *_observed_list(evidence["components"], "No shared component path was detected; treat component styling as an unresolved gap."), "- [inferred confidence=medium] Prefer existing primitives and variants over page-local replacements.", "", "## Layout Principles", "", *_observed_list(evidence["spacing"], "No named spacing tokens were detected; confirm the base spacing rhythm."), *[f"- [observed] Representative page: `{path}`" for path in evidence["pages"][:6]], "- [inferred confidence=medium] Match the density and alignment rhythm of representative pages.", "", "## Motion & Interaction", "", *_observed_list(evidence["motion"], "No motion token was detected; keep transitions restrained until interaction evidence is available."), "- [inferred confidence=medium] Preserve visible hover, focus, pressed, loading, and reduced-motion behavior from existing primitives.", "", "## Accessibility", "", "- [inferred confidence=medium] Preserve semantic controls, keyboard focus visibility, and non-color state cues present in existing primitives.", "- [inferred confidence=low] Contrast, touch targets, text scaling, and reduced-motion behavior require runtime verification.", "", "## Source Evidence & Confidence", "", ] for source in evidence["sources"]: lines.extend( [ f"- [observed] path: `{source['path']}`", f" sha256: `{source['sha256']}`", " confidence: high", ] ) lines.extend( [ "", "## Known Gaps & Exceptions", "", "- [inferred confidence=medium] Semantic intent inferred from implementation must be reviewed before this draft becomes project authority.", ] ) if not source_paths: lines.append("- [inferred confidence=low] No high-signal first-party frontend source was discovered.") if not evidence["radii"]: lines.append("- [inferred confidence=low] Shape and corner-radius conventions are unresolved.") else: lines.extend(f"- [observed] Shape token `{value}`" for value in evidence["radii"][:6]) return "\n".join(lines).rstrip() + "\n" def _state_path(run: Path) -> Path: return run / STATE_RELATIVE def _write_state(run: Path, state: dict[str, Any]) -> dict[str, Any]: _atomic_write_json(_state_path(run), state) return state def _normalize_heading(value: str) -> str: value = re.sub(r"^\d+[.)]\s*", "", value.strip().lower()) return re.sub(r"\s+", " ", value) def _parse_sections(text: str) -> dict[str, str]: matches = list(re.finditer(r"(?m)^##\s+(?:\d+[.)]\s*)?(.+?)\s*$", text)) sections: dict[str, str] = {} for index, match in enumerate(matches): end = matches[index + 1].start() if index + 1 < len(matches) else len(text) sections[_normalize_heading(match.group(1))] = text[match.end() : end].strip() return sections def _safe_relative_file(root: Path, relative: str, label: str) -> Path: if not isinstance(relative, str) or not relative or "\\" in relative: raise BaselineError(f"{label} must be a normalized project-relative path: {relative!r}") # Reject NUL / control chars up front: PurePath accepts them at construction # and only fails at lstat/open with a raw ValueError (issue L3), which # escapes BaselineError handling and surfaces a traceback to the agent. if any(ord(ch) < 0x20 or ch == "\x7f" for ch in relative): raise BaselineError(f"{label} contains control characters: {relative!r}") path_value = Path(relative) if path_value.is_absolute() or ".." in path_value.parts: raise BaselineError(f"{label} escapes project root: {relative}") path = root / path_value if path.is_symlink(): raise BaselineError(f"{label} must not be a symlink: {relative}") resolved = path.resolve() if not _inside(resolved, root): raise BaselineError(f"{label} escapes project root: {relative}") if not resolved.is_file(): raise BaselineError(f"{label} does not exist: {relative}") return resolved def _parse_sources(section: str) -> list[dict[str, str]]: entries: list[dict[str, str]] = [] current: dict[str, str] | None = None path_pattern = re.compile( r"^\s*-\s+(?:\[observed\]\s+)?path:\s*[`'\"]?(.+?)[`'\"]?\s*$" ) hash_pattern = re.compile(r"^\s+sha256:\s*[`'\"]?([0-9a-f]{64})[`'\"]?\s*$") for line in section.splitlines(): path_match = path_pattern.match(line) if path_match: if current is not None: entries.append(current) current = {"path": path_match.group(1).strip()} continue hash_match = hash_pattern.match(line) if hash_match and current is not None: current["sha256"] = hash_match.group(1) if current is not None: entries.append(current) return entries def _validate_claim_labels(sections: dict[str, str]) -> None: claim_pattern = re.compile( r"^\s*-\s+\[(?:observed|inferred confidence=(?:high|medium|low))\]\s+\S" ) for heading in REQUIRED_SECTIONS: content = sections[_normalize_heading(heading)] for line in content.splitlines(): if re.match(r"^\s*-\s+", line) and not claim_pattern.match(line): raise BaselineError(f"unlabelled design claim in {heading}: {line.strip()}") def _validate_source_records(project: Path, sources: Any) -> list[dict[str, str]]: if not isinstance(sources, list) or not sources: raise BaselineError("baseline must contain at least one provenance source") normalized: list[dict[str, str]] = [] seen: set[str] = set() for source in sources: if not isinstance(source, dict): raise BaselineError("baseline source entry must be an object") relative = source.get("path") expected = source.get("sha256") if not isinstance(relative, str) or not isinstance(expected, str): raise BaselineError("baseline source requires path and sha256 strings") if not re.fullmatch(r"[0-9a-f]{64}", expected): raise BaselineError(f"invalid source SHA-256 for {relative}") if relative in seen: raise BaselineError(f"duplicate baseline source: {relative}") seen.add(relative) source_path = _safe_relative_file(project, relative, "baseline source") actual = _sha256(source_path) if actual != expected: raise BaselineError(f"baseline source changed: {relative}") normalized.append({"path": relative, "sha256": expected}) return normalized def _load_state(project: Path, run: Path) -> dict[str, Any]: state_path = _state_path(run) if state_path.is_symlink() or not state_path.is_file(): raise BaselineError(f"baseline state does not exist: {state_path}") try: state = json.loads(_read_text_capped(state_path, "baseline state")) except (OSError, UnicodeError, json.JSONDecodeError) as error: raise BaselineError(f"cannot read baseline state: {error}") from error if not isinstance(state, dict) or state.get("schema") != SCHEMA: raise BaselineError("unsupported baseline state schema") if state.get("project_root") != str(project): raise BaselineError("baseline state is bound to a different project root") return state def _candidate_snapshot(project: Path, candidates: list[Path]) -> dict[str, str]: return {_relative(path, project): _sha256(path) for path in candidates} def _assert_candidate_snapshot(project: Path, state: dict[str, Any]) -> None: expected = state.get("candidate_sha256", {}) if not isinstance(expected, dict) or not all( isinstance(path, str) and isinstance(digest, str) for path, digest in expected.items() ): raise BaselineError("invalid candidate snapshot in baseline state") actual = _candidate_snapshot(project, _candidate_files(project)) if actual != expected: raise BaselineError("baseline candidates changed after preparation; run prepare again") def prepare(project_root: Path | str, run_root: Path | str) -> dict[str, Any]: """Discover a valid baseline or generate a provenance-backed run-local draft.""" project, run = _roots(project_root, run_root) state_directory = run / "design-baseline" state_directory.mkdir(parents=True, exist_ok=True) candidates = _candidate_files(project) candidate_names = [_relative(path, project) for path in candidates] if len(candidates) > 1: hashes = _candidate_snapshot(project, candidates) if len(set(hashes.values())) > 1: return _write_state( run, { "schema": SCHEMA, "status": "ambiguous", "project_root": str(project), "baseline": None, "draft": None, "sources": [], "decision": None, "candidates": candidate_names, "candidate_sha256": hashes, }, ) # Existing candidates are validated by the same strict parser used by # verify(). An incomplete candidate remains untouched while a replacement # proposal is generated in the run directory. if candidates: selected = project / CANDIDATES[0] if (project / CANDIDATES[0]) in candidates else candidates[0] try: sources = _validate_baseline_document(selected, project) except BaselineError: sources = None if sources is not None: state = { "schema": SCHEMA, "status": "ready", "project_root": str(project), "baseline": { "path": _relative(selected, project), "sha256": _sha256(selected), "origin": "existing", }, "draft": None, "sources": sources, "decision": {"kind": "existing", "confirmed_at": _utc_now()}, } return _write_state(run, state) source_files = _collect_sources(project) evidence = _extract_evidence(project, source_files) draft_text = _render_draft(project, evidence) evidence_path = run / EVIDENCE_RELATIVE draft_path = run / DRAFT_RELATIVE _atomic_write_json(evidence_path, evidence) _atomic_write_text(draft_path, draft_text) return _write_state( run, { "schema": SCHEMA, "status": "needs_confirmation", "project_root": str(project), "baseline": None, "draft": {"path": DRAFT_RELATIVE.as_posix(), "sha256": _sha256(draft_path)}, "sources": evidence["sources"], "decision": None, "candidates": candidate_names, "candidate_sha256": _candidate_snapshot(project, candidates), }, ) def _validate_baseline_document(path: Path, project: Path) -> list[dict[str, str]]: try: text = _read_text_capped(path, "baseline document").replace("\r\n", "\n") except (OSError, UnicodeError) as error: raise BaselineError(f"cannot read baseline document: {error}") from error frontmatter = re.match(r"\A---\s*\n(.*?)\n---\s*(?:\n|\Z)", text, re.DOTALL) if frontmatter is None: raise BaselineError("baseline is missing YAML frontmatter") metadata = frontmatter.group(1) if not re.search(r"(?m)^name:\s*\S.*$", metadata): raise BaselineError("baseline frontmatter is missing name") colors = re.search(r"(?ms)^colors:\s*\n((?:[ \t]+[^\n]*(?:\n|$))*)", metadata) if colors is None or not re.search(r"(?m)^\s{2,}[A-Za-z0-9_-]+:\s*\S.*$", colors.group(1)): raise BaselineError("baseline frontmatter is missing color roles") sections = _parse_sections(text) for heading in REQUIRED_SECTIONS: key = _normalize_heading(heading) if key not in sections or not re.sub(r"[`*_#>\-\s]", "", sections[key]): raise BaselineError(f"baseline is missing content for {heading}") _validate_claim_labels(sections) sources = _parse_sources(sections[_normalize_heading("Source Evidence & Confidence")]) return _validate_source_records(project, sources) def confirm( project_root: Path | str, run_root: Path | str, decision: str, reason: str | None = None, ) -> dict[str, Any]: """Confirm a generated draft or explicitly waive the baseline gate.""" project, run = _roots(project_root, run_root) state = _load_state(project, run) normalized_decision = decision.strip().lower() if state.get("status") != "needs_confirmation": raise BaselineError(f"baseline state cannot be confirmed from status: {state.get('status')}") _assert_candidate_snapshot(project, state) if normalized_decision == "waive": normalized_reason = reason.strip() if isinstance(reason, str) else "" if not normalized_reason: raise BaselineError("waiver requires a non-empty reason") _validate_source_records(project, state.get("sources")) state["status"] = "waived" state["baseline"] = None state["decision"] = { "kind": "waived", "reason": normalized_reason, "confirmed_at": _utc_now(), } _write_state(run, state) return verify(project, run) if normalized_decision != "accept": raise BaselineError(f"unsupported baseline decision: {decision}") draft = state.get("draft") if not isinstance(draft, dict) or draft.get("path") != DRAFT_RELATIVE.as_posix(): raise BaselineError("baseline state does not bind the expected draft") expected_draft_hash = draft.get("sha256") if not isinstance(expected_draft_hash, str) or not re.fullmatch(r"[0-9a-f]{64}", expected_draft_hash): raise BaselineError("baseline draft has an invalid SHA-256 binding") draft_path = _safe_relative_file(run, DRAFT_RELATIVE.as_posix(), "baseline draft") if _sha256(draft_path) != expected_draft_hash: raise BaselineError("baseline draft changed after preparation; run prepare again") sources = _validate_baseline_document(draft_path, project) if sources != state.get("sources"): raise BaselineError("baseline draft provenance does not match prepared state") canonical = project / CANDIDATES[0] if canonical.is_symlink(): raise BaselineError("canonical DESIGN.md must not be a symlink") draft_text = _read_text_capped(draft_path, "baseline draft") _atomic_write_text(canonical, draft_text) # Post-write TOCTOU hardening (issue M1): between the pre-write symlink # check and os.replace, a concurrent writer could swap DESIGN.md for a # symlink escaping the project root. Re-assert the canonical entry is a # regular file resolving inside the project before trusting the binding; # the subsequent verify() then re-hashes it as the durable authority. if canonical.is_symlink() or not canonical.is_file(): raise BaselineError("canonical DESIGN.md was replaced during write; re-run prepare") if not _inside(canonical.resolve(), project): raise BaselineError("canonical DESIGN.md escapes project root after write") state["status"] = "ready" state["baseline"] = { "path": CANDIDATES[0].as_posix(), "sha256": _sha256(canonical), "origin": "generated", } state["sources"] = sources state["decision"] = {"kind": "accepted", "confirmed_at": _utc_now()} state["candidate_sha256"] = _candidate_snapshot(project, _candidate_files(project)) _write_state(run, state) return verify(project, run) def verify(project_root: Path | str, run_root: Path | str) -> dict[str, Any]: """Return a verified binding for downstream consumers.""" project, run = _roots(project_root, run_root) state = _load_state(project, run) status = state.get("status") decision = state.get("decision") if status == "waived": if ( not isinstance(decision, dict) or decision.get("kind") != "waived" or not isinstance(decision.get("reason"), str) or not decision["reason"].strip() or not isinstance(decision.get("confirmed_at"), str) ): raise BaselineError("invalid baseline waiver decision") _validate_source_records(project, state.get("sources")) return state if status != "ready": raise BaselineError(f"baseline is not ready: {status}") if not isinstance(decision, dict) or decision.get("kind") not in {"accepted", "existing"}: raise BaselineError("ready baseline lacks a valid decision") baseline = state.get("baseline") if not isinstance(baseline, dict): raise BaselineError("ready baseline lacks a binding") relative = baseline.get("path") expected_hash = baseline.get("sha256") origin = baseline.get("origin") allowed_paths = {candidate.as_posix() for candidate in CANDIDATES} if relative not in allowed_paths: raise BaselineError(f"unsupported baseline path: {relative}") if not isinstance(expected_hash, str) or not re.fullmatch(r"[0-9a-f]{64}", expected_hash): raise BaselineError("invalid baseline SHA-256 binding") if origin not in {"existing", "generated"}: raise BaselineError(f"invalid baseline origin: {origin}") if origin == "generated" and decision.get("kind") != "accepted": raise BaselineError("generated baseline lacks explicit acceptance") candidates = _candidate_files(project) candidate_hashes = _candidate_snapshot(project, candidates) if len(set(candidate_hashes.values())) > 1: raise BaselineError("project has conflicting DESIGN.md candidates") if relative not in candidate_hashes: raise BaselineError(f"bound baseline candidate does not exist: {relative}") baseline_path = _safe_relative_file(project, relative, "baseline") if _sha256(baseline_path) != expected_hash: raise BaselineError(f"baseline changed after binding: {relative}") document_sources = _validate_baseline_document(baseline_path, project) state_sources = _validate_source_records(project, state.get("sources")) if document_sources != state_sources: raise BaselineError("baseline provenance does not match bound state") return state def main(argv: list[str] | None = None) -> int: parser = argparse.ArgumentParser(description=__doc__) subparsers = parser.add_subparsers(dest="command", required=True) for command in ("prepare", "verify"): subparser = subparsers.add_parser(command) subparser.add_argument("project_root", type=Path) subparser.add_argument("run_root", type=Path) confirm_parser = subparsers.add_parser("confirm") confirm_parser.add_argument("project_root", type=Path) confirm_parser.add_argument("run_root", type=Path) confirm_parser.add_argument("--decision", required=True, choices=("accept", "waive")) confirm_parser.add_argument("--reason") args = parser.parse_args(argv) try: if args.command == "prepare": result = prepare(args.project_root, args.run_root) elif args.command == "confirm": result = confirm(args.project_root, args.run_root, args.decision, args.reason) else: result = verify(args.project_root, args.run_root) except BaselineError as error: print(json.dumps({"error": str(error)}, ensure_ascii=False), file=sys.stderr) return 2 print(json.dumps(result, indent=2, ensure_ascii=False)) return 0 if __name__ == "__main__": sys.exit(main())