From e4ce45c9c4bb41e7451a6e5f590e353c258563ea Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D7=A0=CF=85=CE=B1=CE=B7=20=D7=A0=CF=85=CE=B1=CE=B7=D1=95?= =?UTF-8?q?=CF=83=CE=B7?= Date: Sun, 16 Aug 2026 12:34:03 -0700 Subject: [PATCH] chore: close and archive specify-agent-tool-invocation The last task was to confirm every repository declares the tools its recipes invoke. Six of seven did. redocly was declared nowhere, and tracing it found why: the shared docusaurus module installed it globally and unpinned, so the binary sat on the developer's path and its version was whatever the registry served that day. Redocly versions quote YAML scalars differently, so the combined specification a repository commits depended on when its author last ran just deps. Nothing in continuous integration runs generate, so it never surfaced. Fixed as two changes: the module stops installing a global, and osapi pins the version where it invokes it, through bunx. Pinned to the version that produced the committed specification, so nothing regenerates. The same pass removed the last npx invocation in any module. Its delta was already in the corpus. Compared before moving. Co-Authored-By: Claude Opus 5 --- .../.openspec.yaml | 0 .../design.md | 0 .../proposal.md | 0 .../specs/repo-standards/spec.md | 0 .../tasks.md | 47 +++++++++++++++++++ .../specify-agent-tool-invocation/tasks.md | 31 ------------ 6 files changed, 47 insertions(+), 31 deletions(-) rename openspec/changes/{specify-agent-tool-invocation => archive/2026-08-16-specify-agent-tool-invocation}/.openspec.yaml (100%) rename openspec/changes/{specify-agent-tool-invocation => archive/2026-08-16-specify-agent-tool-invocation}/design.md (100%) rename openspec/changes/{specify-agent-tool-invocation => archive/2026-08-16-specify-agent-tool-invocation}/proposal.md (100%) rename openspec/changes/{specify-agent-tool-invocation => archive/2026-08-16-specify-agent-tool-invocation}/specs/repo-standards/spec.md (100%) create mode 100644 openspec/changes/archive/2026-08-16-specify-agent-tool-invocation/tasks.md delete mode 100644 openspec/changes/specify-agent-tool-invocation/tasks.md diff --git a/openspec/changes/specify-agent-tool-invocation/.openspec.yaml b/openspec/changes/archive/2026-08-16-specify-agent-tool-invocation/.openspec.yaml similarity index 100% rename from openspec/changes/specify-agent-tool-invocation/.openspec.yaml rename to openspec/changes/archive/2026-08-16-specify-agent-tool-invocation/.openspec.yaml diff --git a/openspec/changes/specify-agent-tool-invocation/design.md b/openspec/changes/archive/2026-08-16-specify-agent-tool-invocation/design.md similarity index 100% rename from openspec/changes/specify-agent-tool-invocation/design.md rename to openspec/changes/archive/2026-08-16-specify-agent-tool-invocation/design.md diff --git a/openspec/changes/specify-agent-tool-invocation/proposal.md b/openspec/changes/archive/2026-08-16-specify-agent-tool-invocation/proposal.md similarity index 100% rename from openspec/changes/specify-agent-tool-invocation/proposal.md rename to openspec/changes/archive/2026-08-16-specify-agent-tool-invocation/proposal.md diff --git a/openspec/changes/specify-agent-tool-invocation/specs/repo-standards/spec.md b/openspec/changes/archive/2026-08-16-specify-agent-tool-invocation/specs/repo-standards/spec.md similarity index 100% rename from openspec/changes/specify-agent-tool-invocation/specs/repo-standards/spec.md rename to openspec/changes/archive/2026-08-16-specify-agent-tool-invocation/specs/repo-standards/spec.md diff --git a/openspec/changes/archive/2026-08-16-specify-agent-tool-invocation/tasks.md b/openspec/changes/archive/2026-08-16-specify-agent-tool-invocation/tasks.md new file mode 100644 index 0000000..7c58f7d --- /dev/null +++ b/openspec/changes/archive/2026-08-16-specify-agent-tool-invocation/tasks.md @@ -0,0 +1,47 @@ +## 1. Record the requirement + +- [x] 1.1 Write the requirement +- [x] 1.2 Record the decisions and their rejected alternatives in design.md + +## 2. Apply to each repository + +- [x] 2.1 `osapi` — `AGENTS.md` written as part of its layout conversion + (osapi-io/osapi#450) +- [x] 2.2 `gohai` +- [x] 2.3 `nats-client` +- [x] 2.4 `nats-server` +- [x] 2.5 `osapi-orchestrator` +- [x] 2.6 `specs` +- [x] 2.7 `osapi-justfiles` + +## 3. Verification + +- [x] 3.1 Confirm every `AGENTS.md` states how tools are invoked. All seven + carry the `mise exec -- just test` form and the explanation of why a bare + `just` resolves differently for an agent + +- [x] 3.2 Confirm every repository declares the tools its recipes invoke. Six of + seven did. `osapi` was missing `uv`, which `just md-fmt` invokes through + `uvx`, and it is now declared (osapi-io/osapi#450). + + `redocly` was declared nowhere at all. Tracing it found the source: the shared + `docusaurus` module installed it globally and unpinned, so the binary lived on + the developer's path rather than in the project and its version was whatever + the registry served that day. Since redocly versions quote YAML scalars + differently, the combined specification a repository commits depended on when + its author last ran `just deps` — and nothing in continuous integration runs + `generate`, so it never surfaced. On one machine the installed version was + 2.19.1 while the registry served 2.46.1. + + Resolved as two changes: the shared module stops installing a global + (osapi-io/osapi-justfiles#61), and `osapi` pins the version where it invokes + it (osapi-io/osapi#456), through `bunx` because `bun` is the declared runner + and `bunx` already runs the other JavaScript tooling. Pinned to the version + that produced the committed specification, so it is byte-identical and nothing + regenerates. The same pass removed the last `npx` invocation in any module. + + The distinction this settled: a **runner** is declared in `.mise.toml` — `go`, + `just`, `bun`, `uv` — and a **payload** it fetches is pinned where it is + invoked. `mdformat` forces that split rather than illustrating it: its GFM + plugin has to be injected into the same environment, which `.mise.toml` cannot + express, and without it every table in the repository is silently reflowed diff --git a/openspec/changes/specify-agent-tool-invocation/tasks.md b/openspec/changes/specify-agent-tool-invocation/tasks.md deleted file mode 100644 index 775f150..0000000 --- a/openspec/changes/specify-agent-tool-invocation/tasks.md +++ /dev/null @@ -1,31 +0,0 @@ -## 1. Record the requirement - -- [x] 1.1 Write the requirement -- [x] 1.2 Record the decisions and their rejected alternatives in design.md - -## 2. Apply to each repository - -- [x] 2.1 `osapi` — `AGENTS.md` written as part of its layout conversion - (osapi-io/osapi#450) -- [x] 2.2 `gohai` -- [x] 2.3 `nats-client` -- [x] 2.4 `nats-server` -- [x] 2.5 `osapi-orchestrator` -- [x] 2.6 `specs` -- [x] 2.7 `osapi-justfiles` - -## 3. Verification - -- [x] 3.1 Confirm every `AGENTS.md` states how tools are invoked. All seven - carry the `mise exec -- just test` form and the explanation of why a bare - `just` resolves differently for an agent -- [ ] 3.2 Confirm every repository declares the tools its recipes invoke. Six of - seven do. `osapi` was missing `uv`, which `just md-fmt` invokes through `uvx`; - it is now declared (osapi-io/osapi#450). One gap remains: `osapi`'s `generate` - recipe invokes `redocly`, which no repository file declares — it resolves from - whatever the developer installed globally. Declaring it is not a one-line fix: - the version mise supplies (2.46.1) quotes YAML scalars differently from the - version currently on the developer's path (2.19.1), so the committed combined - spec and both generated SDKs change the first time anyone runs `just generate` - against it. That regeneration is its own change, and nothing in continuous - integration runs `generate`, so the drift is invisible until someone does