Prepare local agent memory and rubrics context

[sepo-agent-app]

Summary

• Add npm --prefix .agent run prepare:local-agent to clone local memory/rubrics context into ignored .agent/local/.
• Generate .agent/local/AGENT_CONTEXT.md with MEMORY_DIR / RUBRICS_DIR guidance, memory/rubrics rules, checks, and sub-agent review notes.
• Update AGENT.md, install docs, and memory/rubrics architecture docs for local coding agents.

Verification

• npm --prefix .agent run build
• node --test .agent/dist/__tests__/prepare-local-agent-context-cli.test.js .agent/dist/__tests__/envelope.test.js
• node --test .agent/dist/__tests__/prepare-local-agent-context-cli.test.js
• git diff --check

Closes #121

Part of #314

[sepo-agent-app]

Rubrics Review

Total Score	Verdict	Rubrics Scored
94	PASS	10

Dimension	Rubric	Result	Score	Evidence
coding_workflow / generic	Make surgical changes	pass	8/8	Scope is limited to the requested local-agent context helper, docs, .gitignore, package script, and focused tests.
coding_workflow / generic	Reuse existing code	pass	8/8	Reuses git() and parseGitHubRepoSlugFromRemoteUrl instead of rebuilding repo-root and slug parsing logic.
coding_style / generic	Prefer simple implementations	pass	7/7	Adds one CLI with direct git operations and a single generated context file; no broad new framework.
coding_workflow / generic	Prefer explicit structured inputs	pass	7/7	CLI exposes typed flags for --repo, --dir, --remote, --memory-ref, and --rubrics-ref, with strict parsing and repo slug validation.
coding_workflow / generic	Minimal defaults, native escape hatches	pass	8/8	Defaults to .agent/local, origin, agent/memory, and agent/rubrics, while allowing explicit overrides.
coding_workflow / generic	Make user-facing automation idempotent	partial	4/7	Available branches are refreshed by deleting and recloning the checkout, but missing branches return early without removing any stale prior checkout.
coding_workflow / generic	Keep docs in sync	pass	7/7	Updates AGENT.md, install docs, memory docs, and rubrics docs for the new command and local context behavior.
communication / generic	Write audience-first documentation	pass	7/7	AGENT.md leads with the local agent task and commands before deeper memory/rubrics mechanics.
coding_workflow / generic	No per-file inventory tables in docs	pass	6/6	Docs describe the local workspace and command, without adding stale file inventory tables.
coding_workflow / generic	Read docs and linked context first	pass	6/6	Implementation matches the linked issue #121 plan: ignored .agent/local, memory/rubrics checkout helper, generated context, docs, and sub-agent guidance.

Notes

• The implementation satisfies the core request: .agent/local/ is ignored, prepare:local-agent is added, memory/rubrics are cloned into local context, docs explain the workflow, and tests cover success plus missing rubrics.
• The main rubric-specific gap is rerun behavior when a previously available branch becomes unavailable. The generated context reports the branch as unavailable, but the stale checkout remains on disk and may still be picked up by a local agent.

Findings

• WARNING: Under the idempotency rubric, refreshCheckout() only deletes the target checkout after branchExists() succeeds. If agent/rubrics or agent/memory existed during an earlier run and later becomes unavailable or the user points to a missing ref, the function returns an unavailable result without removing the old .agent/local/rubrics or .agent/local/memory directory. Evidence: early return at prepare-agent-context.ts lines 130-145, cleanup only on the available path at lines 147-151. A focused follow-up test should cover “first clone rubrics, rerun with missing rubrics ref, stale rubrics dir is removed.”

Final Rubric Verdict

PASS

[sepo-agent-app]

Sepo pushed fixes for this PR. Branch: agent/implement-issue-121/codex-26157128277. Requested by @sepo-agent.

• Cleared stale .agent/local/<name> checkout directories when the requested memory/rubrics ref is unavailable.
• Added a clone-then-rerun regression test for a missing rubrics ref so stale local context cannot remain.
• Verified with npm --prefix .agent run build, node --test .agent/dist/__tests__/prepare-local-agent-context-cli.test.js, and git diff --check.

[sepo-agent-app]

Sepo is dispatching follow-up automation.

Source	Next	Target	Round	Status
fix-pr	review	PR #323	5 / 40	Dispatched

Reason: PR fixes succeeded; dispatching review

[sepo-agent-app]

The local checkout is not currently on the PR head, so I’m using the live diff as the source of truth for the review. I don’t need to modify the branch to finish the rubric scoring.## Rubrics Review

Total Score	Verdict	Rubrics Scored
100	PASS	10

