hatch3r 1.0.0 → 1.2.0

package/commands/board/pickup-post-impl.md

@@ -0,0 +1,120 @@
+---
+id: hatch3r-board-pickup-post-impl
+type: command
+description: Post-implementation steps for board-pickup (Steps 7-10). Covers quality verification, commit/push, PR/MR creation, label transitions, board sync, dashboard refresh, reconciliation, and learnings capture.
+tags: [board, team]
+---
+# Board Pickup — Post-Implementation Steps (7-10)
+
+Post-implementation workflow for `hatch3r-board-pickup`. Referenced from the core command file.
+
+---
+
+## Step 7: Quality Verification
+
+Run the project's quality checks (linting, type checking, tests). Refer to the project's `AGENTS.md`, `README.md`, or `package.json` scripts for the appropriate commands.
+
+Verify: all AC met, tests passing, no lint errors, dead code removed, project-specific invariants respected.
+
+---
+
+## Step 7a: Commit & Push
+
+Stage, commit, and push all changes so the branch exists on the remote before PR creation.
+
+**Single issue or epic:**
+
+```bash
+git add -A
+git commit -m "{type}: {short description} (#{issue})"
+git push -u origin {branch-name}
+```
+
+- Use the branch type prefix (`feat`, `fix`, `refactor`, `qa`) matching the branch name.
+- Reference the issue number in the commit message.
+- If `git push` fails (e.g., branch already exists on remote), use `git push` without `-u`.
+
+**Batch mode:** Create one commit covering all issues in the batch.
+
+```bash
+git add -A
+git commit -m "batch: {short description} (#N, #M, #K)"
+git push -u origin {branch-name}
+```
+
+- List all issue numbers in the commit message.
+- If all issues share a type, use that type prefix instead of `batch`.
+
+---
+
+## Step 8: Create Pull Request / Merge Request
+
+> Platform-specific details: see `commands/board/pickup-github.md` (Step 8)
+> Platform-specific details: see `commands/board/pickup-azure-devops.md` (Step 8)
+> Platform-specific details: see `commands/board/pickup-gitlab.md` (Step 8)
+
+Follow the project's PR/MR creation skill or conventions:
+
+1. **Title:** `{type}: {short description} (#issue)` — for batch mode: `batch: {short description} (#N, #M, #K)`.
+2. **Determine epic link type:** If working on an epic's sub-issues, check whether ALL sub-issues of the parent epic are addressed by this PR/MR (listed as `Closes #N`) or are already closed. If yes → use `Closes #<epic-number>` so the epic auto-closes on merge. If some sub-issues remain open and unaddressed → use `Relates to #<epic-number>`.
+3. **Body:** Use the repository's PR/MR template if available (see platform sub-file for template location). Fill: Summary, Type, Changes, Testing, Rollout plan. Include a **Related Issues** section listing:
+   - `Closes #N` for each issue addressed by this PR/MR (including all batch issues).
+   - `Closes #<epic>` (all sub-issues addressed) OR `Relates to #<epic>` (partial) for the parent epic.
+   - Always list both the epic and all sub-issues in the Related Issues section regardless of partial/full completion.
+   - **Batch mode:** List `Closes #N` for every issue in the batch. Include a per-issue summary of changes in the body.
+4. **Create PR/MR** using the platform CLI (see platform sub-file for exact command).
+5. **Link PR/MR to epic** using the platform-specific method (see platform sub-file).
+6. **Verify PR body linkage** and auto-fix missing `Closes #N` references (see platform sub-file).
+
+---
+
+## Step 8a: Post-PR/MR Label Transition & Board Sync
+
+> Platform-specific details: see `commands/board/pickup-github.md` (Step 8a)
+> Platform-specific details: see `commands/board/pickup-azure-devops.md` (Step 8a)
+> Platform-specific details: see `commands/board/pickup-gitlab.md` (Step 8a)
+
+1. **Transition labels to `status:in-review`:** For each `Closes #N` issue (including all batch issues), update status labels using the platform CLI (see platform sub-file). If ALL sub-issues addressed, also transition the parent epic.
+2. **Sync Board:** Run the full **Board Sync Procedure** from `hatch3r-board-shared` for each item (see platform sub-file for specific targets).
+
+---
+
+## Step 9: Post-PR Housekeeping
+
+1. If all sub-issues addressed, confirm the PR body uses `Closes #<epic-number>` so the epic will auto-close on merge and transition to Done.
+2. Remind user `Closes #N` auto-closes on merge.
+3. If partial:
+
+**ASK:** "PR created. N remaining sub-issues on epic #X. Continue with next sub-issue or stop?"
+
+### 9a. Refresh Board Dashboard
+
+**This step is mandatory. Do not skip.**
+
+If a `meta:board-overview` issue exists on the board, refresh it now using cached board data updated with mutations from Steps 4, 8, and 8a. Include the `Recommended Model` column in all issue listings per the Board Overview section in `hatch3r-board-shared`. Do NOT re-fetch all issues; use cached data. Skip silently if no `meta:board-overview` issue exists.
+
+### 9b. End-of-Run Reconciliation
+
+**This step is mandatory. Do not skip.**
+
+Run the **End-of-Run Reconciliation Procedure** from `hatch3r-board-shared`. This verifies board sync, sub-issue links, label consistency, and PR linkage for all issues modified during this pickup run. Output the reconciliation report before proceeding to Step 10.
+
+---
+
+## Step 10: Capture Learnings
+
+After PR creation, capture learnings from this development session.
+
+1. Reflect on the implementation:
+   - Were there any unexpected challenges or blockers?
+   - Did any patterns or approaches work particularly well?
+   - Were there decisions made that future developers should know about?
+   - Were any pitfalls discovered that should be avoided next time?
+
+2. If learnings are identified:
+   - Create learning files in `.agents/learnings/` following the learning file format (see `hatch3r-learn` command).
+   - Include the issue number as `source-issue`.
+   - Tag with relevant area labels from the issue.
+   - **ASK:** "Learnings captured: {list}. Anything else to note? (add more / done)"
+
+3. If no significant learnings: skip silently. Not every task produces learnings. Do not prompt in this case.

