docs(skills): a sibling's wiring comes from the design, not from a comment - #633
docs(skills): a sibling's wiring comes from the design, not from a comment#633xlight05 wants to merge 1 commit into
Conversation
…mment `183e67a8` moved a `component` dependency's endpoint wiring off the live endpoint catalog and into `design.json`, precisely because the catalog only lists components that have already DEPLOYED — so on a first delivery it answers nothing. The agent-facing docs were never moved with it. `workload-and-wiring.md` still told the agent a `component` dependency's wiring is "not derivable from `specs/`", and the skill body still routed it to the "Platform-resolved dependencies" comment. On a project whose only endpoint dependency is a sibling, no such comment is posted, so the agent read the table, found no comment, and invented the value — writing the FRIENDLY component name where OpenChoreo resolves by the SCOPED one. That is not hypothetical: `employees-submit-expense131` shipped `component: expense-api` with `employees-submit-expense131-expense-api` sitting in its own `design.json` under `wiring.endpoint`. The release rendered, the pod ran, the app served, and the sole symptom was a ReleaseBinding parked at `Ready=False / ConnectionsPending` with the project reporting "deploying" for ever. The conformance check caught it and minted issue wso2#6 — which cost a whole coding cycle to transcribe one string the platform had already computed. Move the docs to where the data actually is: - the kind table routes `component` to its `wiring` object, like the other two derived kinds, and a shape table maps the two `wiring` variants onto the two halves of `dependencies:`; - the copy-verbatim rule covers both variants, and names the project prefix as the platform's own name rather than something to "correct"; - the skill body's `endpoints:` half resolves a sibling from `design.json` and keeps the comment for `org-service` alone — which is all it carries that a design cannot; - ADR-0013 is restated at its current state: `component` is on the derived side, and the conformance net checks endpoint targets as well as refs. The local overlay's anchor moves in lockstep (`skill_overlay` fails loudly on a stale anchor, and the 398 remote-worker tests render both variants). Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JvanuzxvZmpfvnh2Pbr2wD
|
Warning Review limit reachedNext included review available in 35 minutes. View limit detailsLimit details: You’ve used the included review currently available. This review ran on the open-source allowance, not this organization's plan, because the pull request author doesn't have an assigned seat. Waiting won't change this — ask an organization admin to assign them a seat, or add seats in Billing if every seat is already assigned, then retry. Review configuration: ⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (4)
Comment |
|
Folded into #632 (commit Leaving this open rather than closing it myself, since the review threads here are still readable context. Close it as superseded whenever suits; nothing is lost. |
|
Superseded by #632, which now carries this commit as Closing rather than merging. Nothing is lost: #632's description carries the full root-cause writeup from here, and the change is already live on the local plane (org skill library md5-matches the built commit; pending skill updates |
1 participant
The problem
employees-submit-expense131shipped this inexpense-webapp/workload.yaml:OpenChoreo resolves an endpoint dependency by the scoped name, so this matched no
binding. The release rendered, the pod ran, the app served — and the only symptom was a
ReleaseBinding parked at
Ready=False / ConnectionsPending, with the project reporting"deploying" for ever. The wiring-conformance check caught it and minted
issue #6, which
cost a whole coding cycle (#6 → #7 → PR #8) to change one string.
The correct value was already in the agent's own tree, byte-exact, committed by the
platform before the agent ever ran:
Root cause: doc drift against a fix that already landed
183e67a8(2026-08-01) moved acomponentdependency's endpoint wiring off the liveendpoint catalog and into
design.json— precisely because the catalog only listscomponents that have already deployed, so on a first delivery it answers nothing.
Its own commit message names this exact failure.
The agent-facing docs were never moved with it:
workload-and-wiring.mdkind tablecomponent→ "not derivable fromspecs/— the skill body"design.jsonsince 2026-08-01SKILL.md→ Theendpoints:halforg-serviceonlyADR-0013workload.yamlnobody has written yet"183e67a8superseded itSo the agent read the table, went looking for a comment, found none — no
"Platform-resolved dependencies" comment exists on any issue in that repo, I checked
all of them — and fell back to the only name it had ever seen.
The instruction that was supposed to save it (
# the platform's name — never "correct" it, in the template) never fired, because the agent had already been told the valuewas not in
specs/.The change
Move the docs to where the data is.
references/workload-and-wiring.mdThe kind table routes
componentto itswiringobject, like the other two derivedkinds.
A new shape table maps the two
wiringvariants onto the two halves ofdependencies:— anendpointobject →endpoints[],ref+envBindings→resources[]— so which half is read off the data rather than off the kind.Copy-verbatim now covers both variants, and the project prefix is stated as the
platform's own name for the component, with the silent failure spelled out:
SKILL.md— theendpoints:half resolves a sibling fromdesign.json, and keepsthe comment for
org-servicealone. It closes the hole the agent actually fell into:ADR-0013— restated at its current state:componentsits on the derived side,and the conformance net checks endpoint targets as well as refs.
overlays/local.md— the anchor moves in lockstep.Gates
runners/remote-worker— 398/398 pass, on this branch's base. These renderSKILL.mdthroughlocal.md, andskill_overlaythrows on a stale anchor(
replace-text matched 0 times), so the overlay edit is proven, not assumed.make license-check— exit 0.Not in this PR
The structural fix.
dependencies:inworkload.yamlis 100% platform-derived —ScopedComponentName, the sibling's own endpoint name,visibility: project,ServiceURLEnvName. Asking a model to transcribe a value the platform calculated is avariance source that no wording removes, and the friendly name is the natural thing to
write, so the wording is fighting the grain.
checkWiringConformancealready holds, at the same moment and in the same process, theshipped file, the declared truth, and the exact missing values — and it writes an
issue. It could write the file: reconcile
dependencies:fromdesign.json, commit,then build off that commit. No PR, no cycle, no model. The precedent exists —
DerivePlatformResourceFactsAtHeadalready commits tomainoutside a PR at the samepre-tag step.
That is a separate change. This one stops the bleeding for the next project.
🤖 Generated with Claude Code
https://claude.ai/code/session_01JvanuzxvZmpfvnh2Pbr2wD