Skip to content

chore(spec-loop): sync specs to main and advance .last-sync - #1162

Merged
potiuk merged 1 commit into
apache:mainfrom
potiuk:spec-sync
Sep 8, 2026
Merged

chore(spec-loop): sync specs to main and advance .last-sync#1162
potiuk merged 1 commit into
apache:mainfrom
potiuk:spec-sync

Conversation

@potiuk

@potiuk potiuk commented Sep 8, 2026

Copy link
Copy Markdown
Member

Summary

tools/spec-loop/.last-sync sat at a1cff444, 17 commits behind main.
Advancing the marker on its own would assert that the specs describe those
commits, so the drift is closed first and the marker moved to de7d7054 last.

Each of the 17 was checked against the specs individually.

Specs updated — shipped behaviour no spec described

Commit Spec What it now records
#1161 meta-and-quality-tooling skill-evals reports ERROR, rather than PASS, when a case's CLI produced nothing gradeable
#1158 security-reporting the dashboard projects the current partial bucket to its end-of-bucket value; RATE series (accumulate from zero) and LEVEL series (carry over) project differently, and mean-based signals are deliberately not projected
#1154 project-agnosticism <PROJECT> and <project> are two placeholders holding different values; the lint carries both spellings and matches spaced variants
#1135 adapters the forwarder relay's contact_handle defaults to an org-level shared inbox rather than a named individual; the multi-hop coordinator case is designed in RFC-AI-0008 and unimplemented
#1145 issue-management-family the family's eval suites, plus the note that --cli runs belong outside a credential-denying sandbox

Commits needing no spec change

One gap recorded rather than papered over

No spec covers marketplace distribution, including the
0.2.0.dev<YYYYMMDDHHMM> stamping rule from #1160. That rule is load-bearing:
the marketplace is served from main, so adopters do install dev versions, and
claude plugin update compares version strings rather than commit SHAs — a
frozen suffix leaves an adopter told they are "already at the latest version"
indefinitely, recoverable only by a full uninstall and reinstall. Logged as a
Known gap in adoption-and-setup.md, wanting its own spec rather than a bullet.

Test plan

  • prek run --all-files passes (exit 0)
  • spec-validate tools/spec-loop/specs/ — no violations
  • check-placeholders clean
  • Every claim written into a spec was verified against the implementation,
    not inferred from the commit subject

Notes for reviewers

The #1158 bullet is worth a second look. My first draft claimed the dashboard
keeps the raw count alongside the projection and marks the bucket incomplete in
the rendered series. Neither is true — I had inferred it from what a reasonable
implementation would do. Reading core.py and render.py gave the actual
design: the RATE/LEVEL split, a projection floored at the observed count so it
can never un-count what already happened, and means excluded because a mean over
items seen so far is already an estimate rather than a partial accumulation.
The bullet now matches the code.

.last-sync is deliberately the last thing in the diff to move.

🤖 Generated with Claude Code

https://claude.ai/code/session_01So3JRGXrbqSGrohtZuHWKg

The marker sat at a1cff44, 17 commits behind main. Bumping it alone
would claim those commits are described by the specs, so the drift is
closed first.

Specs updated for what actually shipped:

- meta-and-quality-tooling: skill-evals errors, rather than passing, when
  a case's CLI produced no gradeable output (apache#1161).
- security-reporting: the tracker dashboard projects the current partial
  bucket to its end-of-bucket value, splitting RATE series (accumulate
  from zero) from LEVEL series (carry over), and deliberately not
  projecting mean-based signals (apache#1158).
- project-agnosticism: <PROJECT> and <project> are two placeholders
  holding different values, and the lint carries both spellings plus
  spaced variants (apache#1154).
- adapters: the forwarder relay's contact_handle defaults to an
  org-level shared inbox rather than a named individual (apache#1135). The
  multi-hop coordinator case is designed in RFC-AI-0008 and unimplemented.
- issue-management-family: the family's eval suites, and the note that
  --cli runs belong outside a credential-denying sandbox (apache#1145).

Commits needing no spec change: apache#1152, apache#1143 and apache#1156 updated their own
specs in-commit; apache#1149, apache#1147, apache#1151 are behaviour-preserving bug fixes;
apache#1155 and apache#1141 are CI and dependency chores; apache#1159's spec edits landed
with it; apache#1144 removes hardcoded literals that no spec asserted.

One genuine gap recorded rather than papered over: no spec covers
marketplace distribution or the dev-version stamping rule from apache#1160,
which is load-bearing because `claude plugin update` compares version
strings, not commit SHAs. Logged in adoption-and-setup as wanting its own
spec.

Generated-by: Claude Code (Opus 5)
@potiuk
potiuk merged commit 1e1e389 into apache:main Sep 8, 2026
9 checks passed
potiuk added a commit that referenced this pull request Sep 8, 2026
…1163)

Closes the gap #1162 recorded rather than papered over: the plugin
marketplace surface had no spec at all.

`marketplace-distribution.md` covers the two manifest families (the
vendor-neutral Agent Plugins 1.0 root manifest with its closed ten-field
schema, and the five client-specific ones), the ten Claude-Code-only
per-family plugins, and the generator/CI gate that keeps them in step
with `family:` frontmatter.

The load-bearing part is the versioning rule. The marketplace is served
from `main`, so adopters install dev versions as the normal case, and
`claude plugin update` compares version strings rather than commit SHAs
— a frozen `.devN` suffix leaves an adopter told they are "already at the
latest version" indefinitely, recoverable only by a full uninstall and
reinstall. Recorded with the reason, along with the fact that nothing
checks the stamp is fresh, which is the one failure mode that is silent
in exactly the wrong direction.

Status is `experimental`, not `stable`: only the Claude Code manifests
have been exercised against a live install. The rest conform to their
vendors' published documentation and nothing more, which the Known gaps
now say.

While registering it: ten specs were absent from both index files
(`overview.md` and `README.md`) — among them `security-model-preparation`
from #1156 and every per-family spec. All ten are now listed in both, so
the indexes are complete.

Also corrects `docs/setup/marketplaces.md`, which said 41 of 70 skill
descriptions carry placeholder syntax; recounted from live frontmatter it
is 45 of 74.

Generated-by: Claude Code (Opus 5)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant