Add enforcement wiring step to hiring process + workflow wiring guide

[joniba]

Fixes #591

Problem

The Adding Team Members process in squad.agent.md creates identity (charter, roster) and routing (routing table entry) but has no step for wiring enforcement rules. When a reviewer is hired, they get a routing table entry but no numbered rule telling the coordinator to automatically route work to them. Result: reviewer exists but never reviews.

Changes

1. squad.agent.md — Added step 7 (Wire enforcement) to Adding Team Members. Renumbered confirmation to step 8.
2. workflow-wiring-guide.md (new) — Guide covering configuration surface area, wiring process, common mistakes, verification checklist.
3. workflow-wiring-appendix-a-code-reviewer.md (new) — End-to-end walkthrough for gate pattern.
4. workflow-wiring-appendix-b-documenter.md (new) — End-to-end walkthrough for follow-up trigger pattern.

Why Three Layers Matter

• Layer 1 (Identity): Charter + roster — WHO the member is
• Layer 2 (Routing): Routing table entry — handles explicit requests
• Layer 3 (Enforcement): routing.md Rules — automatic coordinator behavior

The hiring process previously covered layers 1-2. This PR adds layer 3.

Validated with a clean-session test: a stateless coordinator successfully used the guide to audit and fix a reviewer's missing enforcement rules.

[joniba]

🔍 Code Review — Galadriel (Reviewer)

Verdict: CHANGES_REQUESTED

The PR is high-quality and addresses the exact root cause of #591. The three-layer model (Identity → Routing → Enforcement) is clearly taught, the walkthroughs are actionable, and the genericization is clean. Two factual/format issues should be fixed before merge; one density issue is strongly recommended.

---

Findings Summary

#	Severity	Category	File	Finding
F1	🔴 Medium	Accuracy	workflow-wiring-guide.md	Incorrectly claims issue-lifecycle.md doesn't ship with framework
F2	🟡 Medium	Consistency	workflow-wiring-appendix-b-documenter.md	Ceremony example uses YAML; actual ceremonies.md uses Markdown tables
F3	🟡 Medium	Readability	squad.agent.md	Step 7 is a wall of text; all other steps are one-liners
F4	⚪ Low	Clarity	workflow-wiring-guide.md	Config Surface Area table paths lack .squad/ prefix context
F5	⚪ Low	Robustness	workflow-wiring-appendix-a-code-reviewer.md	Hardcoded step number for issue-lifecycle.md modification
F6	⚪ Nit	Robustness	workflow-wiring-guide.md	Relative appendix links may not resolve from all contexts

---

Finding F1: issue-lifecycle.md existence claim is wrong

Severity: 🔴 Medium
Category: Accuracy
File: workflow-wiring-guide.md, "How to Wire Up an Issue Lifecycle" section (~lines 164–168)

Issue: The guide states:

The framework references .squad/templates/issue-lifecycle.md but does NOT create it — you must create it yourself.

This is factually incorrect. issue-lifecycle.md already exists upstream in .squad-templates/ (11.4 KB, SHA 574c205a). It ships with Squad. Telling users to create it from scratch when it already exists will cause confusion — or worse, users will overwrite the upstream version with a hand-rolled incomplete one.

Suggestion: Replace with:

The framework ships issue-lifecycle.md as a template. If your project already has one deployed at .squad/templates/issue-lifecycle.md, review it for completeness against the wiring requirements below. If not, the Squad init process will create it from the template.

Also update the "Step 1: Create templates/issue-lifecycle.md" heading to something like "Step 1: Review or create templates/issue-lifecycle.md".

---

Finding F2: Ceremony format mismatch in Appendix B

Severity: 🟡 Medium
Category: Consistency
File: workflow-wiring-appendix-b-documenter.md, Step 5 alternative (~lines 97–104)

Issue: The appendix shows a ceremony in YAML-like format:

- name: "Documentation Check"
  when: "after"
  condition: "PR merged that adds features, scripts, tools, or config changes"
  facilitator: "{DocumenterName}"

But the actual upstream ceremonies.md uses Markdown table format:

| Field | Value |
|-------|-------|
| **Trigger** | auto |
| **When** | after |

The main guide (Option B) correctly uses the Markdown table format. A user following Appendix B would create a ceremony the coordinator cannot parse.

Suggestion: Replace the YAML block with a Markdown table matching the format in ceremonies.md and in the main guide's Option B example.

---

Finding F3: Step 7 in squad.agent.md is too dense

Severity: 🟡 Medium
Category: Readability
File: squad.agent.md, Adding Team Members section (line ~765 in diff)

Issue: Step 7 is a 4-line paragraph packed into a single numbered step. Steps 1–6 and 8 are clean one-liners. Step 7 is the most critical new addition and should be equally scannable.

Suggestion: Break into a main instruction + sub-bullets:

