@jjanczur/tyran 0.1.0

package/skills/doctor/SKILL.md

@@ -0,0 +1,35 @@
+---
+description: Check that Tyran itself is healthy in this repo - gates that cannot fire, journal and projection drift, orphaned leases, dead policy rules, config that fails its schema. Reports findings with the fix for each. Use for /tyran:doctor or when a gate seems not to be working.
+---
+
+# Doctor
+
+Three checks, in this order. Run all three even if the first is clean — they
+fail independently.
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/doctor.mjs" --hooks
+node "${CLAUDE_PLUGIN_ROOT}/scripts/doctor.mjs" --state
+node "${CLAUDE_PLUGIN_ROOT}/scripts/schema.mjs" validate config .tyran/config.yaml
+```
+
+**`--hooks` is the one that matters most**, and it is worth saying why. Hooks
+fail OPEN: a gate whose file is missing, whose execute bit was lost, or whose
+matcher can never match does not degrade into a weaker check — the action it
+was meant to stop simply proceeds, with nothing printed anywhere. A dead gate
+and a healthy gate look identical from inside a session. This check is the
+only thing that can tell them apart.
+
+**`--state` compares the journal against its projections** and finds drift,
+leases held by agents that have long since reported, and policy rules that
+match no path in the repo.
+
+## Reporting
+
+Paste the raw output. For each finding give the fix the tool named, and say
+plainly which findings are errors and which are informational — a report that
+blurs the two trains the operator to skim the next one.
+
+If everything is clean, say so in one line with the counts, and resist adding
+advice. A clean doctor run that arrives with a list of suggestions reads as a
+failed one.

package/skills/fidelity-gate/SKILL.md

@@ -0,0 +1,132 @@
+---
+description: Build a UI against a frozen visual reference without drift. An inventory extracted from the reference before any code, a relics list for what exists but should not, and a gate that MEASURES rather than judges - computed styles on a fixture carrying the reference's own data. Use when a mockup, design spec or screenshot is the contract.
+---
+
+# Fidelity gate — building against a frozen visual reference
+
+> Drift that goes uncaught on the first screen multiplies onto every screen
+> after it. Measured on one initiative that skipped this: four waves of
+> rework plus a reconciliation audit, because "looks right" had been accepted
+> as a verdict fourteen times.
+
+## The division of labour, which is the whole idea
+
+**Appearance is read by a MACHINE. Intent is described in WORDS.**
+
+Text, typography, colour, geometry and icons are extracted from the
+reference *mechanically*. Never let a model retype them into prose: every
+restatement is a **lossy copy**, and the source is more precise than any
+description of it — `22px/700/#0a2540` has exactly one interpretation, and
+"large bold dark-blue heading" has hundreds.
+
+Words describe only what a static reference cannot contain: which content is
+an example and which is binding, where the data comes from, visibility
+conditions, the empty state, and the states that do not render (hover, focus,
+error).
+
+## The overriding rule
+
+**The reference is the only source of visual truth.** Handoffs, tickets and
+prose describe BEHAVIOUR; appearance is settled by the reference alone. When
+prose disagrees with the reference about how something looks, **the reference
+wins**, you decide without asking, and you record the divergence.
+
+- An element **not** in the reference **does not exist**. Relics of older
+  code are not carried over without an owner's decision.
+- An element **in** the reference **must be built** — if necessary as an
+  honest-empty version in the reference's own geometry.
+
+## Step 0 — the reference lives in the repo, verified
+
+Pull it into the repo and check it is whole before trusting it: size, the
+file actually ends where it should, and it renders. Work only from the
+in-repo copy. An incomplete reference is a STOP and a report, not something
+to work around — half a contract silently becomes "use your judgement".
+
+## Step 1 — the inventory, before the first line of code
+
+Extract a machine-readable checklist from the reference. One row per element:
+
+| # | Element | Literal text (with capitalisation) | Typography | Colours | Geometry | Icon | States and conditions |
+
+Hard requirements, each of which has been violated at real cost:
+
+- **Literal text**, including format, capitalisation and separators. A 1px
+  rule between two phrases is an element and gets a row.
+- **Icons are carried over VERBATIM** — the reference's own markup or asset.
+  Substituting an icon library because a glyph "looks the same" is
+  forbidden. A similar icon is not that icon.
+- **Every surface with a specific colour, and every line with its extent** —
+  where it starts and where it stops.
+- **Conditional elements carry the condition** in the row.
+
+If the repo has a comparator, it GENERATES the inventory and you only add the
+states column. Write it by hand only where no tool exists yet.
+
+The conductor spot-checks five rows against the rendered reference before the
+work starts. A wrong inventory produces a confidently wrong screen.
+
+## Step 2 — the diff, when the view already exists
+
+Before writing code, every inventory row gets **MATCHES / DRIFT / MISSING**,
+and every element present in the code but absent from the reference goes on a
+**RELICS** list with a disposition: remove (the default) or an owner gate when
+it is load-bearing.
+
+"Apply the differences" without a list of the differences is forbidden. That
+list *is* the plan for the work.
+
+## Step 3 — implement the inventory, and only the inventory
+
+If the reference uses a token, the code uses **that** token. If the reference
+defines a token and never uses it, the code does not use it either. A
+deviation from the reference is only ever a recorded owner decision, never an
+implementer's taste.
+
+## Step 4 — the gate is a MEASUREMENT, not an opinion
+
+1. **A fixture carrying the reference's own data.** Same entity, same period,
+   same numbers. Then every difference in a screenshot is a difference of
+   appearance, not of content — which is the entire reason this step exists.
+2. **Side-by-side captures** at the reference's own widths.
+3. **Computed styles dumped to JSON** for the inventory's selectors and
+   compared against the inventory's values. A disagreement about whether
+   something is 9px or 10.5px is settled by the dump, never by looking.
+   `browser-check` carries how — the capture, the dump, the deterministic
+   waits, and the rule that a zero-size box is a failure rather than a pass.
+   This gate owns the inventory and the verdict; it does not own the browser.
+4. **The verdict is the filled-in checklist**, row by row, attached to the
+   report. A narrative verdict — *"looks consistent"*, *"differences are
+   data-only"* — is REJECTED without it. This is the single rule that decides
+   whether the gate stays a gate.
+5. Failures are fixed in the same piece of work. It does not merge with
+   failures unless the owner says so.
+
+Three things that turn this gate back into an opinion, all observed:
+
+- **A deliberate skip is not a match.** Every deviation carries a reason and
+  lands in an explicit **debt** section of the report.
+- **Raising a tolerance until the run goes green** is forbidden. That is
+  changing the measurement to fit the answer.
+- **A structural selector without a text assertion** silently measures the
+  wrong element when the markup is renumbered. Anchor by an explicit
+  attribute where you can, and always assert the text — a renumbering must
+  produce a loud MISSING, never a quiet wrong reading.
+
+Warm the routes up before a batch run. A cold compile produces failures that
+have nothing to do with fidelity, and chasing them costs a round.
+
+## Step 5 — when the data cannot fill the design
+
+- The element **stays**, honest-empty, in the reference's geometry and style.
+  Hiding a whole section because data is missing needs an **owner decision** —
+  a hidden section is indistinguishable from drift.
+- Missing data is a backend item raised in the report. "Pretty" versus raw
+  values is also a data question; the front end must not hardcode a mask over
+  it without a decision.
+
+## Step 6 — owner acceptance
+
+At the phase gate the owner sees paired captures of full views. The checklist
+catches what is measurable; the owner catches the rest. Neither replaces the
+other, and offering only one of them is how a gate becomes a formality.

package/skills/hello/SKILL.md

@@ -0,0 +1,16 @@
+---
+description: Smoke-test skill that verifies the Tyran plugin is installed and namespaced correctly. Invoke with /tyran:hello.
+disable-model-invocation: true
+---
+
+# Hello (installation smoke test)
+
+Reply with exactly one short paragraph:
+
+1. Confirm the Tyran plugin is loaded and state its version by reading
+   `${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json`.
+2. State the resolved value of `${CLAUDE_PLUGIN_ROOT}` so the user can see
+   where the plugin is installed from.
+
+Do not perform any other action. This skill exists only to verify
+installation, namespacing, and path resolution.

package/skills/pr-feedback/SKILL.md

@@ -0,0 +1,85 @@
+---
+description: Work a reviewer's comments on a pull request to the end. Enumerate all three comment surfaces before triaging any, give every comment a disposition - fixed, declined with a reason, or ticketed - push before you reply, and resolve only what you addressed. Use when a PR comes back with review feedback or a red check.
+---
+
+# PR feedback — closing the loop with a human reviewer
+
+> The safest autonomy class, and the default, ends with a change on a branch
+> and a person merging it. So the ordinary last step of this plugin's work is a
+> pull request somebody reviews — and it was the one step with no protocol.
+> `tyran:reviewer` governs our own internal review; this governs theirs.
+
+## The three surfaces, and why one of them is a trap
+
+GitHub keeps pull-request feedback in three separate resources:
+
+| Surface | Endpoint | What lives there |
+|---|---|---|
+| Conversation | `/issues/{n}/comments` | Plain comments on the PR |
+| Inline review comments | `/pulls/{n}/comments` | Anchored to a line of the diff |
+| Reviews | `/pulls/{n}/reviews` | The submitted verdict **and its body text** |
+
+**A review's body is not in the inline-comments collection.** Reviewers write
+their summary there, and bots put whole findings there — anything that could not
+be anchored to a changed line, which is exactly the "outside diff range" class.
+
+Measured, against a public repository: `cli/cli` PR **#13944** has one review
+carrying a written body and **zero** inline comments. An agent that reads only
+`/pulls/{n}/comments` sees nothing on that PR and reports that there was nothing
+to address. The report is true about what it looked at and false about what it
+claims, which is the failure shape this whole plugin exists to refuse.
+
+So: **fetch all three, paginated, before triaging any of them.** Print the
+counts. `3 inline · 2 review bodies · 1 conversation` is the first line of the
+work, and it is what makes a missed surface visible.
+
+## Every comment gets a disposition
+
+No comment is silently dropped. Each one ends as exactly one of:
+
+- **Fixed** — with the commit that did it.
+- **Declined** — with the reason, in one sentence. Disagreeing is allowed;
+  disagreeing silently is not. If it is a product or scope decision rather than
+  a technical one, it goes to the conductor instead of being decided here.
+- **Ticketed** — real, out of this PR's scope, captured where it will be found
+  again. A promise in a thread is not a ticket.
+
+Nitpicks are answered too, briefly. An unanswered comment reads as unread, and
+the reviewer's next move is to check whether you read the others.
+
+**A comment that names a defect gets pinned as a test**, not just patched. The
+same rule the reviewer applies internally: a finding that cannot be verified as
+fixed will be found again by someone else, later, at more cost.
+
+## Order of operations
+
+1. **Fix, then push, then reply.** "Fixed in `abc1234`" posted before the push
+   is a claim about a commit the reviewer cannot fetch. Push first; quote the
+   real sha.
+2. **Resolve only threads you actually addressed.** Resolving a thread you
+   declined hides the disagreement — say why, and leave it for them to close.
+   Never resolve someone else's open question to tidy the view.
+3. **A red check is feedback.** Read the failing job's own output, not the
+   summary. And gate on the runner's exit code: a pipeline that pipes a test
+   run into `grep` and pushes on success pushes on a red suite too, because
+   `grep` was satisfied.
+4. **Re-check the three surfaces after you push.** Reviews arrive while you
+   work, and CI posts after it finishes. A loop that reads once at the start
+   ends by declaring victory over a snapshot.
+
+## When to stop and ask
+
+- The comment asks for a change that crosses a boundary the story did not own —
+  an API shape, a schema, someone else's module.
+- Two reviewers ask for opposite things. Do not pick; put both in front of the
+  conductor with a recommendation.
+- The review asks for a rewrite large enough to be its own story. Say so with a
+  size, rather than quietly starting it inside a feedback round.
+
+## The report
+
+Counts per surface, the disposition of every comment with its thread, the shas
+that carry the fixes, the checks that are now green with their raw output, and
+anything still open with the reason. If you declined something, that line is the
+most important one in the report — it is the only part the reviewer cannot see
+by looking at the diff.

