hatch3r 1.1.0 → 1.2.0

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)"

package/commands/hatch3r-board-groom.md

@@ -2,6 +2,7 @@
 id: hatch3r-board-groom
 type: command
 description: Ongoing backlog refinement for existing board items. Re-prioritize, reclassify, re-scope, archive stale items, decompose oversized issues, merge duplicates, refresh dependencies, and remediate board health findings.
+tags: [board, team]
 ---
 
 ## Agent Pipeline
@@ -164,7 +165,15 @@ Compare existing open issues pairwise for semantic overlap:
 - Overlapping acceptance criteria.
 - Cross-reference `## Scope` sections for boundary collisions.
 
-#### 3i. Present Refinement Summary
+#### 3j. Unlinked Sub-Issue Detection
+
+For each epic, compare the sub-issue references in the epic body (checklist items, `> Parent:` references) against the native sub-issue list from `issue_read` with `method: get_sub_issues` (GitHub) or equivalent platform call. Flag sub-issues that appear in the body but are not natively linked.
+
+#### 3k. Board Sync Drift Detection
+
+If `board.projectNumber` is configured, compare label-based status (`status:*` labels) against board column status via `gh project item-list {board.projectNumber} --owner {board.owner} --format json` (GitHub) or equivalent platform call. Flag issues where the label status and board column status diverge.
+
+#### 3l. Present Refinement Summary
 
 Present findings grouped by category:
 
@@ -178,6 +187,8 @@ Board Health:
   Stale dependency refs: D issues
   Priority imbalance: {description or "None"}
   Epic ordering discrepancies: E epics
+  Unlinked sub-issues: U issues (non-native links)
+  Board sync drift: V issues (label/board status mismatch)
 
 Grooming Opportunities:
   Re-prioritize candidates: R issues (priority/risk misalignment, priority inflation)
@@ -186,11 +197,12 @@ Grooming Opportunities:
   Grouping candidates: G standalone issues → potential epics
   Duplicate/overlap candidates: O issue pairs
   Dependency cleanup: K issues (stale refs, orphaned labels)
+  Link fix candidates: L issues (advisory or comment-only links)
 
-Available actions: [reprioritize | reclassify | re-scope | demote | archive | decompose | merge | dep-refresh | health-fix | all]
+Available actions: [reprioritize | reclassify | re-scope | demote | archive | decompose | merge | dep-refresh | health-fix | link-fix | all]
 ```
 
-**ASK:** "Here is the board refinement summary. Which grooming actions do you want to perform? Select one or more: reprioritize / reclassify / re-scope / demote / archive / decompose / merge / dep-refresh / health-fix / all. You can also specify issue numbers to target specific items (e.g., 'reprioritize #5, #12')."
+**ASK:** "Here is the board refinement summary. Which grooming actions do you want to perform? Select one or more: reprioritize / reclassify / re-scope / demote / archive / decompose / merge / dep-refresh / health-fix / link-fix / all. You can also specify issue numbers to target specific items (e.g., 'reprioritize #5, #12')."
 
 ---
 
@@ -342,11 +354,9 @@ The original issue becomes the parent epic.
 
 4. For confirmed decompositions:
    - If the original is standalone, convert it to an epic by updating its body with `## Implementation Order` and adding sub-issue links.
-   - Create sub-issues and link to parent using platform CLI:
-     - **GitHub:** Create via `gh issue create` or `issue_write` MCP. Link via `sub_issue_write` MCP.
-     - **Azure DevOps:** Create via `az boards work-item create`. Link via `az boards work-item relation add --relation-type "System.LinkTypes.Hierarchy-Forward"`.
-     - **GitLab:** Create via `glab issue create`. Link via `glab api` issue links endpoint.
-   - Inherit labels/tags from the parent. Add `## Dependencies` sections.
+   - Create sub-issues using platform CLI (`gh issue create` / `az boards work-item create` / `glab issue create`). Fall back to MCP if CLI fails.
+   - Link sub-issues to the parent using the **Sub-Issue Linking Procedure** from `hatch3r-board-shared` (three-tier fallback chain).
+   - Inherit labels/tags from the parent. Add `## Dependencies` sections. Add `has-dependencies` label to sub-issues with dependency references (per rule 7 of Board Sync Enforcement).
    - Sync new sub-issues to the board via the **Board Sync Procedure** from `hatch3r-board-shared`.
 
 ---
