# P4Sudo Project — Claude Code Governance ## Pleasantries Greetings, Claude! --- ## Session Startup Checklist Run these commands at the start of every session. Use `cd` to ensure commands run from the p4sudo workspace root so the correct `.p4config` is picked up. ```bash cd /Users/ttyler/pub/ai/p4sudo 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 switch -l # Confirm active stream (should be "dev *"). p4 -s sync -q # Get current. Ensure output ends with "exit: 0". ``` **Note on `p4 status`:** The file `.claude/settings.local.json` may appear as needing reconciliation. This is expected and intentional — defer the decision on versioning it to Tom at the start of the session. If `p4 -s opened` shows any open files, stop and ask Tom before proceeding. **Always use `cd /Users/ttyler/pub/ai/p4sudo &&` as a prefix on every bash command** — the shell resets its working directory between tool calls, so the `.p4config` must be picked up fresh each time. --- ## Current Task Read the latest session handoff file in `ai/` (highest-numbered `session-NNN-handoff.md`) to understand current project status, what was accomplished last session, and what to do next. --- ## Governance ### Working Directory and Workspace - **Local workspace root:** `/Users/ttyler/pub/ai/p4sudo` - **P4 workspace name:** `bot_Claude_Anthropic.P4MBPro5.p4sudo` - **P4CONFIG file:** `/Users/ttyler/pub/ai/p4sudo/.p4config` - **Active stream:** `//p4sudo/dev` - **P4 server:** Public Depot (see below) This is a **Streams workspace**. The client view is generated from the stream spec and cannot be edited directly in the client spec. To change the view, the stream spec must be edited. Use `p4 switch -l` to see available streams. --- ### P4 Servers Two P4 servers are relevant to this project. #### 1. Public Depot (default for this workspace) | Property | Value | |----------|-------| | P4PORT | `54.241.106.223:1666` | | Official hostname | `public.perforce.com:1666` | | P4CONFIG | `.p4config` (default) | | Access | Public, accessible from anywhere | | Purpose | Open-source P4Sudo framework code | The IP address is used instead of the hostname as a workaround for DNS issues caused by the corporate VPN. #### 2. PPN (Perforce Partner Network) | Property | Value | |----------|-------| | P4PORT | `ssl:50.18.77.74:1670` | | Official hostname | `ssl:ppn.perforce.com:1670` | | P4CONFIG | `.p4config.ppn` | | Access | Private; accessible from anywhere via broker/Swarm, SSH only from VPN | | Purpose | Black Belt program customer data; P4Sudo command deployment | To run a single command against PPN without changing the default P4CONFIG: ```bash p4 -E P4CONFIG=.p4config.ppn ``` To verify PPN login: ```bash cd /Users/ttyler/pub/ai/p4sudo && p4 -E P4CONFIG=.p4config.ppn -s login -s ``` --- ### PPN Server Topology The PPN service involves three server machines: ``` INTERNAL AWS NETWORK ┌──────────────────────────────────────────────────────────────┐ │ │ │ ppn-p4d-01 (Ubuntu 20.04) │ │ └─ p4d :1666 (internal/VPN only) ← primary p4d │ │ │ │ ppn.perforce.com (Ubuntu 20.04, DMZ) │ │ ├─ p4broker :1670 (external-facing) ← production broker │ │ │ └─ DLP rules enforced here (see below) │ │ ├─ p4broker :1671 (internal only) ← P4Sudo broker (TBD) │ │ │ └─ no DLP rules; calls P4Sudo scripts │ │ └─ Swarm / Apache (external-facing, P4 Code Review UI) │ │ │ │ ppn-p4d-02 (Ubuntu 20.04) │ │ └─ standby replica of ppn-p4d-01 ← ignore for now │ │ │ │ new-app-server (Ubuntu 24.04, to be provisioned) │ │ └─ P4Sudo web app (internal-facing) │ │ │ └──────────────────────────────────────────────────────────────┘ │ │ DMZ exposes :1670 (broker) and :443 (Swarm) externally │ :1671 (P4Sudo broker) stays internal-network only ``` - **ppn-p4d-01:** The production P4D. Internal/VPN access only. Safe to target for P4 operations (creating depots, editing text files). - **ppn.perforce.com:** DMZ machine running the production broker (:1670), Swarm, and eventually the P4Sudo broker (:1671). Mission-critical — do not risk the production broker. - **ppn-p4d-02:** Standby replica. Ignore for now. P4Sudo scripts live on the broker machine, so a `p4 failover` of p4d has no impact on script deployment. **SSH access to ppn.perforce.com** requires being on the corporate VPN (port 22 is internal-only). The broker port :1671 will also be internal-only. --- ### DLP (Data Leakage Protection) on PPN DLP rules are enforced **in the production broker config (port :1670)** — they are a broker policy, not a p4d server feature. The P4Sudo broker (port :1671) has its own separate config with **no DLP rules**. Internal users connecting through :1671 get an unrestricted view. **Known DLP behaviors on :1670 (for reference only — not relevant to :1671):** - `p4 users` is blocked unless you are a super user (classified as oversharing) - `p4 clients` is rewritten to show only the requesting user's own workspaces When running commands against PPN during development, prefer :1671 (once available) to avoid hitting these restrictions. --- ### Bot User and Ticket Management - **Bot P4 username:** `bot_Claude_Anthropic` - Tickets expire regularly (typically 24 hours). Always check at session start. - If the ticket has expired, **stop and ask Tom to refresh it** — the bot cannot refresh its own ticket non-interactively. - This applies to both the Public Depot and PPN connections independently. - Tom has noted that generating the ticket before starting the agent is easy to forget — a note in Tom's own runbook would help. --- ### Version Control Workflow - Always create a **numbered pending changelist** for work, not the default CL. - Use `p4 change -o | sed '...' | p4 change -i` to create CLs programmatically. - Always associate file edits with the CL: `p4 edit -c `. - End each changelist description with `#review @robert_cowham @tom_tyler`. - Check syntax before submitting scripts (`bash -n script.sh`, `python3 -m py_compile`). - Do `p4 describe -s ` to verify the CL is on the correct workspace before submitting. - End each session by writing a session handoff file and submitting it. - Files that are already versioned must be opened with `p4 edit` before writing. #### Stream Topology and the `ai/` Folder The `//p4sudo/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 `//p4sudo/main` or to any release stream (e.g. a future `//p4sudo/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 `//p4sudo/dev` as normal. No special handling is needed — the stream spec enforces the boundary automatically. #### Version File The project version is tracked in `//p4sudo/dev/Version` (and promoted to `//p4sudo/main`). The format follows the convention used by other Perforce software projects: ``` Rev. P4Sudo/MultiArch/2026.1/32549 (2026/04/08). ``` Fields: `Rev. /// ().` Update the Version file as part of any release promotion to `main`. Tom manages this file manually; the bot should not modify it unless explicitly asked. --- ### P4Sudo Project Architecture P4Sudo gives non-super P4 users access to privileged or site-defined operations via a controlled, audited mechanism modeled on Unix `sudo`. It is implemented using the p4broker filter/REWRITE feature. ``` User (CLI or web) │ p4 sudo ▼ p4broker :1671 (ppn.perforce.com, internal) │ action = filter; execute = p4sudo.sh ▼ p4sudo.sh (dispatcher) ├─ reads broker stdin (user, workspace, args) ├─ checkauth (verify valid ticket) ├─ reads p4sudo.cfg (authorization rules) └─ dispatches to command script OR rejects │ ▼ mkblackbelt.sh / mkproj.sh / etc. │ runs as p4sudo-svc (service account) └─ operates against ppn-p4d-01 ``` **Key files (deployment on ppn.perforce.com):** | Path | Purpose | |------|---------| | `/p4/common/site/p4sudo/p4sudo.sh` | Core dispatcher (called by broker) | | `/p4/common/site/config/p4sudo.cfg` | Authorization rules | | `/p4/common/site/p4sudo/commands/` | Site-defined command scripts | | `/p4/common/site/p4sudo/commands/*.ui.yaml` | Web form definitions | | `/p4/common/site/p4sudo/logs/` | Operational and audit logs | | `/p4/1/broker/p4broker-p4sudo.conf` | P4Sudo broker config (:1671) | **Service account:** `p4sudo-svc` — holds minimum necessary P4 permissions, must not appear in `p4sudo.cfg` rules, needs a non-expiring broker-side ticket. **Persistent workspace:** `p4sudo-svc.blackbelt` — pre-created on PPN, mapped to `//BlackBelt/main`, used by `mkblackbelt.sh` to update `CustomerIndex.md`. Root directory must exist on `ppn.perforce.com`. To be set up manually as part of P4Sudo deployment; document in Admin Guide. For the p4broker REWRITE feature, see `doc/broker-rewrite-reference/README.md`. --- ### Development Infrastructure Status | Component | Status | Notes | |-----------|--------|-------| | P4Sudo broker :1671 on ppn.perforce.com | **Pending** | Needs AWS Security Group change (internal-only) | | New Ubuntu 24.04 app server (AWS) | **Pending** | New EC2 in same account as PPN fleet | | `p4sudo-svc.blackbelt` workspace on PPN | **Pending** | Manual setup; document in Admin Guide | | p4broker config for :1671 | **Not started** | Draft after port is opened | | `mkblackbelt.sh` implementation | **Not started** | Next major coding task | | P4Sudo web app | **Not started** | After CLI path is solid | --- ### Project File Locations (Public Depot) All P4Sudo framework code is versioned in `//p4sudo/dev/` on the Public Depot. | Depot path | Local path | Description | |------------|------------|-------------| | `//p4sudo/dev/ai/` | `ai/` | Session logs, CLAUDE.md, handoffs | | `//p4sudo/dev/doc/` | `doc/` | Design documents, examples | | `//p4sudo/dev/doc/broker-rewrite-reference/` | `doc/broker-rewrite-reference/` | CBD example files + REWRITE protocol README |