package/commands/board/shared-azure-devops.md

@@ -0,0 +1,149 @@
+---
+id: hatch3r-board-shared-azure-devops
+type: shared-context
+description: Azure DevOps-specific platform details for board shared context. Covers Work Items, Azure Boards, az CLI, and MCP tools.
+tags: [board, team, azure-devops]
+---
+# Board Shared Reference — Azure DevOps Platform Details
+
+Platform-specific procedures for Azure DevOps. Referenced from `hatch3r-board-shared`.
+
+---
+
+## Platform Detection — Azure DevOps
+
+Use `az devops` / `az boards` / `az repos` CLI. Issues = Work Items. PRs = Pull Requests. Board = Azure Boards. Requires `az login` or `AZURE_DEVOPS_PAT`.
+
+### CLI Command Reference
+
+| Action | Command |
+|--------|---------|
+| Create work item | `az boards work-item create --org https://dev.azure.com/{namespace} --project {project} --type "User Story" --title "..."` |
+| List work items | `az boards query --org https://dev.azure.com/{namespace} --project {project} --wiql "SELECT..."` |
+| View work item | `az boards work-item show --org https://dev.azure.com/{namespace} --id N` |
+| Update work item | `az boards work-item update --org https://dev.azure.com/{namespace} --id N` |
+| Close work item | `az boards work-item update --org https://dev.azure.com/{namespace} --id N --state Closed` |
+| Create PR | `az repos pr create --org https://dev.azure.com/{namespace} --project {project}` |
+| Add tag | `az boards work-item update --id N --fields "System.Tags=x"` |
+| Add comment | `az boards work-item update --id N --discussion "..."` |
+| Board sync | Board column = Work Item State |
+
+### MCP Tool Reference
+
+| Action | MCP Tool |
+|--------|----------|
+| Create work item | `create_work_item` |
+| Read work item | `get_work_item` |
+| List work items | `list_work_items` |
+| Search work items | `search_work_items` |
+| Add relation | Work Item parent-child relation |
+| Create PR | `create_pull_request` |
+
+### Terminology
+
+| Concept | Azure DevOps Term |
+|---------|-------------------|
+| Work unit | Work Item |
+| Code review | Pull Request (PR) |
+| Board | Azure Boards |
+| Labels | Tags + Area Paths |
+| Project identifier | `project` name |
+| Status tracking | Work Item State |
+
+---
+
+## Azure DevOps Context
+
+Derived from `.agents/hatch.json` board config:
+
+- **Organization:** top-level `owner` (maps to Azure DevOps organization name)
+- **Project:** top-level `repo` (maps to Azure DevOps project name)
+- **Default branch:** `board.defaultBranch` (fallback: `"main"`)
+- **Type labels → Work Item Tags:** `board.labels.types` (applied as Tags on work items)
+- **Executor labels → Tags:** `board.labels.executors`
+- **Status labels → Work Item State:** `board.labels.statuses` (mapped to Work Item State field)
+- **Area Paths:** `board.areas` (mapped to Azure DevOps Area Paths)
+- **PR template:** Check `.azuredevops/pull_request_template.md` if present.
+
+### Azure DevOps Project Reference (cache for the full run)
+
+- **Organization URL:** `https://dev.azure.com/{namespace}`
+- **Project name:** `board.projectNumber` (repurposed as Azure DevOps project name)
+- **Work Item States:** `Backlog` → `New`, `Ready` → `Active`, `In Progress` → `Active`, `In Review` → `Resolved`, `Done` → `Closed`
+
+---
+
+## Azure Boards Work Item State Sync
+
+Azure Boards syncs via Work Item State changes. There is no separate "add to board" step -- work items appear on the board automatically based on their State and Area Path.
+
+**Status label → Work Item State mapping:**
+
+| Label                | Work Item State |
+| -------------------- | --------------- |
+| `status:triage`      | `New`           |
+| `status:ready`       | `Active`        |
+| `status:in-progress` | `Active`        |
+| `status:in-review`   | `Resolved`      |
+| `status:blocked`     | `New`           |
+| (done)               | `Closed`        |
+
+**Steps for each work item to sync:**
+
+1. **Update Work Item State:** `az boards work-item update --org https://dev.azure.com/{namespace} --id {N} --state "{state}"` using the label→state mapping above.
+2. **Update Area Path (if area labels changed):** `az boards work-item update --org https://dev.azure.com/{namespace} --id {N} --area-path "{project}\\{area}"`.
+3. **Update Tags:** `az boards work-item update --org https://dev.azure.com/{namespace} --id {N} --fields "System.Tags={comma-separated tags}"`.
+
+**MCP fallback:** If `az` CLI fails, fall back to Azure DevOps MCP `update_work_item` with the corresponding state and field values.
+
+**For PRs:** PRs are managed via `az repos pr update --id {N} --status active|completed`. Board sync for PRs is automatic in Azure DevOps when linked to work items.
+
+**Resilience:** If any call fails, retry once. If it still fails, surface a warning and continue. If `az` CLI and MCP are both unavailable, warn: "Azure Boards sync skipped -- run `az login` or set AZURE_DEVOPS_PAT."
+
+---
+
+## Sub-Issue Linking — Azure DevOps
+
+### Three-Tier Fallback Chain
+
+1. **Primary — CLI relation:**
+   `az boards work-item relation add --id {child_id} --relation-type "System.LinkTypes.Hierarchy-Reverse" --target-id {parent_id}`.
+   Record link status as `native`.
+
+2. **Fallback 1 — Comment trace:**
+   If relation add fails:
+   `az boards work-item update --id {epic} --discussion "Sub-issue: #{child} — {title} (linking failed)"`.
+   Record link status as `comment-only`.
+
+### Verification
+
+After linking, verify via `az boards work-item relation list --id {epic}` and check parent-child relations.
+
+---
+
+## Board Sync Enforcement — Azure DevOps
+
+1. **Status updates:** Set via `az boards work-item update --state`.
+2. **Fallback escalation:** `az boards work-item update` CLI → Azure DevOps MCP → surface error to user. Silent skipping is prohibited.
+3. **Board item tracking:** After updating a work item, store the work item ID in the run cache keyed by issue number.
+
+---
+
+## Cross-Cutting Tooling — Azure DevOps CLI-First
+
+**Prerequisites:** `az login` must be completed, or `AZURE_DEVOPS_PAT` environment variable set. Run `az devops configure --defaults organization=https://dev.azure.com/{namespace} project={project}` to set defaults.
+
+| Operation            | Primary (`az` CLI)                                                                             | Fallback (MCP)         |
+| -------------------- | ---------------------------------------------------------------------------------------------- | ---------------------- |
+| List work items      | `az boards query --wiql "SELECT [System.Id] FROM WorkItems WHERE [System.State] <> 'Closed'"` | `list_work_items`      |
+| Read work item       | `az boards work-item show --id N`                                                              | `get_work_item`        |
+| Create work items    | `az boards work-item create --type "User Story" --title "..." --description "..."`             | `create_work_item`     |
+| Update work items    | `az boards work-item update --id N --fields "field=value"`                                     | `update_work_item`     |
+| Search work items    | `az boards query --wiql "SELECT ... WHERE [System.Title] CONTAINS '...'"` | `search_work_items`    |
+| Manage relations     | `az boards work-item relation add --id N --relation-type "System.LinkTypes.Hierarchy-Forward" --target-id M` | Work Item relation API |
+| Add comments         | `az boards work-item update --id N --discussion "..."`                                         | N/A                    |
+| Create PRs           | `az repos pr create --title "..." --source-branch "..." --target-branch "..."`                 | `create_pull_request`  |
+| Read PR details      | `az repos pr show --id N`                                                                      | N/A                    |
+| Manage tags          | `az boards work-item update --id N --fields "System.Tags=tag1; tag2"`                          | N/A                    |
+| Board sync           | Work Item State updates (automatic board placement)                                             | N/A                    |
+| CI/Pipelines         | `az pipelines run list` / `az pipelines run show`                                              | N/A                    |