@@ -377,7 +387,8 @@ Combine overlapping issues discovered after initial dedup.
 Re-analyze and clean up dependency data based on current board state.
 
 1. **Clean stale references:** For issues referencing closed blockers, remove the satisfied `Blocked by #N` lines from `## Dependencies` (the blocker is done, the reference is noise). Replace with `None` if no other dependencies remain.
-2. **Fix orphaned labels:** For issues with `has-dependencies` label but empty or missing `## Dependencies`, either add the section or remove the label.
+1b. **Normalize dependency format:** Replace `Depends on #N` with `Blocked by #N` in `## Dependencies` sections. This enforces the canonical format per the Dependency Data Model in `hatch3r-board-shared`.
+2. **Fix orphaned labels:** For issues with `has-dependencies` label but empty or missing `## Dependencies`, either add the section or remove the label. Also add `has-dependencies` to issues that have dependency references but are missing the label (bidirectional enforcement per rule 7 of Board Sync Enforcement).
 3. **Discover new dependencies:** Analyze the current board for producer/consumer relationships that weren't captured in the original fill. Propose new dependency edges.
 4. **Recompute epic ordering:** For epics with stale `## Implementation Order` sections (flagged in Step 3d), regenerate the section from sub-issues' `## Dependencies` DAG.
 5. **Unblock newly available items:** After cleaning stale refs, identify issues that were previously dependency-waiting but are now available (all blockers closed). Note these for the user.
@@ -414,6 +425,27 @@ Newly unblocked:
 
 ---
 
+#### 4h-link. Link Fix (Sub-Issue Re-Linking)
+
+Re-run the **Sub-Issue Linking Procedure** from `hatch3r-board-shared` for sub-issues identified in Step 3j as non-natively linked.
+
+1. Present link-fix candidates from Step 3j:
+
+```
+Link Fix Candidates:
+
+| # | Title | Parent Epic | Current Link Status |
+|---|-------|-------------|---------------------|
+| #N | {title} | #{epic} | advisory |
+| #M | {title} | #{epic} | comment-only |
+```
+
+**ASK:** "Confirm re-linking for these sub-issues. The procedure will attempt native linking via MCP. Confirm / skip."
+
+2. For each confirmed candidate, run the Sub-Issue Linking Procedure fallback chain starting from the primary tier. Record updated link status in the run cache.
+
+---
+
 #### 4i. Health Fix (Board Health Remediation)
 
 Fix structural gaps detected in Step 3b (missing metadata).
@@ -486,7 +518,7 @@ For every issue/work item whose labels or status changed during Steps 4-5:
 **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 dependency graph from Step 3d, updated with mutations from Step 4, as input.
+2. Compute Implementation Lanes using the **Lane Computation Algorithm** (steps 1-12) from `hatch3r-board-shared`. Use the dependency graph from Step 3d, updated with mutations from Step 4, 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 all mutations from Steps 4-6. Update using platform CLI:
    - **GitHub:** `gh issue edit {N} --body "..."` (fall back to `issue_write` MCP).
@@ -498,6 +530,14 @@ Do NOT re-fetch all issues; use cached data updated with this run's mutations.
 
 ---
 
+### Step 7.5: 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 grooming session. Output the reconciliation report before proceeding to Step 8.
+
+---
+
 ### Step 8: Groom Summary
 
 Present a summary of all changes made during this grooming session:

package/commands/hatch3r-board-init.md

@@ -2,6 +2,7 @@
 id: hatch3r-board-init
 type: command
 description: Initialize a project board (GitHub Projects V2, Azure Boards, or GitLab Issue Boards) with hatch3r's label taxonomy, status fields, and board structure. Platform detected from hatch.json.
+tags: [board, team]
 ---
 
 ## Agent Pipeline