maestro-flow 0.4.21 → 0.4.23

package/.agy/skills/maestro-milestone-release/SKILL.md

@@ -17,6 +17,8 @@ allowed-tools:
 
 <purpose>
 Package a completed milestone into a releasable version. Bumps the project version (e.g. `package.json`, `pyproject.toml`, or language-specific manifest), generates or appends a changelog entry from phase/milestone summaries and git log, creates an annotated git tag, and optionally pushes to the remote. Runs after `/maestro-milestone-complete` has archived the milestone; serves as the final delivery step in the SDLC loop.
+
+Pipeline position: downstream of `/maestro-milestone-complete` (consumes archived milestone + audit verdict). Terminal command — no downstream consumer.
 </purpose>
 
 <required_reading>
@@ -27,11 +29,14 @@ Package a completed milestone into a releasable version. Bumps the project versi
 $ARGUMENTS -- optional explicit version string and flags.
 
 **Flags:**
-- `<version>` -- explicit version (e.g. `1.2.0`). If omitted, version is derived from `--bump` or prompted.
-- `--bump patch|minor|major` -- semver bump relative to the current version (default: `minor`)
-- `--dry-run` -- compute the next version, changelog diff, and tag name without writing files or creating tags
-- `--no-tag` -- skip git tag creation (version bump + changelog only)
-- `--no-push` -- skip `git push --follow-tags` after tagging
+
+| Flag | Effect | Default |
+|------|--------|---------|
+| `<version>` | Explicit version (e.g. `1.2.0`). If omitted, version is derived from `--bump` or prompted | — |
+| `--bump patch\|minor\|major` | Semver bump relative to the current version | `minor` |
+| `--dry-run` | Compute the next version, changelog diff, and tag name without writing files or creating tags | `false` |
+| `--no-tag` | Skip git tag creation (version bump + changelog only) | `false` |
+| `--no-push` | Skip `git push --follow-tags` after tagging | `false` |
 
 **State files:**
 - `.workflow/state.json` -- current_milestone, previous release version
@@ -45,6 +50,13 @@ $ARGUMENTS -- optional explicit version string and flags.
 - Working tree must be clean (no uncommitted changes) unless `--dry-run`
 </context>
 
+<interview_protocol>
+Follows @~/.maestro/workflows/interview-mechanics.md standard.
+
+**Decision points**: version bump type (major / minor / patch / custom), changelog review and confirmation
+**Scope guard**: only release decisions; do not prejudge next milestone scope
+</interview_protocol>
+
 <execution>
 Follow '~/.maestro/workflows/milestone-release.md' completely.
 
@@ -57,7 +69,12 @@ Follow '~/.maestro/workflows/milestone-release.md' completely.
 6. Create annotated git tag `v{version}` with release notes body (unless `--no-tag`)
 7. Push commit + tag to remote (unless `--no-push`)
 
-**Report format on completion:**
+For `--dry-run`, print the computed version, changelog diff, and tag name without side effects.
+</execution>
+
+<completion>
+### Standalone report
+
 ```
 === RELEASE COMPLETE ===
 Version:   v{previous} → v{new}
@@ -65,14 +82,28 @@ Milestone: {milestone_name}
 Tag:       v{new} {pushed|local-only}
 Changelog: {N} entries written to CHANGELOG.md
 Manifest:  {file_path} updated
+```
+
+### Ralph-invoked completion
 
-Next steps:
-  /maestro-plan {next_phase}   -- Start next milestone's first phase
-  /manage-status               -- View project dashboard
+End the step by calling the CLI (no text block output):
+```
+maestro ralph complete <idx> --status {STATUS} [--evidence {path}]
 ```
 
-For `--dry-run`, print the computed version, changelog diff, and tag name without side effects.
-</execution>
+Status verdicts:
+- **DONE** — Normal completion
+- **DONE_WITH_CONCERNS** — Completed with caveats; pass `--concerns`
+- **NEEDS_RETRY** — Tooling error / transient issue; ralph will retry
+- **BLOCKED** — External hard blocker; pass `--reason`
+
+### Next-step routing
+
+| Condition | Suggestion |
+|-----------|-----------|
+| Release successful, starting next milestone | `/maestro-plan {next_phase}` |
+| Want to view project dashboard | `/manage-status` |
+</completion>
 
 <error_codes>
 | Code | Severity | Condition | Recovery |

