# Session 002 Handoff — P4Sudo Project

**Date:** 2026-04-07
**Bot user:** bot_Claude_Anthropic
**Workspace:** bot_Claude_Anthropic.P4MBPro5.p4sudo
**Stream:** //p4sudo/dev

---

## Session Summary

This session focused on design and documentation for P4Sudo — no code was
written yet. The major deliverables were:

1. **UC-001 captured** — Bootstrap Black Belt INFO.md on PPN (CL 32526 / 32528)
2. **mkblackbelt.ui.yaml** — Web form definition for the mkblackbelt command (CL 32528)
3. **p4sudo.cfg.example updated** — Added `ui_def` key docs and mkblackbelt entry (CL 32528)
4. **Broker REWRITE reference files** — CBD project examples added to `doc/broker-rewrite-reference/` (this CL)
5. **ai/CLAUDE.md rewritten** — Full governance document covering server topology, bot ticket management, version control workflow, P4Sudo architecture, dev infrastructure status (this CL)

---

## Changelists This Session

| CL | Description | Status |
|----|-------------|--------|
| 32526 | Add UC-001 use-cases.md (initial draft) | Submitted |
| 32528 | Update use-cases.md (Q1-Q6 resolved); add mkblackbelt.ui.yaml; update p4sudo.cfg.example | Submitted |
| 32530 | Governance: rewrite CLAUDE.md; add broker-rewrite-reference/; add this handoff | **Submitted this session** |

---

## What Was Accomplished

### UC-001: Bootstrap Black Belt INFO.md

The full use case for `mkblackbelt` is now documented in `doc/use-cases.md`:

- 9-step workflow (validate → fetch template → provision depot → provision
  stream → create ephemeral workspace → instantiate INFO.md → submit →
  delete ephemeral workspace → update CustomerIndex.md)
- All 25 substitution tokens inventoried against the PPN INFO.md template
- CustomerIndex.md row format documented
- Web UI field table documented
- All open design questions Q1–Q6 resolved:
  - Q1: Keep rows with empty optional tokens (empty string substitution)
  - Q2: No automated CustomerTag validation at this time
  - Q3: Persistent `p4sudo-svc.blackbelt` workspace is a manual pre-setup step; documented in Admin Guide
  - Q4: Retry-once on CustomerIndex.md submit conflict
  - Q5: Template updated by Tom; both date tokens use `__EDITME_YYYY_MM_DD__`
  - Q6: Swarm URL format confirmed as `https://ppn.perforce.com/files/<CustomerTag>/main/BlackBelt/INFO.md`

### mkblackbelt.ui.yaml

Per-command YAML web form definition for `mkblackbelt`, with:
- 4 sections: Customer Identity, Program Dates & Licensed Seats,
  Customer Contacts, P4 Staff Contacts
- All field types defined (`word`, `line`, `url`, `email`, `date`,
  `integer`, `select`)
- Required vs. optional flags on each field
- Token mappings for INFO.md template substitution
- `token: null` for CustomerIndex-only fields (Tier, CommsChannel, IndexNotes)
- `auto_fields` section for `__EDITME_YYYY_MM_DD__` (set to today at runtime)

### Broker REWRITE Reference

Four files from the CBD (Component Based Development) project added to
`doc/broker-rewrite-reference/` as concrete examples of the p4broker
REWRITE/filter feature. The `README.md` in that directory documents:
- Broker config pattern (`action = filter; execute = ...`)
- stdin field inventory (`command`, `workspace`, `cwd`, `user`,
  `clientIp`, `brokerTargetPort`, `argCount`, `Arg0`…`ArgN`)
- Output protocol (PASS / REJECT / REWRITE / custom output)
- Python and bash parsing patterns
- Key broker constraints (no interactive prompts, all output buffered)
- How P4Sudo uses the filter feature

### Governance (CLAUDE.md)

`ai/CLAUDE.md` rewritten as a durable reference. Now covers:
- Session startup checklist (login check, status, opened, switch, sync)
- Both P4 servers: Public Depot (default) and PPN (`.p4config.ppn`)
- PPN server topology diagram (ppn-p4d-01, ppn.perforce.com DMZ,
  ppn-p4d-02, new Ubuntu 24.04 app server)
- DLP notes (broker policy, not p4d; not applicable to :1671)
- Bot user and ticket management notes
- Version control workflow
- P4Sudo architecture diagram
- Dev infrastructure status table
- Project file locations table

---

## Dev 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 |

---

## Action Items for Tom

1. **AWS Security Group change** — Open port :1671 on `ppn.perforce.com`
   (internal AWS network only, not public internet). This unblocks drafting
   the P4Sudo broker config.

2. **Provision new Ubuntu 24.04 EC2** — In the same AWS account as the
   PPN fleet. This will host the P4Sudo web app.

3. **Generate bot ticket** before starting each session (`p4 -u bot_Claude_Anthropic login`
   on a machine that has the P4 ticket). Tickets expire every ~24 hours.

---

## Next Session: Where to Pick Up

1. **If dev infrastructure is still pending:** Draft `p4sudo.sh` (the core
   dispatcher) and `p4sudo.cfg` config parser in Python or bash.
   This can be written and tested locally before deploying to PPN.

2. **If port :1671 is open:** Draft `p4broker-p4sudo.conf` (the broker config
   for the P4Sudo broker on :1671), then deploy and verify the filter
   intercept works before writing `p4sudo.sh`.

3. **Recommended next coding task:** `p4sudo.sh` dispatcher — reads broker
   stdin, validates the requesting user is not `p4sudo-svc`, parses
   `p4sudo.cfg`, checks authorization rules, dispatches to command script
   or rejects. This is the heart of the system.

---

## Files of Interest

| Path | Notes |
|------|-------|
| `ai/CLAUDE.md` | Full governance — read at session start |
| `doc/use-cases.md` | UC-001 (mkblackbelt) fully documented |
| `doc/mkblackbelt.ui.yaml` | Web form definition |
| `doc/p4sudo.cfg.example` | Annotated config reference |
| `doc/broker-rewrite-reference/README.md` | Broker filter protocol reference |
| `doc/broker-rewrite-reference/Cbd.py` | Full REWRITE example (CBD project) |