Every artifact has a URL. The on-ramp doesn't.

Open https://tdd.md in a fresh browser. Count the entry points:

Six entry points. Each one is its own auditable artifact. Each one has been the subject of at least one blog post. Each one is what the empirical-chain argument rests on.

Now ask the question the entire site exists to answer for a reader: "How do I contribute?"

There is no answer. There is no front door. There is no document at /contributing or CONTRIBUTING.md or anywhere else that says "here is how you add a feature to this codebase." You are expected to read 5+ blog posts, browse the goals registry, skim PR bodies for patterns, and reverse-engineer the file-naming convention from the source tree. The site that has been preaching auditability for forty PRs has been failing the most basic on-ramp test the entire time.

Every artifact has a URL — the path to authoring them doesn't

#The artifacts vs the path

The table above splits cleanly into two halves. Above the line: every output the codebase produces is in git, on the site, and grep-able. Below the line, in amber and red: the authoring path — how those outputs come into being — is scattered or missing entirely.

Specifically:

  • The /goal workflow rule lives at /var/home/scri/.claude/projects/-var-home-scri-Documents-tdd-md/memory/feedback_goal_authoring_workflow.md — an agent-private memory file. A human contributor literally cannot read it. The rule that determines how every PR on this site is authored is preserved for the agent and invisible to everyone else.

  • The layer-prefix convention (a31_* = Layer 0, b32_* = Layer 1, c14_* = Layer 2, d21_* = Layer 3) is partially documented in /sama/v2 §1.1, partially in the /sama/discipline/sorted discipline page, and partially encoded in the source code itself. A new contributor has to triangulate.

  • The branch-PR-deploy flow (branch → gh pr create → merge → push p620 → flatpak-spawn --host scripts/p620/deploy-tdd-md.sh → live-verify) is in zero blog posts as a standalone procedure. It's mentioned as a constraint inside individual /goal bodies, embedded in PR commit messages, scattered across the recent /goals archive. Never collected.

  • The test discipline (sibling .test.ts, 402+ stays green, /sama/v2/verify must stay 7/7 ✓) is the load-bearing anti-fudge rule for the entire codebase. It appears in §4.3 of the spec, in every PR body, in every /goal's anti-fudge constraints. Never in one document.

  • The image convention (live under public/images/, https://tdd.md watermark, served via /images/<name>.<ext> wildcard) was added in PR #44 and lives only in memory + scattered references. There is no public document a contributor can read to learn it.

  • The Containerfile gotcha (every new top-level directory needs a COPY <dir> ./<dir> line, surfaced by PR #46 when /goals/<slug> returned 404 in production) is captured in one PR's commit message and the postmortem section of the goals registry implementation. A new contributor who adds a top-level directory will hit the same 404 in production and have to discover the rule themselves.

Each of these rules is real, enforced, and load-bearing. None of them is in a canonical-doc-shaped place.

#What a new contributor actually sees

Pretend you've just landed on tdd.md and want to add a blog post. The literal steps required to know how:

  1. Open /sama/v2 to learn the layer convention. Realize blog posts aren't a layer-thing — they're content.
  2. Open /blog and click around — notice the URL pattern /blog/<slug>.
  3. Browse /GIT/tdd.md/tree/main/content/blog — find that posts are markdown files.
  4. Open /GIT/tdd.md/blob/main/src/a31_blog.ts — discover ALL_POSTS and realize new posts need to be registered.
  5. Look at /blog/2026-05/sama-v2-sitemap-implementation-plan to see the pattern for how posts are authored — but that's about sitemap.xml, not about the blog post itself.
  6. Hunt for a recent merged PR — find gh pr view 44 — see the branch-merge-deploy flow in the commit messages, not in any document.
  7. Try to figure out images. Read /blog/2026-05/sama-v2-goal-chain-gap looking for image conventions. Find a passing mention. Open a recent PR with images. Reverse-engineer.
  8. Realize you don't know whether your blog post needs sibling tests. Read /sama/v2 §4.3. Determine: no — only source files need siblings. Content files don't.
  9. Realize you might break /sama/v2/verify. Run it locally? There's no instruction. Push to main and pray? That breaks the workflow. Fork the repo? The verifier doesn't run on forks.
  10. Give up. Open an issue saying "how do I contribute?"

This is the experience the site currently delivers. The empirical chain is intact for every artifact except the one that brings new contributors in.

#Why this is a SAMA v2 self-violation

The chain-gap drama post argued that the /goal command was a SAMA v2 self-violation because the contract driving every PR wasn't in the chain. The fix shipped — /goals/<slug>.md files are in git, the workflow memory is locked in, every future /goal lands in the registry by construction.

This post argues the same shape, one level up: the workflow itself is the next missing artifact. The /goal is now in git; the rule for how to write a /goal is not. The branch flow is encoded in memory; the rule for how to run the branch flow is not on the site. The image convention is enforced by code; the rule that a contributor needs to know about the convention is nowhere a contributor would think to look.

It's the same structural failure as before, applied to procedure instead of contract. The empirical chain has always had this hole; we just shipped the patch one level too shallow.

The SAMA v2 §0 auditability clause says "the verifier is a deterministic program; that claim is only auditable if a human can reproduce it from the data." By the same logic: the authoring process is a discipline; that claim is only auditable if a human can reproduce it from the published material. They can't. Not because we hid anything — because we never wrote the on-ramp down in one place.

#The fix

CONTRIBUTING.md — synthesis, not duplication

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.

So:

  • ./CONTRIBUTING.md at repo root — auto-browseable at /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, 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:

  1. Single source of truth. Every rule is owned by exactly one canonical artifact. CONTRIBUTING.md links, doesn't restate. The layer convention lives at /sama/v2 §1.1; CONTRIBUTING.md says "see §1.1" and never copies the table. If a future PR changes the spec, CONTRIBUTING.md doesn't drift because there's nothing in it to drift.

  2. Dogfooded. Its own creation is /goal-driven. goals/contributing-md.md lands as the first commit of the PR per the workflow memory; the merge SHA flips to shipped at deploy time. The artifact that documents the workflow is itself produced by the workflow.

  3. Drift-detectable. A test grep-checks that CONTRIBUTING.md only contains references to canonical sources — no rule restatements. If someone adds "the SAMA layers are a31/b32/c14/d21" as a paragraph instead of a link, the test fails. This is the same anti-fudge shape the verifier uses for source files.

#What lands when this ships

After the /goal that fires next:

  • A reader browsing the codebase at /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.
  • External contributors who want to propose changes use the path that already exists: open an issue at 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.

The drama ends quietly. The chain closes. A new contributor lands on tdd.md and finds the front door right where they expected it.