docs: backfill SPEC-168 through SPEC-174 + README OAuth audit#131
Merged
Conversation
Protocol §2 says every ADR with implementation details must have a
corresponding SPEC in /docs/adrs/specs/. v6.0.4–v6.0.6 (ADR-165 →
ADR-167) had SPECs; v6.0.8–v6.0.14 (ADR-168 → ADR-174) didn't. Drift
during the rapid OAuth-debugging cycle. v6.0.7's bundled change
("recursive web_url decoration + stronger wrapper wording") stays
covered by ADR-167's extension wording.
Backfilled:
- SPEC-168-A: Remove `ask` tool from MCP surface.
- SPEC-169-A: Fix Authorization Server URL in PR metadata.
- SPEC-170-A: Require bearer on MCP HTTP endpoint (401 +
WWW-Authenticate trigger).
- SPEC-171-A: Point AS `authorization_endpoint` at frontend.
- SPEC-172-A: Derive frontend URL from CORS_ORIGINS as fallback.
- SPEC-173-A: Parameterise booleans for SQLite/Postgres portability.
- SPEC-174-A: Hybrid JWT validation in Supabase mode.
Each SPEC carries the impl-detail bits the ADR consciously omits:
file paths, function signatures, test plan, acceptance criteria.
README audit (Protocol §12):
- HTTP-transport MCP section corrected — all HTTP requests now
require a bearer (v6.0.10 removed anonymous reads to make the
spec-compliant 401 trigger fire). Anonymous reads remain
available on the stdio transport.
- IRIS_JWT_SECRET added to required production env vars list, with
the openssl-rand generation hint (per the secret-handling memory
note: generate locally, paste directly into the deploy env, don't
echo into chats or commits).
- IRIS_WEB_URL on iris-api added to required env vars (ADR-171 with
v6.0.12 fallback).
- IRIS_MCP_PUBLIC_URL on iris-mcp added (ADR-169).
- Tool count corrected (~28 → ~27) — `ask` removed in v6.0.8.
- Tool list pruned: "ask-AI" dropped from the inline list;
apply_diagram_creation moved into the local-AI-creation group.
- "Removed in v6.0.8" line added alongside the existing v6.0.0
removals.
- Server-wide orient-first protocol paragraph rewritten to reflect
the two-channel delivery (Server.instructions + per-scope wrapper)
introduced through v6.0.4–v6.0.7, and the TTL refresh + recursive
web_url decoration on package_hierarchy.
No code changes, no version bump, no release.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
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.
Summary
Protocol audit cleanup for the v6.0.4–v6.0.14 OAuth-fix cycle. No code changes, no version bump, no release — pure docs.
Compliance gaps closed
SPECs (Protocol §2: every ADR with impl details needs a SPEC) — 168 → 174 were missing. Backfilled all 7. v6.0.7's bundled change ("recursive
web_urldecoration + stronger orient-wrapper wording") stays covered by ADR-167's extension wording, per your call.asktoolauthorization_endpointat frontendREADME (Protocol §12: must reflect implementation) — corrected the MCP/OAuth section to match v6.0.14 reality:
IRIS_JWT_SECRETadded to required production env vars, with the openssl-rand hint (and the secret-handling caveat: generate locally, never echo into chat).IRIS_WEB_URLandIRIS_MCP_PUBLIC_URLadded to the env-var list with the relevant ADR refs.askremoved from the inline tool list.apply_diagram_creationdescription updated to reflect the local-AI-as-author model.web_urlonpackage_hierarchy.What stays in the ADRs vs. moves into SPECs
The ADRs keep the "why" and "decision" — they're now lean decision-records as protocol §1 intends. The SPECs carry the "how" — file paths, function signatures, code blocks, test plans, acceptance criteria. A reader scanning the ADR knows the trade-off; a reader implementing or reviewing the change goes to the SPEC.
Test plan
No code change, but:
🤖 Generated with Claude Code