7. **Wire enforcement (if applicable).** If the new member's role involves
   gating other agents' work (reviewer, design approver, quality gate):
   - Add a numbered enforcement rule to `routing.md` → Rules section.
     (A routing table entry from step 6 handles explicit requests only —
     enforcement rules are required for automatic gates.)
   - Read `.squad/templates/workflow-wiring-guide.md` for the full process.
   - Check `.squad/templates/issue-lifecycle.md` for lifecycle integration.

---

What needs to change before approval

1. Fix F1 (required): Correct the factual error about issue-lifecycle.md not existing upstream.
2. Fix F2 (required): Replace YAML ceremony format with Markdown table format in Appendix B.
3. Fix F3 (strongly recommended): Break Step 7 into sub-bullets for scannability.

After F1 and F2 are addressed, this PR is ready to merge.

---

Strengths worth calling out

1. Root cause clarity — The PR description and guide both articulate WHY this gap exists (routing table ≠ enforcement) with precision.
2. Two-pattern coverage — Appendix A (gate pattern) and Appendix B (follow-up trigger) cover the two most common enforcement patterns.
3. Clean genericization — Every placeholder uses {CurlyBraceName} convention consistently. No project-specific names leaked.
4. Decisions Audit section — Process for scanning decisions.md for directives that should be routing rules. Operational wisdom.
5. "Common Mistakes" section — Six concrete failure modes with clear explanations.

[joniba]

Correction: F1 Retracted

Reviewer: Galadriel

After further analysis, Finding F1 is withdrawn. The guide's statement that issue-lifecycle.md is not automatically copied into .squad/templates/ during Init Mode is correct — the file exists in .squad-templates/ (the source distribution) but the Init Mode scaffolding does not copy it into the per-squad .squad/templates/ directory. This is a known upstream gap (tracked separately).

Updated verdict: F2 (ceremony YAML format) and F3 (step 7 density) remain. With F1 retracted, the bar for approval is lower — F2 is the remaining required fix, F3 is strongly recommended.

[colinwilliams91]

Correction: F1 Retracted

Reviewer: Galadriel

After further analysis, Finding F1 is withdrawn. The guide's statement that issue-lifecycle.md is not automatically copied into .squad/templates/ during Init Mode is correct — the file exists in .squad-templates/ (the source distribution) but the Init Mode scaffolding does not copy it into the per-squad .squad/templates/ directory. This is a known upstream gap (tracked separately).

Updated verdict: F2 (ceremony YAML format) and F3 (step 7 density) remain. With F1 retracted, the bar for approval is lower — F2 is the remaining required fix, F3 is strongly recommended.

I'm having difficulties upgrading from 0.8.25 to 0.9.x as reported in issue #597 and when I check for issue-lifecycle.md inside .squad/templates/ I also do not see the file. So, maybe the assumption about it not copying over from source on init is correct, but also, the changelog for 0.9.0 shows the addition of issue-lifecycle.md as seen here: https://github.com/bradygaster/squad/blob/main/CHANGELOG.md#added--issue-lifecycle-template

So, is there a chance that the author is not using 0.9.x and therefore missing the file that the code reviewer (Galadriel) is observing? And I'm not sure if the author withdrew F1 or if Galadriel is being sycophantic...
@joniba

[bradygaster]

✅ APPROVED — Excellent work, joniba.

What this PR delivers:

• Adds missing step 7 (Wire enforcement) to the Adding Team Members hiring process in squad.agent.md
• Comprehensive workflow-wiring-guide.md explaining the three-layer enforcement architecture (identity → routing → enforcement)
• Two complete appendix walkthroughs: code reviewer gate pattern (Appendix A) and documenter follow-up trigger pattern (Appendix B)

Why this matters:
You've identified and fixed a real production gap — reviewers were being hired onto the roster but never actually reviewing anything because enforcement rules were missing. The distinction between routing table entries (explicit requests) and enforcement rules (automatic coordinator behavior) is critical and was underdocumented.

Quality assessment:

• Matches team standards (tone, structure, clarity)
• Validated with clean-session test (coordinator successfully used guide to audit and fix missing rules)
• Addresses a real pain point (20 issues closed without a single PR review)
• CI passing (docs-quality + test both green)

This is MSFT-level contribution quality. Merging to main.

[bradygaster]

PR approved! ✅

The PR needs to be rebased on main before it can merge. Can you run:

\\�ash
git checkout fix/591-enforcement-wiring-step
git fetch origin
git rebase origin/main
git push --force-with-lease
\\

Once that's done, the PR will be ready to merge.

[bradygaster]

🔍 Squad Team Review

Reviewed by: CONTROL (TypeScript Engineer) — Pass 3 of consensus ceremony
Action: Phase 5 — Recommend retarget from main→dev
Team Consensus: 5/5 AGREE

Review Summary

Documentation/guide PR. Already APPROVED by reviewers. Currently targets main — recommend retargeting to dev for single release pipeline consistency. Needs rebase after retarget.

Recommendation

Please retarget this PR from main to dev. The project uses dev as the staging branch before main. After retarget, a rebase will be needed.

✅ Verdict: APPROVED — pending retarget to dev