> ## Documentation Index > Fetch the complete documentation index at: https://honest-scholar.science/llms.txt > Use this file to discover all available pages before exploring further. # progress > Use when you want to see the state of a research program — where a hypothesis, paper, or thesis stands, what is blocking it, what is stale — or to regenerate the dashboard. Reads status from each… Progress is a **cross-cutting, read-only reporting** function. It answers "where does this stand, and what is in the way?" at every level (hypothesis / paper / thesis) without ever making or influencing a scientific judgment. It respects the firewall (see `../../docs/design/00-meta-spec.md` §2.3): exploration proposes, resolution disposes, synthesis reports — and progress only *reports*. It adjudicates nothing, scores nothing, and touches no claim. The single source of truth is the **artifact itself**. Every hypothesis, paper, and thesis artifact carries a small status block in its markdown **frontmatter**, versioned in git alongside the thing it describes — the living-document pattern (RSC *Digital Discovery*, DOI:10.1039/D3DD00032J). There is deliberately **no separate progress file** to drift out of sync. `progress` reads that frontmatter and rolls it up; the generated dashboard is a pure projection of it, nothing more. Grounding: `../../resources/references/thesis-and-progress-tracking.md` (Part B), ADR-0014 (`../../decisions/0014-progress-cross-cutting.md`), meta-spec §3.6, lifecycle §5 (`../../docs/design/01-lifecycle.md`). ## When to use * You want the current state of one artifact or of a whole level ("where is paper X?", "which hypotheses are still open?", "is the thesis defensible yet?"). * You want to see **blockers** (a refuted load-bearing hypothesis, an uncovered aim) or **staleness** (artifacts whose `last-updated` has gone cold relative to their backend evidence — cross-check with the experiment backend's `is-current`, resolved from the `backend:` binding in `docs/research/papers.md`). * You need to regenerate `docs/research/dashboard.md` after any status frontmatter changed. Do **not** use progress to decide a verdict, rank artifacts by "productivity," or compute a completion percentage — those are firewall/anti-Goodhart violations (see Guardrails). Status frontmatter is *written* by the resolve skills and by `defend` (the `understanding` field); progress only *reads* it. ## Verbs | Verb | What it does | | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `status [id]` | Read the frontmatter for one artifact (`id` given) or every artifact at a level (`hypothesis` \| `paper` \| `thesis`), roll it up per the rules below, and print a coverage + blockers view. No files written. | | `dashboard` | Regenerate `docs/research/dashboard.md` as a **pure projection** of all status frontmatter. The only file progress writes — and it is machine-owned, never hand-edited. | * `status` is the everyday verb; run it freely, it mutates nothing. * `dashboard` overwrites the generated file wholesale from current frontmatter. If someone hand-edited the dashboard, those edits are (correctly) lost — status belongs in the artifacts, not the projection. The file carries a `` banner. * The dashboard lists, per artifact: level, id, link, verdict, readiness, coverage/blockers, `last-updated`, and (if present) `understanding`. It links artifacts along the hypothesis → paper → thesis-aim chain. It shows **no totals, no scores, no percentages.** ## Status frontmatter The block each artifact owns. Fields are small and orthogonal; absence means "not yet set," never zero. Verdict and readiness are **distinct axes** (see below). ```yaml theme={null} status: level: hypothesis # hypothesis | paper | thesis id: 2026-07-17-monotone-depth verdict: refuted # hypothesis: pending|confirmed|refuted|inconclusive # paper: no-go|publish (once decided) # thesis: n/a (uses defensible below) readiness: resolved # hypothesis: pending|resolved # paper: drafting|under-review|published (sub-states of done) # thesis: framing|synthesis|defensible signed-off-by: "D. Runje" # named human on any material decision (§2.1); null until signed signed-off-date: 2026-07-17 evidence: [run-ref://…] # backend run-refs backing the verdict — never hand-copied numbers covers: [aim-2] # paper→thesis: which aims this artifact supports load-bearing: true # hypothesis→paper: does refutation block the parent's claim? understanding: {status: ok, unresolved: []} # written by the `defend` skill; surfaced, never scored blockers: [] # free-text blockers the author flags last-updated: 2026-07-17 ``` * A **material decision** (`verdict` on a hypothesis, `verdict: publish/no-go` on a paper, `defensible` on a thesis) is only real when `signed-off-by` is set — the named-human requirement of §2.1. Progress reports an unsigned verdict as *not yet decided*, never as done. * `evidence` points at backend run-refs; progress does not read the numbers, only that they exist and (via `is-current`) whether they are stale. ### Where the status block lives Each level has **one authoritative roll-up artifact** that carries the `verdict` / `readiness` / sign-off block progress reads; the other staged docs may carry their own lighter `understanding` + `last-updated` (written by `defend`), which progress *also* surfaces but never treats as the verdict source. | Level | Authoritative artifact | Carries | | ---------- | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | hypothesis | `…/hypotheses//findings.md` | `verdict` (confirmed/refuted/inconclusive), `readiness`, `evidence`, sign-off. Before `findings.md` exists, readiness is `pending`, inferred from the furthest completed stage. | | paper | `…//paper/decision.md` | `verdict: publish\|no-go`, `readiness` (drafting/under-review/published), sign-off. | | thesis | `docs/research/thesis/aims.md` | `readiness: framing\|synthesis\|defensible`, the defensibility sign-off, and the machine-readable **aim list** that `paper → thesis` roll-up matches against each paper's `covers:`. Milestones stay in `thesis/milestones.yml`. | ## Definition of done Per-level exit criteria — the Stage-Gate framing (gate = exit criteria + decision) the resolve gates already embody, not a burndown %: * **hypothesis = resolved** — has a `verdict` (confirmed / refuted / inconclusive) backed by recorded evidence and a named sign-off. Pending = no verdict. * **paper = done** — its constituent hypotheses are all *resolved* **and** the paper is submission-ready (a signed `decision`). `drafting → under-review → published` are sub-states of done, not extra gates. * **thesis = defensible** — every aim is covered by ≥1 paper **and** the kappa states a coherent through-line / original contribution. Program milestones (`thesis/milestones.yml`) are reported alongside but are not the done criterion. ## Roll-up rules Roll-up is a **semantic function of children's states + the level's gate criteria** — never arithmetic. Surface **coverage and blockers**; never an average or percentage. Averaging would hide exactly the failures that matter. * **hypothesis → paper.** "All constituent hypotheses *resolved* AND the claim is written." A single **refuted `load-bearing: true`** hypothesis is a **blocker** on its paper — it invalidates the claim regardless of how many other hypotheses resolved. Report as `covered: 4/5 resolved; BLOCKED by (load-bearing, refuted)`, not `80%`. * **paper → thesis.** "All aims covered by ≥1 paper AND the kappa states the through-line." Roll up as **uncovered aims** + **through-line stated?** — the exact things an examiner checks. Paper *count* is never the target (there is no universal N; the binding norm is scope). * **staleness** is orthogonal: an artifact whose evidence the backend reports as not-current (`is-current`) is flagged stale regardless of verdict. Progress surfaces it; the human decides whether to re-run. Output shape everywhere: `{covered / total by state}` + `{explicit blockers}` + `{stale?}`. No rolled-up number leaves this skill. ## Anti-Goodhart A hard design principle, not a nicety — documented here so it cannot be quietly "improved" into a score later. A self-tracking research tool is *especially* Goodhart-prone: the same person sets and games the metric. * **Surface state, gaps, and staleness — never a productivity score.** Show open hypotheses, uncovered aims, overdue milestones, stale evidence, unresolved understanding gaps. Never a single "progress number." * **Verdict and readiness are distinct axes. A refuted hypothesis reads as done/green, not failed/red** — refutation is successful science; conflating it with failure is a modeling error that would punish honest negative results. * **Do NOT count or compute:** word counts, paper counts, citation/impact proxies, commit counts, %-complete on unresolved work, or a hypothesis "success rate." * **Rationale (cited so it stays honest):** Goodhart's law and Campbell's law (a measure that becomes a target stops measuring); the DORA (2012) and Leiden Manifesto (Hicks & Wouters et al. 2015) principle that metrics *support*, never *replace*, qualitative judgment. See `../../resources/references/thesis-and-progress-tracking.md` (Part B) and ADR-0014. ## Guardrails Load-bearing constraints, not preferences. * **Read-only on state.** Progress never writes status frontmatter and never changes a verdict, decision, or `understanding` field — those are owned by the resolve skills, the human sign-off, and `defend`. The only file it writes is the generated `dashboard.md`. * **Respects the firewall (§2.3) and agency (§2.1).** It reports; it does not propose, dispose, or adjudicate. It never infers whether a decision *should* be made — only whether one *has been* (signed) and what remains uncovered. * **The dashboard is a projection, never a source.** If frontmatter and dashboard disagree, the frontmatter wins and `dashboard` regenerates from it. Nothing in the dashboard is ground truth; there is nothing there to sync or to game. * **No scores, ever** (see Anti-Goodhart). If a future request asks for a percentage, a velocity, a burndown, or a success rate, decline and point here — this is a design invariant, not a missing feature. ## Commit attribution When you commit artifacts produced by this skill, add these git trailers — discovery + provenance (see [`../../resources/commit-attribution.md`](https://github.com/davorrunje/honest-scholar/blob/main/resources/commit-attribution.md)): ``` Generated-with: honest-scholar (https://github.com/davorrunje/honest-scholar) HonestScholar-Skill: progress ```