Skip to content

Releases: SpillwaveSolutions/docgen

v1.1.0 — incremental regeneration + parallel execution

17 Apr 21:41
@RichardHightower RichardHightower
v1.1.0
a1487b3

Choose a tag to compare

View all tags
v1.1.0 — incremental regeneration + parallel execution Latest
Latest

Incremental regeneration, parallel execution, and UX polish.

Measured results

Measured on `tests/fixtures/tiny_repo`:

Before v1.1 After v1.1
Cold run (tiny_repo) ~26 min, $4.57, 60 calls ~16 min, $3.98, 58 calls
Warm run (no source changes) ~26 min, $4.57 (full regen) <1 s, $0.00, 0 calls
Single-file edit Full regen Only that file's class + package + system rollup

The 37% cold speedup comes from `parallelism=3` actually running three LLM calls concurrently per stage in the per-file / per-class / per-package loops. The warm-run drop is incremental regeneration refusing to redo work when inputs are unchanged.

Added

  • Incremental regeneration. Every generated artifact records the SHA1 of its inputs in `.designdoc-state.json`. Subsequent runs skip unchanged work:
    • Stage 2/3 skip files whose source hash matches the previous run.
    • Stage 4/5/7 skip rollups whose input-class-doc hashes are unchanged.
    • Stage 6 uses a tech-debt manifest hash to skip cross-ref research.
  • Parallel per-artifact execution. Stages 2, 3, 4, and 6 now run their per-file / per-class / per-package / per-topic loops under an `asyncio.Semaphore(parallelism)` gate. Default parallelism is 3.
  • `--parallelism N` CLI flag on `designdoc generate` and `designdoc resume` (overrides `config.parallelism`).
  • Progress logging. Orchestrator emits `[N/9] stage x starting` and `[N/9] stage x done in Xs` lines so long runs are observable.
  • `designdoc status` cache-readiness hints. Reports `prev_hashes` and `rollup_hashes` counts so users can see what will skip on the next run.
  • Incremental-regeneration benchmark (`tests/e2e/test_incremental_bench.py`) — real-API cold/warm run against `tiny_repo`; gated on `claude` CLI login.

Changed

  • README documents measured parallel speedup and incremental behavior.
  • Config fields `include_languages`, `output_dir`, and `diagram_format` are now wired through to the pipeline (previously declared but unused).
  • CI workflow runs on `feat/`, `fix/`, `bench/`, `chore/`, `docs/`, and `test/` branches.

Fixed

  • `--config` path and MCP server list are now passed through to every stage.
  • Mermaid double-append bug in the Stage 5 rollup path.
  • CI `mmdc` invocation now runs with `--no-sandbox` so Puppeteer works on GitHub Actions runners.
  • Three ultrareview findings on option passthrough.

Docs

  • Authentication uses the local `claude` CLI (Pro/Max subscription) as SDK transport. No `ANTHROPIC_API_KEY` required for normal use.

Full changelog: v1.0.0...v1.1.0 · CHANGELOG.md

Assets 2
Loading

v1.0.0 — first feature-complete release

17 Apr 21:41
@RichardHightower RichardHightower
v1.0.0
2dd9cf2

Choose a tag to compare

View all tags
v1.0.0 — first feature-complete release

First feature-complete release. Implements the 9-stage harness-engineered documentation pipeline described in plans/2026_04_16_designdoc_gen_v1.md.

Retroactive tag — the release was never formally tagged at the time. See CHANGELOG.md for full details.

Core harness (the invariants)

  • 3-attempt doer/checker loop (MAX_ATTEMPTS = 3, the canonical retry cap). A constitutional guard test prevents the constant from ever being exposed as user config.
  • Checker isolation. The doer's scratchpad never reaches the checker — the checker sees source + doer final output + its own system prompt, nothing else.
  • Schema-validated verdicts. Malformed JSON produces a synthetic fail verdict; never silent success.
  • Budget cap. CostAccumulator raises BudgetExceededError when exceeded; persisted to state so resumed runs honor the remaining budget.
  • Resumable state. Each completed stage writes a checkpoint to <output>/.designdoc-state.json; a crashed run resumes from the last completed stage.
  • HIL fallback. Unresolved disputes ship with inline <!-- HIL: HIL-XXX --> comments + YAML ledger rather than blocking the pipeline.

Nine pipeline stages

  • Stage 0 — Language discovery + file tree (no LLM).
  • Stage 1 — AST-lite signatures (Python `ast`; TS/JS regex fallback).
  • Stage 2 — Per-file summary (LLM doer + Pydantic schema checker).
  • Stage 3 — Class docs (LLM doer + LLM quality checker — first LLM-on-LLM stage).
  • Stage 4 — Package README rollups.
  • Stage 5 — Mermaid diagrams via two-checker loop: deterministic `mmdc` syntax check plus an LLM semantic check. Both must pass.
  • Stage 6 — Tech-debt researcher with Perplexity / Context7 MCP cross-ref.
  • Stage 7 — `SYSTEM_DESIGN.md` + `ARCHITECTURE.md` rollup.
  • Stage 8 — Finalize: README TOC + `hil-issues.yaml` emit.

CLI and plugin

  • Typer CLI: `generate`, `resume`, `status`, `resolve`.
  • `/designdoc` Claude Code slash command.
  • HIL walker CLI helpers.
Loading