Skip to content

Update documentation with 21 changed files (#4744) - #4784

Closed
rysweet wants to merge 4 commits into
mainfrom
feat/issue-4744-nodeoptions-max-old-space-size32768-saved-preferen
Closed

Update documentation with 21 changed files (#4744)#4784
rysweet wants to merge 4 commits into
mainfrom
feat/issue-4744-nodeoptions-max-old-space-size32768-saved-preferen

Conversation

@rysweet

@rysweet rysweet commented Jul 26, 2026

Copy link
Copy Markdown
Owner

Summary

Concise workflow-generated PR for documentation.

Issue

Closes #4744

Changed files

  • docs/reference/claim-reaper-convergence.md
  • docs/reference/engineer-inspect-worktree-resolution.md
  • docs/reference/merge-cap-decoupling.md
  • docs/reference/rpc-health-gate-diagnostics.md
  • docs/reference/rpc-health-stats-snapshot-readiness.md
  • mkdocs.yml
  • src/cognitive_memory/library_adapter.rs
  • src/cognitive_memory/mod.rs
  • src/engineer_loop/mod.rs
  • src/engineer_loop/tests_inspect_worktree_resolution.rs
  • src/engineer_worktree/claim.rs
  • src/engineer_worktree/mod.rs
  • src/error/display.rs
  • src/error/mod.rs
  • src/error/tests_variants_extra.rs
  • src/operator_commands_ooda/daemon/mod.rs
  • src/overseer/claim_reaper.rs
  • src/overseer/mod.rs
  • src/self_relaunch/gates.rs
  • src/self_relaunch/types.rs
  • src/status/provider.rs

Diff stat

 docs/reference/merge-cap-decoupling.md             | 165 ++++++++
 docs/reference/rpc-health-gate-diagnostics.md      | 219 +++++++++++
 .../rpc-health-stats-snapshot-readiness.md         | 381 ------------------
 mkdocs.yml                                         |   5 +-
 src/cognitive_memory/library_adapter.rs            | 277 +------------
 src/cognitive_memory/mod.rs                        |  12 -
 src/engineer_loop/mod.rs                           |  38 +-
 .../tests_inspect_worktree_resolution.rs           | 301 +++++++++++++++
 src/engineer_worktree/claim.rs                     |  73 +++-
 src/engineer_worktree/mod.rs                       |   4 +-
 src/error/display.rs                               |  10 +
 src/error/mod.rs                                   |  10 +
 src/error/tests_variants_extra.rs                  |  31 ++
 src/operator_commands_ooda/daemon/mod.rs           |  49 ---
 src/overseer/claim_reaper.rs                       | 170 +++++++-
 src/overseer/mod.rs                                | 176 +++++++++
 src/self_relaunch/gates.rs                         | 430 +++++++++++----------
 src/self_relaunch/types.rs                         |  49 +++
 src/status/provider.rs                             | 148 +------
 21 files changed, 1866 insertions(+), 1080 deletions(-)

Behavior

Implemented behavior through these branch commits:
f4dc782 fix(claim-reaper): produce Converged in production; drop false serde claims
7d50459 feat(overseer,self-relaunch): implement P2/P3/P4 production code; reconcile docs
ef5984f wip: checkpoint after implementation (steps 7-8)
3cb7b18 fix(engineer-loop): resolve real engineer worktree at inspect seam (#4744)

Validation

ℹ NODE_OPTIONS=--max-old-space-size=32768 (saved preference). To change: /home/azureuser/.amplihack/config
Starting Step 13: outside-in testing. Let me get the branch and inspect what changed.

● Get current branch and merge base (shell)
│ cd /home/azureuser/src/Simard-deploy-4049/worktrees/feat/issue-4744-nodeoptions-max-old-space-si
│ ze32768-saved-preferen && git branch --show-current && echo "---MERGE-BASE---" && git merge-base
│ HEAD origin/main 2>/dev/null || git merge-base HEAD main 2>/dev/null
└ 4 lines…

● Recent commits (shell)
│ cd /home/azureuser/src/Simard-deploy-4049/worktrees/feat/issue-4744-nodeoptions-max-old-space-si
│ ze32768-saved-preferen && git --no-pager log --oneline -15

Risk

No high-risk subsystem pattern detected from changed paths.

Checklist

  • Branch has 4 commit(s) ahead of main
  • Code review completed
  • Philosophy check passed

This PR was created as a draft for review before merging.

rysweet and others added 4 commits July 26, 2026 13:11
@rysweet
fix(engineer-loop): resolve real engineer worktree at inspect seam (#…
3cb7b18 
…4744)

The engineer-loop inspect phase could probe a synthetic, non-repository
`/tmp` path. `git rev-parse --show-toplevel` returned exit 128
(`fatal: not a git repository`), the inspection surfaced
`SimardError::NotARepo`, and a healthy-but-idle engineer was recorded as
producing nothing and then false-stale reaped — discarding whole
engineering loops (goal-board blocker 7f5afcca).

Fix (additive, non-breaking):
- Add `engineer_worktree::resolve_engineer_worktree(claim_key)` which
  resolves the engineer's real managed worktree under
  `<state_root>/engineer-worktrees/`, canonicalizes it, and confirms
  containment inside the managed root (symlink-escape safe).
- Add the distinct `SimardError::MissingWorktree { claim_key, expected_path }`
  variant so a genuinely-absent worktree is a fail-closed signal, never
  conflated with `NotARepo` for a live-but-idle engineer. Its Display is
  log-safe (claim key + expected path, no secrets, no raw subprocess output).
- Drive `run_local_engineer_loop` from the resolved worktree when the
  launching harness names the claim via `SIMARD_ENGINEER_CLAIM_KEY`; a
  named-but-absent claim fails loudly with `MissingWorktree` instead of
  probing a synthetic path. Env unset preserves legacy behavior.

Invariant: a valid engineer worktree never yields `NotARepo`.

Regression tests pin: valid worktree never NotARepo, idle != dead,
resolver returns the real managed worktree, absent claim -> MissingWorktree
(never a synthetic /tmp probe), and MissingWorktree is distinct from
NotARepo. Docs: docs/reference/engineer-inspect-worktree-resolution.md.

Closes #4744

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@rysweet
wip: checkpoint after implementation (steps 7-8)
ef5984f 
Automatic checkpoint to preserve work in progress.
Tests and implementation saved before refactoring phase.
@rysweet
feat(overseer,self-relaunch): implement P2/P3/P4 production code; rec…
7d50459 
…oncile docs

The prior checkpoint committed TDD tests (Step 7) for three bundled fixes but
left their production code unwritten, so `cargo test --lib` failed to compile.
This lands the minimal, philosophy-aligned production code so all committed
tests pass, and corrects the reference docs to describe ONLY shipped behaviour
(zero-BS).

P4 — claim-reaper convergence (#4755):
- Add terminal `InvestigationVerdict::Converged` (fail-closed, label
  "converged"), a routing target at parity with Blocked/Recoverable. The
  existing per-claim freshness-window archival guard already bounds
  re-archival; the doc is corrected to describe that mechanism instead of a
  non-existent SHA-256 fingerprint guard/store.

P2 — merge-cap decoupling (delivery:simard_merge_backlog):
- Add `Overseer.max_merges_per_cycle` (default 2) + a per-cycle `merges_this_cycle`
  counter, reset at plan build. Green+CLEAN+MERGEABLE merges draw from this own
  bounded budget in `gate` (via `is_auto_merge`), independent of the launch cap,
  so ready PRs drain when launches are exhausted. Eligibility untouched (`act`
  still re-verifies). Adds `max_merges_per_cycle_bound_is_honored` covering the
  budget branch.

P3 — rpc-health diagnostics (process:self_deploy_blocked):
- `ProbeOutcome` gains `EmptyStats` (exit-0 empty stdout) and `Unreachable`
  (supersedes `SpawnFailed`), derives `Debug`, and exposes `is_transient()`.
  Probe now captures stdout (both pipes drained) to distinguish a hollow
  success from a genuine round-trip. `run_rpc_health_gate` gains bounded
  retry + capped-exponential backoff over transient outcomes via new
  `RelaunchConfig.health_probe_max_attempts` (3) / `health_probe_backoff` (2s);
  deterministic faults (EmptyStats, non-zero exit) never retry. Fail-closed
  preserved. Docs corrected (no floor/ceil, usize not u32, actual test names).

All targeted + module suites green; cargo check --all-targets, clippy
(--lib --tests) and fmt clean.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@rysweet
fix(claim-reaper): produce Converged in production; drop false serde …
f4dc782 
…claims

Review feedback on P4 (#4755) / P3 bundle:

Finding 1 — Converged was dead scaffolding: the variant, its label(), and its
tests existed, and docstrings/doc claimed it "records ONE terminal decision that
stops re-archival," but RecipeStaleEngineerInvestigator::investigate() returned
Pending on BOTH branches, so Converged was never emitted in production. Wire it:
the reused-epoch branch (minted=false — investigation already dispatched this
freshness window) now returns the terminal, fail-closed Converged instead of
spinning on Pending. The minted branch (tick 1, genuine in-flight dispatch) stays
Pending. Operationally identical on the kept path (only the log token changes), so
the documented anti-59x convergence contract is now actually realized.

Finding 2 — false serde/persistence claims (zero-BS): verdicts are never
serialized or persisted (manifest.json holds only claim key/goal id/idle age/ts/
worktree; there is no serde anywhere), and RelaunchConfig derives only Clone,Debug
and is built programmatically, never deserialized. Reconciled every misleading
comment/doc to the honest mechanism:
- claim_reaper test docstring: drop the reference to the nonexistent test
  persisted_verdicts_deserialize_after_converged_added and the "verdicts persisted
  under reaped-engineers/ deserialize" claim; state label() tokens are stable and
  name-based (log-only).
- types.rs: the new rpc-health fields are additive with Default values (picked up
  by RelaunchConfig::default()/..Default::default()), not "serde-defaulted".
- claim-reaper-convergence.md: replace the "Serialization compatibility" block
  with a "Label stability, not serialization" note and fix the example so tick 1
  is verdict=pending (dispatch) and later reuse-in-place ticks are verdict=converged.

Tests: T1/T2 updated to expect Converged on reused-epoch ticks. All green:
overseer 735, claim_reaper 40, self_relaunch::types 14; clippy 0 warnings; fmt clean.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@rysweet rysweet added the simard-autonomous Simard-authored PR eligible for gated autonomous self-merge label Jul 26, 2026
@rysweet rysweet mentioned this pull request Jul 28, 2026
Merged
@rysweet

rysweet commented Jul 28, 2026

Copy link
Copy Markdown
Owner Author

Auto-closing this stale CONFLICTING auto-generated documentation draft: it can no longer merge cleanly and is superseded by the canonical open auto-doc PR #4826. Enforcing the single-open auto-doc PR invariant (goal_hygiene).

@rysweet rysweet closed this Jul 28, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

simard-autonomous Simard-authored PR eligible for gated autonomous self-merge

Projects

None yet

Milestone

No milestone

1 participant

@rysweet