Status, steps, deliverables¶

Audience. Daily user.

At a glance¶

Every item is a directory under projects/YYYY-MM/YYYY-MM-DD-slug/ containing a README.md. There is no top-level incidents/ or documents/ folder — the kind field in the header discriminates. Three body sections are parsed: ## Steps, ## Deliverables, and anything whose heading is used by the step-add-by-section flow (## Timeline, etc., are left alone).

For the header format, see README format.

Folder layout¶

conception/
├── projects/
│   ├── 2026-04/
│   │   ├── 2026-04-10-auth-rewrite/
│   │   │   ├── README.md
│   │   │   └── notes/
│   │   │       └── investigation.md
│   │   └── 2026-04-14-login-500s/           ← incident, same layout
│   │       └── README.md
│   └── 2026-03/
│       └── 2026-03-22-ci-upgrade/
│           └── README.md
├── knowledge/                                ← optional, explorer pane
│   └── …
├── .condash/                                 ← tree-level state (gitignored)
│   ├── settings.json                         ←   per-host config
│   └── logs/YYYY/MM/DD/HHMMSS-<sid>.txt      ←   per-session terminal capture (plain text + JSON header/footer)
└── condash.json                              ← legacy config (still read)

The .condash/ directory is gitignored by default — the auto-migrator appends .condash/ to your conception's .gitignore the first time it lifts a legacy condash.json into .condash/settings.json. See Config files for the read precedence and the migration mechanics.

Rules, enforced or conventional:

Rule	Enforced by	Notes
Items live at `projects/YYYY-MM/YYYY-MM-DD-slug/README.md`	parser glob	Anything not matching `projects///README.md` is invisible.
Month folder is `YYYY-MM`	convention	The parser does not validate the folder name, but the wikilink resolver expects it.
Item folder starts with `YYYY-MM-DD-`	convention	Dashes; no spaces. The part after the date prefix is the short slug wikilinks resolve against.
Kind lives in the metadata block as `kind: …`	convention	Defaults to `project`. No separate directory per kind — they coexist under one month folder.

The flat-month layout was a deliberate simplification of an earlier projects/<slug>/ + projects/YYYY-MM/<slug>/ split. Items never move between active and archive; a Status: done flip is the only archive signal, and there's nothing for condash to rename. See why Markdown-first for the rationale.

Status model¶

Five ordered values, highest-urgency first:

Value	Meaning
`now`	Actively being worked on this week
`review`	Work done, awaiting review or verification
`later`	Agreed to do, not scheduled
`backlog`	Possible; worth keeping, not committed
`done`	Closed. Stays in its `YYYY-MM/` folder indefinitely.

The parser normalises the value to lowercase and preserves it verbatim — there is no silent rewrite to backlog. Unknown values log a parser warning, sort after every known value (per statusOrder in src/shared/projects.ts), and make the card sprout a red !? <value> badge next to its status pill so typos (wip, active, …) stick out until corrected. A status: line that is absent altogether defaults to backlog (no badge). See README format — Status for the full rule. Inside the dashboard, status changes via drag-and-drop rewrite the status line in place — status: for YAML-frontmatter READMEs, **Status**: for legacy bold-prose READMEs. See mutations.

Steps¶

Markdown checklists inside any ##-level section. The dashboard's default "add step" target is a section literally named ## Steps, but any section (for instance ## Phase 1) can carry checkboxes and they all contribute to the item's progress count.

## Steps

- [ ] Audit current session-cookie usage
- [~] Implement the hybrid read path
- [!] Migration script for existing tokens (blocked on schema sign-off)
- [x] Decide on cookie attributes
- [-] Feature flag (abandoned — shipping directly)

Marker map¶

Marker	Parsed status	Counted as done?
`[ ]`	`open`	no
`[~]`	`progress`	no
`[!]`	`blocked`	no
`[x]` or `[X]`	`done`	yes
`[-]`	`abandoned`	yes

The dashboard's checkbox-click cycle is open → progress → done → abandoned → open, implemented in src/main/mutate.ts (writer) and src/renderer/panes/projects.tsx (UI cycle order). The [!] (blocked) marker is not part of the cycle — set it by editing the README directly when work on a step is paused waiting for an external decision; the parser, counter, writer, and renderer all round-trip it without loss.

The canonical list of markers (and the parsing regex bracket class) lives in src/shared/types/project.ts as STEP_MARKERS.

Where to put steps¶

Keep the top-level ## Steps list short — three to eight high-level milestones. Per-file tasks, acceptance criteria, and detailed implementation checklists belong in notes/<name>.md, not in the README. The README is the bird's-eye view; the notes folder is the workshop.

Why no ordering semantics¶

The parser preserves source order. Drag-and-drop reorder rewrites the affected step lines in place (see src/main/mutate.ts) — there is no explicit index, priority, or ID on a step. Two steps with identical text are indistinguishable.

Deliverables¶

PDF outputs an item produces — technical reports, executive summaries, audits. Declared in a section literally named ## Deliverables:

## Deliverables

- [Technical report](rapport-technique.pdf) — full analysis with code references
- [Executive summary](summary.pdf) — one-page version for stakeholders

Strict syntax:

Piece	Rule
Line start	`- [`
Label	any text until the next `]`
Path	Markdown link target ending in `.pdf`, relative to the item directory
Separator	optional em-dash (`—`), en-dash (`–`), or hyphen (`-`)
Description	optional free text after the separator

The parser (src/main/parse.ts) stops at the next ## heading. Lines that do not match the pattern are silently skipped — a typo means your PDF disappears from the card, no error.

See Deliverables and PDFs for the viewer config, the download route, and how the built-in PDF.js previewer kicks in.

Timeline¶

An append-only human-facing log. The parser (src/main/parse.ts) reads the section to extract the Closed. date for done items and any structured YYYY-MM-DD — text entries; the dashboard surfaces the timeline in the project popover. Lines that don't match the date prefix are kept verbatim but ignored by the timeline view.

## Timeline

- 2026-04-10 — Project created
- 2026-04-12 — Auth audit complete; see notes/investigation.md
- 2026-04-15 — Hybrid read path merged to main

One line per event, dated, imperative, linkable. Useful when re-reading the item months later — much cheaper than scrolling through commit history.

Notes and subdirectories¶

Anything not in the README goes in notes/<name>.md (or any other subdirectory you create from the dashboard — logs/, drafts/, whatever). The card's Files section lists every non-README file in the item directory, grouped by subdirectory up to three levels deep. Hidden entries (leading .) and the top-level README.md are skipped.

See mutations for the create/rename/upload routes, and Linking items with wikilinks for the in-note link syntax.

What is not part of the convention¶

No TOML frontmatter. YAML frontmatter is the canonical header shape from v2.16.0; TOML frontmatter is ignored. The legacy bold-prose header is also accepted indefinitely. See README format.
No IDs. The directory name is the identity. No UUIDs, no auto-incrementing counters.
No schema version. The parser is backwards-compatible within a major version; new fields are additive.
No lock files. Everything the dashboard knows is derived from the tree on every request.
No archive step. Items live at projects/YYYY-MM/YYYY-MM-DD-slug/ for life. Status flips, directories don't — so there's no "archive" or "tidy" workflow to trigger.