creedants/pstack-t3/landing

Landing

Read the pstack-t3 runtime before spawning workers, choosing models, scheduling, or isolating work. It maps those steps onto T3's orchestrator tools.

Writing scales. Integration does not. Landing makes integration a property of the repository, decided once, so no coordinator asks where work lands and no two writers collide.

The rules:

1. One trunk per repository. Every change lands there through the queue.
2. A writer claims a lease on the paths it will change before it starts. Overlapping claims are refused.
3. Writers never integrate. A worker commits in its own worktree and stops. It never merges, rebases a shared branch, or pushes trunk.
4. The queue is the only writer to trunk. It is a lock, not a process. Whoever runs land while the lock is free drains the queue. Everyone else gets "queue busy".
5. A review verdict holds only for the exact change reviewed. The queue lands the pinned SHA, and bounces it when the rebased change differs from the reviewed one.
6. Builds and tests run under a governor slot, so the machine is not overrun.

The script

<skills>/landing/scripts/land.py, where <skills> is the directory holding this skill. Run it from any checkout of the repository, or pass --repo <path>. State lives in SQLite under ${XDG_STATE_HOME:-~/.local/state}/pstack-t3/landing/, one store per repository.

L="python3 <skills>/landing/scripts/land.py --repo <checkout>"
$L init --trunk main --mode human|merge|push|local --check "<cmd>" [--check ...] [--setup "npm ci"] [--batch 4] [--timeout 1800] [--merge-method merge|squash|rebase] [--author-policy any|configured|credited] [--pr-item-line on|off] [--heartbeat-ms 3600000] [--merge-heartbeat-ms 900000] [--base <commit>] [--cap 4] [--generated <paths>] [--rebuild "<cmd>"]
$L mode merge [--merge-method squash]   # change the mode while the queue is empty. --merge-method may change while entries await merge
$L cap 4                     # most changes in flight on the repository at once; 0 clears it
$L lease claim --holder <restaurant>/<dish> --paths src/engine,package.json [--owner <restaurant>/@<generation>]   # prints L<n>, who holds the overlap, or the cap and its holders
$L lease check --holder <restaurant>/<dish> --paths src/engine   # what a claim would answer now, with no lease claimed and no reservation armed: free, the overlapping leases, or the cap
$L lease renew L3 [--if-live] [--owner ...] ; $L lease release L3 [--owner ...] ; $L lease list
$L submit --holder <restaurant>/<dish> --branch <b> --sha <reviewed sha> --lease L3 --reviewer <provider/model> [--owner ...] [--title "..." --body-file pr.md]   # prints E<n>
$L owner --prefix <restaurant>/ --generation 2   # raise a holder prefix's floor; it never lowers
$L lease reserve --for <restaurant>/ --paths a.md,docs --ruling R<n> [--ttl-hours 2] --owner .admin/@<generation>   # prints S<n>; refuses other holders' claims on those paths
$L lease unreserve S<n> --owner .admin/@<generation>   # lift a reservation
$L share --for <restaurant>/ <n> [--clear] --owner .admin/@<generation>   # that prefix's share of the cap; --clear takes 0
$L contest --holders <a>,<b> --owner <restaurant>/@<generation>   # prints C<n>; land holds both holders' entries
$L contest --settle C<n> --first <holder> --owner .admin/@<generation>   # the first holder lands, then the other
$L contest --cancel C<n> --owner .admin/@<generation>   # remove the hold or the order
$L land                      # drain the queue; prints what landed, bounced, or is still queued
$L status [E3] ; $L resume
$L status --holder <restaurant>/<dish>   # that holder's entries with their SHAs; a value ending in / matches every holder under it
$L status --holder <restaurant>/<dish> --sha <sha>   # only its entries at exactly that commit
$L slot -- npm test          # run a heavy command under a governor slot
$L slot --exclusive -- npm run bench   # hold every slot: nothing else heavy runs while it measures
$L slot --slots 2 -- npm test   # take 2 worker slots in one admission

Every command takes --help.

A coordinator replaced by another thread must not write again. owner --prefix docs/ --generation 2 raises the floor for holders under docs/ and never lowers it, so a rerun changes nothing and a lower generation exits 1. lease claim, lease renew, lease release, and submit take --owner <prefix>@<generation>, whose prefix the holder must start with. Inside the write's transaction each refuses a generation below the prefix's floor with land: owner docs/@1 is stale; docs/ is at generation 2, and refuses a holder under a floored prefix that passes no --owner. A prefix with no floor works without --owner. brigade's set --thread --replace raises its restaurant's floor before it records the new thread.

Rulings

The executive admin carries out its rulings from rulings.md.

Set up a repository once

Run init the first time any coordinator writes to a repository. The mode decides whether the user stays a gate on landing, so it is the user's choice. brigade asks it when a restaurant opens. Any other coordinator asks once per repository with the host's question tool, unless the user already said.

The stored-contract rules live in contract.md.

merge and push let reviewed changes reach trunk with no human gate. When the PR needs an approving review, or when it has changes requested, the queue pauses and names the PR and that requirement. It does not run gh pr merge --auto. The user then either relaxes the rule for the queue or switches to human.

Checks are the repository's own test, type check, and lint gates. In push and local mode there is no pull request or CI behind the queue, so the checks are the only gate. land.py init and land.py status print a warning while those modes have none. The warning is advice only and never changes an exit code. --setup installs dependencies, because the queue's worktree is cleaned with git clean -ffdx before every attempt. land.py mode switches between merge, human, and push once nothing is queued, landing, or awaiting merge. land.py mode --merge-method changes the method the next gh pr merge uses, and it may run while entries are queued, landing, or awaiting merge. Changing trunk or remote, or moving to or from local, needs a new contract.

Run writers through it

The runtime's Modes section sets the mode lines of every brief this skill writes and how its spawns run in light mode.

For every unit of writing work:

1. Claim. lease claim the files and directories the unit will change, before delegating. When the claim is refused, fold the unit into the holder's work or hold it until that lease is released. A cap refusal names every holder in flight. Hold the unit until one of them releases. Never claim . unless the unit really touches everything. lease renew extends a live lease. Renewing an expired lease is a new claim on its paths. It is refused when another holder's lease now overlaps or the cap is full, and the refusal names which. --if-live refuses an expired lease instead, so admitting it again is always a separate step taken after the old worker stopped.
2. Brief. A writer is a worktree thread from t3_thread_launch when it runs long or the user should see it, and a delegate_task child otherwise. Isolate a delegated writer per the runtime's Isolation section. Use the required landing base, which can differ from the parent's current commit. Tell the worker to work only in its own worktree branched from <remote>/<trunk> (or refs/landing/<trunk> in local mode), change only the leased paths, keep history linear with no merge commits, run builds and tests through land.py slot -- and every benchmark or timing measurement through land.py slot --exclusive --, commit, and report the branch and head SHA. Put rule 3 in the brief unchanged.
3. Review the exact SHA with a verifier from another model family, or a same-family seat when only the author's family has a runnable seat, per the coordinator's own review step.
4. Submit that SHA with the lease and the reviewer. In merge and human mode, pass --title and --body-file so the PR says what changed and how it was verified. The queue sends the submitted title unchanged. It sends the body unchanged unless the contract sets prItemLine to on, which adds the item's Kind and Goal line when it has one. The line follows body text after one blank line or is the whole body when the body holds only whitespace. With no --body-file, the body is the reviewed commit's body. The reviewer stays in the queue's local store. A submit that changes paths outside the lease is refused. Widen the lease or split the change.
5. Land. Run land. When it prints queue busy, run land again, at most 3 more times, waiting 5 seconds before each try.
6. Settle. Read status E<n>.

• landed: the lease is released. Record it in the coordinator's tables, then remove the worker's worktree with git worktree remove and delete its branch.
• bounced: the lease is active again for the fix. Resubmitting prints a new entry id. Call unwatch_pull_request on the bounced PR. Fire a fresh worker with the original brief, the bounce reason, and trunk. For a size bounce, read File size limit. A conflict or a changed rebase needs a new review after the fix. A reason that reads commit <sha12> has author <name> <<email>>, not the configured <name> <<email>>; recommit it as the configured author says the entry has a foreign commit author. The contract's authorPolicy decides this check. any never bounces on authorship. configured and credited compare each commit between the entry's base and its reviewed commit with git config user.name and git config user.email, and they run only when both have a value. configured bounces an entry with a reviewed commit whose author is not that identity. credited bounces it too unless every such commit carries a Co-authored-by trailer equal to its author as name <email> and the body has a line that reads Based on #<n> by @<login> with an optional trailing period. The body is the --body-file text, or the reviewed commit message body when that text is empty or absent.
• awaiting-merge (merge and human mode): the PR is open. Pull request lifecycle says what the next land does with it.

Keep the queue moving

While any entry you submitted is queued or awaiting-merge, keep the queue moving. Drains from other coordinators on the same repository are harmless, because the queue lock runs one at a time. land prints every holder's entries. Act only on lines whose holder is this coordinator's own, and call watch_pull_request only on those PRs. A sibling's PR is the sibling's to watch. When a sibling's land opens your PR, read its URL from your own status --holder <restaurant>/<dish>, which brigade's watch prints as awaiting merge <pr url>.