# Orphan Detection Check

## Context

App: {{APP_NAME}}
Business flow docs: {{BUSINESS_FLOW_DOCS}}
Story docs: {{STORY_DOCS}}
Screen docs: {{SCREEN_DOCS}}
Actor docs: {{ACTOR_DOCS}}
Resolver docs: {{RESOLVER_DOCS}}
Module metadata (JSON): {{MODULE_METADATA}}

## Instructions

1. Read ALL docs at the paths above
2. Build a reference graph: which docs link to which other docs
3. Run every parity check below to find orphaned documents
4. Return results as JSON per the Output Format section

## Building the Reference Graph

Scan all docs for outgoing links using these patterns:

| From          | To            | Link Pattern                        |
| ------------- | ------------- | ----------------------------------- |
| Business Flow | Story         | `./story/<actor>--<name>.md`        |
| Business Flow | Actor         | `../../actor/<actor>.md`            |
| Actor         | Business Flow | `../business-flow/<flow>/README.md` |
| Story         | Screen        | `../../../screen/<screen>.md`       |
| Story         | Resolver      | `../../../resolver/<name>.md`       |

For each doc, record all outgoing link targets (resolved to actual file paths).

## Parity Checks

| Check ID         | Question                                             |
| ---------------- | ---------------------------------------------------- |
| orphan_stories   | Are there stories not linked from any business flow? |
| orphan_screens   | Are there screens not referenced by any story?       |
| orphan_actors    | Are there actors not participating in any flow?      |
| orphan_resolvers | Are there resolvers not referenced by any story?     |
| invalid_module_ref | Do resolvers reference modules or commands/queries that don't exist in installed modules? |

### How to Check

1. **Orphan stories**: For each file in STORY_DOCS, check if any business flow README links to it. If no flow references it, it is an orphan.
2. **Orphan screens**: For each file in SCREEN_DOCS, check if any story doc links to it. If no story references it, it is an orphan.
3. **Orphan actors**: For each file in ACTOR_DOCS, check if any business flow README links to it AND the actor doc links to at least one flow. If neither condition is met, it is an orphan.
4. **Orphan resolvers**: For each file in RESOLVER_DOCS, check if any story doc links to it. If no story references it, it is an orphan.
5. **Invalid module references**: Parse MODULE_METADATA JSON. For each resolver doc, extract the module and command/query it calls. Verify the module name exists in MODULE_METADATA and the command/query name appears in that module's `docs.command` or `docs.query` array. Report any mismatches.

## Common Gap Patterns

- **Renamed files**: A doc was renamed but links were not updated, leaving the old target as an orphan
- **Leftover drafts**: Docs created during planning but never linked into the flow
- **Incomplete cleanup**: A flow was removed but its stories/screens/resolvers were not deleted

## Output Format

Return a JSON object:

```json
{
  "check_type": "orphan-detection",
  "app": "{{APP_NAME}}",
  "gaps": [...],
  "inconsistencies": [...],
  "summary": { "total_checks": N, "passed": N, "failed": N, "skipped": N }
}
```

See [parity-report-format.md](parity-report-format.md) for field definitions.