luigidemasi opened a new issue, #86: URL: https://github.com/apache/camel-kit/issues/86
> Imported from [luigidemasi/camel-kit#207](https://github.com/luigidemasi/camel-kit/issues/207), opened by [luigidemasi](https://github.com/luigidemasi) on 2026-09-04. > Closed by [luigidemasi/camel-kit#211](https://github.com/luigidemasi/camel-kit/pull/211), merged on 2026-09-05. --- ## Description Narrow replacement for luigidemasi/camel-kit#74, which asked for documentation-URL citations in the implementation output. The underlying need stands: the design spec marks every component and EIP as `(MCP-verified)` but records neither the catalog version binding nor which tool verified each artifact. `skills/camel-brainstorm/guides/design-assembly.md` lists "MCP verification evidence" as spec content in its overview, yet the spec structure has no section for it. The user approves a spec that says "verified" without seeing what it was verified against. The structured evidence already exists, but only in the execute phase. `agents/catalog-researcher.md` emits a `Catalog binding:` line (runtime, platform BOM, returned `camelVersion`, `binding=MATCHED`) and, per artifact, `Result:` and `Verification provenance:` lines. That output stays inside the `LOADED CONTEXT` block consumed by `camel-execute` Step 1.5 and is never written to a user-visible artifact. At design time the catalog calls are made by the brainstorm orchestrator (`skills/camel-brainstorm/SKILL.md`, MCP tools section; `skills/camel-design/guides/component-selection.md`, binding probe) or by the `integration-architect` persona, whose output format has no result or provenance fields. Documentation URLs are out of scope. Re-checked against `main` (`499588f4`) on 2026-09-04: - No catalog tool returns a URL. In camel-jbang-mcp 4.21.0 (the pinned `camel.mcp.version`), `camel_catalog_component_doc` returns name, title, description, label, deprecated, supportLevel, syntax, async, consumerOnly, producerOnly, componentOptions, endpointOptions and headers. The EIP, dataformat and language detail results likewise have no URL field. The tool named in the luigidemasi/camel-kit#74 example, `camel_catalog_component_info`, does not exist; the shipped tool is `camel_catalog_component_doc`. - camel.apache.org hosts only `next` plus two LTS lines. Probed 2026-09-04: `components/4.x/timer-component.html` (the luigidemasi/camel-kit#74 example) 404; `components/4.21.x/...` 404 (4.21.0 is the default pin); `components/4.14.x/...` 404; `next`, `4.18.x` and `4.22.x` 200; `latest` redirects to 4.22.x. - Page names do not follow catalog names: dataformat `jackson` is `jackson2-dataformat.html` on `next` and `jackson-dataformat.html` on 4.18.x; `https`, `imap` and `smtp` have no component page. - A URL composed by the agent from a name and a version is therefore an unverified string. Iron Law 1 step 4 restricts output to validated catalog fields. ## Proposal 1. In `skills/camel-brainstorm/guides/design-assembly.md`, under `## 5. Constitution Compliance`, add: ``` ### Catalog Verification Evidence Catalog binding: camel_catalog_components(limit=0); runtime=[runtime]; platformBom=[groupId:artifactId:version]; returned camelVersion=[camelVersion]; binding=MATCHED | Artifact identity | Result | Verification provenance | |---|---|---| | component:[name] | VERIFIED | camel_catalog_component_doc; requested component:[name]; catalog binding=MATCHED | | eip:[name] | VERIFIED | camel_catalog_eip_doc; requested eip:[name]; catalog binding=MATCHED | | dataformat:[name] | VERIFIED | camel_catalog_dataformat_doc; requested dataformat:[name]; catalog binding=MATCHED | | language:[name] | VERIFIED | camel_catalog_language_doc; requested language:[name]; catalog binding=MATCHED | ``` One row per artifact named in section 3, deduplicated. Labels and tokens are the ones already defined in `agents/catalog-researcher.md` and `skills/shared/mcp-setup.md`. Rows are `VERIFIED` only: an artifact whose detail call failed or whose binding could not be established does not enter section 3 and is recorded as an open design question, as `skills/camel-design/guides/component-selection.md` already requires. No documentation URL is recorded. 2. Name the design-time producers of those rows. `agents/integration-architect.md` output format gains "per artifact: result and verification provenance, using the catalog-researcher labels"; the orchestrator's own calls (`skills/camel-brainstorm/SKILL.md` MCP tools section, `skills/camel-design/guides/component-selection.md`) record the same fields. Without this the block has no source on any target. 3. Self-review item 2 in `design-assembly.md` becomes: every section 3 artifact has a `VERIFIED` row under a `binding=MATCHED` line; if not, verify now. The inline `(MCP-verified)` tags stay as they are. 4. Align the brainstorm error-handling line "MCP tool failure: warn the user, continue with a note that verification is pending" (`skills/camel-brainstorm/SKILL.md`) with `component-selection.md`: a failed verification becomes an open design question, not a note next to a component that stays in the spec. 5. One evidence location for migrations. `skills/camel-migrate/guides/mulesoft-phase2.md`, `biztalk-phase2.md` and `camel-version-phase2.md` keep their "Section 9: Constitution Gate Checks" checkbox for MCP catalog verification but state that it is satisfied by the block above; `skills/camel-design/guides/tdd-assembly.md` item 15 does the same. No restatement of the table. 6. `skills/camel-execute/guides/re-plan-loop.md` Step 3: when a component is replaced, update its row; a probe reported as `UNKNOWN` in Step 2 does not produce a `VERIFIED` row. 7. `ResourceConsistencyTest`: pin `### Catalog Verification Evidence`, `Catalog binding: camel_catalog_components(limit=0)` and `Verification provenance` in `design-assembly.md`; pin the pointer sentence in the three phase-2 guides and `tdd-assembly.md`; assert `design-assembly.md` does not contain `camel.apache.org/components`. 8. `docs/architecture.md` (catalog-researcher is currently described for execute only) and `CHANGELOG.md` `[Unreleased]`. Not in scope: documentation URLs; a new status token or a new shared guide; changes to `camel-implement` (internal, returns a status token under `camel-execute`); an execution-report section (possible follow-up, would need `camel-execute/SKILL.md` Step 4 and `templates/bob/gates/camel-execute.md` in lockstep); Bob gate, Bob2 rule or Ship worker changes (`design-assembly.md` is already read by the Bob gates and the Gemini trait; Ship workers run without skills, so a Ship-produced design spec will not carry the block and the controller must not require it). ## Acceptance criteria - [ ] `design-assembly.md` section 5 contains the `Catalog Verification Evidence` block with the binding line and the artifact table, using only existing tokens - [ ] `agents/integration-architect.md` and the orchestrator MCP sections name per-artifact result and provenance as required output - [ ] Self-review item 2 requires a `VERIFIED` row per section 3 artifact; the brainstorm MCP-failure line matches `component-selection.md` - [ ] The three migrate phase-2 guides and `tdd-assembly.md` point to the block; `re-plan-loop.md` Step 3 updates the affected row - [ ] `grep -rn 'camel.apache.org/components' camel-kit-core/src/main/resources` returns nothing - [ ] `ResourceConsistencyTest` pins the new strings; `./mvnw -B clean install` passes - [ ] `docs/architecture.md` and `CHANGELOG.md` updated - [ ] Website: `content/pipeline/brainstorm.md` (How It Works step 5 and the step-5 Constitution Compliance blurb), `content/getting-started/greenfield.md` (design spec table, row 5), `content/pipeline/_index.md` (spec section list) and `content/pipeline/plan.md` (section 5 reference) describe the new section 5 content ## Website impact — Required `content/pipeline/brainstorm.md`, `content/getting-started/greenfield.md`, `content/pipeline/_index.md`, `content/pipeline/plan.md`. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
