# Build Test Fix Loop Target

This file defines what we want at the end of an overnight Build Test Fix loop.

The goal is not "the app exists."

The goal is:

**A real user can run Co-Vibe locally, connect an agent through MCP, start work, get duplicate-work warnings, see the team state in the UI, and generate a weekly summary draft.**

If that is not true, the loop is not done.

## Product

Co-Vibe is a shared visibility tool for small AI-assisted engineering teams.

It helps a team see:

- what each developer is working on
- what each agent is doing
- what tasks are active, blocked, done, or planned
- what long-running workstreams are active or completed
- when two developers may be doing duplicate work
- what engineering did this week

Co-Vibe should not feel like surveillance.

It should feel like a coordination layer.

## Required End State

At the end of the loop, the repo should contain a working customer-readiness slice with:

1. A shared server.
2. A structured database.
3. An MCP server that agents can call.
4. A web UI.
5. Duplicate-work checking.
6. Human confirmation for overlap.
7. A weekly summary draft.
8. Authentication for real developers.
9. Usage/session tracking foundations and visible metrics.
10. Tests proving the main flow works.
11. A short morning report explaining what was built and what still fails.

## User Journey

This flow must work:

1. A developer starts the Co-Vibe server.
2. The server prints the UI URL and MCP URL.
3. A developer opens the UI.
4. The UI shows Workstreams.
5. An agent calls `covibe_task` with `operation: "check"`.
6. If no overlap exists, the agent can start the task.
7. The task appears in Workstreams.
8. The task event appears in Activity.
9. Another agent checks similar work.
10. Co-Vibe returns an overlap warning.
11. The agent cannot start overlapping work without a human confirmation reason.
12. The confirmed overlap appears in Coordination's overlap warnings.
13. The developer completes a task.
14. The completed task appears in Activity.
15. The system proves the work event was saved in structured storage.
16. The weekly summary draft includes completed work, active work, blockers, decisions, overlap warnings, and agent sessions.

If this journey does not work, the loop continues.

## Data Rules

The source of truth is structured data.

Do not store core state in loose Markdown files.

Markdown is allowed for documentation, exported reports, weekly summary text, and morning reports.

The app must store structured records for:

- developers
- agent sessions
- tasks
- workstreams
- work events
- overlap warnings
- weekly summaries
- usage events
- agent feedback events

## Metrics Foundation

The system stores and exposes:

- session count
- session duration
- agent usage by developer
- MCP tool usage counts
- warnings created
- warnings confirmed
- weekly work volume
- active work by project

The dashboard shows active work, completed weekly work, sessions, session time, tool calls, warnings, and confirmed overlaps.

Deeper statistics can build on the same structured records without changing the core schema.

## MCP Tools Required

The product must expose compact MCP tools:

- `covibe_task`
- `covibe_workstream`
- `covibe_session`
- `covibe_note`
- `covibe_team`
- `covibe_coordination`
- `covibe_warning`
- `covibe_ingest_agent_telemetry`

## Hard MCP Rules

The server must enforce these rules.

Agent instructions alone are not enough.

1. A task cannot start unless `covibe_task` `operation: "check"` was called recently.
2. A workstream cannot start unless `covibe_workstream` `operation: "check"` was called recently.
3. Recent means within 10 minutes.
4. If the check found overlap, start must fail unless a human confirmation reason is provided.
5. Every successful tool call writes a work event.
6. Completed tasks must include a result summary.
7. Every MCP tool call writes a usage event.
8. If a tool blocks an agent, the response must explain what the agent should do next.
9. The agent must receive structured feedback, not only a UI-side warning.
10. Planned tasks cannot be updated or completed until they are checked and started.
11. Abandoned planned or active work can be cancelled with an audit reason.

## Authentication Requirement

Auth has been a real problem in other projects.

Do not leave auth vague.

The loop must pick one of these:

- WorkOS AuthKit
- Clerk

Auth must support:

- developer login for the UI
- developer identity attached to tasks/events
- MCP client token or API key for local agents
- ability to revoke a developer/agent token

Minimum acceptable auth slice:

- real UI login using chosen auth provider
- local MCP token generated for a logged-in developer
- MCP calls map token to developer
- all tasks/events/warnings store developer id

If auth cannot be fully verified overnight, the morning report must say exactly
what works and which external checks remain unproven.