harbor-contract-change

name	harbor-contract-change
description	Use when adding or modifying APIs, schemas, public functions, parser/export/writeback behavior, workflow nodes, CLI behavior, JSON output, file write behavior, or any change with possible Contract Impact under Harbor-spec.

Harbor Contract Change Skill

Version: Harbor-spec v1.3.0
Purpose: Contract-impacting change workflow for Harbor-managed repositories

---

1. Purpose

Use this skill when a task may affect a Contract.

This skill is an on-demand workflow entrypoint.

It is not source of truth.

It must follow:

AGENTS.md
.harbor/policy.yaml
.harbor/safety.yaml
.harbor/rules/contract-rules.md
.harbor/rules/ddt-rules.md
.harbor/rules/runtime-safety.md
.harbor/rules/diary-rules.md
.harbor/rules/project-rules.md, if present

Core principle:

Implementation changes must not leave contracts stale.

---

2. When to Use

Use this skill when adding, modifying, reviewing, or refactoring anything that may affect:

behavior
args
returns
raises
schema
side effects
state changes
idempotency
security
permission
persistence
event shape
database shape
export format
CLI output
JSON output
file write target
exit code
configuration behavior
migration behavior
external-visible result
user-visible result

Typical tasks:

adding or modifying public API
adding or modifying public function
changing CLI command behavior
changing CLI output
changing JSON output
changing schema or data model
changing parser behavior
changing export behavior
changing file writeback behavior
changing workflow node behavior
changing MCP / tool schema
changing event schema
changing auth / permission / security logic
changing migration behavior
changing generated context behavior
changing workspace layout behavior

---

3. Boundary With AGENTS.md, Project Rules, and Other Skills

3.1 AGENTS.md

AGENTS.md is the lightweight cross-tool entrypoint.

It defines the minimum Harbor workflow and instruction priority.

This skill should not duplicate all AGENTS rules.

Use AGENTS.md for:

global role
workspace boundaries
default workflow
instruction priority
context loading order
completion expectations

---

3.2 Project Rules

Project-specific rules live in:

.harbor/rules/project-rules.md

Use Project Rules for:

technology stack
directory map
strictness map
verified test commands
project-specific contract sources
project-specific safety boundaries
local skill routing

If this skill conflicts with Project Rules, inspect .harbor/policy.yaml and .harbor/safety.yaml.

Machine policy wins over Markdown rules.

---

3.3 Related Skills

Use other skills when needed:

harbor-code-review
  Use for reviewing diffs, implementation correctness, semantic drift, and contract consistency.

harbor-ddt-diary
  Use when updating tests, DDT bindings, l3_version, Diary Drafts, changelog, or release notes.