package/commands/board/shared-board-overview.md

@@ -0,0 +1,215 @@
+---
+id: hatch3r-board-shared-overview
+type: shared-context
+description: Board overview dashboard template, model pool, model selection heuristic, and lane computation algorithm. Referenced from hatch3r-board-shared.
+tags: [board, team]
+---
+# Board Overview Reference
+
+If `meta:board-overview` is included in `board.labels.meta`, board commands will look for an open issue with that label to use as a live dashboard. This dashboard is auto-maintained and MUST be regenerated at the end of every board command run that mutates issues. For on-demand regeneration without running a full board command, use `hatch3r-board-refresh`.
+
+Teams can extend the dashboard with project-specific sections, but the following structure and model recommendations are required.
+
+## Frontier Model Pool
+
+When populating the board overview, assign a recommended model to each issue. The pool uses aliases that map to the project's configured model versions in `hatch.json`. Specific model IDs are intentionally omitted here to avoid staleness as model versions change — configure actual model IDs in `hatch.json` under `models`.
+
+| Alias | Strength | Use When |
+| ----- | -------- | -------- |
+| `opus` | Code quality, multi-file refactoring, security, deep reasoning | Complex refactors, security-critical, architectural changes, `risk:high` |
+| `codex` | Agentic coding, long-running tasks, tool orchestration | Multi-step implementations, polyglot codebases, complex tool integrations |
+| `gemini-pro` | Large context windows, multimodal, web development | Massive context needs (large epics), web/frontend work |
+| `sonnet` | Balance of quality and speed | Standard features, bugs, docs, QA — when the top-tier model is overkill |
+
+## Model Selection Heuristic (Quality-First)
+
+1. **Default:** `opus` — highest code quality baseline.
+2. **Override to `codex`** if the issue involves heavy agentic coding, long-running multi-step tasks, or multi-language requirements.
+3. **Override to `gemini-pro`** if the issue requires processing very large context (large epic with many sub-issues spanning many files) or is primarily web/frontend work.
+4. **Downgrade to `sonnet`** ONLY for straightforward issues: simple bugs (`risk:low`), documentation (`type:docs`), QA validation (`type:qa`), or issues with clear bounded scope and no architectural impact.
+
+## Board Overview Issue Format
+
+Issue listings in the board overview MUST include a `Model` column. All board commands that regenerate the dashboard MUST use this canonical template. Omit any status section that has zero issues (except Status Summary, which always appears). Omit Board Health sub-sections that have no findings. Sort issues within each status group by priority (`P0` first), then by issue number.
+
+```markdown
+## Board Overview
+
+**Project:** {owner}/{repo}
+**Last refreshed:** {ISO date}
+
+---
+
+## Status Summary
+
+| Status | Count |
+|--------|-------|
+| Backlog / Triage | {count} |
+| Ready | {count} |
+| In Progress | {count} |
+| In Review | {count} |
+| Externally Blocked | {count} |
+| **Total Open** | **{count}** |
+
+---
+
+## In Progress
+
+| # | Title | Type | Pri | Executor | Model | PR |
+|---|-------|------|-----|----------|-------|----|
+| #{N} | {title} | {type} | {pri} | {executor} | {model} | #{pr_number} or -- |
+
+## In Review
+
+| # | Title | Type | Pri | Executor | Model | PR |
+|---|-------|------|-----|----------|-------|----|
+| #{N} | {title} | {type} | {pri} | {executor} | {model} | #{pr_number} or -- |
+
+## Implementation Lanes
+
+Issues grouped into work streams with dependency-aware phasing.
+Lanes in the same phase can be worked concurrently; within a lane, follow the listed order.
+Lanes in later phases should start after their prerequisite lanes complete or reach a stable state.
+
+### Lane Dependency Map
+
+| Lane | Phase | Prerequisites | Relationship |
+|------|-------|---------------|--------------|
+| Lane 1: {name} | 1 | -- | Independent |
+| Lane 2: {name} | 2 | Lane 1 (resolved-hard) | Depends on Lane 1 output |
+| Lane 3: {name} | 2 | Lane 1 (soft) | Recommended after Lane 1 |
+
+When 4+ lanes have inter-lane edges, also render a **Mermaid diagram**:
+- Solid arrows (`-->`) for resolved-hard edges
+- Dashed arrows (`-.->`) for soft edges
+- Phase 1 nodes = green, Phase 2 = yellow, Phase 3+ = orange
+- Omit diagram when all lanes are Phase 1 or fewer than 4 lanes exist
+
+### Lane 1: {area/theme} [Phase 1]
+
+| Order | # | Title | Type | Pri | Executor | Model |
+|-------|---|-------|------|-----|----------|-------|
+| 1 | #{N} | {title} | {type} | {pri} | {executor} | {model} |
+| 2 | #{M} | {title} | {type} | {pri} | {executor} | {model} |
+
+### Lane 2: {area/theme} [Phase 2]
+> After: Lane 1 (API creates endpoints this lane consumes)
+
+| Order | # | Title | Type | Pri | Executor | Model |
+|-------|---|-------|------|-----|----------|-------|
+| 1 | #{N} | {title} | {type} | {pri} | {executor} | {model} |
+
+## Cross-Epic Dependencies
+
+Dependency relationships between epics. Omit if no cross-epic dependencies exist.
+
+| Upstream Epic | Downstream Epic | Via |
+|---------------|-----------------|-----|
+| #{epicA} {title} | #{epicB} {title} | #{subX} blocks #{subY} |
+
+## Cross-Lane Dependencies
+
+Inter-lane dependency edges from the Lane Dependency Map. Omit if no cross-lane dependencies exist.
+
+| From (Lane) | Issue | To (Lane) | Issue | Type | Reason |
+|-------------|-------|-----------|-------|------|--------|
+| Lane 1: API | #{N} | Lane 3: Integration | #{M} | resolved-hard | #{M} was blocked by #{N} (now closed) |
+| Lane 1: API | #{N} | Lane 2: Auth | #{K} | soft | Shared area overlap, reduced merge conflict risk |
+
+## Waiting on Dependencies
+
+`status:ready` issues with one or more unsatisfied blockers. Not yet available for pickup.
+
+| # | Title | Type | Waiting On | Model |
+|---|-------|------|------------|-------|
+| #{N} | {title} | {type} | #{blocker} ({blocker status}) | {model} |
+
+## Externally Blocked
+
+Issues with `status:blocked` -- waiting on external factors (approvals, environments, third-party services).
+
+| # | Title | Type | Reason | Model |
+|---|-------|------|--------|-------|
+| #{N} | {title} | {type} | {blocker reason} | {model} |
+
+## Backlog / Triage
+
+| # | Title | Type | Pri | Executor | Model |
+|---|-------|------|-----|----------|-------|
+| #{N} | {title} | {type} | {pri} | {executor} | {model} |
+
+---
+
+## Board Health
+
+**Missing metadata:**
+- {list or "None -- all issues have required labels."}
+
+**Stale issues:**
+- {list or "None -- all issues are active."}
+
+**Blocked chains:**
+- {list or "None -- no blocked dependencies."}
+
+**Epic ordering discrepancies:**
+- {list or "None -- all epic Implementation Order sections match sub-issue Dependencies."}
+
+**Lane sequencing warnings:**
+- {list or "None -- all lane phase assignments are clear."}
+
+Flag: Phase 2+ lanes with 0 prerequisite work completed, lanes with bidirectional soft deps (review independence), lanes sharing 4+ soft deps (consider merging).
+
+**Unlinked sub-issues:**
+- {list or "None -- all sub-issues are natively linked."}
+
+**Unlinked in-progress work:**
+- {list or "None -- all active issues have PRs."}
+
+**Board sync drift:**
+- {list or "None -- all labels match board state."}
+
+**Dependency format inconsistencies:**
+- {list using `Depends on` instead of `Blocked by`, or "None -- all use canonical format."}
+
+---
+
+*This issue is auto-maintained by hatch3r board commands. Do not close.*
+```
+
+---
+
+## Dependency Data Model
+
+`## Dependencies` sections in individual issue bodies are the **single authoritative source** of dependency data. Every issue (epic, sub-issue, standalone) tracks its own blockers in its `## Dependencies` section using two reference types:
+
+- **Hard:** `Blocked by #N` -- this issue cannot start until #N is closed. Used for true producer/consumer relationships (A creates what B consumes) and explicit sequencing requirements.
+- **Soft:** `Recommended after #N` -- this issue can proceed in parallel with #N, but sequential execution is recommended (e.g., shared area overlap, reduced merge conflict risk). Soft dependencies are advisory; they do not block pickup or exclude issues from Implementation Lanes.
+
+When no dependencies exist, the section contains `None`.
+
+**Canonical format:** `Blocked by #N` is the only hard dependency format board commands generate. `Depends on #N` is accepted as a legacy alias when parsing but MUST NOT be written. `board-groom` normalizes `Depends on #N` → `Blocked by #N` during dependency refresh.
+
+`## Implementation Order` sections in epic bodies are a **derived convenience view** -- they visualize the dependency DAG among an epic's sub-issues as numbered levels. Board commands that create or update epics MUST regenerate `## Implementation Order` from the sub-issues' `## Dependencies` sections, not the other way around. When the two diverge, `## Dependencies` wins.
+
+## Lane Computation Algorithm
+
+Used by `board-fill`, `board-groom`, and `board-refresh` when generating the Implementation Lanes and Waiting on Dependencies sections. Input: all `status:ready` issues and their dependency data (from `## Dependencies` sections).
+
+1. **Collect** all `status:ready` issues.
+2. **Partition by hard-blocker satisfaction** -- for each collected issue, check all **hard** dependency references (`Blocked by #N`) in its `## Dependencies` section against the full board. An issue is **dependency-waiting** if any hard blocker is still open (regardless of the blocker's status). Soft dependencies (`Recommended after #N`) do not affect this partition. Separate into two sets:
+   - **Available** -- all hard blockers satisfied (closed) or no hard blockers. These proceed to lane computation (step 3+).
+   - **Dependency-waiting** -- one or more hard blockers still open. These are excluded from Implementation Lanes and listed in the **Waiting on Dependencies** section of the overview instead.
+3. **Build the available sub-graph** -- retain **both** hard and soft dependency edges among available issues (from parsed `## Dependencies` sections). Hard edges determine intra-lane ordering. Soft edges are tracked for inter-lane computation in steps 10-12.
+4. **Group by dependency chains** -- issues with sequential dependencies go in the same lane, ordered topologically within the chain.
+5. **Group by area overlap** -- independent issues (no inter-dependencies) that share `area:*` labels go in the same lane. This avoids merge conflicts on the same files when multiple agents work in parallel.
+6. **General lane** -- issues with no dependencies and no area overlap form their own single-issue lanes. If three or more such issues exist, group them into a single "General" lane.
+7. **Name lanes** by the dominant `area:*` label or shared theme of the issues in the lane. Use "General" for the catch-all lane.
+8. **Sort lanes** by the highest-priority issue in each lane (`P0`-lane first, then `P1`, etc.). Break ties by lowest issue number.
+9. **Sort within lanes** by dependency order (blockers before dependents), then by priority, then by issue number.
+10. **Compute inter-lane dependency edges:** After lanes are formed, scan all soft dependencies (`Recommended after #N`) and resolved hard dependencies (`Blocked by #N` where #N is closed) where the blocker and dependent are in *different* lanes. Record: source lane, target lane, edge type (`soft` / `resolved-hard`), issue pair.
+11. **Compute lane phases:** Build a lane-level DAG from step 10 edges. Assign phase numbers via topological ordering:
+    - Phase 1: lanes with no incoming inter-lane edges (can start immediately).
+    - Phase 2+: lanes whose predecessors are all in earlier phases.
+    - Soft-only edges are annotated but do not enforce phasing (advisory).
+    - If all lanes have no edges → all Phase 1 (truly parallel).
+12. **Build Lane Dependency Map:** Produce summary: lane phase assignments, inter-lane edges with types, whether the board is fully parallel or phased. This summary populates the Lane Dependency Map and Cross-Lane Dependencies sections of the board overview.

package/commands/board/shared-github.md

@@ -0,0 +1,169 @@
+---
+id: hatch3r-board-shared-github
+type: shared-context
+description: GitHub-specific platform details for board shared context. Covers GitHub Issues, Projects V2, gh CLI, and MCP tools.
+tags: [board, team, github]
+---
+# Board Shared Reference — GitHub Platform Details
+
+Platform-specific procedures for GitHub. Referenced from `hatch3r-board-shared`.
+
+---
+
+## Platform Detection — GitHub
+
+Use `gh` CLI and GitHub MCP tools. Issues = GitHub Issues. PRs = Pull Requests. Board = Projects V2.
+
+### CLI Command Reference
+
+| Action | Command |
+|--------|---------|
+| Create issue | `gh issue create -R {owner}/{repo}` |
+| List issues | `gh issue list -R {owner}/{repo}` |
+| View issue | `gh issue view N -R {owner}/{repo}` |
+| Update issue | `gh issue edit N -R {owner}/{repo}` |
+| Close issue | `gh issue close N -R {owner}/{repo}` |
+| Create PR | `gh pr create -R {owner}/{repo}` |
+| Add label | `gh issue edit N --add-label "x"` |
+| Add comment | `gh issue comment N -R {owner}/{repo}` |
+| Board sync | `gh project item-add`, GraphQL |
+
+### MCP Tool Reference
+
+| Action | MCP Tool |
+|--------|----------|
+| Create issue | `issue_write` |
+| Read issue | `issue_read` |
+| List issues | `list_issues` |
+| Search issues | `search_issues` |
+| Add sub-issue | `sub_issue_write` |
+| Create PR | `create_pull_request` |
+
+### Terminology
+
+| Concept | GitHub Term |
+|---------|------------|
+| Work unit | Issue |
+| Code review | Pull Request (PR) |
+| Board | Projects V2 |
+| Labels | Labels |
+| Project identifier | `projectNumber` |
+| Status tracking | Projects V2 Status field |
+
+---
+
+## GitHub Context
+
+Derived from `.agents/hatch.json` board config:
+
+- **Owner:** top-level `owner` (fallback: `board.owner`)
+- **Repository:** top-level `repo` (fallback: `board.repo`)
+- **Default branch:** `board.defaultBranch` (fallback: `"main"`)
+- **Type labels:** `board.labels.types`
+- **Executor labels:** `board.labels.executors`
+- **Status labels:** `board.labels.statuses`
+- **Dependency label:** `has-dependencies`
+- **Meta labels:** `board.labels.meta`
+- **Branch convention:** `board.branchConvention`
+- **Issue templates:** Check `.github/ISSUE_TEMPLATE/` if present in the repository.
+- **PR template:** Check `.github/PULL_REQUEST_TEMPLATE.md` if present.
+
+### GitHub Project Reference (cache for the full run)
+
+If `board.projectNumber` is not null, verify via `gh project view {board.projectNumber} --owner {board.owner}` or `gh project field-list {board.projectNumber} --owner {board.owner}` on first use.
+
+- **Owner:** `board.owner`, **owner type:** infer from context (`org` or `user`)
+- **Project number:** `board.projectNumber`
+- **Status field ID:** `board.statusFieldId`
+- **Status option IDs:** Read from `board.statusOptions` (keys: `backlog`, `ready`, `inProgress`, `inReview`, `done`)
+
+---
+
+## GitHub Projects V2 Sync
+
+> **Skip entirely if `board.projectNumber` is null.**
+
+**Prerequisites:** `gh auth refresh -s project` (Projects v2 via gh requires the `project` scope). gh CLI 2.40+ recommended.
+
+**Status label → Projects v2 option mapping:**
+
+Read the mapping from `board.statusOptions` in `.agents/hatch.json`:
+
+| Label                | Option ID from hatch.json          |
+| -------------------- | ---------------------------------- |
+| `status:triage`      | `board.statusOptions.backlog`      |
+| `status:ready`       | `board.statusOptions.ready`        |
+| `status:in-progress` | `board.statusOptions.inProgress`   |
+| `status:in-review`   | `board.statusOptions.inReview`     |
+| `status:blocked`     | `board.statusOptions.backlog`      |
+
+**Steps for each issue to sync (gh CLI primary):**
+
+1. **Resolve project node ID** (once per run, cache for the run): `gh project view {board.projectNumber} --owner {board.owner} --format json -q '.id'`. Required for step 3.
+2. **Add to board + capture item ID:** `gh project item-add {board.projectNumber} --owner {board.owner} --url https://github.com/{board.owner}/{board.repo}/issues/{N} --format json -q '.id'`. **Capture the item ID from the output.** This call is idempotent -- if the item already exists on the board it returns the existing item with its ID.
+3. **Update status:** `gh project item-edit --id {item_id} --project-id {project_node_id} --field-id {board.statusFieldId} --single-select-option-id {option_id}` using the label→option mapping from the table above.
+4. **Verify (first sync per run only):** After step 3, optionally confirm via `gh project item-list {board.projectNumber} --owner {board.owner} --format json` that the item's status matches. If it does not, retry step 3 once.
+
+**For PRs:** Use `--url https://github.com/{board.owner}/{board.repo}/pull/{N}` in step 2.
+
+**Fallback (rare):** If item-add does not return an item ID, use `gh project item-list {board.projectNumber} --owner {board.owner} --format json` and match by issue/PR content to obtain the item ID. Then proceed with step 3.
+
+**MCP fallback:** If gh CLI fails, `project` scope is unavailable, or gh version is too old, fall back to `projects_write` / `projects_get` / `projects_list` with `method: add_project_item`, `method: update_project_item`, `method: get_project_item`, `method: list_project_items` as in the legacy procedure.
+
+**Resilience:** If any call fails, retry once. If it still fails, surface a warning to the user and continue with the next item. If gh CLI and MCP are both unavailable, skip sync silently and warn: "Projects v2 sync skipped -- run `gh auth refresh -s project` or enable the `projects` toolset in your MCP configuration."
+
+---
+
+## Sub-Issue Linking — GitHub
+
+### Three-Tier Fallback Chain
+
+1. **Primary — MCP native link:**
+   `sub_issue_write` MCP with `method: add` using the parent `issue_number` and child's internal numeric `id`.
+   Record link status as `native`.
+
+2. **Fallback 1 — CLI body-reference:**
+   If MCP linking fails, establish an advisory link:
+   - Prepend `> Parent: #{epic}` to the child issue body via `gh issue edit {child} --body "..."`.
+   - Add `- [ ] #{child} {title}` to the epic's sub-issue checklist via `gh issue edit {epic} --body "..."`.
+   - Record link status as `advisory`.
+
+3. **Fallback 2 — Comment trace:**
+   If both primary and Fallback 1 fail:
+   `gh issue comment {epic} --body "Sub-issue: #{child} — {title} (linking failed)"`.
+   Record link status as `comment-only`.
+
+### Verification
+
+After linking, verify via `issue_read` with `method: get_sub_issues` on the parent epic.
+
+---
+
+## Board Sync Enforcement — GitHub
+
+1. **Status updates:** Set via Projects V2 GraphQL mutation or `gh project item-edit`.
+2. **Fallback escalation:** GraphQL mutation → `gh project item-edit` CLI → MCP `projects_write` → surface error to user. Silent skipping is prohibited.
+3. **Board item tracking:** After adding an item to the board, store the returned item ID in the run cache keyed by issue number.
+
+---
+
+## Cross-Cutting Tooling — GitHub CLI-First
+
+**Prerequisites:** `gh auth login` must be completed, or `GITHUB_TOKEN` environment variable set. For Projects v2: `gh auth refresh -s project`.
+
+| Operation            | Primary (`gh` CLI)                                                                                          | Fallback (MCP)                                      |
+| -------------------- | ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
+| List issues          | `gh issue list`                                                                                             | `list_issues`                                       |
+| Read issue details   | `gh issue view`                                                                                             | `issue_read`                                        |
+| Create/update issues | `gh issue create` / `gh issue edit`                                                                         | `issue_write`                                       |
+| Search issues        | `gh search issues`                                                                                          | `search_issues` / `semantic_issues_search`          |
+| Manage sub-issues    | `sub_issue_write` (MCP only — no CLI equivalent)                                                             | `sub_issue_write`                                   |
+| Add comments         | `gh issue comment`                                                                                          | `add_issue_comment`                                 |
+| Create PRs           | `gh pr create`                                                                                              | `create_pull_request`                               |
+| Read PR details      | `gh pr view`                                                                                                | `pull_request_read`                                 |
+| Manage labels        | `gh label create` / `gh label list`                                                                         | `issue_write` (with labels)                         |
+| Projects v2          | `gh project item-add`, `gh project item-edit`, `gh project item-list`, `gh project field-list`, `gh project view` | `projects_write` / `projects_get` / `projects_list` |
+| CI/Actions           | `gh run list` / `gh run view`                                                                               | N/A                                                 |
+| Releases             | `gh release create`                                                                                         | N/A                                                 |
+
+Fallback to MCP only for operations the `gh` CLI cannot handle: sub-issue management (`sub_issue_write`).