openreachtech/hora-core/hora-fast

hora-fast

The parallel scheduler. Same spec, same plan, same feature files, same acceptance as /hora. What changes is when a feature's checkpoints run: several features at once, each in its own worktree, after the parts they share have been built once and fixed.

The design in one sentence: each feature is verified statically as it lands; the version is verified live, once, at the end. A feature's checkpoint 18 is the browser-less gate run /hora-accept already defines. The browser-driven review runs once, over the whole version, at the sweep.

Read ../hora/references/structure.md first, then ../hora-build/references/checkpoints.md. Both apply here unchanged, and so does every git rule in ../hora/references/commits.md.

What is shared with /hora, and what is replaced

The feature file is the contract between the two schedulers. Every checkbox this skill writes into .hora/tasks/<version>/<feature-id>.md is one /hora-build would have written, with the same marks, the same run record and the same checkpoint 18. Either scheduler can continue a version the other started: each reads the first [ ] and goes on from there ("Switching between the two schedulers", below).

This skill edits no hora file and restates none. Where a rule below reads like one in /hora-build, it is a pointer.

What to say before starting

Run the equipment check /hora runs (../hora/SKILL.md, "Whether hora can start at all"). Then estimate what /hora would take from here, and say it:

pace       seconds per feature: wall-time: summed over a feature's lines, from
           the run records of the features already done in this version, or
           from the previous version while none is done
remaining  features in _plan.md still [ ]
 
pace x remaining            what /hora would take from here
its share on 1, 2, 9, 11    what neither scheduler shortens

Ask whether there is a date. Do not assume one. Most versions have none, and wanting the version sooner is reason enough to be here. Where a date exists and the serial estimate fits it, say so; the person chooses which scheduler runs.

Read the four conversation lines apart. wall-time: on checkpoints 1, 2, 9 and 11 is mostly a person answering, and it is the same under either scheduler. A version whose time sits mostly on those four lines gains little here. Say so when the records show it.

A person chooses this skill by invoking it, and the invocation is the whole decision (../hora/references/structure.md, "Where a lever lives", question 2). The record says who chose it ("The record", below).

Deciding where you are

/hora's steps, with 4a and 5 inserted. Do this every time.

0.   As /hora: fetch and prune everywhere, catch up with a hotfix, read the
     open hotfix debts. Then, in every declared repository:
       git -C <repository> worktree list
     Every worktree under .worktrees/ is a feature in flight. Report them
 
1-4. As /hora: spec -> /hora-spec, missing row -> /hora-setup, always
     /hora-plan, a blocking question -> stop
 
4a.  Is a main working copy on a feature/ branch — a feature /hora left
     mid-gate?                     if so -> move it into a worktree ("Moving
                                            a mid-gate feature", below).
                                            Stop only if the move fails
 
5.   Is the foundation built and fixed?
                                   if not -> build it ("The foundation")
 
6.   Are there features still [ ] whose next gate may open?
                                   if so -> run them, up to the limit ("The
                                            parallel loop"). A feature whose
                                            only open checkpoint is 18 gets
                                            its gate run ("Checkpoint 18, and
                                            the sweep")
 
7-8. As /hora's 6, 6a and 7: no [ ] left and no passing full sweep
     -> /hora-accept, whole-version; then the merge into main

Report the decision in one line before starting — "continuing 1.0.0 in parallel. Foundation fixed, 4 of 11 features done, 3 in flight, opening #payroll".

The foundation

Every file two features would both write is built once, before any feature starts. This is /hora-build's exclusivity rule one level up: there, a file two units would both write goes to one of them; here, a file two features would both write goes to the foundation.

It is derived against `release/<version>`'s tip. What the remaining features share and the tip already holds — a table an earlier feature built, a Base member already merged — is done, not foundation work. On a version /hora started, most of it is.

What is in it

An aggregation file is derived, so it is regenerated at every merge rather than built here.

How it is built

1. List the files from the table above in _fast.md, each with what it is for.
   The main session reads and records this before anything is written
2. Run the checkpoints that apply — 3 for tables and schema, 5 for a shared
   module, and the seed — exactly as /hora-build runs one checkpoint: the
   skills match, the digests, one implementer per exclusive unit, lint, the
   verifier, the run record. The record goes on the foundation's own lines
   in _fast.md
3. Each change lands as commits.md says a planned change to something shared
   lands: an update/ branch into release/<version>, in the main working copy
4. The contract check (below), then every repository's whole suite on the tip
5. Mark the foundation fixed in _fast.md

The mechanical contract check

Parallel transcription fails by silent divergence: the declared surface, the generated types and the stubs each correct alone and different from each other. Prose misses it.

Worktrees

One worktree per feature, per repository it touches, on the `feature/<feature-id>` branch `commits.md` names. The branch rules stay as they are; the branch gets a directory of its own.

<project>-app/                                  cwd, as always
  <project>-backend/                            the main working copy. Stays on release/<version>
  .worktrees/<feature-id>/<project>-backend/    feature/<feature-id>, this feature only
  .worktrees/<feature-id>/<project>-frontend-*/ the same, per row the feature touches that the frontend gate takes

`.worktrees/` is ignored by the hora repository, like the nested rows. Add the line to its .gitignore when it is missing.

A worktree is the repository, for every rule that says "from inside the repository". cd, git -C, lint, tests, the change-set derivation — all run in the worktree (../hora/references/structure.md, "Where a per-repository command runs"). Running one of them in the main working copy for a feature in flight is that file's wrong-directory failure, one level up.

What a second working copy needs — dependencies, a database, ports — is the stack handbook's answer, read at run time like every other stack fact. A missing answer is a lacked-environment question, never a guess.

open   on entering the gate's first checkpoint — 3 for the backend row, 10
       for a row the frontend gate takes — where /hora-build cuts the branch:
         git -C <repository> worktree add ../.worktrees/<feature-id>/<repository> \
             -b feature/<feature-id> release/<version>
         then what the handbook says a second copy needs, run inside it
 
close  once that gate has merged — 9, or 17:
         git -C <repository> worktree remove ../.worktrees/<feature-id>/<repository>
         the branch is handled as commits.md handles a merged branch

A feature that names several frontend rows opens one worktree per row, each on entering that row's 10, and each gate follows the previous row's 17 under the order rule (../hora-build/references/checkpoints.md, "A feature that names several frontend rows carries one frontend gate per row").

How many features are open at once is a limit a person sets; the default is three. It bounds machine load and the main session's attention. Correctness does not depend on it.

A session that ends mid-feature loses nothing. Step 0 finds every open worktree from git, and the next run re-enters the feature at its first [ ], in the worktree it already has.

Moving a mid-gate feature into a worktree

/hora keeps the feature it is building in the main working copy, on its feature/ branch, and mid-gate that copy may hold uncommitted work: implementation commits follow the package's convention, and .hora/ commits at the gate's end. A branch checked out in the main copy cannot be checked out in a worktree as well, so the feature moves, and its uncommitted work moves with it:

git -C <repository> stash push -u                       everything uncommitted, untracked included
git -C <repository> switch release/<version>
git -C <repository> worktree add ../.worktrees/<feature-id>/<repository> feature/<feature-id>
git -C ../.worktrees/<feature-id>/<repository> stash pop

The stash creates no commit, so the package's commit granularity is untouched. The work lands in a fresh checkout of the same branch, so the pop has nothing to conflict with. Ignored files stay behind; the worktree gets its own, as the handbook says.

Stop only when a step fails, and say which.

The parallel loop