feat(spec,lint): ADR-0109 revised + Phase 1 — skills-only default path, tool-name registry, advisory skill.tools lint (#3820 R7) - #3885
Merged
Conversation
…h, tool-name registry, advisory skill.tools lint (#3820 R7) ADR-0109 revision: the first draft framed third-party tools as authored binding records; review surfaced the stronger conclusion — the runtime already materialises a tool per declarative action (action_<name>), so the DEFAULT third-party path needs no tool records at all. Skills are the only required authoring artifact; tool records are demoted to an optional AI-presentation refinement layer (Phase 2, gated on acceptance and a real refinement need). AI capability ≡ application capability: same executable, same authz, same audit. Phase 1, implemented here: - spec: PLATFORM_PROVIDED_TOOL_NAMES / PLATFORM_TOOL_FAMILY_PREFIXES / isPlatformProvidedToolName in system/constants/platform-tool-names.ts — the PLATFORM_PROVIDED_OBJECT_NAMES precedent applied to tools. Owning packages live in the cloud repo, so (like CLOUD_PROVIDED_OBJECT_NAMES) the conformance half of the contract lives there; this repo pins the list's internal invariants. - lint: validate-ai-tool-references — the #3820 R7 skill.tools branch, wildcard-aware, resolving against stack.tools ∪ registry ∪ materialised action_<name> family. Warning severity (ADR-0078 advisory-first): runtime plugins outside the registry are statically invisible. Appended to REFERENCE_INTEGRITY_RULES → validate/lint/compile pick it up. Exactly 10 findings / 0 false positives on the HotCRM corpus; a dedicated near-miss suggestion catches the raw-action-name-instead-of-action_<name> mistake edit distance cannot. - spec: 'tools' joins composeStacks' CONCAT_ARRAY_FIELDS (declared records survive composition) and the stack.tools / AI-slot docs teach the ADR-0109 model. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BHjroNkLkajskKbJaidko4
|
The latest updates on your projects. Learn more about Vercel for GitHub. 1 Skipped Deployment
|
github-actions
Bot
added
size/l
documentation
Contributor
📓 Docs Drift CheckThis PR changes 2 package(s): 104 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:
|
os-zhuang
marked this pull request as ready for review
July 28, 2026 14:41
This was referenced Jul 28, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Follow-up to #3871, per maintainer direction on the #3820 thread. Two things happen here: ADR-0109 is revised to the stronger conclusion that surfaced in review, and its Phase 1 ships — which unblocks and delivers the R7
skill.toolsbranch this issue was blocked on.The revision
The first draft framed third-party tools as authored binding records (
tool→ action/flow). Review surfaced that the runtime already materialises a tool per declarative action (action_<name>— the familyactions_executorsubscribes to withaction_*), so the binding the draft proposed already exists implicitly for every action. Revised decision:"Third-party AI extension = write a skill" becomes the entire story: one concept to document and teach, and one less namespace an AI author can hallucinate into.
Phase 1 implementation
PLATFORM_PROVIDED_TOOL_NAMES(@objectstack/spec/system, newplatform-tool-names.ts) — curated registry of the 30 statically-named tools the cloud AI runtime registers (service-ai: 6,service-ai-studio: 24), plusPLATFORM_TOOL_FAMILY_PREFIXES(action_) andisPlatformProvidedToolName(). Exact mirror of thePLATFORM_PROVIDED_OBJECT_NAMESprecedent; the owning packages live in thecloudrepo, so — likeCLOUD_PROVIDED_OBJECT_NAMES— the conformance half of the contract lives there (sibling cloud PR adds those tests). This repo pins the list's internal invariants (snake_case, no cross-package collisions, no static name inside a family namespace, sorted groups).validate-ai-tool-references(@objectstack/lint) — the R7skill.toolsbranch: wildcard-aware resolution againststack.tools∪ registry ∪ materialisedaction_<name>family (stack-level and object-level actions). Severity warning per the ADR-0078 advisory-first ratchet — a runtime plugin outside the registry is statically invisible, and the runtime deliberately tolerates unresolved names. Appended toREFERENCE_INTEGRITY_RULES, sovalidate/lint/compileall pick it up with no CLI changes.triage_case→action_triage_case) — the mistake edit distance can't reach (the prefix alone is 7 edits).composeStacksno longer dropstools— the slot joinsCONCAT_ARRAY_FIELDS, so a declared record at least survives composition.stack.toolsand the AI-slot prose now teach the ADR-0109 model.Verification
@objectstack/spec: 263 files / 6841 tests pass;tsc --noEmitclean; api-surface regenerated (new public exports);check:docs/check:skill-refs/check:react-blocksall in sync.@objectstack/lint: 36 files / 530 tests pass (7 new rule tests + suite wiring updates).@objectstack/cli: 72 files / 739 tests pass (all three commands pick up the rule through the suite).pnpm buildgreen.Out of scope
binding, flow exposure, boot-mirror provenance guard, metadata-type flag revisit, warning→error ratchet) — gated on ADR acceptance.cloud(feature-detects the new spec export; activates fully when.objectstack-shaadvances past this change).Refs #3820 · #3871 · ADR-0109 · ADR-0078 · ADR-0063 · ADR-0064
🤖 Generated with Claude Code
https://claude.ai/code/session_01BHjroNkLkajskKbJaidko4
Generated by Claude Code