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:
@@ -72,12 +80,23 @@ jobs:
         env:
           XSPEC_E6_EXCHANGE_DIR: ${{ github.workspace }}/.e6-exchange
       - name: Upload E-6 exchange outputs for the Windows leg
-        # No files exist until the harness writes the representative fixture's
-        # outputs into XSPEC_E6_EXCHANGE_DIR on this leg. The exchange lives
-        # in a dot-directory, which upload-artifact v4 excludes by default
-        # (include-hidden-files: false since v4.4) — without the override the
-        # written exchange uploads as nothing and the Windows comparison
-        # fails loudly on a missing manifest (E-6, H-9).
+        # Runs regardless of the suite step's verdict (a step without `if:` is
+        # skipped once an earlier step fails), so an exchange written by the
+        # passing E-6 writer test (test/suite/e6-exchange-writer.test.ts)
+        # always reaches the Windows leg even while unrelated Linux product
+        # tests are red — the Phase 9 red-green period included. `!cancelled()`
+        # rather than `always()`: a cancelled job uploads nothing. The Windows
+        # byte-identity test still fails loudly (H-9) exactly when no exchange
+        # was written — never because some other Linux test failed. No files
+        # exist until the harness writes the representative fixture's outputs
+        # into XSPEC_E6_EXCHANGE_DIR on this leg; `if-no-files-found: ignore`
+        # keeps this step harmless when the suite step never ran or the writer
+        # test wrote nothing. The exchange lives in a dot-directory, which
+        # upload-artifact v4 excludes by default (include-hidden-files: false
+        # since v4.4) — without the override the written exchange uploads as
+        # nothing and the Windows comparison fails loudly on a missing
+        # manifest (E-6, H-9).
+        if: ${{ !cancelled() }}
         uses: actions/upload-artifact@v4
         with:
           name: e6-linux-outputs
@@ -103,9 +122,12 @@ jobs:
       - name: Build the product
         run: npm run build
       - name: Download E-6 exchange outputs from the Linux leg
-        # The artifact does not exist until the Linux leg produces outputs; the
-        # harness's E-6 comparison must itself fail loudly when the exchange
-        # directory is missing while the product exists.
+        # The artifact is absent only when the Linux job produced no exchange
+        # (it died before its suite step, or the E-6 writer test itself did not
+        # complete) — its upload step runs whenever that job is not cancelled,
+        # red product tests notwithstanding. The harness's E-6 comparison must
+        # itself fail loudly when the exchange directory is missing while the
+        # product exists.
         continue-on-error: true
         uses: actions/download-artifact@v4
         with:

specs/PHILOSOPHY.md

@@ -14,4 +14,8 @@ 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).
+- Name grammars favor addressability over permissiveness (ruled 2026-09-03 by Liaison on Developer's behalf, without consulting Developer, for the external-UI patch's SPEC revisit): when a character admitted in requirement IDs, tags, source paths, or configuration names cannot be spelled or addressed through xspec's own interface — U+FFFD, which a command-line argument cannot distinguish from an invalid byte; `"`, `'`, `\`, and `&`, which MDX attribute values, MDX/TypeScript string literals, and `rename`'s in-place quote-preserving rewrite cannot always spell — exclude the character from the grammar (a validation finding / configuration error) rather than admit valid-but-unaddressable names or add spelling-and-refusal machinery. Basis: GOALS' complete-CLI-interface, every-behavior-observable, and durable-identity (rename/move rewrite all references) goals, and the seed's identifier-friendly naming guidance; such characters in names are pathological (mojibake, injection-like spellings), so the narrowing costs realistic workspaces nothing. General rule: Liaison answers product-shaping edge-case questions on Developer's behalf when GOALS plus the seed's stated intent determine the answer and the cost falls only on pathological inputs; choices that change realistic workspaces' behavior, or touch approval-gated documents, still go to Developer.