syntaxai/tdd.md · main · goals / contributing-md.md

contributing-md.md 67 lines · 8292 bytes raw · source

slug: contributing-md title: Build CONTRIBUTING.md as the canonical on-ramp + drift-detection test date: 2026-05-25 branch: contributing-md pr_number: 51 merge_sha: 96225f8 status: shipped related_posts: [sama-v2-on-ramp-gap]

Goal: Build the canonical contributor on-ramp that /blog/2026-05/sama-v2-on-ramp-gap argued is missing. One markdown file at the repo root (./CONTRIBUTING.md), browseable via the site's own /GIT/ surface (auto), AND served at /contributing on tdd.md (canonical permalink). No GitHub dependency — external contributors engage via git.tdd.md/issues, not github.com. Three load-bearing properties: (1) single source of truth — every rule LINKS to its canonical artifact, doesn't restate; (2) dogfooded — this goal file is committed BEFORE any code per the workflow memory, and the file goes live with merge_sha filled at deploy; (3) drift-detectable — a sibling test grep-checks CONTRIBUTING.md contains references to canonical sources + enforces a line-count ceiling so future bloat is caught.

Done when:

  • ./CONTRIBUTING.md exists at the repo root with the on-ramp content covering:
    • "Before you start" — links to /sama/v2 (spec), /blog/2026-05/sama-v2-on-ramp-gap (this drama), /blog/2026-05/sama-v2-goal-chain-gap (the prior drama), and a one-line statement that /sama/v2/verify must stay 7/7 ✓ across every merge.
    • "The /goal workflow" — 5-7 lines summarizing the rule from /goals/migrate-historical-goals (which contains the verbatim authoritative version); link points there.
    • "SAMA layer convention" — a table of prefix → layer with concrete examples from this repo (a31_blog.ts, b32_sitemap.ts, c14_git.ts, d21_app.ts, b51_render_layout.ts). Each row LINKS to /sama/v2#11-layers for the canonical definition.
    • "How to add a blog post" — recipe: write content/blog/.md, add ALL_POSTS entry in src/a31_blog.ts, branch + PR + merge + deploy. Link to /blog/2026-05/sama-v2-sitemap-implementation-plan as a worked example.
    • "How to add a /goal" — recipe: type /goal in the conversation, the agent's first action is to write goals/.md per the workflow. Human path: file an issue at git.tdd.md/syntaxai/tdd.md/issues with the Goal/Done-when/Constraints/Load-bearing-files shape.
    • "How to add an image" — recipe: public/images/.svg + rsvg-convert PNG, both must carry the literal text "https://tdd.md" as a watermark. Link to the /images/* wildcard handler in d21_handlers_fallback.ts.
    • "How to add a Layer-1 helper" — recipe: b32_.ts + sibling b32_.test.ts, no I/O in the helper. Link to /sama/v2#41-sorted and /sama/v2#43-modeled-tests.
    • "How to add a top-level directory" — recipe + WARNING: every new top-level directory needs a corresponding COPY <dir> ./<dir> line in Containerfile (lessons-learned from PR #46 where /goals/ returned 404 in production because the dir wasn't shipping with the image).
    • "Anti-fudge defaults" — a 5-bullet checklist: site language English-only; /sama/v2/verify stays 7/7 ✓ across the merge; GitHub flow via flatpak-spawn (admin path); no §4 verifier changes; new top-level dirs require Containerfile updates.
    • "Where to engage if you're not the admin" — open an issue at git.tdd.md/syntaxai/tdd.md/issues. Honest statement: editing the site is admin-only by design (see b51_render_edit.ts); CONTRIBUTING.md describes how the admin (and the agent) author, with the issue-tracker path for external engagement.
  • Layer 3 handler src/d21_handlers_contributing.ts: single closure that reads ./CONTRIBUTING.md from disk and renders it via the docs layout. Route /contributing registered in d21_app.ts. Nav strip in b51_render_layout.ts gets a /contributing link.
  • Sitemap: add "/contributing" to STATIC_PATHS in src/b32_sitemap.ts; existing STATIC_PATHS test updated to expect 13 entries instead of 12; sitemap handler unchanged (it already iterates STATIC_PATHS).
  • Containerfile: add COPY CONTRIBUTING.md ./ (or fold into the existing first COPY line). Verify on deploy that the file is in the running container (curl /contributing returns 200, not 404).
  • Drift-detection test src/b32_contributing_drift.test.ts (Layer 1 pure — reads ./CONTRIBUTING.md once at test time, asserts on its contents):
    • test: contains link to /sama/v2 (the spec is referenced)
    • test: contains link to /goals/migrate-historical-goals (the /goal workflow's canonical version)
    • test: contains link to /blog/2026-05/sama-v2-on-ramp-gap (this drama post)
    • test: contains link to /blog/2026-05/sama-v2-goal-chain-gap (the prior drama)
    • test: contains link to git.tdd.md/syntaxai/tdd.md/issues (the external engagement path)
    • test: line count < 250 (bloat ceiling — restatement detection)
  • The /contributing detail page reads ./CONTRIBUTING.md and renders it through renderDocsPage with active: "goals"-or-equivalent. The Section type may need a new "contributing" value or we route /contributing as a generic markdown route — agent choice based on whichever keeps the nav highlighting consistent.
  • All 402+ tests still pass; the new drift-detection tests add 6 cases.
  • /sama/v2/verify still reports 7/7 ✓ (anti-fudge).
  • This goal file (goals/contributing-md.md) flipped from status: pending to status: shipped in the final commit before deploy, with merge_sha filled from the PR's merge commit. PR body MUST include the verbatim /goal text under a "## /goal" heading per feedback_goal_authoring_workflow.md.
  • Deployed; live-verify with curl:
    • /contributing → 200, body contains the section headers
    • /GIT/tdd.md/blob/main/CONTRIBUTING.md → 200 (the link in /blog/2026-05/sama-v2-on-ramp-gap stops 404'ing)
    • /sitemap.xml | grep -c '/contributing' → at least 1
    • /sama/v2/verify → 7/7 ✓
    • Nav across pages shows /contributing link

Constraints (anti-fudge):

  • CONTRIBUTING.md LINKS to canonical sources, never restates rules. If a future PR adds a paragraph that restates a SAMA layer definition instead of linking to /sama/v2#11-layers, that's drift — the test must catch it via the line-count ceiling at minimum.
  • No GitHub-as-canonical-surface framing. External contributors use git.tdd.md/issues. The admin uses GitHub PRs as an internal mechanism. Honest about both, no pretense.
  • The drift-detection test is a sibling of CONTRIBUTING.md in spirit (lives in src/ for Bun to pick up, but tests the root-level markdown). Treat it like b32_sama_verify.test.ts — Layer 1 pure, no side effects.
  • Site language English-only — the file is read by humans and agents who may not speak Dutch.
  • GitHub flow via flatpak-spawn for the admin's PR-merge path.
  • Do NOT change any §4 verifier logic.
  • The PR body itself MUST embed the verbatim /goal text. Per feedback_goal_authoring_workflow.md, this is the defense-in-depth so the contract survives even if goals/ is corrupted.
  • Don't create a content/contributing.md — the file lives at the repo root (./CONTRIBUTING.md) so GitHub-style tooling on Forgejo recognizes it AND the /GIT/ browser surfaces it at the root level alongside README.md. content/blog/ is for blog posts; CONTRIBUTING.md is project-meta, lives at root.

Load-bearing files to read FIRST:

  • /blog/2026-05/sama-v2-on-ramp-gap (the design spec — read it first; the sketch in the "fix" section is what this /goal executes)
  • /goals/migrate-historical-goals (the canonical /goal workflow definition that CONTRIBUTING.md will link to, not restate)
  • /var/home/scri/.claude/projects/-var-home-scri-Documents-tdd-md/memory/feedback_goal_authoring_workflow.md (the dogfood rule this goal executes for the second time)
  • src/d21_handlers_sama.ts (samaLandingHandler — the pattern the /contributing handler should mirror, but reading from a root file instead of content/sama/)
  • src/d21_app.ts (route table — register /contributing here)
  • src/b51_render_layout.ts:47 + the Section type at line 14 (nav strip + section enum — add "contributing" or reuse existing)
  • src/b32_sitemap.ts (STATIC_PATHS — add "/contributing", update sibling test expectations)
  • Containerfile (add COPY CONTRIBUTING.md line so the file ships with the image — same lesson as PR #46 for goals/)
  • src/b51_render_edit.ts:73-76 (the existing "editing is admin-only" wall and the git.tdd.md/issues redirect — confirm the language CONTRIBUTING.md uses is consistent)