jinaga-server 3.7.5 → 3.8.0

package/.claude/skills/refining-issues/SKILL.md

@@ -0,0 +1,327 @@
+---
+name: refining-issues
+description: Turns a backlog issue in a night-shift repository into one that an unattended agent can implement, and turns a coupled set into a chain that stacks. Use when auditing whether an issue is ready for the queue label, when grouping issues for planning, when an issue's acceptance ends in an unmade decision, when two issues must land together, when an issue asks for a test that guards a redundancy rather than removing it or manufactures one by quoting a document, or when a change to an authority document has just changed how a set of issues is partitioned. Encodes eight checks — five that decide readiness and three that decide independence — plus the five moves that fix a failed check.
+---
+
+# Refining issues
+
+An issue is finished refining when an agent holding no context but the issue
+body can implement it, and when landing it leaves the tree in a state somebody
+would ship.
+
+That is the bar the queue label asserts. `night-shift-worker` is what consumes
+it: a scheduled agent reads the issue, the documents it cites, and works it with
+nobody watching. Refining is what makes that possible. Applying the label is the
+maintainer's call, never yours.
+
+**Read `.night-shift/config.md` before you refine anything.** Three of its
+headings decide how these checks run: `## Issue label` names the queue this
+repository sweeps, `## Authority` names the documents an issue answers to and
+what citing each one means, and `## Before you fix` says what the night shift
+accepts as warrant. A missing required heading is a stop here for the same
+reason it is a stop for the worker — say which one you could not find, and
+refine nothing.
+
+Eight checks decide it. Run R1 to R5 against one issue. Run I1 to I3 across a
+set. Each failed check has one move.
+
+Do not rewrite an issue that passes. A well-argued problem statement that
+already carries criteria that can be shown false is done, and adding structure
+to it costs review attention for nothing.
+
+## Readiness — run against one issue
+
+### R1. Criteria
+
+Does the issue state acceptance criteria, and can each one be shown false?
+
+A criterion names an observable change. "The importer refuses a row whose date
+is not ISO-8601, naming the row and the value" is a criterion. "Add date
+validation to the importer" is a task.
+
+What shows a criterion false depends on what the issue delivers.
+
+- **Behavior in code.** A test that drives the behavior, and can fail when
+  the behavior is wrong.
+- **A document or a declaration.** A check that does not restate the text,
+  and can fail when the document is wrong. The check derives its expectation from the code the document
+  describes, runs the document's examples through the parser or compiler, or
+  reads an outcome in use, such as a live run whose recorded cost disagrees
+  with the declared one.
+- **A document with no such check.** A reviewer reads a stated property of the
+  page and sees whether it holds. "The section shows the token counts and the
+  prices it multiplies" is a property. "The rate is derived correctly" names a
+  method, so no reader can see it fail.
+
+Do not add a test to make a criterion pass R1. A test that fails only when
+somebody edits the text it asserts on shows nothing false, so it cannot be what
+satisfies a criterion, and `night-shift-worker` holds its regression tests to
+the same bar. An acceptance that asks for one fails R5.
+
+Fail R1 when the acceptance section is absent, or when it is a checkbox list of
+work items, or when a bullet reads "resolved by a decision about X". That last
+form is the most common miss, because a decision sitting in the criterion slot
+looks like a criterion.
+
+### R2. Capability
+
+Does the issue say what a caller can do after it lands that they cannot do now?
+
+Read the acceptance and answer the question out loud. If the answer is a
+restatement of the tasks, the issue describes work rather than an outcome.
+
+R1 and R2 fail independently. An issue can carry twelve well-formed checkboxes
+and still never say what changes.
+
+### R3. Premise
+
+If the issue claims a caller *cannot* do something, find the mechanism in code
+before you accept the framing.
+
+An issue that opens with a capability gap and then offers directions has often
+not proved the gap. Search the project's own user-facing documentation first —
+its README and whatever `## Read first` names — because a capability that exists
+is usually documented there already. Then read the source.
+
+A wrong premise does not produce a wrong answer. It produces a correct answer
+to the wrong question, and every direction under it reads as reasonable. The
+cost is a large fix where a small one was needed.
+
+**A decision already recorded is not a gap.** Where an authority document
+records decisions taken, or tensions accepted as compromises, an issue whose
+premise is "the project should not have decided X" is arguing with that record
+rather than reporting a defect. That is a maintainer's question, not a slice:
+say so and stop. What survives such an issue is whatever observable defect it
+noticed in passing, scoped down to that.
+
+### R4. Anchor
+
+Does the issue cite the documents `## Authority` names, in the form that
+heading describes?
+
+The night shift treats the issue body as an index into those documents, not as
+a substitute for them. Authority usually comes in two roles, and a repository
+may declare either, both, or neither:
+
+- **What was decided.** A specification, an accepted design, an RFC. An issue
+  names the sections it answers to. Without them the agent guesses which
+  requirement it is implementing.
+- **What decisions answer to.** A constitution, a set of principles, a review
+  rubric. An issue carries conformance criteria citing the ones each criterion
+  answers to. Without them a change can pass every test and still offend the
+  principle the repository holds itself to.
+
+Fail R4 when the issue omits something `## Authority` requires. The fix is to
+read the document and supply the citation, not to invent a requirement. Where no
+section covers the behavior the issue wants, the issue is asking to amend the
+document — which is the maintainer's decision, by the route `## Authority`
+names, and never an implementation slice's to take.
+
+**Where `## Authority` says `none`, R4 is vacuous. Record it as passed and say
+why.** A repository that holds its issues to no document is a repository where
+this check has nothing to read, which is not the same as an issue that skipped
+it. R5 still runs: it does not depend on R4's documents.
+
+### R5. Remedy
+
+Does the issue prescribe a remedy that removes the defect, or a guard that
+stands over it?
+
+Where `## Authority` names principles, R5 also asks whether the requirement
+obeys the one the issue cited. That is independent of R4: an issue can cite a
+principle correctly and then ask for precisely what it diagnoses. Where
+`## Authority` says `none`, R5 still runs on the reasoning below, which needs no
+document behind it.
+
+The shape is a value written in more than one place, and an acceptance that asks
+for a test asserting the copies agree. The redundancy is the defect. A test over
+the copies leaves every copy standing, adds one more thing to maintain, and goes
+red only when somebody edits one of them — so it converts a problem you could
+have removed into a problem you now have to keep. The remedy is not a check that
+rejects the disagreement; it is an arrangement in which the copies cannot
+disagree, because there is only one.
+
+Ask which copy is the source of truth, and whether the rest can be derived or
+deleted. When they can, that deletion is the requirement, and the test that
+would have guarded them has nothing left to compare.
+
+**The shape has a second form, and it is the one that slips through.** Sometimes
+the fact is written in exactly one place, and the acceptance asks for a test
+that quotes it: "a test reads the built declaration and finds `byte-stable`", "a
+test asserts the page names both rejection types". No pre-existing redundancy
+exists to point at, so the first form does not match. The redundancy arrives
+with the test. The criterion underneath is usually sound — a property of the
+page that a reviewer can see hold or fail, which is what R1 asks of a document.
+Only the test is the copy.
+
+Both forms answer one question: what could this test go red for? When the answer
+is "somebody reworded the thing it quotes", the acceptance is a copy — whether
+it guards a redundancy that was already there or manufactures one that was not.
+
+Fail R5 when the acceptance's subject is agreement between two representations
+of one fact — a runtime validation, a lint, a CI step, or a test — rather than
+the removal of one of them. Fail it too when the acceptance asks for a test
+whose only possible failure is an edit to the text it quotes, even where that
+text is the only copy in the tree. The move is **Remove the freedom** for both,
+though the second form has less to remove.
+
+Run R5 after R4 where `## Authority` names principles, because the cited one is
+part of what R5 reads: an issue that fails R4 offers nothing to check the
+requirement against. Where it says `none`, the order does not matter.
+
+## Independence — run across a set
+
+### I1. Reference
+
+Do this issue's acceptance criteria name another issue's outcome?
+
+That is the whole test. Two issues that edit the same file are independent when
+neither one's criteria mention the other. Two issues that share no file are
+coupled when one's check is satisfiable while the other's hole is open.
+
+Coupling lives in shared invariants. A shared file is not coupling.
+
+When the answer is yes, the coupling has to reach the issue body as a *Depends
+on* line. The night shift sequences off that declaration alone and does not
+infer order from the files an issue touches, so an undeclared dependency is
+invisible to it: two sessions take the coupled pair, both branch from `main`,
+and produce conflicting patches for one design. A declared one becomes a stack.
+
+The reverse costs too. A *Depends on* that no criterion needs makes a free issue
+wait for a blocked one, and the night shift will honor it.
+
+### I2. Dimension
+
+Does the code this issue reads conflate the axis it cares about with another?
+
+An issue inherits the dimensionality of what it reads. A predicate that ORs two
+independent axes into one boolean forces every issue touching it to depend on
+both, whether or not it cares about both. The dependency sits in the code rather
+than in the work.
+
+Hand-maintained consistency across two sites is one degree of freedom wearing
+the costume of two, and the ripple it produces is coupling. An issue that fails
+I2 has found surplus freedom in the representation. Where `## Authority` names
+principles, saying which one it offends is usually the clearest statement of the
+fix.
+
+Fail I2 when the issue must wait for a decomposition rather than for a
+behavior.
+
+### I3. Intermediate
+
+For each order of a coupled pair, is there a state worth shipping in between?
+
+Write the criterion for the halfway point. Usually one order has a coherent
+intermediate and the reverse does not, and that asymmetry is the ordering.
+
+The danger this check catches is specific. Whichever issue of a coupled pair
+lands first ships a green test suite asserting a partial invariant, and a
+passing test that claims coverage it does not have goes into every committed
+baseline as real signal.
+
+Once the order is written down, the pair costs nothing in wall-clock: the upper
+layer branches from the lower one's branch and opens a stacked pull request, so
+neither waits for the other to merge. Ordering is what the night shift needs;
+serialization is not.
+
+## The five moves
+
+**Extract a decision.** Several issues stalling on "Directions:" or "Decide
+first" are often stalling on one decision in different words. Record it once,
+outside all of them, in a design note kept wherever this repository keeps them.
+Every issue that depended
+on it becomes independent with no change to its scope. Answering separately
+produces answers that need not agree. When the decision is one the spec already
+owns — a default, a vocabulary choice, a division of responsibility — the note
+is not yours to write: it is an amendment, and it lands by the route
+`## Authority` names, by the maintainer.
+
+**Remove the freedom.** When R5 fails, name the source of truth and rewrite the
+acceptance as the deletion or derivation of every other copy. The guard the
+issue asked for goes with them: with one statement left there is nothing to
+compare. The guard does not need removing separately; it becomes vacuous.
+
+Write two consequences into the issue. Say that no test asserting agreement is
+to be added, because an agent reaching for evidence will otherwise supply one
+and restore the freedom the issue just removed. And where one of the copies
+lives in a document `## Authority` names, deleting it is an amendment, so the
+issue has to declare itself one in its title and its acceptance. The night shift
+stops and asks rather than guessing which kind of issue it holds.
+
+Where the acceptance manufactures the copy rather than guarding one, there is
+nothing to delete and the move is smaller: strike the test and keep the
+criterion as a property a reviewer checks, or replace the test with one that
+derives. A derived criterion names something the *code* can
+falsify — a documented example that compiles against the shipped build, a
+documented path that resolves against the filesystem, a default read back out of
+the object the factory built. Each fails when the code changes, which is the
+failure a document cannot produce on its own.
+
+Where nothing derives, say so in the issue: the documentation stands on review,
+and no test is to be added. That sentence is load-bearing for the same reason it
+is in the first form. An agent held to a regression test, reading an acceptance
+that names a sentence, will quote the sentence back.
+
+**Decompose the axis.** When I2 fails, the fix belongs to whichever issue owns
+the separation rather than to the issue that noticed it. Decomposing the predicate is
+what makes the other issues perpendicular, so it is scope for the owner rather
+than a new issue.
+
+**Define the intermediate criterion.** When I3 finds a coherent halfway state,
+give it to the issue that lands first. This converts a must-land-together pair
+into a sequence, and it moves the shared invariant out of the gap and into an
+issue that owns it. A note reading "whichever lands second must not reopen this"
+is prose, and prose does not run.
+
+**Split.** An issue holding more than one concern splits, even when the parts
+share a file. Prefer the split when one part is unblocked today and another
+waits on a dependency, because bundling makes the free part wait.
+
+## Worked example
+
+`references/worked-example.md` runs R1 to R3, R5, and I1 to I3 plus both
+structural moves over one backlog, and closes each with the shape to recognize. The domain
+is invented so nothing in it decays as a real backlog is worked. Read it when a
+check's description is not enough to recognize what is in front of you.
+
+R4 has no shape section because it is a presence check: the sections are named
+or they are not.
+
+## Writing the refined issue
+
+Write the title as the defect, then "so", then the consequence. "`start()` has
+no bound, so an unreachable server holds a boot path open."
+
+Body leads with what happened or what the mechanism is, cites the code by path
+and line, and closes with acceptance. A serviceable order: the mechanism in
+prose; **Measured** or **Demonstrated**, showing the behavior against something
+real; **Build** or **Proposal**; **Tests**; **Conformance**, naming what each
+criterion answers to; **Depends on**. Drop **Conformance** where `## Authority`
+says `none` — a heading with nothing to cite is a heading that gets filled in
+with something invented.
+
+A documentation slice may carry no **Tests** entry at all: its criteria are
+properties a reviewer checks, which R1 accepts. Every entry that is there has to
+be able to fail for a reason other than an edit to its own subject. This is the
+sentence R5 most often catches too late: a documentation slice feels like it
+needs a test, a quotation is the only one available, and writing it here is what
+puts it in the suite. The night shift implements the acceptance it is given.
+
+Name the interaction with any issue that shares an invariant, and say which one
+must not reopen the gap.
+
+Say plainly what the issue no longer claims when a check removed part of it. A
+reader who remembers the old framing needs to know it is gone, and the removed
+argument does not belong in the body. This is `CLAUDE.md`'s no-reversed-decision
+rule applied to a tracker: the refined issue describes only what is wrong now.
+
+Refining destroys the evidence. An issue that passes the checks no longer shows
+the defect that made it fail them, and a tracker keeps no body history a later
+reader can reach. GitHub's timeline API returns `renamed` and `labeled` events
+and never the previous body.
+
+So an issue is a poor place to point somebody who needs to learn a shape. It is
+also a decaying one, because the code a good example quotes is usually the code
+the issue deletes. Teach from a constructed case that holds the shape, and keep
+the issue number as provenance for a reader who wants the original.

