sagaz-ai 0.3.1 → 0.3.2

package/CHANGELOG.md

@@ -1,5 +1,62 @@
 # Changelog
 
+## [0.3.2] - 2026-06-11
+
+### Release Type
+
+Patch
+
+### Added
+
+- Operational memory protocol for recurring project and team preferences across Sagaz runs.
+- Operational memory template for `.sagaz/operational-memory.md` style project memory.
+- Package validation for operational memory sections, safety terms, permission references, and template structure.
+
+### Changed
+
+- README, ecosystem README, INDEX, and manifest now expose operational memory as an official Sagaz capability.
+
+### Fixed
+
+- Replaced the previous generic memory protocol with a concrete approval-based operational memory contract.
+
+### Removed
+
+- None.
+
+### Security
+
+- Operational memory explicitly forbids secrets, credentials, session data, production data, and sensitive personal data.
+- Durable project or team memory requires explicit user approval.
+
+### Compatibility
+
+- Windows: supported through Codex Desktop.
+- macOS: supported through Codex Desktop.
+- 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.2 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 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.3.1] - 2026-06-11
 
 ### Release Type

package/README.md

@@ -36,6 +36,7 @@ Sagaz also guides the user through the process. At the end of each phase, it exp
 - **GitHub without guesswork:** Sagaz recommends commits, pushes, pull requests, issues, and releases at the right time.
 - **Web and mobile:** workflows for browser apps, websites, dashboards, Android, and iOS.
 - **Persistent state:** Markdown run state records decisions, approvals, handoffs, risks, and test evidence.
+- **Operational memory:** optional project or team memory records recurring preferences without storing secrets or bypassing approvals.
 - **Agent observability:** compact traces record decisions, tools, evidence, failures, and recoveries.
 - **Durable checkpoints:** long projects can resume across threads and refactors without losing context.
 - **Tool registry:** Sagaz verifies and recommends tools such as GitHub CLI, Playwright, Vercel, Expo/EAS, Supabase, Firebase, Stripe, CI/CD, and observability services.

package/RELEASE_NOTES.md

@@ -2,7 +2,7 @@
 
 ## Release
 
-Version: 0.3.1
+Version: 0.3.2
 Date: 2026-06-11
 Release type: Patch
 GitHub commit: pending
@@ -12,25 +12,26 @@ npm package: pending
 
 ## Summary
 
-Sagaz 0.3.1 adds the official adoption guide for using Sagaz in another project after installation. It documents the first-use flow, team operating model, invocation prompts, Windows/macOS notes, permission expectations, and evidence artifacts.
+Sagaz 0.3.2 adds operational memory: a safe, explicit, approval-based way to record recurring project and team preferences across Sagaz runs without storing secrets or bypassing current user instructions.
 
 ## Audience Impact
 
-- New users: clearer first real step after installing Sagaz.
-- Existing users: can sync the installed skill and follow the adoption guide from a fresh Codex Desktop thread.
-- Teams: get a practical onboarding path before applying Sagaz to production work.
-- Maintainers: package validation now tracks the adoption guide in the ecosystem manifest.
+- New users: can understand how Sagaz handles recurring preferences before using it across multiple projects.
+- Existing users: can sync the installed skill and use the new memory protocol/template in real projects.
+- Teams: get a safer shared preference artifact for stack, design, verification, GitHub, deployment, and handoff expectations.
+- Maintainers: package validation now protects the memory protocol and template from accidental drift.
 
 ## What Changed
 
-- Added `ai-orchestration-ecosystem/ADOPTION.md`.
-- Linked the adoption guide from the root README, ecosystem README, and ecosystem INDEX.
-- Registered the adoption guide in `manifest.json`.
-- Updated package verification so the docs group validates the new guide.
+- Replaced the generic `protocols/memory.md` with a concrete operational memory contract.
+- Added `templates/operational-memory.md`.
+- Registered the memory template in `manifest.json`.
+- Linked operational memory from README, ecosystem README, and INDEX.
+- Added verifier checks for memory levels, approval language, storage path, sensitive-data exclusions, and required template fields.
 
 ## Why It Matters
 
