docs: track the contributor-essential documentation - #11
Closed
hsusul wants to merge 3 commits into
Closed
Conversation
`cargo fmt --all -- --check` and `cargo clippy -D warnings` both failed on
main under rustc 1.97.1. No source change caused this: `useless_concat` and
`unneeded_struct_pattern` are recent clippy lints, and CI pins nothing.
Three clippy fixes, all in test code and all semantics-preserving:
- codex.rs: two single-argument `concat!(..)` calls collapsed to plain
string literals (clippy::useless_concat).
- ingest_file.rs: `IngestOutcome::Skipped { .. }` -> `IngestOutcome::Skipped`;
it is a unit variant (clippy::unneeded_struct_pattern).
Then `cargo fmt --all`, which rewrapped 18 over-width assertion lines across
the two adapters, adapters/common.rs, and four integration tests. Mechanical
line-wrapping at the 100-column limit only.
No production code touched. Verified green: fmt, clippy (lore-core/lore-ipc
and lore-app), cargo test --locked --all-targets (346 pass / 4 ignored),
no_network_in_archive, no_egress, egress-check.sh, IPC bindings in sync,
npm lint/typecheck/test (148 pass).
Follow-up: pinning the toolchain so this cannot recur.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
CI ran `dtolnay/rust-toolchain@stable` with `cargo clippy -- -D warnings`, so
any new lint in a stable release broke the build on a commit that changed
nothing. That is not hypothetical: it is exactly how main went red under
1.97.1 (previous commit). Pinning turns a toolchain upgrade into an explicit,
reviewable change.
- rust-toolchain.toml pins 1.97.1 with rustfmt/clippy and the minimal
profile. rustup honors it for every cargo invocation, locally and in CI.
- Both workflows now reference dtolnay/rust-toolchain@1.97.1 rather than
@stable, so the runner pre-installs the same compiler rustup would fetch
(the action does not read rust-toolchain.toml — verified against its
README; @1.97.1 is a valid ref).
- scripts/toolchain-pin-check.sh fails if the toml channel, the workflow
action refs, and the active rustc are not all the same version. Wired in
as the first step of the rust-core job, ahead of fmt/clippy. Verified it
passes when aligned and fails when the toml and workflows disagree.
This is not the MSRV. `rust-version = "1.90"` in Cargo.toml still declares the
minimum supported compiler; this pins the one we build and lint with.
Verified: pin check, fmt, clippy (both invocations), cargo test --locked
--all-targets (346 pass / 4 ignored), both workflow files parse as YAML.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
.gitignore contained `*.md` + `/docs/`, so a fresh clone carried exactly one
markdown file: README.md. Meanwhile CLAUDE.md called AGENTS.md "the canonical
contributor guide" and the sync rules said to update the canonical doc in the
same change — none of which a contributor could act on, because none of it was
in the repository.
Now tracked (20 files): AGENTS.md, CLAUDE.md, docs/DOCS_INDEX.md, and
docs/{architecture,agents,development}. These are what someone needs in order
to build correctly and to know which doc a change must update.
Deliberately still local-only, because this repository is public:
docs/product/ (strategy, roadmap, PRD), docs/design/ (unshipped design),
docs/decisions/ (ADRs), docs/research/ (named-competitor analysis), and
RESEARCH_SUMMARY.md. The ignore rules now name these explicitly and say why,
rather than blanket-ignoring every .md. AUDIT_LOG.md, POLISH_LOG.md, and
audit-goal.txt are named too — previously they were only caught by the blanket
rule.
Because the published docs reference the internal ones, DOCS_INDEX.md is split
into "Published in this repository" and "Internal — not published", and the 18
in-prose references across AGENTS.md, CLAUDE.md, the five agent docs, and two
architecture docs are marked *(internal)*. A reference you cannot open is now
labelled as internal by design rather than reading as a broken link.
Verified: all 22 relative links in the tracked set resolve, and none points at
a gitignored path (checked with `git check-ignore`, not just local existence).
Scanned all 20 files for credentials, real user paths, emails, and internal
hosts before committing — none present; the only absolute paths are the
anonymized `/Users/x/proj` in the schema examples.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Owner
Author
|
Closing — the decision is that README.md is the only documentation in this public repository. No docs will be tracked. |
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.
Problem
.gitignorehad*.md+/docs/, so a fresh clone contained exactly one markdown file:README.md. All 34 docs, 6 ADRs,AGENTS.md, andCLAUDE.mdwere untracked local files.That contradicts the repo's own rules.
CLAUDE.mdopens by callingAGENTS.md"the canonical contributor guide," and the sync rules say to update the canonical doc in the same change — neither is actionable when the files don't exist for anyone but the maintainer.What's now tracked (20 files)
AGENTS.md,CLAUDE.md,docs/DOCS_INDEX.md, anddocs/{architecture,agents,development}— what a contributor needs to build correctly and to know which doc a change must update.What stays local, and why
This repository is public. These are deliberately not published:
docs/product/docs/design/docs/decisions/The ignore rules now name these explicitly with the reason, instead of blanket-ignoring every
.md.AUDIT_LOG.md,POLISH_LOG.md, andaudit-goal.txtare named too — previously they were only incidentally caught by the blanket rule.Keeping the map honest
Published docs reference internal ones. Rather than delete that information (it's real and useful to the maintainer), it's labelled:
DOCS_INDEX.mdis split into "Published in this repository" and "Internal — not published", the latter unlinked.AGENTS.md,CLAUDE.md, the five agent docs, and two architecture docs are marked*(internal)*.A reference you can't open now reads as internal by design, not as a broken link.
Verification
git check-ignore, not just local file existence, so this is validated against a fresh clone rather than my working tree./Users/x/projin schema examples, and the only URLs are public vendor docs.Note
Git history is unchanged — these files were never committed before, so nothing sensitive is being retroactively exposed from past commits.
🤖 Generated with Claude Code