jinaga-server 3.7.4 → 3.8.0

package/.claude/skills/degrees-of-freedom/.openskills.json

@@ -0,0 +1,7 @@
+{
+  "source": "michaellperry/skills",
+  "sourceType": "git",
+  "repoUrl": "https://github.com/michaellperry/skills",
+  "subpath": "skills/degrees-of-freedom",
+  "installedAt": "2026-10-15T03:05:22.754Z"
+}

package/.claude/skills/degrees-of-freedom/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: degrees-of-freedom
+description: Scores a design, a specification, or an issue's requirement against the degrees-of-freedom constitution — whether a representation has exactly as many independent variables as the problem it represents. Use when a repository names this constitution under ## Authority or in its contributor docs, when an issue's Conformance section cites one of its articles, when reviewing a design for invalid states, redundant state, forbidden combinations, or coupling that ripples across sites, or when deciding whether to remove a redundant copy of a fact or to guard it with a check.
+---
+
+# Degrees of freedom
+
+The constitution is [degrees-of-freedom-constitution.md](degrees-of-freedom-constitution.md), beside this file. Read it in full before you cite it. It is short, and every citation depends on its exact wording.
+
+## Citing it
+
+Cite an article by its number, as `Art. 2`, and quote the sentence you are relying on. Part IV is the evaluation procedure: its questions name the articles they test. The Appendix states where the constitution accepts a compromise, so read it before you call a trade-off a violation.
+
+## Where it governs
+
+Only in a repository that adopts it, by naming it as authority — under `## Authority` in `.night-shift/config.md`, or in its own contributor docs. Nothing outside such a repository is held to it.
+
+An adopting repository installs this skill and commits it, and changes it only by refreshing from this repository. Its copy is never edited in place, so every adopting repository cites the same text.

package/.claude/skills/degrees-of-freedom/degrees-of-freedom-constitution.md

@@ -0,0 +1,142 @@
+# A Constitution of Degrees of Freedom
+
+*A basis for evaluating whether a system's representation is faithful to its problem.*
+
+---
+
+## Preamble
+
+Every system carries two spaces. There is the **problem space**: the set of situations the system must genuinely distinguish and respond to. And there is the **representation space**: the set of configurations the system can actually hold, whether in code, state, or configuration.
+
+A system is well-designed to the exact degree that these two spaces are the same shape. When the representation space is larger than the problem space, the surplus shows up as invalid states, redundant state, forbidden combinations, and coupling. When the representation space is smaller, meaningful variation becomes inexpressible, forcing forks and special cases.
+
+The single governing quantity is the **number of degrees of freedom**: the count of independent variables that can be changed. This constitution holds that a system's degrees of freedom must equal the dimensionality of the problem, no more and no fewer. Everything below is a consequence of that one requirement.
+
+---
+
+## Part I. The Law of State
+
+### Article 1 — Exactness of Freedom
+
+The number of independent variables equals the number of dimensions along which the problem can vary.
+
+This is a two-sided bound, not a minimization. Too many independent variables create configurations that must be forbidden. Too few make valid behaviors unreachable. The target is a bijection between what can be represented and what can meaningfully differ.
+
+*Diagnostic.* Count the inputs a user or operator can set independently. Count the axes along which the problem's behavior should actually vary. If the first number exceeds the second, locate the surplus. If it falls short, locate the variation you cannot express without editing code.
+
+### Article 2 — Derivation of Dependents
+
+Only a generating set is stored. Every value that can be computed from that set is computed, never stored alongside it.
+
+Choose a basis (the sources of truth), then derive the rest by projection. A shared secret is defined once and deployed to both ends. Dependent props descend from a common `useState`. The dependent value has no independent existence, so it cannot drift, and it contributes no degree of freedom of its own.
+
+*Diagnostic.* Look for the same fact maintained in two places, for "keep these in sync" comments, and for update anomalies where changing one field silently invalidates another. Each is stored dependent state that should have been derived.
+
+### Article 3 — Totality of Meaning
+
+Every configuration the system can represent is meaningful. No representable state denotes an error.
+
+A reachable error state is not a bug to be caught. It is evidence that the representation admits a configuration the problem does not contain. The remedy is not a validation check that rejects the state at runtime. It is a representation in which the state cannot be formed. Make illegal states unrepresentable, and the validation becomes unnecessary because it becomes vacuous.
+
+*Diagnostic.* Enumerate the runtime validations that reject inputs the type system or schema permits. Each such guard marks a gap between representation and meaning. Ask whether the representation could be narrowed until the guard has nothing left to reject.
+
+### Article 4 — Canonicity of Representation
+
+No two distinct representations denote the same meaning.
+
+This is the dual of Article 3. Article 3 forbids representations with no meaning; Article 4 forbids distinct representations with identical meaning. Redundant encodings, dead configuration, and flags that produce indistinguishable behavior are all surplus freedom that per instance is harmless but in aggregate invites drift and confusion. The representation should be the quotient of the raw space by semantic equivalence: one representative per meaning.
+
+*Diagnostic.* Search for two configurations that are always behaviorally identical, for options whose values never change any observable outcome, and for encodings with more than one spelling of the same intent.
+
+> **Theorem (Faithful Representation).** Articles 1 through 4 hold jointly if and only if the map from representation space to meaning space is a bijection. Article 3 gives totality (the map is defined everywhere). Article 4 gives injectivity (no collisions). Article 1 fixes the dimension of the domain to match the codomain. Article 2 is the constructive method by which the domain is reduced to its true dimension.
+
+---
+
+## Part II. The Law of Behavior
+
+### Article 5 — Stratification by Rate of Change
+
+Behavior is layered by how often it changes. Decisions that change frequently are expressed high, where they are cheap to change and broad in reach. Mechanism that changes rarely is expressed low, where it is stable.
+
+Layers sheared by their rate of change do not grind against each other. A frequently revised decision that lives inside stable mechanism forces the mechanism to change at the decision's pace, which is the definition of friction.
+
+*Diagnostic.* Chart what changed in the last several revisions and where the change landed. If high-frequency decisions require edits to low-level mechanism, or if a routine policy change demands a code deployment, the layers are misassigned.
+
+### Article 6 — Specification over Process
+
+High-level behavior is stated declaratively and read like a specification. It says what holds, not how it is carried out. Stable machinery, a DSL or an interpreter or a framework, gives the specification its operational meaning.
+
+A single specification governs many processes at once, because the machinery that reads it is shared. This is where Article 5's high layer acquires its reach: one declarative statement, many affected processes.
+
+*Diagnostic.* Read the top layer aloud. If it reads as a sequence of steps rather than a statement of intended properties, behavior is still bound to process. Ask how many processes a single change at this layer affects. One is a warning sign.
+
+### Article 7 — Closure of the Specification Language
+
+Every well-formed specification denotes valid behavior. Changing a specification yields new valid behavior, never a bug.
+
+This is Articles 3 and 4 applied to the specification layer itself. The specification language is a state space, and the same demand governs it: no well-formed sentence should be meaningless or erroneous. When the language is closed in this sense, its guarantees are structural. The author of a specification cannot express an invalid behavior because the grammar and semantics have already absorbed the invariants. The constitution is self-similar: the discipline that governs runtime state governs the language in which behavior is written.
+
+*Diagnostic.* Attempt to write a syntactically valid specification that produces a broken system. Every way you succeed is an invariant the language failed to enforce and pushed onto the author's vigilance.
+
+### Article 8 — Independence of Axes
+
+Changing one part of a specification requires no corresponding change in another part.
+
+Where two parts must change together, the co-varying quantity is a single degree of freedom wearing the costume of two. This is the deep identity in the constitution: **accidental coupling is latent redundancy.** The shared quantity should be named once and derived into both sites, which returns the problem to Article 2. Essential coupling, the kind the problem genuinely imposes, is not eliminated. It is expressed exactly once, inside the derivation, rather than replicated across the sites it governs.
+
+*Diagnostic.* Look for changes that ripple: one intended edit forcing several coordinated edits elsewhere. Trace the ripple to the quantity being kept consistent by hand, and derive it from a single source instead.
+
+---
+
+## Part III. The Unifying Law
+
+Invalid states, redundant states, forbidden combinations, and rippling coupling are not four defects. They are one defect seen from four angles.
+
+> **The representation space has more degrees of freedom than the problem it represents.**
+
+- Surplus freedom that maps to *no* meaning appears as an **invalid state** (Article 3).
+- Surplus freedom that maps to a *duplicated* meaning appears as **redundancy** (Article 4).
+- Surplus freedom constrained *after the fact* appears as a **forbidden combination**, which is a constraint the representation failed to absorb (Article 1).
+- Surplus freedom split *across sites* appears as **coupling**, the hand-maintained consistency of what should have been one derived value (Article 8).
+
+Reduce the degrees of freedom to the dimensionality of the problem and all four dissolve together.
+
+---
+
+## Part IV. Evaluation Procedure
+
+To score a system against this constitution, answer each question. Every "yes" localizes a specific surplus and names the article it offends.
+
+**On state**
+
+1. Can I represent a state I would then have to forbid, reject, or guard against? *(Art. 1, 3)*
+2. Is any value stored that could be computed from other stored values? *(Art. 2)*
+3. Do two distinct configurations ever produce identical behavior? *(Art. 4)*
+4. Does the valid range of one variable depend on the current value of another? *(Art. 1, 8)*
+
+**On behavior**
+
+5. Do frequently changing decisions live inside rarely changing mechanism? *(Art. 5)*
+6. Does the top layer read as steps rather than as a specification of intent? *(Art. 6)*
+7. Can a well-formed specification produce a broken system? *(Art. 7)*
+8. Does one intended change force several coordinated changes elsewhere? *(Art. 8)*
+
+A system honors the constitution when both of these are true:
+
+> There is no state I can represent that I must then forbid, and there is no state I must keep consistent by hand.
+
+The first clause is the state law (Part I). The second is the behavior law (Part II). Together they assert the bijection between representation and problem that the Preamble demands.
+
+---
+
+## Appendix. Boundaries and Tensions
+
+A constitution is more useful when its limits are stated, so that a compromise can be recognized as a compromise rather than mistaken for a violation.
+
+**Deliberate physical redundancy is permitted; conceptual redundancy is not.** A cache, a denormalized read model, or a replica adds redundant *storage* for performance or fault tolerance. This is consistent with the constitution provided the redundant copy is a pure function of its source, is regenerable, and is never authoritative. The conceptual degrees of freedom are unchanged because the source alone determines meaning. The test is whether the copy could be dropped and rebuilt with no loss.
+
+**Essential coupling is expressed, not erased.** Article 8 removes accidental coupling. It does not deny that the problem itself couples some quantities. Genuine coupling belongs in the single derivation that produces the coupled values, where it is stated once, rather than replicated at every site those values appear.
+
+**Minimality is exactness, not compression.** Driving degrees of freedom *below* the problem's dimensionality, whether by clever encoding or by collapsing distinctions the problem actually makes, is a violation of Article 1 as surely as surplus freedom is. The aim is a faithful representation, not the smallest one. Legibility is part of faithfulness.
+
+**Invariants must live somewhere.** Making illegal states unrepresentable moves an invariant from a runtime check into the structure of the representation or the semantics of the language. It does not make the invariant free. The work is in choosing a representation whose shape encodes the constraint, so the cost is paid once at design time rather than repeatedly at runtime and in the author's attention.

