# AI Factory V3 Operator Console Plan — MC 102226

# AI Factory V3 — Internal Operator Console Plan

Generated: 2026-05-26  
Parent MC: #102225  
Plan/spec MC: #102226  
Process: `ai-factory-102225`  
Mode: internal-only, no deploy/no production mutation by default

## 1. Product intent

AI Factory V2 proved the workflow chain: CEO/operator goal → MC parent/subtasks → BookStack/spec → routed work packages → evidence bundle → verification/writeback. V3 should make that workflow easier to operate by adding a small internal operator console that gives John/CEO one place to inspect workflow state and evidence readiness.

This is not an external SaaS product yet. It is an internal productization layer over existing ALAI primitives: MC, process tracker, BookStack, `/tmp/evidence-*`, AI Factory specs, and Company Mesh/P2P evidence.

## 2. First slice recommendation

Build a **read-only CLI/markdown operator console** before any web UI.

Proposed command shape:

```bash
node ~/system/tools/ai-factory.js console --process ai-factory-102225 --json
node ~/system/tools/ai-factory.js console --task 102225 --markdown
```

The command should produce a deterministic status package, for example:

- JSON: `/tmp/alai/ai-factory/console/<process-id>-console.json`
- Markdown: `/tmp/alai/ai-factory/console/<process-id>-console.md`

## 3. Console data model

Minimum JSON fields:

```json
{
  "ok": true,
  "generated_at": "ISO-8601",
  "process_id": "ai-factory-102225",
  "parent_task_id": 102225,
  "bookstack_url": "https://docs.alai.no/...",
  "local_spec_path": "/Users/makinja/system/specs/ai-factory/...md",
  "status": {
    "process": "active|completed|blocked",
    "parent_task": "open|in_progress|ready_for_review|done",
    "next_action": "human-readable next action"
  },
  "subtasks": [
    {
      "id": 102226,
      "role": "plan|build|verify|docs|postflight",
      "status": "open|in_progress|ready_for_review|done",
      "priority": "H|M|L",
      "route": "product|qa|...",
      "evidence_ready": true,
      "bookstack_url": "...|null"
    }
  ],
  "evidence": {
    "expected_dirs": ["/tmp/evidence-102226"],
    "present_files": ["/tmp/evidence-102226/verification.md"],
    "missing_required": []
  },
  "p2p": {
    "required": false,
    "latest_thread_id": "mesh-thr-*|null",
    "latest_end_state": "PASS|PARTIAL|ANSWERED|BLOCKED|null",
    "evidence_paths": []
  },
  "warnings": []
}
```

## 4. In scope for V3 first implementation slice (#102227)

- Extend `~/system/tools/ai-factory.js` with a read-only `console` command.
- Support lookup by `--process <process-id>` and/or `--task <parent-task-id>`.
- Reuse existing files and tools; do not introduce a new database.
- Summarize MC/process/subtask state using existing MC/process evidence.
- Detect evidence bundle presence under `/tmp/evidence-<task>/` and `/tmp/alai/ai-factory/`.
- Include P2P status if evidence paths or mesh thread IDs are discoverable from existing evidence; otherwise report `null`, not guessed values.
- Write deterministic JSON and Markdown output to `/tmp/alai/ai-factory/console/`.
- Provide `--json` output to stdout for scripts.
- Add smoke/regression test coverage.

## 5. Out of scope for first slice

- External SaaS/web portal.
- Browser UI.
- Automatic dispatch or automatic builder execution.
- Replacing MC ready/done gates.
- Replacing Proveo/final QA.
- Production deploy.
- Snowit/Azure/client environment mutation.
- Claiming model-backed PASS when only receipt/plumbing evidence exists.

## 6. Acceptance criteria for build slice #102227

Implementation is acceptable when these are true:

1. `node --check ~/system/tools/ai-factory.js` passes.
2. `node ~/system/tools/ai-factory.js console --process ai-factory-102225 --json` returns valid JSON with `ok=true`, `process_id`, `parent_task_id`, `subtasks`, `evidence`, `p2p`, and `warnings` fields.
3. `node ~/system/tools/ai-factory.js console --process ai-factory-102225 --markdown` writes a Markdown report under `/tmp/alai/ai-factory/console/`.
4. Console output includes the BookStack URL for the workflow when available.
5. Console output lists all five V3 subtasks: #102226, #102227, #102228, #102229, #102230.
6. If an evidence directory is missing, console reports it as missing; it must not fabricate evidence paths.
7. Regression test or smoke script covers at least:
   - process lookup happy path,
   - missing evidence directory warning,
   - JSON parseability,
   - no mutation outside `/tmp/alai/ai-factory/console/`.
8. `git diff --check` passes for changed files.
9. Evidence package for #102227 is written under `/tmp/evidence-102227/` before ready/done.

## 7. Verification plan for #102228

Independent verification should not rely on builder summaries. It should inspect files and run commands:

```bash
cd /Users/makinja/system
node --check tools/ai-factory.js
node tools/ai-factory.js console --process ai-factory-102225 --json > /tmp/alai/ai-factory-v3-console-smoke.json
node -e "const fs=require('fs'); const d=JSON.parse(fs.readFileSync('/tmp/alai/ai-factory-v3-console-smoke.json','utf8')); if(!d.ok || !d.process_id || !Array.isArray(d.subtasks)) process.exit(2)"
node tools/ai-factory.js console --process ai-factory-102225 --markdown
git diff --check -- tools/ai-factory.js tests
```

If tests are added, run the specific test command and include output in `/tmp/evidence-102228/`.

## 8. Risks and mitigations

| Risk | Mitigation |
|---|---|
| Console becomes another hallucination surface | Use deterministic tool/file reads only; null/unknown when evidence is missing |
| It bypasses MC gates | Read-only console; ready/done remains in MC |
| It overstates P2P quality | Distinguish `PASS/PARTIAL/ANSWERED/BLOCKED` and receipt-only evidence |
| It becomes too big | First slice is CLI + markdown only |
| BookStack/API availability blocks local use | Console must work locally even if BookStack is unreachable, using known URLs from MC/spec where present |

## 9. Recommended next actions

1. Close this plan/spec task #102226 with this document as evidence.
2. Start #102227 build slice with this file as the source of acceptance criteria.
3. After #102227, run #102228 independent verification before docs/postflight.