sdg: IP 0001 — foundational machine surfaces for an external spec UI - #7
Open
lzrscg wants to merge 28 commits into
Open
sdg: IP 0001 — foundational machine surfaces for an external spec UI#7lzrscg wants to merge 28 commits into
lzrscg wants to merge 28 commits into
Conversation
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TyZ5zUv2UCkvTkM1tkYUp2
… seed Triage: improvement (new machine-consumable surfaces require SPEC.md changes). Developer confirmed CLI-only connection, UI-owned text editing, and saved-files-only analysis; audit candidates folded in on their merits (parse-local availability, tag sub-ranges, multi-file document view, comment ranges, invocation-anchored root, direct position query). SEED.md consumed. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TyZ5zUv2UCkvTkM1tkYUp2
…odel, exit mapping, refresh, inventory provenance, preview edits, interface versioning Applied: I1 (identity/interpreted-data model for parseable-but-invalid files; invalid imports listed with unavailable targets), I2 (unavailable-data list corrected — occurrence targets never unavailable, source identities and import targets can be; parse-local claim scoped to positions/spellings), I3 (exit mapping stated: findings or unavailable data in the answer -> 1, clean complete answer -> 0, usage/config errors keep 2; answer always emitted), I4 (new query surfaces join read-time refresh on valid workspaces, modify nothing on imperfect ones; inventory never refreshes or writes), I5 (inventory availability restated as parse-independence; content provenance split into invocation/config/discovery, recorded generation state, filesystem), I6 (preview edit classes enumerated: occurrence rewrites, id-attribute rewrites, import specifier/addition/removal edits, section-move deletion/insertion/ self-closing rewrite, file relocation; derived-file removals added), I7 (machine-interface version value stated in SPEC.md, surface reports exactly it — per-build observable; contract scope defined), O1 (per-unit ranges for multi-unit declarations), O2 (identical-range tiebreak removed as unreachable), O3 (byte-classification claim scoped; position-resolution totality and EOF/ beyond-EOF rules), O4 (policy rules reported at coverage-profile depth), O5 (cross-drive anchoring rule). Rejected: none. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TyZ5zUv2UCkvTkM1tkYUp2
…t-2 JSON channel, expansion definedness, enumeration domain, identification preconditions Applied: I1, I2, I3, I4, I5, O1, O2, O3, O4, O5. Rejected: none. - I1: change 8 gains a workspace-independence bullet — consults no workspace or configuration, cannot fail for configuration reasons. - I2: resolved via the channel arm (bullet 2 of change 6 already committed the IP to machine-consumable configuration errors): exit-2 errors emit a JSON error document as the entire standard output, amending the empty-stdout rule. - I3: occurrence spans stated per kind; MDX embedding spans the full braced container, which change 3's byte-classification claim now cites. - I4: dropped "hashes" from the unavailable-data list (no surface this proposal adds reports hashes; naming one would add an unrequested capability) and added the exact expansion-definedness rule (every transitively reached embedding records an occurrence, no cycle re-entered). - I5: finding reporting defined over a consulted domain; a target-only enumeration's domain is the whole discovered set, so masked files always surface as findings with exit 1. - O1: joint-location claim scoped to parseable files. - O2: created-target-file previews report the creation as its own class with the insertion point at file start. - O3: inventory's review-session listing is name-based and content-blind, corrupt sessions included. - O4: structured-diagnostics contract extended to rename/move refusal reasons. - O5: product version phrased as informational; testable contract carried by the machine-interface version. - Compatibility note records the two convention amendments (exit-2 JSON form, change-8 precedence exception). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TyZ5zUv2UCkvTkM1tkYUp2
Applied all items; none rejected. - C1: widened change 4's view domain — when expanded text is requested, the domain gains every file the expansions transitively consult, so the finding blocking an expansion is always in-domain and the never-silent guarantee holds. - I1: change 1's target-node filter is now syntactic acceptance — a well-formed targetable identity selects (possibly zero) occurrences by resolved target; nonexistent, masked, identity-undefined, and unknown targets yield an empty answer with domain findings; only malformed spellings are usage errors; delta flagged in compatibility notes. - O1: default-export unit ranges (named construct vs. export declaration). - O2: graph-data area reported unconditionally as derived, xspec-owned. - O3: session listing selects directory entries by name whatever occupies the path. - O4: preview derived-file consequences defined as the identity-relevant delta, not the full regeneration set. - O5: preview/real-operation equivalence scoped to workspace state, not scheduling. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TyZ5zUv2UCkvTkM1tkYUp2
…ion, corrupt-record outcome, file-filter semantics, availability scoping Applied all items; rejected none. - I1: graph-data area reported as owned with the durable paths carved out and taking precedence — never a blanket derived, deletable unit. - I2: recorded state present but unreadable (corrupt graph data) gets a defined outcome: recorded entries explicitly unavailable, corruption a reported finding, exit 1, full inventory still emitted. - I3: change 1 file filter pinned to the existing file-glob convention (set restriction, empty admission = empty exit-0 answer); the malformed-identity usage-error sentence scoped to the target filter. - I4: change 4 closing sentence scoped to changes 1 and 3, naming where changes 5/7/8 state their own availability. - O1: explicit TypeScript spans — text(...) occurrence = whole call expression; marker occurrence = bare chain, no statement terminator. - O2: "the two" replaced — profiles and rules alike fully expanded. - O3: multi-file view order pinned to byte order of workspace-relative path. - O4: journal occupancy datum added (absence = empty journal). - O5: origin-deletion class's single range covers the adjunct dropped-line bytes, contiguous by construction; no separate class. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TyZ5zUv2UCkvTkM1tkYUp2
…ce-absence guarantee Iteration 5 of patch refinement for 0001-external-ui-apis (IP). Applied: - C1: replaced the graph-data area's contradictory per-occupant ownership composition with one rule stated once in the area entry: the area is a write reservation; reported durable and recorded derived paths are classified as reported; every other path under the area is unattributed — never listed, never claimed, never presented as rebuild-recoverable. The availability paragraph's review-session sentence now defers to that rule instead of asserting opposite ownership. - I1: the empty-finding-free-answer guarantee of change 1 is now scoped to the consulted domain, absolute exactly when no file filter narrows it. - O1: change 4's resolution-failure exemplars now include the unique-bearer-with-undefined-identity case change 1 cites. - O2: change 6 defines the concerned path for missing configuration with no --config: the search-origin directory (invocation working directory), invocation input like change 5's anchoring; compatibility note updated so the invocation-anchored exception covers both changes. - O3: change 5's configuration view names its shape: profiles and rules carried with complete definitions; group references stay names resolved against the view's own group list, never glob expansions. - O4: split the change-1 file-filter sentence and the change-5 provenance/availability sentences into separable statements, all clauses preserved. Rejected: none. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TyZ5zUv2UCkvTkM1tkYUp2
…n unknowability (iter 6) Applied I1: change 2's second bullet now names the exact outputs that gain code-location ranges — occurrence records present their source graph node as one datum (identity plus that node's own construct range; changes 1 and 4 adjusted to match), review payloads generalize the present-node range rule from requirement nodes to graph nodes, and query edge endpoints explicitly remain bare identities. Applied I2: the graph-data-area bullet no longer claims an unattributed path is irrecoverable (false for the graph-data subcase per SPEC 12.1/13.3); the undeletable rule now rests on the consumer's inability to tell regenerable graph data from foreign content. Applied O1: view's glob form states the empty-match outcome (empty set, finding-free, exit 0), mirroring change 1. Applied O2: anchoring bullet's "never as absolute paths" now carries the different-Windows-drives carve-out stated at the change's end. Applied O3: a root's tags/coverage attribute are defined structural absence, not change 4 unavailability — no finding, no exit-1 consequence. Applied O4: preview edits explicitly carry no replacement text; the preview is a safety report, not an edit script whose external application would bypass the journaled mapping. Applied O5: the exit-2 JSON error document's trigger is delimited — --json among the arguments, or a JSON-only surface with no flag needed; the compatibility note now points at that delimitation. Rejected: none. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TyZ5zUv2UCkvTkM1tkYUp2
…dinality, view domain) Applied: I1, I2, O1, O2, O3, O4. - I1: change 6 states the multi-construct location rule — one finding per condition instance carrying a location for every participating construct (duplicate-ID bearers, colliding import declarations, a cycle's full path), context entities as identity data; extended to refusal reasons (cycle a refused move would create). - I2: change 3 assigns the wrong-kind usage error to a discovered code source named directly and fixes the view glob's restriction universe as the discovered spec sources. - O1: change 2 scopes the absent-node clause to the range datum alone, leaving historical-text payload rules untouched. - O2: change 1 states that file and target filters combine conjunctively in one invocation. - O3: split the heaviest sentences in change 4's consulted-domain bullet and change 5's graph-data-area bullet. - O4: change 6 states the missing-configuration concerned path's reported form (change 5's anchoring; degenerate self-reference). Rejected: none. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TyZ5zUv2UCkvTkM1tkYUp2
…rfect files (iter 8) Applied: - I1: change 4 now states the text-value principle for files with findings — Markdown compilation's removal rules classify constructs by syntactic form, never by validity or resolution (imports removed by form, tags removed with every spelled attribute, non-inventoried constructs preserved as content); resolution enters only via text(...) replacement, already the unavailable case. - I2: identity definedness disambiguated — chain conditions (presence, well-formedness, structural validity) are inherited; uniqueness constrains the section's own spelled identity alone, so a uniquely spelled descendant of duplicate-id ancestors keeps its defined identity; defined identity does not imply defined prefixes, and occurrence resolution / the target filter turn on the referenced identity's own definedness. - O1: spread attributes appear among the view's raw attribute spellings by form; invalidity is a located finding, never a view omission. - O2: position-resolution offset domain closed — a non-non-negative-integer offset value is the same usage error as a greater offset. - O3: stable-code scoping stated as deliberate — codes cover exactly the numbered conditions plus refusal reasons; plain usage errors carry no code but still get the JSON error document when JSON output is in effect. Rejected: - O4: the Branch header's mapping is deliberate harness bookkeeping — pushes go to the designated branch and the mapping is recorded in the patch header and PR #7; stripping it mid-process would name a branch nothing pushes to. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TyZ5zUv2UCkvTkM1tkYUp2
…imitation (iter 9)
Applied:
- I1: change 3's attribute parenthetical now reads "attribute inclusion is by
form" — it governs which attributes appear in the view (every spelled one,
validity notwithstanding), not per-attribute ranges. Git history confirms the
intent: the parenthetical entered in iteration 8 as an inclusion statement
("spread attributes appear among the view's raw attribute spellings by form");
"position" was a wording slip. Attributes are carried as raw spellings; ranges
are granted explicitly where intended (tag decomposition, change 6 findings,
change 7 id-rewrite edits).
- O1: the stable-code delimitation now covers review-operation refusals
explicitly — findings under the existing exit-code partition, neither numbered
conditions nor rename/move refusal reasons, uncoded because review flows lie
outside this proposal's UI scope (relied on unchanged).
- O2: change 2's disambiguated-unit sentence now says "each carry the range of
their own construct", ending the collision with change 1's coined "reference
occurrence" (SPEC.md 4.6 uses "occurrence" for the Nth same-named unit).
Rejected: none.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TyZ5zUv2UCkvTkM1tkYUp2
Applied: I1, O1, O2, O3. - I1: change 4 now defines when a section spells an identity (id prop exactly once, quoted attribute form); missing and invalid-form id props (repeated — spellings agreeing or not — braced or valueless values) spell no identity: own identity undefined, descendants' chain broken, and no participation in uniqueness — an invalid-form claimant never poisons a well-formed bearer. Resolution grounded in the document's own principles (no fabrication from invalid syntax, tags/coverage analog, mid-edit containment). - O1: review-refusal aside in change 6 scoped past change 2's range generalization (removes the one self-contradiction reading). - O2: change 5's corrupt-recorded-state finding explicitly joins the numbered validation-error conditions with a stable code. - O3: an occurrence-less MDX-embedding spelling's finding range pinned to the full braced container, keeping change 3's byte classification exact on imperfect files. Rejected: none. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TyZ5zUv2UCkvTkM1tkYUp2
…p exclusivity claim (iter 11) Applied: C1 — replaced change 5's false "alone among readers" claim with an accurate shared-reader statement (inventory + change 7's delta; existing check noted as covered by its staleness condition) and gave change 7's delta a defined outcome on recorded state that exists but cannot be read: the delta, both directions one datum, reported explicitly unavailable, same numbered condition and stable code as change 5's, exit 1, rest of the preview report emitted in full; stated as the succeed/refuse equivalence's one success-side exception (the real operation is not refused — corruption fails no build validation and finishing regeneration replaces it). Aligned change 4's summary pointer and change 6's refusal appositive with the new outcome. Applied: O1 — absent tags/coverage props define the existing defaults (no tags; coverage-required), closing the misreading that presence is required. Applied: O2 — the test seam tied to acquiring workspace exclusivity never engages on a preview, stated at behavior level (no flag prescription). Applied: O3 — reported edit ranges may nest: section-move re-identification rewrites locate inside the origin-deletion range in pre-operation coordinates. Rejected: none. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TyZ5zUv2UCkvTkM1tkYUp2
Iteration 12 review: no Critical or Important items — refinement converged. Applied O2: change 6 now states the invocation-anchored reporting form for every configuration-error concerned path (the found or --config-named configuration file, and the missing-configuration working-directory case), instead of leaving the non-missing cases to the compatibility note's plural. Applied O3: change 3's import entry now states the binding-name datum for a bindingless declaration is structural absence — reported as absent, never as unavailable — per the document's root tags/coverage taxonomy and change 4's closed unavailable-data list. Rejected O1: naming whether the unreadable-record finding becomes a new numbered condition or folds into the existing staleness condition is validation-section organization, which the patch's methodology preamble delegates to spec refinement; the information contract (reported finding, stable code, exit 1, full answer emitted, identical reporter set) is the same on both branches, as the review itself notes. Stage: Proposed -> Accepted. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TyZ5zUv2UCkvTkM1tkYUp2
…iter 1) Integrates all eight accepted surfaces as timeless end-state requirements (review items C1-C9), with concrete invocations (I1): - 5.7 reference occurrences (concept, spans per kind, no-occurrence rule, total order); 11.3 `xspec occurrences [--file <glob>] [--to <node>]` with syntactic --to acceptance and malformed-only usage errors. - 1.7 rewritten: code-location ranges defined; presented in exactly two outputs (occurrence records, review payloads); edge endpoints stay bare identities; 10.7 payload generalized to present graph nodes. - 11.4 `xspec view` (tree, tag decompositions, raw attributes, imports, occurrences, comments, byte-classification guarantee, domain forms) and 11.5 `xspec at <file> <offset>` position resolution. - 11.2 availability contract: parse-local structure, spelled/defined identity, tags/coverage and expanded-text definedness, explicit unavailability, consulted domains, exit mapping, stale-data rule; 13.3 scoped so occurrences/view/at answer mid-edit. - 11.6 `xspec inventory` (anchoring, configuration view, sources, derived map with provenances, graph-data area write reservation and unattributed-path rule, durable files, deterministic ordering). - 14: stable codes for all 23 conditions, location cardinality, concerned paths, refusal-reason codes; new condition 23 (unreadable recorded state); 12.0 JSON error-document delivery whenever JSON output is in effect. - 6.6 previews (`--preview` on rename/move): full plan report, edit classes with pinned ranges, derived delta with condition-23 outcome, refusal equivalence with 13.5 scheduling exception; --test-hold with --preview pinned as a usage error (I2). - 12.6 `xspec version`: machine-interface version 1, workspace-independent, outside configuration-error precedence (14.14 scoped). - 12.0/12.5/13.3/13.5 conventions absorbed the new outcomes (C9). I3: no IP/delta framing survives; internal cross-references only. I4 modularity assessment: no module split - every added portion is consumer-facing interface/contract that PROCESS.md requires in SPEC.md itself, and it is densely interlocked with 1.7/12.0/13.3/14; no clean seam exists in the pre-existing content either. Single file retained under the SHOULD. O1 placement suggestion followed. Rejected items: none. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TyZ5zUv2UCkvTkM1tkYUp2
…esh, import-edit, and view gaps (iter 2) Applied: - C1: node identities exist only over valid source paths — every node of a 14.19-invalid file (roots, sections, code units) has an undefined identity under 11.2; such files keep parse-local structure and their condition-19 finding accompanies every answer whose domain includes them; 1.5's #-unambiguity re-grounded on this rule; occurrences --to gains the invalid-path non-resolve case; 12.0 gains a marked byte-form representation rule for non-UTF-8 workspace-relative paths in outputs. - I1: read-time refresh leaves an unreadable record (14.23) unread, unrepaired, unreplaced; refreshing reads consult no record and report no finding for it; the state persists, reported by 11.6/6.6/14.10, until build or rename/move regeneration replaces the record (13.3, 14.23). - I2: import-removal extent pinned (declaration plus line-drop adjunct, as in 3); import addition inserted as a line of its own at a grammar-permitting, deterministic implementation-latitude offset equal to the previewed offset (6.5, 6.6). - I3: view --text consulted domain defined: exactly the files of resolved targets reachable through occurrence-recording embeddings; a non-resolving spelling is the expansion's boundary; a masked file is never consulted by expansion, its finding surfacing only when requested. - I4: argument checks of 11.3-11.5 precede answering — usage errors exit 2 whatever findings the workspace or named files carry (11.2). - I5: raw attribute spelling defined per attribute, in tag order: name as spelled (absent for spread), source range, and source text (name through value; a spread attribute's entire braced construct) (11.4). - I6: verified against pre-IP baseline (a724662): query was already JSON-only ("a single JSON document is its only output form"), so section 11's JSON-only statement alters nothing pre-existing — no change needed. - O2: 11.4 code-source operand rephrased "wrong-kind operand, a usage error" to avoid conflation with stable code invalid-argument. - O3: review export synopsis aligned to [--json] per its JSON-only text. - O4: confirmed intended, no edit — multiple view <file> operands are deliberate refinement latitude (IP: exact surface shapes settled during spec refinement), consistent with the mandated per-file multi-view response in one document; removing the form would lose harmless capability an editor plausibly wants (view several dirty files at once). Rejected: - O1 (modularization): declined. The extraction candidates (10.4-10.6, 7.4-7.5, 8) are load-bearing contract surface: strategy derivation determines export/next payloads, item identity, and invalidation, and coverage/policy evaluation is itself the command contract; PROCESS requires the full interface/contract in SPEC.md and forbids referencing module internals, so extraction would duplicate contracts rather than shrink the document. The SHOULD yields to those MUSTs here. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TyZ5zUv2UCkvTkM1tkYUp2
…ncerns and file-operand parsing (iter 3)
Applied: C1 (new 12.7 — value forms for ranges, paths and the marked
byte form, the value/absent/unavailable three-state, finding and error
documents, and document forms for occurrences/view/at/inventory/
previews/version, with pinned orderings; 11.6 derived-map bullet aligned
with the record-supplied datum; pointers from 6.6, 11, 12.0, 12.6, 14).
I1 (condition 22 concerns the offending symlink component, one finding
per component; condition 23 concerns the graph-data area; record
conditions added to 14's concerned-path rule). I2 (12.0: # splits only
identity-form arguments, including <file>#<id> operands; bare <file>
operands and --file globs are whole paths with no delimiter role for #).
O1 (10.1 "directory entry" replaces "file"). O2 (5.7 occurrence
existence anchored to target resolution). O3 (13.4 orphan rule extended
to a missing or unreadable record). O4 (12.0 intra-exit-2 precedence:
syntax-only errors before configuration loading, configuration errors
before workspace-consulting argument checks). O5 (finding order and
preview-edit order pinned in 12.7).
Partially applied: O6 — removed the one redundant clause in 11.6's
unattributed-path rule ("the one whose deletion is undone by nothing");
the remaining statements carry distinct load (the foreign case's
definition, the inventory's stance, the consumer rule), so further
compression risks dropping content.
Rejected: O7 — no modularization: nearly all of sections 8-10 is
consumer-facing interface contract that PROCESS.md requires to remain in
SPEC.md itself, which the review itself concedes makes single-file
defensible; extracting mechanism prose mid-IP would churn cross-
references for no requirement.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TyZ5zUv2UCkvTkM1tkYUp2
… total finding order (iter 4) Applied: C1 (refused previews leave the findings-alone list; they keep the four-member preview form with null mapping/files/delta), C2 (one gate phrase — "the validations of \`xspec build\`" — in 6.4, 11.2, 12.0, 13.3; the refusal branch of the all-or-nothing reads covers journal errors (14.13) and refused writes (14.22); refresh runs only where build would succeed and cannot fail; conditions 13/22 accompany no 11.3-11.5 answer — findings are the domain files' alone, finding-free answers stay exit 0), I1 (11 intro corrected: only occurrences/view/at/inventory have 12.7 document forms; query — JSON-only already before the IP — carries its defining section's information), I2 (finding order made total: concerned path with null-first, identities, message; identical findings collapse to one), I3 (list members are [] when empty; null only where a form states the datum absent), O1 (companion attribution via 13.1 naming stated in 11.6), O2 (duplicate unresolved-spelling clauses trimmed from 5.7 and 11.3), O4 (offset spelling pinned to ASCII decimal digits), O5 (recorded paths excluded from the staleness comparison), O6 (marked-byte-form list extended with inventory derived paths and view import targets). Rejected: O3 — no modules extracted: the candidates (§10 review mechanism, §14 condition catalog) are consumer-facing interface/contract, which PROCESS.md requires defined in SPEC.md itself, so no loosely coupled non-contract component exists to extract at the current size. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TyZ5zUv2UCkvTkM1tkYUp2
…ing spelling, unreadable-record staleness (iter 5) Applied: C1 (derived-file map and emit destinations structurally absent for .mdx-less discovered spec sources — 13.1, 13.2 via 7.3, 11.6, 12.7), C2 (view import name = default binding only, absent otherwise — 11.4, 12.7), I1 (canonical anchoring spelling incl. "." self-reference and separator — 11.6, 14), I2 (check reports an unreadable record as a condition-10 finding concerning the graph-data area — 14.10, 12.2), O1 (5.7 definition by resolution), O2 (prefix-first finding order — 12.7), O3 (occurrences in 13.3 content list), O4 (.xspec spelling pinned — 11.6), O5 (exit-2 document holds one finding — 12.7), O6 (positional tree parents to innermost enclosing section — 11.4). Rejected: none. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TyZ5zUv2UCkvTkM1tkYUp2
…comparators, JSON contract details Iteration 6 of applying IP 0001. Applied: C1, I1, O1, O2, O3, O4, O5, O6. - C1: 6.6/6.5 — a created target file's entry reports its creation as its only edit, subsuming the insertion and the import additions composed into the file's initial content (per the IP's "one reported location without pre-operation coordinates"); the moved text's own rewrites stay reported in the origin file; 6.5's preview-offset promise scoped to files existing before the operation. - I1: 12.7 — between-findings `locations` ordering given its element comparator (file path bytes, range start, range end); identities' element rule spelled out alongside. - O1: 14/12.7 — a stable code's value pinned as the listed token string; numerals are ordinals for ordering, no part of the value. - O2: 12.7 — preview edit tiebreak pinned to class-name bytes. - O3: 11.2 — membership rule for a domain file's findings (a location in the file, or the file as concerned path); joint multi-file findings accompany whole when any participant is in the domain. - O4: 6.6 — a refused preview consults no record; no condition-23 finding accompanies a refusal. - O5: 11.5 — a non-UTF-8-path source is nameable by no argument value; its positions are reachable only through the view by glob. - O6: 12.7 — exit-2 error document moved under Document forms, lead exception amended. Rejected: O7 — modularization is a PROCESS SHOULD, not violated at the current size; the reviewer's own framing conditions extraction on future growth, and restructuring at convergence risks breakage with no requirement gain. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TyZ5zUv2UCkvTkM1tkYUp2
… refusal scope (iter 7) Applied: - I1: condition 12 carries no in-source locations and no concerned path (no file's finding per 11.2, so it accompanies no 11.3-11.5 answer, closing 7.5's check-only routing structurally); identities pinned as rule name, edge source, kind token, target; 14's cardinality paragraph and 12.7's identities description widened to match. - I2: the invalid-workspace refusal precedes the operation-specific validation, which is defined and evaluated only over a workspace passing build's validations - the refusal reports the workspace's findings alone, never mixed with refusal reasons (6.4, 14). - O2: 12.2 restated build validations under the build-validations clause so the "additionally" list holds only check-only verifications. - O3: preview `files` entries keyed by current pre-operation path, the relocated file's entry included; created target file by its new path. - O4: 13.3's recorded derived-file paths scoped to generated modules, companions, and emitted Markdown - graph data records no paths, its layout staying unenumerated. Rejected: - O1 (modularization): deferred deliberately - candidate components are bound to the core by dense numbered cross-references (5.4-5.6, 12.0, 12.7, 14) whose contracts could not move to modules without the restatement module rules forbid; the SHOULD is weighed, not dropped. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TyZ5zUv2UCkvTkM1tkYUp2
…stination occupancy (iter 8) Applied: - I1: rename/move old-ID existence judged over spelled identities (11.2), parse-local — undefined-identity bearers still establish existence, no-identity spellings establish none, unparseable origin stays masked (6.4, 6.5). - I2: refused-invalid-id scoped to intrinsic ID form (dot-path of 1.4-valid segments); positional conformance (1.3) is refused-structural-parent's alone, evaluated only over intrinsically valid IDs — no identity reports under both (14). - I3: refused-destination-exists triggers on any occupant of the file-form destination path, whatever kind of filesystem object, symbolic links included (6.5, 14). - O2: a successful non-preview rename/move reports the applied mapping — the preview's mapping information (6.4, 6.5). - O3: finding-form identities content contractual exactly where 14 states it for the condition or reason, otherwise informational — deterministic, composition unpinned (12.7). Not applied: - O1 (modularization): standing deferral upheld. Extracting Review (10) or the query/JSON complex (11, 12.7) requires full interface restatement in SPEC.md per PROCESS module rules; the restructuring risk mid-refinement outweighs the SHOULD at current size. The deferral stays a recorded decision, not an omission. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TyZ5zUv2UCkvTkM1tkYUp2
…n timing (iter 9) Applied: - C1: section-form move target path occupied by anything other than a discovered spec source is refused under refused-destination-exists (6.5 body and refusal list, 14). - C2: rename/move origin operands pinned to discovered spec sources; a code-source origin is a wrong-kind usage error per 11.4's pattern (6.4, 6.5, 12.0 precedence bullet and exit partition). - I1: rename's collision check pinned post-mapping - vacated IDs are no collision, produced IDs checked too, identity-unchanged reports refused-identity-unchanged alone (6.4, 6.5, 14 refused-id-collision). - O2: 11.2 unavailability parenthetical no longer implies a structural view exists for code sources; occurrence's own range (11.3) named. - O3: unreadable-record outcome consolidated into 14.23 as its one normative home; 6.6 and 11.6 defer to it. - O4: explicit sentence in 14 that a refusal reports every applicable reason together, never only the first found. Rejected: - O1: modularization deferred again - the named candidates (Review, Coverage, validation catalogue) are consumer-facing contract that PROCESS.md requires to stay in SPEC.md itself and forbids modules to restate; extracting them mid-IP refinement would churn every section reference while yielding little movable non-contract content. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TyZ5zUv2UCkvTkM1tkYUp2
…ove operands (iter 10) Applied: - C1: 14.10 restructured into four forms — per-file staleness (generated modules/companions per 13.1, emitted Markdown per 13.2) and orphaned recorded files name the file; graph-data staleness (missing or mismatching under 13.3's comparison, recorded paths excluded) and the unreadable record are each one finding whose concerned path is the graph-data area, no path inside named, mirroring 14.23's shape. 12.2 now enumerates the verifications, graph data included, removing the 'generated files' ambiguity. Follows 13.3's existing commitment that check reports graph-data staleness while keeping 11.6's unattributed- path regime intact. - O1: 6.5 classifies move operands by spelling — a mixed-form invocation matches neither synopsis and is a usage error; the file form's inability to spell '#'-containing paths noted as harmless (14.19). - O2: 6.4 drops the '(12.7)' citation on the successful-rename report; 12.7 pins no form for it, so the report stays information-only per 12.0 — consistent with O4's recorded-gap stance. - O3: 7 qualifies 'Every command locates the configuration' to except version, matching 12.6 and 14.14. Rejected: - O5 (modularization): SHOULD, not MUST. The named components are not loosely coupled — 14 is cross-referenced from nearly every section, 10 and 11 interlock with 5.4-5.7, 12.0, 12.7, 13.3-13.5 — so extraction would duplicate contract text into SPEC.md or violate the no-reference-into-module rule; restructuring at convergence adds contradiction risk with no behavioral content. Consistent with prior rounds' deferrals. No-op: - O4: reviewer records the unpinned query/impact/coverage/review member names as a deliberate, IP-faithful gap for a future proposal; no change requested. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TyZ5zUv2UCkvTkM1tkYUp2
…e case (iter 11)
Applied:
- C1: 14.10/12.2 — the per-file content comparison judges the path's
occupant itself, never traversing a symbolic link (13.4): it matches
only a plain file holding exactly the generated content, so a symlink
(whatever its target holds), a directory, or any other non-plain-file
occupant is stale per se. Two conforming implementations can no longer
diverge on a symlinked byte-identical occupant.
- I1: 14.10 — per-file form now reads "missing or does not match",
covering check on a deleted generated module/companion/Markdown file,
parallel to the unit form, 13.3, and 13.4's deleted-file promise;
12.2 aligned ("present as plain files content-identical").
- O2: 11.6 — stated that the condition-23 finding is the only finding an
inventory answer ever carries; findings a listed file or path may bear
(14.19, 14.13, 14.21) report where their conditions assign them.
- O3: 12.7 — concerned-path ordering key pinned to byte-wise comparison
across presentation forms: marked byte-form and plain-string paths
sort in one byte order.
Rejected:
- O1: modularization deferred again — standing SHOULD acknowledged, but
the consumer-facing contract must stay in SPEC.md (PROCESS), limiting
the extractable interior, and restructuring mid-IP-refinement is not
clearly right this round.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TyZ5zUv2UCkvTkM1tkYUp2
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Improvement Proposal
specs/patches/0001-external-ui-apis.md(Stage: Proposed), drafted from the seed "Foundational APIs for an external spec UI" and finalized against the Developer-confirmed scope: CLI-only connection (no service/watch surface), UI-owned text editing (no content-mutation commands), saved-files-only analysis.Proposed SPEC.md change areas: reference occurrences with source ranges; source ranges for code locations; a whole-document structural view (tag-range decomposition, imports, comments, occurrences, direct position resolution, multi-file form); a per-file parse-local availability contract for the new surfaces; a workspace inventory with invocation-anchored root; structured diagnostics with stable codes and ranges; rename/move previews; machine-interface identification.
Also carries the preceding Liaison commits on this branch (PHILOSOPHY.md updates, seed intake) and consumes
specs/tmp/SEED.md.Process notes: branch
claude/xspec-ui-apis-4df8fais this session's harness-designated push branch and stands in forpatch/external-ui-apis(recorded in the patch header). Merge happens only at Phase 11 perspecs/DEVOPS.md.🤖 Generated with Claude Code
https://claude.ai/code/session_01TyZ5zUv2UCkvTkM1tkYUp2
Generated by Claude Code