corvus
closed delivers ADR 0003: The documentation site and the milestone pages synced 21 Oct 2026, 01:52 UTC milestone in GitLab

Documentation site

The documentation of corvus becomes a public site at the.corvus.observer: the ADRs, and one page per milestone that tells where its delivery stands. Each milestone page is a generated data file plus this kind of narrative, refreshed by the operator about once a day through a merge request. Done when the site is live, the existing milestones render with their narrative and real data, and a sync has gone from the skill to a merged MR and a new sync time on the page.

24 issues in the path · 24 closed

  • Done 24
  • In review 0
  • Waiting 0

Path

The first phase lays the plumbing and the skeleton: the plan skill records the order of work in the issues themselves, the milestone skill reads it, and the site renders the ADRs and the shape of a milestone page from a fixture. The second phase makes it real: the sync script and skill, the bucket and hostname in tofu, the hardening of the GitLab projects, and the pipeline that publishes. The third phase backfills the milestones that predate all this, proves the whole path once end to end, and writes the runbook.

Phase 1

  1. 01
    plan records dependencies as references and phase labels agents#6 closed
    agents!2 merged
  2. 02
    milestone orders by the Depends on references agents#7 closed
    agents!2 merged
  3. 09
    Hugo skeleton and theme rendering the ADRs docs#3 closed
    docs!11 merged docs!5 merged docs!2 merged
  4. 10
    milestone page: data schema, narrative and template docs#4 closed
    docs!11 merged docs!5 merged docs!2 merged
  5. 11
    plan scaffolds the milestone narrative agents#8 closed
    agents!2 merged

Phase 2

  1. 04
    Python package, GitLab client and pytest in CI agents#12 closed
    agents!2 merged
  2. 05
    plan in Python with tests agents#13 closed
    agents!2 merged
  3. 06
    sync and order in Python with tests agents#14 closed
    agents!2 merged
  4. 12
    sync script: fetch milestones and write the data files agents#9 closed
    agents!2 merged
  5. 13
    sync skill: worktree, MR and drift report agents#10 closed
    agents!2 merged
  6. 18
    R2 bucket and custom domain for the site platform#9 closed
    platform!1 merged
  7. 19
    pipeline: build on MR, publish to R2 on main docs#5 closed
    docs!2 merged
  8. 23
    project and group settings: expose only what corvus uses platform#10 closed
    platform!1 merged

Phase 3

  1. 03
    backfill dependency references and phase labels of the existing milestones agents#11 closed
    closed, no merged MR
  2. 14
    narratives of the existing milestones docs#6 closed
    docs!2 merged
  3. 20
    verification: the site is live and a sync is published docs#7 closed
    closed, no merged MR
  4. 21
    runbook: publish the site and run the daily sync docs#8 closed
    docs!12 merged

Open questions

Whether the sync should also refresh a closed milestone on demand, or only the ones whose file still says active. Counters from the old setup (services still on the previous host) were left out; they can join the narrative frontmatter later as declared commands.

Deviations and noise

GitLab Free has no blocking issue links, found on the first run of the plan script. The order of work moved to the “Depends on” section of each issue as references, and the ADR was amended in the same milestone. The three milestones that existed had prose dependencies; every section was rewritten by hand during the backfill. The lint milestone’s docs pipeline issue is not in yet, so the pipeline here carries the workflow rules itself, the same way platform does. The shell scripts of the first five agents issues were replaced by the Python package before they reached main.

The first publish needed four fixes that were not planned, each one an issue and a merged MR of its own. Two in the publish job: the rclone image’s entrypoint swallowed the script, and the scheme of the endpoint URL split rclone’s connection string, so the remote moved to environment variables. One in platform: R2 answered 404 on directory paths, so a transform rule in Cloudflare resolves them to index.html. One in the site: Cloudflare caches CSS at the edge in front of the bucket but not HTML, so a publish served new pages with the previous stylesheet until the stylesheet got a fingerprinted URL.

Found on the way

  1. 07
    next lists a merge request once per issue it closes agents#15 closed
    agents!3 merged
  2. 08
    sync lists merge requests that mention an issue as its merge requests agents#16 closed
    agents!4 merged
  3. 15
    site publish job fails: rclone image entrypoint swallows the script docs#9 closed
    docs!3 merged
  4. 16
    site publish job fails: the endpoint URL breaks the rclone connection string docs#10 closed
    docs!4 merged
  5. 17
    milestone page: a progress bar of what is done docs#11 closed
    docs!6 merged
  6. 22
    the site serves a stale stylesheet after a publish docs#12 closed
    docs!7 merged
  7. 24
    the site answers 404 on directory paths: R2 does not serve index.html platform#11 closed
    platform!2 merged

Out of scope

Previews per merge request, and Cloudflare Access in front of the site: the group is public, and the site exposes nothing the repos do not.

Timeline

Decided, planned and started on 2026-10-20, in one day. The plan found the licensing limit on issue links the same afternoon, and the scripts moved to Python with tests before the first merge. The site went live the same evening: the merge of the Hugo site and pipeline was followed by the four fixes above, the first sync published from the skill to the page, and a progress bar on every milestone. Closed the same night: the verification ticked every item of its checklist in a comment, the runbook landed, and the next sync moved the milestone to the archive.