sdg: IP 0001 — foundational machine surfaces for an external spec UI

.github/workflows/ci.yml

@@ -27,8 +27,16 @@ name: CI
 
 on:
   pull_request:
+  # GitHub creates no pull_request-event runs while a PR is unmergeable.
+  # PR #7 (patch 0001, branch claude/xspec-ui-apis-4df8fa, standing in for
+  # patch/external-ui-apis) is conflicted with main (specs/PHILOSOPHY.md), so
+  # its CI signal comes from push-event runs on the branch head instead —
+  # same workflow, same tree; checks attach to the head commit and surface on
+  # the PR. Drop that branch from this list once its PR is mergeable again or
+  # the patch completes. (Same channel sdg/initial-build used, kept for
+  # history.)
   push:
-    branches: [main, sdg/initial-build]
+    branches: [main, sdg/initial-build, claude/xspec-ui-apis-4df8fa]
   workflow_dispatch:
 
 concurrency:

specs/PHILOSOPHY.md

@@ -14,4 +14,7 @@ IMPORTANT: This file may only be edited and interpreted by Liaison. Only Liaison
 - Operational and infrastructure setup work is not a patch in Developer's eyes: "this is not intended to be a patch, its just a one off set up task" (2026-07-28, correcting the npm-publishing work after triage drafted a Bug Report patch for it). Work whose substance is release/deploy/distribution machinery with zero product-behavior change routes as one-off release/devops execution under DEVOPS.md — not through the patch pipeline — and any patch artifacts created by such a misclassification are retired, not refined. Reserve the patch taxonomy for changes to specified product behavior (IP) or to the harness's ability to catch defects (Bug Report).
 - Developer prefers tokenless, workload-identity credentials over long-lived stored secrets for automation: asked "can we use OIDC?" (2026-07-28) immediately after receiving the NPM_TOKEN setup checklist, choosing npm Trusted Publishing over a stored automation token. General rule: when a platform offers an OIDC/trusted-publisher path for a credential the process manages, default to it — long-lived secrets are bootstrap-only fallbacks, and Developer checklists should not require creating or rotating a token that workload identity can replace.
 - xspec's consumption targets include coding-agent cloud environments — Developer asked how best to distribute the CLI into Claude Code web sessions (2026-07-29). Distribution is npm-only: `@modularcloud/xspec` on the public registry is the sole artifact channel; `vX.Y.Z` tags are release records and GitHub Releases carry no distribution artifacts. Consumption guidance (Liaison recommendation accepted as working default, 2026-07-29): per-repo devDependency + `npx xspec` preferred (rides the environment's normal dependency install, lockfile-pinned); `npx -y @modularcloud/xspec` for ad-hoc use; global install only where a bare `xspec` on PATH is explicitly wanted, via the environment's session-setup mechanism. A dependency-free compiled binary distributed via GitHub Releases would be new work, warranted only if a no-Node target ever matters.
+- The xspec product boundary stays headless (2026-07-31): Developer plans an interactive UI on top of xspec — editing specs, visualizing requirement dependencies, seeing the nested structure inline with the MDX, jumping between references — but the UI itself is expected to live outside the xspec product ("won't necessarily be a part of the xspec spec itself"). xspec's role is to expose the foundational, machine-consumable APIs such an interface needs. When scoping UI-adjacent work: programmatic/observability surfaces belong in the product spec; rendering, editing chrome, and interaction design belong outside it. Developer routed this as a patch and asked the process to recommend the concrete changes — an open-ended seed that requests recommendations is a valid seed; the 2026-07-09 near-complete-draft pattern is Developer's habit, not a requirement.
+- UI-adjacent scope rulings, approved 2026-08-03 (single "That sounds great" to the grouped seven-surface proposal for the external-UI patch — the concise grouped-approval pattern again): (1) an external UI connects by invoking the `xspec` CLI per interaction; no persistent service, watch, or push surface without a fresh proposal (one would also touch GOALS' interface statement, an approval-gated edit); (2) the UI owns text editing — xspec supplies positions, structure, validation, and previews, and its only source-rewriting operations remain `rename`/`move`; structured content-mutation commands ("add dependency", "insert section") are deliberately absent; (3) xspec reads only saved files — unsaved-buffer diagnostics are at most a later addition. Treat these as standing defaults for future UI-adjacent scoping, not just this patch.
+- modularcloud/cspec (the repo renamed 2026-07-27 to free the xspec name) contains Developer's earlier partial UI — the "cspec editor" — built on an outdated conception of xspec. Developer's standing filter (2026-08-03): it may be mined for individual good ideas ("see if there are any other good ideas that we should take from it") but is never authoritative and "we should not draw from this too much" — never import its architecture, data model, or naming; adopted ideas must stand on their own merits in current-xspec terms.
 - Refinement loops that plateau are closed by valve ruling, not run to a spontaneous clean round (first applied 2026-07-10, TEST-SPEC.md at iteration 12 of the xspec initial build). Plateau markers: each fresh review yields only one or two genuine but ever-narrower findings, nothing is re-litigated or reversed, and the upstream documents are already converged. Closure shape: one final iteration whose Driver applies what is necessary and then HALTs, with escape hatches for blocking upstream problems or an indefensible late discovery; residual gaps are deliberately left to the downstream problems-file net, which finds them with implementation eyes when they actually matter. Basis: Developer's revealed preference for bounded forward progress over open-ended polishing (bare "continue" nudges, cost sensitivity shown by the 2026-07-09 credits outage, full delegation of process judgment).