/goal pending: contributing-md
First commit on the branch — dogfoods the workflow per feedback_goal_authoring_workflow.md. status: pending, merge_sha: null. Flipped to shipped + filled in the final commit before deploy. Co-Authored-By: Claude Opus 4.7 <[email protected]>
1 file changed · +66 −0
goals/contributing-md.md
+66
−0
| @@ -0,0 +1,66 @@ | ||
| 1 | +--- | |
| 2 | +slug: contributing-md | |
| 3 | +title: Build CONTRIBUTING.md as the canonical on-ramp + drift-detection test | |
| 4 | +date: 2026-05-25 | |
| 5 | +branch: contributing-md | |
| 6 | +pr_number: null | |
| 7 | +merge_sha: null | |
| 8 | +status: pending | |
| 9 | +related_posts: [sama-v2-on-ramp-gap] | |
| 10 | +--- | |
| 11 | + | |
| 12 | +Goal: Build the canonical contributor on-ramp that /blog/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. | |
| 13 | + | |
| 14 | +Done when: | |
| 15 | +- ./CONTRIBUTING.md exists at the repo root with the on-ramp content covering: | |
| 16 | + * "Before you start" — links to /sama/v2 (spec), /blog/sama-v2-on-ramp-gap (this drama), /blog/sama-v2-goal-chain-gap (the prior drama), and a one-line statement that /sama/v2/verify must stay 7/7 ✓ across every merge. | |
| 17 | + * "The /goal workflow" — 5-7 lines summarizing the rule from /goals/migrate-historical-goals (which contains the verbatim authoritative version); link points there. | |
| 18 | + * "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. | |
| 19 | + * "How to add a blog post" — recipe: write content/blog/<slug>.md, add ALL_POSTS entry in src/a31_blog.ts, branch + PR + merge + deploy. Link to /blog/sama-v2-sitemap-implementation-plan as a worked example. | |
| 20 | + * "How to add a /goal" — recipe: type /goal in the conversation, the agent's first action is to write goals/<slug>.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. | |
| 21 | + * "How to add an image" — recipe: public/images/<name>.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. | |
| 22 | + * "How to add a Layer-1 helper" — recipe: b32_<name>.ts + sibling b32_<name>.test.ts, no I/O in the helper. Link to /sama/v2#41-sorted and /sama/v2#43-modeled-tests. | |
| 23 | + * "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/<slug> returned 404 in production because the dir wasn't shipping with the image). | |
| 24 | + * "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. | |
| 25 | + * "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. | |
| 26 | +- 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. | |
| 27 | +- 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). | |
| 28 | +- 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). | |
| 29 | +- Drift-detection test src/b32_contributing_drift.test.ts (Layer 1 pure — reads ./CONTRIBUTING.md once at test time, asserts on its contents): | |
| 30 | + * test: contains link to /sama/v2 (the spec is referenced) | |
| 31 | + * test: contains link to /goals/migrate-historical-goals (the /goal workflow's canonical version) | |
| 32 | + * test: contains link to /blog/sama-v2-on-ramp-gap (this drama post) | |
| 33 | + * test: contains link to /blog/sama-v2-goal-chain-gap (the prior drama) | |
| 34 | + * test: contains link to git.tdd.md/syntaxai/tdd.md/issues (the external engagement path) | |
| 35 | + * test: line count < 250 (bloat ceiling — restatement detection) | |
| 36 | +- 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. | |
| 37 | +- All 402+ tests still pass; the new drift-detection tests add 6 cases. | |
| 38 | +- /sama/v2/verify still reports 7/7 ✓ (anti-fudge). | |
| 39 | +- 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. | |
| 40 | +- Deployed; live-verify with curl: | |
| 41 | + * /contributing → 200, body contains the section headers | |
| 42 | + * /GIT/tdd.md/blob/main/CONTRIBUTING.md → 200 (the link in /blog/sama-v2-on-ramp-gap stops 404'ing) | |
| 43 | + * /sitemap.xml | grep -c '/contributing' → at least 1 | |
| 44 | + * /sama/v2/verify → 7/7 ✓ | |
| 45 | + * Nav across pages shows /contributing link | |
| 46 | + | |
| 47 | +Constraints (anti-fudge): | |
| 48 | +- 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. | |
| 49 | +- 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. | |
| 50 | +- 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. | |
| 51 | +- Site language English-only — the file is read by humans and agents who may not speak Dutch. | |
| 52 | +- GitHub flow via flatpak-spawn for the admin's PR-merge path. | |
| 53 | +- Do NOT change any §4 verifier logic. | |
| 54 | +- 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. | |
| 55 | +- 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. | |
| 56 | + | |
| 57 | +Load-bearing files to read FIRST: | |
| 58 | +- /blog/sama-v2-on-ramp-gap (the design spec — read it first; the sketch in the "fix" section is what this /goal executes) | |
| 59 | +- /goals/migrate-historical-goals (the canonical /goal workflow definition that CONTRIBUTING.md will link to, not restate) | |
| 60 | +- /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) | |
| 61 | +- src/d21_handlers_sama.ts (samaLandingHandler — the pattern the /contributing handler should mirror, but reading from a root file instead of content/sama/) | |
| 62 | +- src/d21_app.ts (route table — register /contributing here) | |
| 63 | +- src/b51_render_layout.ts:47 + the Section type at line 14 (nav strip + section enum — add "contributing" or reuse existing) | |
| 64 | +- src/b32_sitemap.ts (STATIC_PATHS — add "/contributing", update sibling test expectations) | |
| 65 | +- Containerfile (add COPY CONTRIBUTING.md line so the file ships with the image — same lesson as PR #46 for goals/) | |
| 66 | +- 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) | |