Chore: Add Codex Remember validation helper and setup-aware fast-track guidance

[bponghneng]

Chore: Add Codex Remember Validation Helper and Setup-Aware Fast-Track Guidance

Summary

• Type: Chore
• Status: Draft
• Intent: Add validation support to the public Codex Remember skill and make setup detect, report, and optionally install Memory Fast-Track steering guidance.
• Value: Reduces memory maintenance errors while keeping repository-specific fast-track behavior in project steering documents.
• Context: The Codex Remember and Recommend skills currently support setup, manual load, journaling, review, and recommendations, but they do not provide an automated validation helper. Memory Fast-Track behavior is already documented in workspace steering documents such as AGENTS.md; setup should help users notice and install that guidance rather than implementing generic Git sync automation in the skill.
• Companion: This is the Codex companion to v8chllc/claude-plugins#11.

Scope

In Scope

• Add a Remember validation helper to the public Codex plugin repository:
  • codex-plugins/plugins/v8ch/skills/remember/
• Add a $remember validate or equivalent Codex workflow trigger.
• Integrate validation reporting into $remember setup.
• Update the Codex Recommend write workflows to run or instruct a validation preflight before modifying memory.
• Add setup detection for missing Memory Fast-Track steering guidance in AGENTS.md.
• When fast-track steering is missing, setup reports the gap and offers to apply a generated Codex-appropriate section after user approval.
• Add focused tests for validation and setup behavior in codex-plugins where test coverage exists.

Out of Scope

• Implementing a generic fast-track Git automation command inside Remember.
• Replacing repository-owned steering documents as the source of truth for fast-track behavior.
• Changing memory entry semantics beyond validation requirements.
• Modifying installed runtime copies under ~/.codex, ~/.agents, plugin caches, or marketplace snapshots.
• Changing the Claude Code implementation; that belongs in v8chllc/claude-plugins#11.

Affected Surfaces

• Codex Remember skill instructions, references, scripts, and tests in codex-plugins.
• Codex Recommend skill instructions in codex-plugins, only where needed for validation preflight behavior.
• Codex plugin manifests, marketplace metadata, or installer mappings only if repository tests require updates for new helper files.

Chore Details

• Category: workflow/tooling
• Current state: Codex Remember can create and write memory files, and review can manually identify stale or duplicate entries. Recommend dedupes proposed additions before writing. There is no helper that validates memory structure, journal metadata, or setup steering state.
• Desired end state: Codex users can run a validation workflow, setup reports validation status, Recommend avoids compounding malformed memory, and setup can offer to install Memory Fast-Track steering guidance when missing.
• Risk if deferred: Memory files can drift into malformed or duplicated states, and projects may lack the steering guidance needed to safely fast-track memory-only updates.
• Compatibility constraints: Keep this issue aligned with the Claude companion while preserving Codex command syntax and AGENTS.md steering behavior.

Acceptance Criteria

• Codex remember includes a validation workflow in codex-plugins.
• Validation checks .remember/MEMORY.md for expected sections, known type markers, required fields, and duplicate active context entries.
• Validation checks .remember/memory/YYYY-MM-DD.md journal filenames and remember-journal metadata blocks.
• Validation reports issues without mutating files by default.
• Validation uses human-readable output by default.
• Validation includes a minimal machine-readable JSON mode for future automation.
• JSON output includes overall status, counts, and issue objects with severity, code, path, message, and optional suggested_fix.
• $remember setup reports validation results after confirming memory files exist.
• $remember setup detects whether AGENTS.md contains a Memory Fast-Track Workflow section.
• If fast-track steering is missing, setup reports the gap and offers to apply a generated section after user approval.
• The generated fast-track section covers trigger phrases, allowed memory-only paths, fetch-first behavior, conflict limits, secret review, git diff --check, PR/MR preference, direct-push exception, and post-merge verification.
• Generated fast-track guidance accounts for branch/platform differences such as GitHub origin/main with PRs and GitLab origin/master with MRs.
• Codex Recommend write workflows run or instruct a validation preflight before applying memory changes.
• If validation fails before a Recommend write, the workflow reports the issues and avoids compounding malformed memory unless the user explicitly proceeds.
• Tests cover valid and invalid memory files, duplicate context entries, malformed journal markers, bad journal filenames, machine-readable output, and setup detection/application of fast-track steering.

