Skip to content

finos/morphir-scala / .claude/skills/squire

squire

Verified

Use when morphir-scala work needs environment diagnostics or build/network/sandbox unblocking; reference repository management; branch lifecycle refresh after squash-merging a target branch into main; Morphir IR spec/schema sync or export; or task-tracking configuration and beads mode resolution.

FileKindSize
.gitignoreother180 B
.mill-versionother19 B
README.mdmarkdown7.6 KB
SKILL.mdskill md6.7 KB
SquireBranch.scalaother6.4 KB
SquireCellar.scalaother7.4 KB
SquireChangelog.scalaother20.6 KB
SquireDoctor.scalaother13.9 KB
SquireEnv.scalaother16.2 KB
SquireModel.scalaother4.9 KB
SquireProcess.scalaother1.5 KB
SquireRepo.scalaother30.4 KB
SquireSchemas.scalaother25.2 KB
SquireSpec.scalaother35.6 KB
SquireTests.scalaother323.1 KB
SquireTracking.scalaother16.4 KB
SquireVersionCorpus.scalaother3.3 KB
millexecutablescript6.5 KB
mill.batscript9.7 KB
references/branch.mdmarkdown4.4 KB
references/cellar.mdmarkdown4.4 KB
references/doctor.mdmarkdown5.3 KB
references/env.mdmarkdown3.9 KB
references/mill-morphir.mdmarkdown1.6 KB
references/repo.mdmarkdown7.6 KB
references/spec-sync.mdmarkdown10.6 KB
references/tracking.mdmarkdown10.9 KB
squireexecutablescript1.2 KB
squire.batscript1.8 KB
squire.scalaother36.8 KB
test-resources/META-INF/services/kyo.test.Testother275 B
test-resources/schemas/morphir-ir-v4.jsonconfig107.1 KB
test-resources/schemas/morphir-ir-v4.yamlconfig74.2 KB

references/spec-sync.md

View on GitHub
# Squire Spec Sync — Round-tripping the Morphir spec

