# Multi-Project Plans

## Overview

CleverAgents supports plans that target multiple projects simultaneously.
When a plan is created with more than one `--project` flag (or multiple
positional project arguments), a **multi-project plan** is formed.

Each project receives an isolated **ProjectScope** that tracks:

- Which resource IDs belong to the project
- Whether the project is read-only or writable
- Per-project changeset summaries during execution

## Creating a Multi-Project Plan

```bash
agents plan use local/refactor-api \
  --project api-service \
  --project shared-lib \
  --arg target_coverage=80
```

## Alias Resolution

Projects can be given aliases for easier reference in multi-project
contexts:

```bash
agents plan use local/migrate-schema \
  api-service@api \
  shared-lib@lib
```

The `ProjectScopeResolver.resolve_alias()` method searches aliases first,
then falls back to project names.

## Scope Isolation

Each project scope is independently tracked:

| Field               | Description                                 |
|---------------------|---------------------------------------------|
| `project_name`      | Namespaced project identifier               |
| `alias`             | Optional short name for quick reference     |
| `read_only`         | Whether mutations are forbidden             |
| `resource_ids`      | Resources belonging to this project         |
| `changeset_summary` | Per-project file change statistics          |

## Mixed Access Enforcement

By default, plans with mixed read-only and writable projects are
flagged with a warning. To explicitly allow mixed access, set
`allow_mixed_access=True` on the `MultiProjectMetadata`.

When `allow_mixed_access` is `False` (the default), validation returns
an error listing the read-only and writable projects.

## Cross-Project Dependencies

The `CrossProjectDependency` model captures directional dependencies
between projects within a plan:

```
source_project  ->  target_project  (dependency_type)
```

Examples:
- `api-service -> shared-lib` (imports)
- `frontend -> api-service` (api-consumer)

## Per-Project Changeset Summaries

During execution, each project scope records a `ChangeSetSummary`:

| Field                | Description                           |
|----------------------|---------------------------------------|
| `files_changed`      | Number of modified files              |
| `files_added`        | Number of created files               |
| `files_deleted`      | Number of deleted files               |
| `total_lines_changed`| Total lines added + removed           |
| `validation_passed`  | Per-project validation result         |
| `validation_errors`  | Error messages from validation        |

These summaries appear in `agents plan status` output and in the
`as_cli_dict()` representation under `multi_project.project_scopes`.

## Domain Models

| Class                     | Module                                          |
|---------------------------|-------------------------------------------------|
| `ProjectScope`            | `cleveragents.domain.models.core.multi_project` |
| `ChangeSetSummary`        | `cleveragents.domain.models.core.multi_project` |
| `MultiProjectMetadata`    | `cleveragents.domain.models.core.multi_project` |
| `CrossProjectDependency`  | `cleveragents.domain.models.core.multi_project` |
| `ProjectScopeResolver`    | `cleveragents.domain.models.core.multi_project` |

## Service Layer

`MultiProjectService` (in `cleveragents.application.services.multi_project_service`)
provides:

- `initialize_scopes(plan, available_resources)` -- Creates metadata
- `resolve_context_view(plan, name_or_alias)` -- Returns a ProjectScope
- `record_changeset(plan, project_name, summary)` -- Records changes
- `validate_cross_project(plan)` -- Validates constraints

## Plan Model Extensions

The `Plan` model gains:

- `multi_project_metadata: MultiProjectMetadata | None` field
- `is_multi_project: bool` computed property
- `get_project_scope(name_or_alias)` method
- Extended `as_cli_dict()` with multi-project section