# p4mona Project — Claude Code Governance

## Session Startup Checklist

Run these commands **immediately at the start of every session, before any other work**.

```bash
cd /Users/ttyler/pub/ai/p4mona/ai

p4 -s login -s        # Verify ticket. If expired, stop and ask Tom to refresh.
p4 status             # Should be "No files to reconcile" (see note below).
p4 -s opened          # Should be "File(s) not opened on this client."
p4 -s sync -q         # Get current. Ensure output ends with "exit: 0".
```

If `p4 -s opened` shows any open files, stop and ask before proceeding.

After the checklist, **read the most recent `ai/session-NNN-handoff.md`** to pick up where the previous session left off.

## P4 Versioning Info

P4 is used for version control.

### Working Directory and Workspace

- **Local workspace root:** `/Users/ttyler/pub/ai/p4mona`
- **P4 workspace name:** `bot_Claude_Anthropic.P4MBPro5.p4mona`
- **P4CONFIG file:** `/Users/ttyler/pub/ai/p4mona/.p4config`
- **Active stream:** `//p4mona/dev`
- **P4 server:** Public Depot (see below)

### Version Control Workflow

- Always create a **numbered pending changelist** for work, not the default CL.
- Use `p4 change -o | python3 -c "..."  | p4 change -i` to create/edit CLs programmatically (Python is more reliable than sed for multi-line descriptions).
- Associate file edits with the CL: `p4 edit -c <CL> <file>`.
- The `#review` tag in CL descriptions **must appear on its own tab-indented line** to trigger a code review. Example:

      Implement audit log writer.
      	#review @robert_cowham @tom_tyler

- Check syntax before submitting scripts (`bash -n script.sh`, `python3 -m py_compile`).
- Do `p4 describe -s <CL>` to verify the CL is on the correct workspace before submitting.
- End each session by writing `ai/session-NNN-handoff.md` and submitting it.
- Files that are already versioned must be opened with `p4 edit` before writing. Use `p4 status` if unsure.
- Use P4IGNORE files (named `.p4ignore`) as needed.
- To add a file that is blocked by P4IGNORE, use `p4 add -I` (capital I) — not `-f`.
- Small, focused CLs are preferred over large ones. CL numbers are unlimited; no need to conserve them.

#### Stream Topology and the `ai/` Folder

The `//p4mona/dev` stream spec contains an **isolate mapping for `ai/...`**:

    isolate ai/...

This means:
- Session handoff files, CLAUDE.md, and other material in `ai/` are versioned normally in the `dev` stream. They cannot be promoted to `//p4mona/main` or to any release stream (e.g. a future `//p4mona/r26.1`) via copy or merge.
- This is intentional: `ai/` is an audit trail and AI session log, not shippable project content.
- `isolate` differs from `exclude`: `exclude` would remove `ai/` from the stream view entirely (files could not be versioned at all). `isolate` keeps files fully versionable in `dev` while preventing them from flowing north.
- When doing end-of-session handoffs, always submit `ai/session-NNN-handoff.md` to `//p4mona/dev` as normal. No special handling is needed — the stream spec enforces the boundary automatically.
- This file (`ai/CLAUDE.md`) is the versioned copy. A symlink at the workspace root (`CLAUDE.md -> ai/CLAUDE.md`) allows Claude Code to auto-load it. The symlink is intentionally unversioned (it matches `CLAUDE*.md` in the parent `.p4ignore`).

#### P4IGNORE Notes

- The parent `.p4ignore` at `/Users/ttyler/pub/ai/` contains `CLAUDE*.md` — use `p4 add -I` if adding any CLAUDE variant file.
- The `.p4ignore` file itself must also be added with `p4 add -I` (P4 treats the P4IGNORE filename as unversionable by default).

#### Version File

The project version is tracked in `//p4mona/dev/Version` (later to be promoted to
`//p4mona/main`, etc.). The format follows the convention used by other Perforce Software projects:

```
Rev. p4mona/MultiArch/2026.1/32549 (2026/04/08).
```

Fields: `Rev. <Project>/<Platform>/<Release>/<CL> (<Date>).`

Update the Version file as part of any release promotion to `main`. Tom manages this file manually; the agent should not modify it unless explicitly asked.