ADR-367: Add architecture doc for Workflow Event Hooks

[jodavis-claude]

Work item

ADR-367 — Author _doc_WorkflowEventHooks.md, a post-implementation architecture doc describing the shipped instructions: config mechanism, the per-pipeline-state EVENT_NAME table, and the run-event-hooks execution model that Workflow Event Hooks (ADR-360 through ADR-366) actually built.

Changes

• Added _doc_WorkflowEventHooks.md (repo root), written per write-repo-documentation conventions: starts with a Summary: line, contains only the five allowed sections in order (Overview, Responsibilities & Boundaries, Key Design Decisions, Key Classes / Interfaces, Data Flow).
  • Overview covers the instructions: config section (event name → ordered label: instruction map) that replaces the old git-repo.commit/.push/.create-pr/.promote-pr blocks, and run-event-hooks as the mechanism that executes them.
  • Responsibilities & Boundaries mirrors the spec's boundaries that still hold post-implementation (state machine unchanged, per-component commit granularity unchanged, hooks are pipeline-only).
  • Key Design Decisions states each decision's conclusion (label→instruction map merging via merge_config.py's existing recursive dict-merge, ordering guarantee across config tiers, create-pr staying structural/non-hookable-for-creation-itself, signoff's three parallel children and spec-finding having no EVENT_NAME, ValidateStep's conditional push) and links to source rather than restating implementation detail.
  • Key Classes/Interfaces documents run-event-hooks(event, phase, outcome, context_file), the EVENT_NAME table per Step subclass, and the --event argument on workflow-worker/workflow-script.
  • Data Flow traces the descriptor's "event" field from workflow-orchestrate through to the before/after hook calls in workflow-worker/workflow-script.
• _spec_WorkflowEventHooks.md left in place, unmodified — it persists afterward for harvesting, per its own header and per exit criterion Fix repo structure to match what's expected for marketplace #2.

Design decisions

• Documented the shipped hand-off event name as signoff (not the spec's original hand-off) — confirmed via dev_team.py's HandoffStep.EVENT_NAME, default-config.yaml, and update-project-configuration/SKILL.md, all of which use signoff. This is a deliberate description of what shipped, not an error to reconcile with the spec.
• Compressed the Key Design Decisions section to conclusions-plus-source-links rather than reproducing the spec's longer Context/Decision/Consequences prose, per write-repo-documentation's "no implementation detail, link to source instead" convention.
• No "Related Docs" section — write-repo-documentation's fixed section list doesn't include one; cross-references are inline links within the five allowed sections instead, matching _doc_Projects.md's existing precedent.

Testing completed

None — this is a documentation-only task with no code changes, no unit tests, and no new externally-observable behavior for E2E coverage. scripts/validate.sh was run as part of the pipeline's validation step.

[github-actions]

build-and-test: Python test results

Status: ✅ Passed

Test log

[jodavis-claude]

Reviewed _doc_WorkflowEventHooks.md (the only change in this PR) against the shipped implementation. Summary of verification performed:

• Cross-checked every factual claim against source: Step.EVENT_NAME table (debug/research/implement/validate/create-pr/review/fix/signoff) in dev_team.py, _commit_and_push call sites (only in ValidateStep.handle_results() when no script is configured, and in SignoffStep.get_actions()), HandoffStep's docstring and EVENT_NAME = "signoff", CreatePrStep's unconditional dispatch, FindSpecStep/SignoffStep having no EVENT_NAME. All match exactly.
• Verified run-event-hooks/SKILL.md, workflow-worker/SKILL.md, workflow-script/SKILL.md, final-sign-off/SKILL.md, and work-with-pr/SKILL.md (hand-off operations section) against the doc's Key Classes/Interfaces and Data Flow claims — consistent throughout, including the REVIEW_ASSIGNEE_EMAIL removal.
• Confirmed assets/default-config.yaml only ships push/ensure-pushed as generic defaults, matching the doc's Key Design Decisions claim about the config-tier split.
• Confirmed doc structure follows write-repo-documentation conventions exactly: Summary: line, then only the five allowed sections in the required order, no implementation detail restated (links to source throughout).
• Confirmed _spec_WorkflowEventHooks.md is unmodified by this PR (exit criterion #2) and the new doc exists at the correct location/name (exit criterion #1).
• Checked .editorconfig compliance (UTF-8, LF, trailing final newline) — all good.

No Priority 1-4 issues found. One non-blocking observation: the doc's Key Design Decisions section includes the literal reviewer email (jodasoft@outlook.com) as a worked example of the config-tier split. This isn't new exposure — the same email is already committed in _spec_WorkflowEventHooks.md from an earlier PR — so it's consistent with existing precedent and not a blocker, just flagging for awareness since it's now in the permanent architecture doc as well.

Approving.