guardian-framework 0.1.15 → 0.1.17

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/README.md +106 -69
  2. package/dist/cli.js +1 -1
  3. package/dist/exports.js +1 -1
  4. package/package.json +1 -1
  5. package/templates/pi/preflight_report.json +3 -3
package/README.md CHANGED
@@ -1,10 +1,10 @@
1
1
  <div align="center">
2
2
  <picture>
3
- <source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/badge/Guardian-Architecture%20Enforcement-00bcd4?style=for-the-badge&labelColor=222">
4
- <img alt="Guardian" src="https://img.shields.io/badge/Guardian-Architecture%20Enforcement-00bcd4?style=for-the-badge&labelColor=fff">
3
+ <source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/badge/Guardian-SDLC%20Orchestrator-00bcd4?style=for-the-badge&labelColor=222">
4
+ <img alt="Guardian" src="https://img.shields.io/badge/Guardian-SDLC%20Orchestrator-00bcd4?style=for-the-badge&labelColor=fff">
5
5
  </picture>
6
6
 
7
- <h3>From idea to production code — with architecture that's actually enforced.</h3>
7
+ <h3>Business intent → enforced architecture → production code.<br/>One flow, no drift.</h3>
8
8
 
9
9
  <br/>
10
10
 
@@ -12,38 +12,70 @@
12
12
  <a href="https://github.com/arman-jalili/guardian-framework/actions"><img src="https://img.shields.io/github/actions/workflow/status/arman-jalili/guardian-framework/ci.yml?style=flat&colorA=222&colorB=00bcd4" alt="CI"/></a>
13
13
  <a href="LICENSE"><img src="https://img.shields.io/github/license/arman-jalili/guardian-framework?style=flat&colorA=222&colorB=00bcd4" alt="license"/></a>
14
14
  <br/>
15
- <a href="https://github.com/arman-jalili/rigorix-oss"><img src="https://img.shields.io/badge/Built%20with%20Guardian-Rigorix%20(146K%20LOC%20Rust)-00bcd4?style=flat&colorA=222" alt="Rigorix"/></a>
15
+ <a href="https://github.com/arman-jalili/rigorix-oss"><img src="https://img.shields.io/badge/Proven%20on-Rigorix%20(146K%20LOC)%2000bcd4?style=flat&colorA=222" alt="Rigorix"/></a>
16
16
  </div>
17
17
 
18
18
  ---
19
19
 
20
- ### What if your architecture was more than a document?
20
+ Guardian is an SDLC orchestrator for AI-assisted development. It takes you from a business intent — *"I need to build audit logging for regulated financial transactions"* — to an enforcement pipeline that blocks merges if the implementation violates the architecture.
21
21
 
22
- Most projects start with great architecture ideas, then drift. Implementation strays. Dependencies sneak in the wrong direction. By the time anyone notices, the codebase is fighting the original design.
22
+ The entire lifecycle lives in a single `.pi/` directory. Every artifact (modules, ADRs, roadmap, issues, CI scripts, agent skills) is generated from that directory. Nothing is handwritten twice. Nothing drifts.
23
23
 
24
- **Guardian is the tool that prevents that drift — not by documentation, but by enforcement.**
24
+ ---
25
25
 
26
- It works with **pi** — the AI coding agent. You define your architecture once in simple markdown files. Guardian turns those files into executable constraints: CI scripts that validate every change, prompt templates that guide every implementation, and a verification pipeline that blocks merges when code violates architecture.
26
+ ## The Full SDLC
27
27
 
28
- Guardian also **scaffolds agent configurations** for Claude Code, Copilot, Cursor, and OpenCode — exporting skills, context files, and workflow definitions to their respective directories (`.claude/`, `.github/`, `.opencode/`).
28
+ ```
29
+ You have a business intent
30
+ │
31
+ ▼
32
+ Domain Exploration ←─ you and the agent explore, iterate, refine
33
+ │
34
+ ▼
35
+ Architecture Modules ←─ you review, adjust, approve
36
+ │
37
+ ▼
38
+ ADRs, Diagrams, Specs ←─ you challenge decisions, finalize
39
+ │
40
+ ▼
41
+ Roadmap Plan ←─ you adopt phases, set priorities
42
+ │
43
+ ▼
44
+ Epic Execution ─── agents implement, you review PRs
45
+ │
46
+ ▼
47
+ Enforcement Pipeline ─── CI blocks merges on violation
48
+ ```
29
49
 