harbor-safety-preflight
  Use before risky operations, protected file changes, dependency changes, migrations, CI/CD, destructive commands, or .harbor/*.yaml changes.

harbor-context-refresh
  Use when generated context under .harbor/views/** needs refresh.

harbor-workspace-migration-plan
  Use for workspace diagnostics, migration dry-run, cleanup planning, or canonical workspace changes.

This skill may route to these skills, but should not replace them.

---

4. Context Loading Order

Before editing source files, load only the necessary context.

Default order:

1. AGENTS.md

2. Project Rules, if present:
   .harbor/rules/project-rules.md

3. Contract rules:
   .harbor/rules/contract-rules.md

4. DDT rules, if tests or l3_version may be affected:
   .harbor/rules/ddt-rules.md

5. Runtime safety rules, if risky operation may be involved:
   .harbor/rules/runtime-safety.md

6. Diary rules, if the change is important:
   .harbor/rules/diary-rules.md

7. Canonical project structure:
   .harbor/views/project-structure.md

8. Relevant canonical L2 README:
   .harbor/views/l2/<module>/README.md

9. Relevant canonical Module Capsule:
   .harbor/views/modules/<module>/module-card.md
   .harbor/views/modules/<module>/review-checklist.md
   .harbor/views/modules/<module>/debug-playbook.md

10. Relevant contract sources

11. Relevant implementation files

12. Relevant tests, fixtures, snapshots, schemas, or DDT targets

Do not read the whole repository unless the canonical project structure, L2 README, Module Capsule, source files, and tests are insufficient.

Do not treat generated context as source of truth.

Generated context helps orientation.

Source code, tests, schemas, policy, and diary define the actual project state.

---

5. Contract Sources to Inspect

Inspect only relevant contract sources.

Possible contract sources:

docstring
type hints
Pydantic model
FastAPI route
OpenAPI schema
TypeScript type
Zod schema
database migration
event schema
SSE / WebSocket message schema
CLI command schema
MCP tool schema
JSON output
snapshot output
golden file
tests
fixtures
examples
public behavior
user-visible behavior
external integration behavior
file write behavior

If multiple contract sources exist, do not pick one blindly.

Keep them synchronized.

---

6. Step 1: Decide Contract Impact

Before changing implementation, decide:

Contract Impact: yes
Contract Impact: no
Contract Impact: uncertain

Use yes when the change affects any of:

behavior
args
returns
raises
schema
side effects
state changes
idempotency
security
permission
persistence
event shape
database shape
export format
CLI output
JSON output
file write target
exit code
configuration behavior
migration behavior
external-visible result
user-visible result

Use no only when behavior and externally visible results remain unchanged.

If uncertain, inspect more context.

Do not silently treat uncertainty as no impact.

---

7. Step 2: Determine Strictness

Use .harbor/policy.yaml as the source of truth when available.

Default strictness:

strict
standard
light

Treat as strict when touching:

public API
public CLI
public JSON output
core schema
Pydantic model used externally
OpenAPI schema
parser
export
file writeback
review pipeline
workflow node
auth / permission / security
migration
CI/CD
critical path
user-visible result generation
external integration
tool schema
MCP tool schema
workspace layout
generated context behavior

Treat as standard for:

ordinary business logic
service functions
repositories
stable internal APIs
module-level workflows
non-critical data transformations

Treat as light for:

internal helpers
low-risk utilities
test helpers
script-local functions
small formatting helpers

If a target seems light but is used by a strict path, upgrade its strictness.

---

8. Step 3: Check Runtime Safety

Before editing or running commands, decide:

Runtime Safety Risk: yes / no

Use yes when the task involves:

deleting files
batch-moving files
.env or secrets
migrations
CI/CD
Docker / deployment
dependencies
destructive commands
git push
git reset --hard
production config
auth / permission / billing
user data handling
.harbor/*.yaml
.generated or exported skills
external network access

If safety risk exists, use:

harbor-safety-preflight

Do not silently perform risky operations.

---

9. Step 4: Apply Change Order

If Contract Impact: yes, use this order:

1. Read or define the relevant contract.
2. Determine strictness.
3. Update contract first if intended behavior changes.
4. Update implementation.
5. Update tests / DDT.
6. Check semantic drift.
7. Refresh generated context if needed.
8. Create Diary Draft if important.
9. Accept baseline only after verification and explicit user request.

If Contract Impact: no:

1. State why external behavior remains unchanged.
2. Keep the change minimal.
3. Add or run tests if risk justifies it.
4. Refresh generated context only if module boundaries or context changed.

If Contract Impact: uncertain:

1. Inspect more contract sources.
2. Inspect tests / fixtures.
3. Inspect generated context only as orientation.
4. Ask the user only if intended behavior cannot be inferred safely.
5. Do not silently proceed as if there is no impact.

---

10. Step 5: DDT / Test Handling

If the change affects strict targets, tests / DDT are required unless impossible.

For strict DDT targets:

use explicit l3_version
never use strategy="latest"

Allowed:

@harbor_ddt_target("module.func", l3_version=1)
def test_func_success_path():
    ...

Forbidden for strict targets:

@harbor_ddt_target("module.func", strategy="latest")
def test_func_success_path():
    ...

If the project does not implement the decorator, preserve binding intent with comments:

# harbor-ddt-target: module.func
# l3_version: 1
def test_func_success_path():
    ...

When contract changes:

1. Update contract.
2. Upgrade l3_version when needed.
3. Inspect tests bound to the old version.
4. Decide whether old tests remain valid.
5. Update assertions.
6. Add missing edge cases.
7. Do not blindly bind tests to latest implementation.

If DDT work is substantial, route to:

harbor-ddt-diary

---

11. Step 6: Semantic Drift Check

Check for drift between implementation and contract.

Common drift cases:

docstring says invalid input raises ValueError, but implementation returns None
schema says a field is required, but implementation accepts missing value
CLI JSON output changes but tests remain old
file write side effect is added but not declared
tests still verify old behavior after contract changed

Classify findings as:

Confirmed Semantic Drift
Possible Semantic Drift
Contract Gap
Schema Gap
Test / DDT Gap
Implementation Bug
Docstring Stale
False Positive

Do not hide drift.

Do not use harbor accept to silence unresolved drift.

---

12. Step 7: Generated Context Refresh

Generated context lives under:

.harbor/views/**

Generated context is not source of truth.

Refresh generated context when changes affect:

module boundaries
project structure
public contracts
docstrings
tests / DDT
CLI behavior
JSON output
workspace structure
module responsibilities
debug workflow

Typical commands:

harbor project structure --write
harbor docs --changed --write
harbor module seal --changed --write
harbor finish --sync-context
harbor stale
harbor doctor

If context refresh is the main task or becomes non-trivial, route to:

harbor-context-refresh

Do not manually edit .harbor/views/** as project truth.

---

13. Step 8: Diary Decision

Create or recommend a Diary Draft when the task involves:

Contract Change
Breaking Change
schema change
CLI behavior change
JSON output change
workspace layout change
migration behavior change
public API change
DDT strategy change
runtime safety policy change
non-obvious compatibility decision
important bugfix
architecture decision
release-relevant decision

Canonical Diary path:

.harbor/diary/YYYY-MM.jsonl

Do not run:

harbor log

unless the user explicitly requests it.

If Diary is needed but not written, output a Diary Draft.

Use:

harbor-ddt-diary

when DDT and Diary work are both involved.

---

14. Step 9: Harbor Commands

Recommended during contract-impacting work:

harbor checkpoint

At task completion, when generated context may need sync:

harbor finish --sync-context
harbor stale
harbor doctor

For machine-readable checks:

harbor stale --format json
harbor doctor --format json

For workspace diagnostics:

harbor workspace inspect
harbor workspace inspect --format json
harbor workspace migrate --dry-run
harbor workspace migrate --dry-run --format json

harbor workspace migrate --dry-run is read-only and is not part of the default coding workflow.

Do not run unless relevant to workspace diagnostics or migration planning.

---

15. Explicit User Request Only

Do not run the following unless the user explicitly requests it:

harbor log
harbor accept
harbor lock
harbor module promote-skill <module>

Never run harbor accept merely to hide unresolved drift.

Never run harbor log unless the user asked to write a diary entry or the active workflow explicitly includes writing.

---

16. CLI / JSON Output Contract Checklist

If the change affects CLI or JSON output, check:

command name
argument name
option behavior
exit code
stdout format
stderr format
JSON keys
JSON value types
JSON nesting
path format
sorting / deterministic order
machine-local path exposure

Rules:

keep keys stable
keep ordering deterministic when practical
normalize paths
avoid machine-local absolute path leakage unless explicitly required
avoid embedding local runtime state
include enough status information for CI and agents

Changing JSON output is Contract Impact.

---

17. File Write Contract Checklist

If the change affects file writing, check:

write target path
write file name
file format
overwrite behavior
append behavior
idempotency
backup behavior
dry-run behavior
generated file marker
managed block behavior

Strict Harbor write targets include:

.harbor/views/**
.harbor/diary/**
.harbor/rules/**
.harbor/reports/**
.agents/skills/**
AGENTS.md managed block

Do not silently change write targets.

Do not silently switch from dry-run to write.

Do not silently overwrite user-authored content.

---

18. Workspace Contract Checklist

The canonical Harbor workspace is:

.harbor/

Important paths:

.harbor/rules/**   - static Harbor rule docs
.harbor/views/**   - generated context views
.harbor/diary/**   - decision memory
.harbor/reports/** - validation and audit reports
.harbor/cache/**   - runtime cache
.harbor/state/**   - runtime state
.harbor/exports/** - optional exports

Changing workspace layout is Contract Impact.

Use workspace diagnostics:

harbor workspace inspect
harbor workspace migrate --dry-run

migrate --dry-run must remain read-only.

Do not assume migrate --write exists.

---

19. Breaking Change Checklist

A breaking change occurs when existing users, callers, scripts, agents, tests, or downstream systems must change.

Check whether the change:

removes public field
renames JSON key
changes CLI output format
changes exit code
changes schema requirement
changes file path
changes migration behavior
changes public exception behavior
changes compatibility behavior

If breaking:

mark Breaking Change: yes
explain affected consumers
provide migration guidance
update tests
update docs
create Diary Draft
consider release notes

If uncertain:

Breaking Change: uncertain

Do not hide uncertain breaking risk.

---

20. Output Format

Return:

Contract Change Summary:
- Contract Impact: yes / no / uncertain
- Strictness: strict / standard / light
- Affected contracts:
- Implementation summary:
- Tests / DDT:
- Semantic drift:
- Runtime safety:
- Generated context:
- Diary:
- Harbor commands:
- Remaining risks:

If no Contract Impact, include:

Contract Impact: none
Reason:
- behavior unchanged
- args unchanged
- returns unchanged
- raises unchanged
- schema unchanged
- side effects unchanged
- external-visible results unchanged

If commands were not run, say so clearly:

未实际运行测试 / Harbor 命令。建议执行：
<command>

Do not invent tool results.

---

21. Diary Draft Format

If Diary is needed but not written, include:

[Diary Draft]
- Type: feature | bugfix | refactor | chore | incident | decision | security | migration | test
- Importance: low | normal | high | critical
- Visibility: internal | repo | public
- Module:
- Contract Impact: yes | no | uncertain
- Breaking Change: yes | no | uncertain
- Summary:
- Reason:
- Changes:
  - ...
- Tests:
  - ...
- Risks:
  - ...
- Follow-up:
  - ...
- Ref:

If Diary is not needed:

Diary: not needed
Reason:
- <why this change does not require a decision record>

---

22. Common Mistakes

Avoid:

treating docstring as the only contract
changing implementation without Contract Impact assessment
treating Contract Impact: uncertain as no impact
changing strict behavior without tests / DDT
using strategy="latest" for strict DDT
changing CLI output without documenting impact
changing JSON output without tests
changing file write path silently
updating tests only to match broken implementation
updating snapshots without contract review
manually editing generated context as source of truth
hiding breaking changes
using harbor accept to silence unresolved drift
claiming tests passed without running them
skipping Diary for important contract decisions

---

23. Final Principle

Before making a contract-impacting change, ask:

Who or what expects the old behavior?
Which contract sources describe it?
Which tests verify it?
Which generated context summarizes it?
Does the decision need to be remembered?

A Harbor-managed contract change is complete only when implementation, contracts, tests, generated context, and decision memory are aligned.