Maintain Project Board

Maintain: 🌊 Project Board (org project 5)

github.com/orgs/devantler-tech/projects/5 is a product, not a byproduct — it is the maintainer's single surface for seeing what exists, what is moving, and where it is headed across ~20 repos. It gets the same continuous-enhancement treatment as every other product: it participates in the normal rotation, it has a roadmap, and drift in it is a defect (maintainer direction 2026-07-18).

Its users are the maintainer and the agent instances. Judge it the way a user would: open it and ask "can I tell what is happening here?" — not "is the data technically present". A board that is accurate but unreadable has failed.

Shared cross-repo rules live in the monorepo AGENTS.md — in particular Issue hierarchy and Every issue belongs on the board, which are binding on every run whatever product it is working on. This card is the place where the board itself gets improved.

Health checks (the operate half — cheap, every rotation)

Run these as a survey pass; each has a known-good answer.

🔴 Do NOT check the board by enumerating it — an explicit high limit does NOT make enumeration safe. gh project item-list defaults to --limit 30, but raising the limit only moves the cut: measured 2026-08-06, --limit 3000 returned exactly 3000 items against a true projectV2{items{totalCount}} of 4988, with no truncation signal — no warning, no error, exit 0. ~40% of the board was silently absent, so every check below would have reported clean while the drift sat past the cut. Returning exactly the limit is the only tell, and it is one the caller has to look for.

⚠️ Enumeration also costs the whole hourly GraphQL budget, which every lane shares. That same pass left graphql: {limit:5000, remaining:73}. The budget is attached to the user, so all registered writer namespaces draw on it — and the surveyor's paginated reviewThreads queries are what the hygiene pentad's unresolved-thread count depends on. A starved pentad reads as clean, which is a fail-open on the promotion gate. Never spend the shared budget on a board sweep to answer a question a per-issue query answers for ~1 point.

So: ask per issue, not per board. For coverage and membership, query the issue's own side. That read is cheap and it distinguishes "on no project" from "on the board" (negative control: platform#1 → [], verified non-vacuous) — but it carries the same three fail-open traps the enumeration does, so it gets the same discipline:

• Identify the board by its id, never by number alone. A number is unique only within one owner, so a repository-level project or another owner's project numbered 5 satisfies a number-only match and reports an unboarded issue as covered.
• Paginate. projectItems(first: N) truncates exactly like item-list --limit N, and here the truncated read produces the worse answer: "not on the board" for an issue that is.
• Fail closed on the read itself. An empty projectItems and a failed query look identical downstream. Only a successful query may be read as "not on a project"; anything else is unverified, which is a different outcome from either answer.

includeArchived: false is explicit because an archived item is not on the board for triage — it is covered by the archive, not by the sweep, and the default would quietly count it as coverage.

# Resolved once per run; a number alone is not an identity.
BOARD_ID=$(gh api graphql -f query='{organization(login:"devantler-tech"){projectV2(number:5){id}}}' \
  --jq '.data.organization.projectV2.id') \
  || { echo "board id lookup failed; refusing" >&2; exit 1; }

