Overview

Implement chaac fixer — an agent-powered error remediation pipeline that:

1. Takes a runtime error code from a Tawa service
2. Looks up the error's structured metadata from the Bible
3. Reads the referenced source code via stackRefs
4. Uses chaac-boss (Claude planning agent) to generate a fix proposal
5. Holds for admin approval in the Chaac Eye dashboard
6. On approval, opens a Forgejo PR with the proposed change

The entire review + execution infrastructure already exists in chaac-boss. This work is additive only — no existing behavior changes.

Repo Locations

1. chaac — Add fixer Skill

File to create: src/skills/content/fixer.ts

The fixer skill is a Claude rule that instructs the plan worker in chaac-boss how to read a Bible ops error entry and generate a valid fix proposal. It should cover:

• How to read a Bible error entry (product, type: reference, slug: errors)
• How to interpret stackRefs to find the relevant code files
• How to read the agent hint and review-level fields
• The Fix Proposal structure the plan worker must output (see ops-guidelines doc: tawa-platform/reference/ops-guidelines)
• That the agent must never propose changes autonomously — always structure as a reviewable proposal
• review-level: hold means stop and surface to on-call, do not generate a proposal

Register the skill in src/skills/index.ts:

{
  id: 'fixer',
  name: 'Chaac Fixer',
  description: 'Generates structured fix proposals from Bible error entries for admin review',
  category: 'troubleshoot',
  format: 'rule',
  status: 'available',
}

2. chaac-claw — Add fix Command

File to create: src/commands/fix.ts

Command signature

chaac fix <error-code> --service <service-name> [--dry-run]

What it does

Step 1 — Fetch error entry from Bible

Call the jci-mcp Bible API (via JCI_BRAIN_URL from config or env):

GET {JCI_BRAIN_URL}/bible/tawa-platform/reference/errors

Parse the response markdown to find the ### {error-code} section. If not found, exit with a clear message: "Error code {error-code} not found in Bible. Add an entry to {service}/reference/errors first."

Step 2 — Read stackRefs source files

The Bible entry's stackRefs field contains code references in format "{service}/{path}:{symbol}". For each stackRef:

• Resolve the repo path from ~/.chaac/config.yml workspaces (match on service name)
• Read the file content
• Extract the relevant function/symbol if possible

Step 3 — Build task context

Assemble the context payload:

{
  errorCode: string,
  bibleEntry: string,          // raw markdown block for the error
  stackRefsContent: {          // file path → content
    [filePath: string]: string
  },
  reviewLevel: 'standard' | 'admin' | 'hold',
  service: string,
}

If reviewLevel === 'hold' — do not dispatch. Print: "This error is marked review-level: hold. Page on-call instead of submitting a fix proposal." and exit.

Step 4 — Dispatch to chaac-boss

POST {CHAAC_BOSS_URL}/tasks
{
  title: `Fix proposal: ${errorCode} in ${service}`,
  description: `Generate a structured fix proposal for error ${errorCode}...`,
  context: { ...assembled context },
  type: 'fixer',
  metadata: { errorCode, service, reviewLevel }
}

Step 5 — Output

Print the chaac-boss task URL and Chaac Eye dashboard URL so the admin knows where to review:

Fix proposal submitted.
Task:      http://localhost:8091/tasks/{taskId}
Review at: http://localhost:8091/ (Chaac Eye)

Config additions needed (src/config/schema.ts)

jefferson: {
  ...existing fields...
  bibleUrl: z.string().default('https://jefferson.daryx.com:9000')
}
chaaacBoss: {
  url: z.string().default('http://localhost:8091'),
  apiKey: z.string().optional()
}

Register the command in src/index.ts alongside existing commands.

3. chaac-boss — Add Forgejo PR Execution Strategy

Plan worker prompt addition (src/config/prompts.ts)

Add a case for tasks with type: 'fixer'. The plan worker should output steps like:

Step 1: Analyze the error entry and stackRefs code
Step 2: Identify the specific change needed
Step 3: Generate a unified diff for the proposed change
Step 4: Validate that the change matches the agent hint
Step 5: Open a Forgejo PR with the diff

The plan worker must emit a confidence field in its plan output for fixer tasks.

Exec worker — Forgejo PR strategy (src/services/dispatch.ts or new src/services/forgejo.ts)

File to create: src/services/forgejo.ts

When a fixer task step involves opening a PR:

async function openForgejoPR(params: {
  repoOwner: string,
  repoName: string,
  title: string,
  body: string,
  branch: string,
  files: Array<{ path: string, content: string }>
}): Promise<{ prUrl: string }>

Uses Forgejo API at https://git.tawa.insureco.io:

• Creates a new branch from main
• Commits the proposed file changes
• Opens a PR with the fix description and full reasoning chain in the body

Forgejo token should come from env: FORGEJO_TOKEN.

Forgejo Token — Org-Level Config (Dependency)

FORGEJO_TOKEN is not a local env var. It is an org-level secret stored in the tawa platform and read by chaac-boss at task execution time.

How it gets there:

A developer sets it once per org via the tawa console:

Console → Settings → Integrations → Forgejo
  [ Personal Access Token ] ____________  [Save]

Or via CLI:

tawa config set FORGEJO_TOKEN=xxx --secret

chaac-boss reads it from process.env.FORGEJO_TOKEN — the platform injects it as with any other managed secret.

This means the tawa-web Integrations page is a prerequisite for the fixer PR step to work. If FORGEJO_TOKEN is not set, the exec worker must fail gracefully with a clear message:

PR step skipped: FORGEJO_TOKEN not configured.
Set it at Console → Settings → Integrations → Forgejo, then re-run the fixer task.

Repo URL — no config needed

chaac-boss does not need the repo URL in config. When tawa link is run, the repo URL is stored in the builder registry. The exec worker looks it up via the builder API using the service name from the fix proposal:

GET {IEC_BUILDER_URL}/services?name={service}
→ { repoUrl: "https://git.tawa.insureco.io/insureco/iec-wallet" }

New env vars needed (.env.example)

FORGEJO_BASE_URL=https://git.tawa.insureco.io
# FORGEJO_TOKEN is injected from org-level tawa config — do not set locally

Task Lifecycle for Fixer Tasks

No changes to the existing lifecycle state machine. Fixer tasks use the standard flow:

submitted → planning → plan_review → approved → executing → verifying → completed

The plan_review step IS the admin approval gate. The Chaac Eye dashboard already shows this — no UI changes needed.

Out of Scope

• Monitoring integration (Janus/iec-observe triggering fix automatically) — future phase
• Auto-detection of errors from logs — future phase
• tawa-web admin UI for proposals — Chaac Eye dashboard is sufficient for now
• Any changes to existing chaac-boss task types or lifecycle

References

• ops-guidelines: tawa-platform/reference/ops-guidelines (fetch from Bible for full error entry format and Fix Proposal schema)
• chaac-boss task types: /Users/daryx/dev/chaac-boss/src/types/task.ts
• chaac-claw existing commands: /Users/daryx/dev/chaac-claw/src/commands/
• chaac skills index: /Users/daryx/dev/chaac/src/skills/index.ts
• Forgejo API docs: https://git.tawa.insureco.io/api/swagger