openreachtech/hora-core/hora-build

hora-build

Take one feature through the eighteen checkpoints, in order.

Read ../hora/references/structure.md (the layout, the invariants, where and how a command runs) and references/checkpoints.md (the checkpoint list itself) before starting. This skill is read-only on `specs/`; checkpoint 1 is where a problem found there is routed to the two skills that may write it (references/checkpoints.md, checkpoint 1).

One feature at a time, never two

Nothing here ever runs alongside another feature's checkpoints. One feature goes from checkpoint 1 to checkpoint 18, and only then does the next one start:

Where to start

If a backend row is declared, and an equipped skill covers exclusive row-id allocation, clear that allocator's lock unconditionally before touching any checkpoint (its own file describes clearing a stale lock). Nothing holds that lock across invocations, so one still standing at the start of a run is leftover.

Then allocate this feature's id prefix once through that skill, before its first implementing checkpoint, and hand that same prefix to every agent that works in the backend row. The allocator returns the same prefix for the same requester however often it is asked, so allocating here costs one call and leaves the lock free — where several units run at once, asking for themselves would queue them behind each other's lock.

1. Read .hora/tasks/<version>/_plan.md
2. Take the first feature "Whether a feature is ready to build", later
   in this file, says yes to
3. Open .hora/tasks/<version>/<feature-id>.md
4. Take the first checkpoint that is [ ]
5. Run it. Then the next one. Stop when the file has no [ ] left

Report the decision in one line before starting work, as in "building #attendance, from checkpoint 6 of 18". Inside a frontend gate the line names its row: "building #attendance, from checkpoint 11 (frontend-admin) of 18".

In a file that carries several frontend gates, step 4 takes the first `[ ]` in file order, so the rows run in target order and 18 runs once, after the last (references/checkpoints.md, "A feature that names several frontend rows carries one frontend gate per row").

A feature whose only open checkpoint is 18 writes no code, and cuts no branch. That is what a section declaring <!-- built: frontend --> looks like on adoption: everything up to the acceptance gate is marked not-applicable, so this skill goes straight to /hora-accept.

Step 2 skips an entry whose checkpoint 18 is covered by the sweep entry. Where every specified feature carries built:, /hora-plan collapses the per-feature gates into a single adoption sweep (../hora-plan/SKILL.md, "collapses to one sweep"). Taking one anyway would run the twenty individual gates the collapse exists to replace.

A listed feature is never entered, and it has nothing to resume from. A section carrying <!-- baseline: inventoried --> sits under ## Not accepted with no checkbox, so step 2 skips it with no special case (../hora-plan/SKILL.md, "_plan.md — the order"). Its eighteen empty boxes are not a feature nobody started — the feature file's provenance header says which of the two this is, and opening one rebuilds code that is already serving users.

If no feature is ready and some are unfinished, and no open question holds any of them back, that is a dependency cycle or a reference to an `id` that does not exist. Raise it as a contradiction question (blocking: yes) and stop.

A listed feature is not one of the unfinished ones. It carries no checkbox, so a version with nothing left but listed entries is finished rather than deadlocked (../hora/SKILL.md, "Deciding where you are").

A `depends` naming a listed feature is satisfied by the running code, never by a checkbox. Read it as satisfied, and read the dependent's own Rests on: #<id> (not accepted) line for what its pass rests on.

[wing] Whether a feature is ready to build