30
50
  ---
31
51
 
32
- ## How It Works — A Complete Walkthrough
52
+ ## Walkthrough: From Intent to Enforcement
53
+
54
+ ### 1. You Have a Business Intent
33
55
 
34
- **The process is a flow, not a one-time setup. Here's the full loop:**
56
+ *"I need to build a system that collects audit records from CI/CD pipelines, verifies their integrity, stores them, and lets customers query them."*
35
57
 
36
- ### 1. Explore the Domain
37
- Start by understanding the problem space. Guardian guides you through domain exploration — identifying bounded contexts, entities, and the language your business speaks.
58
+ ### 2. Explore the Domain (Human + Agent, Iterative)
38
59
 
39
60
  ```
40
61
  /domain --explore "Audit logging for regulated financial transactions"
41
62
  ```
42
63
 
43
- > Output: structured domain analysis with contexts, entities, and a shared glossary.
64
+ 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:
65
+
66
+ - *"These aren't the right bounded contexts. Merge Ingestion and Query into one."*
67
+ - *"Add a Compliance Engine context. Regulated finance needs it."*
68
+ - *"The ubiquitous language is wrong — we call them 'evidence records', not 'audit records'."*
69
+
70
+ You go back and forth until the model reflects your actual business. Only then do you proceed.
71
+
72
+ ### 3. Scaffold Architecture Modules
73
+
74
+ ```
75
+ /domain --architect-scaffold <session-id>
76
+ ```
44
77
 
45
- ### 2. Define the Architecture
46
- From the exploration, Guardian scaffolds architecture modules. Each module describes one bounded context: its components, dependencies, and contract interfaces.
78
+ Guardian generates one architecture module per bounded context, with components, dependencies, and contract interfaces:
47
79
 
48
80
  ```markdown
49
81
  # Audit Ingestion
@@ -52,98 +84,103 @@ From the exploration, Guardian scaffolds architecture modules. Each module descr
52
84
  status: planned
53
85
  description: Verifies HMAC-SHA256 signatures on incoming audit records.
54
86
  depends: none
87
+
88
+ ## Idempotency Handler
89
+ status: planned
90
+ description: Deduplicates records using Idempotency-Key header.
91
+ depends: HMAC Signature Verifier
55
92
  ```
56
93
 
57
- ### 3. Review & Decide
58
- Architecture Decision Records (ADRs) capture every meaningful choice — why this approach, not that one. They're version-controlled, cross-referenced, and enforced.
94
+ ### 4. Review Architecture (Human in the Loop)
59
95
 
60
- > **ADR-004:** "Use HMAC-SHA256 with JCS canonicalization for audit signatures."
61
- > Status: Accepted. Depends on: ADR-003 (JSON Canonicalization Scheme).
96
+ Now you review the generated architecture. This is where the real design happens:
62
97
 
63
- ### 4. Plan the Roadmap
64
- Group modules into delivery phases with dependencies, migrations, and acceptance criteria.
98
+ - *"The Idempotency Handler shouldn't depend on Signature Verifier — they're parallel."*
99
+ - *"We need an ADR explaining why we chose HMAC-SHA256 over ECDSA."*
100
+ - *"Add a system-overview diagram showing how records flow from ingestion to query."*
101
+
102
+ You tell the agent to add ADRs, update module docs, generate diagrams. You challenge decisions until the architecture is solid.
103
+
104
+ Every ADR captures a decision:
65
105
 
66
106
  ```
67
- /architect --roadmap
107
+ ADR-004: Use HMAC-SHA256 with JCS canonicalization
108
+ ADR-005: Idempotency via Idempotency-Key header (not dedup table)
109
+ ADR-006: Cursor-based pagination for audit listing
68
110
  ```
69
111
 
70
- > Shows: Phase 0: Foundation (5 modules, Days 1–5), Phase 1: Core Pipeline (3 modules, Days 6–12)...
112
+ ### 5. Adopt the Roadmap
71
113
 
