docs(workflow): the roadmap-burndown Spacedock workflow and its earned rules - #240
Merged
Conversation
…d rules
Adds the workflow definition this repository's roadmap burndown now runs on: a
five-stage pipeline (selection, triage, implementation, review, recorded) with
two captain gates, over the Cargento: Visibility 2x2 Roadmap project.
Nearly every rule in it was earned rather than designed, and the file records
the measurement behind each one, because the reason is what lets a rule survive
a case it did not anticipate:
- Linear's serializer rewrites the whole body on any write, including a
targeted patch, and the damage is progressive: a boundary moves on one write,
the mark is dropped on the next, and a repair cannot stabilise it. Markdown
links do not prevent mention-created relations. Bodies must be sent unwrapped.
- A stage-report addendum must not reuse the "## Stage Report: {stage}" heading;
the selector takes the latest match and hides the original from the machine.
- "reconciled" has exactly one window, before "merge guard" archives the entity,
because an archived entity is read-only.
- A dispatch checklist item must be satisfiable by the worker it is given to,
and must name the artifact rather than a category.
- Cost the oracles separately from the runtime, and re-baseline the estimate at
a correction round: a round's content is findings, which are by definition
unknown when the estimate is declared.
- Verify PR content at the SHA. A stale "gh pr diff" once returned text present
in no version of the file.
- Write records specific enough to be contradicted, and when a later
measurement disagrees with a recorded figure, suspect a hidden variable before
suspecting a miscount.
Entity state lives on the spacedock-state/roadmap-burndown orphan branch and is
gitignored here, so stage transitions never churn a code branch. The vendored
_mods/ copy is ignored too; the README explains why, how to restore it, and a
known local-only validator divergence that follows from it.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Signed-off-by: Jared Scott <jared.scott@variable.team>
Contributor
CoverageThreshold: |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds the Spacedock workflow this repository's roadmap burndown now runs on, plus the two
.gitignoreentries and theAGENTS.mddocs-table row it owes.No mirrored Linear issue: this is workflow machinery produced while running the burndown, not a board item.
What it is
A five-stage pipeline —
selection→triage→implementation→review→recorded— over the Cargento: Visibility 2x2 Roadmap project, with captain gates attriageandreview. It does not reinvent what already exists: theburndownskill owns picking and reconciling,recce-dev:linear-deep-diveowns issue analysis,superpowers:test-driven-developmentowns the build, and AGENTS.md, "Pre-PR Checks" owns the gate. What the workflow adds is a durable place for one issue's journey to sit between sessions, an adversarial pass over the issue text before anyone builds against it, and a review whose depth is chosen rather than assumed.Why it reads the way it does
Nearly every rule in it was earned rather than designed, and each carries the measurement behind it. That is deliberate: a rule without its reason gets deleted the first time it is inconvenient, and a record specific enough to be contradicted is what lets a later measurement disagree with it.
A sample, all measured while running the thing:
patch— and the damage is progressive: a boundary moves on one write, the mark is dropped entirely on the next, and a repair provably cannot stabilise it. Markdown links do not prevent mention-created relations. Bodies must be sent unwrapped.## Stage Report: {stage}heading — the selector takes the latest match, so an addendum silently replaces the report rather than supplementing it.reconciledhas exactly one window, beforemerge guardarchives the entity, because an archived entity is read-only.gh pr diffonce returned text present in no version of a file.Layout
Entity state lives on the
spacedock-state/roadmap-burndownorphan branch, checked out as a linked worktree and gitignored here, so stage transitions never churn a code branch or collide with a feature PR.The vendored
_mods/pr-merge.mdis ignored too. The README explains why — a committed copy forks the plugin's own file, and its template placeholders fail this repository's documentation gate — along with how to restore it and a known local-only validator divergence that follows, which is filed as the next housekeeping task on the workflow.Verification
The diff is
.gitignoreplus two Markdown files, so it touches no Python. CI's change detector will nonetheless classify itcode=true, because.gitignoreis not in its prose set, so the full gate is owed and was run locally:ruff check .— all checks passed;ruff format --check .— 147 files already formattedmypy— success, no issues in 108 source filesscripts/lint_embedded.py— frontend assets cleanscripts/bump_version.py --current—0.18.0; no version field moved since the merge basecoverage report— 90.8% againstfail_under = 73scripts/validate_plugins.py— exit 0 against a clean export of the committed tree (git archive HEAD). Run against a working tree that has the ignored mod restored it reports two errors from that file; that is the documented divergence above, and CI checks out committed files only.