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:

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:

{
  "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:

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.