sagaz-ai 0.1.5 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,129 @@
+# Changelog
+
+## [0.3.0] - 2026-06-11
+
+### Release Type
+
+Minor
+
+### Added
+
+- Operations runbook for daily starts, project starts, resumes, handoffs, verification, releases, GitHub operations, and stop conditions.
+- Complete examples library covering web SaaS on Vercel, mobile habit tracking, production bugfix releases, and brownfield refactors.
+- Capabilities matrix comparing Sagaz with common orchestration systems and identifying what Sagaz now covers or intentionally defers.
+- Formal permission contract with approval levels for local edits, installs, network access, GitHub operations, releases, secrets, and destructive actions.
+- Stack playbooks for Next.js/Vercel/Supabase, React/Vite/static hosting, Expo/EAS, Node APIs, and Firebase.
+- Execution trace template and stronger observability contract for commands, decisions, failures, handoffs, and release evidence.
+- MCP connector policy for Figma, GitHub, browser automation, deployment providers, databases, Canva, npm registries, observability, and AI providers.
+
+### Changed
+
+- `npm test` now validates stack playbooks, permission policy, execution trace requirements, observability rules, and MCP connector policy coverage.
+- README, INDEX, manifest, tool registry, run-state template, and Sagaz skill instructions now expose the new governance and connector contracts.
+- Release governance now requires stronger evidence around permissions, connector usage, workflow traceability, and stack-specific verification.
+
+### Fixed
+
+- Filled remaining non-CLI governance gaps identified after the 0.2.0 release.
+- Reduced ambiguity around cross-platform execution on Windows and macOS inside Codex Desktop.
+
+### Removed
+
+- None.
+
+### Security
+
+- Added explicit permission levels for secrets, destructive actions, external publishing, GitHub operations, package registries, and MCP connectors.
+
+### Compatibility
+
+- Windows: supported through Codex Desktop and locally verified on Windows.
+- macOS: supported through Codex Desktop and covered by GitHub Actions package checks.
+- Node.js: package baseline remains `>=22.14`; Node.js 24 is preferred for new installs and CI.
+- Codex Desktop: Sagaz remains a Codex Desktop orchestration skill, not a standalone terminal agent runtime.
+
+### Migration Notes
+
+- Existing users should run `npx sagaz-ai@0.3.0 sync` or `npx sagaz-ai sync` to refresh the installed Codex Desktop skill.
+- Open a new Codex Desktop thread after syncing so the updated skill can be discovered.
+
+### Verification
+
+- npm test: passed locally on Windows.
+- npm run doctor: passed locally on Windows with `Synchronized with source: yes`.
+- npm pack --dry-run: passed locally on Windows after allowing npm cache access outside the sandbox.
+- Windows: prepared and verified from a Windows Codex Desktop workspace.
+- macOS: package checks remain covered by GitHub Actions.
+- Codex Desktop: skill sync remains required after install or upgrade.
+
+### Release Evidence
+
+- Commit: pending.
+- Tag: pending.
+- GitHub release: pending.
+- npm package: pending.
+
+## [0.2.0] - 2026-06-08
+
+### Release Type
+
+Minor
+
+### Added
+
+- Formal workflow contracts and handoff validation across Sagaz workflows.
+- Stronger durable workflow state contract and run-state template.
+- Task-first contracts for reusable Sagaz task definitions.
+- Internal ecosystem manifest and dependency graph validation.
+- Component governance protocol for creating, updating, renaming, deprecating, and removing ecosystem components.
+- Stronger Sagaz evaluation suite with scenario IDs, required evidence, scoring, and release gates.
+- Release/versioning gate for version bumps, tags, GitHub releases, and npm publishes.
+- GitHub Actions enforcement across Linux, Windows, and macOS package checks.
+- Formal changelog and release notes templates.
+- Installed skill synchronization protocol and `npx sagaz-ai sync` command.
+
+### Changed
+
+- `npm test` now validates workflow contracts, task contracts, manifest coverage, dependency graph integrity, release gates, GitHub Actions enforcement, evaluation coverage, and release artifact templates.
+- `npx sagaz-ai doctor` now checks whether the installed Codex Desktop skill is synchronized with the source skill.
+- README and install documentation now include system requirements, Node.js guidance, platform notes, and skill sync instructions.
+- Package release policy now requires manifest validation, dependency graph validation, evaluation evidence, changelog or release notes, and installed skill sync evidence.
+
+### Fixed
+
+- Corrected malformed Markdown code fences in several protocol files.
+- Added missing references so critical protocols remain reachable from the dependency graph.
+
+### Removed
+
+- None.
+
+### Security
+
+- Release and GitHub operations now require clearer approval gates before publishing, tagging, pushing, or releasing.
+
+### Compatibility
+
+- Windows: supported through Codex Desktop and validated by GitHub Actions on `windows-latest`.
+- macOS: supported through Codex Desktop and validated by GitHub Actions on `macos-latest`.
+- Node.js: package baseline remains `>=22.14`; GitHub Actions use Node.js 24.
+- Codex Desktop: Sagaz remains a Codex Desktop skill, not a standalone terminal agent runtime.
+
+### Migration Notes
+
+- Existing users should run `npx sagaz-ai sync` or `npx sagaz-ai install --force` to refresh the installed Codex Desktop skill.
+- Open a new Codex Desktop thread after syncing so the updated skill can be discovered.
+
+### Verification
+
+- npm test: passed locally on Windows.
+- npm run doctor: passed locally on Windows with `Synchronized with source: yes`.
+- npm pack --dry-run: passed locally on Windows after allowing npm cache access outside the sandbox.
+- Evaluation scenarios: covered by the strengthened `evals/sagaz-evaluation-suite.md` contract.
+
+### Release Evidence
+
+- Commit: pending.
+- Tag: pending.
+- GitHub release: pending.
+- npm package: pending.