Dimension	Rubric	Result	Score	Evidence
coding_workflow / generic	Make surgical changes	pass	8/8	Scope stays on the local-agent context helper, focused tests, .gitignore, package script, and matching docs.
coding_workflow / generic	Reuse existing code	pass	8/8	The CLI reuses existing repo slug parsing from bootstrap-branch.js and the existing git() helper instead of adding parallel parsing infrastructure.
coding_style / generic	Prefer simple implementations	pass	7/7	Adds one direct CLI, one npm script, one ignored workspace, and focused tests; no unnecessary workflow or service layer.
coding_workflow / generic	Prefer explicit structured inputs	pass	7/7	prepare-agent-context.ts exposes typed flags for --repo, --dir, --remote, --memory-ref, and --rubrics-ref, with strict parseArgs handling.
coding_workflow / generic	Minimal defaults, native escape hatches	pass	8/8	Defaults cover .agent/local, origin, agent/memory, and agent/rubrics, while still allowing explicit overrides.
coding_workflow / generic	Make user-facing automation idempotent	pass	7/7	Reruns refresh cloned checkouts, regenerate AGENT_CONTEXT.md, and the latest diff removes stale checkout dirs when a ref becomes unavailable.
coding_workflow / generic	Keep docs in sync	pass	7/7	Updates AGENT.md, install docs, memory architecture docs, and rubrics architecture docs for the new local-agent command.
communication / generic	Write audience-first documentation	pass	7/7	AGENT.md leads with the local user task and commands before deeper memory/rubrics mechanics.
coding_workflow / generic	No per-file inventory tables in docs	pass	6/6	Documentation describes the local context workspace and command without adding per-file inventory tables.
coding_workflow / generic	Read docs and linked context first	pass	6/6	The implementation follows the linked #121 plan and fits the #314 stacked small-fixes context: ignored local workspace, memory/rubrics checkout helper, generated context, docs, and tests.

Notes

• The earlier idempotency gap is addressed in the current PR diff: refreshCheckout() now removes the target checkout directory before returning the missing-branch result, and the new regression test covers clone-then-rerun-with-missing-ref behavior.
• No rubric-specific follow-up needed.

Findings

• No rubric-specific findings.

Final Rubric Verdict

PASS

[sepo-agent-app]

AI Review Synthesis

Dual-agent review by Claude and Codex.
Requested by @lolipopshock.

Summary of PR/Issue

PR #323 implements #121 by adding local Codex/Claude-style agent context for the agent/memory and agent/rubrics branches. It adds an ignored .agent/local/ workspace, a prepare:local-agent script, a generated AGENT_CONTEXT.md, focused tests, and matching docs. This is part of the #314 stacked small-fixes batch. The earlier stale-checkout issue from prior review has been fixed at the current PR head.

Review

The current reviewer outputs converge on ship-ready behavior. Claude raised optional polish around generated environment exports, while Codex and rubrics review found no blocking or warning issues; the remaining notes do not require branch changes.

Issue	Severity	Description
No actionable issues remain	INFO	The prior stale local-context blocker is fixed and covered by regression testing; remaining reviewer notes are optional clarity or cleanup only.

Progress

• Verified linked context: Update the agent.md file to inform the memory / rubrics readme file #121 asks for ignored local memory/rubrics context, and batch small fixes #314 is the parent stacked small-fixes orchestration.
• The stale-checkout fix is present: missing refs now remove the stale .agent/local/<name> directory before returning unavailable.
• Regression coverage is present for clone-then-rerun-with-missing-rubrics-ref.
• Existing inline review comments and review threads are empty; no inline comments were posted, replied to, minimized, or resolved.
• Current PR check is passing.

Recommended Next Step

NO_AUTOMATED_ACTION: no unresolved actionable branch work remains.

Final Verdict

SHIP

Action Items

• No required branch-change work remains.

[lolipopshock]

@sepo-agent /answer

why this becomes such a huge PR ? anyway to simplify this?

[sepo-agent-app]

Yes. This PR is huge mostly because of stacking, not because the local-agent memory/rubrics change itself is that large.

What happened:

• PR Prepare local agent memory and rubrics context #323 is for Update the agent.md file to inform the memory / rubrics readme file #121, but its branch includes earlier stacked commits from the batch small fixes #314 batch:
  • Route no-branch-work reviews to self-approval #320: self-approval routing
  • Add natural-language repo config route #321: repo config route
  • Fall back from closed inferred implement base PRs #322: closed base PR fallback
  • then the actual Update the agent.md file to inform the memory / rubrics readme file #121 work
• The actual Update the agent.md file to inform the memory / rubrics readme file #121 change is mainly:
  • prepare-agent-context.ts
  • its focused test
  • .gitignore
  • AGENT.md
  • a few docs
• Measured by commits, the actual Update the agent.md file to inform the memory / rubrics readme file #121 work is about 8 files / ~573 additions, while the PR currently shows 49 files / ~3k additions because GitHub is displaying the stacked base too.

Best simplification options:

1. Cleanest: recreate/rebase Prepare local agent memory and rubrics context #323 from current main and cherry-pick only the two Update the agent.md file to inform the memory / rubrics readme file #121 commits:

   • 989b1210 Prepare local agent memory and rubrics context
   • 3f32e1f Clear stale local context on missing refs

   That should reduce the PR to the real local-agent scope.

2. If we intentionally want a stack: retarget Prepare local agent memory and rubrics context #323’s base to the previous stack PR branch, then merge the stack in order. But since Fall back from closed inferred implement base PRs #322 is already merged and Update the agent.md file to inform the memory / rubrics readme file #121 looks mostly independent, I think a fresh branch from main is better here.

3. Optional code-scope reduction: keep only the CLI, test, .gitignore, AGENT.md, and one install/local-agent doc in this PR. The extra architecture docs can be follow-up if we want an even smaller first pass.

My recommendation: replace/rebase this PR onto current main with only the #121 commits. The implementation itself is reasonable; the PR presentation is the problem.