Stitcher

Accepted

The Stitcher is the bounded LLM layer in Almathal. It fills Seams, generates UI code, and handles migration steps that cannot be expressed declaratively. Everything the Stitcher does is constrained by the deterministic harness the Composer provides.

Why the Stitcher Exists

The Composer is fully deterministic — it resolves Specs, validates compatibility, invokes Scaffolders, and validates Seam contracts without ever calling an LLM. But the Composer cannot write integration code. It doesn’t know how to wire a specific entity definition into a specific React component using a specific version of TanStack Query, while also satisfying shadcn/ui’s component patterns.

That is the Stitcher’s job: the bounded code-writing work the Composer hands off. The key word is bounded. The Stitcher does not write whatever it wants. It receives explicit contracts defining what to produce, where to put it, which Adapters to use, and what behaviors to implement. Everything outside those contracts is off-limits.

This is the core design principle: the Stitcher is a code-writing specialist operating within a harness, not a free-form code generator.

What the Stitcher Receives

Before the Stitcher is invoked, the Composer has already completed:

• Spec Resolution
• Compatibility Validation
• Build Approval (user has signed off)
• Seam Validation (all Seam contracts confirmed satisfiable)
• Scaffolding (scaffolded code skeleton exists)

The Stitcher receives a structured handoff containing:

For each Seam, in dependency order:
  - The Seam contract (seam_id, type, input, output_files, must_use_adapters,
    must_implement, verification)
  - The Seam's resolved input values (from the approved Spec)
  - The Adapter Manifests for each Adapter in must_use_adapters
    (identity, interface_contracts, integration hints, common pitfalls)
  - The scaffolded files that the Seam's outputs will be placed alongside
  - Any structured handoff artifacts from prior Seams in this generation

User-supplied data (entity names, field values, configuration choices) arrives inside a clearly demarcated data block, explicitly labelled as structured configuration data — never interpolated directly into the Stitcher’s instruction context.

What the Stitcher Produces

For each Seam, the Stitcher produces:

1. The declared output files — at the exact paths declared in the Seam contract’s output_files. No other files.
2. A decision rationale — a brief structured summary of what it produced and why: which Adapters it used, which behaviors it implemented, how it interpreted any ambiguous points in the Seam contract.
3. A structured handoff artifact (when the Seam’s output will be consumed by a later Seam) — for example, an OpenAPI spec fragment that the frontend Seam receives as input.

Seam Processing Order

Seams are processed in dependency order — Seams whose outputs are consumed by other Seams run first. Each Seam is processed in isolation: the Stitcher sees only the inputs for that Seam, not the full context of other Seams’ outputs. The handoff artifact mechanism provides inter-Seam communication through structured, typed data rather than raw context accumulation.

This isolation is intentional. Accumulated context grows the attack surface and can produce subtle inconsistencies. Structured handoffs are explicit about what flows between Seams.

Platform Invariants

These are enforced at the platform level, not via prompt instruction. The Stitcher cannot override them, regardless of what appears in its input context.

1. Text-only output. The Stitcher generates code as text files. It has no shell access, no tool-use capability, no ability to execute commands, and no outbound network access during generation. It cannot read the filesystem beyond its provided context.

2. Output path constraints. The Stitcher may only produce files at paths declared in the Seam contract’s output_files. Any output at an undeclared path is rejected before it is written. The generation hard-fails and logs a security event.

3. Bounded retry. The Stitcher may retry a failed Seam at most N times (default 3, platform-configurable). After N failures, the generation hard-fails. The Stitcher cannot extend its own retry budget.

4. No persistent memory. Each Seam invocation starts clean. The Stitcher has no access to prior generation outputs, prior customer sessions, or any state beyond what the Composer provides in the structured handoff.

5. Seam isolation. One Seam invocation cannot influence another except through declared structured handoff artifacts. The Stitcher does not accumulate a growing context window as it processes Seams.

