You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Phase 1: Inventory, the classification rule, and the docs-link drift guard #1339
1. Inventory every agent-facing file, across every repo in the epic, not just this one: AGENTS.md, CLAUDE.md, .rules/*, .context/* (about 9,900 lines here, 97 committed files under .context/ alone), and the equivalents in website, nemar-observability and docs.
2. Write the classification rule, once. ADR 0057 sets the bar: publish good examples, not a
recipe for attacking the platform. That sorts material into three buckets, and the third one changed
meaning:
Public reference -> docs.nemar.org, public source
Admin-only -> private source (phase 3), served gated
Stays with the code -> ADRs and instructions to an agent editing a given checkout
The old framing's third bucket was "must stay in this repo", which was doing the work of a privacy
control and cannot: staying in this repo is staying public. Anything that needs to be unreadable
goes in bucket two, not bucket three.
The rule has to be operable by someone who is not the person who wrote it. A single fact about
where something runs is usually publishable; an assembled map of host aliases, state paths, cron
windows and deploy mechanism is the artifact that moves.
3. The drift guard. A test here that every docs URL referenced by AGENTS.md and .rules/*
resolves, when a sibling ../docs checkout is present, and skips visibly when it is not. starlight-links-validator already fails the docs build on a broken internal link, so this is the
other direction.
Precedent to copy, including the strict/soft split and the dev ref pairing of ADR 0046: test/docs-auth-contract-drift.test.ts in nemarOrg/website and test/docs-auth-contract.test.ts
in nemarOrg/docs, both added in phase 0. Those are a different guard (they compare contract
literals); this one checks link resolution and does not exist yet.
Acceptance
The inventory names every file and its bucket, and a second person can apply the rule.
The drift guard is red when a referenced docs URL does not resolve, and a visible skip with no
sibling checkout.
An ADR records the rule if the sorting turns out to be contested.
changed the title [-]Phase 1: ADR, inventory, and the drift guard[/-][+]Phase 1: Inventory, the classification rule, and the docs-link drift guard[/+]on Sep 13, 2026
Harm evaluation, as the basis for the classification rule
Calibrated deliberately, per ADR 0057: the repos stay open, a determined reader finds everything,
and the goal is raising the cost of the first step, not secrecy. Where the honest answer is
"hiding this buys nothing", that is said rather than hedged.
Two actors: A, ill-willing, holds public knowledge and may obtain an admin key; B, a
contributor doing PRs, whether naive or hostile.
Tier 1: genuinely amplifying, and the reason this phase exists
1. The Hallu self-deploy is a documented code-execution path. setup() runs git fetch && git reset --hard origin/$ZARR_DRIVER_REF (default main) against this public repo, hourly at :30, and since #1109 that supplies the shell script as well as the
Python driver. So landing a commit on main runs code on the SDSC host within the hour.
This is the single highest-value fact in the public tree. It is not drive-by exploitable: the keep-main and keep-dev rulesets are active, so it needs a merge, not a PR. But the public
material currently hands over the mechanism, the exact state path, the ref, the cron minute, and the
fact that the script redeploys itself.
Split it. The design belongs in public (ADR 0029: Actions cannot finish inside the 120-minute
cap, so conversion runs on a cron host). The assembled operational detail is what moves.
2. The backup destination and cadence are public, and they name where the whole user table lives.
ADR 0004 states hourly plaintext .sql D1 snapshots to the private nemarOrg/nemar-db-backup, with
git history for point-in-time recovery. The repo is private and cannot be enumerated from outside,
so this genuinely leaks something an attacker could not otherwise learn: one GitHub repo holds every
user row, in plaintext, with history. It converts "compromise the platform" into "compromise one
repo".
The decision and its reasoning should stay recorded. The destination naming is the part that
belongs on the private side.
3. The in-progress Infisical migration is public. Branch feature/issue-885-epic-secrets-infisical, issue #885, and planning notes under .context/. An incomplete secrets migration is the one case where a roadmap is genuinely sensitive: it says
which secrets are still in the weaker place and when they will move. This is the highest-value item
to move first, because it expires on its own once the migration completes.
4. Dev is the softest edge, and AGENTS.md says so precisely. Dev D1 shares production users
(roughly 609 real addresses), the nemarDatasets org is shared between prod and dev, and the dev
worker holds a live RESEND_API_KEY.
This one is a real trade rather than a clear move. Published, it prevents accidents, and that is
worth a lot (see B below). Published in detail, it is a map of the softest path. Keep the warning,
move the specifics — which variable, which allowlist, which fence function.
Tier 2: what an admin key buys, and why hiding docs barely helps
An admin or owner key is destructive by design: delete-dataset cascades GitHub repo, S3 objects
and D1; bulk-delete; make-public; doi, which is permanent; notify, which reaches real users.
Owner adds keys create, which mints service-account keys and is therefore persistence, and fleet enforce --bulk, which reaches roughly 785 dataset repos.
Public docs remove some reconnaissance here: ID bands, the S3 layout, which endpoints cascade, which
exemplars are exempt from cleanup. Realistically this is low-value to hide. An attacker holding
an admin key runs nemar admin --help and has the same map in a minute. The control is the key, not
the documentation.
So the useful work in this tier is not classification. It is key hygiene: named per-machine keys
(already true, ADR 0047), revocation cascading to linked credentials, owner-only minting for service
accounts (ADR 0048), and making sure a revoked key dies everywhere at once. Phase 1 should record
that finding and not collect these pages.
Actor B: the contributor
Hostile is largely handled.keep-main and keep-dev are active, so a PR cannot self-merge.
The real fan-out risk is nemarDatasets/.github, where a workflow edit reaches ~785 repos at once
and is discovered at dispatch rather than review (ADR 0020). That is a review-discipline problem in
that repo, not a docs classification problem.
Naive is the likelier harm, and the fix is the opposite of hiding. The documented accidents are
running a dev-side job that emails real people, touching the live nm000103-nm000107, hand-bumping
the version and desyncing the release, and adding a cron to the non-prod set that dispatches real
GitHub work.
Every one of those is prevented by a warning that is currently public. Those warnings must stay
public. Moving them would trade a small reconnaissance gain for a real increase in accidents, which
is a bad trade and worth stating in the rule so nobody "tidies" them behind the gate later.
What stays public, so the rule does not over-collect
ADRs and their reasoning, architecture, contracts, schemas, the API surface, the CLI reference, and
every blast-radius warning. This is the project's value and most of its safety. The rule should be
biased toward publishing.
The rule this produces
Move an item to the private side if it does at least one of:
Names a code-execution or credential path concretely enough to act on: host plus path plus
ref plus cadence.
Names where a credential or a full copy of the data lives.
Describes an incomplete security migration.
Is an assembled operational map rather than a single fact. Assembly is the trigger: that a
converter runs on an SDSC host is publishable; host alias plus state path plus cron window plus
deploy mechanism in one table is not.
Keep it public otherwise. Explicitly keep the accident-preventing warnings, and do not collect
Tier 2 pages, whose control is the key rather than the text.
Expected outcome: a small move. On this evidence it is roughly the two runbook files, the
Infisical planning notes, the backup destination naming, and parts of systems-inventory.md
sections 3 and 5 — not the 97 files under .context/.
Done in #1381 (squashed to fb58aaed on the epic branch).
Three deliverables landed: ADR 0058 (the classification rule, including the half that says what does NOT move), a destination column on .context/README.md classifying all 38 entries at 4 private / 34 public, and test/docs-links.unit.test.ts plus its CI wiring.
Review found the guard was disabled by the same defect it was built to fix. paths-ignore: '*.md' on both workflow triggers matched every root markdown file, so a PR editing only AGENTS.md skipped the Tests workflow entirely, before the new paths filter was evaluated. Confirmed on dev commit 02b42189, a CHANGELOG-only change with no Tests run. Narrowed to CHANGELOG.md.
Also fixed: the scan now asks git grep which tracked files mention the docs host rather than using an allowlist, which raised coverage from a handful to 33 files and picked up the two URLs quoted to users in refusals; anchors and query strings no longer produce false failures; and three paths by which the guard could pass while comparing nothing were closed, one of which went green rather than skipping when the docs repo's only slug: override vanished.
ADR 0058's line figure was wrong on both scope and magnitude and is now measured (19,385 here, about 23,100 across four repos), and its list of what moves names the four files one to one.
Next: phase 2, #1377, the agent retrieval surface.
Activity
[-]Phase 1: ADR, inventory, and the drift guard[/-][+]Phase 1: Inventory, the classification rule, and the docs-link drift guard[/+]neuromechanist commentedon Sep 13, 2026
Harm evaluation, as the basis for the classification rule
Calibrated deliberately, per ADR 0057: the repos stay open, a determined reader finds everything,
and the goal is raising the cost of the first step, not secrecy. Where the honest answer is
"hiding this buys nothing", that is said rather than hedged.
Two actors: A, ill-willing, holds public knowledge and may obtain an admin key; B, a
contributor doing PRs, whether naive or hostile.
Tier 1: genuinely amplifying, and the reason this phase exists
1. The Hallu self-deploy is a documented code-execution path.
setup()runsgit fetch && git reset --hard origin/$ZARR_DRIVER_REF(defaultmain) against thispublic repo, hourly at
:30, and since #1109 that supplies the shell script as well as thePython driver. So landing a commit on
mainruns code on the SDSC host within the hour.This is the single highest-value fact in the public tree. It is not drive-by exploitable: the
keep-mainandkeep-devrulesets are active, so it needs a merge, not a PR. But the publicmaterial currently hands over the mechanism, the exact state path, the ref, the cron minute, and the
fact that the script redeploys itself.
Split it. The design belongs in public (ADR 0029: Actions cannot finish inside the 120-minute
cap, so conversion runs on a cron host). The assembled operational detail is what moves.
2. The backup destination and cadence are public, and they name where the whole user table lives.
ADR 0004 states hourly plaintext
.sqlD1 snapshots to the privatenemarOrg/nemar-db-backup, withgit history for point-in-time recovery. The repo is private and cannot be enumerated from outside,
so this genuinely leaks something an attacker could not otherwise learn: one GitHub repo holds every
user row, in plaintext, with history. It converts "compromise the platform" into "compromise one
repo".
The decision and its reasoning should stay recorded. The destination naming is the part that
belongs on the private side.
3. The in-progress Infisical migration is public. Branch
feature/issue-885-epic-secrets-infisical, issue #885, and planning notes under.context/. Anincomplete secrets migration is the one case where a roadmap is genuinely sensitive: it says
which secrets are still in the weaker place and when they will move. This is the highest-value item
to move first, because it expires on its own once the migration completes.
4. Dev is the softest edge, and
AGENTS.mdsays so precisely. Dev D1 shares production users(roughly 609 real addresses), the
nemarDatasetsorg is shared between prod and dev, and the devworker holds a live
RESEND_API_KEY.This one is a real trade rather than a clear move. Published, it prevents accidents, and that is
worth a lot (see B below). Published in detail, it is a map of the softest path. Keep the warning,
move the specifics — which variable, which allowlist, which fence function.
Tier 2: what an admin key buys, and why hiding docs barely helps
An admin or owner key is destructive by design:
delete-datasetcascades GitHub repo, S3 objectsand D1;
bulk-delete;make-public;doi, which is permanent;notify, which reaches real users.Owner adds
keys create, which mints service-account keys and is therefore persistence, andfleet enforce --bulk, which reaches roughly 785 dataset repos.Public docs remove some reconnaissance here: ID bands, the S3 layout, which endpoints cascade, which
exemplars are exempt from cleanup. Realistically this is low-value to hide. An attacker holding
an admin key runs
nemar admin --helpand has the same map in a minute. The control is the key, notthe documentation.
So the useful work in this tier is not classification. It is key hygiene: named per-machine keys
(already true, ADR 0047), revocation cascading to linked credentials, owner-only minting for service
accounts (ADR 0048), and making sure a revoked key dies everywhere at once. Phase 1 should record
that finding and not collect these pages.
Actor B: the contributor
Hostile is largely handled.
keep-mainandkeep-devare active, so a PR cannot self-merge.The real fan-out risk is
nemarDatasets/.github, where a workflow edit reaches ~785 repos at onceand is discovered at dispatch rather than review (ADR 0020). That is a review-discipline problem in
that repo, not a docs classification problem.
Naive is the likelier harm, and the fix is the opposite of hiding. The documented accidents are
running a dev-side job that emails real people, touching the live
nm000103-nm000107, hand-bumpingthe version and desyncing the release, and adding a cron to the non-prod set that dispatches real
GitHub work.
Every one of those is prevented by a warning that is currently public. Those warnings must stay
public. Moving them would trade a small reconnaissance gain for a real increase in accidents, which
is a bad trade and worth stating in the rule so nobody "tidies" them behind the gate later.
What stays public, so the rule does not over-collect
ADRs and their reasoning, architecture, contracts, schemas, the API surface, the CLI reference, and
every blast-radius warning. This is the project's value and most of its safety. The rule should be
biased toward publishing.
The rule this produces
Move an item to the private side if it does at least one of:
ref plus cadence.
converter runs on an SDSC host is publishable; host alias plus state path plus cron window plus
deploy mechanism in one table is not.
Keep it public otherwise. Explicitly keep the accident-preventing warnings, and do not collect
Tier 2 pages, whose control is the key rather than the text.
Expected outcome: a small move. On this evidence it is roughly the two runbook files, the
Infisical planning notes, the backup destination naming, and parts of
systems-inventory.mdsections 3 and 5 — not the 97 files under
.context/.neuromechanist commentedon Sep 13, 2026
Done in #1381 (squashed to
fb58aaedon the epic branch).Three deliverables landed: ADR 0058 (the classification rule, including the half that says what does NOT move), a destination column on
.context/README.mdclassifying all 38 entries at 4 private / 34 public, andtest/docs-links.unit.test.tsplus its CI wiring.Review found the guard was disabled by the same defect it was built to fix.
paths-ignore: '*.md'on both workflow triggers matched every root markdown file, so a PR editing onlyAGENTS.mdskipped the Tests workflow entirely, before the new paths filter was evaluated. Confirmed on dev commit02b42189, a CHANGELOG-only change with no Tests run. Narrowed toCHANGELOG.md.Also fixed: the scan now asks
git grepwhich tracked files mention the docs host rather than using an allowlist, which raised coverage from a handful to 33 files and picked up the two URLs quoted to users in refusals; anchors and query strings no longer produce false failures; and three paths by which the guard could pass while comparing nothing were closed, one of which went green rather than skipping when the docs repo's onlyslug:override vanished.ADR 0058's line figure was wrong on both scope and magnitude and is now measured (19,385 here, about 23,100 across four repos), and its list of what moves names the four files one to one.
Next: phase 2, #1377, the agent retrieval surface.