package/.claude/skills/refining-issues/references/worked-example.md

@@ -0,0 +1,234 @@
+# Worked example
+
+One backlog. The project is a deployment CLI: it builds an artifact, deploys it
+to staging, and promotes a staging build to production.
+It has an auth check on its deploy API, a `--dry-run` flag, and a `help`
+command.
+
+The domain is invented so the shapes stay legible outside any one codebase.
+The shapes are not. See Provenance at the end.
+
+## R1 Criteria — a decision in the criterion slot
+
+An issue lists four confusing error messages and closes with acceptance. Three
+bullets can be shown false. The fourth:
+
+> - Case 4 is resolved by a decision about which registry format the artifact
+>   digest uses, and the `help` text matches that decision.
+
+It has the grammar of a criterion. It names no observable change and cannot be
+shown false, because what it requires is that somebody choose. Three quarters
+of the issue is implementable and the fourth quarter is a question wearing a
+criterion's clothes.
+
+**The shape:** an acceptance bullet whose verb is *decide*, *resolve*,
+*determine*, or *clarify*.
+
+## R2 Capability — a task list that never states an outcome
+
+An issue about unvalidated deploy manifests carries eleven checkboxes across
+design, implementation, and rollout, plus a stated fix ordering. It reads as
+the most complete issue in the backlog. One bullet:
+
+> - [ ] Add `validateManifest` to `src/deploy/manifest.ts`, sibling to
+>   `loadManifest`: walk the parsed tree and check every referenced image tag
+>   resolves in the registry.
+
+That is a precise task. Nowhere does the issue say what an operator can do
+afterward that they cannot do now. The criterion it lacks is one sentence:
+*deploy refuses a manifest that references an image tag the registry does not
+hold, naming the tag.*
+
+**The shape:** an issue you could hand to an implementer that leaves a reviewer
+unable to say what changed. R1 passes, R2 fails, and the two fail
+independently.
+
+## R3 Premise — a capability gap that was not there
+
+An issue titled "An operator cannot see what a deploy will change without
+running it" opens:
+
+> This issue is a request for a strategy rather than a patch, because the two
+> candidate patches pull against each other.
+
+and offers four directions, the largest of which restructures how the CLI holds
+a plan.
+
+The premise is false. `deploy --dry-run` prints the plan and exits, and
+`help deploy` documents it. All four directions solve a problem that does not
+exist.
+
+One real defect the issue mentions in passing survives: the dry-run output
+omits image digests, so an operator cannot tell two builds of the same tag
+apart. The issue scopes down to that.
+
+**The shape:** an issue that opens with "the caller cannot X" and proceeds to
+directions without ever showing the code that refuses. Check the product's own
+help text before the handler, because a capability that exists is usually
+documented there already.
+
+## R5 Remedy — a guard where the freedom should have been removed
+
+The promote timeout is written in three places: `help promote` prints it in
+prose, `config/defaults.yml` sets it, and the deploy API client hard-codes the
+same number as its own fallback. Nothing ties them together, and they agree
+today by hand. An issue notices this and closes with:
+
+> - A test reads the timeout from all three and asserts they agree.
+
+The criterion is observable and can be shown false, so R1 passes. It names an
+outcome, so R2 passes. The drift is real and demonstrated, so R3 passes. It cites
+the principle its repository holds duplication to, so R4 passes. And it asks for
+exactly what that principle diagnoses.
+
+Three independent variables stand where the problem has one, and the acceptance
+adds a fourth thing to maintain rather than removing two. The remedy is to name
+`config/defaults.yml` the source, have the client read it instead of carrying a
+fallback, and have `help promote` print the value instead of spelling it. Then
+no test has anything left to compare.
+
+**The shape:** an acceptance whose subject is agreement between copies. The
+issue has found surplus freedom and asked for a guard to stand over it.
+
+## R5 Remedy — a copy the acceptance creates
+
+`promote --wait` blocks until the deploy settles, and its help text does not say
+that cancelling the wait leaves the deploy running. An issue adds the sentence
+and closes with:
+
+> - `promote --wait`'s help text says that cancelling the wait does not cancel
+>   the deploy.
+> - A test reads `promote --help` and asserts it contains that sentence.
+
+Nothing is written twice here. The help text is the only place that fact lives,
+and the issue is right that it belongs there. The first bullet is a criterion,
+a property a reviewer can see hold or fail, so R1 passes. It names an outcome, so R2
+passes. An operator really did cancel a wait and assume the deploy stopped, so
+R3 passes. The principle about keeping an explanation in one place is cited,
+correctly, so R4 passes.
+
+The second bullet is not a criterion about the product at all. It prescribes a
+test, and the test is the copy that arrives with the acceptance. It can go red
+for one reason: somebody rewords the sentence. It cannot notice that cancelling
+now *does* cancel the deploy, which is the only thing worth knowing. It freezes
+the wording and leaves the behavior unguarded.
+
+What derives here is the flag, not the sentence. A check that every flag the
+parser registers appears in `--help`, and that nothing else does, fails when
+somebody adds or renames a flag without documenting it — a failure the code
+produces. The refined acceptance keeps the criterion, strikes the test, and
+says no test is to be added for the sentence: it stands on review.
+
+**The shape:** an acceptance that quotes a document back to itself. The first
+form guards a redundancy that exists; this one manufactures one that did not,
+which is why reading for surplus freedom does not find it.
+
+## I1 Reference — a shared invariant across no shared file
+
+Issue A adds an authorization check to the deploy API route. Issue B removes an
+internal scheduler that calls the deploy handler directly, bypassing the route.
+
+They edit different files. They are not independent. A's criteria are all
+satisfiable while the scheduler still reaches the handler, so an unauthorized
+deploy still happens and A's tests are green.
+
+**The shape:** two issues whose criteria are each complete and whose
+conjunction is the actual invariant. Neither body has to mention the other for
+the coupling to be real, which is why the check reads the criteria rather than
+the file list.
+
+## I2 Dimension — waiting on a decomposition rather than a behavior
+
+An issue makes `status` report whether the working tree is safe to switch
+branches. Its first draft:
+
+> - The answer is derived from the state `status` already reports. No new
+>   stored field.
+
+The second sentence is right and the first is wrong. `status` reports one
+boolean that ORs two independent axes:
+
+```
+pending = hasUncommittedEdits() || hasUnpushedCommits()
+```
+
+Branch safety depends on the first alone, and the disjunction loses it in
+exactly the ordinary case:
+
+| `pending` | unpushed | uncommitted edits |
+|---|---|---|
+| false | any | false |
+| true | 0 | true |
+| true | above 0 | unknown |
+
+The third row is the common one. So the dependency is not on another behavior.
+It is on a predicate being split along the axis this issue cares about, and
+that split belongs to whichever issue owns separating the two.
+
+**The shape:** an issue that cannot be stated cleanly because a value it must
+read conflates two things. The dependency sits in the code rather than in the
+work.
+
+## I3 Intermediate — the order falls out of the halfway state
+
+Take the coupled pair from I1 and write the criterion for each order.
+
+**B first.** The intermediate is *every deploy path goes through the route*,
+true by removal alone. Worth shipping on its own. A then adds *the route
+authorizes the caller*.
+
+**A first.** The intermediate is *the route authorizes, except the path that
+skips it*. Not worth shipping, and worse than not shipping, because it lands a
+green test suite over an open hole and that green goes into every later
+baseline as real signal.
+
+Only one order has a coherent halfway state. That asymmetry is the ordering.
+
+## Split — one issue, three concerns
+
+One issue holds four confusing error messages and two stale help topics. Sorted
+by what each part actually is:
+
+- Three message fixes, extending a pattern that already exists, blocked on
+  nothing.
+- One format change with a compatibility rationale, coupled to another issue
+  under I1.
+- Two help topics that are stale because a newer flag replaced what they
+  describe, wrong today for a reason unrelated to either.
+
+Three issues. The message fixes stop waiting on a decision that is not theirs,
+and the help fix stops waiting on both.
+
+**The shape:** a single issue whose parts have different blockers. Bundling
+makes the free part wait for the blocked one.
+
+## Extract — four issues, one decision
+
+Four issues each end without a decision:
+
+- Which component owns retry policy for a failed deploy?
+- Which component owns retry policy for a failed registry push?
+- Should a partial rollout retry the failed shards or the whole batch?
+- Where does the retry budget live?
+
+Four phrasings of one question: which layer owns retry, and against what
+budget. Recording the answer once, in a design note outside all four, makes
+every one of them independent without changing any of their scope. Answered
+separately, they produce four answers that need not agree.
+
+## Provenance
+
+Every shape here was found in a real backlog audit of `jinaga/factual-mcp` in
+September 2026, across issues 351, 373, 377, 404, 405, 406, 412, 415, and 416.
+The R5 shapes came from `jinaga/jinaga-worker`: the first from #52 in the same
+month, the second from #19, #22 and #39, whose acceptance sections each asked
+for a test quoting a document back to itself and got one.
+
+The real cases are not reproduced, for two reasons. They carry domain
+vocabulary that costs a reader more than the shape is worth. And each one
+quotes code that the issue describing it deletes, so a faithful transcript
+starts decaying the moment the backlog is worked.
+
+Read the issues if you want the originals. Expect them to have been refined,
+and expect no previous body to be reachable: a tracker keeps no history of an
+issue's text, so what made an issue fail a check is gone once it passes.

