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
9 small, independent findings from the 2026-07 comprehensive audit, grouped so they ship as one PR and pay one CI run rather than 9.
Everything here is medium/low severity — confirmed critical and high findings are filed as their own tickets. Land the batch together where you can; partial PRs are acceptable but cost a CI run each.
Items
README.md:278 — The Usage section documents 8 commands (chat, run, goal, monitor, fleet, graph, init, tools, stats). The binary exposes 25 (main.rs:183-460). Undocumented in README: auth, resume, mcp, connect, usage, cloud, telemetry, observe, memory, scripts, storage, arena, version. auth is the sharp one — README.md:148-149 describes the credential chain as ending in ~/.stella/credentials.toml and never names the command that writes it. resume is the second — durable sessions are a headline feature (main.rs:258-262) that a README-only reader never learns exists. This matters more than usual because release.yml:132 copies README.md into every release tarball, so it is the offline manual users actually get. Fix: Add a compact command-index table to the Usage section — one row per subcommand, one line each, linking to the matching stella.oxagen.sh/docs/commands/<name> page (all 21 of which already exist under stella-docs/content/docs/commands/, verified). That closes the gap without growing the README much.
docs/adr/0009-enum-freeze-resolutions.md:61 — ADR 0009 cites context-prs-spec.md:304 by absolute line number. Markdown line numbers are not a stable address — any edit above line 304 in a 544-line document silently repoints the citation at unrelated prose, with nothing in CI to catch it. The same pattern appears in docs/design/semantic-resolution-bridge.md:26 and :196, which cite docs/papers/stella-defensible-position.md:590-592. The repo already has the correct idiom everywhere else: Rust doc comments cite docs/design/storage-map.md §8 and exploration-sharing.md §3b by section, which survives editing. This finding constrained my own fixes — it is why I preserved line counts in context-prs-spec.md rather than restructuring its header. Fix: Re-anchor the three line-number citations to section references (context-prs-spec.md §7 etc.) and add a sentence to docs/README.md's existing citation paragraph forbidding line-number citations. I did not do it because verifying which section line 304 and lines 590–592 currently fall in, and that the surrounding ADR argument still holds under a section-level citation, is a substantive editorial judgment about ratified decisions that belongs to the ADR owner, not an auditor.
stella-docs/package.json:2 — One artifact carries three names: the directory is stella-docs/, the pnpm package is stella-cli-docs, and prose calls it "the docs site". Worse, stella-docs/ sits alongside fifteen genuine stella-* crates and is indistinguishable from them at ls — which is why README.md:538, CONTRIBUTING.md:118, and AGENTS.md:205 all have to assert "Fifteen crates" and then separately explain that the sixteenth stella-* directory is not one. Root package.json's scripts all read pnpm --filter stella-cli-docs …, so the mismatch is load-bearing in three places. Fix: Covered by the hosting recommendation: rename the directory to website/ and the package to website in the same PR. Not done here because it requires coordinated edits to pnpm-workspace.yaml, root package.json, ci.yml, and docs.yml — all outside my ownership — and a half-done rename is worse than none.
README.md:67 — The from-source instructions say "Rust 1.90+ (via rustup)", which is the MSRV from Cargo.toml's rust-version and correct for cargo install --git. But rust-toolchain.toml pins channel = "1.97.0", so a git clone && cargo build actually makes rustup fetch 1.97.0 — a several-hundred-megabyte surprise the README does not mention. CONTRIBUTING.md:43 handles this correctly ("the toolchain is pinned in rust-toolchain.toml, so rustup will fetch the right one automatically"); the README does not. Fix: Add the same parenthetical to README.md's Prerequisites bullet. Left alone because README.md showed concurrent modification by another agent during this session (the fleet-mode and /pipeline hunks appeared mid-audit), and I confined my README edits to the tool table to avoid an overlapping-hunk collision.
README.md:615 — There is no CHANGELOG.md at the repository root. For a Rust project distributed by tag, curl | sh, and Homebrew, the conventional place a user checks before upgrading is the repo root; here the only narrative history is a single-version MDX page on a website. GitHub Releases carry the commit log, but a commit log is not a changelog. Fix: Add a keep-a-changelog CHANGELOG.md and have the release-notes.mdx page be its rendered view, so the two cannot diverge. Not fixed: authoring the historical entries requires the same unverifiable synthesis I declined for release-notes.mdx.
docs/adaptive-context/phase-0-baseline.md:1(obsolete — resolved by docs(adaptive-context): fresh spec + four-phase plan, retire the 2026-07 bundle #692, see comment) — Two different directories are named adaptive-context: docs/adaptive-context/ (one file, the frozen Phase 0 baseline) and docs/design/adaptive-context/ (three files, the lifecycle spec and build prompt). Independently, docs/design/adaptive-context-lifecycle.md and docs/design/adaptive-context/stella-adaptive-context-lifecycle.md are near-identical titles for a superseded draft and its successor. Both pairs are correctly disambiguated by prose banners once you open the files — but the tree alone actively misleads, and a fd adaptive-context returns four plausible-looking answers to "where is the spec?". Fix: Fold docs/adaptive-context/phase-0-baseline.md into docs/design/adaptive-context/ and rename docs/design/adaptive-context-lifecycle.md to something that reads as superseded (e.g. adaptive-context-lifecycle.superseded.md). Not fixed: docs/README.md:19 links the current path, docs/design/adaptive-context-lifecycle.md is cross-linked from its successor, and moving files under docs/ risks breaking the §-citations from Rust doc comments that I cannot re-verify without cargo.
stella-docs/README.md:101 — No deploy step for the docs site exists in the repository. docs.yml only typechecks and builds; production is wired up in the Vercel dashboard, outside version control. The file states this plainly ("A contributor therefore cannot tell from the repo how a merged docs change reaches stella.oxagen.sh, and nobody but the account holder can redeploy it"), which is admirable candor but not a mitigation. For an OSS project this is a bus-factor-1 hole in the only user-facing documentation channel — all crates are publish=false, so there is no docs.rs fallback if the site goes dark. Fix: Add a production deploy job to .github/workflows/docs.yml gated on push: branches: [main], using a VERCEL_TOKEN repo secret and a GitHub production environment so the deployment is auditable and revocable. Then delete the "No deploy step lives in this repository" paragraph. I did not do this: it requires creating a repository secret and touching .github/, which I do not own.
stella-docs/README.md:12 — docs/brand/ and stella-docs/public/brand/ are independent copies of the same marks that have already diverged — stella-docs/README.md:12-18 documents that stella-logo-light.svg differs in fill between the two, that only stella-logo-{dark,light}.svg and public/icons/ are referenced from src/, and that the rest of public/brand/ is unreferenced. The candor is good; the state is still a live drift generator, and the README's own advice ("delete one copy and point at the other") is not actually achievable, because Next.js cannot serve assets from outside the app's public/ directory. Fix: Make docs/brand/ canonical and generate stella-docs/public/brand/ from it in a prebuild step (or a committed copy job with a CI diff check), and delete the unreferenced files under public/brand/. Not fixed: deleting or moving SVGs risks breaking both the README's sources and the site build, and I cannot run the Next build to verify.
stella-docs/src/app/sitemap.ts:8 — Every page's sitemap entry is emitted with lastModified: new Date() — the build timestamp. The sitemap therefore tells crawlers all 76 URLs changed on every deploy, which is exactly the signal that causes search engines to stop trusting lastModified and fall back to their own heuristics. changeFrequency is likewise a flat "weekly" for a 0.5.x product page and a stable ADR-derived principles page alike. Fix: Use the page's file mtime or the git commit date for lastModified. Not fixed: this is a TypeScript change I cannot compile-verify, and the audit rules correctly forbid unverifiable code edits.
Filed by the comprehensive codebase audit, 2026-07. Put Closes #<this issue> in the PR description and as a commit trailer when the batch lands.
Batched cleanup —
area:docs9 small, independent findings from the 2026-07 comprehensive audit, grouped so they ship as one PR and pay one CI run rather than 9.
Everything here is medium/low severity — confirmed critical and high findings are filed as their own tickets. Land the batch together where you can; partial PRs are acceptable but cost a CI run each.
Items
README.md:278— The Usage section documents 8 commands (chat, run, goal, monitor, fleet, graph, init, tools, stats). The binary exposes 25 (main.rs:183-460). Undocumented in README:auth,resume,mcp,connect,usage,cloud,telemetry,observe,memory,scripts,storage,arena,version.authis the sharp one — README.md:148-149 describes the credential chain as ending in~/.stella/credentials.tomland never names the command that writes it.resumeis the second — durable sessions are a headline feature (main.rs:258-262) that a README-only reader never learns exists. This matters more than usual because release.yml:132 copies README.md into every release tarball, so it is the offline manual users actually get.Fix: Add a compact command-index table to the Usage section — one row per subcommand, one line each, linking to the matching
stella.oxagen.sh/docs/commands/<name>page (all 21 of which already exist under stella-docs/content/docs/commands/, verified). That closes the gap without growing the README much.docs/adr/0009-enum-freeze-resolutions.md:61— ADR 0009 citescontext-prs-spec.md:304by absolute line number. Markdown line numbers are not a stable address — any edit above line 304 in a 544-line document silently repoints the citation at unrelated prose, with nothing in CI to catch it. The same pattern appears in docs/design/semantic-resolution-bridge.md:26 and :196, which citedocs/papers/stella-defensible-position.md:590-592. The repo already has the correct idiom everywhere else: Rust doc comments citedocs/design/storage-map.md §8andexploration-sharing.md §3bby section, which survives editing. This finding constrained my own fixes — it is why I preserved line counts in context-prs-spec.md rather than restructuring its header.Fix: Re-anchor the three line-number citations to section references (
context-prs-spec.md §7etc.) and add a sentence to docs/README.md's existing citation paragraph forbidding line-number citations. I did not do it because verifying which section line 304 and lines 590–592 currently fall in, and that the surrounding ADR argument still holds under a section-level citation, is a substantive editorial judgment about ratified decisions that belongs to the ADR owner, not an auditor.stella-docs/package.json:2— One artifact carries three names: the directory isstella-docs/, the pnpm package isstella-cli-docs, and prose calls it "the docs site". Worse,stella-docs/sits alongside fifteen genuinestella-*crates and is indistinguishable from them atls— which is why README.md:538, CONTRIBUTING.md:118, and AGENTS.md:205 all have to assert "Fifteen crates" and then separately explain that the sixteenth stella-* directory is not one. Root package.json's scripts all readpnpm --filter stella-cli-docs …, so the mismatch is load-bearing in three places.Fix: Covered by the hosting recommendation: rename the directory to website/ and the package to website in the same PR. Not done here because it requires coordinated edits to pnpm-workspace.yaml, root package.json, ci.yml, and docs.yml — all outside my ownership — and a half-done rename is worse than none.
README.md:67— The from-source instructions say "Rust 1.90+ (via rustup)", which is the MSRV from Cargo.toml's rust-version and correct forcargo install --git. But rust-toolchain.toml pins channel = "1.97.0", so agit clone && cargo buildactually makes rustup fetch 1.97.0 — a several-hundred-megabyte surprise the README does not mention. CONTRIBUTING.md:43 handles this correctly ("the toolchain is pinned in rust-toolchain.toml, so rustup will fetch the right one automatically"); the README does not.Fix: Add the same parenthetical to README.md's Prerequisites bullet. Left alone because README.md showed concurrent modification by another agent during this session (the fleet-mode and /pipeline hunks appeared mid-audit), and I confined my README edits to the tool table to avoid an overlapping-hunk collision.
README.md:615— There is no CHANGELOG.md at the repository root. For a Rust project distributed by tag,curl | sh, and Homebrew, the conventional place a user checks before upgrading is the repo root; here the only narrative history is a single-version MDX page on a website. GitHub Releases carry the commit log, but a commit log is not a changelog.Fix: Add a keep-a-changelog CHANGELOG.md and have the release-notes.mdx page be its rendered view, so the two cannot diverge. Not fixed: authoring the historical entries requires the same unverifiable synthesis I declined for release-notes.mdx.
docs/adaptive-context/phase-0-baseline.md:1fd adaptive-contextreturns four plausible-looking answers to "where is the spec?".Fix: Fold docs/adaptive-context/phase-0-baseline.md into docs/design/adaptive-context/ and rename docs/design/adaptive-context-lifecycle.md to something that reads as superseded (e.g. adaptive-context-lifecycle.superseded.md). Not fixed: docs/README.md:19 links the current path, docs/design/adaptive-context-lifecycle.md is cross-linked from its successor, and moving files under docs/ risks breaking the §-citations from Rust doc comments that I cannot re-verify without cargo.
stella-docs/README.md:101— No deploy step for the docs site exists in the repository. docs.yml only typechecks and builds; production is wired up in the Vercel dashboard, outside version control. The file states this plainly ("A contributor therefore cannot tell from the repo how a merged docs change reaches stella.oxagen.sh, and nobody but the account holder can redeploy it"), which is admirable candor but not a mitigation. For an OSS project this is a bus-factor-1 hole in the only user-facing documentation channel — all crates are publish=false, so there is no docs.rs fallback if the site goes dark.Fix: Add a production deploy job to .github/workflows/docs.yml gated on
push: branches: [main], using aVERCEL_TOKENrepo secret and a GitHubproductionenvironment so the deployment is auditable and revocable. Then delete the "No deploy step lives in this repository" paragraph. I did not do this: it requires creating a repository secret and touching .github/, which I do not own.stella-docs/README.md:12— docs/brand/ and stella-docs/public/brand/ are independent copies of the same marks that have already diverged — stella-docs/README.md:12-18 documents that stella-logo-light.svg differs in fill between the two, that only stella-logo-{dark,light}.svg and public/icons/ are referenced from src/, and that the rest of public/brand/ is unreferenced. The candor is good; the state is still a live drift generator, and the README's own advice ("delete one copy and point at the other") is not actually achievable, because Next.js cannot serve assets from outside the app's public/ directory.Fix: Make docs/brand/ canonical and generate stella-docs/public/brand/ from it in a prebuild step (or a committed copy job with a CI diff check), and delete the unreferenced files under public/brand/. Not fixed: deleting or moving SVGs risks breaking both the README's
stella-docs/src/app/sitemap.ts:8— Every page's sitemap entry is emitted withlastModified: new Date()— the build timestamp. The sitemap therefore tells crawlers all 76 URLs changed on every deploy, which is exactly the signal that causes search engines to stop trusting lastModified and fall back to their own heuristics. changeFrequency is likewise a flat "weekly" for a 0.5.x product page and a stable ADR-derived principles page alike.Fix: Use the page's file mtime or the git commit date for lastModified. Not fixed: this is a TypeScript change I cannot compile-verify, and the audit rules correctly forbid unverifiable code edits.
Filed by the comprehensive codebase audit, 2026-07. Put
Closes #<this issue>in the PR description and as a commit trailer when the batch lands.