fe92ed686f5c54536265d5d8958d34ddee1a244f diff --git a/content/blog/sama-v2-on-ramp-gap.md b/content/blog/sama-v2-on-ramp-gap.md index 3569cf8c934f08da90a49918214d905df8122900..f3576ae3413d3ee42a11c6e77a659f4184714f34 100644 --- a/content/blog/sama-v2-on-ramp-gap.md +++ b/content/blog/sama-v2-on-ramp-gap.md @@ -68,12 +68,14 @@ The SAMA v2 §0 auditability clause says *"the verifier is a deterministic progr ![CONTRIBUTING.md — synthesis, not duplication](/images/contributing-onramp-fix.png?v=1) -One markdown file. Two surfaces: +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. -- **`./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. +So: + +- **`./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. - **`/contributing` on tdd.md** — the canonical permalink, served from the same markdown body. Sitemap entry, nav link, navigable like every other page. -One file, two URLs. Same pattern as the sitemap (one source, two delivery mechanisms — registry + URL endpoint). +One file, two URLs, both on tdd.md. Same pattern as the sitemap (one source, two delivery mechanisms — registry + URL endpoint). **Three load-bearing properties** the document must satisfy to be 100% SAMA v2: @@ -87,10 +89,11 @@ One file, two URLs. Same pattern as the sitemap (one source, two delivery mechan After the `/goal` that fires next: -- A reader on `github.com/syntaxai/tdd.md` lands on `CONTRIBUTING.md` and can produce their first PR in a single read. +- 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. - A reader on `tdd.md/contributing` gets the same content, navigable from the main nav. - 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. -- 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. +- 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. +- 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. 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. diff --git a/public/images/contributing-onramp-fix.png b/public/images/contributing-onramp-fix.png index 0c923899c0602fd1a5cb47c6742b0a6f1303aa02..f61d8aa84938699de622bcca21ebd72f9790ef01 100644 Binary files a/public/images/contributing-onramp-fix.png and b/public/images/contributing-onramp-fix.png differ diff --git a/public/images/contributing-onramp-fix.svg b/public/images/contributing-onramp-fix.svg index dcaeec789353a5893ce433f0a05d98476dfb8533..8cadecf6d0bc0fa1ecceecf647aa3374fd628e43 100644 --- a/public/images/contributing-onramp-fix.svg +++ b/public/images/contributing-onramp-fix.svg @@ -5,7 +5,7 @@ The fix — CONTRIBUTING.md synthesizes existing artifacts, no new abstractions Each section links to its canonical source. No duplication. - Two surfaces: ./CONTRIBUTING.md at repo root (GitHub-native) + /contributing on the site. One file, two URLs. + Two on-site surfaces: ./CONTRIBUTING.md browseable at /GIT/tdd.md/blob/main/CONTRIBUTING.md + /contributing canonical. One file. @@ -65,7 +65,7 @@ Three load-bearing properties: 1. SINGLE SOURCE OF TRUTH — every rule is owned by exactly one canonical artifact; CONTRIBUTING.md links, doesn't restate. - 2. TWO SURFACES — ./CONTRIBUTING.md (GitHub auto-detects it) + /contributing (site canonical) read from ONE markdown file. + 2. TWO ON-SITE SURFACES — /GIT/tdd.md/blob/main/CONTRIBUTING.md (auto via /GIT/) + /contributing (canonical). No GitHub dependency. 3. DOGFOODED — its own creation is a /goal-driven artifact at /goals/contributing-md, with merge_sha in frontmatter. Drift detection follow-up: a test grep-checks that CONTRIBUTING.md only contains references to canonical sources (no rule restatements).