Context
PR #37 refactored Tilth to a prompt-driven core (evaluator-only gate; features authored as markdown under <repo>/.tilth/tasks/ instead of an interview-generated prd.json; no prep-feature, no codified ruff/pytest validators, no self-improve step). The README was fully rewritten in that PR and is the current source of truth for the run flow. The docs/ site was intentionally deferred — it still describes the old two-step prep-feature → run flow with validators, prd.json, seed-meta, and self-improve.
This issue tracks bringing docs/ back in line. Approach: diff-driven — work from #37's commits (b431215, e57b0ea, a5496e2) and the rewritten README, page by page.
Structural changes
Page rewrites (by amount of stale content)
Heavy (the prep-feature/validator narrative is the backbone):
Light:
Diagrams to regenerate (via docs/assets/IMAGE_STYLE.md)
The README's two images (brain-hands-session.png, session-render.png) are still accurate. These four are not:
| Image |
Page |
Fix |
harness-loop.jpg |
index.md |
drop the validators box + "Fails" path; flow is task → worker → evaluator → commit, only "Rejects" remains |
per-task-lifecycle.jpg |
running-the-demo.md |
6 boxes → 4 (Prompt, Tool Loop, Evaluator, Commit); remove VALIDATORS + SELF-IMPROVE and the validator_failed feedback curve |
session-end.jpg |
running-the-demo.md |
drop proposed-learnings.md; artifacts are events.jsonl, summary.json, checkpoint.json, task-status.json |
session-layout.png |
running-the-demo.md, session-layout.md |
prd.json → task-status.json; tasks live in the repo's .tilth/tasks/, not under sessions/<id>/ |
Done when
uv run --extra docs mkdocs build --strict is green, no page references prep-feature / prd.json / codified validators / self-improve as current behaviour, and the four diagrams are regenerated.
Refs #37.
Context
PR #37 refactored Tilth to a prompt-driven core (evaluator-only gate; features authored as markdown under
<repo>/.tilth/tasks/instead of an interview-generatedprd.json; noprep-feature, no codified ruff/pytest validators, no self-improve step). The README was fully rewritten in that PR and is the current source of truth for the run flow. Thedocs/site was intentionally deferred — it still describes the old two-stepprep-feature→runflow with validators,prd.json, seed-meta, and self-improve.This issue tracks bringing
docs/back in line. Approach: diff-driven — work from #37's commits (b431215,e57b0ea,a5496e2) and the rewritten README, page by page.Structural changes
docs/deep-dives/seeding.md— theprep-featureinterview engine it documents is gone.docs/deep-dives/prd-json.mdwith a.tilth/tasks/format page (frontmatterid/title+## Description/## Acceptance criteria;overview.md; harness-ownedtask-status.json). Seetilth/tasks.py.mkdocs.ymlnav — drop the seeding.md entry, rename/repoint the prd-json.md entry, and refresh the annotated nav comments that mention prep-feature/validators. Keepmkdocs build --strictgreen.running-the-demo.mdlinks toexamples/seed-reference/(deleted in Prompt-driven harness: drop codified validators, prep-feature, and self-improve #37). It's an external GitHub URL so--strictwon't flag it, but the link is dead.Page rewrites (by amount of stale content)
Heavy (the prep-feature/validator narrative is the backbone):
getting-started/running-the-demo.md— two-step flow →.tilth/tasks/+tilth run; drop validators/self-improve from the per-task lifecycle.getting-started/your-own-project.md— dropprep-featureseeding; author.tilth/tasks/.deep-dives/two-loops.md— remove the validator step from the inner loop.architecture/memory-channels.md— dropprd.json/seed-meta; add task-markdown (overview.md+ tasks) +task-status.json.architecture/anatomy-of-a-run.md— remove validators/self-improve from the data-flow.deep-dives/worker-evaluator-dialogue.md— evaluator is the only gate; drop "validators passed" framing.deep-dives/agent-visibility.md— update the visibility table.architecture/overview.md— invariants/repo-layout (novalidators.py, noseed/).deep-dives/session-layout.md—prd.json→task-status.json; tasks now live in the repo's.tilth/tasks/.Light:
index.md,getting-started/installation.md(dropTILTH_PREP_*),getting-started/visualizing.md,getting-started/resuming.md,deep-dives/{resume-mechanics,hyper-observability,token-recording,index,reset-mechanics,caps}.md.Diagrams to regenerate (via
docs/assets/IMAGE_STYLE.md)The README's two images (
brain-hands-session.png,session-render.png) are still accurate. These four are not:harness-loop.jpgper-task-lifecycle.jpgvalidator_failedfeedback curvesession-end.jpgproposed-learnings.md; artifacts are events.jsonl, summary.json, checkpoint.json, task-status.jsonsession-layout.pngprd.json→task-status.json; tasks live in the repo's.tilth/tasks/, not undersessions/<id>/Done when
uv run --extra docs mkdocs build --strictis green, no page referencesprep-feature/prd.json/ codified validators / self-improve as current behaviour, and the four diagrams are regenerated.Refs #37.