# .cursorrules
This project uses Forge for mechanical context. Before starting any task:
1. Call forge_project_status(project_path) to orient
2. Call forge_context(section=tasks) for current scope
3. Call forge_verify before and after any changes
4. All constraints are in forge_context(section=constraints)
Do not ask about project structure — query it.

# Forge Project Rules
# Forge is the source of truth for project structure, context, and constraints.
# Do not read files to understand the project — query Forge instead.

## Session Start (required before any task)
1. forge_project_status(project_path) — orient, ~20 tokens
2. forge_context(section=tasks) — current scope only if needed
3. forge_context(section=constraints) — rules that apply to this project

## During Work
- forge_verify(target=staged) after every file change — non-negotiable
- forge_impact_check(changed_files=[...]) after any structural change
- forge_context(section=<x>) to answer "how does X work here" — do not guess
- forge_scaffold(describe="...") to add new nodes — do not create files manually

## What NOT to do
- Do not read manifest.yaml directly — query it via forge_context or forge_manifest
- Do not assume project structure — forge_project_status first, always
- Do not create files without scaffolding them through forge_scaffold
- Do not add hardcoded values — check forge_context(section=constraints) first
- Do not use forge_context() with no section — it returns a directory, not content

## Constraints shorthand
- C001: No if/elif chains on project type strings outside ProjectFactory
- C002: dashboard/ imports only BaseProject
- C003: checkers/ are stateless pure functions
- C005: All secrets use env: prefix
- Full constraints: forge_context(section=constraints)

## Forge MCP is a wrapper for CLI
Every forge_* tool call has a CLI equivalent.
If a tool call fails, the CLI command is the fallback.

## project_path
Always absolute or ~/. Never relative.
Forge projects: ~/Projects/forge
Pixionary: ~/Projects/pixionary
LifeOS apps: ~/Projects/lifeos/<app>

## Three-layer orientation (Forge mental model)
1. **Session / evidence (short)** — EGMP under `cowork/audit/sessions/`, gate notes, scratch. For *this pass* and proof, not the long-lived structural backlog.
2. **Machine truth (long)** — `manifest.yaml`, `docs/change-impact.yaml`, accepted ADRs. Contracts and decisions.
3. **Debt / map overlay (medium)** — `.forge-annotations.yaml` sidecars, `forge audit annotate`. Path-indexed backlog the map can attach to.

## Triangulation (roadmap / “triple graph” read)
Treat three views as peers and diff them when reconciling direction:
- **Declared structure** — `forge map` / manifest graph (`build_manifest_graph`).
- **Policy vs edits** — `forge verify` + `forge impact-check` (change-impact rules on diffs).
- **Bottom-up / audit** — `forge audit map` bundle + scan artifacts when you need reality vs manifest drift.

Markdown handbooks are narrative mirrors; prefer regenerating **map** and querying **manifest + annotations** for mechanical truth.

## Phase ritual (end of milestone or weekly)
Run: `forge --help` (CLI surface drift), `forge doctor`, `forge audit annotate list --help` / list open debt, then `forge verify` or `forge impact-check` after substantive edits. Optionally `forge audit map take --help` when working the audit map layer.