Skip to content

F14.3 — Generated board

State Closed
Parent E14
Iteration Release 2
Closed Date 2026-09-29
Predecessors —

Stories: 3 Closed

Story State Depends on
S14.3.1 — State columns on every feature table Closed (2026-09-29) —
S14.3.2 — The board script Closed (2026-09-29) —
S14.3.3 — Board layout and rules Closed (2026-09-29) —

The board in docs/specs/index.md answers two questions: what ships in which release, and what is on no release yet. Today it also carries four hand-maintained epic groups (In progress, Elaborating, Deferred, Done) that repeat what the epic pages say, and a generated per-feature Backlog table that repeats the groups again. This feature replaces both with two generated sections, Releases and Backlog, built by one script from the epic and release pages. The rules:

  1. A feature carries its own assignment: its State, and, on a release, its Iteration field. The board and each release's Scope table are derived from feature pages alone.
  2. Every non-Removed feature with no Iteration is in the Backlog, never both there and on a release.
  3. Inconsistent specs fail the script, so CI or a pre-commit hook can enforce the rules the structure docs today leave to a reviewer.

Design

Outcome: docs/_update_board.sh, in POSIX sh and awk only so that it could be copied into a repository in another language, generated the board's Releases and Backlog sections and each release's Scope table from the feature pages, and failed on inconsistent specs (closed 2026-09-29).

Out of scope. Wiring --check into CI or a pre-commit hook; changing kiln's docs templates; resolving F14.1 and F14.2, which were on no release while this feature was built (the script reported them; the owner later scheduled both on release-2).

S14.3.1 — State columns on every feature table

State: Closed (2026-09-29)

Outcome: E1, E2, E3, E4, E5 and E7 gained a State column after the ID column.

Acceptance: docs/_update_board.sh --check reports no missing-column error.

S14.3.2 — The board script

State: Closed (2026-09-29)

Outcome: docs/_backlog.sh became docs/_update_board.sh, which mkdocs.yml excludes.

Acceptance: each check in the block below tagged S14.3.2 passes, and the script produces identical boards under /bin/sh with BSD awk and under dash with gawk.

S14.3.3 — Board layout and rules

State: Closed (2026-09-29)

Outcome: the board carried the generated region, and specs/index.md, specs/_structure.md and docs/_structure.md dropped the hand-kept board rules.

Acceptance: the board has the marker pair, no ## Board or ### Done heading, and the strict docs build passes.

Acceptance

Run from the repository root. This acceptance block is historical, from when the script used Status/elaborating/planned/in progress/done/deferred and a hand-authored release Scope table; it is kept here in the vocabulary the later ADO migration (specs/_structure.md) introduced, since F14.1 and F14.2 now carry an Iteration and the real tree passes cleanly.

set -euo pipefail
absent() { local rc=0; rg -q --hidden --glob '!.git' "$@" </dev/null || rc=$?; [ "$rc" -eq 1 ]; }
fails_with() { local out rc=0; out=$("${@:2}" 2>&1) || rc=$?; [ "$rc" -ne 0 ] && grep -qF -- "$1" <<<"$out"; }
tmp=$(mktemp -d)
fixture() { cp -R docs "$tmp/$1"; }
# S14.3.1, S14.3.2: the real tree is current and consistent
docs/_update_board.sh
docs/_update_board.sh --check
# S14.3.2
[ -x docs/_update_board.sh ] && [ ! -e docs/_backlog.sh ]
rg -q '^  /_update_board.sh$' mkdocs.yml
absent -e '_backlog\.sh|backlog:start' --glob '!docs/specs/epics/E14-workspace-automation/F14.3-generated-board.md' docs mkdocs.yml CLAUDE.md
absent -e 'gensub|asort|\[\[' docs/_update_board.sh
# the same board and scope tables under dash and gawk
fixture g && mkdir "$tmp/gbin" && ln -s "$(command -v gawk)" "$tmp/gbin/awk"
PATH="$tmp/gbin:$PATH" dash docs/_update_board.sh "$tmp/g"
cmp docs/specs/index.md "$tmp/g/specs/index.md"
cmp docs/releases/release-2/index.md "$tmp/g/releases/release-2/index.md"
# a feature table without a State column
fixture m1 && sed -i.bak 's/^| ID | State |/| ID | Status |/' "$tmp/m1/specs/epics/E1-foundation-and-boundaries/index.md"
fails_with 'E1-foundation-and-boundaries/index.md' docs/_update_board.sh --check "$tmp/m1"
# an Active feature with no Iteration
fixture m2 && sed -i.bak '/\*\*Iteration\*\*/d' "$tmp/m2/specs/epics/E14-workspace-automation/F14.1-discovered-pipeline.md"
fails_with 'F14.1' docs/_update_board.sh --check "$tmp/m2"
# an Iteration naming a release page that does not exist
fixture m3 && sed -i.bak 's#release-2/index.md#release-9/index.md#' "$tmp/m3/specs/epics/E14-workspace-automation/F14.2-pipeline-hardening.md"
fails_with 'F14.2' docs/_update_board.sh --check "$tmp/m3"
# a missing marker
fixture m4 && sed -i.bak 's/<!-- board:end -->//' "$tmp/m4/specs/index.md"
fails_with 'board:end' docs/_update_board.sh --check "$tmp/m4"
# a stale region
fixture m5 && sed -i.bak '/^## Backlog$/a\
stale line
' "$tmp/m5/specs/index.md"
fails_with 'out of date' docs/_update_board.sh --check "$tmp/m5"
# S14.3.3
rg -q '^<!-- board:start -->$' docs/specs/index.md && rg -q '^<!-- board:end -->$' docs/specs/index.md
absent -e '^## Board$|^### Done$' docs/specs/index.md
absent -e 'exactly one group|board row' docs/specs/_structure.md
uv run --group docs mkdocs build --strict -d "$tmp/site"
[ ! -e "$tmp/site/_update_board.sh" ]