metagit-cli 0.23.2__tar.gz → 0.24.0__tar.gz

{metagit_cli-0.23.2 → metagit_cli-0.24.0}/.agents/skills/metagit-agent-access/SKILL.md

@@ -42,7 +42,7 @@ SKILL_ROOT="$(python3 -c "import metagit, pathlib; print(pathlib.Path(metagit.__
 After `metagit skills install --skill metagit-agent-access`:
 
 ```bash
-"$HOME/.config/hermes/skills/metagit-agent-access/scripts/optimize-agent-access.sh" . --apply --json
+"${HERMES_HOME:-$HOME/.hermes}/skills/metagit-agent-access/scripts/optimize-agent-access.sh" . --apply --json
 ```
 
 ### Inline fallback (no scripts)

{metagit_cli-0.23.2 → metagit_cli-0.24.0}/.agents/skills/metagit-cli/SKILL.md

@@ -25,8 +25,10 @@ Repo-root agent docs: [AGENTS.md](https://github.com/metagit-ai/metagit-cli/blob
 
 Global flags (most commands):
 
-- `-c path/to/metagit.config.yaml` — app config (default `metagit.config.yaml`)
-- Workspace manifest: `--definition` / `-c` on catalog commands (default `.metagit.yml`)
+- `metagit -c path/to/metagit.config.yaml` — **appconfig** only (default `metagit.config.yaml`)
+- Workspace manifest: `-c .metagit.yml` on `metagit config …`, `metagit workspace …`, and leaf `config graph suggest|export -c …`
+- Workspace manifest on the coordination families (`branch`, `lease`, `worktree`, `claim`, `task`, `semantic`, `merge`, `schedule`, `aos`): `--definition .metagit.yml` — these commands expose **no `-c`**
+- `--workspace-root` on graph suggest — checkout root used to **scan** inferred deps (default: appconfig `workspace.path`); not the manifest path
 
 ---
 
@@ -119,6 +121,8 @@ metagit config providers --show
 
 ### Graph relationships (suggest, apply, export)
 
+Trailing `-c .metagit.yml` on `config graph suggest|export` is valid (leaf manifest flag). Do not substitute `--workspace-root` for `-c`.
+
 | Task | Command |
 |------|---------|
 | First-time graph discovery (report only) | `metagit prompt workspace -k graph-discover -c .metagit.yml --text-only` |

{metagit_cli-0.23.2/src/metagit/data → metagit_cli-0.24.0/.agents}/skills/metagit-cli/metagit-cli/SKILL.md

@@ -17,7 +17,7 @@ export METAGIT_AGENT_MODE=true
 Global flags (most commands):
 
 - `-c path/to/metagit.config.yaml` — app config (default `metagit.config.yaml`)
-- Workspace manifest: `--definition` / `-c` on catalog commands (default `.metagit.yml`)
+- Workspace manifest: `-c` on `config` / `workspace` catalog commands, `--definition` on the coordination families (`branch`, `lease`, `worktree`, `claim`, `task`, `semantic`, `merge`, `schedule`, `aos`) — default `.metagit.yml` either way
 
 ---
 

{metagit_cli-0.23.2 → metagit_cli-0.24.0}/.agents/skills/metagit-control-center/SKILL.md

@@ -28,7 +28,7 @@ SKILL_ROOT="$(python3 -c "import metagit, pathlib; print(pathlib.Path(metagit.__
 Or from a full skill install:
 
 ```bash
-"$HOME/.config/hermes/skills/metagit-control-center/scripts/control-cycle.sh" .
+"${HERMES_HOME:-$HOME/.hermes}/skills/metagit-control-center/scripts/control-cycle.sh" .
 ```
 
 Wrapper behavior:

{metagit_cli-0.23.2/src/metagit/data → metagit_cli-0.24.0/.agents}/skills/metagit-gitnexus/SKILL.md

@@ -21,6 +21,8 @@ Use this skill whenever GitNexus context is stale or missing for target reposito
 
 ## Manual workspace graph (`.metagit.yml` → Cypher)
 
+**CLI flags:** script `-c` and `metagit config graph export -c .metagit.yml` point at the **manifest**. `--workspace-root` is only the scan root for suggest; global `metagit -c` is **appconfig**.
+
 Promote inferred edges first (see `metagit-graph-maintain` skill), then ingest:
 
 ```bash

{metagit_cli-0.23.2 → metagit_cli-0.24.0}/.agents/skills/metagit-graph-maintain/SKILL.md

@@ -40,6 +40,8 @@ After sign-off, continue with the maintenance workflow below (or `metagit prompt
 
 ## Maintenance workflow
 
+**CLI flags:** `-c` on `config graph suggest|export` is the **manifest** path (trailing leaf `-c` is valid). `--workspace-root` is the checkout root used to scan inferred deps. Global `metagit -c` configures **appconfig**, not `.metagit.yml`.
+
 ### 1. Bootstrap context
 
 ```bash
@@ -59,6 +61,8 @@ MCP: `metagit_suggest_graph_relationships`
 
 Review `candidates[]` for `confidence`, `evidence`, and `source_edge_type`. Skip low-confidence edges unless the operator approves.
 
+Also review `stale_manual[]` — active manual relationships with no supporting inferred edge under the current scan, matched on endpoints so a differing relationship type still counts as support (report-only; do not edit/remove without operator confirmation). Use `--verbose` when candidates are empty to confirm scan roots and ignore prune counts.
+
 ### 3. Preview and apply
 
 ```bash
@@ -117,6 +121,12 @@ Return:
 - GitNexus ingest status (schema + statement count)
 - repos still stale/missing in GitNexus registry
 
+## Lifecycle
+
+- Promoted edges are written with `status: active`, `provenance: promoted`.
+- Deprecate retired edges by setting `status: deprecated` rather than deleting them.
+- `stale_manual[]` from suggest is report-only: confirm with the operator before editing or removing the flagged edges.
+
 ## Safety
 
 - Default `--min-confidence medium`; require operator approval for `--min-confidence all`

{metagit_cli-0.23.2 → metagit_cli-0.24.0}/.mex/ROUTER.md

@@ -16,7 +16,7 @@ edges:
     condition: when implementing MCP runtime, tool schemas, resource handlers, or protocol behavior
   - target: patterns/INDEX.md
     condition: when starting a task — check the pattern index for a matching pattern file
-last_updated: 2026-07-14
+last_updated: 2026-07-28
 ---
 
 # Session Bootstrap
@@ -27,6 +27,9 @@ Then read this file fully before doing anything else in this session.
 
 ## Current Project State
 **Working:**
+- **Durable graph suggest UX (2026-07-28, `feat/durable-graph-suggest-ux`):** leaf `--config-path/-c` on `metagit config graph suggest|export`; `suggest --verbose` human summary + `scan_stats`; shared ignore-aware `metagit.core.utils.repo_walk.iter_repo_files()` (always-on scaffold denylist + nested git-scoped `.gitignore`) wired into `ImportHintScanner` terraform scanning; `GraphRelationship.status`/`provenance` lifecycle fields with `graph_validation.validate_graph_relationships()` (required `id`, endpoint checks) enforced by `config validate` and `suggest --apply`; report-only `GraphSuggestResult.stale_manual[]` (endpoint-matched); docs/skills/prompts updated for flag semantics and lifecycle. Design `docs/superpowers/specs/2026-07-28-durable-graph-suggest-design.md`; plan `docs/superpowers/plans/2026-07-28-durable-graph-suggest.md`. **Review fixes (`.superpowers/sdd/branch-fix-report.md`):** apply writes one `set graph.relationships` and validates the patched document via `ConfigPatchService.draft()` (no more `example-value` placeholder breaking `config validate`); `config validate` no longer relabels aborts as load failures; walker filters on suffix before ignore checks with cached ancestor chains and honors `!` negations; `scan_stats` de-duplicated by repo path; graph edges written as `from:` with explicit `status`/`provenance`.
+- **Hermes install targeting (2026-07-17):** `HERMES_HOME` (default `~/.hermes`) for skills; MCP merges into `$HERMES_HOME/config.yaml` `mcp_servers` via installed `metagit` binary + `METAGIT_AGENT_MODE`; MCP stdio speaks NDJSON (fixes initialize handshake hang with standard clients); design `docs/superpowers/specs/2026-07-17-hermes-install-target-fix-design.md`.
+- **Skills/MCP `--scope project` root (2026-07-17):** CLI project-scope installs resolve against the nearest git repository root via `resolve_project_install_root()` so nested cwds do not create `src/.../.cursor/skills`; library callers still pass explicit `project_root` or rely on cwd after `chdir`.
 - **Derived projects + skills surface (2026-07-14):** in-manifest surgical `workspace.projects[]` via `metagit project derived create|refresh|include|exclude` and MCP `metagit_project_derived_*`; layered `metagit skills surface` / `metagit_skills_surface`; docs `derived-projects.md` / `skills-surface.md`; example `examples/derived-workspace/`; design `docs/superpowers/specs/2026-07-14-derived-projects-skills-inventory-design.md`.
 - **RFC-0013 Agent Operating System (implemented on `feat/rfc-0013-aos`):** thin `metagit.core.aos` composition façade; `metagit aos|coord status|doctor|next`; MCP `metagit_aos_*` / `metagit_coord_*`; `SchedulerService.preview_next`; modality `aos_status`; docs `docs/reference/aos.md`; skill `metagit-aos`; worktree `.worktrees/rfc-0013`.
 - **RFC-0014 Metagit Atlas (Phase 0–1 local MVP on `feat/rfc-0014-atlas`):** repository-local `.atlas/` semantic layer with curated intent, deterministic inventory/Python-symbol/test evidence, validation, derived query index, and `metagit atlas init|generate|validate|status|query|refresh`; modality `atlas_local`; docs `docs/reference/atlas.md`. MCP, federation, and optional adapters remain deferred. **Packaging fix:** `atlas validate` schemas live under `src/metagit/data/schemas/atlas/` so PyPI wheels resolve them (repo-root `schemas/atlas/` alone was missing from 0.22.0 wheels).

{metagit_cli-0.23.2 → metagit_cli-0.24.0}/.mex/context/mcp-runtime.md

@@ -19,7 +19,7 @@ edges:
     condition: when adding a new MCP tool or changing tool schemas
   - target: patterns/debug-mcp-runtime.md
     condition: when MCP message loop, framing, or tool dispatch fails
-last_updated: 2026-06-30
+last_updated: 2026-07-17
 ---
 
 # MCP Runtime
@@ -27,7 +27,7 @@ last_updated: 2026-06-30
 ## Overview
 - Entry command is `metagit mcp serve` from `src/metagit/cli/commands/mcp.py`.
 - Runtime implementation lives in `src/metagit/core/mcp/runtime.py`.
-- Runtime uses stdio JSON-RPC with MCP framing (`Content-Length` header + body).
+- Runtime uses stdio JSON-RPC with **newline-delimited JSON** (MCP stdio spec). Readers also accept legacy LSP-style `Content-Length` frames; writers always emit NDJSON.
 - Gate state is resolved from workspace root + `.metagit.yml` validation before exposing tools.
 
 ## Active Runtime Services

{metagit_cli-0.23.2 → metagit_cli-0.24.0}/.mex/patterns/INDEX.md

@@ -55,8 +55,10 @@ Lookup table for all pattern files in this directory. Check here before starting
 | [project-cli-resolution.md](project-cli-resolution.md) | Fixing or extending `metagit project list/select` when app-config default ≠ manifest projects |
 | [repo-promote-local-to-git.md](repo-promote-local-to-git.md) | Migrating a path-based workspace repo entry to a git-managed clone (`project repo promote`) |
 | [rewrite-campaign-workspace.md](rewrite-campaign-workspace.md) | Reference-implementation rewrite coordinator (source + target repos, campaign, parity registry) |
+| [skills-install-project-scope.md](skills-install-project-scope.md) | Fixing `skills`/`mcp` `--scope project` so installs use the git repo root from nested cwds |
 | [semantic-graph-service.md](semantic-graph-service.md) | Implementing or extending RFC-0010 semantic graph models, JSON store, service queries, and events |
 | [github-gh-auth.md](github-gh-auth.md) | Creating PRs or running `gh` when `GH_TOKEN`/`GITHUB_TOKEN` cause 401 errors |
+| [graph-suggest-maintain.md](graph-suggest-maintain.md) | Maintaining `graph.relationships` — durable fields, validation, ignore-aware suggest scanning, stale review |
 | [run-graphify-analysis.md](run-graphify-analysis.md) | Running `graphify` on the repo or a focused subtree and turning the result into usable graph/report outputs |
 | [update-release-workflow.md](update-release-workflow.md) | Replacing or repairing GitHub release automation and tag-driven publish flow |
 | [validate-doc-links.md](validate-doc-links.md) | Adding or fixing links in README.md and docs/**/*.md; run `task docs:links` |

{metagit_cli-0.23.2 → metagit_cli-0.24.0}/.mex/patterns/debug-mcp-runtime.md

@@ -24,7 +24,7 @@ Primary files: `src/metagit/core/mcp/runtime.py`, `tool_registry.py`, gate/root
 ## Steps
 1. Reproduce with smallest path first (`metagit mcp serve --status-once` for gate snapshot).
 2. Check gate state and allowed tool set before debugging individual tool behavior.
-3. Validate request envelope fields (`jsonrpc`, `id`, `method`, `params`) and framed transport boundaries.
+3. Validate request envelope fields (`jsonrpc`, `id`, `method`, `params`) and stdio framing (NDJSON primary; legacy Content-Length accepted on read).
 4. Run focused runtime tests, then full MCP suite.
 5. If method-specific failure persists, add/adjust regression tests before patching.
 

metagit_cli-0.24.0/.mex/patterns/graph-suggest-maintain.md

@@ -0,0 +1,66 @@
+---
+name: graph-suggest-maintain
+description: Maintaining workspace graph.relationships (durable fields, validation, ignore-aware suggest scanning, stale review).
+triggers:
+  - "graph.relationships"
+  - "graph suggest"
+  - "GraphRelationship"
+  - "stale_manual"
+edges:
+  - target: "../context/conventions.md"
+    condition: when writing or reviewing config/graph code
+last_updated: 2026-07-28
+---
+
+# Graph Suggest / Maintain
+
+## Context
+`workspace.graph.relationships` is a thin durable edge list (`src/metagit/core/config/models.py::GraphRelationship`)
+maintained via `metagit config graph suggest|export` (`src/metagit/core/config/graph_suggest.py`,
+`src/metagit/cli/commands/config.py`). Design:
+`docs/superpowers/specs/2026-07-28-durable-graph-suggest-design.md`.
+
+## Steps
+1. Use leaf `--config-path/-c` on `graph suggest`/`graph export` for the manifest path
+   (mirrors `config validate`); `--workspace-root` is the separate scan/checkout root
+   (default `appconfig.workspace.path`). Global `metagit -c` is appconfig only, never
+   `.metagit.yml`.
+2. Any new recursive scan over managed repos (import hints, terraform, etc.) must go
+   through `metagit.core.utils.repo_walk.iter_repo_files()` — it always applies the
+   shared scaffold denylist (`metagit.core.utils.scaffold_paths`) and honors nested,
+   git-scoped `.gitignore` (pruned during the walk, not post-filtered). Do not add a new
+   `Path.rglob`/`os.walk` for this purpose.
+3. New/edited `GraphRelationship` entries need a non-blank `id` and valid `from`/`to`
+   endpoints (`workspace.projects[].repos`; project-level edges with no `repo` are fine).
+   `graph_validation.validate_graph_relationships()` enforces this — `config validate`
+   calls it, and `suggest --apply` validates the *patched document* via
+   `ConfigPatchService.draft()` (the same `apply_operations` path `patch()` writes) before
+   saving (failures surface as `GraphSuggestApplyResult.validation_errors`, no write).
+4. Lifecycle fields: `status` (`active`/`deprecated`/`proposed`) and `provenance`
+   (`manual`/`promoted`/`imported`). Suggested edges get `provenance="promoted"`. Setting
+   `status="deprecated"` on a manual edge excludes it from `stale_manual` review.
+5. `GraphSuggestResult.stale_manual[]` is report-only: active manual edges with no
+   supporting inferred edge in the current scan. There is no auto-mutate/`--mark-stale` —
+   an agent or human reviews and edits the manifest by hand.
+6. After changing suggest/validation behavior, regenerate schema/docs:
+   `schemas/metagit_config.schema.json`, `docs/reference/metagit-config.*`, and
+   `docs/reference/metagit-config.full-example.yml` (via `metagit config example`).
+
+## Gotchas
+- Nested `.gitignore` patterns are scoped to the directory that declared them (ancestor
+  chain check), not merged into one global set — a pattern in `a/.gitignore` must not
+  exclude files under sibling directory `b/`.
+- `stale_manual` must only flag `status == "active" and provenance == "manual"` — exclude
+  `proposed`, `promoted`, `imported`, and `deprecated`, or maintained/generated edges get
+  incorrectly flagged. Support is matched on **endpoints only**: an inferred edge between
+  the same two endpoints backs a manual edge even when the relationship type differs.
+- Apply must not depend on `SchemaTreeService` defaults. `enable`/`append` seed placeholder
+  values (an `example-value` relationship), so promotion issues one
+  `set graph.relationships` with the complete list rebuilt from the manifest on disk.
+- `graph.relationships` are written under the `from:` serialization alias with explicit
+  `status`/`provenance` (`graph_models.graph_relationships_payload()`). YAML dumps that skip
+  `by_alias=True` emit `from_endpoint:`, which fails the published JSON schema.
+- Per-project `map_dependencies` calls each re-scan every workspace repo, so walk stats must
+  be merged by repo path (`repo_walk.sum_scan_stats`) rather than accumulated.
+- `ConfigExampleGenerator` must emit a valid member for `Literal`-typed fields (not a
+  placeholder string) so the generated exemplar still validates against `MetagitConfig`.

metagit_cli-0.24.0/.mex/patterns/skills-install-project-scope.md

@@ -0,0 +1,29 @@
+---
+name: skills-install-project-scope
+description: Ensure metagit skills/mcp --scope project and Hermes HERMES_HOME targeting install correctly.
+edges:
+  - target: ../context/conventions.md
+    condition: when changing CLI installer path resolution
+last_updated: 2026-07-17
+---
+
+# Skills / MCP project-scope + Hermes install roots
+
+## When
+
+Changing `metagit skills install` or `metagit mcp install` destination paths, debugging installs that land under a nested cwd, or Hermes installs that miss the active gateway home.
+
+## Steps
+
+1. Keep library helpers (`install_skills_for_targets`, `install_mcp_for_targets`) cwd-relative unless callers pass `project_root` — `AgentProfileService` chdirs into repo mounts that may not be git roots.
+2. CLI `--scope project` must call `resolve_project_install_root()` (nearest `.git` parent, else cwd) and pass that as `project_root`.
+3. Hermes user-scope paths must use `resolve_hermes_home()` / `HERMES_HOME` (default `~/.hermes`), not `~/.config/hermes`.
+4. Hermes MCP must merge YAML `$HERMES_HOME/config.yaml` → `mcp_servers` and launch the installed `metagit` binary (never default `uvx metagit-cli`).
+5. Add/extend tests for nested-cwd project scope and `HERMES_HOME` skill/MCP installs.
+6. Document paths in `docs/skills.md` / `docs/reference/metagit-agent.md` and CHANGELOG Fixed.
+
+## Done when
+
+- Dry-run from a subdirectory prints `…/<repo>/.cursor/skills` (or equivalent vendor path), not `…/<subdir>/.cursor/skills`.
+- With `HERMES_HOME=/tmp/h`, Hermes skills land in `/tmp/h/skills` and MCP updates `/tmp/h/config.yaml` without `uvx`.
+- Unit + CLI skills/MCP installer tests pass.

{metagit_cli-0.23.2 → metagit_cli-0.24.0}/CHANGELOG.md

@@ -4,6 +4,38 @@
 
 
 
+## [0.24.0] - 2026-07-28
+
+
+
+### Added
+- **Manifest-homed workspace root:** when `-c` / `--config-path` targets a `.metagit.yml` outside the cwd, relative `workspace.path` resolves against that manifest’s directory (`resolve_workspace_root`) for `config graph suggest|export`, `workspace`, `project`, `prompt`, `skills`, and `gitnexus group sync`. JSON suggest output includes `workspace_root`.
+- **`metagit config graph suggest|export`:** accept a leaf `--config-path/-c` (overrides the `config` group's manifest path); `suggest` gains `--verbose` for a logger-emitted summary (roots, candidate counts, prune stats) even with `--json`. `GraphSuggestResult.scan_stats` aggregates `ImportHintScanner` walk stats (`dirs_pruned`, `files_skipped_gitignore`, `files_yielded`), de-duplicated by repo path so a workspace repo is counted once no matter how many projects are scanned.
+- **`metagit config graph suggest`:** report-only `GraphSuggestResult.stale_manual[]` flags active manual `graph.relationships` entries with no supporting inferred edge in the current scan (deprecated edges excluded; support is matched on endpoints, so a differing relationship type does not flag an edge); `graph-discover`/`graph-maintain` prompts, the `metagit-graph-maintain` skill, and `docs/reference/metagit-config.md` document the `status`/`provenance` lifecycle and the report-only `stale_manual` review step.
+- **Ignore-aware recursive scanning:** new `metagit.core.utils.repo_walk.iter_repo_files()` always prunes the shared scaffold denylist (`SCAFFOLD_PATH_SEGMENTS`, moved to `metagit.core.utils.scaffold_paths`) and honors nested per-directory `.gitignore` files (git-scoped, pruned during the walk, not post-filtered), including `!pattern` negations. `ImportHintScanner._scan_terraform_modules` now uses this walker instead of unbounded `Path.rglob("*.tf")`, exposing per-scan `last_walk_stats`; `WorkspaceSearchService` imports the shared scaffold constant.
+- **Durable `graph.relationships`:** `GraphRelationship` gains `status: Literal["active","deprecated","proposed"]` and `provenance: Literal["manual","promoted","imported"]` (both default consistent with existing manual entries); new `graph_validation.validate_graph_relationships()` requires a non-blank `id` and checks `from`/`to` endpoints against `workspace.projects[].repos`. `suggest --apply` validates the patched document (the exact model that would be written) and reports `validation_errors` instead of writing on failure.
+
+### Changed
+- **`metagit config validate` now exits 1 on invalid `graph.relationships`.** Manifests whose relationships lack an `id` or reference unknown projects/repos previously validated cleanly. *Migration:* add `id:` to existing `graph.relationships[]` entries and correct any endpoint that does not resolve to a `workspace.projects[].repos` entry.
+- **`metagit config graph suggest` default output is a human summary** (counts plus a short candidate list) instead of a raw JSON dump, and no longer includes `operations`. *Migration:* pass `--json` for the previous machine-readable payload.
+- **`graph.relationships[]` are written with the `from:` alias and explicit `status:`/`provenance:`.** Manifests previously round-tripped the internal `from_endpoint:` key, which fails `schemas/metagit_config.schema.json`. Both spellings still load; re-saving a manifest normalizes it to `from:`.
+
+### Fixed
+- **`iter_repo_files` gitignore precedence:** `.gitignore` rules are now evaluated in file order with last-match-wins, and a deeper directory's `.gitignore` overrides its ancestors' rules — matching `git check-ignore` instead of letting any ancestor `!` negation unconditionally beat a later deny pattern.
+- **`metagit config graph suggest --apply`:** applying to a manifest with no `graph:` section no longer writes a placeholder `example-value` relationship that made the following `metagit config validate` fail. Promotion now issues a single `set graph.relationships` carrying the complete list, rebuilt from the manifest on disk.
+- **`metagit config validate`:** graph and `agent_profile` rejections no longer print a misleading "Failed to load metagit configuration file:" line after the real reason.
+- **Terraform import scanning:** `iter_repo_files` filters on `suffix` before running gitignore checks and caches each directory's ancestor rule chain, removing a large regression on repos with many non-matching files. `files_skipped_gitignore` / `files_skipped_scaffold` now count only suffix-matching files.
+- **`metagit config example`:** generate valid values for `Literal`-typed fields (e.g. `graph.relationships[].status`/`provenance`) instead of a placeholder string, so the generated exemplar validates against `MetagitConfig`.
+
+## [0.23.3] - 2026-07-17
+
+
+
+### Fixed
+- **`metagit skills install --scope project` / `metagit mcp install --scope project`:** resolve project-local destinations against the nearest git repository root (not a nested cwd), so installs from subdirectories land in `.cursor/skills`, `.claude/skills`, etc. at the repo root.
+- **Hermes targeting:** honor `HERMES_HOME` (default `~/.hermes`) for `--target hermes` skills; write MCP into `$HERMES_HOME/config.yaml` under `mcp_servers` (not ignored `~/.config/hermes/mcp.json`); launch via the installed `metagit` binary (not `uvx metagit-cli`) and set `METAGIT_AGENT_MODE=true` on the Hermes MCP env block.
+- **MCP stdio handshake:** speak newline-delimited JSON per the MCP stdio transport spec (accept legacy `Content-Length` frames on read). Fixes hangs where standard NDJSON clients never received an `initialize` response.
+
 ## [0.23.2] - 2026-07-16
 
 

{metagit_cli-0.23.2 → metagit_cli-0.24.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: metagit-cli
-Version: 0.23.2
+Version: 0.24.0
 Summary: Metagit multi-repo management tool
 Author-email: Zachary Loeber <zloeber@gmail.com>
 Project-URL: Homepage, https://github.com/metagit-ai/metagit-cli

{metagit_cli-0.23.2 → metagit_cli-0.24.0}/docs/reference/metagit-agent.md

@@ -197,7 +197,7 @@ Writes `orchestration-overseer.md`, optional `AGENTS.md.fragment`, and `manifest
 | `cursor` | `.cursor/agents/*.md` | `~/.cursor/agents/` | agent |
 | `github_copilot` | `.github/agents/*.agent.md` | `~/.github/agents/` | agent |
 | `opencode` | `.opencode/agents/*.md` | `~/.config/opencode/agents/` | agent (subagent) |
-| `hermes` | `.hermes/skills/<name>/SKILL.md` | `~/.config/hermes/skills/<name>/` | skill |
+| `hermes` | `.hermes/skills/<name>/SKILL.md` | `$HERMES_HOME/skills/<name>/` (default `~/.hermes/skills/`) | skill |
 | `openclaw` | `.openclaw/skills/<name>/SKILL.md` | `~/.openclaw/skills/<name>/` | skill |
 | `windsurf` | `.windsurf/skills/<name>/SKILL.md` | `~/.codeium/windsurf/skills/<name>/` | skill |
 | `codex` | `.agents/skills/<name>/SKILL.md` | `~/.agents/skills/<name>/` | skill |
@@ -210,7 +210,7 @@ Writes `orchestration-overseer.md`, optional `AGENTS.md.fragment`, and `manifest
 | `cursor` | `.cursor/skills/` | `~/.cursor/skills/` | `.cursor/mcp.json` | `~/.cursor/mcp.json` |
 | `github_copilot` | `.github/skills/` | `~/.copilot/skills/` | `.vscode/mcp.json` (`servers`) | `~/.copilot/mcp-config.json` |
 | `opencode` | `.opencode/skills/` | `~/.config/opencode/skills/` | `.opencode/mcp.json` | `~/.config/opencode/mcp.json` |
-| `hermes` | `.hermes/skills/` | `~/.config/hermes/skills/` | `.hermes/mcp.json` | `~/.config/hermes/mcp.json` |
+| `hermes` | `.hermes/skills/` | `$HERMES_HOME/skills/` (default `~/.hermes/skills/`) | `.hermes/config.yaml` (`mcp_servers`) | `$HERMES_HOME/config.yaml` (`mcp_servers`) |
 | `openclaw` | `.openclaw/skills/` | `~/.openclaw/skills/` | `.openclaw/mcp.json` | `~/.openclaw/mcp.json` |
 | `windsurf` | `.windsurf/skills/` | `~/.codeium/windsurf/skills/` | `.windsurf/mcp_config.json` | `~/.codeium/windsurf/mcp_config.json` |
 | `codex` | `.agents/skills/` | `~/.agents/skills/` | `.codex/mcp.json` | `~/.codex/mcp.json` |

{metagit_cli-0.23.2 → metagit_cli-0.24.0}/docs/reference/metagit-config.full-example.yml

@@ -83,6 +83,10 @@ graph:
       metadata:
         source: metagit-config-example
 ...
+      # Lifecycle state of this relationship
+      status: active
+      # Origin of this relationship (hand-authored, promoted from a suggestion, or imported)
+      provenance: manual
   # Graph-level metadata for export pipelines
   metadata:
     source: metagit-config-example

{metagit_cli-0.23.2 → metagit_cli-0.24.0}/docs/reference/metagit-config.md

@@ -94,10 +94,22 @@ graph:
       label: API stack depends on shared modules
       tags:
         layer: platform
+      status: active
+      provenance: manual
 ```
 
 These edges are merged into cross-project dependency maps (`type: manual`) and available via `MetagitConfig.graph_export_payload()` for GitNexus-style exports. Request dependency type `manual` when calling `metagit_cross_project_dependencies` to focus on manifest-declared edges.
 
+### Lifecycle: `status` and `provenance`
+
+Each relationship carries a lifecycle `status` (`active`, `deprecated`, `proposed`) and a `provenance` (`manual`, `promoted`, `imported`):
+
+- Edges promoted via `config graph suggest --apply` are written with `status: active`, `provenance: promoted`.
+- Hand-authored edges default to `status: active`, `provenance: manual`.
+- Retire an edge by setting `status: deprecated` rather than deleting it — deprecated edges are excluded from `stale_manual` reporting and skipped by downstream tooling that only wants live edges.
+
+`config graph suggest` reports `stale_manual[]`: active manual relationships with no supporting inferred edge found during the current scan. Support is matched on the edge's **endpoints**, so an inferred edge of a different relationship type between the same two endpoints still counts as support. This is **report-only** — agents and operators should confirm before editing or removing a flagged edge (the scan may simply be missing a clone, a scoped `--workspace-root`, or a dependency type).
+
 ### Discover and suggest relationships (agent automation)
 
 **First-time / empty graph** — guided discovery report (no auto-apply):
@@ -115,6 +127,13 @@ metagit config graph suggest -c .metagit.yml --min-confidence high --apply
 metagit prompt workspace -c .metagit.yml -k graph-maintain --text-only
 ```
 
+### CLI flags
+
+- `metagit config graph suggest|export -c .metagit.yml` — path to the **manifest** (leaf or `metagit config -c … graph …`).
+- `--workspace-root` — checkout root used to **scan** inferred deps. Default: appconfig `workspace.path` resolved against the **manifest directory** (so `-c /other/umbrella/.metagit.yml` homes scans under that umbrella, not the caller cwd).
+- Global `metagit -c metagit.config.yaml` configures **appconfig**, not `.metagit.yml`.
+- Prefer `metagit config graph suggest -c .metagit.yml --verbose` when debugging empty candidates. Suggest JSON includes `workspace_root` for agents.
+
 MCP: `metagit_suggest_graph_relationships`, `metagit_apply_graph_relationships`. Bundled skill: `metagit-graph-maintain`.
 
 ### Export to GitNexus (Cypher)

{metagit_cli-0.23.2 → metagit_cli-0.24.0}/docs/reference/schemas/metagit_config.schema.json

@@ -968,6 +968,28 @@
           "description": "Extensible payload for GitNexus or other graph ingestors",
           "title": "Metadata",
           "type": "object"
+        },
+        "status": {
+          "default": "active",
+          "description": "Lifecycle state of this relationship",
+          "enum": [
+            "active",
+            "deprecated",
+            "proposed"
+          ],
+          "title": "Status",
+          "type": "string"
+        },
+        "provenance": {
+          "default": "manual",
+          "description": "Origin of this relationship (hand-authored, promoted from a suggestion, or imported)",
+          "enum": [
+            "manual",
+            "promoted",
+            "imported"
+          ],
+          "title": "Provenance",
+          "type": "string"
         }
       },
       "required": [

{metagit_cli-0.23.2 → metagit_cli-0.24.0}/docs/skills.md

@@ -27,6 +27,10 @@ metagit skills install --skill metagit-projects --target openclaw --dry-run
 
 Use `--skill` (repeatable) to install one or more bundled skills instead of the full set. Omit `--skill` to install every bundled skill. Add `--dry-run` to preview targets and paths without writing files.
 
+`--scope user` (default) writes under the agent’s user-global skills directory (for example `~/.cursor/skills`). `--scope project` writes under the **git repository root** (for example `.cursor/skills`), even when the command is run from a subdirectory.
+
+For Hermes, user-scope installs follow `HERMES_HOME` (default `~/.hermes`): skills go to `$HERMES_HOME/skills/`, and `metagit mcp install --target hermes` merges into `$HERMES_HOME/config.yaml` under `mcp_servers` using the installed `metagit` binary (not `uvx metagit-cli`).
+
 Optional MCP registration:
 
 ```bash

{metagit_cli-0.23.2 → metagit_cli-0.24.0}/schemas/metagit_config.schema.json

@@ -968,6 +968,28 @@
           "description": "Extensible payload for GitNexus or other graph ingestors",
           "title": "Metadata",
           "type": "object"
+        },
+        "status": {
+          "default": "active",
+          "description": "Lifecycle state of this relationship",
+          "enum": [
+            "active",
+            "deprecated",
+            "proposed"
+          ],
+          "title": "Status",
+          "type": "string"
+        },
+        "provenance": {
+          "default": "manual",
+          "description": "Origin of this relationship (hand-authored, promoted from a suggestion, or imported)",
+          "enum": [
+            "manual",
+            "promoted",
+            "imported"
+          ],
+          "title": "Provenance",
+          "type": "string"
         }
       },
       "required": [

{metagit_cli-0.23.2 → metagit_cli-0.24.0}/skills/README.md

@@ -27,6 +27,10 @@ metagit skills install --skill metagit-projects --target openclaw --dry-run
 
 Use `--skill` (repeatable) to install one or more bundled skills instead of the full set. Omit `--skill` to install every bundled skill. Add `--dry-run` to preview targets and paths without writing files.
 
+`--scope user` (default) writes under the agent’s user-global skills directory (for example `~/.cursor/skills`). `--scope project` writes under the **git repository root** (for example `.cursor/skills`), even when the command is run from a subdirectory.
+
+For Hermes, user-scope installs follow `HERMES_HOME` (default `~/.hermes`): skills go to `$HERMES_HOME/skills/`, and `metagit mcp install --target hermes` merges into `$HERMES_HOME/config.yaml` under `mcp_servers` using the installed `metagit` binary (not `uvx metagit-cli`).
+
 Optional MCP registration:
 
 ```bash

{metagit_cli-0.23.2 → metagit_cli-0.24.0}/skills/metagit-agent-access/SKILL.md

@@ -41,7 +41,7 @@ SKILL_ROOT="$(python3 -c "import metagit, pathlib; print(pathlib.Path(metagit.__
 After `metagit skills install --skill metagit-agent-access`:
 
 ```bash
-"$HOME/.config/hermes/skills/metagit-agent-access/scripts/optimize-agent-access.sh" . --apply --json
+"${HERMES_HOME:-$HOME/.hermes}/skills/metagit-agent-access/scripts/optimize-agent-access.sh" . --apply --json
 ```
 
 ### Inline fallback (no scripts)

{metagit_cli-0.23.2 → metagit_cli-0.24.0}/skills/metagit-cli/SKILL.md

@@ -23,8 +23,10 @@ Repo-root agent docs: [AGENTS.md](https://github.com/metagit-ai/metagit-cli/blob
 
 Global flags (most commands):
 
-- `-c path/to/metagit.config.yaml` — app config (default `metagit.config.yaml`)
-- Workspace manifest: `--definition` / `-c` on catalog commands (default `.metagit.yml`)
+- `metagit -c path/to/metagit.config.yaml` — **appconfig** only (default `metagit.config.yaml`)
+- Workspace manifest: `-c .metagit.yml` on `metagit config …`, `metagit workspace …`, and leaf `config graph suggest|export -c …`
+- Workspace manifest on the coordination families (`branch`, `lease`, `worktree`, `claim`, `task`, `semantic`, `merge`, `schedule`, `aos`): `--definition .metagit.yml` — these commands expose **no `-c`**
+- `--workspace-root` on graph suggest — checkout root used to **scan** inferred deps (default: appconfig `workspace.path`); not the manifest path
 
 ---
 
@@ -117,6 +119,8 @@ metagit config providers --show
 
 ### Graph relationships (suggest, apply, export)
 
+Trailing `-c .metagit.yml` on `config graph suggest|export` is valid (leaf manifest flag). Do not substitute `--workspace-root` for `-c`.
+
 | Task | Command |
 |------|---------|
 | First-time graph discovery (report only) | `metagit prompt workspace -k graph-discover -c .metagit.yml --text-only` |

{metagit_cli-0.23.2 → metagit_cli-0.24.0}/skills/metagit-control-center/SKILL.md

@@ -26,7 +26,7 @@ SKILL_ROOT="$(python3 -c "import metagit, pathlib; print(pathlib.Path(metagit.__
 Or from a full skill install:
 
 ```bash
-"$HOME/.config/hermes/skills/metagit-control-center/scripts/control-cycle.sh" .
+"${HERMES_HOME:-$HOME/.hermes}/skills/metagit-control-center/scripts/control-cycle.sh" .
 ```
 
 Wrapper behavior:

{metagit_cli-0.23.2 → metagit_cli-0.24.0}/skills/metagit-gitnexus/SKILL.md

@@ -20,6 +20,8 @@ Use this skill whenever GitNexus context is stale or missing for target reposito
 
 ## Manual workspace graph (`.metagit.yml` → Cypher)
 
+**CLI flags:** script `-c` and `metagit config graph export -c .metagit.yml` point at the **manifest**. `--workspace-root` is only the scan root for suggest; global `metagit -c` is **appconfig**.
+
 Promote inferred edges first (see `metagit-graph-maintain` skill), then ingest:
 
 ```bash

{metagit_cli-0.23.2 → metagit_cli-0.24.0}/skills/metagit-graph-maintain/SKILL.md

@@ -39,6 +39,8 @@ After sign-off, continue with the maintenance workflow below (or `metagit prompt
 
 ## Maintenance workflow
 
+**CLI flags:** `-c` on `config graph suggest|export` is the **manifest** path (trailing leaf `-c` is valid). `--workspace-root` is the checkout root used to scan inferred deps. Global `metagit -c` configures **appconfig**, not `.metagit.yml`.
+
 ### 1. Bootstrap context
 
 ```bash
@@ -58,6 +60,8 @@ MCP: `metagit_suggest_graph_relationships`
 
 Review `candidates[]` for `confidence`, `evidence`, and `source_edge_type`. Skip low-confidence edges unless the operator approves.
 
+Also review `stale_manual[]` — active manual relationships with no supporting inferred edge under the current scan, matched on endpoints so a differing relationship type still counts as support (report-only; do not edit/remove without operator confirmation). Use `--verbose` when candidates are empty to confirm scan roots and ignore prune counts.
+
 ### 3. Preview and apply
 
 ```bash
@@ -116,6 +120,12 @@ Return:
 - GitNexus ingest status (schema + statement count)
 - repos still stale/missing in GitNexus registry
 
+## Lifecycle
+
+- Promoted edges are written with `status: active`, `provenance: promoted`.
+- Deprecate retired edges by setting `status: deprecated` rather than deleting them.
+- `stale_manual[]` from suggest is report-only: confirm with the operator before editing or removing the flagged edges.
+
 ## Safety
 
 - Default `--min-confidence medium`; require operator approval for `--min-confidence all`

{metagit_cli-0.23.2 → metagit_cli-0.24.0}/src/metagit/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.23.2'
-__version_tuple__ = version_tuple = (0, 23, 2)
+__version__ = version = '0.24.0'
+__version_tuple__ = version_tuple = (0, 24, 0)
 
-__commit_id__ = commit_id = 'g985a83699'
+__commit_id__ = commit_id = 'g2822ee28e'