Drop bare cross-tracker issue references in v2 architecture docs

The seven `docs/architecture/` contract docs (worker-compatibility,
task-matching, control-plane-split, scheduler-correctness, rollout-safety,
operational-liveness, routing-precedence) carried bare `#NNN` tokens that
GitHub auto-resolves against the public workflow repo, producing broken
links and exposing private-tracker numbering.

Replace each `(#NNN)` parenthetical with the existing Phase name that
already identifies the contract, drop the bare `#72` / `#78` / `#83` /
`#578` references in routing-precedence narrative, and update the seven
matching `*DocumentationTest` pinning tests to assert on Phase names and
contract paths instead of bare issue numbers.

Extend `scripts/check-public-boundary.sh` so the regression cannot land
again: any `#NNN` in tracked content under `docs/` or in
`tests/Unit/V2/*DocumentationTest.php` now fails the public-boundary
scan.

Author: durable-workflow-ops

docs/architecture/control-plane-split.md

@@ -18,7 +18,7 @@ This contract builds on the semantics frozen in
 `docs/architecture/execution-guarantees.md` (Phase 1), the routing
 guarantees frozen in `docs/architecture/worker-compatibility.md`
 (Phase 2), and the matching and dispatch guarantees frozen by the
-Phase 3 roadmap (#581). Duplicate execution, retries, redelivery,
+Phase 3 roadmap. Duplicate execution, retries, redelivery,
 compatibility, and task matching keep the language they have there;
 this document adds the language for which role owns which durable
 responsibility and how those roles combine into deployment topologies.
@@ -45,10 +45,10 @@ The contract covers:
 
 It does not cover:
 
-- the scheduler cache independence work described by Phase 5 (#583).
+- the scheduler cache independence work described by Phase 5.
   Phase 5 will replace the shared-cache wake backend with a stronger
   primitive but must preserve the role boundaries named here.
-- the rollout safety enforcement work described by Phase 6 (#584).
+- the rollout safety enforcement work described by Phase 6.
 - host-level infrastructure choices such as reverse proxy selection,
   service mesh, TLS termination, Kubernetes vs Nomad vs bare Docker,
   or database placement. Those are deployment concerns that consume
@@ -249,7 +249,7 @@ Guarantees:
   policies, compatibility pinning, or namespace checks.
 - Schedule evaluation is deduplicated per trigger so a restart or
   split-leader scenario does not produce duplicate starts. Phase 6
-  (#584) will harden this with explicit coordination health; this
+  will harden this with explicit coordination health; this
   contract requires that the scheduler-role surface NOT create a
   new race the Phase 6 work must paper over.
 
@@ -368,7 +368,7 @@ to load without adding identical uniform nodes.
   serialise on the run id they are projecting.
 - **Scheduler role** scales with active schedule count. It is
   horizontally scalable with per-schedule leader election; Phase 6
-  (#584) will freeze the leader-election contract, and topologies
+  will freeze the leader-election contract, and topologies
   before that should run a single scheduler replica.
 - **Execution plane** scales with workflow-task and activity-task
   rate. It is horizontally scalable and is the primary surface
@@ -602,16 +602,16 @@ must not be assumed:
   routing primitive, not a role boundary.
 - Multi-region active/active topology. Cross-region coordination
   is a future roadmap topic and is not covered.
-- Replacement of the shared wake backend. That is Phase 5 (#583).
+- Replacement of the shared wake backend. That is Phase 5.
 - Rollout-safety enforcement and scheduler leader election. That
-  is Phase 6 (#584).
+  is Phase 6.
 
 ## Changing this contract
 
 A change to any named guarantee in this document is a protocol-level
 change for the purposes of `docs/api-stability.md` and downstream
 SDKs. Reviewers should treat unmotivated changes to the language
 above as breaking changes and require explicit cross-SDK
-coordination before merge. The Phase 4 roadmap (#582) owns updates
-to this contract; Phase 5 (#583) and Phase 6 (#584) must extend the
+coordination before merge. The Phase 4 roadmap owns updates
+to this contract; Phase 5 and Phase 6 must extend the
 contract rather than silently redefine it.

docs/architecture/operational-liveness.md

@@ -897,10 +897,10 @@ A change to any guarantee named here MUST ship alongside:
 5. An entry in the repository's public release notes that calls
    out the protocol impact.
 
-This contract builds on Phase 1 (#579) execution guarantees,
-Phase 2 (#580) worker compatibility, Phase 3 (#581) task matching,
-Phase 4 (#582) control-plane split, Phase 5 (#583) scheduler
-correctness, and Phase 6 (#584) rollout safety. Removing a
+This contract builds on Phase 1 execution guarantees,
+Phase 2 worker compatibility, Phase 3 task matching,
+Phase 4 control-plane split, Phase 5 scheduler
+correctness, and Phase 6 rollout safety. Removing a
 citation from that lineage without adding the explicit
 re-derivation is a contract violation. Any future extension
 (stuck-detector strategy changes, sweeper replacement, heartbeat

docs/architecture/rollout-safety.md

@@ -64,10 +64,10 @@ The contract covers:
 
 It does not cover:
 
-- the Phase 4 role split itself; Phase 4 (#582) froze the roles, and
+- the Phase 4 role split itself; Phase 4 froze the roles, and
   Phase 6 names the health and rollout surfaces that apply across
   them.
-- the Phase 5 cache independence substrate; Phase 5 (#583) froze
+- the Phase 5 cache independence substrate; Phase 5 froze
   which layer is correctness and which is acceleration, and Phase 6
   inherits that split. Rollout safety MUST NOT reintroduce cache as
   a correctness dependency.
@@ -185,7 +185,7 @@ Guarantees:
 
 ### Mixed-build safety
 
-Phase 2 (#580) already freezes the worker-compatibility marker
+Phase 2 already freezes the worker-compatibility marker
 contract (`DW_V2_CURRENT_COMPATIBILITY`, `DW_V2_SUPPORTED_COMPATIBILITIES`),
 the single-step compatibility rule across the fleet, and
 `Workflow\V2\Support\TaskCompatibility` / `WorkerCompatibility`. Phase 6
@@ -228,7 +228,7 @@ Guarantees:
 
 ### Protocol version coordination
 
-Phase 4 (#582) names three protocol-version surfaces (worker
+Phase 4 names three protocol-version surfaces (worker
 protocol, control-plane protocol, internal role-to-role). Phase 6
 adds the rollout-safety enforcement:
 
@@ -649,7 +649,7 @@ MUST NOT be assumed:
   splitters, Helm chart overlays). Those are deployment tooling
   concerns that consume this contract.
 - Replacement of the shared cache acceleration layer with a
-  stronger primitive. That seam is part of Phase 5 (#583).
+  stronger primitive. That seam is part of Phase 5.
 - Any change to the Phase 4 role split. Phase 6 must be
   implementable inside each role as defined; it does not move
   authority between roles.
@@ -660,9 +660,9 @@ A change to any named guarantee in this document is a
 protocol-level change for the purposes of `docs/api-stability.md`
 and downstream SDKs. Reviewers should treat unmotivated changes to
 the language above as breaking changes and require explicit
-cross-SDK coordination before merge. The Phase 6 roadmap (#584)
+cross-SDK coordination before merge. The Phase 6 roadmap
 owns updates to this contract; any follow-on architecture phase
 must extend the contract rather than silently redefine it. The
-Phase 1 (#579), Phase 2 (#580), Phase 3 (#581), Phase 4 (#582),
-and Phase 5 (#583) contracts remain the foundation this document
+Phase 1, Phase 2, Phase 3, Phase 4,
+and Phase 5 contracts remain the foundation this document
 builds on.

docs/architecture/routing-precedence.md

@@ -50,13 +50,13 @@ The contract covers:
 
 It does not cover:
 
-- the dedicated task-matching service described by the Phase 3 roadmap
-  (#581). That surface consumes the snapped `connection` and `queue`
-  values frozen here; it does not re-resolve them.
-- the control-plane/data-plane role split described by Phase 4 (#582).
+- the dedicated task-matching service described by the Phase 3
+  roadmap. That surface consumes the snapped `connection` and
+  `queue` values frozen here; it does not re-resolve them.
+- the control-plane/data-plane role split described by Phase 4.
   The split moves which role writes the snapshots but does not change
   the precedence rules named here.
-- cache-backed wake propagation described by Phase 5 (#583). Wake
+- cache-backed wake propagation described by Phase 5. Wake
   signals are eligibility announcements, not routing decisions.
 - host-level queue topology (priorities, sharding schemes, managed
   lanes). Those are operator choices that consume the snapshot; they
@@ -487,13 +487,13 @@ follow-on phase:
   semantics for degraded queues; adding one is a protocol change.
 - **Cross-namespace routing.** Namespaces partition the poll surface
   and are not part of the routing decision. Cross-namespace calls are
-  tracked separately in #72.
+  out of scope for this contract.
 - **Webhook and command-ingress routing.** Command-plane ingress
   routing is tracked in `docs/architecture/control-plane-split.md`
-  (Phase 4) and in the webhook/command taxonomy (#83). Ingress
+  (Phase 4) and in the webhook/command taxonomy. Ingress
   routing is not the same as task routing and does not share
   resolution rules.
-- **Dedicated matching service partitioning.** Phase 3 (#581) may
+- **Dedicated matching service partitioning.** Phase 3 may
   introduce additional partition metadata on the matching side. When
   it does, the matching service will consume `(connection, queue,
   compatibility, namespace)` exactly as frozen in
@@ -549,11 +549,10 @@ roadmap issues rather than redefining them here:
   `docs/architecture/task-matching.md`.
 - retry-time rerouting and degraded-queue drainage, which require a
   new contract extension.
-- cross-namespace routing, tracked in #72.
+- cross-namespace routing, which is out of scope for this contract.
 
 See `docs/architecture/execution-guarantees.md`,
 `docs/architecture/worker-compatibility.md`,
 `docs/architecture/task-matching.md`, and
 `docs/architecture/rollout-safety.md` for the adjacent frozen
-contracts this document builds on. Roadmap context is in
-#78 and #578.
+contracts this document builds on.

docs/architecture/scheduler-correctness.md

@@ -25,7 +25,7 @@ retries, redelivery, compatibility, and the `snapshot()`/`changed()`
 wake primitives keep the language they have there; this document
 adds the language for what those primitives are allowed to be
 responsible for and what remains the job of durable dispatch state.
-The Phase 4 control-plane and execution-plane role split (#582)
+The Phase 4 control-plane and execution-plane role split
 preserves every guarantee here unchanged; the split is a topology
 change, not a correctness change.
 
@@ -59,7 +59,7 @@ The contract covers:
 
 It does not cover:
 
-- the rollout safety enforcement work described by Phase 6 (#584).
+- the rollout safety enforcement work described by Phase 6.
   Phase 6 owns scheduler leader election and coordinated rollout
   across role replicas; this contract names what each node is
   allowed to observe but does not arbitrate which replica is
@@ -262,7 +262,7 @@ acceleration-layer cooperation.
 - When the scheduler role is deployed as multiple replicas, the
   per-schedule row lock taken by `ScheduleManager::triggerDetailed()`
   is the correctness seam, not a cache-held leader key. Phase 6
-  (#584) will harden leader coordination with explicit health;
+  will harden leader coordination with explicit health;
   this contract requires that the scheduler-role surface NOT
   depend on cache coherence for deduplicated firing.
 
@@ -489,12 +489,12 @@ Guarantees:
 The following are explicitly deferred to later roadmap phases and
 must not be assumed:
 
-- **Scheduler leader election across replicas** — Phase 6 (#584)
+- **Scheduler leader election across replicas** — Phase 6
   owns the leader coordination contract. Pre-Phase-6 deployments
   that run multiple scheduler replicas MUST rely on the
   per-schedule row lock as the only correctness seam.
 - **Rollout-safety enforcement across protocol-version steps** —
-  Phase 6 (#584) owns the rollout-safety seam. This contract does
+  Phase 6 owns the rollout-safety seam. This contract does
   not freeze how a mixed-version cluster coordinates schedule
   leadership during a rollout.
 - **A notifier-backed implementation of `LongPollWakeStore`
@@ -516,6 +516,6 @@ A change to any named guarantee in this document is a
 protocol-level change for the purposes of `docs/api-stability.md`
 and downstream SDKs. Reviewers should treat unmotivated changes
 to the language above as breaking changes and require explicit
-cross-SDK coordination before merge. The Phase 5 roadmap (#583)
-owns updates to this contract; Phase 6 (#584) must extend the
+cross-SDK coordination before merge. The Phase 5 roadmap
+owns updates to this contract; Phase 6 must extend the
 contract rather than silently redefine it.

docs/architecture/task-matching.md

@@ -55,14 +55,14 @@ The contract covers:
 
 It does not cover:
 
-- the control-plane/data-plane role split described by Phase 4 (#582).
+- the control-plane/data-plane role split described by Phase 4.
   The split will move matching onto a dedicated control-plane role,
   but must preserve the discovery, claim, and wake guarantees below.
-- the scheduler cache independence work described by Phase 5 (#583).
+- the scheduler cache independence work described by Phase 5.
   Cache independence will replace the shared-cache wake backend with
   a stronger primitive but must preserve the snapshot/changed contract
   named here.
-- the rollout safety enforcement work described by Phase 6 (#584).
+- the rollout safety enforcement work described by Phase 6.
 - host-level queue infrastructure choices such as which Laravel queue
   driver to deploy, how to size queue workers, or whether to run a
   dedicated supervisor process. Those are deployment concerns that
@@ -327,7 +327,7 @@ Guarantees:
   Redis, a database cache, or another backend reachable from every
   server node. File or in-memory backends do not coordinate
   signals across nodes and break the multi-node guarantee. This
-  is the explicit Phase 5 (#583) seam.
+  is the explicit Phase 5 seam.
 
 Wake notification is observability of new work, not an assignment.
 A signalled channel does not promise a specific task to the
@@ -370,7 +370,7 @@ What the contract intentionally does not partition on:
 - The matching role does not implement queue-level priorities. A
   host that needs priority traffic must run priority queues.
 
-These intentional non-guarantees are how Phase 4 (#582) and later
+These intentional non-guarantees are how Phase 4 and later
 phases keep room to introduce a real matching service without
 re-litigating the partition primitives.
 
@@ -386,7 +386,7 @@ an explicit per-worker quota:
   `max_concurrent_activity_tasks` at registration time so operator
   surfaces can show the planned capacity. The matching role does
   not enforce these limits at claim time today; that enforcement
-  is explicitly part of the Phase 6 (#584) rollout-safety work.
+  is explicitly part of the Phase 6 rollout-safety work.
 - Long lease expiry (5 minutes for workflow tasks) is the
   fail-stop boundary for an unresponsive worker. Operators sizing
   rollout windows MUST treat this as the upper bound on how long
@@ -453,7 +453,7 @@ the claim transaction:
 
 These couplings are correct as semantics — every claim must be
 immediately visible to operators and immediately reflected in
-history. They are the seam where Phase 4 (#582) will split the
+history. They are the seam where Phase 4 will split the
 control-plane and execution-plane roles. The contract guarantees:
 
 - Visibility (`RunSummaryProjector`) and lifecycle dispatch
@@ -499,16 +499,16 @@ The following are explicitly deferred to later roadmap phases and
 must not be assumed:
 
 - Per-worker concurrency caps are advertised but not enforced at
-  claim time. Enforcement belongs to Phase 6 (#584) rollout
+  claim time. Enforcement belongs to Phase 6 rollout
   safety, where it can land alongside the broader coordination
   health story.
 - A dedicated out-of-process matching service is not provided. The
   in-worker library shape and the in-server HTTP shape are the
   two supported deployment shapes today; a future Phase 4 service
   shape will preserve the contract above without breaking either.
-- Cache independence for wake notification is deferred to Phase 5
-  (#583). The current cache-backed wake store is the explicit
-  seam Phase 5 will replace.
+- Cache independence for wake notification is deferred to Phase 5.
+  The current cache-backed wake store is the explicit seam Phase 5
+  will replace.
 - Priority queues, weighted fair scheduling, and per-tenant
   isolation primitives are intentionally not part of this
   contract. They are policy choices a host implements through
@@ -523,6 +523,6 @@ A change to any named guarantee in this document is a protocol-level
 change for the purposes of `docs/api-stability.md` and downstream
 SDKs. Reviewers should treat unmotivated changes to the language
 above as breaking changes and require explicit cross-SDK
-coordination before merge. The Phase 3 roadmap (#581) owns updates
-to this contract; Phase 4 (#582), Phase 5 (#583), and Phase 6
-(#584) must extend the contract rather than silently redefine it.
+coordination before merge. The Phase 3 roadmap owns updates to
+this contract; Phase 4, Phase 5, and Phase 6 must extend the
+contract rather than silently redefine it.

docs/architecture/worker-compatibility.md

@@ -39,14 +39,14 @@ The contract covers:
 
 It does not cover:
 
-- the dedicated task-matching service described by the Phase 3 roadmap
-  (#581). The Phase 3 surface will replace broad database polling with
-  explicit match/dispatch, but must preserve the compatibility
+- the dedicated task-matching service described by the Phase 3
+  roadmap. The Phase 3 surface will replace broad database polling
+  with explicit match/dispatch, but must preserve the compatibility
   guarantees below.
-- the control-plane/data-plane role split described by Phase 4 (#582).
+- the control-plane/data-plane role split described by Phase 4.
   The split will move compatibility heartbeating onto the control plane
   but must preserve the observable state named here.
-- the scheduler independence work described by Phase 5 (#583).
+- the scheduler independence work described by Phase 5.
 - host-level deployment orchestration such as container image selection
   or rolling-restart choreography. Those are deployment concerns that
   consume this contract; they do not define it.
@@ -309,7 +309,7 @@ not be assumed:
   frozen separately in `Workflow\V2\Support\WorkerProtocolVersion` and
   is independent of the compatibility marker.
 - Managed-mode or hosted-mode topology (control-plane / data-plane
-  split) is outside this contract. See Phase 4 (#582).
+  split) is outside this contract. See Phase 4.
 
 ## Test strategy alignment
 
@@ -333,5 +333,5 @@ A change to any named guarantee in this document is a protocol-level
 change for the purposes of `docs/api-stability.md` and downstream
 SDKs. Reviewers should treat unmotivated changes to the language above
 as breaking changes and require explicit cross-SDK coordination before
-merge. The Phase 2 roadmap (#580) owns updates to this contract;
+merge. The Phase 2 roadmap owns updates to this contract;
 Phases 3–5 must extend the contract rather than silently redefine it.

scripts/check-public-boundary.sh

@@ -56,6 +56,24 @@ for pattern in "${file_patterns[@]}"; do
   done < <(git grep -n -I -e "$pattern" -- "${pathspec[@]}" || true)
 done
 
+# Bare cross-tracker issue references like "#NNN" in customer-facing
+# architecture docs and their pinning tests will auto-link to the public
+# workflow repo on github.com, exposing internal roadmap numbering and
+# producing broken cross-links. Architecture contracts must reason in
+# product-facing names (Phase numbers, contract titles) rather than
+# private tracker numbers.
+issue_link_pathspec=(
+  'docs/'
+  'tests/Unit/V2/*DocumentationTest.php'
+  ':!.git'
+)
+
+while IFS=: read -r file line _; do
+  [[ -n "${file:-}" ]] || continue
+  printf 'public-boundary: forbidden cross-tracker issue reference at %s:%s\n' "$file" "$line" >&2
+  status=1
+done < <(git grep -n -I -E '#[0-9]{2,4}([^0-9]|$)' -- "${issue_link_pathspec[@]}" || true)
+
 if [[ -n "${PUBLIC_BOUNDARY_GIT_RANGE:-}" ]]; then
   read -r -a rev_args <<< "$PUBLIC_BOUNDARY_GIT_RANGE"
 else