context-harness-upgrade

name

context_harness_upgrade

description

Use when the user asks to upgrade Tiny Context, update Tiny Context, use the Tiny Context upgrade skill to upgrade this project, upgrade project-tiny-context-harness, run ty-context upgrade, run make ty-context-upgrade, Project Tiny Context Harness upgrade, 用 Tiny Context upgrade skill 升级这个项目, 升级 tiny context, 升级tiny context, or 更新 project-tiny-context-harness in a Minimal Context Harness project.

Context Harness Upgrade

Package-Managed Boundary

This Skill is generated by ty-context sync and owned by the Harness package. Do not edit the generated context_harness_upgrade Skill directly.

This Skill handles Harness package upgrade and migration orchestration only. It does not author product facts, refactor business code, replace project tests or prove application quality.

Purpose

When the user asks to upgrade Tiny Context / Project Tiny Context Harness in an existing project, run the canonical upgrade path, handle only migration-scoped follow-up, and leave durable project semantics to the project Context and user-owned code. A sync-only release means no new migration is expected; it does not change the default upgrade entry for explicit upgrade requests.

Workflow

1. Read the project routing and Context entry points before changing files:
   • AGENTS.md
   • project_context/global.md
   • project_context/architecture.md
   • project_context/context.toml
2. Inspect the working tree with git status --short. Do not revert unrelated user changes.
3. Prefer project wrappers when present:
   • make ty-context-sync
   • make ty-context-upgrade
   • make ty-context-doctor
   • make validate-context
4. If no wrapper exists, use the package CLI explicitly:
   • npx --yes --package project-tiny-context-harness@latest ty-context sync
   • npx --yes --package project-tiny-context-harness@latest ty-context upgrade --check
   • npx --yes --package project-tiny-context-harness@latest ty-context upgrade
   • npx --yes --package project-tiny-context-harness@latest ty-context doctor
5. Run upgrade --check when useful, then run upgrade. This remains the default after package updates and for explicit upgrade requests because it plans migrations, applies safe migrations, refreshes managed assets and runs diagnostics.
6. Do not run standalone sync before upgrade for explicit upgrade requests. A direct sync is only a shortcut for releases explicitly marked sync-only when the user asks for managed-asset refresh instead of upgrade diagnostics.
7. Do not run standalone sync after a successful upgrade unless the project wrapper did not run sync or the user explicitly asks for another managed-asset refresh.
8. If upgrade --check or upgrade reports only safe_pending items and the command succeeds, do not invent additional manual cleanup.
9. If the report includes manual_required or blocked, handle only the listed migration scope. Use project_context/context.toml, role placement scan and the existing area graph to decide placement. Do not guess product or business semantics.
10. If the report includes blocked, treat it as a write preflight failure: resolve the blocked migration scope and rerun upgrade before expecting safe migrations or managed asset sync to have been applied.
11. Run diagnostics after migration-scoped follow-up:

• make ty-context-doctor or the CLI doctor
• make validate-context

12. Report commands run, migration status, diagnostics, files changed and any remaining manual items. Use Context: no durable project facts changed unless the upgrade exposed or required a real long-term project fact change.

Manual Handling Rules

• manual_required means the Harness detected a migration-scoped item but cannot safely choose the project meaning. Fix it only when the existing Context or file structure proves the intended placement.
• blocked means the safe target already exists or another conflict prevents a mechanical write. Do not overwrite. Compare source and target, preserve user content and ask for direction if the conflict cannot be resolved from project facts.
• Deprecated override Skills under ty-context-managed/override_skills/** should be migrated to standalone project-local Skills only when their content is still relevant. Do not merge them into package-managed default Skills.
• Ambiguous Context roles should not be guessed from filenames like api.md, notes.md or main.md alone. Register a role only when the manifest, path convention or durable content makes it clear.
• If upgrade creates default project_context/areas/main.md or project_context/areas/main/verification.md but project_context/context.toml already declares real project areas and does not register main, remove those generated defaults instead of preserving them as durable project facts. If main is registered or contains user-authored facts, do not delete it automatically.

Boundaries

• Do not restore legacy stage workflow, sprint documents or phase gates.
• Do not modify application code, product behavior, deployment settings or tests unless the user explicitly asks or a migration report points to a Harness-owned file in that scope.
• Do not write one-off command output, release logs, diagnostics or temporary migration notes into project_context/**.
• Do not edit package-managed generated surfaces directly in a consumer project unless the change is part of a migration conflict that cannot be resolved another way. Prefer rerunning upgrade / sync from the package source.