Skip to content

docs-fix: call a resource in a collection a resource (FIX-2479) - #4912

Merged
jhoffner merged 2 commits into
mainfrom
docs-fix/FIX-2479-resource-wording
Nov 8, 2026
Merged

jhoffner merged 2 commits into
mainfrom
docs-fix/FIX-2479-resource-wording

Conversation

@jhoffner

@jhoffner jhoffner commented Nov 7, 2026

Copy link
Copy Markdown
Collaborator

The problem

FIX-2479 turns the resource vocabulary rule from added lines to the whole tree. Its prose half already reads published pages, and nine published lines still call a resource in a collection a "row". A normal PR can't edit published pages, so they go first, in this docs-fix.

What this does

Rewords those lines and changes nothing else:

  • apps/docs/docs/api/client.md (1)
  • apps/docs/docs/fundamentals/state-and-scopes.md (2)
  • apps/docs/docs/glossary.md (1)
  • apps/docs/docs/orchestration/task-board.md (1)
  • apps/docs/docs/resources/overview.md (1)
  • packages/client/README.md (1), packages/core/README.md (1)
  • apps/docs/docs/orchestration/task-board-parts.svg (1): the figure's caption text. The spec counted eight .md lines; the rule's published set also reads .svg, so this one would fail the whole-tree turn too.

It leaves the six lines that quote the three released messages word for word (collections.md x3, workforce/projects.md, the core and workforce READMEs). Reworded, they would misquote the API users run today; they are kept by one named exemption until /release-docs rewrites them (D4). Names of exports (listCollectionItems, readCollectionItem) are the released API and stay until the same release.

Verified: the rule's prose pattern, grepped over published pages on this branch, now meets only those six quotes. node scripts/check-retired-terms.mjs passes. No changeset.

What's asked of you

Merge when green. Same route as FIX-2354's #4909. Spec: specs/issues/FIX-2479/.


Generated by Claude Code

Rewords the plain published lines that called a resource in a collection
a row, so the resource entry can read the whole tree. The lines that quote
the three released messages word for word are left for /release-docs (D4).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011UNkLD7mJaky2QRikkQ8Z4
@vercel

vercel Bot commented Nov 7, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
flow-state-dev-docs Ready Ready Preview Nov 7, 2026 11:37pm UTC
2 Skipped Deployments
Project Deployment Actions Updated
flow-state-dev-ui Ignored Ignored Preview Nov 7, 2026 11:37pm UTC
flow-state-dev-build-site Skipped Skipped Nov 7, 2026 11:37pm UTC

Request Review

@linear-code

linear-code Bot commented Nov 7, 2026

Copy link
Copy Markdown

FIX-2479

@jhoffner jhoffner added the docs-fix label Nov 7, 2026 — with Claude
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 7, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-07T23:35:59.371978Z 23dcf85 PR opened
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

jhoffner commented Nov 7, 2026

Copy link
Copy Markdown
Collaborator Author

Second look + architecture pass (docs-only PR)

Approach: Right shape. This is a mechanical wording fix with no code to refactor, so there is no architecture opportunity here. I'd leave improve-codebase-architecture alone for this PR. The diff matches the glossary's "Resource" entry (a resource in a collection is a resource).

Findings for the follow-up agent:

  1. The task-board figure is now half-converted (should fix).

    • apps/docs/docs/orchestration/task-board-parts.svg line 478 changed "rows" to "tasks", but the same drawing still says "HOLDS THE ROWS" (l.7), "where the rows live" (l.9), "not the row itself" (l.57), "hands each row to a worker" (l.73) and "written back to the row" (l.75).
    • task-board.md:37 has the same problem in the <Figure description> ("the task collection holds the rows").
    • The caption and the surrounding prose now contradict each other. Either convert the whole figure and its description, or revert the one line and leave the figure alone.
    • Note that a task is arguably a TaskCollectionRef entry, so "task" is the better word than "resource" here. That is why the figure line says "tasks" while the prose in task-board.md:35 says "resources". Pick one for the page.
  2. The sweep is not whole-tree, so the wording is not actually fixed.

    • task-board.md still has "stored row" (l.164), "Rows written by an earlier release" (l.301), "A row the board is unsure about" (l.303), and "hand rows to a session" / "partition ... rows" (l.362-396).
    • api/client.md still has "each row's requestStatus" and "Each row is a ChildSessionSummary" (l.219-244). Those are session-list rows, so they may be legitimately exempt as UI list rows.
    • If the glossary exempts them, say so in the PR body so reviewers know the leftovers are deliberate. Otherwise the PR title overclaims.
  3. The prose check won't catch what remains. docs/contributing/glossary.mjs:122 says FIX-2479 will turn the check into a whole-tree check, but this PR doesn't touch it. After merge, a regression in the remaining "row" uses will pass CI. If widening the check is meant to ship with this fix, it belongs in this PR or a named follow-up. I'd verify this by running the check over the tree rather than by reading it.

  4. Source comments still use the old wording (out of scope, mention only). packages/core/src/types/resource-collection.ts:233 says "this collection's rows". The readCommitted wording in the core README is fixed here, but the JSDoc it is derived from may still say "row". Check that source and README agree.

Verdict: fix #1 before merge. Treat #2 and #3 as decisions for the owner.


Generated by Claude Code

The task-board figure's alt text still called the tasks rows, one line
after the sentence this PR reworded.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011UNkLD7mJaky2QRikkQ8Z4
@gitar-bot

gitar-bot Bot commented Nov 7, 2026

Copy link
Copy Markdown
Code Review ✅ Approved 1 closed / 1 findings

🟢 Low risk · These documentation wording edits replace “row” with “resource” across published pages and leave executable behavior and interfaces unchanged.

Rewords the resource-in-a-collection wording from "row" to "resource" across published docs and READMEs, including the task board figure caption, leaving the six lines that quote released messages unchanged. The figure description beside the reworded line still called tasks rows, which has been addressed. No open issues found.

✅ 1 closed
✅ Quality: Figure description beside the reworded line still calls tasks rows

📄 apps/docs/docs/orchestration/task-board.md:35-37
Line 35 now reads "Its tasks are resources in a collection", but the <Figure> right below it on line 37 still has description={"... the task collection holds the rows ..."}. That description is the figure's alt text, so screen-reader users get the term this PR is removing, one line after the corrected sentence. The rule's prose regex (rows? (in|of|...) ... collection / collection rows?) doesn't match "collection holds the rows". That explains why the grep came back clean, but it's the same usage this docs-fix exists to remove. Reword it in this PR so the whole-tree turn doesn't leave an inconsistent page behind.

Verification

Rules No rules evaluated

Functional validation Not enabled

Set up

For more verification details, comment gitar display:verbose.

Options

Auto-apply is off → Gitar will not commit updates to this branch.
Display: compact → Showing compact verification results.

Comment with these commands to change the behavior for this request:

Auto-apply Compact
gitar auto-apply:on         
gitar display:verbose         

Was this helpful? React with 👍 / 👎 | Gitar

@jhoffner
jhoffner added this pull request to the merge queue Nov 8, 2026
Merged via the queue into main with commit ea563dd Nov 8, 2026
24 checks passed
@jhoffner
jhoffner deleted the docs-fix/FIX-2479-resource-wording branch November 8, 2026 14:47

This branch was successfully deployed

1 active deployment
Preview – flow-state-dev-docs — 2f3e69bc Deployed Nov 7, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants