guardian-framework 0.1.16 → 0.1.17

package/README.md

@@ -26,25 +26,25 @@ The entire lifecycle lives in a single `.pi/` directory. Every artifact (modules
 ## The Full SDLC
 
 ```
-Business Intent
+You have a business intent
     │
     ▼
-Domain Exploration    ─── discovers bounded contexts, entities, ubiquitous language
+Domain Exploration     ←─ you and the agent explore, iterate, refine
     │
     ▼
-Architecture Modules  ─── components, dependencies, contracts per context
+Architecture Modules   ←─ you review, adjust, approve
     │
     ▼
-ADRs & Review         ─── every decision captured, cross-referenced, versioned
+ADRs, Diagrams, Specs  ←─ you challenge decisions, finalize
     │
     ▼
-Roadmap               ─── phases with dependencies, migrations, acceptance criteria
+Roadmap Plan           ←─ you adopt phases, set priorities
     │
     ▼
-Epic Execution        ─── issues generated per component, agents implement in pipelines
+Epic Execution         ─── agents implement, you review PRs
     │
     ▼
-Enforcement           ─── CI validates structure, dependencies, DDD layers, every merge
+Enforcement Pipeline   ─── CI blocks merges on violation
 ```
 
 ---
@@ -55,22 +55,27 @@ Enforcement           ─── CI validates structure, dependencies, DDD layers
 
 *"I need to build a system that collects audit records from CI/CD pipelines, verifies their integrity, stores them, and lets customers query them."*
 
-### 2. Explore the Domain
+### 2. Explore the Domain (Human + Agent, Iterative)
 
 ```
 /domain --explore "Audit logging for regulated financial transactions"
 ```
 
-Guardian analyzes the intent and produces a structured domain model:
-- **Bounded contexts:** Audit Ingestion, Audit Query, Compliance Engine, Policy Engine
-- **Entities:** AuditRecord, Policy, ComplianceReport
-- **Ubiquitous language:** signed records, evidence, compliance score
+Guardian analyzes your intent and produces a structured domain model. But this isn't a one-shot output — it's the start of a conversation. You review, challenge, and refine:
 
-This isn't a brainstorming session. It's the first artifact in a chain that ends with enforced CI.
+- *"These aren't the right bounded contexts. Merge Ingestion and Query into one."*
+- *"Add a Compliance Engine context. Regulated finance needs it."*
+- *"The ubiquitous language is wrong — we call them 'evidence records', not 'audit records'."*
 
-### 3. Define Architecture Modules
+You go back and forth until the model reflects your actual business. Only then do you proceed.
 
-From the exploration, Guardian scaffolds one module per bounded context:
+### 3. Scaffold Architecture Modules
+
+```
+/domain --architect-scaffold <session-id>
+```
+
+Guardian generates one architecture module per bounded context, with components, dependencies, and contract interfaces:
 
 ```markdown
 # Audit Ingestion
@@ -86,11 +91,17 @@ description: Deduplicates records using Idempotency-Key header.
 depends: HMAC Signature Verifier
 ```
 
-Each module defines components, their dependencies, and their contract interfaces. The structure is simple markdown — no DSL, no config language.
+### 4. Review Architecture (Human in the Loop)
+
+Now you review the generated architecture. This is where the real design happens:
 
-### 4. Capture Decisions with ADRs
+- *"The Idempotency Handler shouldn't depend on Signature Verifier — they're parallel."*
+- *"We need an ADR explaining why we chose HMAC-SHA256 over ECDSA."*
+- *"Add a system-overview diagram showing how records flow from ingestion to query."*
 
-Every architectural choice gets an Architecture Decision Record — not as documentation, as a constraint.
+You tell the agent to add ADRs, update module docs, generate diagrams. You challenge decisions until the architecture is solid.
+
+Every ADR captures a decision:
 
 ```
 ADR-004: Use HMAC-SHA256 with JCS canonicalization
@@ -98,81 +109,81 @@ ADR-005: Idempotency via Idempotency-Key header (not dedup table)
 ADR-006: Cursor-based pagination for audit listing
 ```
 
-ADRs are cross-referenced. Change an ADR? The modules that depend on it need updating. The canonical validator catches the gap.
-
-### 5. Plan the Roadmap
+### 5. Adopt the Roadmap
 
-Group modules into delivery phases. Each phase has dependencies, database migrations, and acceptance criteria.
+When the architecture is finalized, you lock it in with a roadmap. Each phase has dependencies, migrations, and acceptance criteria.
 
 ```
 /architect --roadmap
+/architect --adopt-roadmap
 ```
 
-> Phase 0: Foundation — Scaffold & Shared Infrastructure (Days 1–5)
->   Modules: Operations, Auth, Team Management, Rate Limiting, API Versioning
-> Phase 1: Core Ingestion Pipeline (Days 6–12)
->   Modules: Audit Ingestion, Audit Query, Usage Metering
->   Depends on: Phase 0
+> Phase 0: Foundation (5 modules, Days 1–5)
+> Phase 1: Core Ingestion Pipeline (3 modules, Days 6–12, depends on Phase 0)
 
-### 6. Execute
+### 6. Execute via Phases
 
 ```
 /architect --phase "Phase 0"
 ```
 
-Guardian generates one epic per module, one issue per component. Each issue carries:
-- The component's architecture context and dependencies
-- A language-specific codegen skill reference (e.g., `Follow: .pi/skills/agents/rust-codegen.md`)
-- Auto-generated file changes with the correct DDD layer structure
-- Acceptance criteria
+Guardian generates one epic per module, one issue per component. Each issue carries the component's architecture context, language-specific DDD patterns, and acceptance criteria.
 
-The implementing agent reads the skill, loads the relevant DDD patterns on-demand, and builds the component. When done, it calls `pipeline_advance`. Guardian auto-advances through:
+The agent implements. You review PRs. Guardian auto-advances through the pipeline:
 
 ```
 implement → validate → create-mr → merge
 ```
 
-### 7. Enforce
+### 7. Enforcement Closes the Loop
 
-This is where the loop closes. Guardian generates CI scripts from the architecture:
+Every change is validated against the architecture:
 
 | Script | What it enforces |
 |--------|-----------------|
 | `check_ddd_structure.sh` | Every module has `domain/ application/ infrastructure/ interfaces/` — no `contracts/` wrapper |
-| `check_architecture_conformance.sh` | Domain doesn't import infrastructure. Application doesn't import interfaces. Per-module 4-layer structure. |
-| `check_{module}_contracts.sh` | Every frozen interface has a concrete implementation |
+| `check_architecture_conformance.sh` | Domain doesn't import infrastructure. Per-module 4-layer structure. |
 | `validate-canonical.sh` | Every code file references its architecture source |
 
-If a developer (or AI agent) adds a dependency from the domain layer to infrastructure, `check_ddd_structure.sh` catches it and CI fails. The merge is blocked.
-
----
-
-## What This Means
-
-**Architecture drift becomes a compile-time error.**
-
-Not a documentation comment. Not a code review note that gets lost. A CI failure that blocks the merge until fixed.
-
-Guardian was proven on [Rigorix](https://github.com/arman-jalili/rigorix-oss): 146,312 lines of Rust, 30 modules, 580 commits, built by a single developer over 11 active days. The architecture defined in `.pi/` was continuously validated against implementation. When drift happened, it was caught before reaching main.
+If someone (or an AI) adds a dependency from the domain layer to infrastructure, `check_ddd_structure.sh` catches it. CI fails. The merge is blocked.
 
 ---
 
 ## Quick Start
 
 ```bash
+# 1. Scaffold
+cd your-project
 npx guardian-framework init
-```
 
-Then:
-```bash
-cd your-project && pi
+# 2. Explore (iterative — review, refine, repeat)
 /domain --explore "your business intent"
+
+# 3. Generate architecture from exploration
+/domain --architect-scaffold <session-id>
+
+# 4. Review and refine (ADRs, diagrams, modules — human-in-the-loop)
+
+# 5. Adopt the roadmap
 /architect --roadmap
+/architect --adopt-roadmap
+
+# 6. Execute
 /architect --phase "Phase 0"
 ```
 
 ---
 
+## What This Means
+
+**Architecture drift becomes a compile-time error.**
+
+Not a documentation comment. Not a code review note that gets lost. A CI failure that blocks the merge until fixed.
+
+Guardian was proven on [Rigorix](https://github.com/arman-jalili/rigorix-oss): 146,312 lines of Rust, 30 modules, 580 commits, built by a single developer over 11 active days. The architecture defined in `.pi/` was continuously validated against implementation. When drift happened, it was caught before reaching main.
+
+---
+
 ## Links
 
 | | |

package/dist/cli.js

@@ -1335,7 +1335,7 @@ __export(exports_package, {
   bin: () => bin,
   author: () => author
 });
-var name = "guardian-framework", version = "0.1.16", description = "Token-optimized agentic framework scaffolder with pi-first architecture", type = "module", main = "dist/exports.js", exports, types = "dist/exports.d.ts", bin, files, engines, scripts, publishConfig, pi, repository, homepage = "https://github.com/arman-jalili/guardian-framework#readme", bugs, dependencies, devDependencies, keywords, author = "Arman Wolkensteiner-Jalili", license = "MIT", package_default;
+var name = "guardian-framework", version = "0.1.17", description = "Token-optimized agentic framework scaffolder with pi-first architecture", type = "module", main = "dist/exports.js", exports, types = "dist/exports.d.ts", bin, files, engines, scripts, publishConfig, pi, repository, homepage = "https://github.com/arman-jalili/guardian-framework#readme", bugs, dependencies, devDependencies, keywords, author = "Arman Wolkensteiner-Jalili", license = "MIT", package_default;
 var init_package = __esm(() => {
   exports = {
     ".": {

package/dist/exports.js

@@ -995,7 +995,7 @@ __export(exports_package, {
   bin: () => bin,
   author: () => author
 });
-var name = "guardian-framework", version = "0.1.16", description = "Token-optimized agentic framework scaffolder with pi-first architecture", type = "module", main = "dist/exports.js", exports, types = "dist/exports.d.ts", bin, files, engines, scripts, publishConfig, pi, repository, homepage = "https://github.com/arman-jalili/guardian-framework#readme", bugs, dependencies, devDependencies, keywords, author = "Arman Wolkensteiner-Jalili", license = "MIT", package_default;
+var name = "guardian-framework", version = "0.1.17", description = "Token-optimized agentic framework scaffolder with pi-first architecture", type = "module", main = "dist/exports.js", exports, types = "dist/exports.d.ts", bin, files, engines, scripts, publishConfig, pi, repository, homepage = "https://github.com/arman-jalili/guardian-framework#readme", bugs, dependencies, devDependencies, keywords, author = "Arman Wolkensteiner-Jalili", license = "MIT", package_default;
 var init_package = __esm(() => {
   exports = {
     ".": {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "guardian-framework",
-	"version": "0.1.16",
+	"version": "0.1.17",
 	"description": "Token-optimized agentic framework scaffolder with pi-first architecture",
 	"type": "module",
 	"main": "dist/exports.js",

package/templates/pi/preflight_report.json

@@ -1,5 +1,5 @@
 {
-  "timestamp": "2026-07-03T05:52:11Z",
+  "timestamp": "2026-07-03T05:56:51Z",
   "mode": "all",
   "stages_run": [],
   "summary": {
@@ -8,7 +8,7 @@
     "failed": 1,
     "skipped": 12
   },
-  "duration_seconds": 0,
+  "duration_seconds": 1,
   "results": [
   {
     "name": "check_mr_traceability.sh",
@@ -68,7 +68,7 @@
     "name": "secret_scan",
     "status": "pass",
     "message": "",
-    "duration": 0
+    "duration": 1
   },
   {
     "name": "dependency_audit",