Skip to content

epic(governance): establish just-in-time issue sealing, native project metadata sync, and isolated epic branching protocol #12

Closed
2 of 3 issues completed

Description

@nicolasvd

epic(governance): Establish Just-In-Time Issue Sealing, Native Project Metadata Sync, and Isolated Epic Branching Protocol

🎯 1. Vision & Strategic Objectives

  • Mission: Transition the Agentic Android Delivery Kernel from premature, fragmented issue creation to deterministic Just-In-Time (JIT) Sealing, eliminate redundant narrative metadata from markdown bodies, synchronize native GitHub Projects v2 custom fields, and establish an isolated Epic Branching protocol (epic/issue-<id>-<slug>).
  • Core Problem Solved:
    • Eliminates the double-estimation flaw where P1 guessed sizing blind at Step 1.0 before P4 architecture analysis.
    • Eliminates narrative metadata pollution (> **Parent Epic**: #7, ## 🧭 Native Metadata Triad) by utilizing native GitHub Sub-issues (--parent), native milestones, and GraphQL Projects v2 item fields.
    • Protects main from in-flight, partial feature states by isolating Epics into dedicated integration branches (epic/**), with child PRs merging into the Epic branch before a single final release PR lands on main.

🏛️ 2. Architectural Bounds & Invariants

  • Boundary Limits:
    • Operational scripts: scripts/seal-issue.sh, scripts/sync-project-metadata.mjs, scripts/validate-docs.sh.
    • CI Pipeline: .github/workflows/delivery-pipeline.yml (dynamic diffing against ${{ github.base_ref }}).
    • Security & Hook Guards: .agent/hooks/branch-guard.mjs, .agent/hooks/plan-guard.mjs, .agent/hooks/post-merge-dual-sync.sh.
    • Governance & Contracts: AGENTS.md, agent.md, .agent/rules/, .agent/personas/, .agent/templates/, .agent/skills/.
  • WIP Invariant:
    • Macro: Epic issue is In progress throughout the delivery cycle.
    • Micro: Strict WIP = 1 on child tasks (exactly 1 active child branch, at most 1 child PR in review).
  • Quality Airbag: Zero regressions on ./scripts/validate-docs.sh (all byte budgets preserved) and ./scripts/quality-check.sh.

🗺️ 3. Sequential Child Tasks Decomposition DAG

Child issues will be sealed sequentially at their respective Gate 1.4 approval (Zero pre-creation on GitHub):

Seq Child Task Type Diff Target PR Base Target Release Mode
01 feat(tooling): implement deterministic issue sealing script and project metadata sync feat ~200 LOC epic/issue-<epic_id>-... Silent (skip-release)
02 chore(templates): decouple issue forms and templates from narrative metadata chore ~150 LOC epic/issue-<epic_id>-... Silent (skip-release)
03 feat(governance): harden governance rules, hook guards, and CI pipeline for epic branching feat ~280 LOC epic/issue-<epic_id>-... Silent (skip-release)
04 Final Epic PR to main epic Consolidated main Full Release Train

✅ 4. Definition of Done (Epic Level)

  • scripts/seal-issue.sh and scripts/sync-project-metadata.mjs implemented and tested with dry-run and live tests.
  • Templates (4-pillar-spec.md, epic-spec.md) and issue forms purged of narrative metadata.
  • Guards (branch-guard.mjs, plan-guard.mjs) updated to protect epic/* integration branches against direct commits.
  • Post-merge hook dynamically syncs to the PR base ref.
  • CI pipeline (delivery-pipeline.yml) dynamically diffs against ${{ github.base_ref }} and triggers on epic/**.
  • All 3 child tasks successfully merged sequentially into the Epic branch.
  • Final Epic PR squash-merged to main with consolidated commit message closing the Epic and all children.

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions