@pareto4/pp-core 1.8.2 → 1.9.0

package/pp-core/workflows/discovery-to-build/steps/architecture-deliverables.md

@@ -0,0 +1,250 @@
+# Architecture Deliverables — arc42-lite generation (D-13/D-14/D-15/D-16)
+
+> **Lazily-loaded.** Read this file from `pp-core/workflows/discovery-to-build.md`
+> at Step 5h, once all sessions are synthesized (after the `_pp-handoff.md`
+> synthesis and the `.planning/PROJECT.md` / `REQUIREMENTS.md` / `ROADMAP.md`
+> generation steps have run). It is not `@`-imported and is not measured by
+> `tests/workflow-size-budget.test.cjs` (`listWorkflowStems()` is
+> non-recursive) — this is the sanctioned progressive-disclosure escape hatch
+> for a DEFAULT-tier workflow file, not a workaround.
+>
+> Purpose: answers Finaps finding #9 — the client gets a real architect-grade
+> handoff, not just process state. This step is factored on purpose so it can
+> be re-run standalone later if Discovery sessions change, without touching
+> the main `discovery-to-build.md` flow.
+
+## What this step produces
+
+Two deliverables, both written under the client project's `docs/` tree —
+**never** under `.planning/`, which stays process-state only:
+
+1. `docs/architecture/architecture.md` — one arc42-lite document with four
+   sections: Introduction & Goals, Context, Containers, Data Model.
+2. `docs/architecture/adr/NNNN-title.md` — one file per row of Session 5's
+   Architecture Decision Records table.
+
+## Source of truth
+
+All content comes from `.planning/discovery/session-05.md` (Session 5:
+Application & Integration Architecture) plus the following facts already
+captured elsewhere in the synthesis:
+
+- **Introduction & Goals** — `.planning/PROJECT.md`'s core problem statement
+  (from Session 1) plus Session 5's stated architecture goals/constraints.
+- **Context (C4Context)** — Session 5's Integration Points Map plus Session 8
+  (external systems, direction, protocol) for `System_Ext`/`Rel` actors.
+- **Containers (C4Container)** — Session 5's Component Inventory and
+  Technology Stack table for `Container`/`ContainerDb` nodes.
+- **Data Model (erDiagram)** — Session 5's Domain Model / Entity Register
+  table (D-16: entity, key attributes, relationships, owner module).
+- **ADRs** — Session 5's Architecture Decision Records table
+  (`ADR ID | Title | Context | Decision | Consequences | Status`).
+
+Never invent facts that are not present in the session content. If a Session
+5 table is missing or a row is empty, note the gap in the relevant section
+(`[not captured in Discovery]`) rather than fabricating architecture detail.
+
+## Path safety (extends T-04-03)
+
+The same discipline `discovery-sprint.md` already applies to
+`.planning/discovery/` writes applies here to `docs/architecture/` writes:
+
+- All write targets MUST be relative paths under `docs/architecture/`
+  (`docs/architecture/architecture.md`, `docs/architecture/adr/NNNN-title.md`).
+- Never write to an absolute path.
+- Never write to a path containing `..`.
+- The only read target for this step is `.planning/discovery/session-05.md`
+  (plus the already-loaded synthesis context) — never read or write outside
+  `docs/architecture/` and `.planning/discovery/`.
+
+## Idempotent overwrite handling
+
+Before writing, check whether `docs/architecture/` already exists (a prior
+partial run, or a client's hand-authored architecture doc). Follow the same
+"replace an existing block if present, otherwise append" precedent already
+used for the CLAUDE.md injection in `discovery-to-build.md` Step 6b:
+
+- If `docs/architecture/architecture.md` exists and contains a section with
+  the exact heading being generated (e.g. `## Context`), replace that
+  section's content in place; leave any other client-authored sections
+  untouched.
+- If the file exists but has no matching section, append the new section at
+  the end.
+- If the file does not exist, create it fresh with all four sections.
+- Before overwriting any existing, non-empty `docs/architecture/` content,
+  surface a short confirmation summarizing what will change (section names
+  being replaced, ADR files being added) rather than silently overwriting —
+  mirror the `AskUserQuestion` confirmation shape already used elsewhere in
+  `discovery-to-build.md` (Step 4's handoff review prompt).
+- Apply the same per-file idempotency to each `docs/architecture/adr/NNNN-title.md`:
+  if a file for that ADR's title already exists, treat it as already
+  generated and skip re-writing it rather than duplicating content.
+
+## Generating `docs/architecture/architecture.md`
+
+Write (or patch) the file with exactly these four arc42-lite sections, in
+this order. Each section header below is the literal heading text to emit.
+
+### Section 1: Introduction & Goals
+
+Prose paragraph combining `.planning/PROJECT.md`'s core problem statement
+with any architecture goals/constraints captured in Session 5 (performance
+targets, scalability expectations, build vs. buy decisions, non-negotiable
+constraints). Keep it factual — summarize, do not add architectural opinions
+that were not stated during Discovery.
+
+### Section 2: Context
+
+One paragraph of prose describing the system's boundary and the actors that
+interact with it, followed by a Mermaid `C4Context` block built from Session
+5's Integration Points Map and Session 8's Integrations table. Map each
+external system in Session 8 to a `System_Ext` node, the product itself to a
+`System` node, and each user-facing actor from Session 5/Session 1 to a
+`Person` node. Connect them with `Rel` lines carrying the protocol from
+Session 8's table where known.
+
+Example shape (fill every placeholder from actual captured facts — never
+leave a literal `[System Name]` placeholder in the generated output):
+
+```mermaid
+C4Context
+  Person(client, "Client User", "Uses the system")
+  System(system, "[System Name]", "[one-line description]")
+  System_Ext(ext, "[External System]", "[integration purpose]")
+  Rel(client, system, "Uses")
+  Rel(system, ext, "Integrates with", "REST/webhook")
+```
+
+### Section 3: Containers
+
+One paragraph of prose describing the system's major runtime containers,
+followed by a Mermaid `C4Container` block built from Session 5's Component
+Inventory and Technology Stack table. Map each component to a `Container`
+node (or `ContainerDb` for data stores), naming the technology from the
+Technology Stack table as the container's tech label. Connect containers with
+`Rel` lines describing the call/data relationship.
+
+Example shape (fill every placeholder from actual captured facts):
+
+```mermaid
+C4Container
+  Container(web, "Web App", "[frontend tech]", "[responsibility]")
+  Container(api, "API", "[backend tech]", "[responsibility]")
+  ContainerDb(db, "Database", "[db tech]", "[responsibility]")
+  Rel(web, api, "Calls", "HTTPS/REST")
+  Rel(api, db, "Reads/writes")
+```
+
+### Section 4: Data Model
+
+One paragraph of prose summarizing the domain model, followed by a Mermaid
+`erDiagram` block built directly from Session 5's Domain Model / Entity
+Register table (D-16). Emit one entity per register row and one relationship
+line per captured relationship; use the register's stated cardinality where
+given, otherwise default to the most conservative reading (`||--o{`) and
+note the assumption in prose.
+
+Example shape (fill every placeholder from actual captured facts):
+
+```mermaid
+erDiagram
+  ORDER ||--|{ LINE_ITEM : contains
+  CUSTOMER ||--o{ ORDER : places
+```
+
+### Rendering honesty note (mandatory, Pitfall 4)
+
+Immediately after the Data Model section (or as a closing note at the end of
+the document), include one prose line stating plainly:
+
+> C4 diagrams (`C4Context`, `C4Container`) render on GitLab and Obsidian
+> natively. GitHub's bundled Mermaid renderer does not yet include the C4
+> extension, so these blocks display as a readable code fence rather than a
+> rendered diagram there — the `erDiagram` block renders on all three
+> platforms. This is a platform limitation, not a defect in this document.
+
+Do not claim uniform rendering across GitHub/GitLab/Obsidian anywhere else in
+the generated document. All diagram source in this file is embedded Mermaid
+text — no PlantUML, no committed image exports (D-15).
+
+## Generating `docs/architecture/adr/NNNN-title.md`
+
+For each row of Session 5's Architecture Decision Records table, write one
+file at `docs/architecture/adr/NNNN-title.md`, where `NNNN` is a
+zero-padded, sequential number starting at `0001` (following pp-core's own
+`docs/adr/NNNN-title.md` numbering precedent — do not reuse pp-core's own
+ADR numbers, this is a separate sequence in the client's `docs/` tree) and
+`title` is the ADR's title, slugified (lowercase, spaces to hyphens, no
+punctuation).
+
+Each file follows the exact header shape of pp-core's own
+`docs/adr/0011-review-default-reviewers.md`: a `# Title` line, a
+`- **Status:**` / `- **Date:**` field block, prose Context, then
+`## Decision`, `## Consequences`, `## References` sections.
+
+Field mapping from the Session 5 ADR table row to the file:
+
+| ADR table column | File field |
+|-------------------|------------|
+| Title | `# {Title}` (H1 heading) |
+| Status | `- **Status:** {Status}` — default to `Accepted` if the row leaves Status blank; use the row's stated value otherwise |
+| (session completion date) | `- **Date:** {session-05 completion date}` — read from `.planning/discovery/session-05.md`'s own status/completion metadata, or `.planning/discovery/_progress.md`'s Session 5 `Completed` column |
+| Context | Prose paragraph expanding the Context column's content (do not just paste the table cell verbatim if it is telegraphic — write it as a short paragraph while preserving the original meaning) |
+| Decision | `## Decision` section body |
+| Consequences | `## Consequences` section body |
+| — | `## References` section: `- Source: \`.planning/discovery/session-05.md\` — Architecture Decision Records table, {ADR ID}` |
+
+Example shape:
+
+```markdown
+# [ADR Title from Session 5 table]
+
+- **Status:** Accepted
+- **Date:** [session completion date]
+
+[Context column content, expanded to prose]
+
+## Decision
+
+[Decision column content]
+
+## Consequences
+
+[Consequences column content]
+
+## References
+
+- Source: `.planning/discovery/session-05.md` — Architecture Decision Records table, [ADR ID]
+```
+
+If Session 5's ADR table has no rows (architecture decisions not yet
+captured), skip `docs/architecture/adr/` entirely rather than generating
+empty placeholder files, and note the gap in `architecture.md`'s
+Introduction & Goals section.
+
+## Completing the step
+
+1. Create `docs/architecture/` and `docs/architecture/adr/` directories as
+   needed (they do not exist in a fresh client project).
+2. Write `docs/architecture/architecture.md` per the section instructions
+   above, applying the idempotent replace-or-append rule.
+3. Write one `docs/architecture/adr/NNNN-title.md` per Session 5 ADR row,
+   skipping any that already exist (idempotent).
+4. Commit the generated files. This step is the SOLE committer of
+   `docs/architecture/` — `discovery-to-build.md` Step 5h does not commit
+   these files itself, so this block inlines the canonical `pp_run`
+   resolver unconditionally, exactly as every other workflow file does.
+   The resolver is idempotent, so redefining `pp_run` when a caller has
+   already defined it is harmless:
+
+```bash
+_PP_SHIM_NAME="pp-tools.cjs"; _PP_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; PP_TOOLS="${_PP_RUNTIME_ROOT}/pp-core/bin/${_PP_SHIM_NAME}"; if [ -f "$PP_TOOLS" ]; then pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${_PP_RUNTIME_ROOT}/.claude/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${_PP_RUNTIME_ROOT}/.claude/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${_PP_RUNTIME_ROOT}/.codex/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${_PP_RUNTIME_ROOT}/.codex/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif command -v pp-tools >/dev/null 2>&1; then PP_TOOLS="$(command -v pp-tools)"; pp_run() { "$PP_TOOLS" "$@"; }; elif [ -f "$HOME/.claude/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="$HOME/.claude/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${HERMES_HOME:-$HOME/.hermes}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${HERMES_HOME:-$HOME/.hermes}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${CURSOR_CONFIG_DIR:-$HOME/.cursor}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CURSOR_CONFIG_DIR:-$HOME/.cursor}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${CODEX_HOME:-$HOME/.codex}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CODEX_HOME:-$HOME/.codex}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${GEMINI_CONFIG_DIR:-$HOME/.gemini}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${GEMINI_CONFIG_DIR:-$HOME/.gemini}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${COPILOT_CONFIG_DIR:-$HOME/.copilot}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${COPILOT_CONFIG_DIR:-$HOME/.copilot}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${AUGMENT_CONFIG_DIR:-$HOME/.augment}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${AUGMENT_CONFIG_DIR:-$HOME/.augment}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${TRAE_CONFIG_DIR:-$HOME/.trae}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${TRAE_CONFIG_DIR:-$HOME/.trae}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${QWEN_CONFIG_DIR:-$HOME/.qwen}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${QWEN_CONFIG_DIR:-$HOME/.qwen}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${CLINE_CONFIG_DIR:-$HOME/.cline}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CLINE_CONFIG_DIR:-$HOME/.cline}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${GROK_AGENTS_HOME:-$HOME/.agents}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${GROK_AGENTS_HOME:-$HOME/.agents}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; else echo "ERROR: pp-tools.cjs not found at $PP_TOOLS and pp-tools is not on PATH. Run: npx -y @pareto4/pp-core@latest --claude --local" >&2; exit 1; fi; if [ -n "${CLAUDE_ENV_FILE:-}" ] && [ -n "${PP_TOOLS:-}" ]; then printf "export PATH='%s':\"\$PATH\"\n" "${PP_TOOLS%/*}" >> "$CLAUDE_ENV_FILE" 2>/dev/null || true; fi
+
+FILES="docs/architecture/architecture.md"
+ls docs/architecture/adr/*.md >/dev/null 2>&1 && FILES="$FILES docs/architecture/adr/*.md"
+pp_run commit "docs: generate architect-grade handoff (arc42-lite architecture + ADRs)" --files $FILES
+```
+
+5. Return control to `discovery-to-build.md`'s Step 5h caller — this step
+   does not prompt for further user input beyond the overwrite confirmation
+   above (if triggered).