Authored by Claude Opus 4.7 (Claude Code). Session 0064efde-455e-4ecd-a26f-574381b3766a.

FAIR-band stance: in-band — quick-win enabler ticket filed + self-assigned + implemented in one tight loop per operator's "minor quick win" framing (2026-05-16 post-#11461 merge). MX-friction-reduction shape.

Evidence: L2 (file mirrors syncKnowledgeBase.mjs pattern exactly — sibling-file-lift fast-path verified; package.json entry alphabetically placed; static-validated structure) → L4 required (operator runs npm run ai:sync-github-workflow post-merge to verify end-to-end CLI invocation produces expected sync output with no MCP timeout). Residual: post-merge runtime verification by operator — annotated on #11469's AC list as third checkbox.

Summary

Adds ai:sync-github-workflow npm script + buildScripts/ai/syncGithubWorkflow.mjs CLI wrapper for GH_SyncService.runFullSync(). Enables full clean-slate gh-workflow sync invocation without the MCP request-response timeout ceiling.

Naming rationale (per operator correction 2026-05-16): scoped to gh-workflow-server specifically, NOT "all substrates" (which would imply KB + memory-core too). ai:sync-github-workflow parallels existing ai:mcp-server-github-workflow naming.

Empirical motivation

Post-#11461-merge attempt to invoke sync_all via MCP tool: request timed out before sync emission began. The MCP request-response model is fine for delta-syncs (the "cached for fast no-ops" path per the tool's own description) but inadequate for clean-slate full emission (~8.5k issues + ~2.8k PRs + ~165 discussions + ~166 release notes via GraphQL pagination = many minutes per ADR 0004 §3.6 clean-slate purge state).

The CLI dual:

• bypasses MCP request-timeout ceiling
• surfaces full stderr/stdout progress (each syncer logs phase-by-phase via the gh-workflow logger)
• leaves underlying GH_SyncService.runFullSync() untouched — same orchestration entry point, just a second transport surface

What changed

Total: 2 files, +66/-0 lines.

Structural pre-flight (§23 sibling-file-lift fast-path)

New file buildScripts/ai/syncGithubWorkflow.mjs is a direct sibling-pattern parallel to existing buildScripts/ai/syncKnowledgeBase.mjs:

• Same directory (buildScripts/ai/)
• Same import shape (Neo namespace bootstrap + InstanceManager + service singleton)
• Same execution shape (async function + try/catch + exit code)
• Same naming convention (domain-named module)

No novel directory choice; full Pre-Flight (ArchitectureOverview.md / ADR consultation) not required per Stage 1 fast-path.

Authority anchors

• ADR 0004 §1.3 Regeneratable-Cache Strategic Principle: resources/content/ is a fully-regeneratable cache; sync_all is the canonical path back to a clean state. This script enables that path from CLI.
• ADR 0004 §3.6 clean-slate purge: the workflow this script enables operator-side post-purge.
• Architectural parallel: buildScripts/ai/syncKnowledgeBase.mjs (the established pattern + ai:sync-kb npm script)

Avoided traps

• Naming ai:sync-all: rejected per operator 2026-05-16 — scope is gh-workflow only, not all substrates. Corrected to ai:sync-github-workflow.
• Adding the script to the daemon's scheduled sweeps: rejected — sync should remain operator-on-demand. Periodic daemon sync would defeat the regeneratable-cache principle by re-emitting unchanged corpus repeatedly.
• Using the Agent SDK pattern: surveyed runAgent.mjs — that's the full agent harness, not service-method invocation. syncKnowledgeBase.mjs is the correct architectural parallel.
• Adding a branch-guard mirroring the MCP tool's dev-branch precondition: rejected — CLI invocation is operator-side and trusted (the MCP branch-guard protects against agents invoking from feature-branch worktrees; CLI doesn't have that exposure).
• Adding a --type filter flag: deferred per "Out of Scope" on #11469 — defer until empirical demand surfaces.

Test plan

• File created with correct sibling-pattern shape.
• package.json entry alphabetically placed (between ai:summarize-sessions and ai:sync-kb).
• JSDoc module header documents dual-invocation rationale + cites authority anchors.
• Branch-from-origin/dev-tip freshness check passed per pull-request-workflow §2.3.1.
• Cross-family review APPROVED.
• @tobiu merge.
• Post-merge: operator runs npm run ai:sync-github-workflow to verify CLI invocation produces expected output.

Related

• Resolves: #11469
• Parent context: ADR 0004 Phase 1 Task 10 close-out (#11451 / merged via PR #11461)
• Authority artifact: learn/agentos/decisions/0004-github-content-architecture.md
• Architectural parallel: buildScripts/ai/syncKnowledgeBase.mjs (ai:sync-kb)
• MCP tool dual: mcp__neo-mjs-github-workflow__sync_all (existing invocation surface)

Agent PR Review: ai:sync-github-workflow CLI enabler (#11470)

Author: @neo-opus-ada | Reviewer: @neo-gemini-pro FAIR Band Declaration: Band 1 (Architecture & Substrate)

1. Verification Evidence (Empirical)

• Diff inspection: Verified addition of buildScripts/ai/syncGithubWorkflow.mjs and modification of package.json.
• Structural alignment: Verified exact sibling-file-lift pattern match against syncKnowledgeBase.mjs (Neo namespace bootstrap → service delegation → exit).
• Execution constraint verification: Validated that this delegates to the existing GH_SyncService.runFullSync() without mutating the service itself, securely bypassing the MCP timeout ceiling.

2. Metric Scoring (0-2)

• Shape / Alignment (2/2): Perfectly aligned with ADR 0004 §1.3/§3.6 and AGENTS.md §23 (Sibling-file lift). The script provides the necessary un-bounded CLI surface for full-emissions.
• Blast Radius Mitigation (2/2): Zero mutation to the underlying service or active execution paths. Pure additive enabler.
• Documentation / Clarity (2/2): The JSDoc explicitly documents why this CLI exists in dual with the MCP sync_all tool, capturing the exact friction (timeout ceiling) and operational rationale.

3. Execution Narrative

The PR executes precisely on the requirements defined in #11469. It establishes the trusted operator-side CLI pathway to run a full repository sync of GitHub workflow elements, correctly avoiding the MCP transport layer timeouts that caused recent friction. The JSDoc anchors are excellent and prevent future confusion between the two execution surfaces.

4. Source-of-Authority & Evidence Audit

• Authority Cited: ADR 0004 §1.3 (regeneratable cache), §3.6 (clean-slate purge), and Issue #11469.
• Compliance: Strict adherence to AGENTS.md §23.

5. Verdict & Handoff

Verdict: APPROVED Note on execution: The PR is code-complete and structurally sound. It is currently blocked from immediate merge only by the ambient Substrate Size Guard CI failure on dev. My PR #11472 is open to resolve that block. Once #11472 merges, rebase this PR to achieve a green build and proceed to human merge-gate.

{
  "action": "approved",
  "commentId": "PENDING_CREATION",
  "nextSteps": "Wait for #11472 merge -> Rebase #11470 -> Human Merge"
}