-After `0.3.0`, Sagaz had strong governance but needed a direct bridge between installation and first use in a real project. This patch gives teams a safe starting prompt, explains what Sagaz should inspect first, and reinforces permission gates before risky actions.
+Sagaz can now carry stable preferences between projects in an auditable way while still respecting the current repository, current user request, and explicit permission gates. The memory system is intentionally file-based, reviewable, and scoped.
 
 ## Compatibility
 
@@ -45,7 +46,7 @@ After `0.3.0`, Sagaz had strong governance but needed a direct bridge between in
 Run:
 
 ```bash
-npx sagaz-ai@0.3.1 sync
+npx sagaz-ai@0.3.2 sync
 npx sagaz-ai doctor
 ```
 
@@ -56,11 +57,12 @@ Then open a new Codex Desktop thread so Sagaz is rediscovered.
 - `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: adoption guide linked from README, INDEX, and manifest.
+- Manual checks: memory protocol and template are registered in the manifest and linked from docs.
 
 ## Known Limitations
 
 - Sagaz still intentionally skips a standalone CLI runtime; Codex Desktop remains the execution surface.
+- Operational memory is advisory and must not override current user instructions or repository evidence.
 - Connector behavior depends on each external MCP/app authorization and platform availability.
 
 ## Rollback Plan

package/ai-orchestration-ecosystem/INDEX.md

@@ -118,6 +118,7 @@ See `protocols/` for quality gates, testing matrix, stack selection, design qual
 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`
+- `templates/operational-memory.md`
 
 ## Governance
 

package/ai-orchestration-ecosystem/README.md

@@ -47,6 +47,8 @@ Use `protocols/agent-observability.md` and `templates/execution-trace.md` for mu
 
 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.
 
+Use `protocols/memory.md` and `templates/operational-memory.md` before creating durable project or team preferences for future Sagaz runs.
+
 ## 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/manifest.json

@@ -122,6 +122,7 @@
       "templates/implementation-plan.md",
       "templates/execution-trace.md",
       "templates/mobile-release-checklist.md",
+      "templates/operational-memory.md",
       "templates/product-spec.md",
       "templates/qa-report.md",
       "templates/refactor-safety-contract.md",

package/ai-orchestration-ecosystem/protocols/memory.md

@@ -1,32 +1,148 @@
-# Protocol: Memory
+# Protocol: Operational Memory
 
 ## Objective
 
-Define how Sagaz should handle Memory while keeping the process clear, low-token, safe, and verifiable.
+Define how Sagaz records recurring user, team, stack, delivery, and quality preferences across projects without storing secrets, private data, or unverified assumptions as durable memory.
+
+Operational memory is a lightweight project or team artifact. It is not a hidden database, not a substitute for current project inspection, and not permission to act without approval.
+
+## Scope
+
+Use this protocol for preferences that are stable enough to help future Sagaz runs, such as:
+
+- Preferred stack defaults.
+- Design and UX expectations.
+- Testing and verification habits.
+- GitHub, branch, commit, pull request, and release preferences.
+- Deployment and hosting preferences.
+- Communication and handoff style.
+- Team-specific stop conditions.
+- Recurring constraints for Windows, macOS, or Codex Desktop.
+
+Do not use operational memory for:
+
+- Secrets, tokens, passwords, keys, credentials, or session data.
+- Personal sensitive data.
+- Production data.
+- Legal, financial, medical, or employment decisions.
+- Temporary guesses that were not confirmed by the user.
+- Instructions that conflict with the current user request, repository state, or `protocols/permission-contract.md`.
+
+## Memory Levels
+
+- `M0 ephemeral`: context useful only inside the current response or tool step.
+- `M1 thread`: context useful for the current Codex Desktop thread.
+- `M2 project`: preferences useful for the current repository or workspace.
+- `M3 team`: preferences the user explicitly wants Sagaz to remember across projects.
+
+Sagaz may infer M0 and M1 from the current conversation. M2 and M3 require explicit user approval before being written or updated.
 
 ## Required Practice
 