Yes, where its entry in `_plan.md` is `[ ]` and every one of its `depends` is satisfied: [x] in this version, finished in an earlier one (look back through past versions in .hora/tasks/ for a revived feature's dependencies), or listed. /hora takes its next feature from this section through step 2 above. /hora-fast takes one from here too, and opens a gate earlier where the section below says yes.

[wing] Whether a gate may open while a dependency is unfinished

Yes, where every unfinished dependency has reached what this step waits on. Only /hora-fast reads this section. /hora builds one feature to acceptance before the next, so a feature it picks has no unfinished dependency.

What the dependent's backend uses from its dependency is in the foundation before either opens. The contracts, the shared tables, the master seed and every module /hora-plan marked Imports: are built there, and /hora-plan walked every use case through the contracts field by field. Checkpoint 9 walks the use cases as actual calls, so it is the first step that needs the dependency's running code.

A dependent's tests reach its dependency through the foundation, never through the dependency's operations. A row they need in a dependency's table is seeded in the dependent's own band (references/checkpoints.md, checkpoint 5), and the call itself is walked at checkpoint 9.

A dependency's later gate that changes code a dependent built on reopens the dependent. Clear the dependent's first checkpoint that reads the changed code, in every row whose code reads it, with reopened-by: dependency.

Running one checkpoint

0. Look back for the line of the last checkpoint marked [x]. Where it is not
   on screen, write it now, before anything else (step 10)
1. Read the checkpoint's entry in references/checkpoints.md — its exit
   condition, the work it delegates, and when it does not apply
2. Decide whether it applies. If it does not, write the reason and mark it
   [x] with the n/a comment. Move on
3. Match that work against the equipped skills, take a digest of each, and
   record both (below). This is the main session's step, never an agent's
4. Cut this repository's feature/<feature-id> branch, if this is the first
   checkpoint in this gate (see ../hora/references/commits.md)
5. Run it:
     an interactive checkpoint (1, 2, 9, 11, 17, 18)
       -> the main session runs it. Never an agent
     an implementing checkpoint (3-7, 10, 12-16)
       -> hora-implementer, one agent per unit of this checkpoint's work,
          started together (below), each given that checkpoint's exit
          condition, the skill names and digest paths from step 3, and this
          feature's row-id prefix. One agent takes several consecutive
          checkpoints only where "Whether consecutive checkpoints
          may go to one implementer" says yes
     an auditing checkpoint (8)
       -> hora-verifier, read-only, given the skill names to invoke in full
          AND the change set to audit ("The change set of a checkpoint",
          below). The audit skills run over that set, never the whole
          repository
     while an agent runs, the next checkpoint is not entered, not even to
     prepare it (references/checkpoints.md, "The order is a rule")
6. Gather the units: regenerate every aggregation file their registrations
   name, then handle whatever else they reported that is not code (below) —
   a dependency, a conflict-proof change, a new identifier, a contract one
   wanted to change
7. Lint, as "How to lint a checkpoint's files", below, says
     still fails -> fix it, retry (up to five attempts; see "A lint rule contradiction")
8. Test, where the checkpoint's exit condition names tests (6, 16, 18), as
   "How to test a checkpoint's files", below, says
     fails, from something code could fix -> fix it, retry
     fails, from something no code change could fix (the middleware is not
       running, a network call reached nothing, the database was altered
       outside this run) -> stop retrying immediately, without spending the
       retry limit. Report it as a `lacked-environment` question and stop the
       feature there
     dies, leaving no result at all (the process was killed, the machine ran
       out of memory) -> not a code failure either. Report it as a
       `lacked-environment` question that names the configuration the run
       died under (below), and stop the feature there
9. Verify the exit condition actually holds — with hora-verifier for anything
   a reading of the code can settle, handed the marked change set (below);
   in conversation for the four gates that check against use cases. At 6
   and 16, where step 8's suite is itself the proof, the verifier is usually
   skipped (below). At 15, the main session also opens every screen in a
   real browser, since no reading of the code settles a layout
   (references/checkpoints.md, checkpoint 15). Met or not, add this run to
   the line's run record (below)
     sent back -> write the send-back line, then re-enter where the verdict
       says:
         ⏳️ [<n>] <feature> checkpoint <k> sent back to checkpoint <j> | <the findings, or the shortfall> | -> <what comes next>
10. Write [x] into the feature file, and in the same reply the pass line:
         ✅️ checkpoint <k> passed | <the one fact it established> | -> <what comes next>
         🎯 <feature> accepted | checkpoint 18 passed: <the fact> | -> <the next feature>   (at 18)
    Commit at the gate boundary, not here
11. Move to the next checkpoint

The line is written where the box is, so neither goes without the other. The shapes above are all a pass or a send-back needs; /hora-progress holds the rules behind them — what n counts, what may be said between two lines — and is read wherever one of those is in doubt. Step 0 is what catches a line that was missed: a box with no line behind it is written up before the next checkpoint starts, never left for the closing report.

Step 10's split matters. The checkbox is written the moment the checkpoint passes, so an interrupted run resumes at the right place; the commit happens once per gate, so git log .hora/ stays readable (../hora/references/commits.md, "Committing .hora/").

[wing] How to lint a checkpoint's files

cd into this checkpoint's repository, then `npx eslint --fix` on exactly the files it touched, every unit's together, then `npx eslint` on the same files for what remains. --fix clears the mechanical violations without an agent round trip; only what it cannot fix is worth one.

[wing] How to test a checkpoint's files

From that same repository, `npx jest` on exactly the files this checkpoint wrote, with the output written to a file and read from there (below).

Step 3 — matching a checkpoint to the skills that cover it

`references/checkpoints.md` names no package skill, and it never may (../hora/references/structure.md, "No hora file ever names one of those skills"). So the match is made here, once per checkpoint, against what is actually equipped: