hatch3r 1.1.0 → 1.3.0

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`).

package/commands/board/shared-gitlab.md

@@ -0,0 +1,142 @@
+---
+id: hatch3r-board-shared-gitlab
+type: shared-context
+description: GitLab-specific platform details for board shared context. Covers GitLab Issues, Issue Boards, glab CLI, and label-based sync.
+tags: [board, team, gitlab]
+---
+# Board Shared Reference — GitLab Platform Details
+
+Platform-specific procedures for GitLab. Referenced from `hatch3r-board-shared`.
+
+---
+
+## Platform Detection — GitLab
+
+Use `glab` CLI. Issues = GitLab Issues. PRs = Merge Requests (MRs). Board = GitLab Issue Boards. Requires `glab auth login` or `GITLAB_TOKEN`.
+
+### CLI Command Reference
+
+| Action | Command |
+|--------|---------|
+| Create issue | `glab issue create -R {namespace}/{project}` |
+| List issues | `glab issue list -R {namespace}/{project}` |
+| View issue | `glab issue view N -R {namespace}/{project}` |
+| Update issue | `glab issue update N -R {namespace}/{project}` |
+| Close issue | `glab issue close N -R {namespace}/{project}` |
+| Create MR | `glab mr create -R {namespace}/{project}` |
+| Add label | `glab issue update N --label "x"` |
+| Add comment | `glab issue note N -R {namespace}/{project}` |
+| Board sync | Board list = label-based |
+
+### MCP Tool Reference
+
+GitLab MCP tools are not currently available. All operations use the `glab` CLI.
+
+### Terminology
+
+| Concept | GitLab Term |
+|---------|-------------|
+| Work unit | Issue |
+| Code review | Merge Request (MR) |
+| Board | GitLab Issue Boards |
+| Labels | Labels |
+| Project identifier | project ID |
+| Status tracking | Board lists/labels |
+
+---
+
+## GitLab Context
+
+Derived from `.agents/hatch.json` board config:
+
+- **Namespace:** top-level `owner` (GitLab group or user namespace)
+- **Project:** top-level `repo` (GitLab project name)
+- **Default branch:** `board.defaultBranch` (fallback: `"main"`)
+- **Type labels:** `board.labels.types`
+- **Executor labels:** `board.labels.executors`
+- **Status labels:** `board.labels.statuses`
+- **Scoped labels:** GitLab supports scoped labels (`status::ready`, `type::bug`). Map hatch3r label format (`status:ready`) to GitLab scoped format (`status::ready`) when creating labels.
+- **Issue templates:** Check `.gitlab/issue_templates/` if present.
+- **MR template:** Check `.gitlab/merge_request_templates/` if present.
+
+### GitLab Project Reference (cache for the full run)
+
+- **Project path:** `{namespace}/{project}`
+- **Board:** GitLab Issue Boards use label-based lists. Each status maps to a board list label.
+- **Board ID:** `board.projectNumber` (repurposed as GitLab Board ID if configured)
+
+---
+
+## GitLab Board Label-Based Sync
+
+> **Skip entirely if board is not configured.**
+
+GitLab Boards use labels to organize issues into lists. Board sync is achieved by updating issue labels to match the target status.
+
+**Status label → Board list mapping:**
+
+GitLab board lists are label-based. Each status corresponds to a scoped label:
+
+| Label                | GitLab Scoped Label |
+| -------------------- | ------------------- |
+| `status:triage`      | `status::triage`    |
+| `status:ready`       | `status::ready`     |
+| `status:in-progress` | `status::in-progress` |
+| `status:in-review`   | `status::in-review` |
+| `status:blocked`     | `status::blocked`   |
+
+**Steps for each issue to sync:**
+
+1. **Update labels:** `glab issue update {N} -R {namespace}/{project} --unlabel "status::*" --label "status::{new-status}"`. GitLab scoped labels auto-replace within the same scope, so setting `status::ready` automatically removes `status::triage`.
+2. **Verify:** `glab issue view {N} -R {namespace}/{project}` and confirm labels match.
+
+**For MRs:** `glab mr update {N} -R {namespace}/{project} --label "status::{new-status}"`.
+
+**Resilience:** If any call fails, retry once. If it still fails, surface a warning and continue. If `glab` CLI is unavailable, warn: "GitLab Board sync skipped -- run `glab auth login` or set GITLAB_TOKEN."
+
+---
+
+## Sub-Issue Linking — GitLab
+
+### Three-Tier Fallback Chain
+
+1. **Primary — API link:**
+   `glab api projects/{project_id}/issues/{parent_iid}/links --method POST --field target_project_id={project_id} --field target_issue_iid={child_iid}`.
+   Record link status as `native`.
+
+2. **Fallback 1 — Comment trace:**
+   If API linking fails:
+   `glab issue note {epic} -R {namespace}/{project} --message "Sub-issue: #{child} — {title} (linking failed)"`.
+   Record link status as `comment-only`.
+
+### Verification
+
+After linking, verify via `glab api projects/{project_id}/issues/{epic_iid}/links` and check linked issues.
+
+---
+
+## Board Sync Enforcement — GitLab
+
+1. **Status updates:** Set via `glab issue update --label`.
+2. **Fallback escalation:** `glab issue update` CLI → surface error to user. Silent skipping is prohibited.
+3. **Board item tracking:** After updating an issue, store the issue ID in the run cache keyed by issue number.
+
+---
+
+## Cross-Cutting Tooling — GitLab CLI-First
+
+**Prerequisites:** `glab auth login` must be completed, or `GITLAB_TOKEN` environment variable set.
+
+| Operation            | Primary (`glab` CLI)                                          | Fallback (MCP) |
+| -------------------- | ------------------------------------------------------------- | -------------- |
+| List issues          | `glab issue list -R {namespace}/{project}`                    | N/A            |
+| Read issue details   | `glab issue view N -R {namespace}/{project}`                  | N/A            |
+| Create/update issues | `glab issue create` / `glab issue update N`                   | N/A            |
+| Search issues        | `glab issue list --search "..."`                              | N/A            |
+| Manage relations     | `glab issue note N --message "Related to #M"` (advisory only) | N/A            |
+| Add comments         | `glab issue note N -R {namespace}/{project}`                  | N/A            |
+| Create MRs           | `glab mr create -R {namespace}/{project}`                     | N/A            |
+| Read MR details      | `glab mr view N -R {namespace}/{project}`                     | N/A            |
+| Manage labels        | `glab label create` / `glab label list`                       | N/A            |
+| Board sync           | Label updates (automatic board list placement)                | N/A            |
+| CI/Pipelines         | `glab ci list` / `glab ci view`                               | N/A            |

package/commands/hatch3r-agent-customize.md

@@ -2,6 +2,7 @@
 id: hatch3r-agent-customize
 type: command
 description: Configure per-agent customization including model overrides, description changes, and project-specific markdown instructions
+tags: [customize]
 ---
 
 ## Agent Pipeline
@@ -179,5 +180,5 @@ The `protected` field is set in the canonical agent definition and cannot be ove
 - Skill customization: `hatch3r-skill-customize` command
 - Command customization: `hatch3r-command-customize` command
 - Rule customization: `hatch3r-rule-customize` command
-- Model selection: [docs/model-selection.md](../docs/model-selection.md) — configuration, aliases, resolution order
-- Platform support: [docs/adapter-capability-matrix.md](../docs/adapter-capability-matrix.md) — model emission per adapter (native vs guidance)
+- Model selection: [Model Selection](https://docs.hatch3r.com/docs/guides/model-selection) — configuration, aliases, resolution order
+- Platform support: [Adapter Capability Matrix](https://docs.hatch3r.com/docs/reference/adapter-capability-matrix) — model emission per adapter (native vs guidance)

package/commands/hatch3r-api-spec.md

@@ -2,6 +2,7 @@
 id: hatch3r-api-spec
 type: command
 description: Generate or validate an OpenAPI specification from the codebase. Scans route definitions, extracts schemas, and produces a complete API spec.
+tags: [planning]
 ---
 
 ## Agent Pipeline

package/commands/hatch3r-benchmark.md

@@ -2,6 +2,7 @@
 id: hatch3r-benchmark
 type: command
 description: Run and analyze performance benchmarks. Compare results against baselines, identify regressions, and produce performance reports.
+tags: [review, performance]
 ---
 
 ## Agent Pipeline

package/commands/hatch3r-board-fill.md

@@ -2,6 +2,7 @@
 id: hatch3r-board-fill
 type: command
 description: Create epics and issues/work items from todo.md, reorganize the board with dependency analysis, readiness assessment, and implementation ordering. Supports GitHub, Azure DevOps, and GitLab.
+tags: [board, team]
 ---
 
 ## Agent Pipeline
@@ -530,9 +531,9 @@ Execute in dependency order (parents before children). Do not prompt between ope
 **Platform-specific: Issue creation**
 
 **If platform is `github`:**
-1. **Epics first:** `gh issue create -R {owner}/{repo} --title "..." --body "..." --label "..."` (fall back to `issue_write` MCP with `method: create`). Include `## Dependencies` section and `has-dependencies` label. Record the returned `number` and internal numeric `id` field.
-2. **Sub-issues:** Create each. Record the returned `number` and internal numeric `id` field.
-3. **Standalone issues:** Create with `## Dependencies` and `has-dependencies`.
+1. **Epics first:** `gh issue create -R {owner}/{repo} --title "..." --body "..." --label "..."` (fall back to `issue_write` MCP with `method: create`). Include `## Dependencies` section and `has-dependencies` label (per rule 7 of Board Sync Enforcement). Record the returned `number` and internal numeric `id` field.
+2. **Sub-issues:** Create each. Include `## Dependencies` section. Add `has-dependencies` label if the sub-issue has any dependency references (per rule 7 of Board Sync Enforcement). Record the returned `number` and internal numeric `id` field.
+3. **Standalone issues:** Create with `## Dependencies` and `has-dependencies` (when dependencies exist, per rule 7).
 
 **If platform is `azure-devops`:**
 1. **Epics first:** `az boards work-item create --org https://dev.azure.com/{namespace} --project {project} --type "Epic" --title "..." --description "..." --fields "System.Tags=has-dependencies"` (fall back to `create_work_item` MCP). Record the returned work item `id`.
