The spec/plan lifecycle is a fixed plugin convention (skills/docs/conventions.md, sections File layout + Lifecycle). Restating it here is a drift vector. Remove the restated sentence and enforce the git-ignored model with a project-local docs/.gitignore.
The home index and every page breadcrumb link a project root
`<a href="/<slug>/">`, but the router declared only `/`, `/assets/theme.css`,
and the `/{slug}/{*page}` catch-all (which requires a concrete page segment),
so every project-root link 404'd. Add a `/{slug}/` route and a project_index
handler that renders a landing page listing the project's sections and pages
(unknown slug -> 404); the index and breadcrumb root links are now live.
RED-first via the debug skill: tests/e2e.rs
`project_root_resolves_to_landing_with_section_nav` (a GET to /aura/ asserting
200 + the section/page nav) failed 404 before the fix, passes after.
cargo test green (42); clippy clean.
Architect drift review (0060fea..HEAD) against the five domain invariants and
the cycle spec. What holds: read-only Gitea access (the Fetcher exposes no
write path); whitelist + traversal refusal (config::resolve, e2e-pinned); the
single docs-root join shared by serve and check, so check validates exactly
what serve fetches.
Drift resolved in iter 0001.tidy (preceding commit): the missing registry.toml,
the cache-before-fetch data-flow, and the unescaped registry slug/page.
Ratified (carry-on, not fixed this cycle, each tracked as a follow-up issue):
- The render directive-expansion seam is conceptual (a comment), not an AST
walk step. For the walking skeleton (code + table are native Markdown) a
no-op seam needs no code; it materialises when code-include lands.
- GiteaClient's 404->NotFound status mapping is covered by the gated live
smoke's happy path, not a unit test of the 404 branch.
No regression scripts are configured (CLAUDE.md project facts), so the
architect is the sole drift gate; its What holds is non-empty (review
confirmed). Retires the cycle's spec and plan per the lifecycle convention.
closes#1
Resolves the actionable drift the cycle-close architect review found:
- Ship registry.toml (the spec's acceptance artifact) for aura + data-server,
so `docsite serve`/`check` run out of the box — the headline live-render was
not runnable as shipped without it.
- Cache before fetch: the page handler now resolves the branch SHA, serves
from cache on a hit, and only fetches the source on a miss (the spec
data-flow). The pre-tidy handler always fetched, paying a wasted Gitea read
on every cache hit. A new e2e test (a counting fetcher) pins that a second
request serves from cache without re-fetching.
- Escape the registry slug/page in nav_html's href and the index links —
operator-trusted data, but consistent with the documented no-injection
invariant and the rest of the shell (which already escaped).
cargo test green (41: 32 lib + 8 e2e + 1 gated live smoke); clippy clean.
refs #1
The first runnable DocSite server (plan docs/plans/0001-walking-skeleton.md):
`docsite serve` renders the published docs of aura and data-server live from
their Gitea main revisions, dark-themed, navigated from the DocSite-owned
whitelist registry; `docsite check` validates every nav reference against the
live sources with an exit code. Built across nine TDD tasks — config (registry
whitelist + traversal guard), gitea read-only client (Fetcher trait, injected
for offline tests), render (comrak GFM + syntect), theme (embedded dark CSS +
shell), revision-keyed cache, reference validator, axum server, main wiring.
All five domain invariants land: read-only Gitea access via the Fetcher trait;
single source of truth via the (repo,path,sha) cache; reference integrity
detected (check + a fail-loud render-time error block) never enforced;
whitelist publishing with path-traversal refusal; the closed directive
vocabulary's no-op expansion seam reserved in render.
Verification (run by the orchestrator): cargo build green; cargo test green —
40 tests (32 lib unit + 7 e2e via an injected MockFetcher + 1 gated live smoke
that reached the real Gitea this run); cargo clippy --all-targets -D warnings
clean.
Held quality findings (plan-prescribed / plan-deferred, not defects; tracked
as follow-up issues): nav_html interpolates the registry slug/page into the
href unescaped (operator-trusted registry — latent, not a live vector);
GiteaClient's 404->NotFound status mapping (the invariant-3 broken-reference
signal) is covered only by the gated live smoke's happy path, not a unit test.
Resolved API deviations from the plan text (newer crate versions): reqwest
0.13 renamed feature rustls-tls -> rustls; comrak 0.52 deprecated `Plugins`
(used `comrak::options::Plugins`); axum 0.8 capture syntax `/{slug}/{*page}`.
refs #1
The bite-sized implementation plan for the walking skeleton (parent spec
docs/specs/0001-walking-skeleton.md): nine TDD-structured tasks — scaffold,
config, gitea client, render, theme, cache, check, server, and main wiring —
building the live-render server for aura + data-server docs from Gitea main.
src/lib.rs registers modules incrementally so the lib compiles after every
task; main stays a stub until the final wiring task.
refs #1
The walking-skeleton design spec: live-render aura + data-server docs from
Gitea main, dark-themed, navigation from a DocSite-owned whitelist registry,
with the code + table render directives. Source stays once on the Gitea
host; DocSite holds only a revision-keyed cache and never writes to a source.
grounding-check returned BLOCK (greenfield: a first spec has no existing
tests to ground against); user overrode after the one substantial external
assumption — the source files present on the foreign repos' main — was
verified (aura a517899, data-server 694f96f). Decision log on the issue.
refs #1
Single-source-of-truth LAN documentation server: renders each project's
docs live from its canonical Gitea repository (pushed main), with one
consistent theme, holding no content copy and never writing to a source
repo. Sources are fetched via Gitea's read-only raw/API; DocSite holds
only a revision-keyed cache.
Lays the project shell — CLAUDE.md (orchestrator discipline, domain
invariants, skills project facts), a minimal Cargo package, .gitignore —
so the first cycle (the walking skeleton) can be specced and implemented
on top.
Brummel