package/INSTALL.md

@@ -72,6 +72,7 @@ Sagaz: explain the available workflows.
 ```powershell
 npx sagaz-ai status
 npx sagaz-ai doctor
+npx sagaz-ai sync
 npx sagaz-ai install --force
 ```
 
@@ -80,9 +81,30 @@ npx sagaz-ai install --force
 ```bash
 npx sagaz-ai status
 npx sagaz-ai doctor
+npx sagaz-ai sync
 npx sagaz-ai install --force
 ```
 
+## Sync The Installed Skill
+
+When this repository changes, refresh the installed Codex Desktop skill before relying on new Sagaz behavior.
+
+Windows PowerShell:
+
+```powershell
+npx sagaz-ai sync
+npx sagaz-ai doctor
+```
+
+macOS Terminal:
+
+```bash
+npx sagaz-ai sync
+npx sagaz-ai doctor
+```
+
+Then open a new Codex Desktop thread so the updated skill is discovered.
+
 ## Manual Install
 
 Copy the Sagaz skill folder from the repository.

package/README.md

@@ -43,6 +43,7 @@ Sagaz also guides the user through the process. At the end of each phase, it exp
 - **Static site discipline:** hand-built static sites use clean directory URLs by default, GitHub Pages-ready files, and a practical SEO baseline.
 - **Sagaz evaluations:** scenario-based checks help prevent regressions in the orchestration system itself.
 - **Compatibility audits:** Sagaz can check whether Windows, macOS, npm, Node.js, Codex Desktop, AI model behavior, GitHub, package contents, or external platform changes require a Sagaz update.
+- **Future-change safety:** generated projects include detailed documentation for future refactors, improvements, feature additions, design consistency, UX preservation, invariants, and regression checks.
 
 ## How It Works
 
@@ -75,6 +76,37 @@ Key areas:
 - `brownfield-refactor-safe`: refactor an existing project safely.
 - `bugfix-to-release`: fix a bug through verification and release.
 
+## System Requirements
+
+Install these before using Sagaz:
+
+- **Codex Desktop:** required. Sagaz is designed to run as a Codex Desktop skill, not as a standalone terminal agent.
+- **Node.js and npm:** required for the recommended `npx sagaz-ai install` flow. Use Node.js `22.14+` at minimum; Node.js `24 LTS` is preferred for new installations.
+- **Git:** recommended for cloning this repository, inspecting changes, and using Sagaz GitHub workflows.
+- **Operating system:** Windows or macOS with access to the local Codex skills folder.
+
+Optional but recommended for common Sagaz workflows:
+
+- **GitHub CLI (`gh`):** needed for guided GitHub operations such as authentication, pull requests, checks, issues, releases, and repository automation.
+- **Project runtime tools:** install the tools required by the project Sagaz will work on, such as `pnpm`, `yarn`, `bun`, Python, Java, Android Studio, Xcode, Expo/EAS, or database CLIs when that project needs them.
+- **Browser or web testing tools:** useful for visual QA, Playwright flows, accessibility checks, and local web app verification.
+- **Design/tool connectors:** optional connectors such as Figma MCP can be used when available for app-like mockups, design systems, and visual QA.
+
+Verify the core local tools:
+
+```bash
+node --version
+npm --version
+git --version
+```
+
+Verify GitHub CLI only if you want GitHub Ops:
+
+```bash
+gh --version
+gh auth status
+```
+
 ## Installation In Codex Desktop
 
 ### Recommended: Install With npx
@@ -105,6 +137,7 @@ Check installation:
 ```powershell
 npx sagaz-ai status
 npx sagaz-ai doctor
+npx sagaz-ai sync
 ```
 
 #### macOS Terminal
@@ -124,8 +157,11 @@ Check installation:
 ```bash
 npx sagaz-ai status
 npx sagaz-ai doctor
+npx sagaz-ai sync
 ```
 
