Goal Lock

Goal Lock

Use this skill as the task control layer for non-trivial repository work. It keeps each run isolated in its own task folder, grounded in a spec, resumable after context compaction, and honest about verification, issues, and blockers.

Allowed task.json statuses are only:

• in_progress
• completed
• blocked
• pruned

Do not write complete, done, paused, or other status variants.

Start

1. Inspect the relevant repository surface before making commitments.
2. Classify the run:
   • short: one bounded outcome, likely finishable in one session.
   • long: phased work, broad architecture, many subsystems, high risk, or likely compaction.
3. Create a task folder with the scaffolder:
   • python3 .agents/skills/goal-lock/scripts/scaffold_goal_task.py --kind short --title "<short title>" --root <repo-root>
   • python3 .agents/skills/goal-lock/scripts/scaffold_goal_task.py --kind long --title "<short title>" --root <repo-root>
4. Use the printed folder path as the task anchor for the rest of the run.
5. If the active collaboration mode forbids file edits, do not scaffold; keep the same structure in the response or plan instead.

Task folders live under:

• docs/agent-work/shorttasks/<YYYYMMDD-HHMMSSZ-slug>/
• docs/agent-work/longtasks/<YYYYMMDD-HHMMSSZ-slug>/

Required Spec Step

Every goal-lock run starts with the spec-refiner workflow:

• Short tasks: write one repo-grounded spec.md before implementation.
• Long tasks: write a repo-grounded top-level spec.md overview and phased-plan.md first, then refine each phases/phase-XX-spec.md immediately before implementing that phase.

Specs must name verified codebase facts, success criteria, assumptions, and developer handoff notes. Do not invent product or repository facts.

Task Folder Contract

Every task folder contains:

• task.json: id, kind, status, title, timestamps, and current phase.
• spec.md: repo-grounded implementation spec for short tasks or overview spec for long tasks.
• logger.md: chronological progress ledger, discoveries, decisions, and compaction notes.
• implementation.md: touched areas, intended edits, actual edits, and deviations.
• verification.md: commands or manual checks, results, skipped checks, and evidence.
• audit.md: self-audit for short tasks; optional subagent audit notes when used.
• issues-and-blockers.md: discovered issues, blockers, danger level, owner, and resolution status.

Long task folders additionally contain:

• phased-plan.md: full implementation roadmap.
• phases/phase-XX-spec.md: just-in-time phase specs.
• phases/phase-XX-log.md: phase execution notes.
• subagent-audit-plan-compliance.md: independent audit against user goal, plan, and specs.
• subagent-audit-code-health.md: independent audit for regressions, duplication, dead code, missed verification, and architectural drift.

Live Loop

Keep logger.md and task.json current:

• after initial discovery and spec creation
• after each milestone, phase, or major discovery
• before risky or newly in-scope changes
• after verification
• before and after subagent audits
• when resuming after compaction or context loss

Before each new milestone or phase, run a drift check:

• Does the next step still serve the original user goal?
• Has scope expanded without an explicit reason?
• Are unrelated files or systems being changed?
• Does the plan still match discovered codebase facts?
• Is the next step the smallest useful step?

Stop and ask the user when a drift check fails, discovered facts contradict the plan, scope must expand materially, or high-risk/out-of-scope files or contracts must change.

Resume After Compaction

On resume:

1. Re-open the remembered task folder if the path survived context compaction.
2. If no path survived, run python3 .agents/skills/goal-lock/scripts/resume_goal_task.py --root <repo-root> or scan docs/agent-work/shorttasks/*/task.json and docs/agent-work/longtasks/*/task.json.
3. Resume the newest task whose status is not completed or pruned; treat unknown status values as malformed until fixed.
4. If more than one plausible active task exists, ask the user which task to resume.
5. Read task.json, logger.md, the active spec or phase spec, issues-and-blockers.md, and verification.md before continuing.

Audits And Blockers

Short tasks require a written self-audit in audit.md. Use a subagent audit when the task is risky, surprising, multi-file, or user-visible enough that independent review is worth the overhead.

Long tasks require two subagent audits before completion when subagent tooling is available:

• plan/spec compliance audit
• code health, regression, duplication, dead-code, and verification audit

If subagents are unavailable, record the skipped audit and reason in the relevant audit file. Do not pretend an independent audit happened.

For completed long tasks, do not leave placeholder top-level audit.md text behind. If the real completion audits live in subagent-audit-plan-compliance.md and subagent-audit-code-health.md, update audit.md to point to those files and summarize the result.

Codex may fix small in-scope issues discovered while working. Ask for approval before fixing dangerous or out-of-scope issues involving security/auth, data deletion, migrations, billing, public APIs/contracts, broad refactors, or unrelated systems.

Keep durable unresolved findings in issues-and-blockers.md; promote important unresolved items to existing repository audit or architecture issue docs when relevant.

Verification And Completion

Prefer targeted verification first. Broaden to larger tests, lint, build, or manual checks when the risk or touched surface warrants it.

Before calling the task complete:

• record exact verification commands or manual checks
• state skipped or blocked verification honestly
• summarize changed files and behavior
• list remaining risks, issues, and blockers
• update task.json status to completed or blocked
• run python3 .agents/skills/goal-lock/scripts/validate_goal_task.py <task-folder> and fix any contract errors

For clean completed short tasks, prune the folder to summary.md plus task.json. Keep the full short-task folder when verification failed, unresolved blockers remain, or the task changed architecture.

Never claim live, production, full-suite, or end-to-end verification unless it actually ran.

Final responses for goal-lock work should include:

• task folder path
• final status
• verification run
• verification skipped or blocked
• residual risks

Helper Scripts

• scaffold_goal_task.py: create standard short or long task folders.
• validate_goal_task.py: validate status values, required files, scaffold placeholders, verification sections, blockers, and long-task audit records.
• resume_goal_task.py: list active or malformed task folders.
• close_goal_task.py: close a task as completed, blocked, or pruned; it refuses completed/pruned closeout when validation fails.