@@ -546,14 +547,7 @@ Execute in dependency order (parents before children). Do not prompt between ope
 
 **Phase 2 — Link sub-issues** (after all issues exist):
 
-**If platform is `github`:**
-For each sub-issue, link via `sub_issue_write` with `method: add` using the parent `issue_number` and child's internal numeric `id` (NOT the issue number or node_id).
-
-**If platform is `azure-devops`:**
-For each sub-issue, create a parent-child relation: `az boards work-item relation add --org https://dev.azure.com/{namespace} --id {child_id} --relation-type "System.LinkTypes.Hierarchy-Reverse" --target-id {parent_id}`.
-
-**If platform is `gitlab`:**
-For each sub-issue, add a related issue link: `glab api projects/{project_id}/issues/{parent_iid}/links --method POST --field target_project_id={project_id} --field target_issue_iid={child_iid}`. Also reference the parent in the sub-issue body.
+For each sub-issue, follow the **Sub-Issue Linking Procedure** from `hatch3r-board-shared`. Use the three-tier fallback chain (MCP native → CLI body-reference → comment trace) and record link status per child in the run cache under `link_results`.
 
 **Phase 3 — Sync to board** (after all issues and links are created):
 
@@ -568,10 +562,7 @@ For issues needing updates (from Steps 5, 5.5, 5.6):
    - **Azure DevOps:** `az boards work-item update --id N --description "..."`.
    - **GitLab:** `glab issue update N --description "..."`.
 2. **Regenerate `## Implementation Order`** (epics only): Derive from the sub-issues' `## Dependencies` DAG (see Dependency Data Model in `hatch3r-board-shared`). Replace the existing section entirely -- do not manually edit it.
