[mikestankavich]

Platform's share of TRA-1128, in three commits. PR #586 did the ignore/untrack half; this finishes it and adds the shared-process split.

1. The ignore block did not match the ticket

AC#1 requires identical text across repos "so no repo is subtly different again." Platform's block carried a trailing Named to match ble-mcp-test. clause that a previous session added while relaying the text, then described on the ticket as "adopted verbatim." It is not in the ticket.

Dropped. Verified by hash rather than by eye, since three sessions each posted a "paste-verbatim canonical block" and no two matched:

sed -n '187,200p' .gitignore | sha256sum
cfc7cf430d18af4d3e788cfc66b1a0ab5a0e509c06e996b4d285362088a6d225

All four repos report that hash.

2. The sweep left five dangling references

git rm -r --cached removed the tree; nothing removed the pointers into it. Since #586 merged, platform has been documenting paths that do not exist, with a green build throughout.

Test applied per file: does the surrounding prose still mean what it says without the link? Ticket numbers outlive paths, so references carrying real information were retargeted rather than dropped.

File	Disposition
frontend/src/worker/cs108/barcode/accumulator.ts	behaviours already described above it — cite TRA-821
backend/internal/util/httputil/auth_error.go	"a short canonical set" is undefined without its pointer — cite TRA-407
deploy/edge/README.md	already carried TRA-988 beside the two paths
load-tests/ingest/README.md	finding stated inline above it; pointer was redundant — removed

Nothing promoted out of the deleted tree, per "no case-by-case triage, no promoting files just in case."

3. Shared working agreements split into AGENTS.md

Root AGENTS.md, byte-identical across docs, platform and infra, imported by CLAUDE.md via a bare @AGENTS.md. Root-level and conventionally named, so a human finds it and non-Claude tooling reads it.

Pulled from trakrf/docs#218 via gh api rather than retyped — retyping is what produced three non-matching canonical blocks earlier in this ticket.

sha256  8aae612ddf7bea89358c13df03ae395aef041533afb019406c15d7c9bd9ac3c1

CLAUDE.md keeps only repo specifics, stated rather than explained: 496 → 209 words, 51 → 26 lines. Combined with AGENTS.md, 421 words against main's 496 — a real reduction, but only because platform's file was unusually fat. Not comparable to the other repos' figures.

Worktree conventions are out entirely — that is csw.json configuration, not prose, and not a workflow to impose on others. One line survives the cut because it is a build fact rather than a workflow mandate: just bootstrap a fresh worktree before validating, or the go:embed targets are missing and every check fails for that reason alone. That has already invalidated a verification here.

CONTRIBUTING.md is now the single source for branch, commit and merge rules

Making it so required fixing three things it had wrong. None of these would have surfaced by grepping for superpowers; the boundary question flushed them out sideways.

• Branch naming said feature/add-xyz — dead letter in every repo. Now <type>/<slug>, with <type>/<ticket>-<slug> named for maintainers. An outside contributor has no ticket number and could not follow the maintainer form.
• Conventional commits were marked "Optional … no tool depends on it", directly contradicting CLAUDE.md, which stated them as a rule. They are required; enforcement is manual, which is a different claim from optional.
• No merge policy was stated at all. Silence in a contributor guide reads as no policy. Now: every change via PR, --merge, never squash or rebase.

Verification

• just validate — green, exit 0
• Ignore-block and AGENTS.md hashes match the canonical values above
• Wide grep returns only the .gitignore block itself; zero dangling references
• All four ignore patterns confirmed firing against real probe paths via git check-ignore -v, not merely present
• Exactly one @ across CLAUDE.md, AGENTS.md and CONTRIBUTING.md — the intended import, re-grepped after adding it

The import is confirmed to load. Not inferred from the documentation, and not from /context — observed via an InstructionsLoaded hook in a fresh session, payload verbatim:

{"hook_event_name":"InstructionsLoaded",
 "file_path":".../AGENTS.md","memory_type":"Project",
 "load_reason":"include","parent_file_path":".../CLAUDE.md"}

load_reason: "include" with parent_file_path naming CLAUDE.md is the harness stating the @AGENTS.md import resolved at session start. The check carried a control — CLAUDE.md itself appears with load_reason: "session_start" — without which an empty log would have been evidence of nothing rather than evidence of a failed import.

Observed in trakrf/infra. This repo's construct is byte-identical in the relevant respect (a bare @AGENTS.md at CLAUDE.md line 3, the only @ in the file), so the mechanism is confirmed; platform's individual load was not separately instrumented.

Two corrections to earlier versions of this PR body, stated rather than silently removed.

1. It told you to run /context and look for AGENTS.md under "Memory files". That cannot work. /context prints only a category total (⛁ Memory files: 9.6k tokens) with no filenames, in fresh and long-running sessions alike; /context all expands MCP tools and skills instead. The instruction came from the Claude Code memory docs, which describe a list this build does not print.
2. It then offered the Memory files token count as a weak fallback. Also worthless — that number confounds CLAUDE.md's own size change, the import being present or absent, and the auto-memory index growing during a session. 9.4k vs 9.6k separates none of them.

Both were the same shape as the bug they were meant to catch: a check whose output has no place for the answer to appear. /context never reports "AGENTS.md is not loaded" — it says nothing about filenames at all, so a negative result has no shape and a reviewer comes away believing they verified something. The rule that catches it is one word longer than "verify the premise": run the check before you recommend it. Three repos shipped that instruction; none of the three sessions had run it.

Import parsing skips backticks, so a backticked path is silently not imported and a stray bare @ silently is — infra found a latent case held off only by the backticks around git@github.com:trakrf:infra.git. This repo: exactly one @ across CLAUDE.md, AGENTS.md and CONTRIBUTING.md, the intended import, re-grepped after adding it.

Refs: TRA-1128

🤖 Generated with Claude Code

https://claude.ai/code/session_01W7p2hFrE6ZFWS91XvyFQcV

---

Note on the branch name. …-and-split-process-doc is misleading: it names PROCESS.md, which was considered and rejected in favour of AGENTS.md. The name predates the ruling. Not renaming it — that would break the PR history for a cosmetic gain — but a branch name is not a deliverable, and this one describes a mechanism that did not land.
Commit 4 — AGENTS.md preamble cut. The shared file carried six lines explaining its own mechanism, violating the state-don't-explain bar the file itself sets. Cut to three clauses that constrain rather than describe: identical across three repos, the repos are public, the scope bar, plus both pointers as routing. 212 → 187 words, no rule lost. This superseded f01ea43d…, which had been quoted as the byte-identity target throughout this PR and reads exactly as authoritative as the live value. The target is the branch, not any recorded hash.

[github-actions]

🚀 Preview Deployment Update

✅ This PR has been successfully merged into the preview branch.

The preview environment will update shortly at: https://app.preview.trakrf.id

[github-actions]

🚀 Preview Deployment Update

✅ This PR has been successfully merged into the preview branch.

The preview environment will update shortly at: https://app.preview.trakrf.id

[github-actions]

🚀 Preview Deployment Update

✅ This PR has been successfully merged into the preview branch.

The preview environment will update shortly at: https://app.preview.trakrf.id