Clone Feedback Loop & Corrections Engine

1. Problem Statement

The clone factory produces extraction JSONs (L2), compiles them into a system prompt (L3), and tests the clone (L3.5). Automated testing scores 93.8%. But:

This PRD specifies the feedback loop — the system that takes human audit findings, routes corrections to the right upstream skill, triggers targeted re-runs, and tracks convergence until the expert signs off.

2. Current State (What Exists)

Audit Collection Pages

Data Pipeline (Built)

Audit Submit ──→ clone_feedback table
              └──→ audit-analyze API (auto-fires)
                      └──→ improvement_items table (classified findings)
                              └──→ Improvement Dashboard (triage view)
                                      └──→ ??? (MANUAL GAP)

Extraction Review Submit ──→ clone_feedback table
                          └──→ improvement_items table (per flagged item)
                                  └──→ ??? (MANUAL GAP)

Process Factory (Built)

• 23-block DAG engine with parallel groups, human gates, thresholds, snapshots
• Gate rejection stores feedback but does NOT inject it into the next execution
• Auto-retry on threshold failure runs identically (no correction context)
• lens.feedback_loop field exists in block schema but is null for all 23 blocks
• factory_block_id and factory_run_id columns exist on improvement_items but are unused

3. The Complete Feedback Loop

4. New Factory Blocks

Three new blocks insert into the factory DAG between existing layers:

extraction-reviewer (L2.6)

expert-audit (L3.6)

corrections-router (L3.7)

Updated DAG Flow

L0  deep-research ─┐
    expert-recon ───┤ (parallel L0-recon)
    masterybook-sync┘
         │
L0.25 expert-framework-creator [gate: after]
         │
L0.5  demo-compiler
         │
L1    rubric-builder
         │
L2    soul ─┐
      voice ─┤
      framework┤ (parallel L2-extractors)
      resource ┤
      offer ───┘
         │
L2.6  extraction-reviewer [gate: after]  ← NEW
         │
L2.5  gap-analyzer [gate: after]
         │
L3    clone-compiler ─┐
      lead-magnet ─────┤ (parallel L3-builders)
      onboarding ──────┤
      design-system ───┘
         │
L3.5  clone-tester [gate: after, threshold: 85]
         │
L3.6  expert-audit [gate: after]  ← NEW
         │
L3.7  corrections-router  ← NEW
         │ (resets upstream blocks if corrections exist)
         │ (re-triggers L2→L3→L3.5→L3.6 cycle)
         │
L4    boarding-orchestrator (only reached when 0 corrections)
         │
L5    marketing-page-builder ─┐
      email-sequence-builder ──┤ (parallel L5-marketing)
      stripe-setup ────────────┘
         │
L6    audit-page-publisher ─┐
      publish-orchestrator ──┘ (parallel L6-publishing)

5. Corrections Engine Spec

How Corrections Flow Into Re-Runs

When corrections-router executes, it:

Step 1: Query Improvement Items

SELECT * FROM improvement_items
WHERE factory_run_id = '{run_id}'
  AND status = 'accepted'
ORDER BY priority DESC, skill_target

Step 2: Group by Skill Target

{
  "voice-extractor": [
    { "source_text": "Too formal in high-energy mode",
      "expert_correction": "I use 'Let's GO!' not 'Let us proceed'",
      "priority": "high" },
    ...
  ],
  "soul-extractor": [
    { "source_text": "Missing value: Community over competition",
      "expert_correction": "I never rank people against each other",
      "priority": "critical" },
    ...
  ]
}

Step 3: Inject Into Block State

New field: block.state.corrections

// Added to the targeted block's state before re-run
block.state.corrections = {
  version: "v7.1→v7.2",
  source: "expert-audit + extraction-review",
  items: [
    { finding: "...", correction: "...", priority: "high" }
  ],
  instruction: "IMPORTANT: The expert reviewed the previous extraction and flagged these corrections. Apply each correction to the output. Do not lose existing correct content — only fix the flagged items."
}

Step 4: Update /api/execute Context

The execute endpoint already builds context from SKILL.md + inputs + upstream artifacts + gaps. Add corrections as a new context section:

// In /api/execute, when building the prompt:
if (block.state.corrections?.items?.length) {
  contextParts.push(`
## EXPERT CORRECTIONS (MUST APPLY)
The expert reviewed the previous version and flagged these corrections.
Apply each one. Do not remove correct content — only fix flagged items.

${block.state.corrections.items.map(c =>
  `- FINDING: ${c.finding}\n  CORRECTION: ${c.correction}\n  PRIORITY: ${c.priority}`
).join('\n\n')}
  `);
}

Step 5: Mark Items Resolved After Re-Run

After the targeted block completes successfully, mark the improvement_items as resolved:

UPDATE improvement_items
SET status = 'resolved',
    resolved_in_version = '{new_version}',
    resolution_notes = 'Auto-resolved via corrections-router re-run'
WHERE factory_run_id = '{run_id}'
  AND skill_target = '{block_skill}'
  AND status = 'accepted'

6. Multi-Tester Aggregation

Tester Roles & Weights

Consensus Logic

Implementation

Add to clone_feedback table:

ALTER TABLE clone_feedback ADD COLUMN tester_role TEXT DEFAULT 'team';
-- Valid: 'expert', 'product_lead', 'tech_lead', 'team', 'external'

Add to improvement_items table:

ALTER TABLE improvement_items ADD COLUMN consensus_score NUMERIC DEFAULT 0;
ALTER TABLE improvement_items ADD COLUMN flagged_by JSONB DEFAULT '[]';
-- flagged_by: [{ "tester": "samuel-ngu", "role": "expert", "weight": 3.0, "feedback_id": "..." }]

Aggregation runs after each audit submit — queries all improvement_items for the same expert_slug + source_scenario key, recalculates consensus_score across all testers who flagged it.

7. Convergence Tracking

What to Track

Ship Criteria

Convergence Dashboard

New page: align360.asapai.net/{expert}-convergence

Shows version-over-version comparison:

Version  | Auto Score | Expert Rate | Extraction | Critical | High | Status
---------|------------|-------------|------------|----------|------|--------
v7.0     | 91.9%      | —           | —          | 3        | 8    | superseded
v7.1     | 93.8%      | —           | —          | 0        | 5    | superseded
v7.2     | —          | 85%         | 92%        | 0        | 2    | current
v7.3     | —          | —           | —          | —        | —    | pending

8. API Interface Contract

This is the contract between the audit pages (folio-saas) and the corrections engine (process-factory).

Folio-saas → Process Factory (new endpoint)

POST /api/corrections-ingest

Called by audit-analyze and extraction-review-submit after creating improvement_items. Notifies the factory that new corrections are available.

// Request
{
  "run_id": "factory-run-uuid",
  "expert_slug": "samuel-ngu",
  "feedback_id": "clone-feedback-uuid",
  "items_created": 5,
  "by_skill": {
    "voice-extractor": 2,
    "soul-extractor": 1,
    "clone-compiler": 2
  },
  "source": "expert-audit" | "extraction-review"
}

// Response
{
  "acknowledged": true,
  "run_status": "corrections-pending",
  "blocks_to_rerun": ["voice-extractor", "soul-extractor", "clone-compiler"]
}

Process Factory → Folio-saas (existing endpoints, enhanced)

GET /api/a360/improvement-items (new)

Query improvement_items for a factory run. Used by corrections-router.

// Request
GET /api/a360/improvement-items?run_id=xxx&status=accepted&skill_target=voice-extractor

// Response
{
  "items": [
    {
      "id": "uuid",
      "finding_type": "voice_gap",
      "skill_target": "voice-extractor",
      "priority": "high",
      "source_text": "Too formal in high-energy mode",
      "expert_correction": "I use contractions and exclamation marks when excited",
      "consensus_score": 3.0,
      "flagged_by": [{ "tester": "samuel-ngu", "role": "expert", "weight": 3.0 }]
    }
  ],
  "total": 1
}

PATCH /api/a360/improvement-items/:id (new)

Update improvement_item status after correction applied.

// Request
PATCH /api/a360/improvement-items/uuid
{
  "status": "resolved",
  "resolved_in_version": "v7.2",
  "resolution_notes": "Re-extracted with correction context",
  "factory_block_id": "voice-extractor",
  "factory_run_id": "run-uuid"
}

9. Schema Changes

Migration 005: Feedback Loop Support

-- 005-feedback-loop.sql

-- 1. Tester role on clone_feedback
ALTER TABLE clone_feedback ADD COLUMN IF NOT EXISTS tester_role TEXT DEFAULT 'team';

-- 2. Multi-tester consensus on improvement_items
ALTER TABLE improvement_items ADD COLUMN IF NOT EXISTS consensus_score NUMERIC DEFAULT 0;
ALTER TABLE improvement_items ADD COLUMN IF NOT EXISTS flagged_by JSONB DEFAULT '[]';

-- 3. Version tracking
ALTER TABLE improvement_items ADD COLUMN IF NOT EXISTS prompt_version TEXT;
ALTER TABLE improvement_items ADD COLUMN IF NOT EXISTS extraction_version TEXT;

-- 4. Index for corrections-router queries
CREATE INDEX IF NOT EXISTS idx_improvement_items_run_status
  ON improvement_items(factory_run_id, status)
  WHERE factory_run_id IS NOT NULL;

CREATE INDEX IF NOT EXISTS idx_improvement_items_expert_scenario
  ON improvement_items(expert_slug, source_scenario)
  WHERE source_scenario IS NOT NULL;

10. Process Factory Integration

Changes to Process Factory Engine

1. Block state: add corrections field

In lib/types.ts, add to BlockState:

corrections?: {
  version: string;           // "v7.1→v7.2"
  source: string;            // "expert-audit" | "extraction-review" | "both"
  items: Array<{
    finding: string;
    correction: string;
    priority: 'critical' | 'high' | 'medium' | 'low';
    improvement_item_id: string;
  }>;
  instruction: string;       // injected into LLM context
}

2. Execute endpoint: inject corrections context

In /api/execute, when building the LLM prompt, check for block.state.corrections and prepend as a high-priority context section.

3. Gate rejection: inject feedback into corrections

In /api/factory-run reject action, convert gate feedback into a corrections-compatible format and store in block.state.corrections so the next run actually uses it.

4. New blocks in template

Add extraction-reviewer, expert-audit, and corrections-router to clone-factory-template.json with proper dependency wiring.

5. Corrections-router execution logic

The corrections-router is unique — it doesn't call an LLM. It:

1. Reads improvement_items from folio-saas API
2. Groups by skill_target
3. Resets targeted upstream blocks (via factory-run reset action)
4. Injects corrections into each block's state
5. If 0 accepted items → marks itself done, DAG proceeds to L4
6. If > 0 items → triggers re-run cycle, eventually returns to L3.6 (expert-audit) for re-validation

11. Build Sequence

Verification

1. Create a factory run with the updated 26-block template
2. Run L0→L2 normally
3. L2.6 extraction-reviewer generates review page → expert submits → improvement_items created
4. L2.6 gate approved → L2.5 gap-analyzer → L3 compile → L3.5 test
5. L3.6 expert-audit generates audit page → expert submits → improvement_items created
6. L3.7 corrections-router reads items → resets targeted L2 blocks → re-runs with corrections
7. Cycle repeats: L2→L3→L3.5→L3.6→L3.7 until 0 corrections
8. L3.7 passes through to L4 boarding-orchestrator
9. Convergence dashboard shows version progression