6. Build Verification gates all output. The Stitcher’s output for each Seam is subject to mechanical verification (compile, lint, smoke tests) before delivery. The Stitcher cannot bypass this gate. Failed verification triggers a retry with the failure as additional context.

Why invariants are enforced mechanically

Telling an agent “follow our output constraints” via a prompt instruction is probabilistic — the agent may not comply. Enforcing constraints mechanically (the platform rejects undeclared paths before writing; the platform blocks retries after N attempts) is deterministic. The Stitcher’s trustworthiness comes from the harness, not from the model’s good behaviour.

The Resolver as Input Guardrail

Before the Composer hands off to the Stitcher, the Resolver processes all user-supplied data as a security gate. The Resolver:

Pattern detection (primary defense): Scans all free-text variation point values for injection-characteristic patterns — directive language, instruction-like phrasing, combinations of override signals. Detected patterns → immediate rejection with an error message and a logged security event. The value never reaches the Spec.

Type constraint enforcement: Every variation point has a declared type. Enum values must be in the declared options list. Strings must match declared patterns (identifier formats, URL patterns, length limits). Lists must conform to declared schemas. Values failing validation are rejected at input time.

Structured data envelope: User-supplied values enter the Stitcher’s context inside a clearly labelled data block. The Stitcher’s governing instructions (the Seam contract) are always the dominant context; user data is always subordinate configuration data, explicitly identified as such.

The Resolver is a synchronous gate in the same generation pipeline — no separate service, no network hop. User input passes through the Resolver before being stored in the Spec. The Spec the Stitcher receives contains only Resolver-validated values.

AI Reviewer (Post-Generation)

After the Stitcher completes all Seams and Build Verification passes, the AI Reviewer inspects the generated application as an advisory pass. The AI Reviewer uses a different model from the Stitcher to prevent rubber-stamping.

The AI Reviewer looks for:

• Security anti-patterns (unauthenticated endpoints, broken access control, hardcoded credentials)
• Anti-patterns (business logic in controllers, N+1 queries)
• Consistency issues (API and frontend using different naming conventions)
• Code quality concerns that tests don’t catch

The AI Reviewer’s findings are advisory — they surface as warnings in the Build Approval report but do not block delivery. The customer decides whether to address them before deploying.

Pipeline Position

Resolver (input guardrail)
    ↓  [validated, enveloped user data]
Compiler → Spec Resolution → Compatibility Validation → Build Approval
    ↓  [approved Spec]
Seam Validation
    ↓  [validated Seam contracts]
Scaffolding
    ↓  [scaffolded skeleton + structured handoff]
Stitcher
  ↓ Seam 1 (isolated invocation)
  ↓ Seam 2 (isolated invocation, receives Seam 1 handoff artifact)
  ↓ Seam N ...
    ↓  [generated files]
Build Verification (compile, lint, tests — deterministic gate)
    ↓  [verified output]
AI Reviewer (advisory, different model)
    ↓  [warnings surfaced to customer]
Delivery

What the Stitcher Is Not

• Not a free-form code generator. It fills declared Seam contracts, not open-ended prompts.
• Not an agent with tool use. It cannot execute commands, make network calls, or access the filesystem beyond its provided context.
• Not the Composer. The Composer is deterministic. The Stitcher is the bounded LLM complement to the Composer.
• Not the AI Reviewer. The Stitcher produces code. The AI Reviewer inspects code. Different models, different roles.
• Not responsible for security scanning. It produces code. Build Verification and the AI Reviewer check what it produced. External security scanning (CVE on components, code-level vulnerability scanning) is a deployment-layer concern.

Governance

The Stitcher’s invocations are fully logged per ADR-0028. Every invocation record includes: model ID and version, Seam ID, input hashes, output file paths, token counts, verification result, retry count, and the decision rationale the Stitcher provided. These records form part of the generated application’s audit trail delivered to the customer.

See ADR-0028: Almathal AI Governance Posture for the full governance requirements. See ADR-0030: Stitcher Security Invariants for the decision record establishing the invariants above. See ADR-0009: Fully-Specified Seam Contracts for how Seam contracts are structured.