Pilot GitHub Projects for v13 — derived release-focus view

Update 2026-05-08 — Label-Driven Canonical Membership Adopted

Effective canonical contract (supersedes "Canonical membership" line + AC3 below):

• Canonical membership = release:v13 label on issue. This Project mirrors the labeled set exactly.
• Reconciliation source: ai/scripts/reconcileV13Project.mjs drives Project membership from gh issue list --label release:v13 (NOT from #10960's native sub-issue tree).
• #10960's native sub-issue tree: retained as a human-curated organization layer; not canonical for Project membership. See #10960's "Update 2026-05-08" header for that ticket's matching contract amendment.

Why the pivot: GitHub's parent_child relationship is structurally limited to one parent per issue. #9999's existing children (e.g., #10030, #10013) cannot be re-parented under #10960 without breaking established parent_child relations. The release:v13 label co-exists with any other parent_child structure, so it is the only viable canonical signal for the v13 Project pilot.

Operational rule: When a ticket is filed/identified as gating an M1-M7 exit gate → label it release:v13. The reconciliation script keeps Project #12 in sync with that labeled set.

The original "Canonical membership" / AC3 language below describes the pre-pivot intent and is retained for decision-history visibility.

Context

Graduates Discussion #10959 per its OQ1-5 resolutions. Sub-issue of #10960 (v13 release tracking) — that ticket's native sub-issue tree provides this Project's canonical membership.

@tobiu's prompt 2026-05-08:

"all 3 of you are neo repo maintainers, and members of the neo github organization. so far, we did not use github projects yet. you have full access. would this help?" + "a project should mean: main focus items. of course additional backlog items can get tackled in parallel as needed."

Cross-family peer review (Gemini OQ3 + GPT OQ1/OQ2/OQ3/OQ4/OQ5) converged: yes to a v13-only pilot, but only as a strict Read-Only Derived View of the issue substrate. Project must NOT carry canonical state.

Operator addenda (2026-05-08, post-graduation):

1. Public visibility — release-related Projects should be publicly visible. GraphQL exposes ProjectV2.public. Default public: true unless blocked by org policy.
2. GitHub Projects v2 only — Classic Projects sunset by GitHub on github.com in 2024 and the classic REST API sunset in 2025. Target ProjectV2 / projectsV2 / UpdateProjectV2Input.public GraphQL surface exclusively.

The Problem

learn/agentos/v13-path.md documents M1-M7 as prose; #10960 carries the canonical sub-issue tree. Today release-readiness assessment requires reading multiple ticket bodies + the path doc. A visual board over the canonical substrate adds:

1. Visual milestone roadmap (M1-M7 timeline)
2. Cross-epic rollup (#10960's sub-tree flattened to one filterable surface)
3. Per-agent lane visibility (M1 owner-split rendered as columns)
4. Public release visibility — external observers (contributors, downstream users, AI ecosystem watchers) see the v13 release path without needing repo-level read access to internal coordination

But: any Project-only state fragments the swarm's context window per Gemini's framing — "if it's not on the Issue, it doesn't exist to the Swarm."

The Architectural Reality

API surface (per operator addendum 2): GitHub Projects v2 ONLY. Use the ProjectV2 / projectsV2 GraphQL types; UpdateProjectV2Input.public for visibility. NO classic REST endpoints (/projects/columns, /projects/cards), NO classic columns/cards primitives, NO migration assumptions from a v1-shaped mental model.

Source-of-truth contract (per OQ3 resolution):

• Canonical membership: native sub-issue relation under #10960
• Canonical status: issue state + existing labels (agent-task:in-progress, etc.)
• Canonical owner: assignee
• Canonical milestone tag: issue label (M1, M2, ..., M7) OR GitHub Milestone object
• Project fields: derived presentation only — zero Project-only canonical state
• Reconciliation: weekly or on-demand gh script reports drift; manual board hygiene NOT relied on

API tooling path (per OQ1 resolution):

• Start with gh CLI / GraphQL fallback. NO new MCP tool yet.
• MCP promotion threshold: 1-2 weeks pilot use AND (≥3 agent-side reads/writes per active day OR 2+ shell-friction-caused coordination failures) AND a narrow tool design statable without large tool-description payload.
• If promoted: prefer narrow read/reconcile surface (list_projects, get_project_items, sync_issue_focus_project) — NOT arbitrary board mutation.

The Fix

Pilot setup:

1. Create one ProjectV2: "Neo v13 Release" scoped to the neomjs org (not repo-level — supports cross-repo if v13 ever spans repos). Created with public: true per operator addendum 1 — release path visible to external observers.
2. Configure views:
   • Roadmap view rendering M1-M7 iterations on a timeline
   • Board view with status columns driven by labels
   • Per-owner view grouping by assignee
3. Custom field policy: iteration field MUST map bidirectionally to issue Milestone or label (per Gemini's "If native bi-directional syncing isn't possible, we shouldn't use that field"). NO Project-only fields.
4. Membership: auto-add #10960's native sub-issues; manual additions disallowed.
5. Automation rules:
   • agent-task:in-progress label → "In Progress" column
   • agent-task:review label → "Review" column
   • Issue closed → "Done" column
6. Reconciliation script: ai/scripts/reconcileV13Project.mjs — gh CLI / GraphQL — weekly cron OR on-demand operator-trigger; reports drift between #10960 sub-tree and Project membership.

Documentation (per OQ4 resolution):

• learn/agentos/GitHubWorkflow.md — add "Project state is observability-only" rule + how peers read+write Project state via gh (ProjectV2 GraphQL only)
• learn/agentos/DreamPipeline.md — explicit non-input warning: Project membership/status is NOT consumed by DreamService / GoldenPathSynthesizer

Time-box (per OQ5 resolution):

• Pilot through M3 (~3 milestones).
• Retirement criteria (any of):
  • 30%+ of release-critical tickets missing from the Project (drift indicator)
  • Operator + 2 agents independently report visualization isn't changing decisions they would have made anyway (zero-value indicator)
  • Maintenance overhead exceeds 1 hour/week aggregate operator+agent time (cost indicator)
• Positive graduation metric (must hit at least one): at least one recorded decision-value event where the Project changed prioritization, sequencing, or handoff clarity.

Acceptance Criteria

• AC1: ProjectV2 "Neo v13 Release" created at neomjs org level via GraphQL createProjectV2; @tobiu, @neo-opus-4-7, @neo-gemini-3-1-pro, @neo-gpt have access.
• AC2: Configured views: roadmap (M1-M7), board (label-driven status), per-owner (assignee group). No views with Project-only state.
• AC3: Membership auto-population from #10960 native sub-issue tree. No manual additions.
• AC4: Automation rules wired (labels → columns + closed → Done).
• AC5: ai/scripts/reconcileV13Project.mjs reconciliation script committed; reports drift; runnable via npm run ai:reconcile-v13-project.
• AC6: Docs updated: GitHubWorkflow.md + DreamPipeline.md per OQ4 resolution.
• AC7 (post-pilot): After M1-M3, evaluate against retirement criteria + positive graduation metric. Either continue pilot (with documented decision-value event), retire pilot cleanly (close this ticket + dismantle Project), OR graduate from pilot to canonical state (file separate ticket for graduation work).
• AC8: No new MCP tool surface added during pilot; if promotion threshold (per OQ1) is hit, file separate Add Projects API to mcp__neo-mjs-github-workflow__* ticket — NOT this PR's scope.
• AC9 (operator addendum 1): Project created with public: true. Verify ProjectV2.public === true post-creation via GraphQL node(id: "...") { ... on ProjectV2 { public } }. If blocked by org policy or security review, document the rationale in this ticket as an [OQ_RESOLUTION_PENDING] annotation; #10960's issue/sub-issue tree remains the public canonical substrate regardless.
• AC10 (operator addendum 2): No code, scripts, or docs reference Projects classic / v1 primitives (projects.columns, projects.cards, /repos/.../projects/columns, REST /projects/{id} endpoints). All API calls target ProjectV2 GraphQL surface. Reconciliation script (AC5) uses projectsV2(first: ...) query exclusively.

Out of Scope

• MCP tool implementation for Projects API (deferred per OQ1 promotion threshold)
• GitHub Projects classic / v1 — sunset by GitHub on github.com (2024) and classic REST API (2025). NOT a fallback. NOT a migration source. The pilot is greenfield ProjectV2.
• Cross-repo Projects (v13 is single-repo today; cross-repo as future evolution if v14 spans repos)
• Custom fields beyond the labeled-derived iteration mapping
• Manual board curation as a workflow primitive

Avoided Traps / Gold Standards Rejected

• Rejected: Project as canonical-state surface. Per Gemini's "Read-Only Derived View" rule — any Project-only state fragments the swarm context window.
• Rejected: ad-hoc membership. Membership derives from #10960 sub-tree; that's the only source.
• Rejected: build the MCP Projects tool surface upfront. Per OQ1 — promote later only if frequency/friction justifies. Premature tooling expands MCP-tool-description budget without empirical demand.
• Rejected: full release-tracking PM tool feature parity (story points, burn-down, velocity charts). Pilot scope is visualization + decision-value, not full PM-tool replication.
• Rejected: private-by-default Project visibility. Per operator addendum 1 — release tracking should be publicly visible to external observers (contributors, downstream users); private only if org policy blocks public.
• Rejected: Projects classic / v1 primitives. Per operator addendum 2 — v1 is sunset; no fallback path, no compatibility layer.

Related

• Parent ticket: #10960 — v13 release tracking (canonical sub-issue tree)
• Grandparent epic: #9999 — Cloud-Native Knowledge & Multi-Tenant Memory Core (v13 main epic)
• Strategic anchor: learn/agentos/v13-path.md
• Graduation source: Discussion #10959 — all 5 OQs RESOLVED_TO_AC by cross-family peer review (Gemini OQ3, GPT OQ1/OQ2/OQ3/OQ4/OQ5)
• Operator addenda:
  • #10961 commentId IC_kwDODSospM8AAAABBqSdpQ — public visibility (relayed by @neo-gpt with empirical verification of ProjectV2.public field)
  • #10961 commentId IC_kwDODSospM8AAAABBqSuPw — ProjectV2-only mandate (relayed by @neo-gpt with sunset-date verification)

Origin Session ID: 005b6edf-85d8-4980-9e17-486b6b8bed3f

Retrieval Hint: `query_raw_memories(query="GitHub Projects v2 pilot v13 Read-Only Derived View main focus items reconciliation gh CLI fallback iteration field bidirectional mapping public visibility ProjectV2")`