docs: the public surface stops describing a private workspace - #11
Open
Danny-Devs wants to merge 1 commit into
Open
docs: the public surface stops describing a private workspace#11Danny-Devs wants to merge 1 commit into
Danny-Devs wants to merge 1 commit into
Conversation
Four fixes to what a stranger reads first. The repo is a protocol; its
front pages had been written as if the only readers were its own agents.
ROADMAP's contributing step pointed would-be contributors at
`github.com/Danny-Devs/s402` — a repo this is not. That is the single
place a reader is told where to go, and it sent them elsewhere. It now
matches the idiom the rest of the docs already use.
EVIDENCE.md was an internal work log at the repo root: a branch name, an
absolute filesystem path on a contributor's laptop, a section titled
"Open questions", and an agent defending its own conduct. Nothing in it
is dangerous, which was never the standard — it told a reader evaluating
whether this is a serious protocol that the repo is scratch space. It is
retained in full, verbatim, outside this repo; it is relocated, not
deleted.
Seven `linear.app` links pointed into a private issue tracker. Every one
was a login wall for every reader, and each advertised an internal
tracking number to no benefit. Where the reference carried meaning the
sentence keeps it ("on the v0.4 roadmap", "scoped for a future
release"); where it was pure bookkeeping it is gone.
AGENTS.md told a contributor's agent to escalate to a named person. A
public AGENTS.md addresses whoever shows up, so it now says to open an
issue.
DELIBERATELY KEPT: bare DAN-### references inside docs/adr/ and
typescript/CHANGELOG.md. Those are append-only records and the reference
is provenance — it says which decision produced a line, which is worth
more than the cost of an unresolvable token. Only the dead URLs were
stripped from them.
NOT TOUCHED, needs a human call: LESSONS.md still reads in the first
person as an agent's diary. The content is good and public post-mortems
are a real trust signal, so whether it stays and in whose voice is a
judgment about the project's public character, not a cleanup.
Verified: `git grep linear.app` returns 0; ROADMAP.md and README.md
carry no repo slug but s402-protocol/core plus two external links, both
confirmed publicly readable by unauthenticated fetch (with a known-private
repo as a negative control, which correctly failed); EVIDENCE.md is
untracked; the secrets scan stays clean.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Four fixes to what a stranger reads first. This repo is a protocol; some of its front pages had been written as though the only readers were the people already working on it.
The one that actually loses someone
ROADMAP.md§ How to propose a change pointed contributors atgithub.com/Danny-Devs/s402— a repo this is not. That is the single place a reader is told where to go, and it sent them elsewhere. It now reads[file an issue](https://github.com/s402-protocol/core/issues), matching the idiomdocs/comparison.mdalready used.An internal work log was sitting at the repo root
EVIDENCE.mdwas one contributor's session notes: a branch name, an absolute filesystem path on a laptop, a section headed "Open questions". Nothing in it is sensitive, which was never the standard — it told anyone evaluating whether this is a serious protocol that the root of the repo is scratch space. Removed here; retained in full elsewhere, so this is a relocation rather than a deletion.Dead links into a private tracker
Seven
linear.appURLs acrossdocs/andtypescript/CHANGELOG.mdresolved to a login wall for every reader, and each advertised an internal ticket number to no benefit. All seven are gone. Where the reference carried real meaning the sentence keeps it — "on the v0.4 roadmap", "scoped for a future release" — and where it was pure bookkeeping it is removed.Kept deliberately: bare
DAN-###tokens insidedocs/adr/andtypescript/CHANGELOG.md. Those are append-only records where the token is provenance — it says which decision produced a line. That is worth more than the cost of an unresolvable reference to a reader who was never going to click it. Only the dead URLs were stripped from them.AGENTS.mdnamed a personThe corollary rule told a contributor's agent to escalate to a specific individual. A public
AGENTS.mdaddresses whoever shows up, so it now says to open an issue describing the overlap.Verification
git grep linear.appROADMAP.md/README.mds402-protocol/core, plus two external linksREADME.mdexternal links reachable unauthenticatedDanny-Devs/sui-gas-station✅ ·sweeinc/sweefi✅git ls-files EVIDENCE.mdLink reachability was tested with the git credential helper explicitly disabled, using a known-public repo as a positive control and a known-private one as a negative control. Without the negative control a success would only have proven the tester could read them.
Not addressed here
LESSONS.mdstill reads in the first person, as a session diary rather than a project engineering log. The content is genuinely good and public post-mortems are a real trust signal, so whether it stays — and in whose voice — is a judgment about this project's public character rather than a cleanup. Left for a maintainer.Docs only. No source, tests, or published package contents are touched.
🤖 Generated with Claude Code