Edge Cases and Failure Modes

• Missing .remember/MEMORY.md: validation should report memory as uninitialized and point to setup.
• Missing .remember/memory/: validation should report partial initialization and point to setup.
• Custom AGENTS.md has a related but non-matching fast-track section: setup should avoid destructive edits and ask for manual review or explicit approval.
• Repository default branch is not obvious: generated guidance should use placeholders or detected branch data rather than hardcoding the wrong remote branch.
• GitHub/GitLab platform is not obvious: generated guidance should avoid claiming unsupported PR/MR commands.
• Existing malformed memory should not be auto-rewritten during validation.

Implementation Guidance

Proposed Approach

• Add a small helper script or reference-backed workflow under the Codex Remember skill package.
• Keep validation deterministic and file-based; do not require network access.
• Define a concise validation report format with severity, file path, and fix guidance.
• Provide default human-readable output plus a minimal JSON mode for automation.
• Add setup steps that:
  • ensure core memory files exist,
  • run/report validation,
  • inspect AGENTS.md,
  • offer a generated Memory Fast-Track section when missing.
• Keep fast-track sync itself in steering docs. The generated section should be adapted from the Vault and WSWS workspace examples.
• Update Codex Recommend workflows to invoke or require validation preflight before memory writes.

Dependencies and Constraints

• Codex uses $remember command-style references and AGENTS.md steering files.
• Public codex-plugins is the source of truth for this Codex skill.
• Follow codex-plugins/AGENTS.md and validation guidance before implementation.
• Preserve alignment with the Claude companion issue after normalizing syntax and steering-file differences.

Likely Areas Touched

• codex-plugins/plugins/v8ch/skills/remember/SKILL.md
• codex-plugins/plugins/v8ch/skills/remember/references/
• codex-plugins/plugins/v8ch/skills/remember/scripts/
• codex-plugins/plugins/v8ch/skills/recommend/SKILL.md
• Related tests and plugin metadata as required by the repository.

Rollout, Migration, and Rollback

• Rollout: Implement in codex-plugins; coordinate behavior with the Claude companion implementation.
• Migration: Existing projects can run setup or validate; setup offers steering additions only after approval.
• Rollback: Revert skill/helper changes; no user project files are changed unless setup was explicitly approved in that project.

Observability

• Human-readable validation output should summarize pass/fail counts and list actionable issues by file.
• JSON validation output should expose the same result in a small stable schema.
• Setup output should clearly state whether Memory Fast-Track steering is present, missing, added, or skipped.

Test and Evidence Plan

• Automated checks: Run focused Codex plugin asset tests, helper tests, and manifest/marketplace tests required by codex-plugins.
• Manual checks: Review Codex skill wording for $remember syntax, AGENTS.md steering behavior, and generated fast-track section content.
• Evidence before merge: Include command output for tests run, or explain checks that could not run.

Resolved Questions

• Validation output format: use human-readable output by default and include a minimal machine-readable JSON mode for future automation. Keep the JSON schema small and stable with overall status, counts, and issue objects containing severity, code, path, message, and optional suggested_fix.

Agent Instructions

• Implement only the in-scope Codex behavior and acceptance criteria above.
• Keep the Codex implementation aligned with the Claude companion while preserving Codex command syntax and AGENTS.md steering-file behavior.
• Do not implement generic fast-track Git automation inside Remember.
• Do not modify installed runtime copies.
• Include validation evidence or explain why a check could not be run.