[darko-mijic]

The article series, re-pinned for the first UX/UI design pass

PR #34 published the article series pinned to b5e0a8be, and the owner ruled that the first refresh after PR #40 re-pins it. This is that refresh. It moves the series to f990bded (the merge of PR #34, after PR #40), regenerates the evidence there, and updates the prose PR #40 made stale. The goal is that the first UX/UI design pass starts from material that describes the Studio designers will actually open.

The question it answers: does the design-pass packet (compact Parts 1, 2 and 5, the designer's brief, and a Studio generated at the pin) describe today's Protocol? At b5e0a8be it did not. The brief described the composing panel before PR #40, said AI presentation had no carrying Spec, and Part 1 gave the CLI's Node range as >=20.

Working record. Branch docs/articles-refresh-1; base main at f990bded; head 53804437. The owner's working rules: refresh the series by its playbook so everything is ready for the first design pass; commits, push and this pull request are authorized. No arc Pack: the diff touches only docs/articles/ (6 files, +68 / −66) and changes no Spec carrier, readiness statement or decision row.

Ready for the design pass

Material	Where
The designer's brief: fixed ground, open design space, seven prototype questions	Part 2, A compact brief
Orientation and the AI direction	Part 1, Part 5
The current Studio, hosted, no install	preview/34: its stamp names 35f1094d, PR #34's merge ref, whose tree (385e3af9) is byte-identical to the pin's
Acceptance tasks to test prototypes against	the Studio's manual verification
The one product question the pass reopens	spec:consumers.ai-assisted-reading #aiPresentationBoundary (below)

The hosted Studio stays out of the manuscripts on purpose: articles are publication drafts, and a preview URL is not a durable source. To build the same page set locally, run Part 2's try-it block.

What the pass owes the corpus. PR #40 added spec:consumers.ai-assisted-reading at idea. Its blocking question, decided by the owner, asks what contract would keep an assistant's own explanations or arrangements distinct from graph claims and reviewable. The provisional answer is that an assistant selects existing deterministic readings only. The trigger is this pass: "the UX design pass measures that assistant selection or a generated explanation helps a named review task." Part 2's brief and Part 5 now say so, so a prototype that tests assistant selection is in scope and its measurement has somewhere to land.

What changed

The pin. One line in the playbook names it, and the evidence sync reads that line. Every commit-pinned link (33 distinct paths, all present at f990bded), every git checkout line and every footer moved with it. The playbook's Step 2 now diffs the next refresh from f990bded.

Evidence, regenerated at the pin. All 11 blocks were rebuilt from the pin's git objects. Three changed:

Block	At b5e0a8be	At f990bded
Specs and readiness	456: 447 ready, 4 scoped, 5 idea	459: 447 ready, 4 scoped, 8 idea
Nodes, edges and locations	1,072 nodes (366 Anchor); 2,978 edges; 3,120 locations	1,079 nodes (370 Anchor); 2,996 edges; 3,157 locations
Open questions	16 across 12 Specs: 10 blocking, 6 non-blocking	15 across 12 Specs: 12 blocking (9 deferrals, 3 holds), 3 non-blocking
Part 4's byFile excerpt	an anchor at line 21	the same anchor at line 22

Delivery facts, build backlog, drift alarm, design backlog, 55 recipes and 5 skills are unchanged. The design diff (recipe 35) from b5e0a8be's graph to the pin's: 3 Specs added (all idea), 43 changed, none removed; one Pack changed.

Prose, measured against the pin (playbook Step 5).

Article	Change	Why
Part 2	Each gathered intent shows its scope and the change it asks for, and a closed Preview memo shows the exact text before it is copied or saved	PR #40's #memoPreview rule and the intent label fix; brief question 6 asks exactly this
Part 2	A floor not evaluated shows as floor not evaluated, not as below idea	PR #40's #notEvaluated ruling: a new honesty state designers must render
Part 2, Part 5	The AI-assisted reading capture, its provisional answer and its trigger	It names this design pass as its re-entry condition
Part 1	The CLI declares Node ^20.19.0 || >=22.12.0	PR #40's Node range; the toolchain overlap is unchanged
Playbook	Article 08 states the unspecified rule without an exception	L1-02 closed in PR #40: unspecified is a reserved Then key
Playbook	House rule 9 names what the Markdown link gate checks and what it leaves to a person	PR #40 added the gate

Part 1's honesty sentence ("reject hand-authored delivery facts") needs no edit: at b5e0a8be a section-level deliveryFacts key slipped past it, and PR #40 refuses that. Part 3's code is all generated evidence; the worked example changed only its README.

Rulings

Made by the owner:

Ruling	One line	Carried in
Re-pin after PR #40	The first refresh after PR #40 re-pins the articles and regenerates the evidence	PR #34's description; this PR
Merge order	PR #40 first, then PR #34 after merging main	PRs #40 and #34

Delegated to the agent, awaiting the owner's review:

Ruling	One line	Carried in
The pin is f990bded	main after both merges, CI green; it holds the articles themselves, which the sync's git-object rebuild allows	the playbook baseline
The hosted Studio link lives in this description, not the manuscripts	A preview URL is not a durable publication source	this description
How Parts 2 and 5 present the AI capture	As an idea-stage owner question with a provisional answer, never as a ratified design	Parts 2 and 5

Try it

git fetch origin docs/articles-refresh-1 && git switch docs/articles-refresh-1 && npm ci
node docs/articles/sync-evidence.mjs --print-pin       # f990bded1d7ca86f19f5746ef412613f8e908be3
npm run check:articles -- "$PWD"                      # Checked 11 evidence blocks at f990bded…
npm run --silent sdp -- studio . --exclude explorations --exclude examples --exclude test/fixtures/import/parity
open generated/spec-studio/index.html                   # gather an intent on a Spec page, then open Preview memo under Composing

Feedback wanted

• Is Part 2's paragraph on the AI capture the right weight for a designer, or should the brief leave it to Part 5?
• Should the first design pass have a roadmap entry? pack:roadmap has none today, and entries join only on the owner's word.

Next: the roadmap at the head

Rendered with recipe 55 over pack:roadmap at this head; this PR moves no entry.

The next work, from the roadmap

Roadmap: The Protocol's roadmap pack:roadmap

To state means the floor allows ready and a person still judges the statement. Built means every Spec of the entry's work states ready and has an implementation binding; it reports no passing test and no deployment.

The Protocol's next work, first entry first. The order is a preference: it dates, gates and sequences nothing, and what each entry still needs is read from the graph each time.

First the cleanup that removes the frozen plans, review reports and superseded concept material, as the roadmap and the pull request record make possible. Then the two steps a reader of the Studio's pages could not take, the words of a test line that checks a declaration and an outside register's entries, and then the composed-intent model the build backlog holds. What the first adopter's mass update asks for joins when the owner selects it; a capture landing adds nothing here. An entry leaves by an edit to this manifest once its selected work is complete or no longer belongs among the next work.

To design

Place	Entry	Next	Purpose and reach
1	The Protocol removes its frozen plans, review reports and superseded concept material spec:protocol.delivery-record-cleanup	itself idea → scoped, nothing holds it; blocked by spec:protocol.delivery-record-cleanup#question.durableContent	Remove plans/, reviews/ and the superseded concept material from the tree, after moving into the graph the durable content they still hold, so the repository keeps one delivery record: the graph, git and the pull requests.
3	An outside register is a named Studio input, so a cited token links to its entry spec:consumers.spec-studio.register-input	itself scoped → defined, held by no-blocking-open-questions; blocked by spec:consumers.spec-studio.register-input#question.registerEntry, spec:consumers.spec-studio.register-input#question.inputForm	A cited token reads as bare text on every page, and the register that defines it is neither linked nor shown.

To state

Place	Entry	Earlier waiting statements	Purpose and reach
2	A pinned declaration shows the words of each test line that cites it spec:consumers.spec-studio.cited-line-text	No preceding waiting statement in the statement queue.	The declarations page names each citing line by file and line only, so the reader leaves the page to read it, and has no route at all when the page set carries no source link.

To build

Place	Entry	Purpose and reach	Rests on
4	Views compose scoped intent instead of patching canonical source spec:consumers.edit-model	Let a view frame a requested change without giving derived surfaces a direct write path to canonical source.	nothing unbuilt

Waiting on the owner

• spec:protocol.delivery-record-cleanup#question.durableContent (blocking), place 1: Which content in plans/, reviews/ and the concept documents does no Spec, test, decision or recipe carry yet, and where does each piece belong?
• State spec:consumers.spec-studio.cited-line-text: it states scoped and its floor allows ready; place 2
• State spec:protocol.delivery-record-cleanup: it states idea and its floor allows scoped; place 1

Deferred, with their triggers

• spec:carrier.sdp-import.feature-adapter#question.featureAdapter: Which bare .feature constructs can an import adapter preserve honestly? Trigger: an adopter migrates a gen-1 .feature corpus into the Protocol
• spec:consumers.agent-surface.combination-coverage#question.combinationCoverage: Which combinations of slot values should coverage enumerate and report? Trigger: a design pass asks which combinations no example exercises
• spec:consumers.ai-assisted-reading#question.aiPresentationBoundary: If an assistant generates explanations or arrangements beyond selecting deterministic readings, what contract keeps its output distinct from graph claims and makes the exact reading reviewable, including how the exact output is retained with its model, prompt and inputs? Trigger: the UX design pass measures that assistant selection or a generated explanation helps a named review task
• spec:consumers.impact-graph.symbol-reach#question.symbolIdentity: Which language-neutral identity and extraction boundary can support exhaustive symbol reach without freezing a single compiler's representation into the Protocol? Trigger: a reader needs symbol-level reach that file-level imports and curated anchors cannot give
• spec:consumers.projections-model.roadmap-views#question.releaseReader: Does a reader need release or baseline views that the roadmap, the recipes and git tags do not serve? Trigger: the first published release
• spec:consumers.reference-projection#question.namedOutsideReader: Does a human reader outside the repository need a reference projection the four shipped roots do not serve? The taxonomy row is not that reader. Trigger: a named consumer outside the repository, with a way to measure that demand inside the arc that builds the projection
• spec:consumers.structural-mermaid#question.namedStructuralReader: Does a reader need diagrams rooted at code units, which census tables and Spec-rooted one-hop Mermaid do not serve? Trigger: a named reader with that need, plus a decision that refines spec:decisions.shipped-projections-frozen for the affected Mermaid rendering or supersedes that ruling whole
• spec:observation.run-evidence.bound-file-freshness#question.freshness: When should changes to bound files make recorded run evidence stale? Trigger: a reader cannot tell whether a run at another commit still applies, because nothing says whether its bound files changed since
• spec:observation.runtime-overlay#question.observationIdentity: Which external observation identity and freshness boundary is small enough for the graph while still supporting an honest observed delivery fact? Trigger: An adopter needs runtime measurements linked to measurable Spec targets and can supply an observation identity and freshness policy for review.

The design pass is not a roadmap entry. Its re-entry condition is the owner's decision to start it, using the packet above; its result feeds the AI-assisted reading question, whose trigger it is.

Verification

Measured at 53804437; re-run the commands rather than inheriting these results.

• npm run check:articles -- "$PWD" checked all 11 blocks at f990bded and exited 0.
• npm run check passed on a clean worktree of the head: all 14 steps through preflight, 4,137 tests in 135 files plus 102 in the CLI pass, with the Markdown link gate. A first run in the main checkout failed lint only on build output inside an agent's leftover worktree under the gitignored .tmp-scratch/; no repository file had a finding.
• Every commit-pinned path in the articles exists at f990bded (git cat-file -e).
• main's CI passed at f990bded.
• CI passed on this head (run, pull-request run), the article-evidence step included; the Studio preview deployed to preview/41.

🤖 Generated with Claude Code

Confidence Score: 4/5

The PR appears safe to merge, with one non-blocking clarification needed in Part 5.

Findings

1.  Different AI roles get confused ▶

Summary

Re-pins the article series to f990bded and refreshes the design-pass material.

• The article series points to the f990bded source and its refreshed evidence.
• Part 2 describes the Studio's memo preview and unevaluated readiness floor.
• The design-pass brief ties AI-assisted reading to an open product question.

_{Reviews (1) · Last reviewed commit: "docs(articles): re-pin the series to f99..." · Reviewed by Greptile}

Summary by CodeRabbit

• Documentation
  • Updated article links, checkout instructions, source references, and footers to point to commit f990bded.
  • Refreshed displayed census figures and clarified readiness-floor reporting when a Spec’s kind or altitude is unratified.
  • Clarified the provisional boundaries for AI-assisted reading and when those boundaries will be revisited.
  • Updated CLI Node.js engine guidance and documented unspecified as a reserved contract key with a distinct coverage-gap diagnostic when selected by a bound example.

[coderabbitai]

No actionable comments were generated in the recent review.

Walkthrough

The article series now uses commit f990bded as its source baseline and updates its displayed corpus figures. It also documents Studio presentation details, a provisional boundary for AI-assisted reading, and clarifications to article review guidance.

Changes: Article series documentation

Layer / File(s)	Summary
Refresh source baseline and measurements docs/articles/01-the-spec-is-the-prompt-is-the-design.md, docs/articles/02-one-graph-many-views.md, docs/articles/03-walkthrough-intent-to-verified-code.md, docs/articles/04-stop-building-verb-walls-for-coding-agents.md, docs/articles/05-ai-can-shape-the-reading.md, docs/articles/README.md	Commit-pinned links and checkout instructions now use f990bded. Displayed census figures are updated. The documented CLI Node engine range changes to `^20.19.0
Describe Studio and AI-reading boundaries docs/articles/02-one-graph-many-views.md, docs/articles/05-ai-can-shape-the-reading.md	The articles add details about readiness floors and intent-panel previews. They describe a provisional AI-assisted-reading boundary, including its reopening condition and the distinction between prototypes and shipped functionality.
Update article-series review guidance docs/articles/README.md	The README states that unspecified is reserved and describes the distinct coverage-gap diagnostic. It also clarifies which Markdown links the automated gate checks and which require manual review.

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Other

Possibly related PRs

• libar-dev/software-delivery-protocol#34: Introduced the article manuscripts and publication playbook that this PR updates.

Merge Risk: Minimal · up to 53804

No actionable merge-blocking risk remains in this documentation-only refresh.

Pre-merge checks: 4

Check name	Status	Explanation
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly and concisely identifies the documentation change: re-pinning the article series to commit f990bde for the first design pass.
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

• X
• Mastodon
• Reddit
• LinkedIn

Recent review info

Run configuration

• Source mode: Auto
• Repository: libar-dev/software-delivery-protocol
• Branch: main
• File: .coderabbit.yaml
• Commit: f990bde
• Layers: Repository YAML (base), Repository UI (inherited)
• Review profile: CHILL
• Plan: Advanced
• Run ID: 3e053d44-0493-4d85-a647-b44bf0f4ad3e

Commits

Reviewing files that changed from the base of the PR and between f990bde and 5380443.

Files selected for processing: 6

• docs/articles/01-the-spec-is-the-prompt-is-the-design.md
• docs/articles/02-one-graph-many-views.md
• docs/articles/03-walkthrough-intent-to-verified-code.md
• docs/articles/04-stop-building-verb-walls-for-coding-agents.md
• docs/articles/05-ai-can-shape-the-reading.md
• docs/articles/README.md

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

[greptile-apps]

Different AI roles get confused

This sentence puts both the second and third patterns under the open question in spec:consumers.ai-assisted-reading. But the second pattern has an agent write a deterministic generator that people review before use. The Spec’s question concerns assistant-written explanations or arrangements that do not keep that deterministic guarantee.

Readers may mistake ordinary generator development for the unresolved feature that lets a model write answers. Limit this sentence to the third pattern and describe reviewed generator changes separately.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!