#  System Prompt: Evolutionary Architecture Pipeline Implementation

**Goal:** Build a custom CI/CD script that combines spatial data (where code lives), temporal data (when code changes), and structural data (what the code does) to guide incremental refactoring in a TypeScript + Effect.ts codebase.

**Tech Stack:**
1.  **Dependency-Cruiser:** To map spatial boundaries (Seams).
2.  **Hercules:** To map temporal evolutionary coupling. 
3.  **Opengrep:** To identify data-flow anti-patterns (Tramp Data, Branching).
4.  **TypeScript (Node.js):** The "glue" script (`refactor-bot.ts`) that synthesizes the data.

---

### Step 1: Establish Spatial Boundaries (Dependency-Cruiser)
**Agent Instructions:**
1. Install dependency-cruiser: `npm install -D dependency-cruiser`
2. Initialize it `npx depcruise --init` and configure it for a TypeScript environment.
3. Modify the `.dependency-cruiser.js` configuration to define "Seams". Group the application by folders (e.g., Domain boundaries, Layers, or Effect modules).
4. Create an npm script named `"map:boundaries"` that runs depcruise and outputs the architecture to a JSON file: `npx depcruise src --output-type json > ./.architecture/seams.json`.

---

### Step 2: Establish Temporal Coupling (Hercules / Git Mining)
**Agent Instructions:**
1. Set up a tool to extract **Logical Coupling** from the git history. 
   *(Note for Agent: Use the `src-d/hercules` binary via Docker or Go, OR use the simpler `code-maat` Python/Clojure alternative if Hercules is blocked by local environment constraints).*
2. Execute a git log command to get history:
   ```bash
   git log --all --numstat --date=short --pretty=format:'--%h--%ad--%aN' --no-renames > ./.architecture/logfile.log
   ```
3. Run the coupling analysis tool against this log. The goal is to output a `.csv` or `.json` file (`coupling.json`) with three columns/fields: `[FileA, FileB, CoChangePercentage]`.
4. Ensure this output is saved to `/.architecture/coupling.json`.

---

### Step 3: Implement Deep Static Analysis (Opengrep / Semgrep)
**Agent Instructions:**
1. Install the open-source CLI (e.g., `npm install -g opengrep` or use `pip install semgrep`).
2. Create a folder `/.architecture/rules/`.
3. Write custom YAML rules to detect code smells specific to **Effect.ts** and functional pipelines. 
4. **Rule 1: Tramp Data in Pipelines.** Write a rule that looks for a variable passed into a `.pipe()` or `Effect.gen` that traverses across a recognized boundary un-mutated. Use the ellipsis operator (`...`).
   *Example concept:*
   ```yaml
   rules:
     - id: effect-tramp-data
       pattern: pipe(..., $MOD_A.get($DATA), ..., $MOD_B.save($DATA), ...)
       message: "Potential tramp data crossing seam boundaries."
       languages: [typescript]
       severity: WARNING
   ```
5. Ensure there is a command to run this and output to JSON: `opengrep --config ./.architecture/rules/ --json > ./.architecture/smells.json`

---

### Step 4: Write the Synthesis Script (`refactor-bot.ts`)
**Agent Instructions:**
Write a Node.js TypeScript file (`scripts/refactor-bot.ts`) that acts as the brain. This script must:

**1. Load the Data:**
*   Parse `seams.json` (Which files belong to which boundary).
*   Parse `coupling.json` (How often files change together).
*   Parse `smells.json` (Where the AST anti-patterns are).

**2. Detect Cross-Seam Leaks (High External Coupling):**
*   Look at pairs in `coupling.json` that co-change > 60% of the time, but live in *different* Seams according to `seams.json`.
*   *Action:* Flag these as **Architectural Leaks**. Check if `smells.json` found tramp data in these specific files. 

**3. Detect Splittable Contexts (Low Internal Cohesion):**
*   Look at files that exist in the *same* Seam (e.g., both are in `src/payments/`), but have a co-change frequency of < 5%.
*   *Action:* Flag this boundary as a candidate to be split into two smaller bounded contexts.

**4. Generate the Output/Report:**
*   Output a Markdown report summarizing:
    *   **⚠️ High Priority Refactors:** Cross-layer tightly coupled files (includes Semgrep AST context).
    *   **✂️ Suggested Seam Splits:** Modules with low internal cohesion.
*   Exit with code `1` if the max coupling threshold is breached to fail the CI/CD pipeline, otherwise exit with `0`.

---

### Definition of Done for Agent:
1. `dependency-cruiser` is configured and outputs `seams.json`.
2. Git history pipeline outputs `coupling.json`.
3. Opengrep/Semgrep YAML rules are written for Effect.ts and output `smells.json`.
4. `refactor-bot.ts` successfully reads all three files and prints an Evolutionary Architecture Report in the console.