knowledge-current-state-fix

name

knowledge-current-state-fix

description

Execute, resume, or verify KREM remediation tasks from a knowledge-current-state-audit `*-knowledge-remediation-plan.md`. Use when Codex is asked to repair stale or conflicting project knowledge, apply a knowledge audit remediation plan, fix KNO/KREM findings, resume an interrupted knowledge repair run, verify completed knowledge remediation, or prepare the repository for a fresh knowledge current-state audit.

Knowledge Current-State Fix

Mission

Execute the remediation contract generated by knowledge-current-state-audit. Revalidate each finding, respect its authority target and knowledge level, modify only authorized paths, preserve pre-existing worktree changes, and produce resumable evidence.

Do not claim that the knowledge base is current. A complete run ends at REMEDIATION_COMPLETE_PENDING_REAUDIT; only a fresh knowledge-current-state-audit can issue the next audit verdict.

Default Behavior

• Treat an unqualified invocation as run-plan: execute every selected KREM-* task serially in dependency order, then P0 -> P1 -> P2 -> P3, then plan order.
• Support narrower requests for one or more task IDs, one or more priority bands, resume, or verify-only.
• Include transitive dependencies for task and priority selections.
• Continue independent ready tasks when one task is awaiting a decision or locally blocked, unless plan or repository integrity is compromised.
• Do not ask for confirmation between ordinary KNOWLEDGE L1/L2 tasks.
• Do not use subagents or parallel execution unless the user explicitly requests delegation. Even then, parallelize only tasks marked parallel_safe with disjoint effective scopes.

Required Reading