package/.agy/skills/maestro-plan/SKILL.md

@@ -122,7 +122,13 @@ For each created TASK-{NNN}.json that has issue_id:
 
 This ensures issue → TASK traceability. The `task_refs[]` and `task_plan_dir` fields on the issue allow the dashboard to resolve and display associated TASK details.
 
-**Report format on completion:**
+### Mode: Revise / Check
+
+Follow workflow plan.md § "Revise Mode" and § "Check Mode" respectively. These modes bypass the standard P1-P5 create pipeline.
+</execution>
+
+<completion>
+### Standalone report
 
 ```
 === PLAN READY ===
@@ -133,20 +139,16 @@ Collision: {collision_status}
 
 Plan: scratch/{YYYYMMDD}-plan-P{N}-{slug}/plan.json
 Tasks: scratch/{YYYYMMDD}-plan-P{N}-{slug}/.task/TASK-*.json
-
-Next steps:
-  /maestro-execute              -- Execute the plan
-  /maestro-execute --dir {dir}  -- Execute specific plan
-  /maestro-plan {phase}         -- Re-plan with modifications
 ```
 
-**Completion (when invoked from ralph):**
-End the step by calling the CLI (no `--- COMPLETION STATUS ---` text block):
+### Ralph-invoked completion
+
+End the step by calling the CLI (no text block output):
 ```
-maestro ralph complete <idx> --status DONE [--evidence scratch/{YYYYMMDD}-plan-P{N}-{slug}/plan.json]
+maestro ralph complete <idx> --status {STATUS} [--evidence scratch/{YYYYMMDD}-plan-P{N}-{slug}/plan.json]
 ```
 
-STATUS verdicts (CLI-enforced enum):
+Status verdicts:
 - **DONE** — Plan created/revised and confirmed → next step picks up automatically
 - **DONE_WITH_CONCERNS** — Plan produced but with explicit caveats; pass `--concerns "..."`
 - **NEEDS_RETRY** — Plan failed (tooling error, transient issue); ralph will retry
@@ -154,10 +156,14 @@ STATUS verdicts (CLI-enforced enum):
 
 > Ambiguous requirements are NOT a completion status — resolve them in-place via `ask_question` during planning (≤3 rounds), then proceed to DONE. `NEEDS_CONTEXT` has been removed; context shortage is handled by the harness's automatic compaction.
 
-### Mode: Revise / Check
+### Next-step routing
 
-Follow workflow plan.md § "Revise Mode" and § "Check Mode" respectively. These modes bypass the standard P1-P5 create pipeline.
-</execution>
+| Condition | Suggestion |
+|-----------|-----------|
+| Plan confirmed for execution | `/maestro-execute` |
+| Plan confirmed, specific directory | `/maestro-execute --dir {dir}` |
+| Re-plan with modifications | `/maestro-plan {phase}` |
+</completion>
 
 <error_codes>
 | Code | Severity | Condition | Recovery |

package/.agy/skills/maestro-roadmap/SKILL.md

@@ -38,13 +38,16 @@ For formal specification documents (Product Brief, PRD, Architecture, Epics), us
 $ARGUMENTS -- requirement text, @file reference, or upstream context source.
 
 **Flags:**