72
- ### 5. Execute Phases or Epics
73
- Guardian generates issue files from your architecture — one issue per component, with full context, acceptance criteria, and auto-generated file changes.
114
+ When the architecture is finalized, you lock it in with a roadmap. Each phase has dependencies, migrations, and acceptance criteria.
74
115
 
75
116
  ```
76
- /architect --phase "Phase 0"
117
+ /architect --roadmap
118
+ /architect --adopt-roadmap
77
119
  ```
78
120
 
79
- > Creates 5 epics × N component issues each, organized in a pipeline.
80
- > Each issue includes: `Follow: .pi/skills/agents/rust-codegen.md` — the implementing agent gets the right DDD patterns automatically.
121
+ > Phase 0: Foundation (5 modules, Days 1–5)
122
+ > Phase 1: Core Ingestion Pipeline (3 modules, Days 6–12, depends on Phase 0)
123
+
124
+ ### 6. Execute via Phases
81
125
 
82
- The agent implements each component. When done, it calls `pipeline_advance`. Guardian auto-advances through:
83
126
  ```
84
- implement → validate → create-mr → merge
127
+ /architect --phase "Phase 0"
85
128
  ```
86
129
 
87
- If CI fails (architecture violation, security issue, broken test), the pipeline blocks until fixed.
130
+ 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.
88
131
 
89
- ---
132
+ The agent implements. You review PRs. Guardian auto-advances through the pipeline:
90
133
 
91
- ## What Makes Guardian Different
134
+ ```
135
+ implement → validate → create-mr → merge
136
+ ```
92
137
 
93
- | Instead of... | Guardian does this |
94
- |---------------|-------------------|
95
- | Drawing diagrams that go stale | Generates CI scripts that check structure on every commit |
96
- | Writing "domain must not depend on infrastructure" in a doc | Creates a `check_ddd_structure.sh` that literally greps for illegal imports and fails if found |
97
- | Trusting code review to catch drift | Blocks merges when architecture is violated — no human oversight needed |
98
- | Onboarding new devs with 30-page docs | Every issue carries its full context: architecture reference, codegen patterns, acceptance criteria |
99
- | One-size-fits-all prompts | Generates language-specific codegen skills (Rust, Go, Python, TypeScript, Java/Spring Boot) with DDD + Clean Architecture patterns |
138
+ ### 7. Enforcement Closes the Loop
100
139
 
101
- ---
140
+ Every change is validated against the architecture:
102
141
 
103
- ## Built with Guardian
142
+ | Script | What it enforces |
143
+ |--------|-----------------|
144
+ | `check_ddd_structure.sh` | Every module has `domain/ application/ infrastructure/ interfaces/` — no `contracts/` wrapper |
145
+ | `check_architecture_conformance.sh` | Domain doesn't import infrastructure. Per-module 4-layer structure. |
146
+ | `validate-canonical.sh` | Every code file references its architecture source |
104
147
 
