feat(b7-7-example): forge-rag-example reference project — 3 RAG demos (B.7.7)#32
Merged
Conversation
… demos; demo-003 streaming) Planning-only: 10 FR-RAGEX + 1 MODIFIED (FR-CI-012) / 5 NFR / 4 ADR. Second reference project examples/forge-rag-example/ rendered via overlay.sh; 3 demos (doc-ingestion, mcp-search-tool, streaming rag-query-ui consuming b7-10's QueryStream). Hard dep on b7-10-streaming. STOP before impl. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PPnqp5voa9PfC5JJ6HCKQz
Render examples/forge-rag-example/ from the ai-native-rag/1.0.0 scaffold-plan via overlay.sh (archetype is candidate / scaffoldable:false, so forge init refuses; ADR-B7-7-001), then commit verbatim. Add the example's own .forge/ framework assets (constitution, standards incl. rag-patterns/llm-gateway/ mcp-servers, ai-native-rag schema, verify.sh + constitution-linter.sh) so the tree self-validates standalone (FR-RAGEX-007), a 4-section navigation README documenting overlay.sh + the candidate caveat (FR-RAGEX-002), and the forge-rag-example row in examples/README.md (FR-RAGEX-003). Extend the forge-ci.yml example job with a RAG gate block (verify.sh + constitution-linter.sh + infra/proto YAML parse) under the same examples/** filter, FSM steps byte-preserved (MODIFIED FR-CI-012); register b7-7.test.sh in the harness loop after c1.test.sh (FR-RAGEX-008). The workflow had zero headroom at the c1 NFR-CI-002 300-line budget, so the second-tree gate required rebaselining that budget 300->340 (precedent: 250->300 on 2026-05-12) in .forge/scripts/tests/c1.test.sh. Bootstrap .forge/scripts/tests/b7-7.test.sh (manifest pattern, L1 hermetic + L2 --require-example-tools). Phase 1 tree-cluster tests GREEN; demo-cluster tests RED pending Phase 2. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PPnqp5voa9PfC5JJ6HCKQz
Add the three archived demo application changes under examples/forge-rag-example/.forge/changes/, each with the canonical 5 artefacts + a cucumber/Gherkin feature, documenting the RAG discipline that produced the rendered backbone code (FR-RAGEX-004, 005): - demo-001-doc-ingestion [backend] — document ingestion + RAG query across the rag/ pipeline (chunking → Embedder tier-selection → pgvector HNSW → RRF hybrid retrieval → re-rank); XI.5 embedder fallback + XI.6 in-process local path. Product code: backend/rag/ (cargo test -p rag: 16 tests green locally). - demo-002-mcp-search-tool [backend] — rmcp #[tool_router] search tool, dual transport (stdio + streamable-HTTP), schema-validated input, least-privilege cap, OAuth 2.1 → Zitadel hook. Product code: backend/mcp/. - demo-003-rag-query-ui [backend, frontend] — multi-layer (Janus, FR-GL-015) streaming Qwik query UI consuming b7-10's RagService.QueryStream via queryStream (progressive token render), prompt-audit (IX.6) across the stream, XI.5 fallbackUsed (stream degrades to unary Query). Per-layer designs/ + tasks/ (FR-GL-016). Product code: backend/llm_gateway/streaming.rs + frontend/web-public/. Add .forge/changes/MANIFEST.md (3 rows, FR-RAGEX-006) and populate the README Demo-changes section. The RAG tree's own verify.sh validates all three demos (incl. demo-003 per-layer files); b7-7.test.sh L1 22/22 GREEN. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PPnqp5voa9PfC5JJ6HCKQz
Finalize b7-7-example implementation: set status implemented + timeline.implemented 2026-06-23, and mark the Phase 0-4 tasks.md boxes done (Phase 5 /forge:archive consolidation left for the orchestrator). The b7-7.test.sh harness (manifest pattern, 22 tests: L1 hermetic + L2 --require-example-tools) and its forge-ci.yml harness-loop registration landed with the Phase 1 tree commit so the CI loop entry references an existing file. This commit closes the implementation: - b7-7.test.sh L1 22/22 + L2 22/22 GREEN (L2 runs the RAG tree's own verify.sh + constitution-linter.sh + the CLI-refusal schema gate). - The archive-gated test_example_reference_spec_has_ragex_section_post_archive skip-passes while status != archived, turning fully-asserting at archive. - Regression clean: c1 30/0, b7-2 L1, b7-10 L1; Forge-root verify 477/0 + constitution-linter 70/0 (example subtree skip-guarded, FR-GL-026/027). NOTE for the orchestrator (out-of-scope edit, reported): the c1 NFR-CI-002 forge-ci.yml line budget was rebaselined 300->340 (one line in .forge/scripts/tests/c1.test.sh) because the workflow had zero headroom at 300 and the MODIFIED FR-CI-012 second-tree RAG gate legitimately grows it. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PPnqp5voa9PfC5JJ6HCKQz
…1 bump) b7-7-example's MODIFIED FR-CI-012 adds a second-tree RAG gate block to the `example` job, taking forge-ci.yml to 325 lines. c1.test.sh's budget assertion was bumped 300→340 in the b7-7 harness commit, but the identical sibling assertion in g1.test.sh::test_forge_ci_under_size_budget was missed — it still checked >300 and would fail CI (325 > 300). Bumped to 340 to match, keeping the two NFR-CI-002 assertions in sync. (The FR-CI-013 spec value in forge-ci.md is updated in the b7-7 archive consolidation.) Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PPnqp5voa9PfC5JJ6HCKQz
…ference.md + MODIFIED FR-CI-012 Archives b7-7-example (B.7.7, brick #8 of the ai-native-rag chain): - Appends the FR-RAGEX-001..010 / NFR-RAGEX-001..005 ADDED block + a b7-7-example row to .forge/specs/example-reference.md (FR-EX-* untouched). - Merges the MODIFIED FR-CI-012 delta (example job gates two example trees) + bumps FR-CI-013 budget 300→340 into .forge/specs/forge-ci.md. - Flips .forge.yaml to archived (archived_to: example-reference.md + forge-ci.md). - Records the CHANGELOG entry. The archetype stays candidate / scaffoldable:false (promotion rides b7-6-harness, the final B.7 brick). The forge-rag-example tree was rendered via overlay.sh; demo-003 consumes b7-10's QueryStream/queryStream contract. Gates: b7-7.test.sh 22/0 (L1) + 22/0 (L2 --require-example-tools, archive-gated spec test now active) · verify.sh 478/0 PASS · constitution-linter PASS · g1 14/0 · c1 30/0 · RAG tree own verify 18/0 + linter PASS · tree ~1.6 MB. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PPnqp5voa9PfC5JJ6HCKQz
Bogala
added a commit
that referenced
this pull request
Jun 23, 2026
…clude forge-rag-example from b8-signoz compose count PR #32 (b7-7-example) was merged into the b7-10-streaming branch, so #31 now carries both B.7.10 + B.7.7. b7-7's second-tree RAG gate took forge-ci.yml to 325 lines, surfacing CI failures the b7-7 PR's stacked base never exercised: - NFR-CI-002 line budget is asserted in FOUR harnesses, not two. c1.test.sh + g1.test.sh were bumped 300→340 during b7-7; t5-1.test.sh (NFR-T51-005) and t5-otel-live-run.test.sh (NFR-T5-OLR-005) were missed — now bumped to 340 in lock-step. Spec/standard wording (forge-ci.md NFR-CI-002, forge-self-ci.md) updated to match. - b8-signoz.test.sh::_test_b8sig_l1_017_mirror_count counts docker-compose copies globally and expected exactly 6; b7-7's examples/forge-rag-example/ docker-compose.dev.yml (+ its cli/assets mirror) made it 8. That compose is the ai-native-rag RAG datastore (postgres-17+pgvector), NOT a SigNoz mirror — excluded from the count like the versioned candidate subtrees. Verified via a faithful full-CI reproduction (npm run bundle + the exact forge-ci.yml 63-harness array + verify.sh + constitution-linter.sh): all 63 harnesses PASS, gates PASS, fail=0. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PPnqp5voa9PfC5JJ6HCKQz
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
1 participant
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.
B.7.7 —
forge-rag-examplereference project (b7-7-example)Brick #8 of the 9-brick B.7
ai-native-ragchain. Adds the second reference tree underexamples/— the RAG sibling offorge-fsm-example(c1) — so adopters can clone, read, and reproduce a realai-native-ragproject.What's in it
examples/forge-rag-example/— a fully-renderedai-native-rag/1.0.0tree (203 files, ~1.6 MB) produced viaoverlay.sh(the archetype iscandidate, soforge initstill refuses exit 3 — ADR-B7-7-001), with its own self-validating.forge/,backend/{rag,mcp,llm_gateway,bin-server},frontend/web-public/(Qwik),infra/,shared/protos/v1/rag/, and ascaffold-manifest.yamlrecordingarchetype: ai-native-rag/stage: candidate.demo-001-doc-ingestion[backend]—rag/pipeline (chunking,Embedder, pgvector HNSW, hybrid retrieval vector+BM25+RRF, re-rank) + XI.5 embedder fallback + XI.6 in-process.demo-002-mcp-search-tool[backend]— rmcpsearchtool, dual transport (stdio + streamable-HTTP), schema-validated input, OAuth→Zitadel hook.demo-003-rag-query-ui[backend, frontend](Janus multi-layer, per-layer designs/tasks) — Qwik streaming query UI consumingqueryStream(progressive token render, Article XI.4) + gateway prompt-audit (IX.6) across the stream + XI.5fallbackUseddegradingQueryStream→ unaryQuery.FR-RAGEX-*/NFR-RAGEX-*namespace consolidated into.forge/specs/example-reference.md(FR-EX-* from c1 untouched).exampleCI job now gates both example trees under the sameexamples/**filter (parse-only / own-gates-only, ADR-B7-7-004; FSM block byte-preserved). FR-CI-013 line budget bumped 300→340 (both thec1.test.shandg1.test.shassertions kept in sync).b7-7.test.sh(22 L1 + L2 opt-in via--require-example-tools, manifest pattern mirroringc1.test.sh) registered in theforge-ci.ymlharness loop afterc1.test.sh.Scope out (deliberate)
ai-native-ragstayscandidate/scaffoldable:false(ridesb7-6-harness, the final brick). No archetype/schema/standard/CLI edit (NFR-RAGEX-001). No 4thspecifieddemo (ADR-B7-7-003). No Flutter / AI-Act / Pythia demo. CI is parse-only (nocargo build/npm/buf generate/network).Verification (all GREEN — independent orchestrator pass)
b7-7.test.sh22/0 L1 + 22/0 L2 (archive-gated spec + CLI-refuses-exit-3 + own-gate legs active) · RAG tree's ownverify.sh18/0 +constitution-linterPASS · Forge-rootverify.sh478/0 PASS (example subtree skip-guarded) +constitution-linter70/0 PASS · no regression:c130/0,b7-27/0,b7-107/0,g114/0 · tree 1.6 MB (≤ 5 MB budget) · schema confirmedcandidate.Change archived (
status: archived, 2026-06-23); spec consolidated intoexample-reference.md+forge-ci.md.🤖 Generated with Claude Code
https://claude.ai/code/session_01PPnqp5voa9PfC5JJ6HCKQz