-- `-y` / `--yes`: Auto mode — skip interactive questions, use recommended defaults
-- `-c` / `--continue`: Resume from last checkpoint
-- `-m progressive|direct|auto`: Decomposition strategy (default: auto)
-- `--from <source>`: Load upstream context package (brainstorm:ID, blueprint:BLP-xxx, analyze:ANL-xxx, @file, or path). Consumes context-package.json
-- `--from-brainstorm SESSION-ID`: (backward compat alias for `--from brainstorm:ID`)
-- `--revise [instructions]`: Revise existing roadmap. If instructions provided, apply directly. If omitted, ask user. Preserves completed phase progress.
-- `--review`: Roadmap health assessment (read-only)
+
+| Flag | Effect | Default |
+|------|--------|---------|
+| `-y` / `--yes` | Auto mode — skip interactive questions, use recommended defaults | false |
+| `-c` / `--continue` | Resume from last checkpoint | false |
+| `-m progressive\|direct\|auto` | Decomposition strategy | auto |
+| `--from <source>` | Load upstream context package (brainstorm:ID, blueprint:BLP-xxx, analyze:ANL-xxx, @file, or path). Consumes context-package.json | — |
+| `--from-brainstorm SESSION-ID` | Backward compat alias for `--from brainstorm:ID` | — |
+| `--revise [instructions]` | Revise existing roadmap. If instructions provided, apply directly. If omitted, ask user. Preserves completed phase progress. | — |
+| `--review` | Roadmap health assessment (read-only) | — |
 
 **Input types:**
 - Direct text: `"Implement user authentication system with OAuth and 2FA"`
@@ -63,24 +66,22 @@ maestro-roadmap → .workflow/roadmap.md (Milestone > Phase hierarchy)
 maestro-analyze {phase} → maestro-plan → maestro-execute → maestro-verify
 ```
 
-### Pre-load specs
-1. **Architecture specs**: Run `maestro spec load --category arch` to load architecture constraints. Use as context for phase decomposition — ensures roadmap respects documented decisions and boundaries.
-2. Optional — proceed without if unavailable.
+### Pre-load
+
+1. **Specs**: `maestro spec load --category arch` — load architecture constraints for phase decomposition
+2. **Wiki search**: `maestro wiki search "{requirement keywords}" --json` → prior knowledge
+3. All optional — proceed without if unavailable
 </context>
 
 <interview_protocol>
-Interview the user relentlessly until shared understanding is reached. Active only in interactive mode; skip when `-y/--yes`, `--revise`, `--review`, `-c/--continue`, or input is already specific (clear requirement + mode).
-
-- One decision per turn via ask_question with 2–4 options + a (Recommended) default. The user controls termination — keep interviewing until convergence; they can interrupt naturally or via `Other` at any time.
-- Search-first when uncertain: before asking, resolve via `state.json`, existing `roadmap.md`, `project.md`, `maestro spec load`, `maestro wiki search`, Glob/Grep/Read, or — for open-ended multi-file scans — spawn `invoke_subagent([{ TypeName: "<TypeName>", Role: "<Role>", Prompt: "<Prompt>", Workspace: "inherit" }])` / `maestro delegate ... --role explore`. Never ask what code or memory can verify; never bounce your own ambiguity back to the user — search first, then ask only what truly needs human judgment.
-- Writeback cadence: each settled decision is immediately appended/updated in the `Roadmap Decisions` section at the top of `.workflow/roadmap.md` (create the section if absent). Do NOT batch writeback to the end — partial decisions must already be on disk before the next question.
-- Walk the decision dependency tree strictly: mode → requirement scope → decomposition strategy → phase dependencies/order. Do not open the next branch until the current one is settled.
-- Scope guard: only decide the shape of the roadmap. Do not pre-resolve intra-phase task breakdown — that belongs to `plan`.
-
-Decision points: scope (MVP / complete / phased) → strategy (progressive / direct / auto) → milestone boundaries → phase dependencies and order.
-
-Exit: on consensus or explicit user signal to proceed, finalize the `Roadmap Decisions` section (rows already populated incrementally). Schema:
-`| # | Decision | Choice | Source (user / code / default) |`
+Follows @~/.maestro/workflows/interview-mechanics.md standard.
+
+**Interaction mode**: convergent menu-driven
+**Decision tree** (strict order): mode (create / revise / review) → requirement scope (MVP / complete / phased) → decomposition strategy (progressive / direct / auto) → milestone boundaries → phase dependencies and order
+**Scope guard**: only roadmap shape; do not pre-resolve intra-phase task breakdown (belongs to plan)
+**Writeback target**: .workflow/roadmap.md "Roadmap Decisions" section (create if absent)
+**Additional skip conditions**: --revise, --review (skip to respective mode)
+**Exit condition**: on consensus or explicit user signal → finalize Roadmap Decisions section
 </interview_protocol>
 
 <execution>
