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:
- A feature carries its own assignment: its
State, and, on a release, itsIterationfield. The board and each release's Scope table are derived from feature pages alone. - Every non-Removed feature with no
Iterationis in the Backlog, never both there and on a release. - 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" ]