# Phase Handover — AF-Project-Index (Project Index — Runtime Discovery)

| Field | Value |
| --- | --- |
| Phase ID | `ai-framework-project-index` |
| Title | Project Index — Single Runtime Discovery Entry Point |
| Status | Complete |
| Service(s) | N/A (documentation / process only) |
| Version | Framework project-index-1.0 |
| Date | 2026-07-26 |
| ADR(s) | Extends [ADR-018](../architecture/adr/ADR-018.md), [ADR-019](../architecture/adr/ADR-019.md) (process; no new ADR) |

## Business Analysis Summary

| Item | Detail |
| --- | --- |
| Capabilities delivered | Authoritative `project-index.yaml` for all registered services; execution starts from index; no repository folder scans for discovery |
| Explicit non-goals honored | No business service code changes; no completed business phase retrofits; no pre-generated per-service snapshot YAML files |

## Enterprise Phase Discovery Summary (this docs phase)

| Item | Detail |
| --- | --- |
| Discovery Record location | This handover + [project-index.yaml](../ai-framework/project-index.yaml) |
| Gaps promoted & closed | Ad-hoc path discovery → Project Index resolution for services, snapshots, roadmaps, handovers |
| Exclusions | All business phases and services |
| CRUD-only rejected | N/A (process rule) |

## Enhancement Catalog

### New authoritative index

| Document | Purpose |
| --- | --- |
| [project-index.yaml](../ai-framework/project-index.yaml) | One entry per registered service with all required discovery fields; `execution_order`; shared references |

### Core execution upgrades

| Document | Enhancement |
| --- | --- |
| [runtime-read-policy.md](../ai-framework/runtime-read-policy.md) | Project Index step 1; never scan folders; paths from index |
| [context-cache-policy.md](../ai-framework/context-cache-policy.md) | Index always reload; update on registration/Complete |
| [service-snapshot-policy.md](../ai-framework/service-snapshot-policy.md) | Snapshot paths from index; index updated on regeneration |
| [master-prompt.md](../ai-framework/master-prompt.md) | Index-first loading; registration updates index |
| [development-loop.md](../ai-framework/development-loop.md) | Discovery from index; Documentation Update updates index |
| [enterprise-phase-discovery.md](../ai-framework/enterprise-phase-discovery.md) | Project Index as primary discovery source |
| [mandatory-phase-artifacts.md](../ai-framework/mandatory-phase-artifacts.md) | Artifact #44 Project Index Update |
| [phase-handover.md](../ai-framework/phase-handover.md) | Project Index Update section |
| [quality-gates.md](../ai-framework/quality-gates.md) | Mandatory Project Index validation gate |

## Reusable Components

| Component | Location | Reuse notes |
| --- | --- | --- |
| Project Index | `docs/ai-framework/project-index.yaml` | First file loaded every execution |
| Execution order | Same `execution_order` block | Machine-readable phase entry |
| Service entries | Same `services` list | Resolve snapshot, roadmap, handover paths |

## Public APIs

N/A — documentation/process only.

## Events

N/A.

## Permissions

N/A.

## Extension Points

| Extension point | How to extend | Forbidden uses |
| --- | --- | --- |
| New service | Add index entry + service-manifest entry in same phase | Discovering services by scanning `backend/services/` |
| New index field | Add to policy + template + validation gate | Full repository tree walks |

## Known Limitations

- Index seeded from [service-manifest.yaml](../ai-framework/service-manifest.yaml) at framework upgrade time; per-service snapshots not pre-generated.
- `latest_handover: null` for services without handover files yet.
- Agents must keep index aligned with manifests on every registration and Complete phase.

## Migration Notes

| Item | Detail |
| --- | --- |
| Alembic revision(s) | N/A |
| Upgrade steps | Load `project-index.yaml` first on every execution; update index on next service Complete phase |
| Breaking changes | None for runtime; mandatory index-first discovery for future phases |

## Dependencies

| Dependency | Type | Required for |
| --- | --- | --- |
| AF-Service-Snapshot | Docs | Snapshot paths in index |
| AF-Context-Cache-Policy | Docs | Incremental loading |
| AF-Runtime-Read-Policy | Docs | Load tiers |

## Boundary Compliance

- [x] No foreign service ownership implemented
- [x] No business logic duplication
- [x] No cross-DB access
- [x] No business service code modified

## Project Index Update

| Field | Value |
| --- | --- |
| Index path | docs/ai-framework/project-index.yaml |
| Services indexed | 27 (all service-manifest entries) |
| Last updated | 2026-07-26 |

## Enterprise Completeness Sign-Off

- [x] Discovery completeness (index-based discovery)
- [x] Documentation completeness
- [x] Self Audit

## Definition of Done

- [x] project-index.yaml published with all registered services
- [x] All listed framework docs updated
- [x] Project Index quality gate added
- [x] Framework handover complete
- [x] No business code changes

## Next Phase Entry

1. [project-index.yaml](../ai-framework/project-index.yaml) — **always first**
2. Execution order steps 2–8 per [runtime-read-policy.md](../ai-framework/runtime-read-policy.md)
3. Update index on service registration and phase Complete
4. Resume business milestones per [next-steps.md](../next-steps.md) when explicitly requested

| Field | Value |
| --- | --- |
| Recommended next phase | Per [next-steps.md](../next-steps.md) (experience-11.4) — not started by this phase |
| Blockers for next phase | None |
| Entry checklist | Project Index → policies → snapshot → manifests → latest handover → Discovery |

## Completion Sign-Off

- [x] Project Index integrated as single discovery entry point
- [x] Mandatory Project Index validation gate added
- [x] Framework handover complete
- [x] No business service modifications

## Related Documents

- [Project Index](../ai-framework/project-index.yaml)
- [Runtime Read Policy](../ai-framework/runtime-read-policy.md)
- [Service Snapshot Policy](../ai-framework/service-snapshot-policy.md)
- [Phase Handover AF-Service-Snapshot](phase-af-service-snapshot.md)