@@ -93,16 +94,45 @@ Sub-modes:
 - **Revise** (`--revise`): Follow workflow roadmap.md "Mode: Revise" section
 - **Review** (`--review`): Follow workflow roadmap.md "Mode: Review" section
 
-### Next-step routing on completion
+</execution>
+
+<completion>
+### Standalone report
+
+```
+=== ROADMAP READY ===
+Milestones: {count}
+Phases: {total_phases}
+Strategy: {progressive|direct|auto}
+Output: .workflow/roadmap.md
+--- COMPLETION STATUS ---
+Status: {DONE|DONE_WITH_CONCERNS}
+Concerns: {if any}
+```
+
+### Ralph-invoked completion
+
+End the step by calling the CLI (no text block output):
+```
+maestro ralph complete <idx> --status {STATUS} [--evidence {path}]
+```
+
+Status verdicts:
+- **DONE** — Normal completion
+- **DONE_WITH_CONCERNS** — Completed with caveats; pass `--concerns`
+- **NEEDS_RETRY** — Tooling error / transient issue; ralph will retry
+- **BLOCKED** — External hard blocker; pass `--reason`
+
+### Next-step routing
 
 | Condition | Suggestion |
 |-----------|-----------|
-| Roadmap approved, need analysis | /maestro-analyze 1 |
-| Simple project, ready to plan | /maestro-plan 1 |
-| Need UI design first | /maestro-impeccable build |
-| View project dashboard | /manage-status |
-| Need formal spec documents | /maestro-blueprint |
-</execution>
+| Roadmap approved, need analysis | `/maestro-analyze 1` |
+| Simple project, ready to plan | `/maestro-plan 1` |
+| Need UI design first | `/maestro-impeccable build` |
+| View project dashboard | `/manage-status` |
+| Need formal spec documents | `/maestro-blueprint` |
+</completion>
 
 <error_codes>
 | Code | Severity | Condition | Recovery |

package/.agy/skills/maestro-verify/SKILL.md

@@ -39,7 +39,22 @@ Registers VRF artifact in state.json on completion.
 <context>
 $ARGUMENTS — phase number or no args for milestone-wide, with optional flags.
 
-Flags (`--skip-tests`, `--skip-antipattern`, `--dir`), scope routing, output paths, and VRF artifact registration schema are defined in workflow `verify.md`.
+### Flags
+
+| Flag | Effect | Default |
+|------|--------|---------|
+| `--skip-tests` | Skip Nyquist test coverage validation (V2), only run Goal-Backward verification | false |
+| `--skip-antipattern` | Skip anti-pattern scan step | false |
+| `--dir <path>` | Verify a single plan directory instead of milestone-wide | — (milestone mode) |
+
+**Scope routing:**
+| Input | Scope | Resolution |
+|-------|-------|------------|
+| `--dir scratch/{dir}` | single plan | Verify one plan, write verification.json into plan dir |
+| numeric arg | phase | Verify all execute artifacts for that phase |
+| no args | milestone | Aggregate all execute artifacts for current milestone |
+
+Output paths and VRF artifact registration schema are defined in workflow `verify.md`.
 
 ### Pre-load context (before verification)
 
@@ -65,28 +80,48 @@ Follow '~/.maestro/workflows/verify.md' completely.
 
 On confirm → `Skill("spec-add", "<category> <content>")`.
 
-**Next-step routing on completion:**
-- All checks pass, no gaps → /quality-review
-- Gaps found (must-have failures or anti-pattern blockers) → /maestro-plan --gaps
-- Low test coverage (Nyquist gaps) → /quality-auto-test
+</execution>
 
-**Gap-fix closure loop:**
-Gaps found → maestro-plan --gaps → maestro-execute → maestro-verify (re-run)
+<completion>
+### Standalone report
 
-**Completion status:**
 ```
---- COMPLETION STATUS ---
+=== VERIFY COMPLETE ===
 STATUS: DONE|DONE_WITH_CONCERNS|NEEDS_RETRY
 CONCERNS: {description if applicable}
 NEXT: /quality-review
---- END STATUS ---
+=== END VERIFY ===
 ```
 
 Status mapping:
 - **DONE** — All checks pass, no gaps → NEXT: /quality-review
 - **DONE_WITH_CONCERNS** — Gaps found (must-have failures or anti-pattern blockers) → NEXT: /maestro-execute (after /maestro-plan --gaps)
 - **NEEDS_RETRY** — Verification could not complete (missing artifacts, corrupt data)