package/.github/workflows/main.yml

@@ -4,11 +4,11 @@ name: CI
 
 # Controls when the workflow will run
 on:
-  # Triggers the workflow on push or pull request events but only for the main branch
+  # Triggers on pushes to main, and on every pull request whatever its base,
+  # so each layer of a stacked chain gets its own check runs
   push:
     branches: [ main ]
   pull_request:
-    branches: [ main ]
 
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:

package/.night-shift/config.md

@@ -0,0 +1,84 @@
+# 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
+
+`public`
+
+There is nothing to withhold here. One sibling repository in this practice is
+private, so never carry its contents into an issue or pull request in this one.
+
+## Issue label
+
+`ready`
+
+## Read first
+
+- `CLAUDE.md` — commands, layers, storage implementations, and where the
+  Specification-to-SQL translation lives.
+- The documents under `## Authority`, at the articles the issue cites.
+
+## Authority
+
+- `.claude/skills/degrees-of-freedom/degrees-of-freedom-constitution.md` — the
+  principles a design answers to. An issue's **Conformance** section cites the
+  article each criterion answers to. 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.
+Report it and open no pull request.
+
+Much of this server's behavior comes from the `jinaga` library it depends on.
+A defect may live there rather than here, and may already be fixed in a newer
+`jinaga` release. Check which side of that boundary the defect is on before
+changing code in this repository.
+
+## Verification commands
+
+Green before every push, in this order.
+
+```
+npm ci
+npm run build
+npm test
+```
+
+The container starts with no `node_modules`, so `npm ci` is not optional, and a
+stale `node_modules` fails the build against types the current `jinaga`
+exports. `npm test` type-checks and runs Jest without a database.
+
+`npm run integration` needs Docker and PostgreSQL and is not part of the bar.
+
+## CI workflow
+
+`main.yml`
+
+Read runs for this file; it is the merge gate. It runs on a bare
+`pull_request:` with no `branches:` filter, so every layer of a stack gets
+check runs from its own pull request event.
+
+`publish.yml` and `upgrade-jinaga.yml` do not gate a pull request. Address the
+workflow by this file name rather than by its display name, `CI`.
+
+## After the pull request
+
+`none`
+
+## What is different about this repository
+
+This is a published npm package whose queue is mostly defects reported against
+released versions. An issue may not reproduce at all, and saying so with
+evidence is the whole result. Do not manufacture a fix to justify the session.
+
+`upgrade-jinaga.yml` opens a pull request daily when a new `jinaga` is
+published, on a branch named `upgrade/jinaga-<version>`. Those pull requests
+are not night-shift work and are not prior work for an issue, unless the issue
+is the upgrade itself.

package/.night-shift/skills.md

@@ -0,0 +1,17 @@
+# Installed skills
+
+These skills are installed here as committed copies. They are not fetched at run
+time: an upstream edit would otherwise change what an unattended run does
+without anyone reviewing it, and a network install adds a failure mode at
+whatever hour the run wakes.
+
+| Skill | Source | Upstream commit |
+|---|---|---|
+| `night-shift-worker` | `factoryengineering/skills` | `2fb85d8297c0a3059365bd809b8242f5657f2740` |
+| `refining-issues` | `factoryengineering/skills` | `2fb85d8297c0a3059365bd809b8242f5657f2740` |
+| `degrees-of-freedom` | `michaellperry/skills` | `3722c778facbfccc609a928d25ffb22e1ba461e6` |
+| `night-shift-setup` | `factoryengineering/skills` | `2fb85d8297c0a3059365bd809b8242f5657f2740` |
+
+To take an upstream change, re-copy the skill directory from its source, update
+its commit above, and read the diff before you push. Local edits to an installed
+skill belong upstream instead, or the next update silently reverts them.