The IR specification, its design notes and its JSON schemas live upstream in [finos/morphir](https://github.com/finos/morphir). They are also mirrored into the knowledge base under `kb/bundles/morphir/morphir-upstream/`, so they can be read, searched, linked and edited alongside everything else here.

Squire keeps those two copies honest. `spec sync` brings upstream's changes in; `spec export` sends this side's changes back out.

```text
finos/morphir ──── spec sync ────▶ kb/bundles/morphir/morphir-upstream/
      ▲                                          │
      └──────────── spec export ─────────────────┘
```

---

## Division of labour

**`kb` owns the mechanism.** The `kb sync` commands are domain-neutral: they read a bundle's `sync.yaml`, mirror the paths it names, record what was imported in `sync.lock.yaml`, and inject the knowledge base's own frontmatter keys inside a fenced `# kb:begin` … `# kb:end` region. Export removes exactly that region, so the bytes that go back upstream are the bytes that came from it. None of that knows or cares that the upstream is Morphir.

**Squire owns the Morphir specifics.** Which repository (`finos/morphir`), which ref, which subtrees the reference checkout needs, which of upstream's validators have to pass before a change is fit to send, and the order the steps run in. Squire drives `kb`; it never re-implements it.

Keep it that way. A rule that only makes sense for Morphir belongs here. A capability any mirrored bundle would want belongs in `kb`.

---

## Prerequisite: the reference checkout

Both halves need a checkout of upstream at `.refs/finos/morphir`. Morphir is a large repository and the mirror maps four subtrees of it, so clone it sparsely:

```bash
${CLAUDE_PLUGIN_ROOT}/squire reference repo add https://github.com/finos/morphir \
  --sparse docs --sparse website --sparse tests/bdd --sparse wit
```

- `docs/` — the specification prose, the design documents behind it, and the ADRs
- `website/` — `static/schemas/` (the schemas that actually define the IR), `static/ir/examples/`, and the `scripts/yaml-to-json-schemas.js` generator the export gauntlet runs
- `tests/bdd/` — the fixtures and feature files that are the executable ground truth
- `wit/` — the IR expressed as WebAssembly Interface Types

See [repo.md](repo.md) for what `--sparse` does. `spec sync` prints this exact command and stops if the checkout is missing.

**Keep the sparse set at least as wide as the manifest.** These paths are the top-level roots of every glob in the bundle's `sync.yaml`; add a mapping there and this set has to grow with it. A file that is mapped but not checked out is indistinguishable from a file upstream deleted, so it reports as `deleted-upstream` — and `--prune` acts on that. `spec sync` warns when the checkout is narrower than it expects, and refuses outright to run `--prune` in that state. Widen an existing checkout with:

```bash
git -C .refs/finos/morphir sparse-checkout set docs website tests/bdd wit
```

---

## `squire spec sync` — import

```bash
# Ordinary import from main
${CLAUDE_PLUGIN_ROOT}/squire spec sync

# See what would happen, touching nothing
${CLAUDE_PLUGIN_ROOT}/squire spec sync --dry-run

# Import from a tag or branch
${CLAUDE_PLUGIN_ROOT}/squire spec sync --ref v4-draft

# Take upstream's side of files edited on both sides, and drop files upstream deleted
${CLAUDE_PLUGIN_ROOT}/squire spec sync --theirs --prune

# Use the checkout exactly as it stands
${CLAUDE_PLUGIN_ROOT}/squire spec sync --no-fetch
```

Five steps, each reported, any of which aborts the run non-zero:

1. **checkout** — `.refs/finos/morphir` is present. If not, the `repo add` command to run is printed.
2. **fetch** — `git fetch --depth 1 origin <ref>` then a detached checkout of `FETCH_HEAD`. Refuses to move a checkout with uncommitted changes: those are usually a half-finished export, and overwriting them would lose real work. Skipped by `--no-fetch` and by `--dry-run`.
3. **status** — `kb sync status --json`, summarised by state (see below).
4. **pull** — `kb sync pull`, with `--dry-run`, `--theirs` and `--prune` passed through. This writes the mirrored concepts and assets and rewrites `sync.lock.yaml` and the bundle index.
5. **check** — `kb check --no-provenance`, whose findings are printed. Provenance is off deliberately: it verifies concept `sources:` against `.refs/`, which mirrored documents do not carry.

**When to run it:** before starting spec work, so you are editing today's upstream rather than last month's; and again before exporting, so a diverged file is caught here rather than in a pull request.

---

## `squire spec export` — export

```bash
# Project local edits into the reference checkout on a review branch
${CLAUDE_PLUGIN_ROOT}/squire spec export

# See what would be written and which validators would run
${CLAUDE_PLUGIN_ROOT}/squire spec export --dry-run

# Export into some other morphir checkout — a fork you already have a remote on
${CLAUDE_PLUGIN_ROOT}/squire spec export --to ~/code/github/me/morphir

# Also send files that moved upstream since the last import (reconcile them first)
${CLAUDE_PLUGIN_ROOT}/squire spec export --include-diverged
```

Four steps:

1. **push** — `kb sync push --to <checkout>`. Only `local-only` files are exported by default; `diverged` ones need `--include-diverged` and a human's judgement first. A file whose `# kb:begin` fence is damaged is refused, and the step fails.
2. **branch** — `git switch -c morphir-kb/spec-sync` in the checkout (override with `--branch`, suppress with `--no-branch`). Re-running switches to the existing branch, so successive exports accumulate on one.
3. **validators** — run from inside the checkout. Each is skipped with a warning when its tool is not on PATH or when
   what it judges is not in the checkout, which a sparse clone makes normal:
   - `jsonschema fmt --check website/static/schemas/`
   - `jsonschema lint website/static/schemas/*.yaml`
   - `jsonschema metaschema website/static/schemas/*.yaml`
   - `squire schemas compare --from website/static/schemas` — the YAML↔JSON sync check upstream does not have
4. **status** — `git status --short` in the checkout, and stop.

**A validator blames only what the export touched.** Upstream's GitHub Actions runs none of these, so schemas arrive
already failing — at the pinned commit `morphir-ir-v4-document-tree-files.yaml` does not satisfy its own metaschema,
and none of the committed JSON is canonical by `jsonschema fmt`. A failure in a subtree this export did not write is
reported in full and does not fail the run. Blocking a prose change on a schema defect somebody else introduced would
only teach people to route around the gauntlet.

Two notes on the schema tooling. `jsonschema fmt` refuses YAML input in 16.3.0, and every schema upstream keeps is
YAML, so that first validator currently always skips — which also means upstream's own `fmt:schema` task and the
`.husky/pre-push` hook gating on it cannot be doing what they appear to. The last validator reproduces
`node scripts/yaml-to-json-schemas.js` in Scala using Kyo YAML. The upstream generator needs `js-yaml`, a
devDependency no sparse reference checkout will have installed; Squire's in-process comparison is verified
byte-for-byte against upstream's committed output and runs without a Node or Bun runtime.

**It does not commit and it does not push.** The contribution is the human's, made under their FINOS CLA, and only they can judge whether what landed in the checkout is what they meant to send.

### No AI attribution on the commit

When you do commit in the checkout, the message must carry no `Generated with …`, no `Made with Cursor` (or any
other `Made with <tool>` footer), no `Co-authored-by:` for any agent, and no tool credit of any kind. Upstream's
`.husky/commit-msg` hook strips such trailers, and FINOS EasyCLA requires every author named on a commit to have a
signed CLA — which an agent cannot have. The same rule governs pull request descriptions and review comments. If a
host tool inserts attribution automatically, strip it before finishing. See this repository's
[AGENTS.md](../../../../AGENTS.md).

---

## What the states mean

`kb sync status` derives a state per mirrored file by comparing three things: the local copy reduced to its upstream form, the hash recorded in `sync.lock.yaml` at the last import, and the file in the reference checkout. Nothing is stored; it is recomputed every run.

| State | Meaning | What to do |
|-------|---------|------------|
| `clean` | All three agree. | Nothing. |
| `local-only` | Edited here since the import; upstream has not moved. | This is what `spec export` sends. |
| `upstream-only` | Upstream moved; no local edits. | `spec sync` takes it, losing nothing. |
| `diverged` | Both sides changed since the import. | Reconcile by hand. `kb sync diff <path>` shows both. `--theirs` takes upstream's; `--include-diverged` sends yours. |
| `missing-local` | In the lockfile, absent from the mirror. | `spec sync` restores it. If upstream dropped it, `--prune`. |
| `deleted-upstream` | Mirrored here, gone upstream, unmodified. | `spec sync --prune` removes it here too, if that is what you want. |
| `deleted-upstream-edited` | Gone upstream, but edited here. | Held back by everything, `--prune` included. Restore it upstream and export, or revert the edit. |
| `untracked` | Matches a mapping in `sync.yaml` but was never imported. | `spec sync` imports it. |
| `unreadable` | The `# kb:begin` … `# kb:end` region is damaged, so the file cannot be reduced to its upstream form. | Repair the fence by hand, or re-import with `--theirs`. An error, not a warning: an export would send the wrong bytes. |

Only `unreadable` and `missing-local` are errors in `kb check`. The rest are drift — a prompt to decide something, not a broken build.

---

## Editing rules

- **Edit in the knowledge base, never in `.refs/`.** The reference checkout is a mirror that `spec sync` overwrites; anything typed there is lost on the next fetch. The one exception is the export branch, which is the checkout's whole purpose — and even there, the source of truth is the bundle.
- **Do not hand-edit `sync.lock.yaml`.** It is generated, and it is the only record of what the import baseline was.
- **Do not hand-edit below the `<!-- kb:sources -->` marker** in the bundle index. `kb sync pull` regenerates it.
- **Frontmatter inside the `# kb:begin` … `# kb:end` fence is ours; everything outside it is upstream's.** Adding a key inside the fence is fine. Moving upstream's keys into it is not — they would vanish on export.
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall