Two-way GitHub Sync (Cycle 0021)

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## Unreleased
 
+- Two-way GitHub Sync (0021-two-way-github-sync)
 - Automated Witness Capture (0020-automated-witness-capture)
 - Config Management (0019-config-management)
 - Method Cli (0001-method-cli)
@@ -24,8 +25,8 @@
 - Ship Sync Automation (0018-ship-sync-automation)
 ### Fixed
 
-- Resolved review feedback on PR #5: revised release runbook bullets for 
-  clarity, enforced phase heading order in tests, and clarified 
+- Resolved review feedback on PR #5: revised release runbook bullets for
+  clarity, enforced phase heading order in tests, and clarified
   commitment and signpost boundedness invariants.
 
 ## Unreleased

README.md

@@ -7,7 +7,8 @@ A backlog, a loop, and honest bookkeeping.
 ### Stances
 
 **The agent and the human sit at the same table.** They see different
-things. Both are named in every design. Both must agree before work
+things. Both are named in every design as abstract roles (e.g.,
+"Repository Operator", "System Architect"). Both must agree before work
 ships.
 
 **Default to building the agent surface first** - it is the foundation
@@ -157,7 +158,7 @@ The backlog file is removed. Work does not live in two places.
 
 ### Commitment
 
-Pull it and you own it - "you" meaning the named sponsors (human and
+Pull it and you own it - "you" meaning the named sponsor roles (human and
 agent) in the design doc. It does not go back.
 
 - **Finish** - hill met.

docs/BEARING.md

@@ -14,9 +14,9 @@ Current priority: pull TBD to continue the system's maturity.
 
 ## What just shipped?
 
+- `0021-two-way-github-sync`: Two-way GitHub Sync
 - `0020-automated-witness-capture`: Automated Witness Capture
 - `0019-config-management`: Config Management
-- `0018-ship-sync-automation`: Ship Sync Automation
 
 ## What feels wrong?
 

docs/VISION.md

@@ -1,10 +1,10 @@
 ---
 title: "METHOD - Executive Summary"
-generated_at: 2026-04-04T20:20:00-07:00
+generated_at: 2026-04-04T22:35:00-07:00
 generator: "manual synthesis following Executive Summary Protocol (Cycle 0013)"
-generated_from_commit: "644e40a9205213ba4d3db5b233c7042ea1ba687e"
+generated_from_commit: "921706b9fc9fd5c7cf78331bdd0f3f91013ea558"
 provenance_level: artifact_history
-witness_ref: docs/method/retro/0020-automated-witness-capture/witness/verification.md
+witness_ref: docs/method/retro/0021-two-way-github-sync/witness/verification.md
 source_files:
   - README.md
   - CHANGELOG.md
@@ -32,6 +32,7 @@ source_files:
   - docs/design/0018-ship-sync-automation/ship-sync-automation.md
   - docs/design/0019-config-management/config-management.md
   - docs/design/0020-automated-witness-capture/automated-witness-capture.md
+  - docs/design/0021-two-way-github-sync/two-way-github-sync.md
 ---
 
 # METHOD - Executive Summary
@@ -50,16 +51,16 @@ state of the system without replacing the underlying files.
 ## Current state
 
 METHOD has evolved from pure doctrine into a formal, programmable system.
-Twenty cycles are already closed:
+Twenty-one cycles are already closed:
 
 - **CLI Foundations (0001-0004, 0007):** Established the CLI, witness
   conventions, and separated the module structure.
 - **Enforcement (0005-0006):** Added the `drift` command and CI gates.
 - **Maturity (0008-0011, 0016, 0019):** Formalized releases, metadata
   contracts, extracted a clean API, adopted System-Style JS, and
   implemented a formal configuration system.
-- **Connectivity (0012, 0014):** Implemented an MCP server and a GitHub
-  Issue synchronization adapter.
+- **Connectivity (0012, 0014, 0021):** Implemented an MCP server and full
+  two-way GitHub Issue synchronization.
 - **Workflow (0013, 0015, 0017-0018, 0020):** Formalized the Executive
   Summary Protocol, Git branch doctrine, Behavior Spikes, Ship Sync
   automation, and Automated Witness Capture.
@@ -80,7 +81,7 @@ The repo is organized under two legends:
 Covers cycle discipline, backlog movement, adapters (GitHub, MCP), and
 named patterns (spikes, workflow).
 - **Active:** None.
-- **Up-next:** `PROCESS_two-way-github-sync`.
+- **Up-next:** `PROCESS_i18n-string-extraction`.
 
 ### SYNTH
 Covers repo self-description, signposts, and provenance level.
@@ -93,8 +94,8 @@ Covers repo self-description, signposts, and provenance level.
 - None.
 
 ### Up-next
-- **PROCESS_two-way-github-sync:** Support syncing comments and labels
-  back to the filesystem backlog.
+- **PROCESS_i18n-string-extraction:** Extract hardcoded English strings into
+  a centralized messages file.
 
 ### Inbox
 - None.

docs/design/0009-generated-signpost-provenance/generated-signpost-provenance.md

@@ -8,8 +8,8 @@ Source backlog item: `docs/method/backlog/asap/SYNTH_generated-signpost-provenan
 
 ## Sponsors
 
-- Human: @james
-- Agent: @gemini-cli
+- Human: Backlog Operator
+- Agent: Sync Automator
 
 ## Hill
 

docs/design/0010-yaml-frontmatter-schema/yaml-frontmatter-schema.md

@@ -8,8 +8,8 @@ Source backlog item: `docs/method/backlog/inbox/PROCESS_yaml-frontmatter-schema.
 
 ## Sponsors
 
-- Human: @james
-- Agent: @gemini-cli
+- Human: Backlog Operator
+- Agent: Sync Automator
 
 ## Hill
 

docs/design/0011-library-api-surface/library-api-surface.md

@@ -10,8 +10,8 @@ Legend: PROCESS
 
 ## Sponsors
 
-- Human: @james
-- Agent: @gemini-cli
+- Human: Backlog Operator
+- Agent: Sync Automator
 
 ## Hill
 

docs/design/0012-mcp-server/mcp-server.md

@@ -10,8 +10,8 @@ Legend: PROCESS
 
 ## Sponsors
 
-- Human: @james
-- Agent: @gemini-cli
+- Human: Backlog Operator
+- Agent: Sync Automator
 
 ## Hill
 

docs/design/0013-executive-summary-protocol/executive-summary-protocol.md

@@ -10,8 +10,8 @@ Legend: SYNTH
 
 ## Sponsors
 
-- Human: @james
-- Agent: @gemini-cli
+- Human: Backlog Operator
+- Agent: Sync Automator
 
 ## Hill
 

docs/design/0014-github-issue-adapter/github-issue-adapter.md

@@ -10,8 +10,8 @@ Legend: PROCESS
 
 ## Sponsors
 
-- Human: @james
-- Agent: @gemini-cli
+- Human: Backlog Operator
+- Agent: Sync Automator
 
 ## Hill
 

docs/design/0015-git-branch-workflow-policy/git-branch-workflow-policy.md

@@ -10,8 +10,8 @@ Legend: PROCESS
 
 ## Sponsors
 
-- Human: @james
-- Agent: @gemini-cli
+- Human: Backlog Operator
+- Agent: Sync Automator
 
 ## Hill
 

docs/design/0016-system-style-javascript-adoption/system-style-javascript-adoption.md

@@ -10,8 +10,8 @@ Legend: PROCESS
 
 ## Sponsors
 
-- Human: @james
-- Agent: @gemini-cli
+- Human: Backlog Operator
+- Agent: Sync Automator
 
 ## Hill
 

docs/design/0017-behavior-spike-convention/behavior-spike-convention.md

@@ -10,8 +10,8 @@ Legend: PROCESS
 
 ## Sponsors
 
-- Human: @james
-- Agent: @gemini-cli
+- Human: Backlog Operator
+- Agent: Sync Automator
 
 ## Hill
 

docs/design/0018-ship-sync-automation/ship-sync-automation.md

@@ -10,8 +10,8 @@ Legend: PROCESS
 
 ## Sponsors
 
-- Human: @james
-- Agent: @gemini-cli
+- Human: Backlog Operator
+- Agent: Sync Automator
 
 ## Hill
 

docs/design/0019-config-management/config-management.md

@@ -10,8 +10,8 @@ Legend: PROCESS
 
 ## Sponsors
 
-- Human: @james
-- Agent: @gemini-cli
+- Human: Backlog Operator
+- Agent: Sync Automator
 
 ## Hill
 

docs/design/0020-automated-witness-capture/automated-witness-capture.md

@@ -10,8 +10,8 @@ Legend: SYNTH
 
 ## Sponsors
 
-- Human: @james
-- Agent: @gemini-cli
+- Human: Backlog Operator
+- Agent: Sync Automator
 
 ## Hill
 

docs/design/0021-two-way-github-sync/two-way-github-sync.md

@@ -0,0 +1,79 @@
+---
+title: "Two-way GitHub Sync"
+legend: PROCESS
+---
+
+# Two-way GitHub Sync
+
+Source backlog item: `docs/method/backlog/up-next/PROCESS_two-way-github-sync.md`
+Legend: PROCESS
+
+## Sponsors
+
+- Human: Backlog Operator
+- Agent: Sync Automator
+
+## Hill
+
+Extend the GitHub adapter to support full two-way synchronization between
+the local filesystem and GitHub Issues. The filesystem remains the
+authority for local content; the adapter will:
+1. **Push**: Update existing GitHub issues if the local title or body has
+   changed since the last sync. (This is the default action for
+   `sync github`).
+2. **Pull**: Update local backlog items with remote labels, status
+   (Open/Closed), and top-level comments to keep the local context rich.
+
+If both `--push` and `--pull` are provided, they run sequentially:
+local changes are pushed first, then remote updates are pulled.
+
+## Playback Questions
+
+### Human
+
+- [ ] `method sync github --push` (or default) updates the title and
+  description of an existing GitHub issue if the local file changes.
+- [ ] `method sync github --pull` updates local backlog files with data
+  from GitHub (labels, status, comments).
+- [ ] `method sync github --push --pull` runs both operations
+  sequentially (Push then Pull).
+- [ ] Local files reflect GitHub status (e.g., if an issue is closed on
+  GitHub, the local file is updated or moved).
+
+### Agent
+
+- [ ] `GitHubAdapter.pushBacklog()` and `GitHubAdapter.pullBacklog()` are
+  implemented and tested with mocks.
+- [ ] `tests/github-adapter.test.ts` proves that both remote-to-local and
+  local-to-remote updates work correctly.
+
+## Accessibility and Assistive Reading
+
+- Linear truth / reduced-complexity posture: Syncing remote comments
+  locally ensures the full context of an item is available in a single
+  linear markdown file.
+- Non-visual or alternate-reading expectations: Same as one-way sync.
+
+## Localization and Directionality
+
+- Locale / wording / formatting assumptions: Standard English for synced
+  content headers.
+
+## Agent Inspectability and Explainability
+
+- What must be explicit and deterministic for agents: The mapping of
+  GitHub states to local lane movements must be deterministic.
+- What must be attributable, evidenced, or governed: The source of the
+  synced data (GitHub) must be clear.
+
+## Non-goals
+
+- [ ] Real-time sync (this remains a manual command-triggered move).
+- [ ] Conflicts resolution (filesystem wins for title/body content on
+  push; metadata like labels and comments are enriched on pull).
+
+## Backlog Context
+
+Implement two-way synchronization for the GitHub adapter, allowing
+labels, comments, and issue status to sync back from GitHub to the local
+filesystem backlog.

docs/invariants/sponsor-abstractness.md

@@ -0,0 +1,26 @@
+---
+title: "Invariant: Sponsor Abstractness"
+---
+
+## What must remain true?
+
+Sponsors named in design documents are abstract roles, not specific
+individuals or agent instances.
+
+## Why does it matter?
+
+METHOD is a coordination protocol between two seats at the table: the
+Human and the Agent. Naming literal people (e.g., "@james") or literal
+agents (e.g., "@gemini-cli") creates a brittle, person-dependent history.
+Roles (e.g., "Repository Operator", "Code Hardener", "Protocol Designer")
+describe *who would care* about the feature and *what perspective* they
+bring, which remains true regardless of who is currently sitting in the seat.
+
+## How do you check?
+
+- Design documents name sponsors as roles (e.g., "Human: System Architect").
+- No literal personal names or specific agent brand names are used in
+  the `Sponsors` section.
+- The roles named are descriptive of the interests being represented
+  in the cycle.
+- This is enforced by the automated docs test (`tests/docs.test.ts`).

docs/method/backlog/asap/PROCESS_branch-naming-consistency.md

@@ -0,0 +1,27 @@
+---
+title: "Branch Naming Consistency"
+legend: PROCESS
+lane: asap
+---
+
+# Unify branch naming rules across METHOD docs
+
+METHOD currently names cycle branches inconsistently.
+
+Examples in the docs point in different directions:
+- `docs/method/process.md` says cycle work must happen on
+  `cycles/<cycle_name>`
+- the same document's branch naming section says cycle branches use
+  `####-slug`
+
+That should be one rule, not two.
+
+Why this matters:
+- branch naming is part of METHOD's coordination surface
+- conflicting examples create unnecessary drift across repos
+- agents and humans should not have to guess which rule is canonical
+
+Deliverable:
+- choose one branch naming rule for cycle branches
+- update `README.md` and `docs/method/process.md` to match
+- include one clear example and remove contradictory wording