docs: FOC board rule updates from 2026-05-05 sweep

[BigLep]

Summary

Rule and workflow improvements discovered during FOC board sweeps on 2026-05-05, 2026-05-06, and 2026-05-07:

Rule updates

• R-SL-001: Add re-requested reviewer exception — if a reviewer who requested changes is re-requested, their objection is not superseded by another approval
• R-SL-008: Require linked PR to be In Progress or later before moving an issue to "Issue awaiting PR merge"; add cycle inheritance from linked PRs regardless of milestone; use has:linked-pull-requests board filter to narrow queries to only issues with linked PRs
• R-SL-008 unlinked PR discovery: Use no:linked-pull-requests filter on In Progress issues, then targeted timelineItems GraphQL
• R-PR-007: Require Phase 2 before flagging — empty reviewRequests is ambiguous (pending requests are consumed when a review is submitted); do not flag based on Phase 1 data alone
• R-PR-007 (external items): Exclude repos outside blessed orgs — cannot request reviewers, so flagging is noise
• README rule 4: Require hyperlinks on all item references in reports/flags

Playbook improvements

• Stage 0 (new): Create a unique sweep workspace directory (/tmp/foc-board-sweep@<timestamp>) so all file writes target new files, avoiding Write tool read-first issues
• Stage 1 ordering: Run cycle-gap queries after status mutations so newly in-flight items get caught
• Stage 1 cross-referencing: Use format: "compact" + Write-to-disk + jq reconstruction workflow; add R-PR-007 to Phase 2 candidate action lists
• Stage 1 Phase 2 batching: Collect all Phase 2 candidates (R-PR-006, R-PR-007, empty reviewDecision) into a single list, then fetch in parallel instead of sequential per-rule lookups
• Stage 4 R-SL-008: Use has:linked-pull-requests filter instead of fetching all non-Done issues with verbose "Linked pull requests" field
• Stage 5 targeted queries: Replace bulk Done-item fetch with targeted gap queries to avoid wasting context on 100+ items

Agent prompt updates

• Make FilOzzy MCP + GitHub CLI/MCP a hard prerequisite
• Add setup step: create sweep workspace before queries
• Add pitfall [WIP] feat: add GitHub Projects v2 exporter for FOC GA Tracker #7: use format: "compact", Write to $SWEEP/ immediately, check pagination
• Add pitfall feat: add GitHub milestone manager script #8: use jq for board + GitHub metadata joins (not manual reasoning)

FilOzzy MCP server (filozzy-mcp)

• format: "compact": New columnar JSON format for list_board_items — field names appear once, rows are value arrays (~40-60% fewer tokens than format: "json")
• format: "json": New object-per-item JSON format with pagination metadata
• Refactored display item building into shared _build_display_items() helper
• Unit tests: 15 tests for _format_json and _format_compact (roundtrip, sparse rows, pagination, size comparison, unicode)
• Document pseudo-fields (Node ID, Repository, Id, Number, url, Title, Kind, Assignees) in list_board_items docstring

GitHub Projects Client (github-projects-client)

• Trim linked PR objects: GitHub Projects v2 REST API returns full PR payloads (~8KB each) for "Linked pull requests" field. Now trimmed to compact JSON with just {repo, number, state, draft, title, author} (~100 bytes each)
• Unit tests: 8 tests for linked PR trimming (valid JSON output, kept/stripped fields, size comparison, backwards compatibility)
• README: Document field value trimming behavior

Future ideas

• Async result refs: Documented design for server-side result storage with ref-based fetch, eliminating token I/O for large results when MCP server goes external

Other

• Regenerate filozzy-mcp/uv.lock for Python >=3.13 constraint

Test plan

• Rules applied successfully in full board sweeps on 2026-05-05, 2026-05-06, and 2026-05-07
• _format_compact unit tests pass (15/15)
• Linked PR trimming unit tests pass (15/15)
• Next sweep agent session uses format: "compact", $SWEEP/ workspace, and batched Phase 2

[Copilot]

Pull request overview

Updates the FOC board rule documentation and sweep guidance based on the 2026-05-05 full-board sweep, aiming to reduce sweep errors and improve consistency when cross-referencing board items with GitHub PR metadata.

Changes:

• Added Stage 1 guidance for programmatically cross-referencing board PRs with GitHub “Phase 1” metadata using jq.
• Updated lifecycle rule R-SL-008 to only move issues to “⌚️ Issue awaiting PR merge” once a linked PR is actively in flight, and to inherit cycle from linked PRs even when milestone logic wouldn’t apply.
• Strengthened sweep-agent prerequisites/pitfalls and updated README guidance to require hyperlinks in reports and treat empty reviewDecision as ambiguous.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.

File	Description
foc-board-rules/sweep-playbook.md	Adds jq-based cross-referencing workflow and updates Stage 4 queries/rule notes to reflect R-SL-008 refinements.
foc-board-rules/sweep-agent-prompt.md	Tightens required tool prerequisites and adds a pitfall warning against manual JSON cross-referencing.
foc-board-rules/status-lifecycle.md	Updates R-SL-001 with a re-requested-reviewer exception and refines R-SL-008 semantics + cycle inheritance guidance.
foc-board-rules/README.md	Requires hyperlinks in reporting and clarifies how to interpret empty reviewDecision during Phase 1 triage.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 8 out of 9 changed files in this pull request and generated 5 comments.

Comments suppressed due to low confidence (1)

filozzy-mcp/filozzy_mcp/server.py:455

• list_board_view_items accepts a format parameter but only handles format == "json"; any other value (including "compact") silently returns the human JSONL format. To avoid surprising behavior, consider either (a) validating format and erroring on unsupported values here, or (b) adding support for "compact" for parity with list_board_items.

    if not items:
        msg = f"No items found for view URL: {view_url}"
        if order_warning:
            msg = order_warning + "\n\n" + msg

[Copilot]

Pull request overview

Copilot reviewed 11 out of 12 changed files in this pull request and generated 3 comments.

[rjan90]

I think compact pagination can still produce incompatible schemas across pages here. Since _build_display_items() strips empty values before _format_compact() builds columns, page 1 and page 2 can end up with different column sets for the same requested fields.

The playbook merge example keeps page 1’s .columns and just concatenates rows, so if a field is empty on page 1 but present on page 2, reconstruction can silently drop or mislabel values.

[BigLep]

Agreed — I have a follow-up PR that discards compact entirely, so I won't fix this now.

[rjan90]

Need to fix the lint-failure to make CI green at least. Also added another comment. But apart from that looks good to me, so will add the approval to not block merge, once lint-fix is in.

[BigLep]

I will merge this, but I have a followup PR to simplify and clean things up.