Skip to main content
Glama

Certify Production-Ready Architecture

architect.certify

Pro/Teams — second-pass adversarial certification of an architect.validate run that scored production_ready (A or B first-pass tier). ON CLIENT TIMEOUT — DO NOT RETRY THIS TOOL. RECOVERY FIRST: the run_id is emitted in the FIRST notifications/progress event at t=0s (BEFORE the LLM call begins). Capture it. On timeout, call me.validation_history(run_id='<that-id>') to fetch the persisted cert verdict; the server-side run completes independently within a 20-minute budget. This is the canonical recovery path. Use it before considering any retry. Long-running LLM call (60-180s typical; exceeds Claude Code's ~60s idle budget); MCP clients commonly close the call before the server returns. Retrying re-runs the LLM call AND burns one of your 3 cert retry-budget attempts. Mints the certified production_ready badge when both reviewers sign off; caps the run to C/emerging when the second pass surfaces a missed production_blocker. MANDATORY DOCTRINE RULE (load-bearing): the badge certifies the EXACT code that produced the validate run_id, NOT 'this codebase' in general. If you modify, fix, or iterate the code between architect.validate and architect.certify — even a single character — cert rejects with code_fingerprint_mismatch. Fixing the code voids the run. The recovery path is always: edit code → architect.validate → fresh run_id → architect.certify on the fresh run. Do NOT cert from a stale run_id after iteration; ask the user to re-validate first. WHEN TO CALL: only after architect.validate returned tier=production_ready AND the user wants the certified badge AND the code has not been touched since the validate run. NOT for tier=draft/emerging/not_applicable runs (typed rejections fire — see below). NOT idempotent across attempts: each call is one of the 3 attempts in the retry budget. BEHAVIOR: atomic one-shot single LLM call, ~60-180s server-side at high reasoning effort (small payloads finish faster; observed p99 ~250s; server-side budget is 20 min, ~5× observed max). Exceeds typical MCP-client tool-call idle budget (~60s in Claude Code), so the FIRST notifications/progress event fires at t=0 carrying the run_id. The run is atomic by contract — no in_progress lifecycle, no cancellation, no resume. Updates the persisted run's result_json (public review URL + me.validation_history(run_id=...) reflect the cert outcome). ELIGIBILITY GATE (typed rejection enum on failure): caller must own the run, tier=production_ready, less than 24h old, not already certified, within cert retry budget (max 3 attempts), no other cert call in flight for the same run_id, code fingerprint must match the validated code, AND the submitted payload must be cert-payload-complete (see Payload Completeness below — cert rejects pre-LLM with payload_incomplete when an imported module's surface isn't visible in the validate payload that produced this run_id). Rejection reasons (typed Literal): auth_required, paid_plan_required, run_not_found, not_run_owner, not_eligible_tier, not_agentic_component (tier=not_applicable runs), already_certified, certification_age_exceeded, retry_budget_exhausted, code_fingerprint_mismatch, code_fingerprint_missing, code_not_on_file (caller omitted code argument AND the 24h cert-retry hold for this run has expired or was never written. Recovery: re-run architect.certify from the same MCP session that ran architect.validate, passing the code explicitly — the server never persists code by design), payload_incomplete (submitted/validated payload imports modules whose contents aren't visible — cert refuses pre-LLM to prevent a false-precision downgrade. Recovery: re-validate with verbatim public-surface stubs for every imported module, then re-cert on the fresh run_id. Empirically validated: PR #157 iter8/iter9 cert rejections were exactly this class — code on disk was correct, the submitted payload merely omitted module visibility), cert_consensus_score_below_threshold (consensus_median<75 — consensus runs only), cert_consensus_unstable_blocker (any principle mode_stability<80% — consensus runs only), run_state_corrupt, cert_persistence_failed, cert_in_flight (a prior architect.certify call on this run_id is still running. Poll me.validation_history for the verdict; do not retry until it resolves). PAYLOAD COMPLETENESS (load-bearing for cert eligibility): the cert reviewer reads the EXACT payload that produced the validate run_id. Imported modules whose surface isn't present in the payload cause pre-LLM payload_incomplete refusal. Avoidance — when validating with intent to cert, bundle public-surface stubs for every imported module: from sqlalchemy.exc import SQLAlchemyError → include a stub class; from app.db import models → include a class models: namespace stub with the columns/methods you reference; module-level imports of dataclass, Literal, json, datetime, timezone MUST also be in the payload (cert correctly catches when they're omitted — code would NameError on import). 'Submit Like Production': the payload should be the code as it would actually run, not a compressed sketch. The stubs cover IMPORTED dependencies only; the certified code's own enforcement branches (approval gates, policy checks, recovery paths) must be present in full. A # ... placeholder reads as an ABSENT control and is graded against you, not as shorthand for one that exists. PRE-LLM REJECTION AUDIT TRAIL: when cert rejects before the LLM call (payload_incomplete, code_fingerprint_mismatch, etc.), certification_attempts=[] on the response — no attempt landed in the retry budget, no LLM hop occurred. The rejection envelope's rejection_reason + guidance are the actionable surface. (Audit-trail UI surfacing of pre-LLM rejections is tracked in the platform self-audit set as anomaly #5; out of scope for the cert tool itself.) INPUTS: re-send the SAME code that produced the run_id (the architect persists findings + recommendations, never code, by design — privacy-preserving). Server compares the submitted code's SHA-256 fingerprint to the stored fingerprint and rejects mismatches. Auth: Bearer , Pro or Teams plan required. UK/EU data residency (Cloud Run europe-west2). Code processed transiently by OpenAI (no-training-on-API-data) and dropped; payloads JSON-escaped + delimited as inert untrusted data — prompt-injection inside code is ignored. If the cert call fails outright (provider error, persistence error), a fresh architect.certify is the recovery path; the eligibility gate enforces the 3-attempt retry budget. For long-running cert workflows the answer is to re-validate, not to make this tool stateful. OUTCOMES: certification_status ∈ {confirmed_production_ready (badge mints), downgraded_to_emerging (cert review surfaced a missed production_blocker, tier capped at C/emerging), unavailable_provider_error (LLM call failed, retry within budget)}. Cert findings + summary + attempt history surfaced on the persisted run for full inspectability.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
codeNoThe same code that was sent to architect.validate to produce this run_id. Sent verbatim — the cert reviewer needs the actual code to surface production_blockers the first pass missed. May be omitted (empty string) when the prior validate stored the code under the 24h cert-retry hold; in that case the server reuses the stored code automatically. Sent under the same enterprise-safety envelope as architect.validate (transient processing, no training, JSON-escaped + delimited).
run_idYesThe run_id from a prior architect.validate call. Returned in the validate response when persistence_status='saved'. Must be owned by the caller (per-user authorisation, same gate as me.validation_history).

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault

No arguments

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate non-idempotent, non-read-only behavior, and the description massively expands on this: atomic one-shot execution, 60-180s runtime, client-timeout risk, retry-budget consumption, fingerprint-mismatch rejection, and side effects like badge minting or downgrade. No annotation contradiction exists; idempotentHint=false matches 'NOT idempotent across attempts.'

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with bolded section headers and front-loads the most critical timeout/recovery warning. However, it is extremely long and contains some redundancy (repeated recovery-path guidance) and tangental audit-trail context that could be trimmed without losing essential usage information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's high complexity, non-idempotent behavior, retry budget, and failure modes, the description is remarkably complete: it enumerates typed rejection reasons, eligibility gates, payload-completeness rules, outcome enum values, recovery paths, and data-residency/transient-processing notes. The output schema exists, and the description still explains the returned certification_status variants, so an agent has full context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% (run_id, code), but the description adds critical parameter semantics: code must be the exact code that produced the run_id, may be omitted under the 24h cert-retry hold, and must be payload-complete with stubs for imported modules. It also clarifies run_id provenance and ownership requirements, going well beyond the schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence states a specific verb and resource: 'second-pass adversarial certification of an architect.validate run that scored production_ready.' It further distinguishes itself by naming the sibling flow and the badge outcome, so an agent can immediately tell this is not validate or validate_consensus.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description includes an explicit 'WHEN TO CALL' section with precise preconditions ('only after architect.validate returned tier=production_ready AND...') and explicit non-conditions ('NOT for tier=draft/emerging/not_applicable runs'). It also provides a canonical recovery path for timeouts and alternatives via me.validation_history, making usage boundaries clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4.4/5.0
Disambiguation5/5

Each tool has a clearly distinct purpose within its domain: the validators are differentiated by lens (architect/design/spec), content tools are split by entity (principles/clusters/guides/examples/assets) with list/get/search variants, and even the me.* and handoffs.* tools have non-overlapping functions. The only near-overlap (architect.validate vs architect.validate_consensus) is explicitly disambiguated by the consensus variant's description.

Naming Consistency4/5

Tool names consistently use a domain prefix (architect., principles., me., etc.) and snake_case throughout. While most are action-oriented (validate, list, get, search, add, await, report, summarize), some me.* and handoffs.* names are noun phrases (me.learning_path, handoffs.agency) that don't signal the action as clearly, creating minor deviation from a pure verb_noun or action pattern.

Tool Count3/5

At 29 tools, the set is heavy but justified by the server's broad multi-domain scope (doctrine, validation, learning, support, and team analytics). Each tool has a distinct role, but the number exceeds the typical well-scoped range, and some content types (e.g., examples) could have been consolidated without losing function.

Completeness4/5

The server covers its apparent domains thoroughly: doctrine content has list/get/search for most entity types, validation covers architecture/design/spec with consensus and certification, and user learning/support have appropriate tools. Minor gaps exist—e.g., examples have no list-all endpoint, and session management is web-only—but none are blocking for core workflows.

Resources