# Cross-Project Technical Pattern Registry

## Purpose

This registry captures recurring technical lessons, workarounds, design choices, and failure modes that appear across Beawit's applications and automation workflows. It exists so agents can recognize when a new task is an instance of a known pattern and apply proven countermeasures instead of rediscovering the problem.

This is the **generalization layer** of the agent continual-learning system:
- **Plasticity**: new patterns are added as they are discovered.
- **Stability**: old patterns are versioned and never silently overwritten.
- **Generalization**: patterns are retrieved by symptom, cause, or affected domain and injected into task context.

## Registry Structure

```
patterns/
├── README.md                  # This file
├── patterns.json              # Machine-readable manifest
├── ollama-structured-output-fallback.md
├── json-escaping-downstream-api.md
├── api-version-deprecation.md
├── pty-device-code-auth.md
├── queue-poll-async-job.md
├── llm-as-parser-fallback.md
├── credential-rotation-recovery.md
├── reverse-proxy-container-binding.md
├── human-approval-risky-publish.md
└── transient-failure-retry.md
```

## Pattern File Template

Every `.md` pattern uses the same sections:

```markdown
# Pattern: <Short Name>

## Symptom
What the agent or user sees when the pattern is active.

## Affected Projects
List of known projects/workflows where this pattern has occurred.

## Root Cause
Why it happens.

## Standard Fix
The proven workaround, safety net, or design choice.

## When to Apply
Trigger conditions for applying this pattern to a new task.

## Verification
How to confirm the fix actually worked.

## Related Patterns
Links to other patterns that often appear together.
```

## How Patterns Are Used

1. **Manual reference** — read the registry before designing a new integration or workflow.
2. **Automatic retrieval** — `architecture/pipeline.js` loads relevant patterns into the context packet based on keyword matching against the task input.
3. **Skill/worfklow design** — when a new workaround is applied, propose a new pattern entry if the underlying shape is reusable.

## Adding or Updating a Pattern

1. Create or edit the `.md` file.
2. Update `patterns.json` with id, tags, related patterns, and affected projects.
3. Run `node architecture/pipeline.js "sample query"` to verify the pattern is retrievable.
4. Update `MEMORY.md` Cross-Project Patterns if the pattern is stable and reusable.