-- Start from the user goal and current project state.
-- Load only relevant context.
-- Separate facts, assumptions, inferences, risks, and decisions.
-- Ask permission before meaningful state changes.
-- Record evidence and residual risk.
+1. Inspect current project state before applying memory to a concrete task.
+2. Treat memory as advisory, not authoritative.
+3. Prefer current user instructions over stored preferences.
+4. Ask before creating or updating M2 or M3 memory.
+5. Record source, date, owner, confidence, scope, and expiry for each durable entry.
+6. Keep memory compact and easy to audit.
+7. Reconfirm stale or risky preferences before using them.
+8. Use `templates/operational-memory.md` for durable M2 or M3 entries.
+9. Reference `protocols/permission-contract.md` before any action that changes local state, remote state, deployments, packages, billing, credentials, or GitHub history.
+10. Reference `protocols/agent-observability.md` when memory affects a multi-phase or high-risk workflow.
 
-## Standard Recommendation Format
+## Approval Rules
+
+Sagaz must ask explicit approval before:
+
+- Creating a project memory file.
+- Adding a new durable preference.
+- Promoting a thread preference to project or team memory.
+- Applying a stored preference that affects architecture, cost, security, data, deployment, release, or public output.
+- Removing, renaming, or changing the meaning of an existing durable preference.
+
+Approval prompt format:
 
 ```md
-Recommendation:
-Why now:
-What changes:
-Benefit:
+Memory update proposed:
+Scope:
+Preference:
+Source:
+Why it helps:
 Risk:
-Permission required:
+Expiry or review date:
+Approval needed:
+```
+
+## Storage Convention
+
+Preferred project-local path:
+
+```text
+.sagaz/operational-memory.md
+```
+
+If the project should not store Sagaz artifacts, use a user-approved location and record that location in the handoff.
+
+Do not create hidden memory outside the workspace without explicit user approval.
+
+## Entry Format
+
+Each durable memory entry must include:
+
+```md
+Preference ID:
+Scope: M2 project | M3 team
+Status: active | proposed | deprecated
+Owner:
+Source:
+Created:
+Last reviewed:
+Review by:
+Confidence: low | medium | high
+Preference:
+Applies when:
+Do not apply when:
+Permission impact:
+Evidence:
 ```
+
+## Conflict Handling
+
+When memory conflicts with a current instruction or repository evidence:
+
+1. Follow the current user instruction when it is safe and clear.
+2. Explain the conflict briefly.
+3. Ask before updating or deprecating the memory entry.
+4. Record the decision in run state or execution trace when the task is meaningful.
+
+## Review And Expiry
+
+Use review dates to prevent stale preferences from becoming invisible defaults.
+
+- M2 project memory should be reviewed after major stack, deployment, or team changes.
+- M3 team memory should be reviewed at least every 90 days or before a major release.
+- Any memory involving cost, security, compliance, deployment, or public communication should be reconfirmed before use when stale.
+
 ## Blocking Conditions
 
-- The primary flow fails.
-- A relevant build, check, or test fails without explanation.
-- Secrets or sensitive data would be exposed.
-- A high risk is not accepted by the user.
-- Verification evidence is missing for the risk level.
-
+- The user has not approved durable memory creation or update.
+- The proposed memory includes secrets or sensitive data.
+- The memory conflicts with `protocols/permission-contract.md`.
+- The current repository state contradicts the stored preference and the conflict is not resolved.
+- The memory would cause unapproved external operations, publishing, deployment, billing, or destructive changes.
+- The memory entry lacks source, scope, or review date.
+
+## Output
+
+When using operational memory, Sagaz should say:
+
+```md
+Memory used:
+Scope:
+Source:
+Applied to:
+Confidence:
+Permission impact:
+```
+
+When proposing a memory update, Sagaz should ask for approval using the approval prompt format and wait for the user before writing durable memory.

package/ai-orchestration-ecosystem/templates/operational-memory.md

@@ -0,0 +1,49 @@
+# Operational Memory
+
+## Metadata
+
+```yaml
+project:
+owner:
+scope: M2 project
+created:
+last_reviewed:
+review_by:
+storage_location:
+```
+
+## Operating Rules
+
+- Use this file only with `protocols/memory.md`.
+- Do not store secrets, tokens, passwords, keys, credentials, session data, production data, or sensitive personal data.
+- Current user instructions and current repository state override stored preferences.
+- Reconfirm stale, risky, or high-impact preferences before use.
+
+## Preferences
+
+| Preference ID | Scope | Status | Owner | Source | Created | Last reviewed | Review by | Confidence |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| MEM-001 | M2 project | proposed |  |  |  |  |  | medium |
+
+## Preference Details
+
+### MEM-001
+
+Preference:
+
+Applies when:
+
+Do not apply when:
+
+Permission impact:
+
+Evidence:
+
+Notes:
+
+## Deprecated Preferences
+
+Move old preferences here instead of deleting them when history is useful.
+
+| Preference ID | Deprecated on | Reason | Replacement |
+| --- | --- | --- | --- |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sagaz-ai",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Sagaz AI orchestration ecosystem installer for Codex Desktop.",
   "type": "module",
   "bin": {

package/scripts/verify-package.js

@@ -813,6 +813,85 @@ function validateMcpConnectorPolicy() {
   }
 }
 
+function validateOperationalMemoryProtocol() {
+  const file = path.join(ecosystemRoot, "protocols", "memory.md");
+  if (!fs.existsSync(file)) {
+    fail(file, "operational memory protocol is missing");
+    return;
+  }
+
+  const text = readText(file);
+  const present = headings(text);
+  for (const section of [
+    "Objective",
+    "Scope",
+    "Memory Levels",
+    "Required Practice",
+    "Approval Rules",
+    "Storage Convention",
+    "Entry Format",
+    "Conflict Handling",
+    "Review And Expiry",
+    "Blocking Conditions",
+    "Output"
+  ]) {
+    if (!present.has(section)) {
+      fail(file, `missing section "${section}"`);
+    }
+  }
+
+  for (const term of [
+    "templates/operational-memory.md",
+    "protocols/permission-contract.md",
+    "protocols/agent-observability.md",
+    ".sagaz/operational-memory.md",
+    "M0 ephemeral",
+    "M1 thread",
+    "M2 project",
+    "M3 team",
+    "secrets",
+    "sensitive data",
+    "explicit user approval",
+    "Approval needed:",
+    "Review by:",
+    "Permission impact:"
+  ]) {
+    if (!text.includes(term)) {
+      fail(file, `operational memory protocol must mention "${term}"`);
+    }
+  }
+}
+
+function validateOperationalMemoryTemplate() {
+  const file = path.join(ecosystemRoot, "templates", "operational-memory.md");
+  if (!fs.existsSync(file)) {
+    fail(file, "operational memory template is missing");
+    return;
+  }
+
+  const text = readText(file);
+  const present = headings(text);
+  for (const section of ["Metadata", "Operating Rules", "Preferences", "Preference Details", "Deprecated Preferences"]) {
+    if (!present.has(section)) {
+      fail(file, `missing section "${section}"`);
+    }
+  }
+
+  for (const term of [
+    "protocols/memory.md",
+    "Do not store secrets",
+    "Current user instructions",
+    "Preference ID",
+    "Permission impact",
+    "Evidence",
+    "Review by"
+  ]) {
+    if (!text.includes(term)) {
+      fail(file, `operational memory template must mention "${term}"`);
+    }
+  }
+}
+
 function validateDurableRunStateProtocol() {
   const file = path.join(ecosystemRoot, "protocols", "durable-run-state.md");
   if (!fs.existsSync(file)) {
@@ -1561,6 +1640,8 @@ validateExecutionTraceTemplate();
 validateDurableRunStateProtocol();
 validateAgentObservabilityProtocol();
 validateMcpConnectorPolicy();
+validateOperationalMemoryProtocol();
+validateOperationalMemoryTemplate();
 validateComponentGovernanceProtocol();
 validateEvaluationSuite();
 validateReleaseVersioningGate();