feat(lint,spec): AI surface-affinity rule, ADR-0063 doc completion, ADR-0109 draft (#3820) - #3871
Merged
Merged
Conversation
…DR-0109 draft (#3820) Positioning work ahead of R7 (issue #3820): the agent authoring surface is closed per ADR-0063, so the buildable AI rule is the one that checks a statically provable, runtime-fatal contradiction — skill ↔ agent surface affinity (ADR-0064 §3) — not agent.skills resolution. - lint: new `validate-ai-surface-affinity` rule + tests, appended to REFERENCE_INTEGRITY_RULES so `validate`/`lint`/`compile` all pick it up. Error severity: the runtime throws on this binding at chat time. Unresolved skill names are deliberately out of scope (kernel skills are runtime-registered; #3820 D0/D2). False-positive floor read per branch (#3806): clean on the HotCRM-shaped corpus, `examples/` proves nothing here. - spec: stack.zod.ts AI-slot prose no longer describes the withdrawn ADR-0040 model — agents marked platform-internal (ADR-0063 §2), tools marked declaration-only pending #3820 D0, skills named as THE extension primitive. app.defaultAgent re-documented as a surface-binding knob (its example was the withdrawn tenant-agent pattern). SkillSchema documents that per-skill `permissions` deliberately does not exist (ADR-0049) — the field HotCRM authored and Zod silently stripped. - docs: ADR-0109 (Proposed) — the #3820 D0 decision: third-party tools are bindings to actions/flows; platform tool names become a conformance-tested registry; unblocks the R7 skill.tools branch. 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
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:
|
Check Changeset and the generated-docs gate in TypeScript Type Check both flagged the previous commit: add the missing changeset (@objectstack/lint minor, @objectstack/spec patch) and the regenerated content/docs/references/ui/app.mdx row for the re-documented `app.defaultAgent`. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BHjroNkLkajskKbJaidko4
…rfaceAffinity to the suite Both branches appended a rule to REFERENCE_INTEGRITY_RULES; resolution keeps main's validateFlowTemplatePaths (#3810) first and this branch's validateAiSurfaceAffinity last, with the suite test's fixture and report-order assertions carrying both. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BHjroNkLkajskKbJaidko4
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.
Positioning work ahead of R7, per the disposition in #3820 (assessment comment): the agent authoring surface is closed per ADR-0063, and the tool namespace has no fact registry yet (D0), so the buildable AI rule today is the one that checks a statically provable, runtime-fatal contradiction — skill ↔ agent surface affinity (ADR-0064 §3).
What's in here
1.
validate-ai-surface-affinity(new lint rule)An agent binds a surface (
ask/build, ADR-0063 §1); a skill declares affinity (ask/build/both, §3). The runtime throws on an incompatible binding (resolveActiveSkills, cloudagent-runtime.ts) — chat-time 500 after parse, validate, and deploy all passed. Both sides of the check are declared in the same stack, so the rule has zero false positives by construction; both sides default'ask'whensurfaceis absent, mirroring the runtime, so it is safe on the raw-configlintpath too.REFERENCE_INTEGRITY_RULES—validate,lint, andcompilepick it up with no CLI changes.agent.skills[]names: kernel skills (schema_reader, the ask/build bundles) are runtime-registered and statically invisible — resolving againststack.skillsalone is lint: no reference-integrity for AI metadata (agent skills, skill tools) — R7, blocked on D1/D2 #3820 D0/D2 territory. Unresolved names are skipped.examples/declares zero agents/skills, so the floor test is the HotCRM-shaped corpus (2 agents × 6 skills, nosurfacefields) — clean.2. Spec docs: finish what ADR-0063 already decided
The AI-slot prose in
stack.zod.tsstill described the withdrawn ADR-0040 model ("Persona-bearing copilots (1-3 per app)… the active app'sdefaultAgentis selected automatically"), andapp.defaultAgent's example was literally the withdrawn tenant-agent pattern (defaultAgent: 'sales_copilot'). Rewritten to the ADR-0063 reality:stack.agents— marked platform-internal (§2): kernel ships exactly two agents; third parties author skills.stack.tools— marked declaration-only pending lint: no reference-integrity for AI metadata (agent skills, skill tools) — R7, blocked on D1/D2 #3820 D0: no handler binding, no runtime reader; the executable tool set is runtime-registered.app.defaultAgent— re-documented as a surface-binding knob ('ask'implicit default /'build'for authoring surfaces), not a custom-agent slot;app.form.tshelpText matched.SkillSchema— documents that per-skillpermissionsdeliberately does not exist (ADR-0049): HotCRM authored one and Zod silently stripped it; the doc now tells authors (human and AI) where access is actually gated.3. ADR-0109 (Proposed) — the #3820 D0 decision
Third-party tools are bindings to executable primitives the platform already has (actions/flows), never free-floating executables; kernel tool names become facts via a conformance-tested
PLATFORM_PROVIDED_TOOL_NAMESregistry (the #3657 precedent). This is what unblocks the R7skill.toolsbranch with a resolvable universe instead of a 37.5% false-positive rate on its own motivating corpus.Out of scope (per issue thread)
skill.toolsresolution — blocked on ADR-0109 acceptance.loadAgent/resolveDefaultAgentplatform filtering) — sibling PR incloud.Verification
@objectstack/lint: 35 files / 507 tests pass (8 new).@objectstack/spec: 259 files / 6745 tests pass.@objectstack/cli: 72 files / 734 tests pass (suite wiring picks the rule up on all three commands).pnpm build: 71/71.Refs #3820 · ADR-0063 · ADR-0064 · ADR-0078 · ADR-0049
🤖 Generated with Claude Code
https://claude.ai/code/session_01BHjroNkLkajskKbJaidko4
Generated by Claude Code