package/skills/prompt-tuning/SKILL.md

@@ -0,0 +1,102 @@
+---
+description: Iterate on a prompt, or on anything whose quality is measured by non-deterministic model output, without chasing noise. A noise baseline before the first edit, medians over repeated runs, enforcement AFTER generation rather than in the wording, and detectors that surface candidates rather than defects.
+---
+
+# Prompt tuning — working with non-deterministic output
+
+> Every rule here has a measured cost behind it. The first one alone accounts
+> for three tuning rounds spent moving a number that had never moved.
+
+## Measure before you change anything
+
+**1. Take a noise baseline BEFORE the first edit.** Same prompt, same inputs,
+at least two runs; record the spread of every metric you care about. A delta
+smaller than the spread is noise, not the effect of your change. To compare
+two versions, run each at least three times per input and compare **medians**.
+
+Measured: ±20% output length and a jumping paragraph count **with no change
+to the prompt at all**. Three rounds of tuning were spent chasing that before
+anyone ran the same prompt twice.
+
+**2. Measure conversion factors between representations; never assume them.**
+One initiative assumed a 1.15× expansion between two languages and measured
+1.3–1.4×. The assumption would have invalidated the entire budget built on
+it. When a factor's spread is wider than your target band, no source-side
+budget can guarantee the target — catch the tail with a gate **after** the
+transformation instead of tightening the budget before it.
+
+**3. After three failed rewordings of the same defect on the same case, name
+it a KNOWN LIMITATION** and hand it to a human. A fourth blind iteration is
+chasing noise with extra steps.
+
+## Writing the prompt
+
+**4. Every numeric example becomes a quota; every template phrase becomes a
+verbatim anchor.** Describe the CRITERION, not the illustration. "Two threads
+means two paragraphs" produced two-paragraph output in six samples out of
+six, where an example of a two-paragraph answer had not. State criteria in
+**both directions** — a one-sided formulation works only in the direction you
+named.
+
+**5. A rule in a prompt is a request. Enforcement is a mechanism that runs
+AFTER generation** — a gate plus regeneration with a targeted nudge.
+Confirmed on four separate properties: length ceiling, presence of figures,
+language of a recommendation, and post-translation condensation.
+
+Put a safety catch on the source side: when the source genuinely lacks the
+property you are demanding, do not demand it. A gate that requires figures
+from a source containing none is an instruction to fabricate.
+
+**6. Volume minimums are SOFT (log them), ceilings are hard.** Regenerating
+because output was "too short" produces padding, reliably.
+
+**7. The target quoted to the model sits below the threshold the gate
+enforces.** A sample two characters over the ceiling cost two paid
+regenerations. Both numbers come from ONE constants module — every hand-copy
+of a constant into a script, a prompt, a test or a message to the model is a
+future lie, and it will be discovered by the number that did not get updated.
+
+## Building the gate
+
+**8. On fail-open, return the BEST candidate — not the last one, and not the
+current one.** Rank by *weighted* severity: regulatory beats content beats
+length, ties broken by length. Counting violations without weights is a fake
+ranking, and it has a predictable failure: text with no figures is shorter,
+so it wins. The accepted sample must be exactly what reaches the payload
+**and** the cache; watch for "last one wins" when steps are written, or you
+poison the cache with a candidate you rejected.
+
+**9. Measure the gate's own cost before wiring it in.** A regex reading a
+whole source was a hot path at 835 ms; fixing its quantifiers took it to
+0.2 ms. Add a performance test with a threshold, or the next one will not be
+noticed either.
+
+**10. A prompt in a database plus code with placeholders forces a deployment
+ORDER**: the code that supplies the variables ships first, the prompt second.
+Add a version guard so the gate is inert until the prompt reaches the version
+that feeds it, and log any placeholder the build did not supply.
+
+## Judging output, and detectors
+
+**11. A detector finds CANDIDATES, not defects.** Especially across languages
+or formats. Confront every hit with the source before reporting it, or you
+will report your own regex's shortcomings as the product's. Three false
+alarms were avoided exactly this way. Choose the direction of the check with
+the lower false-positive background: for translations, look for *invented*
+content rather than *lost* content.
+
+**12. Judge against the SOURCE, not against world knowledge.** "Correcting" a
+fact to match what you know is a grounding violation, not a fix. One
+fabrication charge collapsed when the source turned out to use the disputed
+name 63 times.
+
+**13. Audit samples with the strongest tier available.** A cheap tier
+produced false negatives and demanded content the prompt explicitly forbade.
+And remember the audit is itself non-deterministic: a borderline rejection is
+a signal for a HUMAN auditor, not a trigger for another prompt iteration.
+
+**14. Sweep for residue by CLASS, not by known spellings.** Search for the
+value — the old ceiling `35` — not for the wording of a label. Check also
+whether a test is PINNING an incorrect label into place. Pin a reviewer's
+counterexamples as MUST-PASS tests: one such test caught a fix that was only
+half done, before it came back around.

