An AI-augmented systems-engineering methodology, built around the Hatley-Pirbhai (HP) structured-analysis framework from 1988/2000 and the modern AI capabilities of the 2020s. Bringing rigorous systems specification — long the domain of FAA-certified avionics — into reach for any AI-assisted development project.

This repository has two distinct halves:

hatley-pirbhai/
├── PLAN.md                     ← document of record (decisions, tactics, design log)
├── examples/                   ← workshop: dogfood projects developed using the toolkit
│   ├── solar/                  ← Solar Local Stack (Hoymiles + Victron orchestration)
│   └── fishing-rig/            ← AutoFishingRig (automated bite-detection)
├── reference-docs/             ← workshop reading aids (the two HP source PDFs, gitignored)
├── graphify-out/               ← workshop methodology analysis (gitignored)
│
└── toolkit/                    ← THE DELIVERABLE — what ships to practitioners
    ├── README.md
    ├── bootstrap.sh            ← user-space install of uv, d2, mmdc
    ├── pyproject.toml          ← Python project (uv-managed)
    ├── hp_toolkit/             ← model / load / validate / render code
    ├── scripts/                ← render_project.py, check_dictionary.py
    ├── skills/                 ← Claude Code skill files
    └── reference/HP_QUICK_REF.md   ← HP method vocabulary card

• The workshop (everything at the repo root) — design log, dogfood projects, methodology development. This is where the toolkit is built and exercised.
• The toolkit (toolkit/) — the deliverable that ships to practitioners. Python package, scaffolding scripts, skill definitions, reference card.

Given a project's dictionary.yaml — the canonical declaration of every entity, flow, transition, architecture module, ADR, budget, SLO, bounded context, and more — the toolkit:

1. Validates the model (reference integrity, hierarchy consistency, coverage metrics, orphan detection, PSPEC balancing, Stage 5 allocation, modernization cross-references: STRIDE on cross-trust-zone interconnects, TPM vs budget direction, SLO→TPM resolution, ACL routing on cross-context flows, MITRE/CWE/compliance ID format)
2. Renders the model in three notations:
   • Mermaid — .mmd + .svg
   • D2 — .d2 + .svg
   • Cytoscape interactive HTML — clickable, drag-to-rearrange, double-click drill-down navigation between levels
3. Catches drift — the renderer round-trip (dictionary → diagram → diff against hand-written) surfaces inconsistencies the human eye misses

Rendered artifacts span the five HP stages plus a modernization layer:

# 1. Install (user-space; no sudo)
bash toolkit/bootstrap.sh

# 2. Validate an example project
cd toolkit
uv run python -m hp_toolkit.validate ../examples/solar/dictionary.yaml

# 3. Render an example end-to-end (Context + DFD + CSPEC)
uv run python scripts/render_project.py ../examples/solar
uv run python scripts/render_project.py ../examples/fishing-rig

Then open any of the .generated.html files under examples/*/ in a browser to see the interactive workspaces.

• For methodology refresh — toolkit/reference/HP_QUICK_REF.md (60+ HP terms with modern analogs)
• For toolkit usage — toolkit/README.md
• For example projects — examples/solar/ (mature reference) or examples/fishing-rig/ (transferability test)
• For design rationale and lived methodology tactics — PLAN.md

End-to-end rendering pipeline live for both dogfood projects. Both have all 5 HP stages locked + the modernization layer applied (ADRs, design-time budgets + runtime TPMs, SLOs anchored to TPMs, per-leaf observability + V&V, STRIDE on cross-trust-zone interconnects + MITRE/CWE/compliance refs; solar additionally declares 2 bounded contexts + an Anti-Corruption Layer). All generated from each project's dictionary.yaml via the same generic script. Both projects also produce a living portal (project_index.generated.html + collapsible sidebar on every page) and a shareable PDF (project.generated.pdf, ~70–80 pages of cover + TOC + diagrams + sidecars + HP reference). Toolkit transferability has been validated across two genuinely different domains (solar energy orchestration; automated fishing rig). Brownfield ingest pipeline shipped — hp-ingest <codebase> orchestrates 6 LLM subagents over a deterministic Python prep layer to produce a draft dictionary.yaml from an existing codebase; first dogfood target is acme-cp.

Deferred work tracked in PLAN.md > Open Questions: per-level label abbreviation, edge refinement schema, hp-ingest dogfood on acme-cp (next branch), per-context filtered renderer view (hp-render-context), third-project transferability (doorbell), merge-mode for incremental ingest (Q4-deferred v2 feature).