Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion FORK.md
Original file line number Diff line number Diff line change
Expand Up @@ -159,7 +159,7 @@ Plugins may control this lifecycle only through the typed `host.updates` methods

`syncUpstream` is a distinct **Hermes upstream → Axiom deploy** operation. It reuses the deploy-aware `hermes update` reconciliation and guarded resolver in a Hermes-owned isolated worktree, publishes the verified result to `origin/<deploy>`, and must not mutate live `HEAD`, rewrite local `main`, rebuild Desktop, or restart services. A retained conflict handoff remains resumable through the same action even when upstream divergence has since reached zero. Preparing/applying **Axiom deploy → Local** stays a separate explicit lifecycle; a prepared local stage blocks upstream sync because publishing a new deploy target would invalidate that artifact.

The resolver child owns edits and cheap structural checks only. The parent rejects unexpected untracked files, stages tracked changes only, commits a checkpoint, and binds all later validation and publication to that exact full `HEAD`. Marker phases retain `resolved_head`, `validation_sha`, and per-check status so failed or interrupted validation resumes from the checkpoint without rerunning passed checks. Parent checks run serially, with Python checks before Desktop checks; Desktop dependencies are prepared once inside the retained worktree with an isolated, script-free `npm ci`. A resolver timeout terminates the process tree, then salvages the work only when structural validation succeeds; otherwise the handoff remains `resolve_pending`.
The resolver child owns edits and cheap structural checks only. The parent rejects unexpected untracked files, stages tracked changes only, commits a checkpoint, and binds all later validation and publication to that exact full `HEAD`. For each conflict, the updater derives a bounded resolver brief under `update-reports/` containing only matched watch areas, conflicting files, protected invariants, upstream/drop guidance, precise references, and parent-owned check IDs. The child reads that brief instead of loading the full fork contract and operations corpus every run. Marker phases retain `resolved_head`, `validation_sha`, and a typed check ledger keyed by the full resolved SHA. Each result carries the stable check ID, canonical-spec SHA-256 fingerprint, status, nullable return code, bounded/redacted output tail, duration, and completion time. Passed results are reused only when both SHA and fingerprint match; old command-keyed `check_status` maps are accepted but not trusted for reuse. Parent checks run serially, with Python checks before Desktop checks; Desktop dependencies are prepared once inside the retained worktree with an isolated, script-free `npm ci`. A resolver timeout terminates the process tree, then salvages the work only when structural validation succeeds; otherwise the handoff remains `resolve_pending`.

If deploy resolution and parent validation succeed but the final push fails, the
handoff advances to `push_pending` instead of returning to conflict resolution.
Expand Down
4 changes: 2 additions & 2 deletions docs/axiom-fork-contract.md
Original file line number Diff line number Diff line change
Expand Up @@ -54,8 +54,8 @@ The `axiom` branch is expected to:
5. Treat upstream disparity as a maintenance signal, not a deploy blocker. `origin/axiom` freshness controls Axiom-Desktop updates; `upstream/main...HEAD` tells maintainers when to review drift.
6. Do not rely only on merge conflicts to retire fork patches. Conflicts catch same-line overlap, but upstream can land a better adjacent/architectural fix that merges cleanly. During each upstream merge, review the carried Desktop patch layer and drop local fixes only after verifying upstream has an equivalent or better behavior.
7. Keep fork-only code that has clean boundaries in **fork-owned modules**, not inline in upstream hotspot files. The deploy-branch update flow lives in `hermes_cli/axiom_update.py` (extracted from `main.py` on 2026-06-21) with a thin import seam back into `main.py`. Upstream never edits a filename it does not ship, so these carry with ~zero merge surface. See FORK.md → "Fork footprint reduction" for the seam contract and the lazy-import rule that avoids the circular import. When adding new fork-only update/deploy logic, put it in `axiom_update.py`, not back in `main.py`.
8. Plain `hermes update` autonomously resolves deploy handoffs when needed. The resolver child edits the retained temp worktree and performs only structural checks. The parent validates no unmerged files/conflict markers remain, rejects unexpected untracked files, stages tracked changes only, commits a checkpoint, and binds focused validation and publication to that exact full commit ID. It must hard-stop on sensitive paths or ambiguous Git state.
9. Parent validation is resumable. Marker phases retain `resolved_head`, `validation_sha`, and per-check status; retries require the retained `HEAD` to match, preserve validation failures, and skip checks already recorded as passed or unavailable. Checks run serially with Python before Desktop validation. Desktop validation prepares dependencies once inside the retained worktree with `npm ci --include=dev --ignore-scripts`; it never installs test tooling into the live Hermes runtime.
8. Plain `hermes update` autonomously resolves deploy handoffs when needed. The resolver child edits the retained temp worktree and performs only structural checks. The updater derives a bounded, conflict-scoped brief under `update-reports/`; it includes only conflicting files and matched catalog areas with invariants, upstream/drop guidance, precise references, and parent-owned check IDs. The child uses this brief as its primary contract rather than loading all fork/runbook/skill documents. The parent validates no unmerged files/conflict markers remain, rejects unexpected untracked files, stages tracked changes only, commits a checkpoint, and binds focused validation and publication to that exact full commit ID. It must hard-stop on sensitive paths or ambiguous Git state.
9. Parent validation is resumable. Marker phases retain `resolved_head`, `validation_sha`, and a typed ledger bound to the exact full resolved SHA. Every result records stable check ID, SHA-256 fingerprint of the canonical check spec, status, nullable return code, bounded/redacted output tail when available, duration, and completion time. Retries reuse a passed/unavailable result only when both resolved SHA and fingerprint match; a changed HEAD invalidates all results and a changed spec invalidates that check. Legacy command-keyed `check_status` markers are read safely but rerun into the typed ledger. Checks run serially with Python before Desktop validation. Desktop validation prepares dependencies once inside the retained worktree with `npm ci --include=dev --ignore-scripts`; it never installs test tooling into the live Hermes runtime.
10. A retained handoff is a snapshot, not a permanent merge state. Before launching a resolver for a phase-less or `resolve_pending` marker, compare the recorded `origin_head` and `upstream_head` against current `origin/<deploy>`. If both recorded refs are already ancestors, clear the stale marker/worktree and start a fresh deploy update; validation checkpoints must never be discarded by this snapshot rule. Resolver timeouts terminate the process tree and may continue only when structural resolution can be checkpointed safely. `push_pending` retries publish the recorded exact commit without rerunning resolution, and the marker/worktree are removed only after publication (and, for a normal update, live fast-forward) succeeds.
11. There are no deploy update modes. The first host to observe upstream work publishes the reconciled artifact; any later host fast-forwards to that same `origin/<deploy>` result.

Expand Down
Loading
Loading