105
- **[Rigorix](https://github.com/arman-jalili/rigorix-oss)** — a deterministic coding-agent runtime built using Guardian's own workflow:
106
- - 146,312 lines of Rust
107
- - 30 modules across 3 crates
108
- - 18 ADRs, 38 module specs, 44 issue drafts
109
- - 580 commits over 11 active days
110
- - Built by a single developer — Guardian handled orchestration and enforcement
148
+ 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.
111
149
 
112
150
  ---
113
151
 
114
152
  ## Quick Start
115
153
 
116
154
  ```bash
155
+ # 1. Scaffold
156
+ cd your-project
117
157
  npx guardian-framework init
118
- ```
119
158
 
120
- Answer 4 prompts (project name, language, AI tools, validators). You get:
121
- - A `.pi/` directory with full architecture scaffolding
122
- - 20 TypeScript extensions (orchestration, pipeline, kanban, validation, etc.)
123
- - 21 workflow prompt templates
124
- - 74 CI scripts with language-specific validators
125
- - Agent export files for Claude Code, pi, Copilot, Cursor, and more
159
+ # 2. Explore (iterative — review, refine, repeat)
160
+ /domain --explore "your business intent"
126
161
 
127
- Then:
128
- ```
129
- cd your-project && pi
130
- /domain --explore "your business domain"
162
+ # 3. Generate architecture from exploration
163
+ /domain --architect-scaffold <session-id>
164
+
165
+ # 4. Review and refine (ADRs, diagrams, modules — human-in-the-loop)
166
+
167
+ # 5. Adopt the roadmap
131
168
  /architect --roadmap
169
+ /architect --adopt-roadmap
170
+
171
+ # 6. Execute
132
172
  /architect --phase "Phase 0"
133
173
  ```
134
174
 
135
175
  ---
136
176
 
137
- ## One File, One Constraint
177
+ ## What This Means
138
178
 
139
- At the heart of every file is a canonical reference:
179
+ **Architecture drift becomes a compile-time error.**
140
180
 
141
- ```typescript
142
- //! @canonical .pi/architecture/modules/auth-system.md#token-validation
143
- //! Issue: #42
144
- ```
181
+ Not a documentation comment. Not a code review note that gets lost. A CI failure that blocks the merge until fixed.
145
182
 
146
- When code and architecture diverge, the reference breaks. CI catches it. The merge is blocked. Architecture drift becomes a compile-time error, not a documentation comment.
183
+ 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.
147
184
 
148
185
  ---
149
186
 
@@ -151,7 +188,7 @@ When code and architecture diverge, the reference breaks. CI catches it. The mer
151
188
 
152
189
  | | |
153
190
  |---|---|
154
- | **Full User Manual** | [docs/USER_MANUAL.md](docs/USER_MANUAL.md) — every workflow, every command, validated against source |
155
- | **Reference Implementation** | [Rigorix](https://github.com/arman-jalili/rigorix-oss) — 146K LOC Rust, 30 modules, built with Guardian |
191
+ | **User Manual** | [docs/USER_MANUAL.md](docs/USER_MANUAL.md) — every workflow, command, and extension |
192
+ | **Proven on** | [Rigorix](https://github.com/arman-jalili/rigorix-oss) — 146K LOC Rust, 30 modules |
156
193
  | **Source** | [github.com/arman-jalili/guardian-framework](https://github.com/arman-jalili/guardian-framework) |
157
194
  | **License** | MIT |
package/dist/cli.js CHANGED
@@ -1335,7 +1335,7 @@ __export(exports_package, {
1335
1335
  bin: () => bin,
1336
1336
  author: () => author
1337
1337
  });
1338
- var name = "guardian-framework", version = "0.1.15", 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;
1338
+ 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;
1339
1339
  var init_package = __esm(() => {
1340
1340
  exports = {
1341
1341
  ".": {
package/dist/exports.js CHANGED
@@ -995,7 +995,7 @@ __export(exports_package, {
995
995
  bin: () => bin,
996
996
  author: () => author
997
997
  });
998
- var name = "guardian-framework", version = "0.1.15", 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;
998
+ 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;
999
999
  var init_package = __esm(() => {
1000
1000
  exports = {
1001
1001
  ".": {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "guardian-framework",
3
- "version": "0.1.15",
3
+ "version": "0.1.17",
4
4
  "description": "Token-optimized agentic framework scaffolder with pi-first architecture",
5
5
  "type": "module",
6
6
  "main": "dist/exports.js",
package/templates/pi/preflight_report.json CHANGED
@@ -1,5 +1,5 @@
1
1
  {
2
- "timestamp": "2026-07-03T05:48:30Z",
2
+ "timestamp": "2026-07-03T05:56:51Z",
3
3
  "mode": "all",
4
4
  "stages_run": [],
5
5
  "summary": {
@@ -8,7 +8,7 @@
8
8
  "failed": 1,
9
9
  "skipped": 12
10
10
  },
11
- "duration_seconds": 0,
11
+ "duration_seconds": 1,
12
12
  "results": [
13
13
  {
14
14
  "name": "check_mr_traceability.sh",
@@ -68,7 +68,7 @@
68
68
  "name": "secret_scan",
69
69
  "status": "pass",
70
70
  "message": "",
71
- "duration": 0
71
+ "duration": 1
72
72
  },
73
73
  {
74
74
  "name": "dependency_audit",