-</execution>
+
+### Ralph-invoked completion
+
+End the step by calling the CLI (no text block output):
+```
+maestro ralph complete <idx> --status {STATUS} [--evidence {path}]
+```
+
+Status verdicts:
+- **DONE** — Normal completion
+- **DONE_WITH_CONCERNS** — Completed with caveats; pass `--concerns`
+- **NEEDS_RETRY** — Tooling error / transient issue; ralph will retry
+- **BLOCKED** — External hard blocker; pass `--reason`
+
+### Next-step routing
+
+| Condition | Suggestion |
+|-----------|-----------|
+| All checks pass, no gaps | `/quality-review` |
+| Gaps found (must-have failures or anti-pattern blockers) | `/maestro-plan --gaps` |
+| Low test coverage (Nyquist gaps) | `/quality-auto-test` |
+
+**Gap-fix closure loop:**
+Gaps found → maestro-plan --gaps → maestro-execute → maestro-verify (re-run)
+</completion>
 
 <error_codes>
 | Code | Severity | Condition | Recovery |

package/.agy/skills/team-adversarial-swarm/scripts/aco.py

@@ -89,7 +89,7 @@ def cmd_init(args: argparse.Namespace) -> None:
     paths = SessionPaths(Path(args.session))
     if not paths.config.exists():
         _fail(2, f"config not found: {paths.config}")
-    config = json.loads(paths.config.read_text())
+    config = json.loads(paths.config.read_text(encoding="utf-8"))
 
     paths.ensure_dirs()
 
@@ -107,7 +107,7 @@ def cmd_init(args: argparse.Namespace) -> None:
         "start_nodes": config.get("task_space", {}).get("start_nodes", "any"),
         "edges": config.get("task_space", {}).get("edges", "complete"),
     }
-    paths.task_space.write_text(json.dumps(task_space, indent=2, ensure_ascii=False))
+    paths.task_space.write_text(json.dumps(task_space, indent=2, ensure_ascii=False), encoding="utf-8")
 
     # Initialize pheromone
     aco_cfg = config.get("aco", {})
@@ -148,9 +148,9 @@ def _pick_start_node(nodes: List[str], state: PheromoneState, mode: str) -> str:
 
 def cmd_select(args: argparse.Namespace) -> None:
     paths = SessionPaths(Path(args.session))
-    config = json.loads(paths.config.read_text())
+    config = json.loads(paths.config.read_text(encoding="utf-8"))
     state = PheromoneState.load(paths.pheromone_current)
-    task_space = json.loads(paths.task_space.read_text())
+    task_space = json.loads(paths.task_space.read_text(encoding="utf-8"))
 
     n_ants = config.get("swarm", {}).get("n_ants", 5)
     nodes = task_space["nodes"]
@@ -190,7 +190,7 @@ def _load_iteration_artifacts(paths: SessionPaths, iteration: int) -> List[dict]
     artifacts = []
     for f in files:
         try:
-            artifacts.append(json.loads(Path(f).read_text()))
+            artifacts.append(json.loads(Path(f).read_text(encoding="utf-8")))
         except json.JSONDecodeError as e:
             print(f"warning: skipped malformed artifact {f}: {e}", file=sys.stderr)
     return artifacts
@@ -213,9 +213,9 @@ def _validate_artifact(art: dict, valid_nodes: set) -> Optional[str]:
 
 def cmd_update(args: argparse.Namespace) -> None:
     paths = SessionPaths(Path(args.session))
-    config = json.loads(paths.config.read_text())
+    config = json.loads(paths.config.read_text(encoding="utf-8"))
     state = PheromoneState.load(paths.pheromone_current)
-    task_space = json.loads(paths.task_space.read_text())
+    task_space = json.loads(paths.task_space.read_text(encoding="utf-8"))
     valid_nodes = set(task_space["nodes"])
 
     artifacts = _load_iteration_artifacts(paths, args.iter)