# 0 = on the board, 1 = verified absent, 2 = UNVERIFIED (never conflate 1 and 2).
on_board() { # on_board <owner> <repo> <issue-number>
  _ob_after=null   # prefixed: the function assigns in the caller's scope
  while :; do
    _ob_page=$(gh api graphql -F owner="$1" -F name="$2" -F number="$3" -F after="$_ob_after" -f query='
      query($owner:String!,$name:String!,$number:Int!,$after:String){
        repository(owner:$owner,name:$name){ issue(number:$number){
          projectItems(first:100, after:$after, includeArchived:false){
            nodes{ project{ id } } pageInfo{ hasNextPage endCursor } } } } }') || return 2
    printf '%s' "$_ob_page" | jq -e '.data.repository.issue.projectItems' >/dev/null || return 2
    if printf '%s' "$_ob_page" | jq -e --arg id "$BOARD_ID" \
         '[.data.repository.issue.projectItems.nodes[].project.id] | index($id)' >/dev/null; then
      return 0
    fi
    printf '%s' "$_ob_page" | jq -e '.data.repository.issue.projectItems.pageInfo.hasNextPage' >/dev/null \
      || return 1
    _ob_after=$(printf '%s' "$_ob_page" | jq -r '.data.repository.issue.projectItems.pageInfo.endCursor')
  done
}

(-F is what makes the first page's null a JSON null rather than the string "null"; a later cursor that happened to look like a number or boolean would be coerced too, and GraphQL would reject it — an error, so 2, never a wrong answer. index($id) returning 0 for the first item is truthy to jq -e, which fails only on false and null; do not "fix" that into a length test.)

If a check genuinely needs the whole board, pair the enumeration with a mandatory truncation guard and treat a trip as a hard failure, never a result:

total=$(gh api graphql -f query='{organization(login:"devantler-tech"){projectV2(number:5){items{totalCount}}}}' \
  --jq '.data.organization.projectV2.items.totalCount') \
  || { echo "totalCount query failed; refusing" >&2; exit 1; }
items=$(gh project item-list 5 --owner devantler-tech --format json --limit "$LIMIT") \
  || { echo "item-list failed; refusing" >&2; exit 1; }
n=$(printf '%s' "$items" | jq '.items | length')
for v in "$n" "$total"; do
  case "$v" in ''|*[!0-9]*) echo "non-numeric count [$v]; refusing" >&2; exit 1 ;; esac
done
if [ "$n" -eq "$LIMIT" ]; then echo "TRUNCATED at limit ($n); refusing" >&2; exit 1; fi
if [ "$n" -lt "$total" ];  then echo "INCOMPLETE: $n of $total; refusing" >&2; exit 1; fi

(Written as if, not cond && { …; exit 1; }. Measured: the && form is safe mid-script — set -e exempts a non-final component of an AND-OR list — but on the healthy path it evaluates to 1, so as the last command of a script or function it returns a spurious failure and takes a set -e caller down with it. if has no such edge. Set LIMIT above totalCount; the equality arm is what catches the silent cut.)

🔴 Each gh call is checked on its own line, and both counts are asserted numeric, because otherwise this guard fails OPEN — the exact direction it exists to prevent. Measured: with gh returning non-zero, the old one-line pipeline left n empty; [ "" -eq "$LIMIT" ] and [ "" -lt "$total" ] then both exit 2 with integer expression expected, and a [ failure inside an if condition is exempt from set -e — so both arms evaluated false, the script reached its success path, and it exited 0 having counted nothing. A rate limit therefore read as a clean board. set -o pipefail alone would not have saved it either: the pipeline masks gh's status behind jq's. Verified in all three states — gh failing ⇒ exit 1, a genuine truncation (n == LIMIT) ⇒ exit 1, and a healthy full read ⇒ exit 0, so the guard is not vacuous.

Never suppress stderr on these calls: a rate-limited gh prints API rate limit exceeded and exits non-zero, and a 2>/dev/null turns that into an empty result indistinguishable from a clean board.

Never close an Epic while any descendant is still open. Close the Epic only when its children are done (or explicitly cancelled). If a survey finds a closed Epic with open descendants, re-open it immediately — that is the #2266 resolution, not a Backlog filter change.

Coverage and hierarchy are the two that silently rot, because auto-add is forward-only and capped at 5 workflows on the Team plan — see monorepo#2237. Until that is solved, backfill is a standing duty, not an exception.

What "advance" means here

• Views — exactly three, and resist adding a fourth. The board carries a kanban (board), a backlog (table) and a roadmap (roadmap) view. Epic breakdown lives on the Backlog view via the Show hierarchy toggle, NOT as a separate view and NOT as a Parent issue group-by — maintainer direction 2026-07-18, when a proposed fourth "By epic" view was folded into the Backlog instead. The principle generalises: prefer an extra grouping, slice or filter on an existing view over a new view. Every additional view is another surface to keep honest and another place for the maintainer to look; a board with three well-configured views beats one with seven overlapping ones. Add a fourth only when a genuine audience or cadence cannot be served by grouping an existing view. ⚠️ Creating a view is scriptable; EDITING one is not. REST documents POST /orgs/{org}/projectsV2/{project_number}/views with name, layout (table/board/roadmap), filter and visible_fields — so a new view can be created from the API. There is no documented PATCH/DELETE for a view, ProjectV2View is a read-only GraphQL type (no view mutations), and gh project has no view subcommand — so changing an existing view's filter, layout, grouping or toggles needs a browser with the maintainer's session. (A GET against the views path 404s on this org, so treat the POST as documented-but-unexercised: verify before relying on it, and don't create a throwaway view to test — there is no documented way to delete it.) Propose view edits precisely (layout, filter string, grouping, visible fields) so applying them by hand is mechanical.

  The only browser an agent can DRIVE is Chrome via the Claude extension. Computer-use grants browsers at read tier only — screenshots work, clicks and typing are blocked at the OS level — so Safari/Firefox/Arc can be seen but never operated, by design. Don't burn a round trip requesting browser access for a click-through task; check list_connected_browsers first, and if nothing is connected, say so and offer the tooltip-guided walkthrough instead. When saving a view, GitHub prompts "make it the default for everyone" — the board is shared, so every view save is a public change.

  Current configuration (verified live 2026-07-18):

  View	Layout	Filter
  🧮 Kanban	Board	is:issue is:open -status:"✅ Done" -type:"Epic"
  📋 Backlog	Table	is:issue is:open no:parent-issue
  🗺️ Roadmap	Roadmap	is:issue is:open type:"Epic" no:parent-issue

  Keep these three filters. #2266 asked whether open work under a closed root should be fixed by changing the Backlog filter, re-opening the root, or re-parenting. Decision (2026-07-22): re-open the root (and never close an Epic with open descendants). A filter change cannot express that case, a fourth view would violate the three-view rule, and re-parenting destroys the recorded decomposition. No maintainer UI edit is required for this decision.

  Each view shows one layer of the hierarchy, and only one (maintainer direction 2026-07-18): Kanban = actionable work only — a parent is resolved by finishing its children, so an epic is never something you drag across a board; Backlog = top-level only (no:parent-issue) with children reached by expanding the hierarchy, never listed as sibling rows; Roadmap = top-level Epics.

  ⚠️ Filter on type:"Epic", NOT on no:sub-issues-progress or label:roadmap. The structural filter only excludes epics that have already been decomposed — 37 undecomposed epics were sitting on the Kanban looking like actionable work, because an epic nobody has broken down yet has no children to detect. Switching to -type:"Epic" dropped the Kanban 166 → 130 and is correct from the moment an issue is filed. The label is likewise unreliable: it depends on label hygiene, and Epic as a type is a superset (62 epics vs 55 roadmap-labelled).

  The board tracks ISSUES, not PRs (maintainer direction 2026-07-18): a PR that closes an issue stands in for that issue's progress, so showing both double-counts the same work — dropping ,pr took the Ready column from 8/5 to a true 2/5. ⚠️ No automation moves an issue card from its linked PR's state — native Project workflows act only on the project's own items, and nothing in this org updates an issue's Status from PR events. **The agent working the PR moves the issue's Status by hand at each lifecycle step, when that step's entry condition in AGENTS.md actually holds — a PR merely being open is still 🏃🏻‍♂️ In Progress; it becomes 👀 In Review only once CI is green and a review has been requested, and 🚀 Ready to Merge only on a green review at head with the pentad clear. Moving a card early makes the board overstate progress, which is the one thing a status ladder must never do. Only the final closed→Done move is a built-in workflow.

  ⚠️ 📊 Verifying belongs on the issue that is still OPEN, not on the one the merge just closed. A delivery PR carries Fixes #delivery, so merging closes that issue and the built-in closed→Done workflow marks it ✅ Done — moving it to Verifying would either be immediately overwritten or leave finished work looking pending. When the outcome cannot be known at merge, the PR also carries Part of #experiment; that experiment/Kata issue stays open, and it is the one that goes to 📊 Verifying until its measurement date, when it becomes ✅ Done with the decision recorded. If a change has no separate experiment issue but still needs a post-merge check, keep the delivery issue open (drop Fixes, use Part of) rather than closing it and reopening it. This also makes Fixes #N load-bearing for visibility, not just bookkeeping: an agent-authored PR with no linked issue is now invisible on the board, so the capture-before-you-build rule is what keeps the board complete. When a substantive PR has no issue, the fix is to file/link the issue — never to put PRs back on the board. Dependency-automation PRs correctly disappear: they are automation-owned and need no action, so they were only ever noise on a planning surface.

  Backlog has Show hierarchy = On, which nests sub-issues under their parents inline (up to 8 levels) — that is what makes it the by-epic view; do not add a Parent issue group-by on top, and do not turn the toggle off. Roadmap binds Start/Target to the Year iteration's Year start/Year end, zoom Year, with the Year marker on; items without a Year show an unscheduled + placeholder, which is the honest rendering of "not scheduled".

  Hierarchy filters — use the FIELD name, and get it from the UI, not from docs. The working qualifiers are has:sub-issues-progress (is a parent) / no:sub-issues-progress (is a leaf), and has:parent-issue / no:parent-issue / parent-issue:owner/repo#N. They key off the project field name ("Sub-issues progress"), not the issue-search spelling: has:sub-issue is NOT a valid project filter — GitHub silently ignores an unrecognised qualifier rather than erroring, so a wrong guess looks like it worked.

  ⚠️ Two method rules, learned the hard way on 2026-07-18:

  1. Never compare item counts across views to test a filter. Board and table layouts count differently — the same stricter filter read 193 on the board and 163 in the table. A cross-view comparison produced a confidently wrong conclusion (that has:sub-issue was being ignored and that no parent filter existed). Always A/B a filter within ONE view.
  2. Type no: into the filter box to get the authoritative qualifier list. GitHub autocompletes every supported field; picking from that list inserts the exact syntax. That is faster and more reliable than docs, which do not enumerate project-field qualifiers.

• Status semantics. Options run ✅ Done → 📊 Verifying → 🚀 Ready to Merge → 👀 In Review → 🏃🏻‍♂️ In Progress → 🫴 Ready → 📥 Backlog → 🧊 Icebox, and the merge is the boundary between Ready to Merge (pre-merge, mechanical) and Verifying (post-merge, evidential). The order is deliberately reversed — finishing work sits leftmost, so the board reads stop starting, start finishing (maintainer direction 2026-07-18). Never re-order it into left-to-right flow. Column limits encode the same WIP discipline; treat an over-limit column as a signal to finish, never as a reason to raise the limit. "Blocked" is intentionally not a status — use a native issue dependency (Blocked badge renders in-place) and reserve the blocked label for cross-org blockers.

• Issue Types are mandatory — every issue carries exactly one of Epic, Feature, Bug, Security, Performance, Refactor, Docs, Spike, Kata, Chore (see the contract's Issue hierarchy for the definition-of-done each implies). An untyped issue is an incomplete issue. Setting one always works, but always name the repo — a bare number resolves in the current repo, so triaging another repo's item from the monorepo would type the same-numbered monorepo issue instead: gh issue edit <N> --repo devantler-tech/<repo> --type "<Type>" (or pass the issue URL). Managing the org type list is a REST surface — collection GET/POST /orgs/{org}/issue-types, then item-specific PUT and DELETE /orgs/{org}/issue-types/{issue_type_id} (there is no collection-level PATCH) — but it needs admin:org (Issue Types write), which the routine's PAT does not carry (it 403s). So: use the API when the token has the scope — that is the auditable path and it works unattended — and fall back to org settings in a browser only when it does not. Do not treat type-list drift as un-fixable just because one token lacks the scope.

• The roadmap axis. A roadmap layout plots date or iteration fields only — it does not render hierarchy. The Year iteration field (2026/2027/2028) is the current coarse axis and is assigned on evidence of activity, never by assumption. Finer Start date/Due date values encode the maintainer's intent — do not invent them; propose a sequence and let him drag, or ask.

• Fields. 50-field cap per project. Prefer an org-level issue field over a project field when the value should be identical everywhere (25/org) — project fields are per-board by design.

• Insights. Charts exist and are underused. Note the trap: archived items are excluded from Insights entirely, so an aggressive archive rule silently truncates historical burn-up.

Mutation safety

• updateProjectV2Field with singleSelectOptions replaces the whole option list — always pass the existing option **id**s or every assignment is destroyed. Verify emoji codepoints after writing (🫴 Ready is U+1FAF4; a wrong codepoint silently rewrites the option name).
• Adding an item and setting its fields are two separate calls — you cannot do both at once.
• Pace bulk work: ~80 content-generating requests/minute, 500/hour. Serialize; never fan out.
• The board is public. Adding items from private repos is a maintainer decision, not an agent default.

Roadmap & enhancement

Roadmap lives in GitHub Issues on devantler-tech/monorepo — never enumerated here, because a hard-coded list goes stale the moment an issue closes or a new one is filed (the same mistake the retired status-board made). Query it live:

That issue repository also anchors coordination for path-less board/API work: acquire agent-claim/<issue> against the monorepo root before mutating, retain the returned SHA, atomically renew the retained SHA immediately before the board mutation with claim_sha="$(.claude/scripts/agent-claim.sh renew <issue> "$claim_sha" --repo-dir <monorepo-root>)", and retire that renewed SHA only after the resulting board state is read back and verified. A failed renew means a takeover won or ownership is unknown, so stand down without mutating. A comment is an activity record, not an atomic claim.

Board work hangs off the board Epic — monorepo#2261 — so it is found structurally, never by string matching:

gh api "search/issues?q=org:devantler-tech+is:issue+is:open+parent-issue:devantler-tech/monorepo%232261&per_page=100" \
  --jq '.items[] | "#\(.number)\t\(.created_at[0:10])\t\(.title)"'

A text search ("board" in:title,body) was tried and rejected: it misses board issues that don't contain the word ("Automate stale-item archiving") and pulls in unrelated issues that merely mention a board. A hard-coded list was rejected before that, for going stale on the first close. File new board work as a child of #2261 — the contract's default that every issue belongs to an Epic, applied to the board's own product.

The strategic frame: what can the maintainer still not see at a glance? Answer that, and the board has advanced.