package/skills/retro/SKILL.md

@@ -0,0 +1,69 @@
+---
+description: Close an initiative by learning from it. Spawns the retrospective agent over the ledger, the notes and the agents reports, records what it changed and what it rejected, and writes durable facts about this repo into .tyran/knowledge/. Runs automatically at the end of an initiative; also available as /tyran:retro.
+---
+
+# Retro
+
+The only loop through which Tyran gets better at *this* repo instead of
+repeating the same mistake every initiative.
+
+**You normally do not have to invoke this.** The `Stop` gate refuses one turn
+when an initiative has all its tickets merged and no retrospective recorded
+since the last merge. This skill is what you run when it does — or when you
+want one early.
+
+## 1. Spawn the retrospector
+
+Spawn `tyran:retro` at the tier `node "${CLAUDE_PLUGIN_ROOT}/scripts/tiers.mjs"
+--role retro` resolves, over the initiative's `PLAN.md`, `NOTES.md`, the
+agents' reports, and the initiative's git log.
+
+Do not do this work yourself in the conducting session. The retrospector's
+value comes from reading the record cold; a conductor reviewing its own
+initiative rates its own decisions, and rates them well.
+
+## 2. Record the outcome — including "nothing"
+
+Every retro ends with a journal entry, whatever it concluded:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/journal.mjs" append "$J" retro.entry "$INIT" \
+  --actor retro --data '{"kind":"skill","target":"skills/run/SKILL.md","confidence":"medium"}'
+```
+
+`kind` is `skill`, `agent`, `script`, `doc`, `knowledge` — or **`skipped`**
+with the reason, when the judgement is that this initiative has nothing worth
+changing. That is a correct outcome and it settles the gate exactly like any
+other. A retro that always finds something is not learning, it is padding.
+
+**When `kind` is `skill`, follow `skill-writing`.** New skills are AUTO class —
+you may commit one without asking — and that is only safe against a standard.
+It carries the admission test (a skill nothing already points at is a library
+entry), the description budget you are spending on every future session, and
+the activation test that proves the thing fires at all. A skill that never
+triggers costs its description on every turn and returns nothing.
+
+## 3. Write down what is true about THIS repo
+
+Durable facts go to `.tyran/knowledge/<topic>.yaml`, which is AUTO class —
+the retrospector may write it without asking:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/schema.mjs" validate knowledge .tyran/knowledge/<topic>.yaml
+```
+
+An entry is a fact, convention, gotcha, command or decision, with a
+confidence, its provenance, and the paths it applies to. The counters
+(`used`, `helpful`, `outdated_reports`) exist so a later retrospective can
+retire an entry that stopped earning its keep — knowledge that only ever
+grows is a context tax with a good story attached.
+
+Write what a competent newcomer would get wrong, not what the code already
+says. "The test suite takes 9 minutes, so do not run it per file" is worth an
+entry. "This is a Next.js app" is not: the next agent can see that.
+
+## 4. Report
+
+Five lines: candidates considered, implemented, rejected and why, what was
+deleted or merged, what is left for next time. Rejections are as valuable as
+changes — they stop the next retrospective relitigating the same idea.

package/skills/root-cause/SKILL.md

@@ -0,0 +1,89 @@
+---
+description: Find the mechanism behind a failure instead of patching its symptom. Reproduce first, change one variable per experiment with the prediction written before the run, bisect rather than re-read, and exit by naming the mechanism and pinning it with a failing test. Use for a bug, an unexplained red test, or a failure that will not reproduce.
+---
+
+# Root cause — working a failure down to its mechanism
+
+> This is the situation the conductor is told to spend its most expensive
+> reasoning on: a diagnosis, a failure nobody can reproduce, two agents who
+> disagree. Spending more thinking on an undisciplined search just produces a
+> more confident wrong answer, so here is the discipline.
+
+## Reproduce first. Everything else is downstream of this
+
+**A fix for a bug you cannot reproduce is a guess with a diff attached.** You
+cannot tell whether it worked, and neither can the reviewer — the bug's absence
+after the change is indistinguishable from the bug's absence before it.
+
+Get to the smallest reliable reproduction you can, and write down the exact
+command, input and environment. If it reproduces only sometimes, capture the
+rate — "3 of 20 runs" is a fact you can measure against later, "it is flaky" is
+not. If it will not reproduce at all, that is now the task: what does the
+failing environment have that yours does not — version, data, timezone,
+concurrency, permissions, a warm cache?
+
+## Read the whole error
+
+The first line names where it surfaced, not where it went wrong. Read the full
+stack, the frames from your own code in particular, and everything logged in the
+seconds before. The answer is stated outright more often than anyone expects,
+which is why "I read the error" and "I read the first line of the error" have to
+be different sentences.
+
+## One variable, and write the prediction first
+
+Change ONE thing per experiment, and **write down what you expect to happen
+before you run it.** An experiment whose outcome you did not predict teaches
+almost nothing: whatever comes back, it confirms something you already believed.
+A prediction that turns out wrong is the single most informative event available
+to you, and you only get it by committing first.
+
+Two changes at once and you have learned nothing about either.
+
+## Halve the surface
+
+Do not re-read the code hoping to spot it. **Bisect.**
+
+- Over time: `git bisect` against a command that exits non-zero on the failure.
+  A scriptable check turns an afternoon into a few minutes.
+- Over the input: cut it in half, keep the half that still fails, repeat.
+- Over the system: disable, stub or bypass half the pipeline. Where does the
+  value stop being correct? Instrument at the boundary between two components
+  before you go inside either.
+
+## It is your code before it is the library
+
+The base rate favours the code changed most recently by the fewest people —
+yours. Suspect the dependency only after the evidence points there, and then
+**read the installed version's source**, not your memory of the API and not the
+documentation for a version you might not have. `node_modules` is on disk; the
+answer is a `grep` away, and a remembered signature has already sent people
+down a day of the wrong road.
+
+## When three hypotheses have died
+
+The wrong assumption is one you have not written down. Stop testing and list
+what you believe is true about the system — which file is loaded, which branch
+is running, which build is deployed, which database you are pointed at, that the
+change you made is even in the process you are running. Then test the cheapest
+item on that list.
+
+Almost every long debugging session ends here: something everyone was certain
+of was not true. `prompt-tuning` has the sibling rule for non-deterministic
+work — after three failed attempts at the same defect, name it a known
+limitation and hand it to a person rather than taking a fourth blind swing.
+
+## Exiting
+
+1. **Name the MECHANISM, not the symptom.** "The cache key omits the locale, so
+   the second request serves the first request's body" is a root cause. "The
+   page showed the wrong language" is the symptom you started with.
+2. **Pin it with a failing test before the fix.** Written after the fix, a test
+   only proves the code's current behaviour; written before, it proves the bug
+   existed and is gone. This is also what the reviewer will ask for.
+3. **Check for siblings.** The same mechanism usually has other victims —
+   another cache key, another unhandled path. Find them now, while you
+   understand it.
+4. **Report the mechanism, the evidence, the fix and the blast radius**, plus
+   the hypotheses you killed. Those save the next person from re-running your
+   dead ends, and they are the part everyone omits.