+Use `npx sagaz-ai sync` after updating this repository or package to refresh the installed Codex Desktop skill. Then open a new Codex Desktop thread so Sagaz is rediscovered.
+
 Then open a new Codex Desktop thread and run:
 
 ```text
@@ -206,6 +242,8 @@ Sagaz should choose the appropriate workflow, create or update persistent run st
 
 For production-grade work, Sagaz can also apply SRE readiness, DORA metrics, secure SDLC, dependency governance, data privacy lifecycle, architecture fitness functions, API contracts, performance budgets, accessibility compliance, database migrations, release strategy, and AI application quality protocols.
 
+For medium, large, production, web, mobile, refactor, or feature-extension work, Sagaz should create or update a future-change guide covering product intent, architecture, design system, UX rules, components, invariants, testing, safe refactor procedure, safe feature-addition procedure, deployment, and known risks.
+
 For tool-heavy work, Sagaz uses a tool registry to verify local availability and recommend the right connector or platform before asking permission to install, authenticate, deploy, publish, or modify external resources.
 
 For common project types, Sagaz can start from documented stack presets such as Next.js on Vercel, React with Vite, Expo mobile, React Native, Supabase, Firebase, Node APIs, static sites, and admin dashboards. For hand-built static sites, Sagaz should default to clean URLs through directory `index.html` files and verify SEO essentials including canonical URLs, Open Graph/Twitter metadata, Schema.org JSON-LD, sitemap, robots, optimized images, and GitHub Pages files when applicable.

package/RELEASE_NOTES.md

@@ -0,0 +1,83 @@
+# Release Notes
+
+## Release
+
+Version: 0.3.0
+Date: 2026-06-11
+Release type: Minor
+GitHub commit: pending
+Git tag: pending
+GitHub release: pending
+npm package: pending
+
+## Summary
+
+Sagaz 0.3.0 completes the main non-CLI governance layer for Codex Desktop orchestration. It adds operational runbooks, complete scenario examples, a capabilities matrix, formal permission policy, stack playbooks, execution trace evidence, and MCP connector governance.
+
+## Audience Impact
+
+- New users: clearer operating model, examples, stack guidance, and permission expectations before using Sagaz.
+- Existing users: should refresh the installed skill with `npx sagaz-ai sync`.
+- Maintainers: stronger package checks now catch stack playbook, observability, permission, and connector-policy drift.
+- Design team: Figma MCP usage is governed as a formal connector workflow for app-like mockups and design artifacts.
+- Engineering team: workflow evidence now includes traceable commands, decisions, failures, permissions, and handoffs.
+
+## What Changed
+
+- Added an operations runbook for everyday Sagaz use.
+- Added complete examples for common delivery scenarios.
+- Added a capabilities matrix against other orchestration ecosystems.
+- Added a formal permission contract for Windows and macOS Codex Desktop usage.
+- Added stack-specific playbooks.
+- Added an execution trace template and stronger observability protocol.
+- Added MCP connector policy across design, deploy, package, data, browser, and AI providers.
+- Expanded package verification to enforce the new governance files.
+
+## Why It Matters
+
+Sagaz now has clearer rules for how agents should choose tools, request permission, preserve workflow state, hand off work, verify stack-specific outcomes, and operate MCP connectors without drifting into ad hoc behavior.
+
+## Compatibility
+
+- Windows: supported and locally verified from a Codex Desktop workspace.
+- macOS: supported through Codex Desktop and GitHub Actions runner validation.
+- Node.js: `>=22.14` remains the package minimum; Node.js 24 is preferred for new installs and CI.
+- Codex Desktop: required.
+- GitHub Actions: package checks run on Ubuntu, Windows, and macOS.
+- npm package: still an installer/distribution package, not a standalone Sagaz runtime.
+
+## Migration Notes
+
+Run:
+
+```bash
+npx sagaz-ai@0.3.0 sync
+npx sagaz-ai doctor
+```
+
+Then open a new Codex Desktop thread so Sagaz is rediscovered.
+
+## Verification
+
+- `npm test`: passed locally on Windows.
+- `npm run doctor`: passed locally on Windows with installed skill synchronization confirmed.
+- `npm pack --dry-run`: passed locally on Windows after npm cache access was allowed outside the sandbox.
+- Manual checks: Git status reviewed before release preparation.
+
+## Known Limitations
+
+- Sagaz still intentionally skips a standalone CLI runtime; Codex Desktop remains the execution surface.
+- GitHub release and npm publishing remain explicit approval steps.
+- Connector behavior depends on each external MCP/app authorization and platform availability.
+
+## Rollback Plan
+
+- Revert the release commit if the GitHub repository update fails.
+- If published to npm, publish a patch version that restores the previous known-good package contents.
+- Users can reinstall a previous npm version with `npx sagaz-ai@<version> install --force` if needed.
+
+## Release Decision
+
+Approved by: Thiago Cabral
+Approval date: 2026-06-11
+Residual risk: GitHub Actions and npm publishing still need remote execution after push.

package/ai-orchestration-ecosystem/INDEX.md

@@ -5,6 +5,7 @@
 - `ACTIVATE.md`: ready-to-use activation prompts.
 - `quickstart.md`: minimum operating rules.
 - `README.md`: ecosystem overview.
+- `manifest.json`: internal component registry for validation and navigation.
 
 ## Core
 
@@ -50,17 +51,29 @@ See `protocols/` for quality gates, testing matrix, stack selection, design qual
 - `protocols/dora-metrics.md`
 - `protocols/secure-sdlc.md`
 - `protocols/dependency-governance.md`
+- `protocols/dependency-graph-validation.md`
 - `protocols/data-privacy-lifecycle.md`
 - `protocols/architecture-fitness-functions.md`
 - `protocols/api-contracts.md`
 - `protocols/performance-budgets.md`
 - `protocols/accessibility-compliance.md`
 - `protocols/database-migrations.md`
+- `protocols/release-versioning-gate.md`
 - `protocols/release-strategy.md`
 - `protocols/ai-application-quality.md`
 - `protocols/agent-observability.md`
+- `protocols/component-governance.md`
+- `protocols/communication.md`
+- `protocols/delegation.md`
 - `protocols/durable-run-state.md`
 - `protocols/compatibility-update-audit.md`
+- `protocols/future-change-safety.md`
+- `protocols/installed-skill-sync.md`
+- `protocols/memory.md`
+- `protocols/model-routing.md`
+- `protocols/mcp-connector-policy.md`
+- `protocols/permission-contract.md`
+- `protocols/post-delivery-monitoring.md`
 
 ## Tools
 
@@ -78,6 +91,15 @@ See `protocols/` for quality gates, testing matrix, stack selection, design qual
 - `stack-presets/static-site.md`
 - `stack-presets/admin-dashboard.md`
 
+## Stack Playbooks
+
+- `stack-playbooks/README.md`
+- `stack-playbooks/nextjs-vercel-supabase.md`
+- `stack-playbooks/react-vite-static.md`
+- `stack-playbooks/expo-eas.md`
+- `stack-playbooks/node-api.md`
+- `stack-playbooks/firebase.md`
+
 ## Evaluations
 
 - `evals/sagaz-evaluation-suite.md`
@@ -85,13 +107,21 @@ See `protocols/` for quality gates, testing matrix, stack selection, design qual
 ## Examples
 
 - `examples/README.md`
+- `examples/web-saas-vercel.md`
+- `examples/mobile-habit-tracker.md`
+- `examples/bugfix-production-release.md`
+- `examples/brownfield-refactor.md`
 
 ## Templates
 
-See `templates/` for task briefs, product specs, technical specs, design systems, stack recommendations, run state, squad handoffs, QA reports, release checklists, changelogs, release notes, and final handoffs.
+See `templates/` for task briefs, product specs, technical specs, design systems, future-change guides, refactor safety contracts, stack recommendations, run state, squad handoffs, QA reports, release checklists, changelogs, release notes, and final handoffs.
+
+- `templates/execution-trace.md`
 
 ## Governance
 
+- `governance/capabilities-matrix.md`
+- `governance/operations-runbook.md`
 - `governance/quality-policy.md`
 - `governance/security-policy.md`
 - `governance/versioning.md`

package/ai-orchestration-ecosystem/README.md

@@ -4,20 +4,24 @@ A local AI orchestration ecosystem for Codex, focused on autonomous teams, consi
 
 ## How To Use
 
-1. Read `quickstart.md`.
-2. Choose the smallest sufficient workflow or squad.
-3. Use formal tasks, handoffs, and quality gates.
-4. Create or update run state for medium/large work.
-5. Verify before declaring done.
+1. Read `governance/operations-runbook.md` for the daily operating procedure.
+2. Read `quickstart.md`.
+3. Choose the smallest sufficient workflow or squad.
+4. Use formal tasks, handoffs, and quality gates.
+5. Create or update run state for medium/large work.
+6. Verify before declaring done.
 
 ## Structure
 
+- `manifest.json`: internal component registry used to validate and navigate the ecosystem.
 - `workflows/`: named end-to-end flows.
 - `squads/`: specialized teams.
 - `agents/`: role definitions.
 - `tasks/`: formal task contracts.
 - `protocols/`: operating rules and quality gates.
+- `stack-playbooks/`: operational guides for common stack implementation, verification, and deployment.
 - `templates/`: reusable Markdown artifacts.
+- `examples/`: complete web, mobile, bugfix, and refactor flow examples.
 - `engineering/`: software engineering standards.
 - `governance/`: quality, security, and maintenance policies.
 
@@ -25,6 +29,22 @@ A local AI orchestration ecosystem for Codex, focused on autonomous teams, consi
 
 No delivery is complete without verification evidence proportional to the risk.
 
+## Ecosystem Maintenance
+
+Use `manifest.json` as the component registry and `protocols/component-governance.md` when creating, updating, renaming, deprecating, or removing Sagaz ecosystem components.
+
+Use `protocols/release-versioning-gate.md` before version bumps, Git tags, GitHub releases, or npm publishes. A Sagaz release is not ready until package checks, doctor, manifest coverage, dependency graph validation, relevant evaluation scenarios, and changelog or release notes are complete.
+
+Use `protocols/installed-skill-sync.md` after changing the Sagaz skill or release rules so the installed Codex Desktop skill does not drift from the repository copy.
+
+Use `governance/capabilities-matrix.md` when comparing Sagaz with CrewAI, AutoGen, LangChain, LangGraph, AIOX, Synkra, or similar orchestration systems.
+
+Use `protocols/permission-contract.md` before actions that change local state, remote state, accounts, deployments, packages, credentials, or GitHub history.
+
+Use `protocols/agent-observability.md` and `templates/execution-trace.md` for multi-phase, production, release, deployment, package, or high-risk work.
+
+Use `protocols/mcp-connector-policy.md` before using MCPs or external connectors such as Figma, GitHub, Canva, Browser, Vercel, Supabase, Firebase, npm, or observability tools.
+
 ## Advanced Engineering Coverage
 
 Sagaz includes protocols for SRE readiness, DORA metrics, secure SDLC, dependency governance, data privacy lifecycle, architecture fitness functions, API contracts, performance budgets, accessibility compliance, database migrations, release strategy, and AI application quality.

package/ai-orchestration-ecosystem/agents/ui-systems-designer.md

@@ -9,6 +9,8 @@ Create design systems, tokens, components, and consistent visual rules.
 - Define colors, typography, spacing, radii, borders, elevation, icons, and motion.
 - Create base components and variants.
 - Standardize forms, feedback, cards, tables, navigation, and modals.
+- When Figma MCP is available, create implementation-ready Figma components, variants, tokens, and screen frames for the mockup.
+- Ensure Figma components map cleanly to the chosen frontend stack, component library, or internal design system.
 
 ## Standard Output
 
@@ -16,5 +18,6 @@ Create design systems, tokens, components, and consistent visual rules.
 - Component inventory
 - Responsive rules
 - Component states
+- Figma component and frame plan when applicable
 - Consistency checklist
 

package/ai-orchestration-ecosystem/agents/ux-architect.md

@@ -10,6 +10,8 @@ Design flows, journeys, information architecture, and interactions that reduce f
 - Map happy paths, errors, and empty states.
 - Organize navigation and information hierarchy.
 - Set usability criteria.
+- When Figma MCP is available, define navigable mockup flows that behave like the intended application.
+- Specify interaction states, transitions, and screen-to-screen behavior clearly enough for implementation.
 
 ## Standard Output
 
@@ -17,5 +19,6 @@ Design flows, journeys, information architecture, and interactions that reduce f
 - Navigation map
 - Screen states
 - Interaction requirements
+- Figma mockup flow requirements when applicable
 - Usability criteria
 

package/ai-orchestration-ecosystem/agents/visual-qa.md

@@ -10,10 +10,13 @@ Validate interfaces visually before delivery and block layout, hierarchy, respon
 - Find overlap, overflow, misalignment, clipping, and weak contrast.
 - Validate interactive states.
 - Compare implementation against the design system.
+- When Figma MCP was used, inspect Figma frames or screenshots before handoff and verify that the mockup supports the intended user journeys.
+- Confirm that the mockup includes realistic states and does not create impossible implementation expectations.
 
 ## Standard Output
 
 - Viewports tested
+- Figma frames or screenshots reviewed when applicable
 - Issues found
 - Recommended fixes
 - Verdict