Upgrade notes
What changes when you move to a new release, where a version number cannot say it.
Most releases need nothing here. Semver carries compatibility, --generate-notes carries the
list of what changed, and the four layers in versioning carry which of them
moved. What none of those can carry is the sentence a person needs before upgrading: your
working setup will behave differently, and here is the repair.
A change belongs here when a configuration that works today stops working, or starts working differently, without the person having changed it. A new feature does not; a bug fix usually does not; a fix that makes a previously-quiet misconfiguration loud does.
How this reaches a release
A note is written as its own file in .changes/upgrading/.
The version it ships in is unknown until the release is cut. Name the file <issue>-<slug>.md and
open it with the note's ### heading.
Notes do not go in this file directly. Each one used to be added at the same line, so two open pull requests always conflicted.
When a tag is chosen, mise run file-upgrade-notes <tag> moves every staged note under
## <tag> here. Newest issue comes first. At release time, .github/workflows/release.yml
prepends that section to the generated notes. The note then appears in the release itself.
release.sh refuses a tag while a note is still staged. An unfiled note fails silently in
two ways. It is dropped from the release being cut, or it lands in a later release. The repair
is to run the filing task and commit.
cli/v0.25.0
A coined property type is now reported
property-type-unknown warns on a type: that nothing reads (#1391). Its values were never checked.
Known types are string, text, ref, date, number, claim, quotation and list.
For entries that are records, declare a list with fields:.
The finding is a warning and does not gate.
cli/v0.24.0
phase settle --merge writes the phase merge, and max_open_proposals is read locally
yidam phase settle --merge writes the merge that settle drafts. It is authored by yidam phase, with you as committer.
It refuses a phase that is not ready, or a baseline that has moved on. It also refuses a checkout that is not the commit.
--summary "<text>" replaces the drafted tally in the merge subject.
Plain yidam phase settle is unchanged and still commits nothing.
[cluster] max_open_proposals is now read by yidam propose and yidam run, against local propose/* branches.
At the cap, neither opens a new proposal branch. A corpus without the key sees no change.
See cli-reference.md and configuration.md.
New derivations may write proposals, where an identity allows it
New derivations ship [serve] act = "when-identity" in .yidam/config.toml.
serve --mcp then serves propose and cycle wherever a git author identity resolves.
Without one, the server still starts, with the read tools only.
It says why at startup and in every refusal of propose or cycle.
An HTTP bind beyond loopback is treated the same way.
An existing repository keeps what its file says.
Write act = "when-identity" under [serve] to adopt the new default.
act = true still refuses to start where a condition fails.
The MCP contract is now 0.32.0.
Sessions now open with the loop's brief
New derivations ship .claude/settings.json with two Claude Code hooks.
The SessionStart hook prints yidam cycle --brief into the session.
The Stop hook records the round and tells you what each turn moved.
Run yidam migrate scaffold to add the hooks to an existing repository.
It creates .claude/settings.json, or adds the hooks to yours.
It refuses a settings file that already declares hooks.
Add the two entries by hand there, as sadhana/root/claude-settings.json does.
yidam doctor warns when a repository with a CLAUDE.md has no hooks.
The hooks run the binary in .yidam/bin, so pin a release that has yidam hook.
An older binary makes the hooks silent, never a failure.
cycle can now say what moved since the last round
yidam cycle --record keeps this round under .yidam/loop/<branch>.json.
yidam cycle --since-last reports what arrived and what left since that record.
It covers findings, due clocks, stale steps, refs in flight and local proposals.
Each branch keeps its own record, and a detached HEAD keeps HEAD.json.
The directory writes its own .gitignore, so nothing in it is ever staged.
No migration is needed.
With no record, since_last is absent and since_last_unread says why.
Never read that as nothing having moved.
yidam cycle --brief prints a short report within a token budget.
The default budget is 500 tokens, and --budget changes it.
It refuses --format json.
Without these flags, cycle prints exactly what it printed before.
cycle acts now say whether a command does them
Each act in cycle's next, and each clock naming a remedy, now carries kind.
It is tool or person.
A tool act carries argv, and running it from the report's root is the act.
A next item also carries targets, naming the nodes, steps or refs it is about.
A loop can now run tool acts without parsing the prose act string.
Treat a missing kind as person, because an older yidam sends none.
The MCP contract is now 0.31.0.
Its cycle notes now also describe stale_steps and stale_steps_unread.
cycle now reports stale manifest steps as owed
yidam cycle now reads .yidam/capabilities.toml the way yidam run --dry-run does.
A step whose receipt does not match the tip is listed under stale_steps.
It adds one yidam run act to next.
cycle --strict now exits nonzero on a stale step, as it does on a due clock.
A scheduled job using --strict may start failing where it passed before.
Run yidam run, or drop --strict if you only wanted the report.
When the steps cannot be planned, stale_steps_unread says why.
A detached HEAD is the common case, so CI checkouts will see it.
cycle now spells an in-flight act in_flight
next[].source for an in-flight phase is "in_flight". It used to be "inflight" (#1439). The schema always declared "in_flight", so a validating consumer rejected any cycle report with a phase in flight.
If you match on source, match "in_flight". This applies to a script or a prompt that reads cycle --format json or the MCP cycle tool. A match on "inflight" will stop finding anything.
cli/v0.23.1
The bootstrap skill is no longer vendored
A re-vendor now removes .yidam/.vendor/prelude/skills/ (#1435). The bootstrap skill made your repository and never runs in it again.
Delete the bootstrap row from .yidam/skills/README.md by hand. It sits under Inherited from prelude, and its link now goes nowhere.
A re-vendor never rewrites that file, so nothing else will remove it.
Delete the whole table if that row was its only entry.
cli/v0.23.0
index-build embeds each record alone
index-build now embeds one record per call (#1428). Each record is embedded the way a query is.
Before, records went in batches of 256. Each vector then depended on the records batched with it.
Rebuild your index with yidam index-build. An old index still works, but its vectors sit slightly apart from its queries.
On one corpus, a record used as a query kept 92% of its top ten.
A shared remote index should be rebuilt by every corpus that pushes to it. Then all its vectors come from one build.
The build is also faster and smaller. One corpus took 23 seconds instead of 43, and 0.2 GB instead of 12 GB.
[index] batch_size restores batching, but its vectors drift from the queries again. See configuration.
cli/v0.22.0
type: list is now a checked type
A property declared type: list is now read (#1391, RFC-0050). Before, list was a coined type and nothing checked it.
Its value must now be a non-empty list.
A single value not wrapped in a list is reported by property-type.
items: and fields: say what each item is. fields: declares a record, closed to keys it does not name.
A misspelled key in a record is now an error.
See configuration for the forms.
A tag inside a property is no longer the node's standing (#1382). Standing is read from top-level type: claim properties only.
To grade each entry, declare the property type: list with a claim field.
claim-property-undeclared now suggests exactly that.
The warehouse contract no longer refuses a list property. It gets no column, as a claim does.
cli/v0.21.0
Semantic retrieval is in every released binary
vector-read joined the default feature set (#442). Every install channel now carries index-build and semantic retrieve.
yidam --version lists vector-read index among its features.
The binary grows from about 23 MB to 56 MB.
What changes for you: retrieve turns semantic once the corpus has an index.
Run yidam embed && yidam index-build, or yidam vault pull --index where a vault holds one.
A corpus with no index answers by keyword, as before.
Semantic retrieval does not span tonpa dependencies; keyword retrieval does.
On an Intel Mac, install ONNX Runtime 1.24 or newer. brew install onnxruntime provides it.
The Homebrew tap installs it for you.
Elsewhere set ORT_DYLIB_PATH to a libonnxruntime.dylib.
Without it, only commands that embed fail, and each names the fix.
On Linux, the release binaries now need glibc 2.39 or newer. Debian 13 and Ubuntu 24.04 qualify.
Debian 12, Ubuntu 22.04 and RHEL 9 do not, and fail with version GLIBC_2.39 not found.
The cluster image moved to Debian 13 for the same reason.
To keep the old build, install from source. Pass --no-default-features with the other default features.
Installation has the command.
cli/v0.20.0
Export an ontology to BigQuery and TextQL
yidam export --format warehouse writes your ontology as a BigQuery contract (#1394).
It writes one table per class, a link table per edge and a value table per closed set.
The first export writes ddl/bigquery/0001_init.sql.
A later export writes the next numbered migration, and refuses a change that would lose data.
A feed maps a pipeline's landing table onto the contract.
Declare one in .yidam/warehouse/feeds/<feed>.yml, and the export writes a MERGE script per table.
It refuses a feed that maps anything the ontology does not declare.
--with-corpus adds your nodes as rows, and --format textql writes a TextQL Ontology folder.
See From a corpus to a warehouse for the whole route.
What changes for you: nothing, until you run the export. Never run a snapshot feed over an empty landing table, because it deletes every row that feed wrote.
cli/v0.19.0
catalog-location-malformed reports a url with a # fragment
A url location that names a member with # is now a finding (#1352).
A fragment never reaches the server, so catalog-fetch downloads the whole file.
The entry then reads as if it held only the part the fragment names.
The finding names the file actually fetched.
What changes for you: a corpus holding such a location gets a new warning.
Move the part after # under members: to read one file inside a zip.
See Read a file inside a zip.
A file inside a zip is read as a reading
A location can list members:, paths inside the zip it names (#1351).
catalog-extract unpacks each into the cache and records it under the zip's readings:.
Each such reading carries member: and by: unzip.
See Read a file inside a zip.
Lint refuses a member path that leaves the archive.
catalog-location-malformed names a path with .., a leading /, a drive letter or a backslash.
What changes for you: nothing.
An entry without members: reads as before.
Source packs that pin a mutable identifier
A scheme can pin an identifier that names a moving target (#1343).
Declare [scheme.<name>.pin] with mutable, read, media, value and pinned.
source add asks the read once, and writes the version it answered into the identifier.
See Source packs.
archive 0.2.0 adds github and wikipedia.
github:<owner>/<repo>@<ref>/<path> is pinned to the commit the ref names.
wikipedia:<lang>/<title> is pinned to the article's current revision.
A bare wayback:<url> is pinned to the capture the archive names.
catalog-fetch refuses the mutable form, with how to pin it.
It never asks the read.
The MCP contract is now 0.30.0.
resolve_source returns the pinned identifier in locations, and answered counts the read.
What changes for you: re-pin archive to use the new schemes.
archive@^0.1 does not admit 0.2.0. Change it to archive@^0.2, then run mise run yidam-vendor-update.
Every wayback:<timestamp>/<url> location resolves as before.
Source packs that read a listing or a catalog
A scheme can resolve through a page that lists its files (#1342).
Write resolve = { listing = "…", match = '…' }, or resolve = { dcat = "<host>" } for a DCAT-US data.json.
Use one where a release date or a fresh path in the address defeats a template.
See Source packs.
source add writes the file it picked into the identifier.
The location reads scheme:local-id@<pin>, and catalog-fetch follows only the pin.
An identifier in such a scheme without a pin is skipped, with a message saying how to pin it.
A resolve without template now parses.
A pack with no template, listing or dcat still fails source check, now with that message.
The MCP contract is now 0.29.0.
resolve_source returns the pinned identifier in locations, and answered counts a page read.
What changes for you: nothing. Every template pack resolves as before.
Source packs that read a paged answer to its end
A scheme can declare paginate (#1341).
Name the offset parameter, the record array, and how to know the last page.
catalog-fetch asks for every page, and records one artifact holding every record.
See Source packs.
catalog-fetch refuses an answer with exceededTransferLimit: true from a scheme without paginate.
The refusal is a finding on the entry, and the run fails.
What changes for you: nothing, unless an entry fetched a cut-short answer.
Such an entry recorded the first page only. Declare paginate on its scheme, and fetch it again.
catalog-location-malformed checks identifiers against your packs
Once you enable a source pack, identifier locations are held to it (#1328).
yidam lint reports a scheme that no enabled pack declares.
It also reports a local id that the scheme's pattern refuses.
When a template pack declares the scheme, the finding names that pack.
For example, wayback: names archive. Pin it under prelude_sources to clear the finding.
What changes for you: nothing, until you pin a pack.
A corpus with no packs is checked for the scheme:local-id shape alone, as before.
doctor checks that your binary was built at the pin
yidam doctor has a new commit check (#1324).
It compares the running binary's build commit with .yidam.toml's commit.
They agree when one hash is a prefix of the other.
What changes for you: a stale .yidam/bin/yidam now fails doctor.
That is the binary a re-vendor leaves behind when nobody rebuilt it.
The finding names both commits. Run mise run yidam-build to repair it.
A repository with no .yidam/bin/yidam gets a warning instead, since another yidam answered.
A binary that records no build commit also warns, because nothing can be compared.
The scholarly and archive source packs
The template ships its first two source packs (#1320).
scholarly reads papers by doi:, pmc: and arxiv:, through Crossref, Europe PMC and arXiv.
archive reads Wayback Machine snapshots and Internet Archive items.
See Source packs.
One source add --fetch doi:… reaches a paper's open-access full text.
The DOI leads to a europepmc: location, and that one to pmc: when Europe PMC holds the text.
catalog-extract then reads the full text as plain text, without the reference list.
scholarly requires YIDAM_CONTACT.
Every request it makes names that contact, and it waits three seconds between requests to one host.
What changes for you: nothing, until you pin a pack.
Add scholarly@^0.1 or archive@^0.1 under prelude_sources, then run mise run yidam-vendor-update.
search_sources and resolve_source over MCP
serve --mcp answers two source-pack questions, and writes nothing (#1319).
search_sources is yidam source search. resolve_source is yidam source add --dry-run.
Both sit at a new sources tier, true where the corpus enables a pack.
The MCP contract is now 0.28.0. See MCP server.
[serve] offline_sources = true answers both from the packs' recorded fixtures.
Each answer says which route it took, in answered.
What changes for you: nothing, until you enable a pack.
A client that pins the contract version sees 0.28.0, with sources in the capability block.
Source pack transforms, and readings: on a catalog artifact
A source pack's scheme may name a describe and an extract transform (#1318).
Each is a .glu file under the pack's transforms/, run in the calculator arm's closed prelude.
The binary parses the response as JSON, XML or CSV and hands the transform the parsed value.
yidam source check admits each transform and runs it over the scheme's fixtures.
Transforms need the source-transforms feature, which is outside the default build.
It implies calculators-gluon, and adds 3 packages and 0.12 MB over it.
A build without it checks the rest of a pack, and says it did not check the transforms.
catalog-extract records a reading under readings:, not text:.
Each reading names its digest, its media type, and what took it in by:.
An artifact fetched from an identifier whose pack declares extract is read by that transform.
A build without source-transforms reports that artifact as skipped.
What changes for you: nothing you must do.
An entry that holds its reading under text: keeps it, and lint and the vault still read it.
A PDF that already has a text: reading is not read again.
catalog-fetch follows identifiers through source packs
catalog-fetch now fetches a kind: identifier location through the pack declaring its scheme (#1317).
An identifier no enabled pack declares is skipped, as before.
See Fetching an identifier.
Every request now names the tool in its User-Agent.
Set YIDAM_CONTACT to an email address or URL to add it there.
A pack with contact = "required" fetches nothing without it.
A refused request now fails the run.
A non-success status is recorded under refused and not retried.
Before, it stopped the whole run with an error.
[transport] auth now names where each credential goes.
Write { env = "VAR", header = "Name" } or { env = "VAR", query = "param" }.
source check now reports a bare variable name as an error.
--archive adds the nearest Wayback capture as a pinned location.
It needs an enabled pack declaring the wayback scheme.
yidam source list, search and add
yidam source add doi:… writes a draft catalog entry from a pack (#1316).
It follows the scheme's then chain and records each identifier as a location.
The entry is obtained: false, and its body is the pack's eight prompts, unanswered.
Each entry is its own catalog: commit. --fetch then runs catalog-fetch on it.
yidam source search <pack> <query> prints the identifiers a pack's search answers with.
A pack declares that endpoint in a new [search] table. source check holds it to the format.
See Source packs.
Set YIDAM_CONTACT before asking a pack that requires a contact.
It goes in the user agent. source list shows what each pack needs and whether it is set.
--offline answers from a pack's recorded fixtures and asks nothing.
What changes for you: nothing, until you enable a pack.
Source packs, prelude_sources, and yidam source check
A source pack names a family of sources by identifier, such as doi: or pmc: (#1315).
It is a directory holding pack.toml and entry.md, with optional transforms/ and fixtures/.
See Source packs for the format.
yidam source check holds every pack and every pin to that format, offline.
It exits nonzero on an error, so a repository that writes its own pack runs it in CI.
prelude_sources in .yidam/decisions/proposals.yml pins the packs a re-vendor copies.
Write <pack>@<range>, or <pack>@<range> from <repo>@<commit> for another corpus's pack.
mise run yidam-vendor-update copies each into .yidam/.vendor/sources/.
It refuses a pin the pack's version does not meet, and then changes nothing.
What changes for you: nothing, until you pin a pack.
A repository with no prelude_sources vendors no packs, and source check passes.
Catalog locations gain identifier, and the catalog gains four types
A catalog location can be kind: identifier, with a value of scheme:local-id (#1314).
For example, doi:10.1167/tvst.8.5.14 or pmc:PMC6753881.
kind: doi and kind: pmc are still reported by catalog-location-malformed.
The finding now names the fix, yidam migrate locations. Run it with --dry-run first to see each rewrite.
A value that is a URL is reported and left for you to rewrite.
The catalog type set gains statute, report, standard and document.
yidam lint now reports catalog-type-unknown at Warn for any other word.
primary is reported too, because it names a standing, not a form.
Nothing maps it for you: pick the type that fits each source.
The SDKs are no longer vendored
The SDKs moved from yidam/prelude/sdks/ to yidam/sdks/ (#1311). The prelude copy no longer carries them.
The next yidam-vendor-update deletes .yidam/.vendor/prelude/sdks/, which held 66 to 377 files.
It does so even when the pinned ref predates the move.
What changes for you: probably nothing. No derived repository we know of builds the vendored SDKs.
If yours depends on one by path, depend on the published yidam-core crate instead.
Its manifest now sits at yidam/sdks/rust/Cargo.toml upstream.
Every scaffolded CI job downloads yidam before compiling it
The privacy job and both release jobs now download a released binary first (#1308).
Before, they cloned yidam and compiled it at every pin, released or not.
Only the corpus job tried the download.
What changes for you depends on the file.
The privacy job sits in ci.yml's YIDAM:CI region, so your next re-vendor brings it.
release.yml is yours, so take the new .github/workflows/release.yml on upgrade.
Its guard and bundle jobs then skip the toolchain whenever your pin has a release.
index.yml still compiles, because no release carries --features index.
A re-vendor takes the newest release, not the origin's HEAD
yidam-vendor-update now pins the newest cli/v* release by default (#1308).
A release is a pin yidam-build can download, so no compiler runs.
An untagged pin compiled the CLI from a clone, in every repository that took it.
What changes for you: your next re-vendor may land on a release, not on main.
To keep pinning unreleased main, run YIDAM_REF=HEAD mise run yidam-vendor-update.
A repository pinned ahead of the newest release is refused rather than rolled back.
The refusal prints both commands: stay on main, or take the release on purpose.
yidam-vendor-status and the CI staleness report now measure against the newest release too.
A kuten profile with a populated policy slot is refused
A kuten proposes no severities, and a profile that tries is no longer read (#1305).
The policy slot was parsed and then ignored, so a proposed severity reached nothing.
The policy layer decides disclosure only. Nothing in it changes a check's severity.
What changes for you: nothing, unless you author a kuten profile.
Every shipped profile carries proposes_overrides: [], which still parses.
A non-empty list now stops kuten check with an error, and doctor warns. Both name the slot.
check-diff stops offering a candidate on a repeated suffix
Some words are no longer compared when check-diff looks for a near-miss (#1298).
Such a word ends three or more of the report's type names and appears nowhere else in them.
Nine error types are no longer each offered margin-of-error because they share error.
The finding rows are unchanged; only the nearest lead goes.
cli/v0.18.0
index-build moves into vector-read and needs no protoc
index-build no longer writes a LanceDB table, so building an index needs no protoc (#1287).
Nothing ever read that table. Every reader decodes corpus.arrow, which index-build now writes directly.
index-build is now in the vector-read build. index is kept as an alias for it.
An install with --features index or --features full still builds, without protoc.
A vector-read build now lists index in yidam --version and the report's features.
A client that read index as "this build needs protoc" should read it as "this build can make an index".
An index built before this upgrade is still read. Its corpus.lance/ directory is no longer used.
The next index-build removes it.
yidam run plans every epistemic step last
A run that both lands and proposes now proposes at the head it leaves (#1237).
Before, a proposal planned between two landings named a head the branch had already passed.
The next run found no propose/<head> for the new tip, and proposed again.
What changes for you: nothing to do. Dependencies still run first. A step's report may list in a new order.
The cluster base creates the executor's token secret
yidam/cluster/base now creates yidam-<corpus>-run.service-account-token (#1237).
Without it, every pod of a generated workflow waited in Init on a mount that never arrived.
What changes for you: move your base reference to this release's tag. An overlay that copies the base needs the secret too. See cluster-runs.md.
Regenerate a cluster workflow
A workflow from yidam cluster workflow stopped after its first landing (#1237).
Its expressions named hyphenated tasks with a dot, which Argo could not resolve. Nothing failed, and the run waited.
They now name each task in brackets, as tasks['land-x'].
A run not admitted now ends Succeeded, not in Error. Each task waits for the one before to succeed.
A skipped pin used to let the first step start and read an output nothing wrote.
A CronWorkflow now lists its time under spec.schedules. Argo Workflows 4 refuses the old spec.schedule.
Argo 3.6, the oldest version the run supports, reads either form.
What changes for you: regenerate every committed workflow. Run yidam cluster workflow again with the flags you used.
cluster status reports what a run did, from records
yidam cluster status lists a corpus's recent cluster runs (#1236). For each run it gives the admission and its reason.
Each step is landed, proposed, refused with the lander's reason, or not reached. Each gather peer has its outcome.
It reads the records Argo keeps on each Workflow, through kubectl, and never a log.
See cluster-runs.md.
A refused landing now writes a record to --out. The record holds refused and the lander's reason, and the pod still fails.
What changes for you: nothing, until you upgrade the image. A lander from an older image writes no refusal record.
status shows its refusals as failed, pointing at the pod's message.
A push can submit a cluster run, and every run holds a per-corpus mutex
yidam cluster workflow --on-push github writes an Argo Events EventSource and Sensor (#1235).
A push to the branch submits the same run the cron does, and the run asks admit first.
The lander's own push submits a run too, and that run finds nothing owed.
See cluster-runs.md.
Every generated workflow now holds a mutex, yidam-<corpus>. Two runs of one corpus queue instead of racing.
The field is synchronization.mutexes, which needs Argo Workflows 3.6 or later.
What changes for you: regenerate your workflow, on Argo Workflows 3.6 or later. A manifest written before this upgrade still runs, without the mutex.
Running on push is opt-in. It needs Argo Events and the streamflow-on-push overlay's two extra objects.
An S3 vault can assume a role by web identity
A vault can use a role from IRSA instead of a stored key (#1234). The default vault
assumes AWS_ROLE_ARN with the token in AWS_WEB_IDENTITY_TOKEN_FILE. Another vault names its
own with YIDAM_VAULT_<NAME>_ROLE_ARN and …_WEB_IDENTITY_TOKEN_FILE. It never inherits
AWS_ROLE_ARN. The remote index reads YIDAM_INDEX_ROLE_ARN the same way. See
cli-reference.md and
cluster-runs.md.
What changes for you: nothing, unless you opt in. Keys you export for a vault still win over
an injected role. A vault given both its own role and its own keys is now refused. doctor now
says where each vault's credentials come from.
Fenced clusters need STS. Pods that assume a role call STS first. Add its interface
endpoint's addresses to [cluster.egress] sts, then regenerate the policies.
Update the image first. An older binary refuses .yidam/config.toml once it holds
[cluster.egress] sts.
The lander can push as a GitHub App
yidam cluster land can push with a short-lived GitHub App token instead of a deploy key
(#1233). Set [cluster] git_auth = "github-app" and [cluster.github_app] app_id. Put the
App's key in the write secret as private-key.pem. The lander mints a token for the one
repository, with contents: write, and pushes over HTTPS. See
cluster-runs.md.
What changes for you: nothing, unless you opt in. Deploy keys stay the default. To switch,
regenerate your workflow. If you set [cluster.egress] remote, include the GitHub API's
addresses too.
Update the image first. An older binary refuses .yidam/config.toml once it holds
git_auth or [cluster.github_app].
Cluster pods are labelled by what they may reach, and a new command fences them
yidam cluster workflow labels every pod, and yidam cluster network-policy writes the
policies that select them (#1232). Each pod carries yidam.dev/corpus and yidam.dev/egress:
remote, vault or internet. A step pod, where a calculator runs, reaches the vault and
nothing else. catalog-fetch now runs from its own template, step-catalog-fetch.
What changes for you: regenerate your workflow. Then set the API server's addresses in
[cluster.egress] executor and write the policies into your overlay. An s3:// vault also
needs vault. See cluster-runs.md. Without a
CNI that enforces NetworkPolicy, the policies apply and enforce nothing.
Update the image first. An older binary refuses .yidam/config.toml once it holds
[cluster.egress].
Every generated cluster pod is bounded, and every run is cleaned up
yidam cluster workflow now writes resources, a deadline, retries and cleanup (#1231).
Each pod requests 250m CPU and 512Mi memory, is limited at 2 CPU and 2Gi, and fails after an hour.
pin, survey and step retry twice. land never does. Argo deletes a pod that succeeded,
and a workflow a day after it succeeds or a week after it fails.
What changes for you: regenerate your workflow. Set other sizes in [cluster.pod] and
[cluster.cleanup]. A calculator can set its own under [capability.<name>.cluster].
See cluster-runs.md.
Update the image first. The pods read .yidam/config.toml and .yidam/capabilities.toml.
An older binary refuses either file once it holds one of these tables.
Every generated cluster pod meets the restricted Pod Security Standard
yidam cluster workflow now writes a security context on every template (#1230).
Each pod runs as uid 1000, with a read-only root filesystem and no capabilities.
It writes only to two emptyDir volumes, /tmp/yidam and /home/yidam, and a file:// vault.
What changes for you: regenerate your workflow. A manifest written before this upgrade still runs.
It is refused by a namespace that enforces restricted. See cluster-runs.md.
A cluster corpus deploys with one kubectl apply -k
The objects around a generated workflow are now a Kustomize base and overlay (#1229).
The service account, both git secrets and the vault claim come from yidam/cluster/.
What changes for you: docs/cluster/argo-rbac.yml is gone.
Its objects live in the base, which your overlay names by URL at your cli/v* tag.
Copy the streamflow overlay, set its prefix to your corpus, and add your key files.
Then run kubectl apply -k. See cluster-runs.md.
Objects you already created keep working, since the names are unchanged.
Each corpus on a cluster names its own secrets and service account
yidam cluster workflow now names every object for its corpus, as yidam-<corpus>-<role> (#1228).
Two corpora in one namespace used to share yidam-git-write, so either lander could move the other's refs.
What changes for you: a regenerated workflow refers to new names.
Your cluster still holds yidam-run, yidam-git-read, yidam-git-write and yidam-vault.
Recreate each under its new name, and apply the Kustomize overlay in cluster-runs.md.
Or keep the old names by setting them in [cluster.names]. See configuration.md.
Keep old names only when one corpus runs in the namespace.
A gather runs on a cluster, and each peer's answer has a receipt
yidam cluster workflow now adds a gather's tasks for each file in .yidam/gathers/ (#1217).
Each peer is asked in its own pod, and nothing but the lander holds a git credential.
What changes for you: a local yidam gather now commits receipts too.
They land at .yidam/runs/gather/<name>/<peer>.yml, one per peer that answered or came back empty.
A gather branch you already proposed holds none, so a repeat run builds a different tree.
Pass --force to replace it, or delete the branch first.
A corpus without .yidam/gathers/ gets the same workflow as before.
regen and vault push author their own commits
yidam regen --commit and yidam vault push --commit write the regen:, index: and bundle: commits (#1215).
Each commits only the tracked files it changed, under its own author, and commits nothing when nothing changed.
It refuses a file that already has uncommitted edits.
The index workflow now runs yidam vault push --index --commit and pushes. Its Commit the lock step is now Push the lock commit.
Take the new .github/workflows/index.yml on upgrade. index-build and bundle still commit nothing, because their output is gitignored.
An interval's target may mark its line of holders finished
interval: accepts complete:, naming a property on the exclusive_over target (#1213).
Write complete: line_complete on a tenure class, and line_complete: true on each finished office.
The new interval-gap check then warns on a span inside that line held by fewer than it seats.
Spans before the first holder and after the last are not gaps. Targets without the mark are unchecked.
A calculator the corpus cannot run yet is declared, not stubbed as a skill
A capability in .yidam/capabilities.toml may omit run (#1184). It parses as declared and not built.
Every yidam run plan holding it is refused by name, and nothing lands.
The bootstrap now declares an unrun calculator there instead of writing a skill stub in .yidam/skills/.
An existing calculator stub can move the same way. Declare its reads, writes and verb, then delete the skill.
Until it gains a run, a bare yidam run refuses the whole manifest.
lint reports a skill that does not say whether it is built
yidam lint now reports skill-status-unstated at Info (#1182). It names each skill in .yidam/skills/ whose status: is missing.
It also names a skill whose value is neither built nor stub.
Every skill written before #1063 is reported after this upgrade. Nothing gates on it.
Add status: built or status: stub to each one, then run yidam skills-index.
The consumption record names the nodes retrieve returned
A retrieve line in .yidam/record/calls.jsonl now carries node_ids (#1020).
It lists the ids retrieve returned, in rank order. Every other tool records null.
yidam record uses them to name the corpus nodes no recorded retrieve returned.
Its JSON report gains consumption.reach, which is null over a record written before this change.
A line without the key is still read. Nothing needs to change in a corpus.
yidam record --fold commits the consumption record
The record [serve] record keeps can now reach the history (#1018).
yidam record --fold counts the new lines of .yidam/record/calls.jsonl into .yidam/consumption.json.
It commits that file alone, as one refresh: commit on the current branch.
The commit is operational, so no proposal branch and no author are involved.
The file is never truncated. The fold remembers how many bytes it counted, and takes only complete lines. A line a server writes during the fold is counted by the next one. With nothing new to count, the fold writes no commit, so it can run on a clock.
yidam record now reads the committed counts and the file together.
Its JSON report gains consumption.folded, which is 0 in a corpus that has never folded.
Nothing needs to change in a corpus until you choose to fold.
serve --mcp --http can require a bearer token
Set YIDAM_SERVE_TOKEN or pass --token-file, and every request needs the token (#939).
A request without it gets 401 on every path. Nothing changes until one is set.
What changes for you: check the environment you serve from. An empty YIDAM_SERVE_TOKEN now refuses to start.
So does setting the variable and --token-file together.
A token does not lift the loopback rule for [serve] act. See mcp-server.md.
A bind off loopback warns at startup
serve --mcp --http --bind with a non-loopback address now prints a warning (#939).
The transport authenticates nobody. Anyone who reaches the port can call every read tool.
The warning names each served tool, and the two repairs.
What changes for you: nothing, unless you watch stderr. The server still starts and answers.
Bind 127.0.0.1, or require a bearer token. A token silences the warning.
Domain libraries are vendored beside the prelude, not inside it
The domain libraries moved from yidam/prelude/domains/ to yidam/domains/ (#934). The prelude copy no longer carries them.
yidam-vendor-update copies only the domains named in prelude_domains into .yidam/.vendor/domains/.
Without that key, it keeps the domains this repository already vendored.
What changes for you: a vendored domain changes path. The next re-vendor moves it from .yidam/.vendor/prelude/domains/<domain>/ to .yidam/.vendor/domains/<domain>/.
Re-point any crates/Cargo.toml path or packages/ dependency that names the old path.
A repository that vendors no domain sees no change.
Every vector index needs rebuilding
The embedding runtime moved to fastembed 7, and it embeds into a different vector space (#536). Its ONNX Runtime is newer, and the quantized kernels answer about 3e-4 differently per dimension. The TypeScript SDK moved with it, because transformers.js 4.3 answers the same way.
What changes for you: re-run yidam index-build. Re-run yidam index-push too if you push one.
Until then, semantic retrieve reports stale_contract and answers with keyword search instead.
It does not rank against vectors from the old space. An index built before the witness existed is not checked.
yidam index-verify reports mismatch on an old index, and match once it is rebuilt.
yidam dispatch runs an agent seat as a run
yidam dispatch <question> --seat <name> runs the elector a seat declares in .yidam/sangha/dispatch/<name>.toml (#477).
The position lands on a propose/* branch with a receipt of what ran. The seat's registry row must already record that model, version and config hash.
What changes for you: nothing, unless you dispatch a seat. .yidam/sangha/dispatch/ is new and absent by default.
yidam lint gains elector-receipt-disagrees, a warning that is silent until a dispatch receipt exists.
See cli-reference.md for the declaration's shape.
yidam gather asks pinned peers a question
yidam gather <name> runs the question in .yidam/gathers/<name>.toml against each tonpa peer (#476).
Each peer's answers land as cites: on one ? question node, on a propose/* branch.
What changes for you: nothing, unless you write a gather. .yidam/gathers/ is new and absent by default.
No existing command changed. See cli-reference.md for the file's shape.
yidam cluster runs the manifest on Argo Workflows
yidam cluster workflow, admit, pin, step, land (#475, RFC-0026 §7). The same
run as yidam run, one pod per act. workflow generates the Argo manifest from
.yidam/capabilities.toml and [cluster] in .yidam/config.toml. The step pod holds no
credential that can move a ref; only the lander does. cluster-runs.md is the
deployment guide, for a file:// vault that needs no credentials and for s3://.
What changes for you: nothing, unless you deploy it. [cluster] is a new config table and
is absent by default. No existing command changed its behaviour.
Every workflow also runs the catalog. catalog-fetch, catalog-extract and catalog-reconcile
run ahead of your manifest's steps. A manifest that declares one of those names has no workflow.
Rename the capability.
Receipts are now format_version: 2. A receipt can record version, and image_digest on a
cluster. The digest is recorded only for an image pinned by @sha256:. Version 0.17.0 reads these
receipts unchanged.
check-diff offers fewer nearest names
A nearest candidate now needs a shared root of five characters, up from four (#390).
Across fourteen derived corpora, more than half of the four-character candidates were wrong.
Most shared a truncation such as stat, offering status for statement.
What changes for you: fewer candidates, and no findings. Every unmodelled-concept row is
still reported. A few right candidates on four-letter words are gone, such as vote.
cli/v0.17.0
An interval's target may seat more than one
interval: accepts capacity:, naming a property on the exclusive_over target (#1205).
Write capacity: seats on a tenure class. Then an office with seats: 3 may have three
holders at once. A target that omits the property holds one. Quoted digits such as "3" count.
A value that is not a whole number of at least one is reported on the target.
interval-overlap now reports each holder once, naming every earlier holder it overlaps. It
used to report once for each overlapping pair.
A class may declare its interval
interval: names an instance's start and end (#1201). Write start: and end:, each a
date property the class declares. Add exclusive_over: with a relationship from edges:.
No two instances may then link one target by it at once.
A new interval-overlap lint check is an error for each overlapping pair, and for an end before
its start. Intervals are half-open. They compare as query orders dates, at the precision both
sides share. So 1893 and 1893-06-01 meet rather than overlap. An absent end is still open.
Nothing changes until a class declares interval:. A declaration with a misspelled key, or no
end:, is a malformed class.
A new version of a source names the nodes that read the old one
yidam catalog-fetch names every node citing an entry when it records a new version (#1200).
A new version is a digest from a location the entry already held a digest from. The report and
the refresh: commit both list the nodes. The JSON row gains a superseded list.
yidam due gains a fifth clock, superseded. It lists each node citing a source that has
changed since the node was last committed. Set [due] superseded_after in days to let it come
due. A commit touching the node discharges it. A new text reading of a PDF is not a new version.
Nothing needs changing. The clock reads undeclared until the key is set, and still reports
what it measured.
F2 rewrites the moved node's own links
An editor rename between classes now re-relativizes the moved node's links (#1193). Before,
F2 moved the file and rewrote inbound links. It dropped every edit to the moved node itself. A
link written as ./sibling.yml was left pointing into the wrong class. yidam rename was not
affected.
What to do. Run yidam lint after any cross-class F2 rename made before this release.
graph-check reports each link it left dangling.
A class rename keeps its instances' ages
yidam migrate class writes moved-from: into every instance it moves (#1192). Before, a
class rename restarted both commit counts for each instance. Every orphan's escalation clock
reset. Every open question dropped off due's overdue list.
The line is the one yidam rename writes, for example moved-from: ../gage/canyon-outlet.yml.
An instance that already declared one has it replaced. The migrate plan lists each line it adds.
The JSON report gains a moved_from list. Class renames made before this release are not
backfilled.
A renamed node keeps its ages
yidam rename writes moved-from: into the node it moves (#1180). Before, a rename
restarted two counts of commits. One is how long nothing has cited a node, which orphan-in
escalates on. The other is how long a question has stood [open], which due reads. A renamed
overdue question dropped out of due entirely, and its clock read Ok.
The new line names the old path the way a target: does, for example
moved-from: ../concept/low-flow.yml. Both counts now carry across the move. A move that also
adds a citation or answers the question still ends that count. F2 in an editor writes the same
line. A second rename replaces it.
A move made without the command still restarts both counts. To keep them, add the line by hand
in the commit that moves the file. Moves made before this release are not backfilled. The
rename JSON report gains a moved_from object.
A quotation of a PDF is checked against a text reading
New command, yidam catalog-extract (#1172). It takes a text reading of each PDF artifact.
It files the reading in the vault cache and records it under the PDF as text:. It commits the
change as extract:.
Lint compares a quotation of a PDF with that reading. Before, every such quotation was
quotation-unchecked. Now a span missing from the reading is quotation-span-drift, an error.
Run catalog-extract on the machine that holds the PDFs, then run yidam lint.
Nothing changes until you run it. A PDF with no reading stays quotation-unchecked. An older
binary ignores the text: key.
yidam rename moves a catalog entry
yidam rename catalog/old new renames a catalog entry (#1159). Before, the command
took corpus nodes only. Renaming an entry by hand left every edge source: naming its old
stem, which edge-source-unresolved then reported.
The command now moves .yidam/catalog/old.md to new.md and rewrites every citation of it.
An edge source: is rewritten in the spelling its author used, stem or path. A markdown link
under .yidam/ that resolved to the entry is re-relativized from the file that holds it. That
covers node prose, other entries, decision records and the catalog README. On the largest
corpus we measured, one rename rewrote 107 citations across 41 files. Lint was identical
before and after.
Anything that names the old file without linking it is reported and not rewritten. The
report's corpus_dir is .yidam for a catalog entry, and from and to read
catalog/<name>.md. --dry-run prints the plan and changes nothing. Nothing changes for a
corpus node rename.
An edge source: counts as a citation
catalog-uncited and verified-unsourced read edge sources (#1158). Before, only a
links: target or a prose link to a catalog entry counted as a citation. An entry cited only
from edge source: values was reported uncited. A node whose [verified] claim rested on such
an edge was reported unsourced. Yet edge-source-unresolved resolved every one of those edges.
Now the resolver every citation count shares reads edge sources too. It admits the same two
catalog spellings: the entry's file stem, or a path written as a target: is. catalog audit
and the MCP claim surface read the same function, so their counts move with the gate's.
Two checks may change on upgrade. catalog-used-by-drift compares an entry's hand-written
used-by list to the nodes citing it. More citations can mean more drift. On the largest corpus
we measured it rose from 79 to 86 findings, all Warn. catalog-unobtained-but-cited is Error and
now fires for an edge resting on an obtained: false entry. No corpus we measured had one.
The graph report says what omitting a property costs
A new field, omission, on each class property in yidam graph --format json (#1155).
Its value is gates, reported or licensed: the verdict missing-property gives when an
instance omits the property. Before, the report carried only required, one bool. A property
marked required: false and one that said nothing both arrived as false. The web
editor labelled a licensed omission reported.
required is unchanged. The web editor reads omission and labels a licensed property
allowed. Against a binary older than the field, it labels a false property does not
gate rather than guessing. Nothing changes for a corpus.
doctor asks whether the ontology ever stated its contract
A new contract check (#1078). It warns when no property in the ontology says required:.
It also warns when no class with edges says edge_policy:. Either way, missing-property or
unlicensed-edge can warn there and never gate.
Writing the key is the answer, whatever its value. required: false counts, and so does
edge_policy: characteristic. One class answering answers for the whole ontology.
It is a warn, so doctor still exits 0. doctor --strict does not. Of 16 derived
ontologies measured, 14 warn.
doctor --only <id> reports only the named checks. yidam-vendor-update runs
doctor --only contract after it re-vendors. A binary that predates the flag prints nothing
there, so the first re-vendor after an upgrade may stay quiet.
Lint warns on a node linked only to its class
only-instance-of is a new warning (#1072). It reports a node whose only link is to its
own .ont.yml. The finding names the relationships its class declares. Add one of them to
the node, or delete the node if it is a stub.
A class the ontology names only as an edge's target is a leaf by design. Its instances are exempt. The warning never fails the gate.
A quotation property type
A property may be declared type: quotation (#1070, RFC-0046). Its value names a catalog
entry in of: and holds the copied words in span:. Add sha256: when the entry holds more
than one artifact. quotation-span-drift fails when the entry's cached bytes lack the words.
quotation-unresolved fails when of: or the pin names nothing. Where the bytes are not in
this machine's vault cache, or are not text, quotation-unchecked reports it at Info. A CI
runner with no cache sees only Info findings.
Nothing changes until a class declares the type. A corpus that coined quotation for itself
is now checked against this shape. yidam rename rewrites of: with the entry.
A quotation's of: is a citation of its entry (#1174). catalog-uncited and
verified-unsourced count it, as they count an edge source:.
Lint reports a decision or a URL nothing registers
New Info finding, decision-uncited (#1068). It reports a decision record nothing in the
repository refers to. A markdown link to the record counts. So does its path, decisions/<stem>,
named in any file git tracks, code included. A links: target or an edge source: naming its
id: counts. So does a decision/<id> entry in references:, or another record's supersedes:.
Text inside a REGEN block, or in a vendored or generated region, does not count. Across 13
derived corpora, it reported 29 of 346 records. Info, not a gate: your exit code does not change.
New Info finding, source-unregistered (#1068). It reports a URL in a node or a catalog
body that no catalog location: covers. A location covers its own path and every path beneath
it on that host. A corpus that declares no url or url_template location is not read. To
clear a finding, register the source, or add the URL as a location: on its entry. Info, not a
gate: your exit code does not change.
An edge source: is resolved
A new Error check, edge-source-unresolved (#1067). Before, lint checked only that a
verified edge wrote a source:. A value naming a renamed or nonexistent catalog entry passed.
Lint now resolves the value on every edge that writes one, whatever its tag. Three spellings
resolve: a catalog entry's file stem, a path written the way target: is, or a decision
record's id:. Every edge source in every derived corpus we measured already resolves. A
corpus that writes none has nothing to do.
If the check fires, the finding names the edge and the value as written. Rename the value to the entry's current stem, or baseline the finding.
The scaffolded .gitignore ignores .vscode/settings.json
The yidam extension writes this file itself (#1065). At activation its vendor guard marks
.yidam/.vendor/** read-only. Its schema wiring adds the yidam schema --settings mapping. Both
land in .vscode/settings.json. A git add -A then commits the file. Three derived repositories
did.
Why that matters. Other extensions write machine paths into the same file, such as a Python interpreter under your home directory. A tracked copy publishes the next one.
What to do. A new repository gets the rule at genesis. It matches at any depth. An existing
repository can copy it from sadhana/root/gitignore. If the file is already committed,
git rm --cached .vscode/settings.json untracks it. The extension re-applies the guard in every
window, so no protection is lost. To keep sharing the file on purpose, add
!.vscode/settings.json after the rule.
skills-index reports whether a skill is built
A skill's frontmatter may say status: built or status: stub (#1063). yidam skills-index adds a Status column and a count line above the table. A skill that says neither
is reported as unstated, never as built. The bootstrap now writes status: stub into each
calculator stub it leaves.
After this upgrade, yidam regen --check reports .yidam/skills/README.md as stale. Run
yidam skills-index and commit the table. Every existing skill reads unstated until you add
the field. Nothing gates on the value.
A built skill that another derivation also wrote can now be sent upstream. upstream.md names
the from:derived-skill label and its template.
yidam schema leaves a schema file it did not write alone
Repo-owned schemas (#1057). Every file yidam schema writes now carries a marker in its
$comment. When a target in .yidam/schemas/ has no marker, the run refuses before writing
anything, and names the files. A repository that compiles its own, stricter schemas into that
directory keeps them. It needs no guard task around mise run schema any more.
Files an earlier release wrote have no marker either. The first run after this upgrade refuses them. Replace them once, and commit the result:
yidam schema --force
yidam schema --settings is unchanged. It reads no schema file and writes none.
required: false silences missing-property
An omission the class licensed is no longer a warning (#1055). Before, missing-property
warned on every omitted property that was not required: true. A property marked
required: false warned the same as one that said nothing.
It is now silent on required: false. A property that says nothing still warns, and
required: true still gates. To accept a standing missing-property floor, write
required: false on the properties an instance may omit. No baseline is needed.
A re-vendor names the workarounds it makes unnecessary
Cited issues (#1054). Record a workaround with the upstream issue it works around, as
yidam#587 or as the issue's URL. After a re-vendor, yidam-vendor-update lists each cited issue that a commit at
the new pin fixes. The workaround for it can go. git grep yidam#587 finds it.
It reads tracked files only, and skips .yidam/.vendor/ and .yidam/corpus/. It needs no
network beyond the clone the re-vendor already makes.
A re-vendor now reaches ci.yml and CLAUDE.md
Scaffold regions (#1054). Genesis installs .github/workflows/ci.yml and .claude/CLAUDE.md
once. Until now no re-vendor touched them again. So a gate added upstream never reached your CI.
The scaffold now marks the part of each file that is yidam's. In ci.yml that is the privacy
and corpus jobs, between # <!-- YIDAM:CI --> and # <!-- /YIDAM:CI -->. In CLAUDE.md it is
the template's sections, between <!-- YIDAM:CLAUDE --> and <!-- /YIDAM:CLAUDE -->.
mise run yidam-vendor-update rewrites each region from the scaffold at the new pin. It never
reads the rest of the file.
An existing repository has no markers. Install them once, then re-vendor:
yidam migrate --dry-run scaffold # see what each region takes in
yidam migrate scaffold # do it
mise run yidam-vendor-update # fill the regions
Commit the migration as a migrate: commit. Anything inside a region is replaced. A step you
added to the privacy or corpus job shows in the re-vendor's diff as removed. Move it to a job
of your own, outside the markers.
A workflow with neither job gets an empty region, and the re-vendor fills it. A CLAUDE.md with
none of the template's headings is yours, and is left unmarked. The migration refuses when one of
your sections sits between two of the template's. Move it, then run it again.
yidam doctor has two new checks. scaffold warns while a file has no region. ci warns when no
workflow runs a corpus gate. It reads .github/workflows/ only, and follows a mise run into
your own mise.toml.
A node may declare a refusal, and derive check holds an argument to it
refuses: is a named node field (#1053, RFC-0045). It lists the sentences in which a node
declines an inference. A new refusal-span-drift lint check is an error when one quotes text
the node's prose no longer holds. A corpus that declares no refusals sees nothing new.
yidam derive check reads artifacts under [derive] paths. Without that key, it reads
nothing and passes. With it, every memo or dossier there needs a reach: and cites: spans.
It must also answer each declared refusal in a paragraph it cites.
SDK parity moves 0.16.0 → 0.17.0 and yidam-core 0.10.0 → 0.11.0, for the new field. An SDK
that predates it keeps refuses: in extra, where nothing reads it.
export --format llms prints instead of writing llms.txt
Stdout by default (#919). Without --out, yidam export --format llms wrote llms.txt at
the repository root. A reader who only meant to look at the corpus got an untracked file.
It now prints the pack to stdout. The summary line goes to stderr. With --out, nothing
changes. A script that reads llms.txt after the export needs --out llms.txt.
A domain article is checked, as the genesis commit holds it
Four new checks read .yidam/constitution/ (#593, RFC-0047). Bootstrap now writes a
constitutional augmentation there, with its Rego rule and cases. yidam lint reads each rule
from the genesis commit. domain-article-violated fails on a rule's refusal.
domain-article-edited fails when a file there differs from the genesis commit.
domain-article-unproven warns on a rule with no cases, or a failing case.
domain-article-unverifiable warns in a shallow clone, where no rule is read.
Nothing changes without the directory. No derived repository has one yet. An article appended
to the vendored CONSTITUTION.md did not survive yidam-vendor-update, and none was found.
A resolution record must name its rounds and positions
New check, resolution-deliberation-unrecorded (#592). It names a resolution record missing
rounds: or positions:. It also names a rounds: that is not a count of at least one.
PROTOCOL.md has asked for both fields since 2026-08-20. No record in any derived repository
carries them.
Old records warn. New ones gate. Git ancestry decides which is which. A record gates when the
commit that added it descends from the commit that put rounds: into your PROTOCOL.md. A
repository bootstrapped after 2026-08-20 has that line from genesis, so every record it adds
gates. A repository whose vendored PROTOCOL.md lacks the line only warns, until it re-vendors.
The repair is two lines of frontmatter. Write rounds: 1 if the loop ran once. List every
position file the loop read under positions:. A shallow clone cannot see the ancestry, so there
every finding warns.
cli/v0.16.0
A multi-line value leaves an inline block that shares its line
The marker contract (#1137). update_regen wrote a value that holds a newline in block
form. Block form is read by line. The open tag must start its line, and the close tag must
stand alone on its own. An inline block inside a sentence has neither, and the rewrite broke it
two ways. With text before the open tag, the tag became prose and the block was never read
again. With text after the close tag, the next run read on to a later block's close tag. It
then wrote over that block too.
Such a block is now left as it is. An inline block with its line to itself still takes the block form. SDK parity moves 0.15.0 → 0.16.0.
What changes for you: nothing, unless a generator returned more than one line into a block
inside a sentence. No generator does today. count returns one number. If one does, yidam regen leaves that block unchanged and regen --check does not report it. Move the block onto
a line of its own.
AGENTS.md reads by occasion, and a new generator writes it
yidam routes (#972, RFC-0039). A new derivation's AGENTS.md no longer lists every
prelude file to read before acting. It carries a <!-- REGEN: yidam routes --> block instead:
what every occasion reads, then one heading per occasion, each a list of section links. An
occasion is named by the commit verb it ends in. The block is rendered from
.yidam/.vendor/prelude/routes.yml, so a re-vendor brings the new routes and regen --check
reports a stale block.
An existing derivation's AGENTS.md has no markers, and a generator writes nothing where it
finds none. So yidam regen leaves the file as it is, and the whole-file list keeps working.
yidam migrate routes puts the routes block into an existing AGENTS.md
yidam migrate routes (#1135). Re-vendor first, so the prelude carries routes.yml. Then:
yidam migrate --dry-run routes # see which list it replaces
yidam migrate routes # do it
It replaces the bullet list under Before taking substantive action with the rendered block.
No other line of the file changes. Commit the result as a migrate: commit. From then on,
yidam regen keeps the block current, and a stale one fails regen --check.
It refuses when the heading is missing or has no list under it. So does a bullet in that list
linking anything but a vendored prelude file. That line is yours.
Each refusal prints the block to paste by hand. yidam doctor warns under routes until the
block is there.
The skills README no longer explains where judge went
sadhana/skills/README.md (#1077). The scaffold's skills README ended with a paragraph
about judge. It said the skill used to be listed there, and why it left. That is a note about
the template, and every repository installed it at genesis. A reader there has never met
judge.
judge scores runs of yidam's own bootstrap test harness. It lived in prelude/skills/, so
every derived repository vendored it. The bootstrap skill also read it before starting work.
In cli/v0.2.0 it moved to yidam/tests/, beside the harness that calls it. A derived
repository has no copy of that harness.
What changes for you: nothing. New repositories get the table only. In an existing
repository, the paragraph under "Inherited from prelude" in .yidam/skills/README.md can be
deleted.
A scaffold for watching a source, where unreachable is not unchanged
sadhana/github/workflows/watch.yml (#1073). A derived repository polled a source on a
schedule. For 24 rounds the source was unreachable. The job saw no diff, so the build stayed
green.
The new workflow runs a round you write at .github/watch/round. It appends one row per round
to .github/watch/heartbeats.tsv, and commits nothing else. A round that crashes, or prints no
verdict, is filed unreachable. A watch job in ci.yml reads the ledger. It fails after
seven unreachable rounds in a row, or seven days with no round.
What changes for you: nothing until you arm it. The workflow ships with no schedule. The
gate runs only when the ledger exists. An existing repository can copy both workflow changes
from sadhana/github/workflows/. The header of watch.yml says how to arm it.
yidam lint reads the artifact's links into the corpus
broken-object-link (#577, RFC-0028 Erratum 6). A repository declaring [object] paths
holds a corpus and an artifact that cite each other. A node's link into the artifact was already
checked. A link from a crate README to a node was read by nothing. Deleting the node left it
dead, and no finding named the README.
What changes for you: new warnings, if you declare an object. yidam lint now reads the
tracked .md, .rs and .ts files [object] paths claims. Each relative link into .yidam/
must resolve. A dead one is a warning at the line that holds it. Warnings do not fail the
build, and escalate_after cannot raise these. Fix the link, or drop it if the node is gone
on purpose. A #L range on such a link is now held by the line-citation checks too. A
repository without [object] paths sees nothing new.
kuten check gains a coupling field. It counts the links each way. For nodes, decisions
and catalog entries, it says how many the artifact cites and how many cite it. It is null
without an object, and for a projected corpus. The field is not required in the report
schema, so output from an older CLI still validates.
A derived repository overrides inherited tasks from mise.overrides.toml
The scaffold ships an include slot for overriding inherited tasks (#1064). A task in
mise.toml cannot override one from mise.yidam.toml. In mise, an included task wins over the
file that includes it. Among includes, the later one wins. A repository that needed to replace
an inherited task had to invent a second include. It also had to learn that rule. New
repositories now get mise.overrides.toml at genesis, empty and listed last. No vendor update
writes it.
What changes for you: nothing, unless you want the slot. An existing repository keeps its
mise.toml, which the vendor update does not rewrite. To adopt it, list the file after the
inherited layer:
[task_config]
includes = ["mise.yidam.toml", "mise.overrides.toml"]
A missing include is skipped without a word, so the line is safe before the file exists. A
repository that already keeps its own override include can keep it, or rename it. Do not use
mise.local.toml: mise also loads that name as a config file and warns about every task in it.
migrate value renames one value of a closed set
A value of a declared values: set can be renamed as one event (#1120). Declaring a set
closes it. So creek → stream could not be done in two steps. Renaming the declaration
first puts every instance in violation. Renaming the instances first puts them outside the
set. yidam migrate value <class> <property> <from> <to> does both halves together. It
rewrites the item on the declaration and the value on every instance holding it. It writes a
migration record. Quoting follows what was written. A value outside the set is refused. So is
a rename onto a value already in the set.
A class declares a closed value set, and property-type holds instances to it
values: on a string property (#1052, RFC-0044). A class could not declare the set of
values a property admits. So 40 properties across seven corpora spelled one in the
description, as extant | demolished | ruin. Nothing read it there. 33 instances held a
value outside the set their own class documented. A string property now declares the set as
values: [extant, demolished, ruin] beside type:. Declaring it closes it.
What changes for you: nothing until a class declares a set. No corpus carries values:,
and a property without one is unbounded, as before. Once a class declares the set,
property-type reports every instance holding a value outside it and names the set. The
finding gates, as the check always has. Each report is one of two things. A value the set
should have carried is one line on the declaration. Prose in a token field is a value to
restore. The match is exact: In operation is not in operation. The compiled class schema
now carries the set as enum, and the gate is no looser than the schema.
migrate retype into string is held to the set. A set on any other type is carried and
ignored, so it starts to bind at the retype. An instance outside it is reported and blocks
before anything is written.
A class file carrying values: is refused by every earlier CLI. The class-file schema is
closed. An older CLI would compile the set to nothing and validate the drift as fine. Upgrade
before adopting the field. SDK parity moves 0.14.0 → 0.15.0 and yidam-core 0.9.0 → 0.10.0.
Both are for the new OntologyProperty.values field, which every compiler emits.
phase settle refreshes the REGEN blocks, and a gates generator writes the gate table
yidam phase settle (#1066). Closing a phase requires the REGEN blocks to be current, and
settle never touched them. Every repository ran regen by hand one commit before the phase
commit. In the reporting corpus that was 101 of 118 phase commits. settle now asks what
regen --check asks, refreshes what is stale, stages it, and asks again. The printed sequence
opens with the regen: commit when there is one to write.
What changes for you: a phase with a stale block is not ready. settle used to say
ready over a block CI would have called stale. It now says not ready, with the remedy.
A block no generator writes is not ready either. Nothing is refreshed from a checkout that
differs from HEAD. settle names the files and the sync instead. A block generated from
that tree would not hold against the commit. The report carries a regen object: what
passed, what is stale, what was staged, and what was dirty.
yidam gates (#1066). A new generator, run by yidam regen with the others. It writes
a table of every run: step in .github/workflows/ci.yml into the README's yidam gates
block. The scaffold's README carries the block in place of the sentence that named three
gates by hand. An existing repository adds the block where that sentence is, and runs regen.
A declared gluon calculator is now refused by yidam lint
yidam lint (#1099). A capability declaring run = { gluon = "..." } was only checked when
it ran. A script at a path that does not exist, or one invoking a macro, was quiet until the
step. lint now refuses all three failures from the manifest, without invoking a calculator.
The three are reported as separate checks. calculator-script covers a path that does not read
and a script invoking a macro. calculator-scope covers a name the closed prelude does not bind.
calculator-type covers a script that is not Corpus -> Computed.
What changes for you: a corpus with a broken calculator now fails lint where it passed. The
repair is the one the step would have demanded anyway. Nothing here is a new rule about what a
calculator may say — lint and run call one admission function.
calculator-scope and calculator-type need a typechecker. They are absent from the report
of a binary built without calculators-gluon, which is the one install.sh downloads. A build
that held no script to the prelude should not report that it did. calculator-script is text, so
it gates in every build.
Bless either of the two from a full build and lint from a light one. The entry is carried
(#1114). The light run did not ask the check, so it neither compares the entry nor reports it
stale. It prints the ids it did not ask. A blessing from the light build keeps the entry too.
The same holds for unrecognized-verb without --commits. An entry under a check no build has
any more is still stale, and still fails.
A re-fetched artifact record keeps the redistributable: the entry already carried
yidam catalog-fetch (#1074). A record's vault: and redistributable: are decisions a
person makes. A fetch left both blank on every record it wrote. That is right for a first
capture: nothing an HTTP 200 establishes is a licence. It was wrong for a re-capture. A source
you had cleared produced a new record silent on the question. vault push then refused the new
bytes, and one licensing decision had to be re-entered by hand per edition.
Both fields are now carried forward from the entry's latest record for that same location. The
refresh: commit body names each field it carried and the digest it came from. A licence on a
new record is reviewable as continued rather than established.
What changes for you: a re-capture may now arrive already cleared. The assertion is still yours. The command reproduces the record you wrote and never invents one. A first capture is unchanged and still records neither field. Only the latest record for a location is consulted. Change your answer and every edition after it inherits the new one.
Entries whose latest record the old command wrote need one edit. That record is silent, and
a silent record carries nothing forward. Nothing here can tell a silence you intended from one
the command left, so it does not guess. Put redistributable: on the newest record for that
location once, and vault: if you had one. It carries from there. A record with no from: names
no location and is never a source for a carry. Those are written by hand or by a bulk importer.
A REGEN block written on one line stays on one line
The marker contract (#1094, RFC-0043). update_regen wrote every block the same way. A
newline after the open tag, the content, a newline before the close tag. A block written inside
a sentence came back as four lines, the sentence broken across them. That is the shape
RFC-0043's count generator needs, and the reason no generator writes one today. A block whose
body holds no newline is now written back without newlines. It stays where its author put it.
What changes for you: nothing, unless you had already written one. No generator emits an
inline block today, so no existing document changes shape. If you hand-wrote one and watched
yidam regen unwrap it, it will now survive. A value holding a newline of its own still goes
back in block form. It cannot fit on the line. A body that did not match its form would be
rewritten on the next run.
update_regen finds the block scan_markers sees
The marker contract (#1094). The two halves of the contract located a block differently.
scan_markers required the open tag to begin its line. update_regen searched the bytes and
took the first prefix match. Three consequences, all silent:
- A block in the middle of a line was invisible to the reader and rewritten by the writer.
- A block at column 0 whose close tag sat alone on a line swallowed the next block too.
update_regenmatched a command that merely began with the one asked for.
There is now one locator. update_regen asks scan_markers for every block. It updates each
one whose command is equal to the one requested — every one, not the first.
What changes for you: a document with two blocks for the same generator now updates both.
That was the intent all along. The old behaviour updated the first and left the rest stale.
regen --check then reported drift the command could not clear. A command that is a prefix of
another generator's name no longer matches it.
A capability may declare a typed calculator
.yidam/capabilities.toml (#1091, RFC-0042). run takes a second shape. A table naming one
gluon script sits beside the sequence it has always taken:
run = { gluon = ".yidam/capabilities/travel-tier.glu", calls = 2000000 }
The script's entry point is declared Corpus -> Computed. It is applied in this process. So a typed
calculator gets no scratch tree, no child process, and none of the five environment variables.
What changes for you: nothing, unless you write the new form. Every existing run = ["sh", …]
parses and runs as before. A receipt already committed for one keeps its bytes.
Two things are worth knowing before you write the table form. A typed calculator must declare its
own .glu under reads, the same rule the shell arm has. A declaration that does not is refused by
name. The script's digest goes in the receipt and in the input state, so editing a calculator makes
its step stale.
The arm is also behind --features calculators-gluon, which is outside the default set. The
binary install.sh downloads parses the declaration and plans it. It then declines that step by
name, and says which feature would run it. A corpus that wants the downloaded binary to run it
writes the sequence form.
regen --check reports a block no generator writes
yidam regen --check (#1062). A REGEN block whose command names no generator used to be
skipped in silence. Nothing wrote it, nothing reported it, and the gate passed. It now fails,
naming the file and the command.
What changes for you: a repository that passed may now go red. The cause is a marker
whose name is wrong, usually a typo. The block has been stale since it was written. Correct
the name, or delete the block. yidam regen does not clear it, because no generator carries
that name.
Only commands beginning yidam are judged, so a block your own tooling refreshes is
untouched. Measured across twenty-two repositories carrying REGEN blocks, the check found
none, so most upgrades will see no change.
yidam count — a number in prose, checked against the graph
New command and new REGEN generator (#1071, RFC-0043). yidam count <query> prints how
many nodes a query matches. With no query it is the generator yidam regen runs: it refreshes
every <!-- REGEN: yidam count <query> --> block in the tracked markdown set. Inline, so the
number sits inside its sentence. A figure published in prose is now checked by
yidam regen --check instead of remembered.
What changes for you: nothing until you write a block. No existing document has one. To
adopt it, replace a hand-counted figure with a block and run yidam regen:
The map has <!-- REGEN: yidam count district -->44<!-- /REGEN --> districts.
Two things are worth knowing before you do.
A query that does not typecheck refuses its block and fails the run. It does not write a
0. A query that cannot run has not counted zero of anything. The block keeps what it holds,
and the error names the file, the query and the diagnostic. Under --format json the run emits
no report at all, so read the exit code.
A block naming no query — <!-- REGEN: yidam count --> — is reported as unclaimed, not
written. No run can fill it. That verdict's wording changed with this release. It used to say
the command named a generator that does not exist. It now says the command is one no generator
writes, which is the true statement for this block.
migrate retype requotes an instance instead of refusing it
yidam migrate retype (#1044). Retyping to number now unquotes an instance holding
"24". Retyping to string or date quotes a bare 24. Both are repairs property-type
already named, carried out on the instances and nowhere else.
What changes for you: the command writes where it used to refuse. A retype across the
quoting boundary used to exit nonzero. It now edits each instance value, and the corpus still
passes its own gate. A value with no number in it still refuses, and names what it tried.
about 24 and ~24 are unchanged.
malformed-yaml reads your catalog and your decisions
yidam lint now gates on a catalog entry or a decision record whose YAML does not parse
(#1056). The check covered instances and classes. The other two records read through
unwrap_or_default(), which turns a file nobody can read into a record declaring nothing. One
corpus lost a catalog entry's TTL for its whole history, and a decision record that governed a
phase. One unclosed quote each.
What changes for you: a lint run that passed may now fail. Nothing about your corpus changed. What changed is that the silence ended, and the file the finding names was never being read. The repair is the parse error the finding quotes; it carries the parser's own line and column.
Two states are worth knowing before you look.
A catalog entry whose frontmatter did not parse was read as obtained: true. obtained: was
absent from the empty record, and absent means obtained. It carried no TTL, no used-by and no
artifacts, so catalog-expired, catalog-used-by-drift and catalog-artifact-malformed each
passed with nothing to check.
A decision record that did not parse was read as a record with no id: and no summary:.
yidam decisions renders that under the file's stem, with an em dash. It is how the log renders
a record nobody has filled in.
A file with no frontmatter, and a file with nothing in it, are both unchanged. Neither has
contradicted anything, and neither is reported. A frontmatter block that opens with --- and
never closes is reported: an opened header claims a document follows.
Every other finding about an unreadable file is suppressed, as it has been for instances and classes since #676. Fix the parse error and they come back, correct this time.
retrieve takes a where, and the index carries the properties it reads
yidam retrieve --where '<predicate>' (#1029, RFC-0041). The text inside a query step's
[...], verbatim: --where 'began<=1893,ended>?1893'. Same grammar, same check, same
comparison, applied before the k cut. It returns the rows query would, ranked.
The MCP retrieve tool takes the same string as where. A predicate that cannot be asked is
rejected with query's code. An empty answer the predicate caused is predicate-unsatisfied.
What changes for you: re-embed and re-index. The index gains a properties column holding
each row's declared date and number values. An index built before this reads as it did, and
retrieve without a where is unchanged over it. A where against it is refused as
where-unindexed. The repair is the two commands you already run:
yidam embed && yidam index-build
The same re-index repairs #1047. Every corpus.arrow before this held the first ten rows of
its corpus, whatever meta.json said. The export read them back through a query with
lancedb's default limit. retrieve on a local index and the web shell read that file. A
class-unindexed answer over a class the corpus holds was this.
The embedding record gains a properties object, absent where a node has no ordered property.
A corpus without one writes the records it wrote before. The SQLite export gains a
properties column. meta.json lists the index's columns.
A remote index does not carry the column. index-push leaves it behind on purpose, and a
server backed by one refuses a where as where-remote. Keyword search answers one in every
build.
MCP contract 0.25.0 → 0.26.0. retrieve gains an optional where. A client built against
0.25.0 never sends one and sees the response it saw.
A property can be a number, and a number can be ordered
type: number exists (#1030, RFC-0040). Declare it on a class property, and write the
values unquoted: length_km: 24. A quoted "24" is text, and property-type now says so.
The four ordering operators are licensed on it, and = compares numerically. So
reach[length_km>9] returns the reach measuring 10, and length_km=7.0 matches a stored 7.
A unit is declared once, on the column. unit: km sits beside type: number on the
declaration. Instances carry bare numbers, and the compiled class schema publishes the unit
as x-yidam-unit, an annotation nothing validates against. A class file carrying unit:
is refused by every earlier CLI's class-file schema, which is the correct refusal.
MCP contract 0.24.0 → 0.25.0. SDK parity 0.12.0 → 0.13.0. yidam-core 0.7.0 → 0.8.0.
unordered-property's message names date and number; the code is unchanged.
OntologyProperty gains unit in all three SDKs. In Rust that is a new public field on a
struct a caller can write as a literal. The crate moves a minor version for it. A client built against 0.24.0 never asks to order a number, so nothing it
does today behaves differently. Nothing on disk changes: no corpus has a number yet.
examples/streamflow retypes reach.length_km and its two instances drop their tildes.
doctor --strict now asks about .yidam/computed/
doctor gained a computed question (#1028). A calculator's writes glob governed the
executor and nothing else. So a corpus could compute an answer, commit it, and have no surface
that read it back. doctor now reads what is in .yidam/computed/. It attributes each file to the
capability that declares it, and says whether the answer still stands.
What changes for you, and only if you have that directory. A computed file is now a warn
when its inputs have moved since its receipt. So is one whose bytes are not the ones the receipt
recorded. Both were silent before. doctor still passes on a warning; doctor --strict does
not. So strict CI that was green yesterday can go red today, with no file changed. The repair is
the one the check prints: yidam run, then commit what it lands.
The window right after a run reads differently from a stale answer. yidam run writes a commit
and deliberately leaves your working tree alone. Between the run and the sync, the files it produced
are at HEAD and not in your checkout. That is its own warning, remedied by
git restore --source=HEAD --worktree --staged -- .yidam/, rather than a report of never having
run.
A file that is not a signal table is not a problem. Reading requires a top-level
format_version: 1 and a signals: list. Anything else is listed and ignored.
cli-reference has the shape, and RFC-0026 §4.2 the argument.
yidam embed attaches computed signals
An embedding record now carries a signals object (#1028) where a signal table names that
node. The key is absent where there is none. So a corpus that computes nothing writes the
records it wrote before, byte for byte. An index already built stays valid.
What changes for you. If you have signal tables, re-run yidam embed and yidam index-build
to pick the signals up. Nothing forces this. The records you have are still readable, and a stale
one carries no signals rather than wrong ones. Signals are not part of the embedded text, so the
vectors do not move.
The keyword arm can rank
retrieve without a vector index now ranks by BM25 (#1026). It scored the fraction of query
terms a node held. Every node holding all of them scored exactly 1.0. The tie broke on the node
id. So a two-term query over forty matching nodes returned the first k alphabetically.
This is the only retrieval a released binary performs. --features vector-read is not in the
release matrix. So the shipped channel degrades to keyword search, and that arm could not order its
answers.
What changes for you. The same nodes come back. Only the order is new. A short node about your query now outranks a long one that merely mentions it. A rare term outweighs a common one.
A degraded score is no longer a fraction of one. BM25 is unbounded. Across the walkthrough
corpora in this repository the anchor score now lands between 3 and 6. Every one of them used to
read exactly 1.00. Nothing dropped out: the IDF is the +1 variant, which stays positive even
for a term every node holds.
An anchored query ranks the same way, over the step's candidate classes. retrieve also
reaches installed dependencies, so the same term can weigh differently in the two arms. That
follows from the candidate sets, which differ on purpose.
yidam serve --mcp can say whether a corpus has ever been read
serve --mcp wrote nothing at all before this (#719). Not a log, not a counter, not a cache.
Thirteen tools dispatched, returned, and the process forgot. So this repository could say who
asserted every node, and when, and under what review. It could not say whether any node had ever
been read.
One key turns the other side on, in the corpus's own .yidam/config.toml:
[serve]
record = true
With it, one line goes to .yidam/record/calls.jsonl per tools/call, over either transport:
{"at":1758758400,"commit":"2bb499a","tool":"retrieve",
"args_digest":"sha256:9f3a…","outcome":"ok","results":3,
"degraded":true,"rejected":false,"ms":12}
That makes four questions answerable that were not. Which queries came back empty — previously
discarded, and the most direct evidence of what a corpus is missing. Whether the degraded keyword
path served real traffic. retrieve always reported degraded per call, and nothing aggregated
it. So this corpus has answered from keyword search for a month was not a statement anyone could
make. Whether anything ever acted on a clock. And how much of the read surface is used at all.
Nothing changes for a corpus that does not write the key, which is every corpus today. Absent, the server writes nothing, exactly as before.
Your query text is never recorded. A digest of the arguments and nothing else, on both
transports. Over --http a server answers callers it cannot authenticate. The record must not
become a file of their questions. The digest is stable, so the same call digests alike.
.yidam/record/ must be gitignored. A server that declared record refuses to start until it
is. A derived repository gets the entry from the template's own .gitignore. A repository that has
diverged needs the line added. The check asks git check-ignore, so .git/info/exclude or a
global ignore file satisfies it too. The rule is vault materialize's. The reason is related: this
project's protocols prescribe git add -A, and a tracked record dirties the tree after every
served session.
The file is a staging buffer, not the record of last resort. The history is the graph, and
folding this into a refresh:-class commit is a scheduled run. git commit-tree on the read path
would make the cheapest tool call the most expensive thing the server does. A record of what was
retrieved is operational under RFC-0026. So it needs no new authority concept and no author.
That fold is not built yet (#1018), and neither is a report over it (#1019).
yidam overlay copies what git tracks
Each subtree overlay copies is now the tracked set under it (#984). yidam/, sadhana/
and samudaya/ used to be walked on the filesystem, minus a list of names. That list is the one
#912 took away from yidam clone. It was left standing here. Measured against a working
checkout, six gitignored paths under yidam/ were reached by no entry in it. Two .astro/
build caches. Two junit.xml reports. The compiled VS Code extension, and a pytest cache. All
six travelled into every repository overlay was run against. That is the half of bootstrap
where the target already holds someone's work.
What changes for you. An overlay from here adds no build output and no editor caches.
Nothing tracked stopped travelling. As with clone, an uncommitted file in your yidam checkout
will not reach the target. Commit it, or at least git add it.
overlay now refuses a source it cannot read a tracked set from. It does not fall back to
walking the directory. A fallback restores the whole hole in the circumstance nobody tests. The
source has to be a git checkout anyway. The .yidam.toml pin it writes is read from that same
git directory.
malformed-yaml reads .yidam/corpus/universal.yml too
yidam lint now gates on a universal-declarations file whose YAML does not parse (#1081).
The check covered the four records a corpus is written in after #1056. The fifth file a lint run
reads was still read through unwrap_or_default(). A single unclosed quote in it read as a file
declaring no universals. Every check that consults them then passed over an empty list. A gate
reported clean over declarations it had not read.
What changes for you: a lint run that passed may now fail. Nothing about your corpus
changed. The finding names .yidam/corpus/universal.yml and quotes the parser's line and
column. Every other finding about that file is suppressed until it reads. A repository with no
such file is unchanged and is not reported. Absent is a legitimate answer; unreadable is not.
A document whose yidam: block is not a findings record is reported
New findings-malformed check (#1081). An instance or catalog entry may carry a yidam:
block in its frontmatter holding findings. The block is ordinary YAML, so the file parses.
malformed-yaml has nothing to say about it. But a block of the wrong shape decoded to no
findings at all, silently. Three shapes did, all of them legal YAML:
- A list where a mapping was wanted.
- A bare string.
- A mapping whose keys are not the record's.
Each read as a document with no findings.
What changes for you: a document carrying a block nothing could read now fails the gate. The
finding quotes the decoding error. A document with no yidam: block is not reported, and neither
is one whose block reads. A file whose frontmatter is broken is reported by malformed-yaml as
before and is not attributed to the block.
yidam doctor counts all four records, and reads your bundle manifests
yidam doctor (#1081). The corpus line counted instances and classes. It printed
N file(s), all readable on a repository with an unreadable catalog entry or decision record.
That is the same silence malformed-yaml had before #1056. It was in the command people run to
ask whether a repository is sound. The line now counts all four records, and a failure names how
many of how many do not parse.
The corpora line now reports an unpacked bundle whose manifest.yml does not parse. That
file is where a dependency's commit, genesis digest and index model are read from. Every field
in it is optional, because an older bundle format legitimately omits them. So a manifest nobody
could read was indistinguishable from an old one. It also switched off the shadow check, which
compares genesis digests and stays quiet when either side is unknown. tonpa install now warns
on the same condition as it writes the file.
What changes for you: doctor may now fail where it passed. The remedy for a manifest is
mise run tonpa-install. The remedy for a corpus file is yidam lint, which quotes the parse
error. A dependency that is not installed is reported as not installed, and not also as
unreadable.
samudaya audit says when a seed's header did not parse
yidam samudaya audit (#1081). A seed whose frontmatter does not parse was read as a seed
declaring nothing. The audit then reported the fields it found missing — kind: first — rather
than the reason it found nothing. The parse error is now reported for that file. The field-level
complaints are not, since none of them was measured. A seed with no frontmatter at all is
unchanged: it has contradicted nothing.
cli/v0.15.0
yidam clone copies what git tracks, and refuses a source that is not the template
A clone is now the tracked set of the checkout it is run from, minus NOT_INHERITED (#912).
It used to walk the working tree and subtract a list of names. A clone taken from a working
checkout was 2,931 files and 22.7 MB. Of that, 1,436 files and 14 MB was .claude/worktrees/.
It was gitignored the day that entry was written, and absent from git ls-files all along.
The same hole delivered .local, and dist against dist-*/ was #900.
What changes for you. A derived repository created from here carries no build output, no install prefix and no agent scratch directories. The same clone now measures 1,433 files and 15 MB. Nothing tracked stopped travelling: the exclusions are unchanged, and every one of them is a path somebody committed on purpose.
An uncommitted file in your checkout will not reach the new repository. That is the point
of the change, and it is the one way it can surprise you. If you were editing the template and
cloning to test the edit, commit it first — or at least git add it.
clone now refuses a source that is not the template (#913). It copies the directory it is
run from, and nothing asked what that directory was. From an empty directory it wrote a target
holding one file, .yidam.toml. Quickstart §3 leaves the reader in a copy of
examples/streamflow. From there it copied 21 files of another domain. It printed
Pinned to yidam 2261d6e2 — streamflow's own genesis commit, labelled as a yidam pin. Both
exited 0.
What changes for you. clone and overlay are run from a checkout of yidam. An installed
binary carries the CLI, not the template, so this is the prerequisite:
git clone https://github.com/goedelsoup/yidam && cd yidam
yidam clone ~/my-corpus
The test is yidam/prelude/ and sadhana/. Those are what a derived repository does not
have: bootstrap vendors the prelude away and consumes the scaffold at genesis. So a derived
repository is refused too. To move a corpus, copy the corpus.
A clone that has not been bootstrapped is a state, not a failure
yidam doctor reports a fresh clone as a warn and exits 0 (#914). It used to report
fail repository … is a git repository with no .yidam/, with the remedy yidam overlay . —
overlaying the template onto a copy of the template. graph-check, lint and the other gates
said not a yidam repository … Derive one with 'yidam clone <target>', naming the command
whose output the reader was standing in.
.yidam/ is written at genesis, which is step 8 of the bootstrap dialogue. Between clone and
genesis a repository has a pin and no corpus. That is not a fault. It is the state bootstrap
starts from, and all three reports now name it and point at BOOTSTRAP.md.
What changes for you. A CI job that runs yidam doctor and keys on the exit code now
passes here, where it used to fail. Three conditions together recognise the state: .yidam.toml
present, .yidam/ absent, and at most one commit. A repository that has been worked in and has
lost its .yidam/ is still a fail, with the older message. That is a breakage rather than a
beginning.
doctor --strict still refuses it, which is the reading a CI job wants. Nothing that gates
on a corpus started passing: graph-check, lint, export, schema and bundle exit 1 as
before. Only what they say changed.
yidam --help is short, and --help-all is the full listing
yidam --help now prints thirteen commands instead of fifty-eight (#921). It ran to ninety
lines, and the eleven <!-- REGEN --> generators — corpus-index, crates-index,
bundle-status and the rest — printed above graph, retrieve and query, which are what
the tool is for. A reader opening it to find out what yidam does met a maintenance surface
first.
What changes for you. Nothing about the commands themselves: every one still exists, still
takes the same flags, and yidam <command> --help is unchanged. What moved is where the whole
roster is printed. yidam --help-all is the ninety-line grouped listing, * markers and all.
If you parse yidam --help, read --help-all instead. A script deriving the command set
from the short listing will now see thirteen commands, not fifty-eight. One deriving the set
that writes will see five, not thirty-two. Neither will fail while doing it. That is the one
way this change is quiet, so it is the one worth checking. docs/cli-reference.md documents
the full surface, and a gate holds it to --help-all.
yidam with no arguments now prints the short listing. It used to print an error about a
missing subcommand. Both exit 2; only the text changed.
The web-install, web-dev and web-build tasks are gone
packages/web/ has been deleted, and its three inherited tasks with it (#942). The
browser shell read an exported .yiz bundle. #236 closed it by decision. The tasks outlived
that decision in mise.yidam.toml, which every derived repository inherits.
What changes for you. mise run web-install, mise run web-dev and mise run web-build
no longer resolve. In a derived repository they could not run anyway. Each began with cd packages/web, and the shell was never part of the scaffold. The removal makes that visible
in the task list rather than at the prompt.
Nothing replaces them. RFC-0030 records why a rendered reader is a derived repository's own object, not a template surface.
cli/v0.14.0
yidam lint reads a quote set off in a blockquote
A citation that shows its passage under the link is now held to it (#899). The house writes a quote two ways: inline, or set off below the citation.
The set-off fence has been read since #758. The blockquote had not. So a citation carrying its evidence on the page was scored as carrying none.
What changes for you. A citation of that shape may now report slid-line-citation
instead of unverified-line-citation. That is Error, and under the baseline ratchet.
The finding is not new rot. The quote was already wrong about the lines; nothing read it.
Re-point the citation, or yidam lint --bless if the debt is inherited. The finding names
the range the passage moved to, so the repair is a transcription.
The rule is adjacency, as it is for a fence. Everything between the link and the > must be
punctuation. It must contain the colon or dash that introduces it. An aside that follows a
full stop is not adopted.
yidam policy --format json now emits the report contract, and one key was renamed
All four policy subcommands gained the report envelope (#893). check, eval, gate
and test printed their fields with no envelope around them. RFC-0024 named its dependency as
"RFC-0001 (the report contract policy check --format json emits on)", so this is the
contract arriving, not changing.
The addition is safe to ignore. The envelope carries the report flattened, so every key
these commands already emitted keeps its name and its place. A consumer reading .ok,
.allow, .deny or .tests needs no change. What it gains is format_version, yidam and
root.
One rename, and it is breaking: policy test's passed is now passing. It was a count.
This contract gives passed exactly one meaning: the gate verdict, a boolean, in
graph-check, regen --check, index-verify and doctor. One key cannot carry two types for
two commands. If you read .passed from policy test, read .passing. Nothing else moved:
.failed and .changed_by_override are unchanged, and tests[].passed is a different,
nested key that was always a boolean.
Why none of this was caught before. report_goldens.rs requires every --format-bearing
command to have its fields checked. It found those commands by scanning top-level --help, and
clap does not print a group's children's flags. So policy's four — and kuten check, and
phase's three — were never in its population. The scan now descends.
yidam phases grew two columns and a fifth state
phases rows carry type and source, and state can now be interrupted (#473). A
phase gained a record: .yidam/phases/<name>.yml, written by the new yidam phase start.
Where a ref carries one, it decides whether the phase is running or stopped partway. Ref shape
cannot see that difference, which is why the value is new rather than a renaming.
report.schema.json declares state as a closed enum. A validating consumer that pinned
the four-member list will reject a report carrying interrupted. Widen it. The five members
are active, interrupted, settled, rewritten and position, and git::REF_STATES is
the roster both sides are held to.
Nothing in your repository has to change, and no phase you already have is affected. Every
existing phase/* ref carries no record, reads exactly as it did, and is marked source: ref.
RFC-0028 §3 keeps that arm permanently rather than as a migration window. type is absent on
those rows, never blank. There is no default phase-type list, and a consumer must render the
absence rather than supply one.
If you consume cycle's in_flight or due's phase clock, they now include interrupted
phases. Both filtered on state == "active", which was the whole of in flight while
active was the only unsettled state. A run that stopped partway is more in flight than one
nobody touched today, so it counts.
yidam run is a plan, and the domain-computer indexes gained a column
yidam crates-index and yidam packages-index write a third column (#472). It names the
capability that runs that crate, read from .yidam/capabilities.toml. A crate nothing declares
gets an em dash. Before, that crate and one implementing a connector produced the same row.
Your regen --check will report those blocks stale until you re-run them. Nothing about
your repository changed; the generator's output did. yidam regen rewrites both and the gate
goes green again. This is the only thing here that turns a passing gate red.
A fresh step is now skipped rather than invoked. yidam run <step> compares the step's
input state to its committed receipt before invoking it, and runs nothing where they match.
It used to invoke every time and discard the result when the bytes came back identical. So a calculator's side effects stop happening on a run with
nothing to recompute. A log it appends to, say, or a request it makes. Declare ageing_days = <n> on the capability to re-run it on a
cadence regardless. That is what the key is for.
yidam run <step> now also runs what the step declares it comes after. after is new,
so nothing you have declared can be affected — a manifest carrying it did not parse before.
yidam run with no step argument runs the whole manifest, and --dry-run resolves the plan
and writes nothing.
yidam run --format json changed shape. It emitted one step's fields at the top level:
step, verb, route, committed. It now emits steps, an array of those, beside
requested, dry_run, ran, skipped and committed. A consumer reading the old shape must
move down one level. The envelope's format_version is unchanged, and deliberately: run's own
fields were never in the frozen contract. report.schema.json declares the envelope, not this
command's body.
A capability that does not declare its own implementation is now refused by name. The step
is invoked in a tree holding exactly what reads resolves to, so run = ["sh", ".yidam/capabilities/x.sh"] needs .yidam/capabilities/** in its reads. Such a manifest never
worked; it failed at invocation with sh: no such file or directory. Now it says which
declaration is missing.
Committed REGEN blocks no longer report build artifacts
Three gated blocks stopped asserting things no commit carries (#895). The rule is the one
cli/v0.12.0 states below. A committed, gated block may only report what every checkout of that
commit agrees on.
yidam status drops its index cell. The block no longer renders index present or index not initialized. yidam index-status and yidam bundle-status now write a pointer. Their blocks
say where the answer lives instead of answering.
Why. The vector index and the bundle are build artifacts. Neither is in any commit. The blocks
stat-ed them anyway, so yidam regen --check answered about the machine.
Measured on one derived corpus, same tree and same commit: moving .yidam/index/ aside flipped
the gate. Exit 1 became exit 0. CI has no index and so never saw the failure. It landed on the
contributors who had adopted --features index.
What to do. Run yidam regen once and commit the result as a regen: commit. If you move a
local index aside before mise run ci, you can stop.
Where the measurements went. yidam index-status and yidam bundle-status still print them.
yidam doctor's index check and yidam due's index row still report freshness. yidam status --format json still carries index_present. Nothing reading a report loses a field.
The scaffolded .gitignore now ignores .yidam/index/ and .yidam/bundle.yiz. Only
*.lance/ was ignored before, so meta.json and embed.config.json stayed tracked.
Why that matters. yidam index-build writes indexed_commit as the current HEAD. Committing
the index then advances HEAD past it by one. The commit writing "up-to-date" was itself the change
that made it stale.
What to do. A new repository gets both rules at genesis. An existing one can copy them from
sadhana/root/gitignore. If an index is already committed, git rm -r --cached .yidam/index
untracks it.
yidam serve --lsp lints an unsaved buffer as a node
A buffer whose file does not exist yet is now checked (#607). Before, no check saw it. Its findings were none, which is what a clean node's are. Now it is a node, if its path is one the corpus walker would accept.
Your editor may show new findings on a new file. They are the findings yidam lint would
report once you save. Nothing changes for a buffer whose file is on disk.
The server declares it. The initialize result carries
experimental.yidam.unsavedInstances: true. A client that needs this can check for it.
A seat can say what it holds, and yidam lint reads it across the seat's own history
Four new findings about ma/* branches (#294). A seat may now keep
.yidam/sangha/commitments/<elector>.md on its own branch. It carries two sections, ## What this seat holds and ## What this seat has withdrawn. Each item links the position that
argued it. The file is never transported onto the baseline.
One new Info finding fires whether or not you adopt it.
elector-commitments-absent reports a seat that has filed a position and carries no
commitments file. A repository with three such seats gains three Info findings and nothing
else. Your exit code does not change. The other three are silent until a commitments file
exists.
Two of the other three gate, and only over a file you wrote.
elector-commitments-malformed is an Error when the file does not carry both headings. A file
with no headings parses to two empty sections, which would turn the next check off.
elector-commitment-vanished is an Error when a ground disappears. A position named under
holds at one commit, and in neither section at a later one, is the finding. Deleting the file
counts, because it takes the grounds it held with it. elector-position-unindexed is Info and
reports one of the seat's own positions that neither section names.
The item's identity is the position it links, never its prose. Reword an item freely. What
must not disappear is the link. Moving it to ## What this seat has withdrawn is always the
answer. Withdrawing a ground is the act the loop exists to produce, and is never reported.
The commitments file is read from the branch, so a thin clone reports less rather than
differently. A checkout without the ma/* commits sees no seats at all, like
resolution-independence-mismatch. Fetch the elector branches to get the real answer in CI.
yidam lint now derives a resolution's independence:
New Info finding, resolution-independence-mismatch (#823). It reports a record whose
stated independence: is not the one its seats derive. The derived value rides in the finding,
so the finding is also the repair. Info, not a gate: your exit code does not change.
It is silent unless your registry binds Kind, Model, Version and Config. Without
those columns every record derives unrecorded. A record that states nothing over an
unrecorded derivation is passed over. Filling the columns in is what arms it.
The registry is read at each seat's own tip, not at HEAD. A checkout without the ma/*
commits reads unrecorded rather than falling back. --depth 1 and --single-branch are both
that checkout. So a record that does state a value will report there. Fetch the elector
branches to get the real answer in CI. resolution-scope-unverifiable already warns about the
same thin clone.
yidam sangha --json gains resolutions[].independence, a string, empty where the record
carries none. Not required by the schema, for the reason synthesized_by is not.
cli/v0.13.0
Several corpora can share one vector index, and a query can ask across them
MCP contract 0.23.0 → 0.24.0. retrieve takes an optional corpora argument, every
response carries scope, and every result carries corpus (#835). A server built against
0.23.0 answers every call unchanged. A client built against it never asks to span, so nothing
it does today behaves differently.
Nothing on disk or in a bucket moves. Vector keys have carried the corpus since the first
push. So has corpus, as a filterable metadata key. An index several corpora already push to
can be asked a spanning question, with no re-push by any of them.
Only a remote index can answer one. A local .yidam/index/ is one corpus by construction.
A call that asks to span it is not an error. It is not silently honoured either: it answers
locally and reports scope: "local". Compare scope against what you asked to know whether
the span happened.
A result from another corpus cannot be fetched. Its id is the reference grammar's
absolute form: yidam://<corpus>/node/<class>/<name>. get_node cannot resolve it, because
that corpus is not installed here. Its text is all you get. corpus is null for
this server's own rows, so a client can tell the two apart without parsing anything.
corpus is not origin. origin names an installed dependency under .yidam/tonpa/,
whose nodes this server read and whose ids it resolves. A corpus that merely shares an index is
neither. One word for both would say a row is followable when it is not.
yidam retrieve, and one vector space per index
A new command, and a new refusal from index-push. Neither changes a corpus. yidam retrieve <words> is the retrieval serve --mcp performs, dispatched through the same tool
call, with --k, --class and --corpora. It had no terminal route before.
index-push now refuses an index built in another vector space. An index carries one
embedding contract and every push overwrites it. Two spaces in one index would let a spanning
query rank one corpus's rows against the other's. The scores would look ordinary. If your push
starts refusing, that index already holds a contract your embed.config.json disagrees with.
Push to a different index, or rebuild with the settings it declares.
Where the contract cannot be read, the push proceeds and says so. A write-only credential
is a legitimate shape for a pusher. So a 403 on GetVectors is a printed note, not a
refusal. A push also now reports the other corpora it found in the index, with a row count
each. --dry-run is the read-only way to ask.
yidam migrate findings lifts the questions an earlier propose wrote
A finding is a record under the node's yidam: key. It used to be an English sentence appended
to description:. It was found again by grepping the prose for its opening words. Paragraphs an
earlier release wrote are still recognised and still closed. Nothing was stranded, and nothing
here is urgent. This is the one-time lift (#728).
yidam migrate --dry-run findings # what it would do
yidam migrate findings # do it
Two numbers move, and only for a corpus that runs it. The [open] claim counts drop. A
carried question stops being counted among the claims the corpus makes. That is the whole point
of the record. open-questions does not change: the record is still an open question on the
node.
A corpus publishing a claim tally in a generated block will see that tally fall. Roughly by the
number of questions propose has open. Re-run yidam corpus-index after the lift.
A paragraph you reworded stays prose. The lift matches the marker, the check in brackets and
the fixed framing sentence exactly. A sentence you rewrote is yours, and this will not guess where
the tool's words ended. Those are counted in the report and left alone, [open] tag included. So
a reworded paragraph keeps counting as a claim until you decide otherwise.
A catalog entry with no frontmatter is refused rather than lifted. Removing the paragraph there would leave nowhere findable to put the record. The run reports the file and writes nothing at all.
The migration is idempotent and writes a record under .yidam/migrations/.
A retrieve result says whether its text is all of it
MCP contract 0.22.0 → 0.23.0. Every entry of results carries truncated, a boolean
(#853). It is false on keyword search and on a local index. Neither has a per-row ceiling to
cut against. Only a corpus served out of a remote vector index can answer true. A server built
against 0.22.0 still answers every call. A client built against it reads a cut row as a whole
one, which is the state this ends.
A remote index stores each row's text under a 40 KB ceiling. yidam index-push already cut
the rows that exceeded it, and already said so in its report. What was missing was the other
end. The flag travelled back with the row and retrieve dropped it. So half a document rendered
exactly like all of one. Nothing about what is stored changes here, and no index needs
rebuilding.
Expect almost no true. Across sixteen measured corpora, one row in 3,246 is cut. It is a
catalog source rather than a node. A node's text is the fields somebody wrote; a source's is a
whole markdown document that no format caps. A remote index over catalog sources is where this
bites. It is where you find out which of them you have been reading half of.
An edge may no longer assert a standing its endpoints contradict
edge-standing-unheld is a new warn (#858). It reports an edge asserting a standing stronger
than one its own endpoints declare. claim_tag: verified between two nodes graded [open] claims
more about the relation than the corpus claims about either end.
It reports in every corpus, with no declaration, like edge-verified-unsourced. Writing the
tag is the opt-in. A relationship listed under structural: is not exempt. Bookkeeping that
asserts more than the nodes it files has stopped being bookkeeping.
A node's standing is a property its class declared type: claim. Nothing else. Not the
weakest marker in its prose. A synthesis node carries all three tags by design, so reading its
weakest would grade your best-made nodes [open]. A corpus whose classes declare no claim-typed
field therefore sees nothing here, however its edges are tagged.
It is one-directional. An open edge between two verified nodes is never reported. Such a
corpus knows both things and does not say they are related. That is the vocabulary working.
This check's population is not empty by construction, and it is the only one here. That is why
it is warn, and why it stays warn. Both sides of the comparison are opted into separately. So a
corpus can adopt edge tags on nodes graded years earlier, and inherit findings it did not write.
The repair is a demotion on the edge, or a promotion on the node with a reason. Nothing proposes
the promotion for you. yidam lint reports more findings and mise run ci passes.
An edge's standing is now counted and listed, and where it used to be counted it was the node's
claim_tag on a link was graded by two lint checks and read by nothing else. open-questions,
status, corpus-index and the MCP claims and open_questions tools now read it too (#857).
A corpus that tags no edge sees none of this. Every figure and every table below appears only
where there is something to report.
A bracketed edge tag stops being counted as a node's claim. A link writing claim_tag: "[open]" was visible to the byte scan over the node's file. That is the spelling a corpus
adopts after being told the prose scan needs brackets. So the edge's standing was already being
reported — as an [open] in the node's own prose. It now belongs to the edge.
If your corpus writes the bracketed form on links, expect three things. status and
corpus-index will show fewer node claims. A new edge figure will carry the difference.
And the node will leave open-questions, with the edge arriving in its own right. The bare
form — claim_tag: open — was never counted anywhere and only gains.
status and corpus-index grow a second figure rather than a bigger one. claims still
counts a node's prose and its claim-typed properties; edges is the same three over its links.
A corpus-wide total is the two added, and nothing adds them for you. An edge is in no node's
text, and it belongs to two nodes at once. One merged number would answer about a denominator
nobody chose. The edges segment and the Edges column render only where some edge is tagged.
That keeps yidam regen --check green in a repository that has not made the distinction.
An open edge is its own entry in open-questions, not a promotion of the node. It is listed
under the node's label, with the triple beside it. The link still points at the node, because
that is the file it is written in. The JSON gains scope — node or edge — on every entry,
and relationship and target on the edge ones.
MCP contract 0.20.0 → 0.21.0. claims serves edge claims with scope: edge;
open_questions gains the edge arm and scope on every entry. A server built against 0.20.0
still answers every call, because the additions are new fields and new entries. But it
under-reports a corpus that tags edges, in exactly the way the CLI did before this.
An edge may say what it rests on, and a verified one is asked for a source
A link could always be written with extra keys and nothing read them. claim_tag: and source:
are now part of the link shape, and two checks read them (#587).
edge-verified-unsourced reports in every corpus, with no declaration. A link writing
claim_tag: verified and no source: is a new warning where there was none. Tagging edges is the practice this came from, and the published schema used to
underline it as invalid. If your corpus does it, expect one finding per verified link with
nothing behind it. The repair is a source: or a demotion to inference. Which of the two is
yours to decide; nothing proposes a promotion.
edge-untagged reports nothing until you ask for it. Its population is every edge, so it
runs only where .yidam/corpus/universal.yml says so:
edge_claims:
required: true
structural:
- instance-of
- concerns
- subject-of
structural: names the relationships that are bookkeeping rather than empirical. Both keys are
new and both are optional; a corpus that writes neither is checked exactly as it was. Writing
structural: alone records the exemption and switches nothing on.
Both checks are warn, so neither reaches the baseline and neither turns the gate red.
yidam lint reports more findings and mise run ci passes.
The editor stops underlining the two keys. The link item in the published node schema listed
target, relationship and note, and closed the object. So a corpus writing edge provenance
got a red squiggle on every tagged link. Rerun yidam schema to pick up the new shape, and
edge_claims: in the universal.yml schema with it.
The MCP contract has a write tier, and a server's corpus snapshot is no longer fixed at startup
The contract goes to 0.22.0 and gains one tier, act, holding two tools: propose and
cycle. Both are absent from every server that has not been told to write. That is every
server today, so nothing about an existing deployment changes until somebody writes the key.
Two things to know if you consume this surface.
The freshness sentence narrowed, and today nothing you can read moves. Contract 0.9.1 said that every read came from the corpus built on disk at startup. Freshness was a restart. That is now startup, or the server's own last write.
A change made outside the server is still invisible until a restart, exactly as before. An
edit, a tonpa install, a commit from another process: all unchanged.
The second half is the part worth having before you change any client code. propose builds its
commits against a temporary index and creates the ref with update-ref. The working tree is
untouched and HEAD does not move. Every read tool answers byte-identically across the write.
So the reload is a correct no-op for the only write this tier has, and no response observably differs. The rule is in the contract for two reasons. It costs one corpus re-walk on a call that already wrote to git. And the first act tool that touches the working tree should not also have to be a contract change.
If you cached a handshake's corpus.commit, it is still correct today. It is no longer guaranteed
to be.
act is the one capability in the block that is permission rather than ability. Every other
key is filled from what the server can back. This one is false unless the corpus says otherwise,
even on a server that could write perfectly well. A client must never infer it.
To turn it on, in the corpus's own .yidam/config.toml:
[serve]
act = true
And three clauses must hold, or the server refuses to start rather than quietly serving the read tools:
- a git author identity resolves in the corpus being served —
user.nameanduser.email, the values the commit would take. A checkout with none cannot declareacton any transport, stdio included; - the declaration is this key and nothing else. A flag would make may a tool write into this corpus a property of whoever launched the server;
serve --mcp --httpbinds loopback. A server reachable from another machine may not declare it, because no author exists for a remote caller yet.
The refusal is the point rather than an inconvenience. An operator wrote the key and got a running server. They would read that as the answer to the question they asked.
What propose may write is unchanged from the CLI. Three verbs go onto a propose/<head>
branch: open, withdraw, close. Never onto the baseline, and nothing merges itself.
There is no --force on this surface. Replacing a proposal branch discards commits nobody has
reviewed, and that repair is a person's.
yidam cycle also ships as a CLI command, available in every build and needing none of this.
used-by: [] is now a claim the drift check reads
catalog-used-by-drift compares a catalog entry's declared used-by against the nodes that
cite it. It skipped that comparison whenever the list was empty. An empty list and an absent key arrived at
the check as one value. So used-by: [] was a silent opt-out.
An entry sitting at used-by: [] while nodes cite it now draws a warning it did not draw
before. Nothing in a repository changes to bring this about. It is the state a hand-authored
entry starts in. The entries most likely to be affected are the newest ones.
used-by: with no key at all is unchanged and still exempt. Absence declares nothing. A command that
filled it would decide an entry should make a claim its author never made.
The two states have always been different; only one of them was being read.
The gate does not go red. The check is warn severity, and warnings never reach the
baseline — yidam lint reports one more finding and mise run ci passes. The repair is:
yidam catalog-reconcile
which substitutes the citations for the empty list and commits as reconcile:. It still
leaves an entry with no used-by: key alone.
One thing to know if you read the report rather than the terminal. In catalog-audit --format json, the drift field distinguishes the two states and used_by does not. Both render as
[]. drift is null for an absent key, and an object for a declared-empty one. A
client switching on used_by.length === 0 was never telling them apart and still is not.
degraded_reason has a fourth value, and it is not a property of the deployment
The MCP contract goes to 0.20.0. retrieve and an anchored query may now report
remote_unavailable, alongside no_index, no_vector_support and stale_contract.
A client that validates the field against a closed set of three will reject a valid
response. Nothing in a repository changes to bring this about. The new value appears when a
corpus declares [index.remote] and the service behind it does not answer.
If you wrote that validation, widen it. The set is frozen in
yidam/sdks/parity/mcp/tools.json, which is the file to read it from.
There is a second thing to know, and it is the part a cache gets wrong. The three older values
are properties of a deployment: true when the server starts, true for its lifetime. The new
one describes a call. A server may report it on one request and nothing on the next. A
client that reads degraded_reason once at handshake and remembers it will be wrong about its
second question.
Nothing else moves. A corpus that declares no [index.remote] — which is every corpus today —
answers exactly as it did.
yidam regen now populates two more blocks, so --check can newly fail
vault-status and decisions-log write REGEN blocks. yidam regen did not run either of
them, and yidam regen --check did not report them stale.
Both now run, and mise run ci can go red on a repository nobody changed. The README's
Artifacts block is the one to expect. Most corpora still hold the placeholder the template
ships there — the italic line telling you to run the generator. It was never checked, so it
never had to be true.
The repair is the ordinary one:
mise run regen
git commit -am 'regen: populate the vault-status block'
Read the diff before committing it. The block reports the arrangement your .yidam/config.toml
declares — which stores exist, who may read each, what routes where. If it says something you
did not intend, the block is right and the configuration is the thing to fix.
Two other corrections travel with it. yidam decisions-log no longer describes itself as
read-only; it writes a block when .yidam/decisions/README.md carries one. And yidam policy
no longer carries the * write marker in --help, because it writes nothing.
A property can be retrievable without being prose
prose: true, added in cli/v0.11.0, is right for what a node says. A gage's parameter and
its units are not that. Neither string was in any vector. A query for cubic feet per second
could not reach the node that writes the phrase. Identifiers, codes and units are what a reader
types verbatim, and they were the part excluded.
Flagging them prose: true would reach the embedding. It would also make node-too-long count
the code. And missing-description would accept a node that says nothing but the code. So
there is a second flag:
# <class>.ont.yml
properties:
- name: parameter
type: string
retrievable: true
description: The measured quantity, by its publisher's parameter code.
Who this affects. Any corpus keeping identifiers, codes or units in a property. Nothing
changes for a corpus that flags none. Absent means false, exactly as required: and prose:
are.
What changes when you flag one. No report. yidam embed composes the property, and nothing
else reads the flag. So re-run yidam index-build, and expect no movement in lint. A
property already flagged prose: true needs nothing. Prose reaches the embedding already, and
a property flagged both is composed once.
What it does not reach. A property holding anything but a string. A prose key holding a list is not prose either. It is a real state, and guessing a rendering would put words in the corpus's mouth.
cli/v0.12.0
The README status block no longer counts phases, and refuses a shallow clone
Two changes to yidam status and one to yidam regen. Both follow one rule: a committed,
gated block may only report what every checkout of that commit agrees on.
Phase counts leave the block. yidam status no longer renders N active phase(s) into the
README. The counts read branch refs, and which refs a checkout holds is a property of how it was
fetched. So for one commit there was no value that passed yidam regen --check everywhere. A default CI
checkout and a machine that had run git fetch wanted different numbers. The gate was unwinnable
rather than wrong. The count also moved with no commit at all. Pushing a phase branch reddened
the gate on every open pull request.
What to do. Run yidam regen once and commit the result as a regen: commit. Your block loses
one cell. Your CI may have added an all-branches git fetch to make the two agree. It is no longer needed
for this. Check whether anything else you run wants it before removing it.
Where the counts went. yidam phases prints them, and being current is the point there.
yidam status --format json still carries active_phases, settled_phases,
rewritten_phases and positions. Nothing reading the report loses a field.
yidam regen now refuses a shallow clone. The block reports the corpus genesis, which is the
repository's first commit. A --depth 1 checkout does not have it, and git does not say so: it
names the boundary commit a root. The block was therefore written from a date the clone invented,
and --check asked you to commit it. Measured on one corpus: genesis 2026-08-28 from a full
clone, 2026-09-07 from a shallow clone of the same commit.
What to do. Check out with fetch-depth: 0, or run git fetch --unshallow. The scaffolded
.github/workflows/ci.yml already does the former. If yours does not, this step now fails with a
refusal naming the remedy rather than reporting a stale block.
genesis reads unknown in a shallow clone, in every command, not just this block. That is
the same change from the other side. A corpus whose history is absent has no genesis to name.
yidam bundle writes genesis_hash: null there, which consumers already handle.
A qualified evidence tag is now a claim, so two numbers move
[verified — as proposed] used to match none of the three tokens exactly. It counted as no
claim at all. claim-tag-malformed filed a finding on it, and that finding's own advice was
that there was nothing to do. Such a tag now reads as one claim at its standing. It carries the
qualifier as free text, and the finding is gone.
Two numbers change in your corpus, and neither is a defect.
- Claim counts rise.
yidam status,corpusand theclaimsMCP tool all count the tags they were silently dropping. Runyidam regenso the README blocks that publish those counts agree again. A stale REGEN block is a failing build in a derived repo. claim-tag-malformedfindings fall, by exactly the number of claims gained. Your.yidam/lint-baseline.ymlwill report them as expired. Runyidam lint --blessonce.
Measured over the six corpora that write these details, 38 findings became 38 claims. Three corpora move by nothing; the others:
| corpus | findings | claims |
|---|---|---|
| ohio-education-funding | 535 → 506 | 1362 → 1391 |
| allen-recorder | 13 → 6 | 420 → 427 |
| demi-moore | 10 → 8 | 1678 → 1680 |
What is unchanged. A bracket that folds in a citation — [verified — Pearl 2009] — is
still not a tag, and still reported; move it into references:. A bracket holding two
standings — [verified for the arithmetic; inference for the reading] — is still not a tag
either. Its advice now says so: write two claims. Nothing on disk needs editing for this.
The MCP contract goes to 0.19.0, because it is the contract that states what counts as a claim.
A bundle now says which corpus it is
manifest.yml gains genesis_hash: the full SHA of the corpus's first commit. genesis was
already there and is a date, so it can order two bundles and cannot tell them apart. Two
corpora created on one day share a date; no two share a root commit.
bundle_version stays "1". Adding a field is not a breaking change. Nothing that could
read a bundle before can fail to read one now. Nothing on disk needs editing. Rebuild with
yidam export --format bundle for a bundle that carries the field. Bundles you have already
published stay valid without it.
If you read manifest.yml yourself, absence means the corpus is unidentified. It does not
mean zero, and no placeholder should be substituted. One constant would name every bundle
built before this alike — the confusion the field exists to prevent.
yidam doctor's corpora check uses it for one new finding. A path dependency and an unpacked
bundle can claim one name, and the checkout is what gets read. That is normal when the two are
one corpus in two forms. It is a failure when their genesis hashes differ, because then
tonpa.lock pins a corpus nobody is reading. The check is silent when either hash is unknown.
export, bundle and schema refuse a directory that is not a corpus
They used to succeed. In a directory with no .yidam/, every export format wrote an
artefact and exited 0. An empty bundle, an RDF graph of nothing, a llms.txt with no nodes.
--format bundle, --format web and schema also created .yidam/ on the way, which is
the marker every check tests for. One run in the wrong directory left a tree that graph-check,
lint and doctor would all accept.
If a script of yours runs one of these outside a corpus, it now exits 1 and names the directory. That is the change to look for. Nothing changes inside a repository, and an empty corpus still exports. An hour-old repository with no nodes is a corpus, not a missing one.
schema --settings is unaffected. It prints a compiled-in editor mapping and reads no corpus,
so there is nothing for it to refuse over.
A corpus nested in another repository has no identity, and RDF export says so
genesis_hash — the corpus's first commit — was read by running git at the corpus root. Git
resolves upward, so a corpus that is a directory inside a repository was described by
whichever repository encloses it.
Every corpus under this template's examples/ was in that position. All four minted RDF
subjects under urn:yidam:094509a128f4, which is the template's own first commit. Their four
owl:Ontology resources were one resource asserting four different labels.
export --format rdf now refuses such a corpus rather than naming it with its host's
identity. manifest.yml's genesis_hash is null for it, and genesis reads unknown
instead of the host's date. Every other export format is unaffected: only RDF names subjects.
If this affects you, give the corpus its own repository. Copy it out and git init there,
or yidam clone a fresh one. A corpus that is already its own repository changes by nothing,
and no subject that was correct before moves.
That is why this refuses rather than falling back to the corpus's own earliest commit. Such a fallback would have kept the four exports working, and changed each identity the day its corpus was extracted.
A phase merged with GitHub's rebase or squash button is no longer counted as active
yidam status and yidam phases decided a phase had settled by asking whether its ref is an
ancestor of the baseline. That is true only of the merge PHASES.md prescribes — --no-ff,
keeping the synthesis event.
GitHub's Rebase and merge and Squash and merge both write a single-parent commit onto the
baseline. Neither moves the branch tip. So the ancestry test was false, permanently, and the
phase read active forever. One repository reached 22 phases in flight, every one of
them complete. The number could not fall from inside the repository, because it is computed over
refs.
Your active-phase count may drop, and that is the fix rather than a loss. Those phases now
read rewritten — settled by a merge that rewrote their commits. yidam status names them
separately from settled, because the repair is different. The ref can never become an
ancestor, so deleting it is the only way the count falls.
If you consume the JSON, status --format json gains rewritten_phases, and phases rows
can carry state: "rewritten". It is a new field rather than a fold into settled_phases. A
consumer watching active_phases fall needs somewhere to see where the difference went.
One case is knowingly not covered: a squash-merged branch whose files the baseline later edits
again still reads active. Detecting it needs the branch's combined patch searched through the
baseline's history, which is exact and unbounded in cost. The error is in the safe direction.
cli/v0.11.0
score says why the criteria are the template's, in four states
score read a range's kuten at the range's tip. Then it wrote a sentence about the
repository. A range ending before your adoption said you hold no kuten. So did a range whose
declared profile is not vendored. That state is one kuten check and doctor both warn about.
Who this affects. Anyone scoring a range older than their adoption. That is nearly every range: both early adopters declared in their last two commits.
What changes. The report names one of four states. The unreadable-profile state is now a
warning. --format json gains source, declared and holds_now.
One JSON field narrows. revision used to carry what the range's tip declared, even where
the criteria were the template's. A record could read held: false beside revision: 1. It is
now null whenever held is false, and what the tip declared is under declared.
query's rejection codes: three you may be matching on have never fired
rejected.code is frozen so a client can branch on it without matching prose. The frozen
list and the codes serve --mcp actually emits had never been compared. They disagreed in
both directions for nine contract versions.
Three frozen names are yidam lint check ids, and no query rejection has ever carried
one — unknown-property, unlicensed-edge, edge-target-class. They are gone from the
list. Five the server does emit were frozen nowhere and are now in it: undeclared-property,
unlicensed-hop, unsatisfiable-predicate, unordered-property, anchor-across.
Who this affects. Anything branching on rejected.code — a custom MCP client, or a
script reading yidam query --format json.
Why this is more than a spelling. unknown-property and undeclared-property are the
same thing to a person and different strings to a match. The else arm of such a branch is
usually unknown rejection. So a misspelled property name arrived unclassified at the caller
the code set exists to serve. Silently, and in the direction that hides it.
The repair. Compare your match arms against the list in
yidam/sdks/parity/mcp/tools.json. Arms for the three removed names are dead code;
add the five. diagnostics[].code is enumerated in the same file for the first time. A
client can branch on that too, rather than matching its prose.
yidam propose records a question instead of writing a sentence
A question this tool opened used to be a paragraph spliced into description:. It was found
again by searching the prose for the sentence it had written. It is a record under the node's
yidam: key now. The key is a digest of the check and the finding's words.
Who this affects. Any corpus that has run yidam propose.
What gets better. A question survives an author rewriting the node's prose — it is closed
by id. A carried question stops being counted among the corpus's own open questions. And a
node whose description: is a plain scalar can now be asked about at all. It used to be
refused: a paragraph could not be appended without reformatting a line.
Nothing strands. Paragraphs written by an earlier release are still recognised and still closed when their finding goes away. Lifting them into records is not automatic; the questions stay askable and closable either way.
One number moves. The [open] claim counts drop by however many questions this tool had
carried. Those were never the corpus's own. yidam open-questions still lists the nodes, so
what shrinks is the claim tally and not the worklist.
Prose is what the ontology declares, and description is no longer required by name
node-too-long and missing-description read description and nothing else, while the claim
counter reads the whole file. A corpus keeping prose in a summary or a findings was
measured on a fraction of what it wrote. One reads 21 lines a node against a true 34. And a
node with a summary and no description was reported as having nothing said about it.
A class now declares which of its top-level keys hold prose. The corpus may declare it once for every class:
# <class>.ont.yml
prose: [findings]
# universal.yml
prose: [summary, findings]
The effective set is {description} ∪ universal ∪ class. description never has to be
listed and naming other keys does not unname it.
Who this affects. Any corpus writing prose in a top-level key other than description.
Nothing changes for a corpus that does not: absent both declarations the set is
[description], exactly as before.
What changes when you declare. node-too-long counts more lines, so findings may rise —
this is the number the ceiling was always about. missing-description findings fall.
yidam embed composes the full prose, so re-run yidam index-build. An index built
before this embedded a node's label and its edge names. It did not embed what the node said.
description has also been dropped from the node schema's required list. The check no
longer asks for that key by name. An editor will stop underlining a node that says what it
knows in a field the corpus declared.
A property can hold prose too
The declaration above reaches a top-level key. Most prose that is not in description is not
there. Measured over sixteen corpora and 2,763 nodes: 68.6% hold a nested block scalar. 83% of
that sits under properties:. A method or a verbatim is the node
saying something. Nothing that read prose could see it.
A property now says so itself:
# <class>.ont.yml
properties:
- name: method
type: string
prose: true
description: How the figure was computed.
Who this affects. Any corpus keeping prose in a property. Nothing changes for a corpus that
flags none: absent means false, exactly as required: is.
What changes when you flag one. node-too-long counts those lines. On one public corpus,
flagging 14 declarations moved it from 58 findings to 94. That is the length those nodes
always were.
missing-description stops reporting a node whose substance is a transcription in a property.
And yidam embed composes the property, so re-run yidam index-build. On that corpus the
flag adds 10.4% more prose and rewrites the text of 380 nodes of 694.
What it does not reach. Prose under links:, and prose nested under a coined top-level
key. Together those are 17% of the nested prose measured. The first belongs to the edge
vocabulary. The second needs a class contract that describes the key. Neither is in this
release.
A baseline holding the old counts still passes, so nothing goes red. It also leaves room for regressions that nothing will report.
The inquiry kuten is at revision 2, and two bands are gone
nodes-per-commit and median-node-lines measured how old a repository is, not how it works.
Nothing read them at matched maturity, and every member of the fit exits both bands by ageing.
One left both within six hours of the fit that used it.
Who this affects. Any repository holding inquiry. Nothing is broken and nothing gates.
What changes. kuten check reports three findings where it reported five. The AGENTS.md
block loses its Shape line. The two numbers are still measured and still in the report; no
band judges them.
The repair. Re-vendor, then record a superseding decision:
YIDAM_REF=v0.5.0 mise run yidam-vendor-update
Until you do, doctor warns that your record names revision 1 and the vendored profile is at 2.
That is the revision model working, not a fault.
kuten check rows read in one unit, and a divergent row says which side
A row read declared 0.12–0.27 measured 12% — two halves of one comparison, in two units.
Worse, 12% is inside 0.12–0.27 when you convert it, and the row was reporting divergence.
Who this affects. Anyone reading kuten check, and any consumer parsing its JSON.
What changes. Bands render in the value's unit: declared 12%–27%. Shares carry a decimal:
measured 11.9%. A divergent value names the side it fell on: 11.9% (below 12%).
Why the last one. The verdict compares a float and the display was rounded. So a divergent row could show a number that reads as inside its own band. Precision alone cannot close that; naming the side can.
cli/v0.10.0
A corpus can declare what its practice is aimed at
yidam kuten is new. A kuten declares what this corpus's work is for, as the ontology
declares what it is about.
It ships as vendored prelude and carries a revision. A decision record adopts it. Holding none is a supported state, and it reports as one.
Who this affects. Every repository, on its next re-vendor. Nothing changes until you adopt one.
The repair. Nothing is broken. To adopt, re-vendor and then declare:
YIDAM_REF=v0.4.0 mise run yidam-vendor-update
yidam kuten adopt inquiry
adopt copies the revision out of the vendored profile rather than asking for it. It also
adds the AGENTS.md section and fills it, because the scaffold carrying that section is
consumed at genesis.
Where there is no AGENTS.md at all, it writes none and says so. It prints the section for
you to paste. yidam doctor reports it until a file carries the block.
Then yidam kuten check reads your history against what you declared. It writes nothing and
exits zero however far a corpus has drifted.
yidam score <range> reads a session's work
The genesis rubric scores a repository's birth, once. Nothing said whether a session's work was any good.
score reports one row per declared criterion, each with the evidence it came from. There is
no overall number: a single score over a range names somebody's session.
Criteria come from the kuten's rubric slot, or from the template where no kuten is held. The
report says which, every time.
node-too-long counts the description, and your baseline is now loose
The check counted the whole file — frontmatter, properties and links included — while its own rationale argues about prose. The two came apart once corpora began recording where their edges come from.
One derived corpus reported 212 findings, and 207 came from a single class. Its fixed structure runs 18 lines before a word of prose.
Who this affects. Any corpus whose nodes record provenance on their links. Findings fall, often sharply.
The repair. Re-bless after upgrading:
yidam lint --bless
lint --commits can be scoped to the corpus register
A repository with an artifact beside its corpus has two commit registers, and yidam modelled
one. A feat: on web/ was reported as a corpus-vocabulary violation.
Name the artifact's paths and it no longer is:
[object]
paths = ["web/**", "crates/**"]
Who this affects. Nobody who leaves the key unset. The default is unchanged.
One asymmetry, deliberate. yidam vocabulary --check reads a subject line before the
commit exists. It cannot ask git for paths, so it still warns where lint now stays quiet.
Its callers are a contributor at a terminal, the VS Code commit box, and the MCP tool
check_subject. Tracked as #652.
Corrected 2026-09-07 (#693): this note first named a commit-msg hook, which this project does not ship.
A citation naming a line is held to what the line says
lint now checks #L42 fragments on prose links, reading the quoted passage against the
lines cited.
Who this affects. Repositories whose prose cites files by line number. Most do not.
cli/v0.9.0
serve refuses a directory that is not a corpus
yidam serve --mcp and serve --mcp --http now fail at the command when started somewhere
with no .yidam/ directory, instead of starting and serving an empty corpus.
Who this affects. Anyone whose MCP client launches the server from a directory other than the corpus. That configuration was always wrong and never said so, which is why this is worth reading rather than merely noting: the symptom changes from a server that answers every question with nothing into a server that does not come up.
The old behaviour was worse than "serves nothing". The handshake for a directory that was not
a corpus was identical in shape to one for a repository bootstrapped an hour ago — nodes: 0,
skills: 0, decisions: 0 in both — and the only field that differed, domain, was derived
from the directory's own name. An agent had no way to tell "this corpus is empty" from "this
is not a corpus", and the warning that would have said so went to stderr, which an HTTP client
cannot read.
The repair. Point the client at the corpus. For a client that starts its servers somewhere else, pin it:
{
"mcpServers": {
"yidam": {
"command": "sh",
"args": ["-c", "cd /abs/path/to/my-corpus && exec yidam serve --mcp"]
}
}
}
The Claude Code plugin does this for you and checks before it spawns.
What is not affected. A repository that has been bootstrapped and has nothing written into
it yet is still served. The test is .yidam/, not corpus content — an empty corpus is a
legitimate corpus, and saying otherwise to its author is the one thing this change must not
do.
See #549.