package/.claude/skills/night-shift-setup/.openskills.json

@@ -0,0 +1,7 @@
+{
+  "source": "factoryengineering/skills",
+  "sourceType": "git",
+  "repoUrl": "https://github.com/factoryengineering/skills",
+  "subpath": "skills/night-shift-setup",
+  "installedAt": "2026-10-15T02:59:05.063Z"
+}

package/.claude/skills/night-shift-setup/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: night-shift-setup
+description: Stands up the night-shift protocol for an organization, from nothing to a running nightly sweep. Creates the Night Shift Log application from a committed seed, registers the practice and each tracked repository exactly once, writes the per-repository configuration file the worker refuses to run without, and creates the scheduled sessions that fire the sweep. Use when adopting the night-shift protocol for the first time, when adding a repository to an existing practice, or when a run stopped because it found no practice or no repository matching the one it was sweeping.
+---
+
+# Night Shift Setup
+
+The night shift is a coordinator that sweeps a labelled issue queue and one worker per repository that takes a single issue to a pull request. Neither keeps state between runs, so both read a log, and the log is an application you create once and share across every repository you track.
+
+This skill covers the one-time acts. `night-shift-coordinator` and `night-shift-worker` cover everything that happens nightly.
+
+## When to use
+
+- **Adopting the protocol** for the first time in an organization.
+- **Adding a repository** to a practice that already exists.
+- **A run stopped** because it found no practice, no matching repository, or more than one of either.
+- **A run stopped** because a repository's configuration file was missing a required heading.
+
+---
+
+## What you are building
+
+| Piece | Where it lives | How many |
+|---|---|---|
+| The Night Shift Log application | your Factual workspace | one per organization |
+| A practice, and one repository record per tracked repository | inside that application | one practice, one record each |
+| `.night-shift/config.md` | each tracked repository | one per repository |
+| `.night-shift/routines.md` | the coordinator's own repository | one |
+| The installed skills | committed into each repository | worker in each tracked repository, coordinator in its own |
+| The scheduled sessions | your agent host | one coordinator, one worker per repository |
+
+```
+Task Progress:
+- [ ] Create the log application and publish the seed
+- [ ] Create the practice, exactly once
+- [ ] Register each tracked repository, exactly once
+- [ ] Write .night-shift/config.md in each tracked repository
+- [ ] Install and commit night-shift-worker and refining-issues in each tracked repository
+- [ ] Install and commit night-shift-coordinator in its own repository
+- [ ] Write .night-shift/routines.md
+- [ ] Create the sessions and fire the coordinator once by hand
+```
+
+---
+
+## Create the log
+
+Read **[creating-the-log.md](creating-the-log.md)**. It publishes `log-model.factual` into a new application, then runs the practice and repository ceremony.
+
+**Two calls in that ceremony are not idempotent.** Creating a practice and registering a repository both mint a new record every time they run, and a duplicate splits your history across two records that nothing joins. Never call either without first running, in the same session, the query that would have found the thing.
+
+---
+
+## Configure each repository
+
+Read **[configuring-a-repository.md](configuring-a-repository.md)**. It lists the required headings, says why each one cannot be derived or defaulted, and gives a filled-in example.
+
+The rule that keeps this from growing back into a second protocol: **anything that is not one of those headings belongs in the skill, not in the config.**
+
+---
+
+## Install the skills
+
+```bash
+npx openskills install factoryengineering/skills
+```
+
+Install `night-shift-worker` and `refining-issues` into each tracked repository, and `night-shift-coordinator` into the repository the coordinator checks out.
+
+`refining-issues` is what fills the queue the worker drains. It is installed beside the worker, in the same repository, because it reads the same `.night-shift/config.md` and audits that repository's issues — and because the bar the queue label asserts should be legible to anyone looking at the repository whose issues carry it. A person runs it; nothing schedules it. **Commit what you install.** A scheduled run that installs from the network at execution time can have its protocol changed by an upstream edit it never reviewed, and gains a failure mode at whatever hour it wakes.
+
+Record which upstream commit each installed copy came from, so a later reader can tell an intentional local edit from an old copy.
+
+---
+
+## Create the sessions
+
+Read **[creating-the-routines.md](creating-the-routines.md)**. Each session's prompt is a loader that names its skill and its configuration file, and nothing more. Protocol restated in a prompt is protocol that can disagree with the skill, and the disagreement will not surface until a run acts on the wrong half.
+
+---
+
+## Verify before you leave it running
+
+1. Fire the coordinator by hand, in daylight, appending `Dry run. Sweep and report; dispatch nothing.` to the message.
+2. Confirm it resolves the practice and every repository, reads each configuration file, and reports a queue per repository.
+3. Let one scheduled run go unattended, then read the sweep back out of the log and check that its dispatch count matches its report.
+
+## Resources
+
+| Resource | Purpose |
+|---|---|
+| [creating-the-log.md](creating-the-log.md) | Publishing the seed, and the one-time practice and repository ceremony |
+| [configuring-a-repository.md](configuring-a-repository.md) | The required headings, with a worked example |
+| [creating-the-routines.md](creating-the-routines.md) | The scheduled sessions and their loader prompts |
+| [log-model.factual](log-model.factual) | Read and send. The log's 47 definitions and its manifest, in four batches |

package/.claude/skills/night-shift-setup/configuring-a-repository.md

@@ -0,0 +1,111 @@
+# Configuring a tracked repository
+
+Every tracked repository carries `.night-shift/config.md` at its root. The worker reads it from its checkout; the coordinator reads the same file over the hosting API; `refining-issues` reads it before it audits anything. There is one copy, in the repository it describes, so the roles cannot disagree about it.
+
+It sits outside `.claude/skills/`, so reinstalling a skill cannot clobber it, and outside `.claude/` entirely, because that directory is agent-harness configuration and this is protocol configuration a person maintains.
+
+## Contents
+
+- [The headings](#the-headings)
+- [What is deliberately not here](#what-is-deliberately-not-here)
+- [Worked example](#worked-example)
+
+## The headings
+
+Every heading in the table below is required. `## Branch prefix` is recognized too, and is optional.
+
+**A missing required heading is a stop, not a default.** A worker that cannot find one names it and opens no pull request. `none` and `Nothing.` are legal values; absence is not, because absence cannot be told apart from an oversight.
+
+| Heading | Why it cannot be derived or defaulted |
+|---|---|
+| `## Visibility` | `private` carries a rule against quoting the repository's contents into any public place. A wrong guess is a leak, and nothing inside the container can tell you. |
+| `## Issue label` | A wrong guess silently sweeps the wrong queue, or nothing at all. |
+| `## Read first` | Which files a worker must read before touching an issue. One repository points at a build guide, another at an accepted specification, another at nothing. |
+| `## Authority` | The documents an issue must answer to, and what citing each one means. `refining-issues` runs R4 against this and nothing else. It is not derivable: which document governs, and whether citing it means naming a section or citing a principle, is a decision about how the project is run. `none` is a complete answer, and it makes R4 vacuous rather than failed. |
+| `## Before you fix` | Where "reproduce first" is replaced by something else, such as conformance criteria a change is held to. |
+| `## Verification commands` | The exact commands, in order, that must be green before every push. |
+| `## CI workflow` | The workflow *file* that gates the merge. Deriving it means parsing every workflow in the repository at whatever hour the run wakes. |
+| `## After the pull request` | Post-pull-request hooks. This is the heading the rule exists for: `none` says a person decided there is nothing, while absence says nobody looked. |
+| `## What is different about this repository` | Free prose for anything the protocol does not fix. `Nothing.` is a complete answer. |
+
+`## Branch prefix` is optional and defaults to `claude/issue-<number>-<slug>`. It is cosmetic, and a wrong guess costs nothing.
+
+## What is deliberately not here
+
+Four values a reader might expect. Each is derivable, and a stored copy can only be wrong later.
+
+- **The repository's owner and name** come from `git remote get-url origin`.
+- **Whether `gh` is installed** comes from `command -v gh`.
+- **Whether stacked pull requests are enabled** comes from `register-stack.sh list` returning exit 3.
+- **Whether a workflow strips the queue label on close** changes nothing a run does, because the protocol always filters for open issues.
+
+**Anything that is not one of those headings belongs in the skill.** This file is where a second, per-repository protocol would grow if it were allowed to, and the closed list is what prevents it.
+
+## Worked example
+
+````markdown
+# Night shift configuration
+
+The `night-shift-worker`, `night-shift-coordinator`, and `refining-issues`
+skills read this file. Every `##` heading below except `## Branch prefix` is
+required. A missing heading is an error, not a default: stop and name the
+heading you could not find. Anything that is not one of these headings is
+protocol, and protocol lives in the skill.
+
+## Visibility
+
+`private`
+
+Never quote this repository's contents into a public repository, issue, or
+pull request. Its sibling repositories are public.
+
+## Issue label
+
+`ready`
+
+## Read first
+
+- `CONTRIBUTING.md` — build commands, subsystem layout, testing rules.
+
+## Authority
+
+- `docs/architecture.md` — the accepted design. An issue names the section it
+  answers to wherever one covers the change. An amendment to it is the
+  maintainer's decision and never lands in an implementation slice.
+
+## Before you fix
+
+Reproduce first. An issue's repro may have been reconstructed rather than
+verified by its reporter, so a repro that fails is a finding, not a failure.
+
+## Verification commands
+
+Both green before every push, in this order.
+
+```
+npm run typecheck
+npm test
+```
+
+`npm test` builds first, so a fresh container needs no separate build step.
+`npm run typecheck` reaches scripts the workspace build leaves out.
+
+## CI workflow
+
+`ci.yml`
+
+Read runs for this file; it is the merge gate. A second workflow also runs on
+pull requests, and neither carries a `branches:` filter, so every layer of a
+stack gets check runs from its own pull request event.
+
+## After the pull request
+
+`none`
+
+## What is different about this repository
+
+Issues carry their own dependencies. Many close with a `Depends on #<n>` line,
+and epics carry an order clause the maintainer rewrites as sessions find
+things, so read the clause on each sweep rather than trusting a remembered
+sequence.
+````

package/.claude/skills/night-shift-setup/creating-the-log.md

@@ -0,0 +1,59 @@
+# Creating the Night Shift Log
+
+## Contents
+
+- [Publishing the seed](#publishing-the-seed)
+- [The practice ceremony](#the-practice-ceremony)
+- [Registering a repository](#registering-a-repository)
+- [References are session tokens, not identifiers](#references-are-session-tokens-not-identifiers)
+
+## Publishing the seed
+
+The log is a Jinaga application reached through the Factual MCP server. Create it once per organization.
+
+1. Open a console. It starts unbound.
+2. `let $apps = applications`. The response lists every workspace you can reach, each carrying its own `ref`. Pick the workspace you want and take that `ref`. Spend it in a **second** call, because a batch that binds and indexes in one go is guessing at an index it has not seen yet.
+3. `create application "Night Shift Log" in <the ref you took>`, on a clean console.
+
+   The indexes are one flat sequence across workspaces and the applications inside them, so the workspace you want is not reliably `$apps[0]`. Read the ref off the response rather than assuming a position.
+4. Send `log-model.factual` in its four marked batches, **in file order**. Do not reorder: fact types precede the specifications that walk them, specifications precede the actions that write them, and within the fact types each one follows every type it names as a predecessor. Sending the batches separately makes a failure name its layer, because a batch stops at its first failure.
+5. `publish` after batch 3. Expect a `manifest_missing` warning; batch 4 is the answer to it.
+6. Send batch 4, then publish again.
+
+**Batch 4 is not decoration.** It carries the routing that lets anything discover the application, and the per-action argument guidance that both night-shift skills tell a run to read instead of trusting a list in a file. An application published without it works and is undiscoverable.
+
+## The practice ceremony
+
+A **practice** is one person's night-shift setup, and one practice covers every repository tracked. It roots at a single-use owner, so you reach it through `practicesForAdministrator` rather than by owning it.
+
+```
+query practicesForAdministrator($me)
+```
+
+| Rows | What it means | What to do |
+|---|---|---|
+| exactly one | Already set up | Use it. **Do not call `createPractice`.** |
+| none | First time | `call createPractice($me)`, then re-run and confirm exactly one. |
+| more than one | Setup ran twice | **Stop.** Two practices split the history. Ask which to keep; `deletePractice` retires the other. |
+
+## Registering a repository
+
+Inside the practice, find the repository whose current name matches the one you are adding.
+
+```
+query repositoriesInPractice($practice)
+```
+
+| Rows matching the name | What to do |
+|---|---|
+| exactly one | Already registered. **Do not call `registerGitHubRepository`.** |
+| none | Read the numeric repository id from the host, then `call registerGitHubRepository($practice, $githubId, "owner/name")`. Re-run and confirm exactly one. |
+| more than one | **Stop.** Two bindings for one repository split the history the same way two practices do. |
+
+The numeric id is what survives a rename or a transfer. The name is a mutable property superseded through `prior`, which is why a rename uses `renameRepository` and never edits anything.
+
+**`createPractice` and `registerGitHubRepository` are the only non-idempotent writes in this system.** Neither may ever sit in a retry or a fallback position. A shell `cmd-a || cmd-b` runs `cmd-b` when `cmd-a` merely prints something unexpected, and that second call is a real write, not a test.
+
+## References are session tokens, not identifiers
+
+A `practiceRef`, a `repositoryRef` and a `nameRef` are scoped to the console that produced them. **Never write one into a configuration file.** Store the application title and the repository name, and re-resolve the references through `practicesForAdministrator` at the start of every run. A stored reference is a value derived from something else, and it goes stale silently.

package/.claude/skills/night-shift-setup/creating-the-routines.md

@@ -0,0 +1,80 @@
+# Creating the scheduled sessions
+
+The night shift runs as scheduled Claude Code sessions: one coordinator on a cron schedule, and one worker per tracked repository that the coordinator fires on demand.
+
+Each worker checks out the repository it works, because it builds, tests and pushes there. The coordinator's checkout is free, since it only reads and fires, so give it the repository that holds its own configuration rather than borrowing one of the tracked repositories. A coordinator that checks out a tracked repository reads that repository's copy of everything as if it were authoritative for all of them.
+
+## The routine table
+
+The coordinator's repository carries `.night-shift/routines.md`: one row per session, with the session identifier, its role, its prompt file, the repository it checks out, the repository it targets, its token's environment variable name, and its schedule.
+
+One table, not two. The coordinator reads the worker rows to know what to fire; a person reads every row to know what exists. Storing a session identifier in two places is how the two fall out of step.
+
+The token *names* belong in the table. The tokens themselves belong in the session environment, never in a repository.
+
+## Prompts are loaders
+
+A prompt names the skill and the configuration, and stops. Everything else is protocol, and protocol restated in a prompt is protocol that can disagree with the skill it duplicates. The disagreement will not surface until a run acts on the wrong half.
+
+One worker prompt serves every worker session. Nothing in it is repository-specific: the checkout already names the repository, and everything that varies is in that repository's `.night-shift/config.md`.
+
+**Coordinator:**
+
+```
+You are the night-shift coordinator.
+
+Read `.night-shift/routines.md` in this checkout. It lists the repositories to
+sweep, the session to fire for each, and the environment variable holding that
+session's token.
+
+Then follow the night-shift-coordinator skill exactly. That skill is the
+protocol. This prompt is not: where the two disagree, the skill wins, and say
+so in your report.
+
+Budget: <n> dispatches per sweep. State this number in every skip rationale
+that leans on it, and in your report.
+
+Do not poll the workers. End your turn once every fire has returned and been
+recorded, and report what you dispatched, what you skipped and why.
+```
+
+**Worker:**
+
+```
+You are a night-shift worker.
+
+The message you were fired with names one issue in this repository, and may
+name a lower issue to stack on.
+
+Read `.night-shift/config.md` in this checkout, then follow the
+night-shift-worker skill exactly. That skill is the protocol. This prompt is
+not: where the two disagree, the skill wins, and say so in your report.
+```
+
+The budget belongs in the coordinator's prompt rather than in the skill, because it is an operator's choice about one night's capacity and not a property of the protocol. The skill's part is to require that the number be stated wherever a skip leans on it.
+
+## Tool access
+
+The coordinator needs to read issues, pull requests and branches across every tracked repository, and to attach the repositories it does not check out. It needs the Factual MCP server for the log, and the ability to fire the worker sessions. It needs nothing that writes to a repository.
+
+A worker needs the hosting API for issues and pull requests, the Factual MCP server, and permission to run `register-stack.sh` at its installed path. **When the script's path changes, the worker's allowed-tools list changes in the same edit.** A path that no longer matches does not error; the call is simply refused at whatever hour the run wakes, and the chain is silently left unregistered.
+
+**Both roles need the harness's push-notification tool on their allowed-tools list.** A session sends that notification itself, so it does not depend on the routine's own completion-notification setting: the routine setting reports that a run finished, and the tool reports something from inside the run. They are separate mechanisms, and a routine whose completion notifications are off should still deliver one a session sends. **That last point is read from the tool contracts and has not been confirmed against a live run**, so confirm it on the first run below before you rely on it; a run whose only way of reporting an unreachable log is a notification that never arrives reports nothing at all.
+
+## Keeping prompts and files in step
+
+The prompt files live in the coordinator's repository; the live prompts live in the routine API. They drift the moment one is edited without the other.
+
+Sync in one direction only, from the files to the sessions, and make it a reviewed step rather than something a run does to itself:
+
+1. Read the live prompt.
+2. Archive it verbatim if no archived copy exists yet. That copy is the rollback.
+3. Compare against the file. Identical means nothing to do.
+4. Write the file's contents, with the tool list and the checkout, in one update.
+5. Read it back and confirm it matches. **If it does not, report the difference and stop. Never retry a write.**
+
+## First run
+
+Fire the coordinator by hand, in daylight, appending `Dry run. Sweep and report; dispatch nothing.` Confirm it resolves every repository and reports a queue for each. Only then let the schedule run it unattended.
+
+**Confirm the push notification on that same run**, by appending `Send a push notification saying the dry run started.` and watching for it to arrive. Do it with the routine's own completion notifications set the way you intend to leave them, because that is the combination the night shift will actually run in. If nothing arrives, the unreachable-log rule in `night-shift-log.md` has no way to reach anyone, and the tool list or the routine's settings need fixing before the schedule takes over.