ADR-026: Cognitive Supply Chain Architecture

Status: Proposed Version: 1.0 Date: 2025-12-22 Supersedes: N/A Related ADRs: ADR-012, ADR-025 Related PRDs: N/A

Context

Traditional prompt engineering treats prompts as ephemeral, disposable text. This leads to:

The SEA™ Forge delivery pipeline requires a systematic approach where:

Decision

SEA™ Forge SHALL implement a Cognitive Supply Chain Architecture where:

  1. Prompt files are executable SOPs organized in a Work Breakdown Structure (WBS)
  2. The file structure is the Semantic Router - directory paths define cognitive context
  3. Prompts are trainable parameters subject to self-grooming and evolution
  4. Specs are Boundary Conditions that prevent regression to generic patterns
  5. Backward chains detect drift between code and specifications

Rationale

Core Principles

1. Prompt-as-Function (The Atomic Unit)

Each prompt file is a Serverless Function with:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

---
type: task
domain: backend/auth
dependencies: ["@/docs/schema.md", "@/utils/logger.ts"]
output_format: "code_block_only"
---

# Context

You are a Senior Backend Engineer.

# Objective

Implement the login handler defined in the user stories.

# Constraints

- Must pass the tests in `login.test.ts`
- No external libraries other than those in `package.json`

2. File System as DAG (The Semantic Router)

The Work Breakdown Structure maps to a Directed Acyclic Graph of prompts:

1
2
3
4
5
6
7
8
9

/prompts
  /01_requirements
    01_user_stories.prompt.md  ← Generates: /docs/stories.md
    02_acceptance_criteria.prompt.md
  /02_architecture
    01_system_design.prompt.md ← Reads: /docs/stories.md
    02_api_contracts.prompt.md
  /03_implementation
    01_scaffold_auth.prompt.md ← Reads: /docs/api_contracts.md

The directory path IS the context vector. Child nodes inherit parent context.

3. Test-Driven Prompting

Every task prompt MUST be paired with a validation mechanism:

This enforces the invariant: No code exists without verification.

4. Stateless Execution (The Semantic Firewall)

Each prompt task:

  1. Opens with a fresh context window
  2. Reads only explicit dependencies (not chat history)
  3. Saves structured output to disk
  4. Severs the associative chain between tasks

This prevents Context Pollution and Hallucination Loops.

The Processing Phases (MECE WBS)

Phase Objective TDD State Output
1. Case Initialization Define the gap RED → GREEN → REFACTOR PRD + Acceptance Criteria
2. Structural Design Define constraints RED → GREEN → REFACTOR ADR + SDS
3. Construction Synthesize logic RED → GREEN → REFACTOR Verified Source Code
4. Integration Assemble system RED → GREEN → REFACTOR Deployable Artifact
5. Delivery Validate in reality RED → GREEN → REFACTOR Live Feature + Telemetry
6. Feedback Close the loop RED → GREEN → REFACTOR New Case Files (Flywheel)

Constraints

Quality Attributes

Bounded Contexts Impacted

Consequences

Positive

Negative

Additional Notes