@@ -266,7 +266,7 @@ def cmd_update(args: argparse.Namespace) -> None:
     # Elitist: re-load best history, deposit extra on best path
     best_data = None
     if paths.best.exists():
-        best_data = json.loads(paths.best.read_text())
+        best_data = json.loads(paths.best.read_text(encoding="utf-8"))
     current_best = max(scored, key=lambda x: x["score"]) if scored else None
     if current_best:
         best_art = next(a for a in artifacts if a["ant_id"] == current_best["ant_id"])
@@ -281,7 +281,7 @@ def cmd_update(args: argparse.Namespace) -> None:
                 "evidence": best_art.get("evidence", []),
                 "updated_at": time.time(),
             }
-            paths.best.write_text(json.dumps(best_data, indent=2, ensure_ascii=False))
+            paths.best.write_text(json.dumps(best_data, indent=2, ensure_ascii=False), encoding="utf-8")
         # Elite deposit
         state.deposit(best_data["path"], best_data["score"])
 
@@ -292,14 +292,14 @@ def cmd_update(args: argparse.Namespace) -> None:
 
     # Persist trails
     trails_file = paths.trails / f"{args.iter}.jsonl"
-    trails_file.write_text("\n".join(json.dumps(t, ensure_ascii=False) for t in trail_log))
+    trails_file.write_text("\n".join(json.dumps(t, ensure_ascii=False) for t in trail_log), encoding="utf-8")
 
     mean_score = sum(s["score"] for s in scored) / len(scored) if scored else 0.0
     best_score = best_data["score"] if best_data else 0.0
     prev_best = 0.0
     history_files = sorted(paths.pheromone_history.glob("*.json"))
     if len(history_files) >= 2:
-        prev = json.loads(history_files[-2].read_text())
+        prev = json.loads(history_files[-2].read_text(encoding="utf-8"))
         prev_best = prev.get("stats", {}).get("best_known", best_score)
     delta = best_score - prev_best
 
@@ -323,7 +323,7 @@ def cmd_update(args: argparse.Namespace) -> None:
 
 def cmd_converged(args: argparse.Namespace) -> None:
     paths = SessionPaths(Path(args.session))
-    config = json.loads(paths.config.read_text())
+    config = json.loads(paths.config.read_text(encoding="utf-8"))
     cv = config.get("convergence", {})
 
     state = PheromoneState.load(paths.pheromone_current)
@@ -339,7 +339,7 @@ def cmd_converged(args: argparse.Namespace) -> None:
     }
 
     if paths.best.exists():
-        metrics["best_score"] = json.loads(paths.best.read_text()).get("score", 0.0)
+        metrics["best_score"] = json.loads(paths.best.read_text(encoding="utf-8")).get("score", 0.0)
 
     # max_iterations
     max_iter = cv.get("max_iterations", 5)
@@ -397,7 +397,7 @@ def cmd_report(args: argparse.Namespace) -> None:
 
     best = None
     if paths.best.exists():
-        best = json.loads(paths.best.read_text())
+        best = json.loads(paths.best.read_text(encoding="utf-8"))
 
     # Top-K trails across all iterations
     all_trails = []
@@ -410,7 +410,7 @@ def cmd_report(args: argparse.Namespace) -> None:
     # Convergence curve
     curve = []
     for hf in sorted(paths.pheromone_history.glob("*.json"), key=lambda p: int(p.stem)):
