feat(skills): canonical-URL drift lessons from dojo-os DOJ-4200 / DOJ-4075 (#24)

Adds three rules to spike-recommend (Rules 11, 12, 13) derived from the
canonical-URL migration session in dojo-os (2026-05-20):

Rule 11 — Predict semantic conflicts, not just file conflicts.
  When a brief references an in-flight PR, the Known Pitfalls / Technical
  Constraints sections must enumerate the SEMANTIC contracts both PRs
  touch (URL shapes, type signatures, state schemas, edge function
  payload shapes, event names) — not just file paths.

Rule 12 — Verify URL-builder output matches the declared Route mount.
  When a brief covers a URL canonical migration, Acceptance Criteria must
  include an explicit matchPath check that buildXxxUrl(...) output is
  reachable via its declared ROUTES.X template. Reference test:
  dojo-os src/utils/__tests__/url-builders-match-routes.test.ts.

Rule 13 — Use useAuth().isAuthenticated for chrome decisions.
  Auth-aware page chrome must use useAuth() branching inside a single
  wrapper (PathwaysPage / PathwayDetailPage pattern), NOT a
  PUBLIC_*_ROUTE_PREFIXES string list. Cites dojo-os commit dbd8a1d04.

Also adds a CHANGELOG note in implement-advisor flagging that the
redaction-quality gate is no longer sufficient on its own for
canonical-URL migrations with in-flight overlap — the brief must also
satisfy spike-recommend Rules 11 + 12 to be considered
implementation-ready.

Bumps version 1.15.0 → 1.16.0 across package.json, plugin.json,
marketplace.json, and the README visible Version line, with a new
CHANGELOG entry — per the warn-version-readme-changelog-sync rule
this PR's lineage itself defines.

All 210 hook tests still pass.

Created by Claude Code on behalf of @andres.

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>

Author: lapc506

.claude-plugin/marketplace.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
   "name": "make-no-mistakes",
-  "version": "1.15.0",
+  "version": "1.16.0",
   "description": "The disciplined dev lifecycle — implement issues, review PRs, sync releases, test E2E, manage sessions, and stash secrets via OS-native prompts. One plugin to make no mistakes.",
   "owner": {
     "name": "Luis Andres Pena Castillo",
@@ -11,7 +11,7 @@
     {
       "name": "make-no-mistakes",
       "description": "Dev lifecycle orchestrator: disciplined Linear issue execution with worktree isolation, PR review with Greptile gating, team release sync, E2E test generation and execution, test suite previewer, security pentesting, MoSCoW + RICE prioritization, cross-platform secret stash via OS-native GUI prompts (zenity / kdialog / osascript / Get-Credential), and session management. 18 commands, 6 auto-activating skills, 2 specialized agents.",
-      "version": "1.15.0",
+      "version": "1.16.0",
       "author": {
         "name": "Luis Andres Pena Castillo",
         "email": "lapc506@users.noreply.github.com"

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "make-no-mistakes",
-  "version": "1.15.0",
+  "version": "1.16.0",
   "description": "The disciplined dev lifecycle — implement issues, review PRs, sync releases, test E2E, manage sessions, stash secrets, and enforce manifest-driven tool-call hooks. One plugin to make no mistakes.",
   "author": {
     "name": "Luis Andres Pena Castillo",

CHANGELOG.md

@@ -18,6 +18,61 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.16.0] - 2026-05-20
+
+### Added
+- **Three new rules in `spike-recommend` (Rules 11, 12, 13) from the
+  DOJ-4200 + DOJ-4075 canonical-URL migration session in `dojo-os`
+  (2026-05-20).** Briefs touching URL canonical migrations or coexisting
+  with an in-flight PR must now satisfy:
+  - **Rule 11 — Predict semantic conflicts, not just file conflicts.**
+    When a brief references an in-flight PR, the "Known Pitfalls" /
+    "Technical Constraints" sections must enumerate the SEMANTIC contracts
+    both PRs touch (URL shapes, type signatures, state schemas, edge
+    function payload shapes, event names) — not just file paths. The
+    motivating bug: a subagent on DOJ-4075 predicted "7 shared files will
+    conflict" with DOJ-4200; the actual file conflict count was close (6),
+    but the real drift was semantic — DOJ-4200's canonical URL shape vs
+    DOJ-4075's forum URL builders silently diverged with zero file overlap.
+  - **Rule 12 — Verify URL-builder output matches the declared Route mount.**
+    When a brief covers a URL canonical migration, Acceptance Criteria must
+    include an explicit `matchPath` check that `buildXxxUrl(...)` output is
+    reachable via its declared `ROUTES.X` template. Reference test:
+    `src/utils/__tests__/url-builders-match-routes.test.ts` in `dojo-os`.
+    The motivating bug: Greptile P1 on DOJ-4200 (commit `dbd8a1d04`) —
+    `courseBasePath = '/pathways/:slug'` produced URLs like
+    `/pathways/X/Y/workbook` that had NO matching `<Route>` mount.
+  - **Rule 13 — Use `useAuth().isAuthenticated` for chrome decisions, not
+    URL-prefix string detection.** Briefs that propose auth-aware page
+    chrome must require `useAuth()` branching inside a single wrapper
+    component (the PathwaysPage / PathwayDetailPage pattern), not a
+    `PUBLIC_*_ROUTE_PREFIXES` string list. The motivating bug: DOJ-4200's
+    first attempt put `/pathways` in `PUBLIC_COURSE_ROUTE_PREFIXES` and
+    made every visitor — authed and anon — see the public layout, losing
+    the app shell for authed users on the canonical pathway-course URL.
+    Fix in `dojo-os` commit `dbd8a1d04`.
+- **`implement-advisor` CHANGELOG note** flagging that the redaction-quality
+  gate is no longer sufficient on its own for canonical-URL migration
+  issues with in-flight overlap — the brief must also satisfy spike-recommend
+  Rules 11 + 12 to be considered "implementation-ready".
+
+### Notes
+- These rules complement the parallel `dojo-os` PR
+  (`andres/canonical-url-lessons-hooks`) which adds:
+  - `.claude/hooks/pre-write-routes-yaml-canonical.sh` — pre-write hook
+    blocking `content_types.<X>.canonical: /app/...` (the canonical URL
+    must never carry the legacy `/app/` prefix per the DOJ-4064 thesis).
+  - `src/utils/__tests__/url-builders-match-routes.test.ts` — Vitest test
+    asserting every `buildXxxUrl` reaches its declared route template via
+    `matchPath`. This is the reference implementation cited by Rule 12.
+- Defense-in-depth (DOJ-4064 three-layer drift thesis, Cure 4):
+  - **Toolkit level (this PR)** — cross-repo enforcement; any toolkit
+    consumer that runs `/spike-recommend` for a canonical-URL migration
+    gets the gates above embedded in the brief.
+  - **Repo level (parallel `dojo-os` PR)** — local hook + Vitest test
+    enforce the same contracts in the dojo-os repo even if this toolkit
+    isn't installed.
+
 ## [1.15.0] - 2026-05-14
 
 ### Added

README.md

@@ -1,6 +1,6 @@
 # make-no-mistakes
 
-**Version: 1.15.0** · [CHANGELOG](./CHANGELOG.md) · [Marketplace](https://github.com/DojoCodingLabs/make-no-mistakes-toolkit)
+**Version: 1.16.0** · [CHANGELOG](./CHANGELOG.md) · [Marketplace](https://github.com/DojoCodingLabs/make-no-mistakes-toolkit)
 
 The disciplined dev lifecycle — implement issues, review PRs, sync releases, test E2E, and manage sessions. One plugin to make no mistakes.
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lapc506/make-no-mistakes",
-  "version": "1.15.0",
+  "version": "1.16.0",
   "description": "The disciplined dev lifecycle — implement issues, review PRs, sync releases, test E2E, manage sessions, stash secrets, and enforce manifest-driven tool-call hooks (no SSH+DB, no manual prod, no minified build, no secret leaks, Slack format). OpenCode + Claude Code plugin.",
   "type": "module",
   "main": "./dist/index.js",

skills/implement-advisor/SKILL.md

@@ -21,6 +21,7 @@ You detected that the user wants to **implement a Linear issue or start developm
 
 ## CHANGELOG
 
+- **2026-05-20 — Surface canonical-URL drift gates from spike-recommend.** When the issue under analysis is a URL canonical migration (touches `<Route>` mounts, `buildXxxUrl` helpers, or `aliases_redirect_only` in a routes map) AND there's an in-flight PR overlap, the redaction-quality gate is no longer sufficient on its own. Even a Bilingual-formatted brief is "soft" if it doesn't enumerate the SEMANTIC contracts both PRs touch (Rule 11 in `spike-recommend`) and assert URL-builder ↔ Route reachability (Rule 12). Recommend re-running `/make-no-mistakes:spike-recommend {ISSUE-ID}` first to refresh the brief against the v1.16.0+ ruleset, THEN `/make-no-mistakes:implement`. Background: DOJ-4200 + DOJ-4075 lessons (`dojo-os`, 2026-05-20).
 - **2026-05-13 — Gate on issue redaction quality.** Before recommending `/make-no-mistakes:implement`, fetch the Linear issue and check whether its description is in Bilingual Format (Human Layer + Agent Layer + ACs + Context Files). If not, recommend `/make-no-mistakes:spike-recommend {ISSUE-ID}` first to normalize the description in place, THEN `/make-no-mistakes:implement`. Implementation agents work much better against a normalized brief.
 
 ## When This Applies

skills/spike-recommend/SKILL.md

@@ -20,6 +20,7 @@ This template is called "Bilingual Issue Brief". The canonical definition of the
 
 ## CHANGELOG
 
+- **2026-05-20 — Canonical-URL migration lessons (Rules 11, 12, 13).** Added three rules derived from the DOJ-4200 + DOJ-4075 session in `dojo-os` (2026-05-20). Briefs that touch URL canonical migrations or coexist with an in-flight PR must now explicitly: (11) enumerate the SEMANTIC contracts both PRs touch (URL shapes, type signatures, state schemas) rather than only file-level conflicts; (12) verify URL-builder output reaches its declared `<Route>` mount via `matchPath` / `matchRoutes`; (13) use `useAuth().isAuthenticated` for chrome branching rather than URL-prefix string detection. Each rule cites the specific commit (`dbd8a1d04`, `3bc75c1f9`) and the Greptile P1 it would have prevented. See Rules section.
 - **2026-05-13 — Removed duplicated metadata block from body template.** Labels go to tracker fields, body stays narrative. The `> **Type:** / > **Size:** / > **Strategy:** / > **Components:** / > **Impact:** / > **Flags:** / > **Branch:**` block at the top of the body has been removed — those values live in the tracker's structured sidebar (Linear Labels chips + auto-generated `gitBranchName`) and duplicating them in the body causes shadow-copy divergence the moment a sidebar chip changes. See "Field mapping" below for where each label is set.
 - **2026-05-13 — Tracker is now the canonical destination.** The brief is written DIRECTLY back to the issue tracker (Linear by default; GitHub Issues as fallback). The skill can also CREATE a new issue when no URL is supplied. Local `./issue-briefs/{ISSUE-ID}.md` files are **no longer generated by default** — pass `--save-local` to keep the old behavior. _Migration note for existing users:_ if you relied on the local file, add `--save-local` to your invocation; otherwise the brief now lives in the tracker description.
 
@@ -477,6 +478,32 @@ Evaluate the **long-term implications** of this implementation:
     * On `--save-local`, ALSO write `./issue-briefs/{ISSUE-ID}.md` as a non-canonical mirror with a banner pointing at the tracker URL.
     * Without `--save-local`, never create the local file. The previous default (always-write-local) caused divergence between the brief and the tracker and is retired.
 
+11. Predict semantic conflicts, not just file conflicts.
+
+    * When a brief references an in-flight PR (an open PR on the same repo, especially one that hasn't merged yet), the "Known Pitfalls & Gotchas" and "Technical Constraints" sections MUST enumerate the **semantic** contracts both PRs touch — not just the file paths.
+    * Semantic contracts include: URL shapes (canonical paths, route templates), type signatures (function arguments, return types, generic params), state schemas (Redux/Zustand/TanStack Query key shapes, DB column meanings), edge function payload shapes, and event names.
+    * File-level conflict prediction is necessary but insufficient. The DOJ-4200 + DOJ-4075 session (`dojo-os`, 2026-05-20) had a subagent predict "7 shared files will conflict" — the actual file conflict count was 6 (close enough), but the bigger drift was a SEMANTIC conflict: DOJ-4200's new canonical URL shape (`/pathways/:p/course/:s`) vs DOJ-4075's URL builders for forum URLs (which the subagent kept on the legacy shape per Strategy A). Neither PR touched the other's files, yet the URL contract between them had silently diverged.
+    * Format inside the brief:
+      > **In-flight overlap with {OTHER-ISSUE-ID}:**
+      > - **File-level**: {N} files touched by both (list).
+      > - **Semantic contracts**:
+      >   - URL shape `X` — both PRs construct it; verify the shape matches.
+      >   - Type `Foo` — PR A widens the union; PR B narrows it. Decide which wins.
+      >   - Query key `queryKeys.x.y` — both PRs invalidate it; ensure invalidation timing is compatible.
+
+12. Verify URL-builder output matches the declared Route mount.
+
+    * When a brief covers a URL canonical migration (anything that introduces a new `buildXxxUrl` helper, mutates the return of an existing one, or moves a `<Route path="..." />` mount), the Acceptance Criteria MUST include an explicit check: "`buildXxxUrl(...)` output `matchPath`s against the declared `ROUTES.X` template (or the inline route mount string in `AppRoutes.tsx`)."
+    * Suggest writing a Vitest test (see `dojo-os` `src/utils/__tests__/url-builders-match-routes.test.ts` as a reference implementation) that asserts each builder's representative output is reachable via `matchPath({ path: template, end: true }, builtUrl)`.
+    * Why: Greptile caught this exact bug as a P1 on DOJ-4200 (commit `dbd8a1d04`). The route-contract test (DOJ-4168 / Cure 1A) validates yaml ↔ source crosswalk for canonical URLs, but it does NOT catch "builder produces a URL that doesn't match its declared route template" — because the builder name and the `ROUTES` key are decoupled. Briefs that fail to surface this gap let the same bug ship.
+    * If the in-flight PR introduces a route mount inline in the router file (per the DOJ-4200 inline-mount pattern), the contract still applies: the builder output must reach that mount via `matchPath` against the literal template string.
+
+13. Use `useAuth().isAuthenticated` for chrome branching, NOT URL-prefix string detection.
+
+    * When a brief proposes a page component that renders different chrome (header, layout, CTA bar) based on whether the visitor is authenticated, the Technical Constraints MUST require the branching to happen via `useAuth().isAuthenticated` (or the project's equivalent auth hook) — NOT via inspecting `location.pathname` against a `PUBLIC_*_ROUTE_PREFIXES` string list.
+    * Rationale: prefix-based detection makes EVERY visitor to a path under the prefix see the anon chrome, including authed users — violating the DOJ-4064 contract ("one URL = one auth-aware component, branching internally"). DOJ-4200's first attempt added `/pathways` to `PUBLIC_COURSE_ROUTE_PREFIXES` and lost the app shell for authed users on the canonical pathway-course URL. Fix (commit `dbd8a1d04`): replace the prefix list with `useAuth().isAuthenticated` and cite the PathwaysPage / PathwayDetailPage pattern as the canonical model.
+    * Reference cite to include in the brief: "Use the PathwaysPage / PathwayDetailPage pattern — `useAuth().isAuthenticated` branching inside a single wrapper component. See `dojo-os` commit `dbd8a1d04` for the kind of bug this prevents."
+
 ### Usage
 
 ```bash