Fix: on-ramp gap post pointed at github.com as canonical contribute surface
The post claimed readers land on github.com/syntaxai/tdd.md to read CONTRIBUTING.md and open a first PR. Both wrong: - github is not the canonical surface for this codebase. The repo lives on a self-hosted Forgejo at git.tdd.md; the site browses its own source through /GIT/tdd.md/... - External readers cannot PR via GitHub: b51_render_edit.ts:73-76 enforces admin-only edits and points users at git.tdd.md/syntaxai/tdd.md/issues for engagement. Updates the two affected paragraphs in the post body + the image text (header + property #2 in the bottom callout) to reflect that the two surfaces are both ON tdd.md: ./CONTRIBUTING.md browseable at /GIT/tdd.md/blob/main/CONTRIBUTING.md, and /contributing on the site. No GitHub dependency in the contribution path. Co-Authored-By: Claude Opus 4.7 <[email protected]>
3 files changed · +10 −7
content/blog/sama-v2-on-ramp-gap.md
+8
−5
| @@ -68,12 +68,14 @@ The SAMA v2 §0 auditability clause says *"the verifier is a deterministic progr | ||
| 68 | 68 | |
| 69 | 69 |  |
| 70 | 70 | |
| 71 | -One markdown file. Two surfaces: | |
| 71 | +One markdown file. Two on-site surfaces — **GitHub is not the canonical contribution surface for this codebase**. The repo lives on a self-hosted Forgejo at `git.tdd.md`; the editable site is admin-only; external contributors engage by reading the site, browsing the source through tdd.md's own SAMA-native `/GIT/` viewer, and filing issues at `git.tdd.md/syntaxai/tdd.md/issues`. Neither path goes through github.com. | |
| 72 | 72 | |
| 73 | -- **`./CONTRIBUTING.md` at repo root** — GitHub auto-detects this and surfaces it in the contribute UI. A reader on `github.com/syntaxai/tdd.md` gets pointed at it immediately. | |
| 73 | +So: | |
| 74 | + | |
| 75 | +- **`./CONTRIBUTING.md` at repo root** — auto-browseable at [`/GIT/tdd.md/blob/main/CONTRIBUTING.md`](/GIT/tdd.md/blob/main/CONTRIBUTING.md) via the same source-browser that already renders every other file in the repo. No GitHub dependency. | |
| 74 | 76 | - **`/contributing` on tdd.md** — the canonical permalink, served from the same markdown body. Sitemap entry, nav link, navigable like every other page. |
| 75 | 77 | |
| 76 | -One file, two URLs. Same pattern as the sitemap (one source, two delivery mechanisms — registry + URL endpoint). | |
| 78 | +One file, two URLs, both on tdd.md. Same pattern as the sitemap (one source, two delivery mechanisms — registry + URL endpoint). | |
| 77 | 79 | |
| 78 | 80 | **Three load-bearing properties** the document must satisfy to be 100% SAMA v2: |
| 79 | 81 | |
| @@ -87,10 +89,11 @@ One file, two URLs. Same pattern as the sitemap (one source, two delivery mechan | ||
| 87 | 89 | |
| 88 | 90 | After the `/goal` that fires next: |
| 89 | 91 | |
| 90 | -- A reader on `github.com/syntaxai/tdd.md` lands on `CONTRIBUTING.md` and can produce their first PR in a single read. | |
| 92 | +- A reader browsing the codebase at [`/GIT/tdd.md/tree/main`](/GIT/tdd.md/tree/main) sees `CONTRIBUTING.md` listed at the repo root and can read it in one click — same path every other source file uses, no off-site jump. | |
| 91 | 93 | - A reader on `tdd.md/contributing` gets the same content, navigable from the main nav. |
| 92 | 94 | - An agent context-loaded with this site no longer has to assemble the workflow from scattered sources — one document is the entry point, with links out to the canonical artifacts for the details. |
| 93 | -- The empirical chain gains its final missing link: the procedural one. Every artifact has a URL. The path to authoring them now also has a URL. | |
| 95 | +- External contributors who want to propose changes use the path that already exists: open an issue at [git.tdd.md/syntaxai/tdd.md/issues](https://git.tdd.md/syntaxai/tdd.md/issues), or fork via the Forgejo mirror. `CONTRIBUTING.md` documents that path honestly — it's not a GitHub fork-and-PR flow, and pretending it is would be drift against the existing edit handler's "editing is admin-only" wall. | |
| 96 | +- The empirical chain gains its final missing link: the procedural one. Every artifact has a URL. The path to authoring them now also has a URL — on tdd.md, not on github.com. | |
| 94 | 97 | |
| 95 | 98 | The `/goal` that drives this work follows immediately after this post — same pattern as every other plan-then-execute cycle on this site. After merge, the postmortem post compares the plan to what landed. |
| 96 | 99 | |
public/images/contributing-onramp-fix.png
+0
−0
public/images/contributing-onramp-fix.svg
+2
−2
| @@ -5,7 +5,7 @@ | ||
| 5 | 5 | <g font-family="ui-monospace, 'SF Mono', 'JetBrains Mono', Menlo, Consolas, monospace"> |
| 6 | 6 | <text x="80" y="46" font-size="20" font-weight="600" fill="#909090">The fix — CONTRIBUTING.md synthesizes existing artifacts, no new abstractions</text> |
| 7 | 7 | <text x="80" y="92" font-size="32" font-weight="700" fill="#e8e8e8">Each section links to its canonical source. No duplication.</text> |
| 8 | - <text x="80" y="120" font-size="14" fill="#7a7a7a">Two surfaces: ./CONTRIBUTING.md at repo root (GitHub-native) + /contributing on the site. One file, two URLs.</text> | |
| 8 | + <text x="80" y="120" font-size="14" fill="#7a7a7a">Two on-site surfaces: ./CONTRIBUTING.md browseable at /GIT/tdd.md/blob/main/CONTRIBUTING.md + /contributing canonical. One file.</text> | |
| 9 | 9 | </g> |
| 10 | 10 | |
| 11 | 11 | <!-- Column headers --> |
| @@ -65,7 +65,7 @@ | ||
| 65 | 65 | <g font-family="ui-monospace, 'SF Mono', 'JetBrains Mono', Menlo, Consolas, monospace"> |
| 66 | 66 | <text x="100" y="552" font-size="16" font-weight="600" fill="#7ec77e">Three load-bearing properties:</text> |
| 67 | 67 | <text x="100" y="578" font-size="14" fill="#c8c8c8">1. SINGLE SOURCE OF TRUTH — every rule is owned by exactly one canonical artifact; CONTRIBUTING.md links, doesn't restate.</text> |
| 68 | - <text x="100" y="602" font-size="14" fill="#c8c8c8">2. TWO SURFACES — ./CONTRIBUTING.md (GitHub auto-detects it) + /contributing (site canonical) read from ONE markdown file.</text> | |
| 68 | + <text x="100" y="602" font-size="14" fill="#c8c8c8">2. TWO ON-SITE SURFACES — /GIT/tdd.md/blob/main/CONTRIBUTING.md (auto via /GIT/) + /contributing (canonical). No GitHub dependency.</text> | |
| 69 | 69 | <text x="100" y="626" font-size="14" fill="#c8c8c8">3. DOGFOODED — its own creation is a /goal-driven artifact at /goals/contributing-md, with merge_sha in frontmatter.</text> |
| 70 | 70 | <text x="100" y="648" font-size="13" fill="#8a8a8a">Drift detection follow-up: a test grep-checks that CONTRIBUTING.md only contains references to canonical sources (no rule restatements).</text> |
| 71 | 71 | </g> |