/goal pending: sama-discipline-prefix
First commit per feedback_goal_authoring_workflow.md. Hypothesis test of cost-flattening from PR #42 postmortem. Clock starts at this commit; flipped to shipped at final commit before deploy. Co-Authored-By: Claude Opus 4.7 <[email protected]>
1 file changed · +71 −0
goals/sama-discipline-prefix.md
+71
−0
| @@ -0,0 +1,71 @@ | ||
| 1 | +--- | |
| 2 | +slug: sama-discipline-prefix | |
| 3 | +title: Move /sama/<discipline> → /sama/discipline/<slug> — hypothesis test of cost-flattening | |
| 4 | +date: 2026-05-25 | |
| 5 | +branch: sama-discipline-prefix | |
| 6 | +pr_number: null | |
| 7 | +merge_sha: null | |
| 8 | +status: pending | |
| 9 | +related_posts: [sama-v2-git-url-refactor-postmortem] | |
| 10 | +--- | |
| 11 | + | |
| 12 | +Goal: Execute the second URL refactor under the b32_<old>_url_redirect pattern established by PR #42 (git-url-drop-owner). Move the four /sama discipline pages from /sama/<slug> to /sama/discipline/<slug>, creating a cleaner namespace for v1 content alongside /sama/v2/* for v2 content. Inbound links survive via ONE regex 301 redirect using exactly the same shape as b32_git_url_redirect.ts. **Primary purpose: hypothesis test** — the postmortem of PR #42 closed with a falsifiable claim that "if the second URL refactor lands in ~1 hour, the cost-flattening of pattern-as-redirect is confirmed". This /goal IS that test. The clock starts at the first commit on this branch and stops at deploy+live-verify. | |
| 13 | + | |
| 14 | +Done when: | |
| 15 | +- All four discipline URLs work under the new shape: | |
| 16 | + * /sama/discipline/sorted → 200, content as before | |
| 17 | + * /sama/discipline/architecture → 200 | |
| 18 | + * /sama/discipline/modeled → 200 | |
| 19 | + * /sama/discipline/atomic → 200 | |
| 20 | +- Old URLs are permanent redirects: | |
| 21 | + * curl -I https://tdd.md/sama/sorted → HTTP/2 301, location: /sama/discipline/sorted, cache-control: public, max-age=86400 | |
| 22 | + * Same for architecture, modeled, atomic | |
| 23 | +- Implemented as ONE regex in src/b32_sama_discipline_url_redirect.ts (mirroring b32_git_url_redirect.ts exactly): | |
| 24 | + const OLD_PATTERN = /^\/sama\/(sorted|architecture|modeled|atomic)$/; | |
| 25 | + export const rewriteOldSamaDisciplineUrl = (pathname: string): string | null => { ... } | |
| 26 | + Fixed enumeration of the four slugs (S/A/M/A are spec-frozen). Sibling test src/b32_sama_discipline_url_redirect.test.ts covers: each of the four matches, the new URL form returns null, an unrelated /sama/v2 URL returns null, an unrelated /something path returns null, empty input returns null. | |
| 27 | +- Layer 3 wiring: | |
| 28 | + * src/d21_handlers_fallback.ts: import + 301-emit block placed BEFORE the existing rewriteOldGitUrl block (both are legacy-URL redirects; order by alphabetical prefix or by recency, but the new one must NOT match new-shape URLs) | |
| 29 | + * src/d21_app.ts Bun routes: change "/sama/:slug" → "/sama/discipline/:slug" (the explicit handler now matches the new shape; /sama/v2 + /sama/skill + /sama (landing) all keep working because Bun route precedence) | |
| 30 | +- All hard-coded /sama/sorted, /sama/architecture, /sama/modeled, /sama/atomic strings in content/ and src/ rewritten to use /sama/discipline/<slug>: | |
| 31 | + * content/sama/v2.md (the spec references the disciplines in §1.1) | |
| 32 | + * content/sama/sorted.md (cross-refs to the other three) | |
| 33 | + * content/sama/architecture.md | |
| 34 | + * content/sama/modeled.md | |
| 35 | + * content/sama/atomic.md | |
| 36 | + * content/home.md (if it links to disciplines) | |
| 37 | + * Any /blog post that references them via /sama/<slug> | |
| 38 | + * src/d21_handlers_sama.ts (the SAMA_LANDING_MD template that renders /sama; row links to /sama/<slug>) | |
| 39 | + After: `grep -rE "/sama/(sorted|architecture|modeled|atomic)" content/ src/` returns 0 lines (excluding the redirect helper + sibling test + this goal file itself). | |
| 40 | +- Sitemap auto-updates: src/d21_app.ts sitemap handler maps ALL_SAMA → /sama/<slug>; this needs to change to /sama/discipline/<slug>. STATIC_PATHS unchanged (/sama landing still lives at /sama). | |
| 41 | +- All 409+ tests still pass; new helper test adds 6-8 cases for the redirect regex. | |
| 42 | +- /sama/v2/verify still reports 7/7 ✓ (anti-fudge). | |
| 43 | +- This goal file (goals/sama-discipline-prefix.md) flipped from status: pending → status: shipped in the final commit before deploy, with merge_sha filled. | |
| 44 | +- Deployed; live-verify with curl: | |
| 45 | + * /sama/discipline/sorted → 200, body contains "Sorted" | |
| 46 | + * /sama/sorted → 301 with Location /sama/discipline/sorted | |
| 47 | + * curl -sL of the old URL lands on 200 with content | |
| 48 | + * /sitemap.xml | grep -c "/sama/discipline/" → 4 | |
| 49 | + * /sama/v2/verify → 7/7 ✓ | |
| 50 | +- HYPOTHESIS TEST CLAIM: clock from "git checkout -b sama-discipline-prefix" to "deploy success + live-verify passes" is ≤ 90 minutes (the postmortem of PR #42 predicted "~1 hour"; a 50% buffer is fair given this is hypothesis-verification, not blind prediction). Wall-clock duration recorded in the postmortem post. | |
| 51 | + | |
| 52 | +Constraints (anti-fudge): | |
| 53 | +- ONE regex in the redirect helper. If the regex grows into a hand-maintained list, anti-fudge is violated. | |
| 54 | +- Mirror b32_git_url_redirect.ts shape exactly — same export signature, same sibling-test structure, same Layer-3 wrapper in d21_handlers_fallback.ts. This is the WHOLE POINT of the hypothesis test; deviating defeats it. | |
| 55 | +- Don't change /sama/v2 or /sama/skill URLs. Only the four discipline pages move. | |
| 56 | +- Don't add a "discipline" segment to /sama (landing) or /sama/v2 (spec). Only to per-discipline detail pages. | |
| 57 | +- No alias mode. 301 forces consolidation. | |
| 58 | +- Site language English-only. | |
| 59 | +- GitHub flow via flatpak-spawn (branch → PR → merge → push p620 → deploy via flatpak-spawn --host scripts/p620/deploy-tdd-md.sh). | |
| 60 | +- Do NOT change any §4 verifier logic. | |
| 61 | +- PR body MUST include this verbatim /goal under a "## /goal" heading per feedback_goal_authoring_workflow.md. | |
| 62 | + | |
| 63 | +Load-bearing files to read FIRST: | |
| 64 | +- src/b32_git_url_redirect.ts (the template — copy its shape line-for-line) | |
| 65 | +- src/b32_git_url_redirect.test.ts (the sibling-test template) | |
| 66 | +- src/d21_handlers_fallback.ts (the rewriteOldGitUrl block — insert the new redirect adjacent) | |
| 67 | +- src/d21_app.ts (Bun route table — change /sama/:slug → /sama/discipline/:slug; sitemap handler ALL_SAMA mapping) | |
| 68 | +- src/d21_handlers_sama.ts (SAMA_LANDING_MD template — discipline row links) | |
| 69 | +- src/a31_sama.ts (ALL_SAMA — should remain unchanged; only URL emission changes downstream) | |
| 70 | +- content/sama/*.md (cross-discipline link rewrites) | |
| 71 | +- /blog/sama-v2-git-url-refactor-postmortem (the hypothesis being tested — re-read so the postmortem's framing stays consistent) | |