-3. **Apply epic regrouping:** Link standalones to epics.
-   - **GitHub:** `sub_issue_write` MCP. Update epic body.
-   - **Azure DevOps:** `az boards work-item relation add` with parent-child relation.
-   - **GitLab:** `glab api` issue links endpoint. Update epic body.
+3. **Apply epic regrouping:** Link standalones to epics using the **Sub-Issue Linking Procedure** from `hatch3r-board-shared`. Update epic body with the new sub-issue reference.
 4. **Mark `status:ready`:** Remove `status:triage`, add `status:ready`. Do not downgrade existing statuses.
    - **GitHub:** `gh issue edit N --remove-label "status:triage" --add-label "status:ready"`.
    - **Azure DevOps:** `az boards work-item update --id N --state "Active" --fields "System.Tags=+status:ready;-status:triage"`.
@@ -598,7 +589,7 @@ Board Summary: N created, M updated, X marked ready, Y still triage, Z parallel
 **This step is mandatory. Do not skip.**
 
 1. Search the cached board inventory for an open issue labeled `meta:board-overview`.
-2. Compute Implementation Lanes using the **Lane Computation Algorithm** from `hatch3r-board-shared`. Use the cached dependency DAG from Step 5.5 as input.
+2. Compute Implementation Lanes using the **Lane Computation Algorithm** (steps 1-12) from `hatch3r-board-shared`. Use the cached dependency DAG from Step 5.5 as input. This includes inter-lane dependency computation, lane phasing, and the Lane Dependency Map.
 3. Assign models to all open issues using the **Model Selection Heuristic (Quality-First)** from `hatch3r-board-shared`.
 4. **If found:** Regenerate the dashboard body using the **Board Overview Issue Format** template from `hatch3r-board-shared`, populated with cached board data updated with mutations from Step 7. Update the issue body using platform CLI (fall back to MCP):
    - **GitHub:** `gh issue edit {N} --body "..."` (fall back to `issue_write` MCP).
@@ -613,6 +604,14 @@ Do NOT re-fetch all issues; use cached data.
 
 ---
 
+### Step 7.8: 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 created or updated during this run. Output the reconciliation report before proceeding to Step 8.
+
+---
+
 ### Step 8: Cleanup
 
 **ASK:** "All issues created. Should I remove processed items from `todo.md`? (yes / no / only created ones)"