-        snap = json.loads(hf.read_text())
+        snap = json.loads(hf.read_text(encoding="utf-8"))
         curve.append({
             "iteration": snap["iteration"],
             "entropy": snap["stats"]["entropy"],

package/.agy/skills/team-adversarial-swarm/scripts/pheromone.py

@@ -114,11 +114,11 @@ class PheromoneState:
 
     def save(self, path: Path) -> None:
         path.parent.mkdir(parents=True, exist_ok=True)
-        path.write_text(json.dumps(self.to_dict(), indent=2, ensure_ascii=False))
+        path.write_text(json.dumps(self.to_dict(), indent=2, ensure_ascii=False), encoding="utf-8")
 
     @classmethod
     def load(cls, path: Path) -> "PheromoneState":
-        return cls.from_dict(json.loads(path.read_text()))
+        return cls.from_dict(json.loads(path.read_text(encoding="utf-8")))
 
     def select_neighbors(
         self,

package/.agy/skills/team-adversarial-swarm/scripts/scoring.py

@@ -62,7 +62,7 @@ def load_verified_scores(scores_file: Path) -> Dict[str, float]:
     """Load pre-computed verified_scores from scorer role output (if exists)."""
     if not scores_file.exists():
         return {}
-    data = json.loads(scores_file.read_text())
+    data = json.loads(scores_file.read_text(encoding="utf-8"))
     return {
         ant_id: entry["verified_score"]
         for ant_id, entry in data.get("scores", {}).items()

package/.agy/skills/team-swarm/scripts/aco.py

@@ -89,7 +89,7 @@ def cmd_init(args: argparse.Namespace) -> None:
     paths = SessionPaths(Path(args.session))
     if not paths.config.exists():
         _fail(2, f"config not found: {paths.config}")
-    config = json.loads(paths.config.read_text())
+    config = json.loads(paths.config.read_text(encoding="utf-8"))
 
     paths.ensure_dirs()
 
@@ -107,7 +107,7 @@ def cmd_init(args: argparse.Namespace) -> None:
         "start_nodes": config.get("task_space", {}).get("start_nodes", "any"),
         "edges": config.get("task_space", {}).get("edges", "complete"),
     }
-    paths.task_space.write_text(json.dumps(task_space, indent=2, ensure_ascii=False))
+    paths.task_space.write_text(json.dumps(task_space, indent=2, ensure_ascii=False), encoding="utf-8")
 
     # Initialize pheromone
     aco_cfg = config.get("aco", {})
@@ -148,9 +148,9 @@ def _pick_start_node(nodes: List[str], state: PheromoneState, mode: str) -> str:
 
 def cmd_select(args: argparse.Namespace) -> None:
     paths = SessionPaths(Path(args.session))
-    config = json.loads(paths.config.read_text())
+    config = json.loads(paths.config.read_text(encoding="utf-8"))
     state = PheromoneState.load(paths.pheromone_current)
-    task_space = json.loads(paths.task_space.read_text())
+    task_space = json.loads(paths.task_space.read_text(encoding="utf-8"))
 
     n_ants = config.get("swarm", {}).get("n_ants", 5)
     nodes = task_space["nodes"]
@@ -190,7 +190,7 @@ def _load_iteration_artifacts(paths: SessionPaths, iteration: int) -> List[dict]
     artifacts = []
     for f in files:
         try:
-            artifacts.append(json.loads(Path(f).read_text()))
+            artifacts.append(json.loads(Path(f).read_text(encoding="utf-8")))
         except json.JSONDecodeError as e:
             print(f"warning: skipped malformed artifact {f}: {e}", file=sys.stderr)
     return artifacts
@@ -213,9 +213,9 @@ def _validate_artifact(art: dict, valid_nodes: set) -> Optional[str]:
 
 def cmd_update(args: argparse.Namespace) -> None:
     paths = SessionPaths(Path(args.session))
-    config = json.loads(paths.config.read_text())
+    config = json.loads(paths.config.read_text(encoding="utf-8"))
     state = PheromoneState.load(paths.pheromone_current)
-    task_space = json.loads(paths.task_space.read_text())
+    task_space = json.loads(paths.task_space.read_text(encoding="utf-8"))
     valid_nodes = set(task_space["nodes"])
 
     artifacts = _load_iteration_artifacts(paths, args.iter)
@@ -266,7 +266,7 @@ def cmd_update(args: argparse.Namespace) -> None:
     # Elitist: re-load best history, deposit extra on best path
     best_data = None
     if paths.best.exists():
-        best_data = json.loads(paths.best.read_text())
+        best_data = json.loads(paths.best.read_text(encoding="utf-8"))
     current_best = max(scored, key=lambda x: x["score"]) if scored else None
     if current_best:
         best_art = next(a for a in artifacts if a["ant_id"] == current_best["ant_id"])
@@ -281,7 +281,7 @@ def cmd_update(args: argparse.Namespace) -> None:
                 "evidence": best_art.get("evidence", []),
                 "updated_at": time.time(),
             }
-            paths.best.write_text(json.dumps(best_data, indent=2, ensure_ascii=False))
+            paths.best.write_text(json.dumps(best_data, indent=2, ensure_ascii=False), encoding="utf-8")
         # Elite deposit
         state.deposit(best_data["path"], best_data["score"])
 
@@ -292,14 +292,14 @@ def cmd_update(args: argparse.Namespace) -> None:
 
     # Persist trails
     trails_file = paths.trails / f"{args.iter}.jsonl"
-    trails_file.write_text("\n".join(json.dumps(t, ensure_ascii=False) for t in trail_log))
+    trails_file.write_text("\n".join(json.dumps(t, ensure_ascii=False) for t in trail_log), encoding="utf-8")
 
     mean_score = sum(s["score"] for s in scored) / len(scored) if scored else 0.0
     best_score = best_data["score"] if best_data else 0.0
     prev_best = 0.0
     history_files = sorted(paths.pheromone_history.glob("*.json"))
     if len(history_files) >= 2:
-        prev = json.loads(history_files[-2].read_text())
+        prev = json.loads(history_files[-2].read_text(encoding="utf-8"))
         prev_best = prev.get("stats", {}).get("best_known", best_score)
     delta = best_score - prev_best
 
@@ -323,7 +323,7 @@ def cmd_update(args: argparse.Namespace) -> None:
 
 def cmd_converged(args: argparse.Namespace) -> None:
     paths = SessionPaths(Path(args.session))
-    config = json.loads(paths.config.read_text())
+    config = json.loads(paths.config.read_text(encoding="utf-8"))
     cv = config.get("convergence", {})
 
     state = PheromoneState.load(paths.pheromone_current)
@@ -339,7 +339,7 @@ def cmd_converged(args: argparse.Namespace) -> None:
     }
 
     if paths.best.exists():
-        metrics["best_score"] = json.loads(paths.best.read_text()).get("score", 0.0)
+        metrics["best_score"] = json.loads(paths.best.read_text(encoding="utf-8")).get("score", 0.0)
 
     # max_iterations
     max_iter = cv.get("max_iterations", 5)
@@ -397,7 +397,7 @@ def cmd_report(args: argparse.Namespace) -> None:
 
     best = None
     if paths.best.exists():
-        best = json.loads(paths.best.read_text())
+        best = json.loads(paths.best.read_text(encoding="utf-8"))
 
     # Top-K trails across all iterations
     all_trails = []
@@ -410,7 +410,7 @@ def cmd_report(args: argparse.Namespace) -> None:
     # Convergence curve
     curve = []
     for hf in sorted(paths.pheromone_history.glob("*.json"), key=lambda p: int(p.stem)):
-        snap = json.loads(hf.read_text())
+        snap = json.loads(hf.read_text(encoding="utf-8"))
         curve.append({
             "iteration": snap["iteration"],
             "entropy": snap["stats"]["entropy"],

package/.agy/skills/team-swarm/scripts/pheromone.py

@@ -114,11 +114,11 @@ class PheromoneState:
 
     def save(self, path: Path) -> None:
         path.parent.mkdir(parents=True, exist_ok=True)
-        path.write_text(json.dumps(self.to_dict(), indent=2, ensure_ascii=False))
+        path.write_text(json.dumps(self.to_dict(), indent=2, ensure_ascii=False), encoding="utf-8")
 
     @classmethod
     def load(cls, path: Path) -> "PheromoneState":
-        return cls.from_dict(json.loads(path.read_text()))
+        return cls.from_dict(json.loads(path.read_text(encoding="utf-8")))
 
     def select_neighbors(
         self,

package/.agy/skills/team-swarm/scripts/scoring.py

@@ -62,7 +62,7 @@ def load_verified_scores(scores_file: Path) -> Dict[str, float]:
     """Load pre-computed verified_scores from scorer role output (if exists)."""
     if not scores_file.exists():
         return {}
-    data = json.loads(scores_file.read_text())
+    data = json.loads(scores_file.read_text(encoding="utf-8"))
     return {
         ant_id: entry["verified_score"]
         for ant_id, entry in data.get("scores", {}).items()