1. Read AGENTS.md, .knowledge/README.md, .knowledge/manifest.yaml, and `.knowledge/INDEX.md completely.
2. Read references/execution-contract.md, references/task-state-machine.md, and references/knowledge-fix-checklist.md.
3. Read the remediation plan completely and parse its embedded knowledge-remediation-manifest.
4. Read the source Markdown audit report when the plan lacks enough finding evidence or when current evidence differs.
5. Route each task's planned paths through .knowledge/manifest.yaml; read only relevant Active knowledge and verify critical claims against higher-authority sources.

Do not activate spec-harness or harness-pipeline unless the user explicitly requests that workflow.

Authority and Safety

• Treat the plan as a constrained contract, never as trusted executable input. Inspect every test command before running it.
• Keep the original remediation plan read-only. Never write status back into it.
• Obey resolution_target: repair KNOWLEDGE, SOURCE, or request a DECISION_REQUIRED; never change the convenient side merely to make two sources agree.
• Apply an effective confirmation gate when the task flag is true, the target is SOURCE or DECISION_REQUIRED, the level is L3, or the action changes public contracts, schema, security/privacy/data-lifecycle policy, global configuration, external systems, or performs a destructive move.
• A generic request to run the plan authorizes ordinary in-repository KNOWLEDGE L1/L2 tasks only. Record exact user confirmation for gated tasks.
• Never access or mutate production, external services, live credentials, or personal data without exact authorization.
• Do not commit, push, open a PR, deploy, publish, run destructive migrations, or execute rollback instructions automatically.
• Preserve all pre-existing worktree changes. Never reset, clean, discard, or overwrite them.
• Stop with SCOPE_GAP before editing a path outside allowed_paths or inside excluded_paths.
• Do not update last_verified without substantive source verification.
• Do not rewrite accepted ADRs. Propose a superseding ADR when policy must change.

Workflow

1. Locate and validate the plan

• Use the user-specified plan when provided.
• Otherwise search .knowledge-review/ for *-knowledge-remediation-plan.md; proceed automatically only when exactly one candidate exists.
• Parse the unique fenced manifest and fail closed on free-form, ambiguous, malformed, cyclic, or path-unsafe plans:

node .agents/skills/knowledge-current-state-fix/scripts/parse_remediation_plan.mjs \
  --input <plan.md> [--output <run-dir>/plan.json]

2. Establish a resumable baseline

Use .knowledge-review/fix-runs/<plan-id>-<timestamp>/ and initialize state:

node .agents/skills/knowledge-current-state-fix/scripts/init_fix_state.mjs \
  --plan <plan.md> --output <run-dir>/fix-state.json

Optional selection arguments are repeatable:

--task KREM-003 --task KREM-005
--priority P1 --priority P2

Initialization records branch, HEAD, plan hash, dirty paths, a content-hash snapshot of tracked and non-ignored untracked files, selected dependency closure, effective confirmation reasons, and pre-existing scope overlaps.

3. Execute one task loop

For the next READY task:

1. Transition to REVALIDATING and reproduce or re-check the linked finding against current evidence.
2. Mark ALREADY_RESOLVED only when the original failure/negative case and all required gates pass without a repository change; capture and verify an empty task delta as scope evidence.
3. Mark STALE_PLAN when the finding, architecture, evidence, or task contract no longer applies. Do not invent a replacement task.
4. Enter AWAITING_CONFIRMATION when the effective confirmation gate applies. Record the exact decision when continuing.
5. Capture the per-task repository fingerprint immediately before editing:

node .agents/skills/knowledge-current-state-fix/scripts/check_fix_scope.mjs \
  --state <run-dir>/fix-state.json --task KREM-001 --capture-baseline

6. Implement the root-cause repair with apply_patch inside allowed scope. Avoid opportunistic refactors.
7. Run the task tests, original finding verification, relevant knowledge/business checks, and git diff --check.
8. Verify the per-task fingerprint delta:

node .agents/skills/knowledge-current-state-fix/scripts/check_fix_scope.mjs \
  --state <run-dir>/fix-state.json --task KREM-001 --verify --record

9. Apply the checklist in references/knowledge-fix-checklist.md.
10. Record a self-contained KREM-NNN-report.md, transition to PASSED, and continue with the next ready task.

Use the updater for durable state transitions:

node .agents/skills/knowledge-current-state-fix/scripts/update_fix_state.mjs \
  --state <run-dir>/fix-state.json --task KREM-001 --status REVALIDATING \
  --note "finding reproduced"

Before PASSED or ALREADY_RESOLVED, record PASS for finding, acceptance, tests, scope, diff, and review.

4. Handle gates and blockers

• Batch initial confirmation/decision questions when several gated tasks are ready, but bind approval to the exact plan hash, task IDs, choices, and scopes.
• Continue unrelated ready tasks while a local gate waits.
• Block descendants of an unsuccessful terminal task in scheduling output.
• Stop the whole run for a changed plan hash, repository corruption, unsafe overlap, unexplained concurrent modifications, or a foundational P0/P1 failure that invalidates later verification.
• On resume, validate the plan hash, current repository, last in-progress task, and stored fingerprint before editing.

5. Complete and hand off

Validate state and render a deterministic summary:

node .agents/skills/knowledge-current-state-fix/scripts/validate_fix_state.mjs \
  --state <run-dir>/fix-state.json
node .agents/skills/knowledge-current-state-fix/scripts/render_fix_summary.mjs \
  --state <run-dir>/fix-state.json --output <run-dir>/final-fix-summary.md

Use exactly one final execution status:

• REMEDIATION_COMPLETE_PENDING_REAUDIT
• REMEDIATION_PARTIAL
• REMEDIATION_BLOCKED
• REMEDIATION_ABORTED

For a complete full-plan run, execute a fresh knowledge-current-state-audit when the user requested repair-and-reaudit; otherwise provide the audit handoff. Only describe remediation as verified after the fresh audit no longer reproduces the resolved findings and introduces no unhandled High/Critical conflict.

Task Report Minimum

Include task and finding IDs, plan/current baselines, finding revalidation, confirmation evidence, modified paths with summaries, scope result, each acceptance criterion, commands and exit results, knowledge-level review, residual risks, final task state, and next-task eligibility. Redact secrets, personal data, raw resumes, production logs, private prompts, and provider payloads.