vincentkoc/dotskills/codex-goal-mining

Codex Goal Mining

Purpose

Recover structured Codex goal history and convert free-form runs into evidence-backed, repeatable suites.

When to use

• The user asks what /goal commands ran locally or across the fleet.
• Large QA, beta, release, localization, model, cleanup, or PR campaigns need retesting.
• The user wants active, paused, blocked, or long-running goals ranked.
• Repeated semantic runs need stable suite names and copy-paste prompts.
• Goal time, thread span, tokens, dates, machines, or reachability matter.

Workflow

1. Collect structured data with scripts/codex-goal-report.py.

• Fleet report: scripts/codex-goal-report.py --policy ~/.config/codex-goal-mining/fleet-policy.json --json
• Local only: scripts/codex-goal-report.py --local --json
• Recent window: add --since YYYY-MM-DD.
• Exact activity window: add --activity-overlap --since <ISO> --until <ISO>.

Existing --since semantics remain creation-time based without that flag.

• Bounded repeat snapshots: add --cursor-file <path> to compute reset-safe

deltas. No cursor or report directory is created by default.

• Selected machines: repeat --machine <fleet-alias>.
• Require fleet coverage with --fleet; any unreachable source is rendered

and returns nonzero instead of silently reporting success.

• Use --one-attempt for a single configured/first interpreter attempt per

host. Policy entries may declare python and wsl_python.

• Remote collection requires fleet-credentials ssh-target TARGET. Its

token-free reply selects the registered helper or an unregistered native SSH alias. A missing helper, unsupported query, or invalid reply stops that target; it never authorizes native SSH.

• Set transport: "fleet-credentials" for a helper-owned target, and

wsl_transport separately for a WSL target. Removing its registration then remains an error. Omitted transport or "ssh" performs automatic lookup before each native interpreter attempt; it does not remember past ownership.

• Registered targets use one helper invocation with the configured interpreter

or python3. Helper refusals never retry another interpreter or use raw SSH. The helper needs its own enrolled context and Python 3.11+; the reporter remains compatible with Python 3.9. Local-only collection needs no helper.

• A registered collection has a 180-second observation bound. On timeout,

cancellation or pipe I/O failure, signal only its owned helper with TERM and allow ten seconds for cleanup. Stop the fleet pass, retain unresolved custody, and report remaining targets as unattempted. Local reaping does not prove remote exit.

• Start fleet configuration from references/fleet-policy.example.json; never commit a real private inventory.

1. Treat the data sources correctly.

• Prefer goals_1.sqlite for objective, status, tokens, and Codex-recorded active goal time.
• Join state_5.sqlite for thread timestamps and rollout paths.
• Use JSONL only as a fallback for older installations.
• Wall-clock thread span includes idle and resume gaps; never describe it as active labor.
• Goal database counters are lifetime snapshots. Only cursor deltas have an

observation interval, and a reset is unknown rather than zero.

• Preserve root/child identity where the state database supplies it. JSONL

fallback reports unknown rather than guessing.

1. Report collection coverage first.

• List reached and unreachable machines.
• Give the date range, goal count, statuses, total active goal time, and median goal time.
• Preserve exact transport blockers instead of silently shrinking the fleet.

1. Mine patterns semantically.

• Exact duplicate text is weak evidence because operators rephrase goals.
• Cluster by intended test surface, matrix, exit criteria, and repeated operating contract.
• Prioritize unfinished goals and recurring high-time campaigns.
• Separate product beta suites from operational queues such as contributor PR sweeps.

1. Produce reusable reruns.

• Use [suite:<name>] [baseline:<sha-or-date>] [matrix:<targets>] [exit:<criteria>].
• Include a fixed matrix, evidence requirements, blocker rules, and definition of done.
• Start from references/goal-suite-patterns.md, then adapt to current evidence.

1. Keep reports private.

• Default to terminal/JSON delivery. Use --output only when retained output

was requested or required.

• Scrub secrets, private hosts, personal absolute paths, and credentials before creating a gist or sharing externally.
• Use a secret gist unless the user explicitly requests public visibility.

1. For retained output or resumable collection state, apply the task artifact

contract from $operations-worktree. Reuse identity-matched canonical inventories instead of copying large payloads.

Inputs

• Local Codex stores under ~/.codex/.
• Optional fleet policy supplied with --policy or CODEX_FLEET_POLICY.
• Optional date window, machine aliases, suite focus, or output path.

Outputs

• Markdown or JSON fleet goal report.
• Ranked active, paused, blocked, and long-running goals.
• Semantic campaign summary with timing and reachability caveats.
• Stable copy-paste /goal suite prompts and rerun priority order.

Flow

stateDiagram-v2
    [*] --> Select
    Select --> Local: local only
    Select --> Lookup: remote target
    Lookup --> Helper: registered
    Lookup --> Native: unregistered and automatic mode
    Lookup --> Blocked: unknown or required registration absent
    Lookup --> StopFleet: timeout or cancellation
    Helper --> Report: completed or refused
    Helper --> StopFleet: timeout cancellation or I/O failure
    Native --> Report: completed or terminal refusal
    Native --> Lookup: interpreter failed and retry allowed
    Native --> StopFleet: timeout or cancellation
    Local --> Report
    Blocked --> Report
    StopFleet --> Report: include unattempted targets
    Report --> [*]