Context upgrade

Context Upgrade

Upgrade and layout-repair work is a controlled operator workflow. It must be invoked explicitly by the user when context-harness itself has an update, a local fleet refresh is requested, installed copies need validation, or a current-v3 layout needs repair. Do not invoke implicitly just because a repo contains context-harness files.

Prefer model-led edits, explicit verification, and conservative deployment over broad rewrites.

Start

1. Read the target repo's NOW.md, then relevant CONTEXT.md sections, especially ## Operating Constraints, ## Workflow, ## Relationships, and ## Learned Patterns.
2. Read PLAN.md when it contains migration findings, decisions, skipped repos, or previous verification output.
3. Identify the upgrade scope:
   • canonical source repo only
   • one target project
   • local project fleet refresh
   • installed skill deployment targets
   • current-v3 layout repair
4. Inspect the current worktree before edits. Treat unrelated changes as user work and do not revert them.

Upgrade Principles

• Keep AGENTS.md small: activation contract plus generated CONTEXT.md index. Do not duplicate durable context there.
• Preserve project-specific context. Replace only stale harness boilerplate, schema markers, generated index blocks, and runtime scripts that are meant to be managed.
• Prefer model-led edits over blanket migration scripts when local conventions may matter. Use scripts for detection, dry runs, refreshes, and repeatable mechanical changes.
• Include dirty target repos in fleet refreshes, but classify candidate paths, preserve unrelated work byte-for-byte, and record conflicts instead of forcing overwrites. Never reset, restore, clean, stash, commit, or push user work.
• Keep the preferred skill set small. Add or split a skill only when the invocation intent is genuinely different from existing skills.
• Modify canonical skill source in this repository. Treat installed copies and symlinked deployments as outputs unless the user explicitly asks for a local override.
• Route task-local findings and decisions to PLAN.md; durable upgrade lessons to CONTEXT.md; closeout state to NOW.md.

Source Upgrade

When changing context-harness itself:

1. Define the user-visible behavior and compatibility target before editing.
2. Update the canonical skill files, templates, scripts, README text, and tests that directly support the behavior.
3. Keep the supported layout current-v3 only unless the user explicitly chooses a new schema.
4. If CONTEXT.md changed, run:

node scripts/context-index.js update

5. Verify source changes with:

tests/run-all.sh
node scripts/context-index.js check

Project Layout Repair

Use this only when the user explicitly asks to repair or refresh an existing context-harness project. context-init is only for repositories with no context-harness layout.

For a single repo or fleet refresh:

1. Inspect the current files and git status first. Treat unrelated changes as user work.
2. Preserve project-specific context. Replace only stale harness boilerplate, schema markers, generated index blocks, and runtime scripts that are meant to be managed.
3. For partial or custom contexts, make model-led edits instead of forcing a generated layout.
4. Refresh generated indexes and local runtime scripts when the repair requires it.
5. Re-run node scripts/context-index.js check in representative targets.

Fleet Refresh Guardrails

For local fleet refreshes, inspect every target's status and include dirty repos under managed-file boundaries. Capture pre/post state, preserve unrelated dirty paths, and record managed local conflicts rather than overwriting them. Refresh only managed harness boilerplate/runtime, generated indexes, and unambiguous schema markers. Run node scripts/context-index.js update and node scripts/context-index.js check in each updated target, keep a machine-readable release ledger of changed/unchanged/failed targets, and do not let fleet work replace a target project's product task.

Deployment

After canonical source changes that should affect local harnesses:

1. Deploy through the user's normal deployment layer. In this repo, local deployment is usually via agent-nexus:

nexus sync --yes
nexus doctor

2. Verify representative installed copies or symlinks when frontmatter, invocability, hook behavior, or skill routing changed.
3. Tell the user when IDEs or agent hosts need restarting to pick up new frontmatter or skill metadata.

Closeout

Before finishing:

1. Summarize source files changed, target projects repaired/refreshed, skipped repos, and any deployment targets updated.
2. Record remaining fleet cleanup or unsupported targets in PLAN.md.
3. Promote only durable lessons to CONTEXT.md.
4. Update NOW.md with current focus, blockers, next step, timestamp, and touched files.
5. If the update made future catch-up materially easier through consolidation, use context-maintain Dream/Compact rules and log only actual edits.

Never store raw transcripts, secrets, raw API/web output, or bulky migration logs in context files.