From 69633f94c37233836676b14cd19c82a4b52f9131 Mon Sep 17 00:00:00 2001 From: NicolasVD Date: Fri, 25 Sep 2026 16:27:22 +0200 Subject: [PATCH] docs(readme): rewrite engineering showcase, JIT sealing protocol, and persona matrix (closes #20) --- .agent/hooks/post-checkout | 2 +- README.md | 244 +++++++++++++++++++++++++++++++------ banner.svg | 126 +++++++++++++++++++ scripts/seal-issue.sh | 4 +- 4 files changed, 340 insertions(+), 36 deletions(-) create mode 100644 banner.svg diff --git a/.agent/hooks/post-checkout b/.agent/hooks/post-checkout index da11998..5b28a94 100755 --- a/.agent/hooks/post-checkout +++ b/.agent/hooks/post-checkout @@ -1,6 +1,6 @@ #!/usr/bin/env bash # ============================================================================== -# Second Brain โ€” Post-Checkout Issue Progress Sync Hook +# Agentic Android Delivery Kernel โ€” Post-Checkout Issue Progress Sync Hook # ============================================================================== # Automatically binds open Milestone, active Cycle, and transitions issue status # to "In Progress" on GitHub Project board when checking out an issue branch. diff --git a/README.md b/README.md index 632e7f4..a00a763 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,17 @@ +

+ Agentic Android Delivery Kernel Banner +

+ +

+ Quality Airbag Status + Jetpack Compose + Roborazzi Visual Regression + License + Micro-Kernel Architecture +

+ +--- + # ๐Ÿ›ก๏ธ Agentic Android Delivery Kernel > **The Deterministic Multi-Agent Governance Protocol for Production Android Apps** @@ -5,19 +19,22 @@ --- -## ๐ŸŒŸ Overview +## ๐ŸŒŸ Executive Overview & Value Proposition Autonomous AI coding agents often derail when given unbounded write access to production codebases: -* **Direct commits on `main` / `master`** bypassing branch reviews. -* **Premature implementation** without sealed product specifications or user consent. -* **Unmonitored merges** and unverified tests causing silent regressions. +* **Direct commits on `main` / `master`** bypassing branch protection and peer review. +* **Premature implementation** without sealed product specifications or human approval. +* **Unmonitored autonomous merges** and unverified tests causing silent regressions. * **Hardcoded UI literals** breaking internationalization and accessibility. +* **Hallucinated dependencies and architectural drift** that degrade repository maintainability. -**Agentic Android Delivery Kernel** is an architectural framework and deterministic micro-kernel (< 10 KB) designed to enforce strict software engineering discipline on AI agents. It orchestrates **6 specialized personas** governed by a sequential state machine with **2 human-in-the-loop blocking gates**. +**Agentic Android Delivery Kernel** is an architectural framework and deterministic micro-kernel (< 10 KB) designed to enforce strict software engineering rigor on AI agents. It orchestrates **6 specialized engineering personas** across a sequential state machine with **2 human-in-the-loop blocking gates**, guaranteeing that no code is written, tested, or released without formal human authorization. --- -## ๐Ÿ›๏ธ Sequential Persona State Machine & Gating Locks +## ๐Ÿ›๏ธ Sequential Persona State Machine & Gating Verification + +The kernel governs agent operations through a strict **3-Phase Deterministic Lifecycle** with an essential **Testing / Quality Airbag** verification step prior to release: ```mermaid flowchart TD @@ -25,18 +42,25 @@ flowchart TD P1["P1: Product Planner\nAnti-duplication & Gherkin User Stories"] --> P2["P2: Design Lead\nM3 Tokens, 4-State UI Matrix"] P2 --> P3["P3: Privacy & Data\nZero-PII, Analytics Taxonomy, GDPR"] P3 --> P4["P4: System Architect\nClean MVI, Boundaries, Epic DAG Decomposition"] - P4 --> Spec["Dual-Write Spec\nGitHub Issue Comment + implementation_plan.md"] + P4 --> Spec["Dual-Write Spec\nLocal implementation_plan.md"] end - Spec --> Gate14{"๐Ÿ›‘ GATE 1.4 : Inception Halt\nExplicit Written Approval\n(Branch Guard active on default branch)"} + Spec --> Gate14{"๐Ÿ›‘ GATE 1.4 : Inception Halt\nExplicit Written Approval\n(Branch Guard active on main & epic/**)"} - subgraph Delivery["Phase 2 ยท Delivery"] - Gate14 -->|Explicit approval| Branch["Dedicated Feature Branch\n/issue--"] + subgraph Sealing["Just-In-Time (JIT) Sealing"] + Gate14 -->|Explicit approval| JIT["JIT Issue Sealer\n./scripts/seal-issue.sh --from-plan\nAtomic GitHub Issue & Project v2 Sync"] + end + + subgraph Delivery["Phase 2 ยท Construction & Delivery"] + JIT --> Branch["Dedicated Feature Branch\n/issue-- (WIP = 1)"] Branch --> P5["P5: Software Engineer\nTDD & Strict Compose Implementation\nZero Hardcoded Strings (strings.xml)"] - P5 --> Airbag["๐Ÿ›ก๏ธ Quality Airbag\n./scripts/quality-check.sh\n(codeSanityCheck + Lint + Roborazzi)"] end - subgraph Release["Phase 3 ยท Release"] + subgraph Testing["Testing & Verification"] + P5 --> Airbag["๐Ÿ›ก๏ธ Quality Airbag\n./scripts/quality-check.sh\n(codeSanityCheck + Lint + Roborazzi)\n& ./scripts/validate-docs.sh (38 Contracts)"] + end + + subgraph Release["Phase 3 ยท Release & Observability"] Airbag -->|100% green checks| P6["P6: Release Manager\nGit Push & Open PR Walkthrough"] P6 --> Gate35{"๐Ÿ”’ GATE 3.5 : Auto-Merge Lock\nHuman Authorization Required\n('Tu peux merger')"} Gate35 -->|Written confirmation| Merge["Squash Merge & Dual-Sync\nKanban Closure & Branch Pruning"] @@ -45,26 +69,131 @@ flowchart TD style Gate14 fill:#ff4d4f,stroke:#333,stroke-width:2px,color:#fff style Gate35 fill:#ff4d4f,stroke:#333,stroke-width:2px,color:#fff style Airbag fill:#52c41a,stroke:#333,stroke-width:2px,color:#fff + style JIT fill:#1890ff,stroke:#333,stroke-width:2px,color:#fff ``` +### The 3 Core Lifecycle Phases + +1. **Phase 1 โ€” Inception Consortium (Personas 1โ€“4)**: + - **Persona 1 (Product Planner)** executes an anti-duplication query via `GitHubMCP:search_issues`. + - The Consortium drafts a formal 4-Pillar Specification in the local `implementation_plan.md` artifact. + - Persona 4 consolidates sizing (`XS` to `XL`) and estimates before sealing. + - **Gate 1.4 Verification (STOP & WAIT)**: Strict halt. Zero branches, code edits, or premature GitHub issues before explicit written approval. + - Upon Gate 1.4 approval: `./scripts/seal-issue.sh --from-plan` seals the tracking issue assigned to `@me` with native flags (`--milestone`, `--parent`), associates Project v2 fields (`Priority`, `Size`, `Estimate`, `Status: Ready`), and initializes integration branches if Epic. + +2. **Phase 2 โ€” Construction & Delivery (Persona 5)**: + - Activated **strictly after** Gate 1.4 approval and JIT sealing. + - P5 cuts a dedicated branch `/issue--` from default branch or active Epic branch (`WIP = 1`). + - Production implementation adheres to Clean MVI architecture, strict Compose theming, and zero hardcoded literals. + - **Testing / Quality Airbag**: Execution of `./scripts/quality-check.sh` (`codeSanityCheck`, Android Lint debug/release, Roborazzi visual regressions) and `./scripts/validate-docs.sh` (38 documentation contracts). + +3. **Phase 3 โ€” Release & Observability (Persona 6)**: + - Activated after all Quality Airbag assertions pass 100% green. + - Persona 6 pushes the branch and opens a Pull Request with a structured Walkthrough via `GitHubMCP:create_pull_request`. + - PR targets `epic/**` with `skip-release` for intermediate child tasks; targets `main` for standalone or consolidated Epic releases. + - **Gate 3.5 โ€” Zero Auto-Merge Lock**: Strict halt with PR link. Merges exclusively after explicit user confirmation (*"Tu peux merger"*). + - Executes squash merge, runs `.agent/hooks/post-merge-dual-sync.sh` (dynamically synchronizing base branch), and prunes branches. + +### Conditional Persona 2 Design Gate + +Pillar 1 (Design Spec) enforcement is contextual and adaptive: +* **UI & Composable Changes**: **Persona 2 (Design Lead)** must define Material 3 tokens (from [`DESIGN.md`](DESIGN.md)), 4-state UI matrix (`Loading`, `Empty`, `Error`, `Content`), and Roborazzi expectations. +* **Non-UI Changes**: For backend, Room, CI/CD, scripts, or doc chores, Pillar 1 is explicitly marked: `N/A โ€” No visual/UI changes`. +* **Explicit User Override**: If prompt requests to skip design (*"skip design"*, *"sans design"*), P2 is immediately bypassed. + --- -## ๐Ÿ‘ฅ The 6 Engineering Personas +## ๐Ÿ‘ฅ The 6 Engineering Personas & Principle of Least Privilege (PoLP) -| Persona | Role | Key Deliverable | Tools Allowed / Denied | -|---|---|---|---| -| **P1 ยท Product Planner** | Product Management | Sealed Issue, Gherkin User Stories, 3-State Access Matrix | Read & GitHub issues only. **No code.** | -| **P2 ยท Design Lead** | UI/UX & Design Tokens | Material 3 tokens (`DESIGN.md`), 4-state UI matrix, Roborazzi specs | Design specs & assets. | -| **P3 ยท Privacy & Data** | Compliance & Telemetry | Zero-PII analytics taxonomy (`docs/analytics-taxonomy.md`), GDPR | Telemetry & data models. | -| **P4 ยท System Architect** | Architecture & Tech Lead | Clean MVI boundaries, DAG Epic decomposition (< 300 LOC) | Read-only verification. **No code.** | -| **P5 ยท Software Engineer** | Senior Android Developer | Production Kotlin/Compose code, atomic commits, TDD | Writes strictly in dedicated branch. | -| **P6 ยท Release Manager** | QA & Release Management | Quality Airbag execution, PR Walkthrough, Zero Auto-Merge Lock | PR lifecycle & deployment. | +The kernel divides operational responsibilities into 6 distinct personas. To guarantee security and prevent unintended file modifications, the **Principle of Least Privilege (PoLP)** is enforced at runtime: + +| Persona | Manifest | Role & Deliverables | Metadata Ownership | Shell Execution (`run_command`) | +|---|---|---|---|:---:| +| **P1 ยท Product Planner** | [p1-product-planner.md](.agent/personas/p1-product-planner.md) | Anti-duplication, Gherkin User Stories, 3-State Access Matrix, Milestone hygiene | `Priority`, `Estimate` (co-owner) | โŒ **Revoked** | +| **P2 ยท Design Lead** | [p2-design-lead.md](.agent/personas/p2-design-lead.md) | Material 3 tokens, WCAG AAA compliance, 4-state UI matrix, Roborazzi specs | Pillar 1 Design Spec | โŒ **Revoked** | +| **P3 ยท Privacy & Data** | [p3-privacy-data.md](.agent/personas/p3-privacy-data.md) | Zero-PII telemetry contracts, GDPR/AI Act compliance, event taxonomy | Pillar 2 Data Spec | โŒ **Revoked** | +| **P4 ยท System Architect** | [p4-system-architect.md](.agent/personas/p4-system-architect.md) | Clean Arch, Room DDL, boundary audit, Epic DAG decomposition (< 300 LOC) | `Size` (XSโ€“XL), `Estimate` (co-owner) | โŒ **Revoked** | +| **P5 ยท Software Engineer** | [p5-software-engineer.md](.agent/personas/p5-software-engineer.md) | Kotlin/Compose implementation, Clean MVI, Zero Hardcoded Strings, TDD | Working code, atomic commits | โœ… **Allowed (Dedicated branch only)** | +| **P6 ยท Release Manager** | [p6-release-manager.md](.agent/personas/p6-release-manager.md) | Quality Airbag, PR walkthrough, Milestone release train, Crashlytics sync | PR Lifecycle, Tier 1/2 releases | โœ… **Allowed (Release ops only)** | + +--- + +## ๐Ÿ›ก๏ธ Core Governance & System Invariants + +1. **Rule 0 (JIT Issue-First)**: Zero code, branch, or premature GitHub issue stubs before Gate 1.4. Issues are sealed Just-In-Time via `./scripts/seal-issue.sh` only after human approval. +2. **Rule 0.1 (Epic Branch Isolation Protocol)**: Epics (`Size: L/XL`) establish an isolated integration branch `epic/issue--`. Direct commits on `epic/**` are strictly forbidden. Implementation proceeds via atomic child issues (< 300 diff lines) branching from and merging into `epic/**` before a consolidated release PR lands on `main`. +3. **Rule A (Append-Only Immutability)**: Issue title and body are permanently read-only once created. Revisions are appended exclusively via comments. +4. **WIP = 1 (Single Active Pair)**: Exactly 1 issue `In Progress` and at most 1 PR `In Review` at any time (Macro Epic in progress, Micro child WIP = 1). +5. **Dual-Write Pattern**: Canonical remote GitHub issue synchronized with local `implementation_plan.md` mirror for IDE harmony. +6. **Zero Auto-Merge Lock (Gate 3.5)**: The agent never merges autonomously without human confirmation (*"Tu peux merger"*). +7. **Runtime Bypass Guardrails**: + * **`branch-guard.mjs`**: PreToolUse hook intercepting file write tools (`write_to_file`, `replace_file_content`), blocking edits on protected branches (`main`, `epic/**`). + * **`plan-guard.mjs`**: PreToolUse hook intercepting shell executions, blocking `--no-verify`, inline hooks overrides (`-c core.hooksPath`), and direct git pushes to protected branches. + +--- + +## ๐Ÿ“ Repository Architecture & Directory Layout + +```text +. +โ”œโ”€โ”€ .agent/ +โ”‚ โ”œโ”€โ”€ hooks/ # Runtime tool interception & safety guards +โ”‚ โ”‚ โ”œโ”€โ”€ branch-guard.mjs # Blocks file writes on protected branches (main, epic/**) +โ”‚ โ”‚ โ”œโ”€โ”€ plan-guard.mjs # Blocks bypasses (--no-verify, -c core.hooksPath) +โ”‚ โ”‚ โ”œโ”€โ”€ pre-commit-airbag.sh # Staged lint, doc checks & zero-hardcoding verification +โ”‚ โ”‚ โ””โ”€โ”€ post-merge-dual-sync.sh# Dynamic base-branch synchronization & branch cleanup +โ”‚ โ”œโ”€โ”€ personas/ # 6 Declarative Engineering Persona manifests (PoLP) +โ”‚ โ”‚ โ”œโ”€โ”€ p1-product-planner.md +โ”‚ โ”‚ โ”œโ”€โ”€ p2-design-lead.md +โ”‚ โ”‚ โ”œโ”€โ”€ p3-privacy-data.md +โ”‚ โ”‚ โ”œโ”€โ”€ p4-system-architect.md +โ”‚ โ”‚ โ”œโ”€โ”€ p5-software-engineer.md +โ”‚ โ”‚ โ””โ”€โ”€ p6-release-manager.md +โ”‚ โ”œโ”€โ”€ playbooks/ # Modular engineering playbooks (< 8,500 bytes) +โ”‚ โ”‚ โ”œโ”€โ”€ android-standards.md # Kotlin, MVI, and Compose engineering standards +โ”‚ โ”‚ โ”œโ”€โ”€ compose-theming.md # Material 3 tokens & typography implementation +โ”‚ โ”‚ โ”œโ”€โ”€ room-migrations.md # SQLite DDL & Room schema migration protocols +โ”‚ โ”‚ โ””โ”€โ”€ roborazzi-export.md # Screenshot testing & visual regression capture +โ”‚ โ”œโ”€โ”€ rules/ # Core governance specifications (< 9,500 bytes) +โ”‚ โ”‚ โ”œโ”€โ”€ agent-lifecycle.md # 3-Phase Lifecycle, Circuit Breaker, Dual-Write +โ”‚ โ”‚ โ”œโ”€โ”€ backlog-planner.md # Inception Consortium, Rule 0/0.1/A, 10 Golden Rules +โ”‚ โ”‚ โ”œโ”€โ”€ git-workflow.md # Conventional commits, SemVer, branch hygiene +โ”‚ โ”‚ โ””โ”€โ”€ firebase-standards.md # Cloud architecture & Crashlytics synchronization +โ”‚ โ”œโ”€โ”€ sidecars/ # Automated background listeners +โ”‚ โ”‚ โ””โ”€โ”€ sync-issue-progress.mjs# Auto-transitions issue to In Progress on checkout +โ”‚ โ”œโ”€โ”€ skills/ # Native Antigravity semantic skills +โ”‚ โ”‚ โ”œโ”€โ”€ plan-issue/ # Inception & 4-Pillar framing skill +โ”‚ โ”‚ โ”œโ”€โ”€ open-pr/ # Release & Walkthrough delivery skill +โ”‚ โ”‚ โ”œโ”€โ”€ quality-airbag/ # Full sanity check validation skill +โ”‚ โ”‚ โ””โ”€โ”€ sync-stitch/ # Stitch MCP screenshot synchronization skill +โ”‚ โ””โ”€โ”€ templates/ # Deterministic markdown templates +โ”œโ”€โ”€ app/ # Reference Android Starter Application +โ”‚ โ”œโ”€โ”€ src/main/java/ # Clean Jetpack Compose starter activity +โ”‚ โ””โ”€โ”€ src/test/java/ # Roborazzi screenshot verification test suite +โ”œโ”€โ”€ docs/ # Technical governance specifications +โ”‚ โ”œโ”€โ”€ analytics-taxonomy.md # P3 Contract: Zero-PII event taxonomy +โ”‚ โ”œโ”€โ”€ qa-classification-test-guide.md # P6 Contract: QA test matrix & classification +โ”‚ โ””โ”€โ”€ scripts-reference.md # Operational CLI scripts reference documentation +โ”œโ”€โ”€ scripts/ # Operational automation tooling +โ”‚ โ”œโ”€โ”€ install-hooks.sh # Binds git hooks to .agent/hooks +โ”‚ โ”œโ”€โ”€ seal-issue.sh # Just-In-Time issue sealing & Projects v2 synchronization +โ”‚ โ”œโ”€โ”€ quality-check.sh # Complete Gradle sanity check execution +โ”‚ โ”œโ”€โ”€ validate-docs.sh # Formal verification of 38 documentation contracts +โ”‚ โ””โ”€โ”€ sync-project-metadata.mjs # Direct Projects v2 GraphQL metadata synchronization +โ”œโ”€โ”€ AGENTS.md # Agent Micro-Kernel & Root Governance (< 10,000 bytes) +โ”œโ”€โ”€ ARCHITECTURE.md # Formal Architecture & State Machine Specification +โ”œโ”€โ”€ DESIGN.md # Serene Intellectual Design Tokens (YAML frontmatter) +โ”œโ”€โ”€ design-system.md # Visual Component Matrix, 4-state specs & motion +โ”œโ”€โ”€ kernel.config.json # Declarative project configuration file +โ”œโ”€โ”€ kernel.config.schema.json # Formal JSON Schema validating kernel.config.json +โ””โ”€โ”€ README.md # Engineering Showcase & Documentation +``` --- ## โš™๏ธ Declarative Configuration (`kernel.config.json`) -All repository-specific parameters are extracted into a single declarative file validated by `kernel.config.schema.json`: +All repository-specific parameters are centralized in `kernel.config.json`, formally validated by `kernel.config.schema.json`: ```json { @@ -104,39 +233,86 @@ All repository-specific parameters are extracted into a single declarative file --- -## ๐Ÿš€ Quickstart in 3 Steps +## ๐Ÿš€ Developer Quickstart in 4 Steps ### 1. Configure the Kernel -Clone the repository and edit `kernel.config.json` with your project coordinates: +Clone the repository and adapt `kernel.config.json` with your project coordinates: ```bash git clone https://github.com//agentic-android-delivery-kernel.git my-app cd my-app -# Edit kernel.config.json +# Customize kernel.config.json ``` -### 2. Install Git Hooks -Bind local git hooks to `.agent/hooks` (`pre-commit-airbag.sh` and `branch-guard.mjs`): +### 2. Install Local Git Hooks +Bind local git hooks to `.agent/hooks` to activate the pre-commit airbag and branch guard: ```bash ./scripts/install-hooks.sh ``` ### 3. Verify the Quality Airbag -Ensure compilation, Android Lint, and Roborazzi screenshot assertions pass 100% green: +Ensure compilation, Android Lint, Roborazzi screenshot assertions, and documentation contracts pass: ```bash +# Validate documentation contracts and byte budgets (38 checks) +./scripts/validate-docs.sh + +# Run runtime guardrail test suite +node scripts/test-runtime-guardrails.mjs + +# Execute full Android code sanity check ./scripts/quality-check.sh ``` +### 4. Pair with the Agent +When initiating a feature or bug fix: +1. **Inception Prompt**: Prompt the agent with your user requirement. Persona 1 checks for duplicates and the Consortium drafts `implementation_plan.md`. +2. **Gate 1.4 Halt**: The agent halts and awaits your explicit approval. +3. **JIT Sealing**: Once approved, the issue is sealed automatically on GitHub with Projects v2 fields. +4. **Delivery & Testing**: Persona 5 implements code on `/issue--` and verifies tests green. +5. **Gate 3.5 Release**: Persona 6 opens the PR and awaits your explicit command (*"Tu peux merger"*). + +--- + +## ๐Ÿ“š Technical Playbooks & Governance Registry + +The kernel provides exhaustive technical playbooks and governance rules located in `.agent/`: + +| Asset | Path | Summary & Focus | +|---|---|---| +| **Android Standards** | [`.agent/playbooks/android-standards.md`](.agent/playbooks/android-standards.md) | Clean MVI, Kotlin Progressive mode, Unidirectional Data Flow, Zero Hardcoded Strings | +| **Compose Theming** | [`.agent/playbooks/compose-theming.md`](.agent/playbooks/compose-theming.md) | Material 3 token mapping, Serene Intellectual color palette, typography scales | +| **Room Migrations** | [`.agent/playbooks/room-migrations.md`](.agent/playbooks/room-migrations.md) | SQLite DDL, automated migration testing, Room schema export integrity | +| **Roborazzi Export** | [`.agent/playbooks/roborazzi-export.md`](.agent/playbooks/roborazzi-export.md) | Pixel-perfect screenshot capture, light/dark mode matrices, Stitch MCP sync | +| **Agent Lifecycle** | [`.agent/rules/agent-lifecycle.md`](.agent/rules/agent-lifecycle.md) | 3-Phase Lifecycle, Token Sobriety, Circuit Breaker, Dual-Write Pattern | +| **Backlog Planner** | [`.agent/rules/backlog-planner.md`](.agent/rules/backlog-planner.md) | Rule 0/0.1/A, Inception Consortium, 4 Pillars, 10 Golden Planning Rules | +| **Git Workflow** | [`.agent/rules/git-workflow.md`](.agent/rules/git-workflow.md) | Conventional Commits, SemVer releases, Dual-Sync base branch reconciliation | +| **Scripts Reference** | [`docs/scripts-reference.md`](docs/scripts-reference.md) | Comprehensive CLI reference for all operational scripts and sidecars | +| **QA Test Guide** | [`docs/qa-classification-test-guide.md`](docs/qa-classification-test-guide.md) | 4-tier crash qualification, non-fatal triage, automated QA test matrix | +| **Analytics Taxonomy** | [`docs/analytics-taxonomy.md`](docs/analytics-taxonomy.md) | Zero-PII contract, value bucketing, GDPR & EU AI Act compliance specifications | +| **Design System** | [`design-system.md`](design-system.md) | Visual component states (`Loading`, `Empty`, `Error`, `Content`), motion timing | +| **Design Tokens** | [`DESIGN.md`](DESIGN.md) | Canonical YAML frontmatter design tokens (Serene Intellectual palette) | + +--- + +## ๐Ÿ“ฆ Reference Android Starter Stack Included + +The repository includes a production-ready Android Compose starter: +* **Jetpack Compose & Material 3**: Pre-configured `Theme.kt`, `Color.kt`, and `Type.kt` adhering to Serene Intellectual design tokens. +* **Roborazzi Visual Regression Test**: `app/src/test/.../GreetingPreviewScreenshotTest.kt` verifying pixel-level rendering in JVM unit tests without an emulator. +* **Gradle Airbag Task**: `./gradlew codeSanityCheck` bundling `lintDebug`, `lintRelease`, unit tests, and Roborazzi screenshot verification. +* **Kotlin Progressive Mode**: Enforcing strict compiler checks, zero unused warnings, and null-safety guarantees. + --- -## ๐Ÿ“ฆ Reference Implementation Included +## ๐Ÿšข CI/CD Quality Gate & Automated Delivery -The repository includes a working Android Compose starter: -* **Clean Compose Activity**: `app/src/main/` with Material 3 theming. -* **Roborazzi Screenshot Test**: `app/src/test/.../GreetingPreviewScreenshotTest.kt` verifying pixel-level rendering. -* **Airbag Gradle Task**: `./gradlew codeSanityCheck` verifying debug & release lint, unit tests, and screenshots. +The GitHub Actions pipeline ([`.github/workflows/delivery-pipeline.yml`](.github/workflows/delivery-pipeline.yml)) enforces the Quality Airbag automatically: +* **Pull Request Gate**: Runs on all PRs targeting `main` and `epic/**`. Validates documentation budgets, executes Gradle sanity checks, and blocks regressions. +* **Intermediate Child PRs**: Tagged with `skip-release` to omit heavy APK building during iterative child tasks. +* **Release Automation**: Triggered upon milestone closure or manual dispatch. Builds signed release APKs and automatically dispatches builds to Firebase App Distribution with structured release notes. +* **Minimal Privileges**: Workflows default to top-level `permissions: { contents: read, pull-requests: read }` with scoped elevation only where strictly required. --- ## ๐Ÿ“„ License -Distributed under the **Apache-2.0 License**. See `LICENSE` for details. +Distributed under the **Apache-2.0 License**. See [LICENSE](LICENSE) for details. diff --git a/banner.svg b/banner.svg new file mode 100644 index 0000000..8dbcb01 --- /dev/null +++ b/banner.svg @@ -0,0 +1,126 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Antigravity 2.0 Native + + + + + + + Jetpack Compose & Roborazzi + + + + + + + Zero Rogue Commits + + + + + + + Agentic Android Delivery Kernel + โ€” Micro-Kernel Protocol + + + Deterministic Multi-Agent Governance, Just-In-Time Issue Sealing & Automated Quality Airbag + + + + + + + + + Principle of Least Privilege + 6 Personas & PoLP + Dedicated engineering roles, + shell revoked for P1โ€“P4 + + + + + + Human-In-The-Loop + 2 Blocking Gates + Gate 1.4 Inception Halt & + Gate 3.5 Auto-Merge Lock + + + + + + Traceability & Epics + JIT Sealing & Rule 0.1 + seal-issue.sh + Projects v2, + isolated epic/** branching + + + + + + Comprehensive Verification + Quality Airbag + codeSanityCheck, Roborazzi + & 38 doc contracts verified + + + diff --git a/scripts/seal-issue.sh b/scripts/seal-issue.sh index ce1034d..741e67b 100755 --- a/scripts/seal-issue.sh +++ b/scripts/seal-issue.sh @@ -116,7 +116,9 @@ node -e ' const formattedTitle = (scope && scope !== "core") ? `${type}(${scope}): ${cleanTitle}` : `${type}: ${cleanTitle}`; const slug = cleanTitle.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").substring(0, 40); - fs.writeFileSync(varsPath, `TYPE="${type}"\nSCOPE="${scope}"\nPARENT="${parent}"\nMILESTONE="${milestone}"\nPRIORITY="${priority}"\nSIZE="${size}"\nESTIMATE="${estimate}"\nFORMATTED_TITLE="${formattedTitle.replace(/"/g, "\\\"")}"\nSLUG="${slug}"\n`, "utf8"); + const escapeBash = (str) => String(str).replace(/\\/g, "\\\\").replace(/"/g, "\\\"").replace(/`/g, "\\`").replace(/\$/g, "\\$"); + + fs.writeFileSync(varsPath, `TYPE="${escapeBash(type)}"\nSCOPE="${escapeBash(scope)}"\nPARENT="${escapeBash(parent)}"\nMILESTONE="${escapeBash(milestone)}"\nPRIORITY="${escapeBash(priority)}"\nSIZE="${escapeBash(size)}"\nESTIMATE="${escapeBash(estimate)}"\nFORMATTED_TITLE="${escapeBash(formattedTitle)}"\nSLUG="${escapeBash(slug)}"\n`, "utf8"); let body = content.replace(/^---\s*\n[\s\S]*?\n---\s*\n/, ""); body = body.split("\n").filter(line => {