# Maintaining Your Harness

A harness is not a one-time setup. It is a living artifact that must evolve
alongside the codebase it describes. This document covers the philosophy and
practice of keeping harness docs current -- bridging the gap between slow drift
(entropy) and acute changes (feature merges, architecture shifts).

---

## Why Harness Maintenance Matters

Stale harness docs are worse than no docs. No docs force an agent to discover
everything from scratch -- slow, but at least the agent reads actual code. Stale
docs give the agent confident, wrong instructions. The agent follows them
faithfully, producing code that fits a codebase that no longer exists.

This is the **Instruction Rot** anti-pattern documented in
[Anti-Patterns](anti-patterns.md#5-context-overload-and-instruction-rot):
instructions that were once relevant but are no longer accurate, remaining in
the config file and misleading the agent. Stale instructions produce stale code.
Contradictions between docs and reality cause unpredictable behavior.

The cost of updating docs at merge time is low -- you already understand the
change, the context is fresh, and the update is small. The cost of catching up
later is high -- you must re-derive context, audit multiple docs, and risk
missing something. Every day of delay compounds the problem.

> Principle: update harness docs when the change is fresh (cheap). Do not defer
> to a quarterly review (expensive).

---

## Two Modes of Maintenance

Harness docs face two kinds of decay, and each requires its own response.

### 1. Event-Driven (Acute)

A feature lands, the architecture changes, a major dependency is added. The
harness docs must update NOW -- in the same PR as the code change.

**When to trigger:**
- A new service, module, or top-level directory is added
- The tech stack changes (new database, new framework, new language)
- Build, test, lint, or deploy commands change
- Coding conventions are added or modified
- Module boundaries or dependency directions shift
- A major dependency is added, removed, or replaced

**How to respond:**
- Include harness doc updates in the same PR as the code change
- Use the post-implementation checklist (`checklists/post-implementation.md`)
  as a reminder of which docs to check
- Add an entry to your project's harness changelog
- The `maintain-harness-docs` playbook (`agent/playbooks/maintain-harness-docs.md`)
  walks through the full process

**Principle:** Harness doc updates belong in the same PR as the feature that
triggers them. If the doc update ships in a follow-up PR, it will be forgotten.

### 2. Time-Driven (Chronic)

Even without acute changes, docs drift. Variable names get refactored. File
paths change during cleanup. Patterns evolve incrementally without any single
PR being "the trigger." This slow rot requires periodic sweeps.

**Recommended cadence:**
- **Weekly:** Doc freshness check. Run the doc-gardening script to verify file
  references, command references, and internal links are still valid.
- **Monthly:** Reproduce-your-work calibration. Pick a recent task and have an
  agent attempt it using only the harness docs. Note where the agent gets stuck
  or goes wrong -- those are maintenance targets.
- **Quarterly:** Major harness review. Read every harness doc end-to-end.
  Delete anything stale. Update anything outdated. Verify all examples compile
  and all commands work.

**Reference:** [Entropy Management](entropy-management.md) covers the full
time-driven maintenance approach, including garbage collection agents,
doc-gardening scripts, and quality grade tracking.

---

## The Change-Impact Matrix

Not every code change affects every harness doc. Use this matrix to determine
which documents need updating for each type of change.

| Change Type | .github/copilot-instructions.md | ARCHITECTURE.md | AGENTS.md | Specs | Changelog |
|-------------|-----------|-----------------|-----------|-------|-----------|
| New module/service | Tech stack, directory structure | Module map, boundaries, data flow | Structure section | New spec if major | Yes |
| Database change | Tech stack | Data flow, domain concepts | Tech stack section | Relevant specs | Yes |
| New major dependency | Tech stack | Architecture notes if it affects flow | Tech stack section | Relevant specs | Yes |
| Build/test command change | Build commands section | -- | Build commands | -- | Yes |
| Convention change | Conventions section | -- | Conventions section | -- | Yes |
| API change (new endpoint) | -- | Data flow if new pattern | -- | API specs | Maybe |
| Refactor (same behavior) | Directory structure if paths changed | Module map if boundaries moved | Structure if paths changed | -- | Only if boundaries changed |
| Dependency patch/minor bump | -- | -- | -- | -- | No |
| Typo fix / formatting | -- | -- | -- | -- | No |
| New CI/CD step | Build commands if new command | -- | -- | -- | Maybe |

**Reading the matrix:** A dash (--) means no update is typically needed. "Maybe"
means use judgment -- if the change is significant enough that an agent's
behavior would differ, update the doc.

---

## The Harness Changelog

A harness changelog tracks the evolution of your harness docs over time. Each
entry ties a doc change to the code change that triggered it.

### Why Track Changes

- **Auditability:** When a doc seems wrong, you can trace back to when it was
  last updated and what triggered the update.
- **Onboarding context:** New team members can read the changelog to understand
  how the project's architecture has evolved.
- **Pattern recognition:** Over time, the changelog reveals which types of
  changes most frequently require doc updates -- helping you build better habits.

### How to Use It

- Keep entries lightweight: 3-5 lines each, focused on what changed and why
- Most recent entries at the top
- One entry per PR or logical change (not one per file modified)
- Template: [`templates/docs/harness-changelog-template.md`](../templates/docs/harness-changelog-template.md)

### Example Entry

```markdown
### 2026-03-15 -- Added Redis caching layer

**Trigger:** PR #247 (feature/redis-cache)
**Documents updated:**
- `.github/copilot-instructions.md` -- Added Redis to tech stack table, added `redis-cli` to build commands
- `ARCHITECTURE.md` -- Updated data flow to show cache layer, added Redis to infra diagram

**Impact:** Agents now know to check cache before hitting the database.
```

---

## CI Enforcement

Automated checks can detect when architecture-significant code changes land
without corresponding harness doc updates. This catches the most common
maintenance failure: forgetting to update docs in the same PR.

### How It Works

The harness doc check script (`templates/hooks/check-harness-docs.sh`) scans
the changed files in a PR and looks for architecture-significant patterns:

- New directories under `src/`
- Changes to `*.csproj` / `Directory.Packages.props`, `global.json`, `*.psd1` `RequiredModules`, `package.json`, etc.
- Changes to CI/CD configuration
- New database migration files
- Changes to build scripts or Makefiles

When it detects these patterns without corresponding changes to harness docs
(`.github/copilot-instructions.md`, `ARCHITECTURE.md`, `AGENTS.md`, etc.), it emits a warning.

### Rollout Strategy

Start soft and upgrade gradually:

1. **Week 1-4: Warning mode.** The check runs and prints a message but does not
   block the merge. This gives the team time to build the habit.
2. **Month 2-3: Soft gate.** The check is a required status check but can be
   overridden by a reviewer. This makes the warning visible in code review.
3. **Month 4+: Hard gate.** The check blocks merges. By now the team expects it
   and includes doc updates routinely.

### Configuration

Reference: [`templates/hooks/check-harness-docs.sh`](../templates/hooks/check-harness-docs.sh)

The script is configurable:
- Set which file patterns count as "architecture-significant"
- Set which doc files must be updated
- Toggle between warning mode and hard gate mode

---

## Common Scenarios

### Scenario 1: "I added a new service module"

You created `src/services/notifications/` with a new notification service.

**Documents to update:**
- **.github/copilot-instructions.md:** Add `notifications/` to the directory structure section.
  Add any new build/test commands if the service has its own.
- **ARCHITECTURE.md:** Add the notification service to the module map. Document
  its boundaries (what it depends on, what depends on it). Add it to the data
  flow if it introduces a new path.
- **AGENTS.md:** Update the structure section to include the new directory.

**Changelog entry:**
```
### 2026-03-20 -- Added notification service
**Trigger:** PR #312 (feature/notifications)
**Documents updated:**
- `.github/copilot-instructions.md` -- Added notifications/ to directory structure
- `ARCHITECTURE.md` -- Added notification service to module map and data flow
**Impact:** Agents know where to put notification-related code and understand its dependencies.
```

### Scenario 2: "I changed the database from LocalDB to Azure SQL Database"

**Documents to update:**
- **.github/copilot-instructions.md:** Update tech stack table (LocalDB -> Azure SQL Database). Update build
  commands (add EF Core migration commands, connection-string config, Managed Identity setup). Update common pitfalls
  if any LocalDB-specific warnings existed (e.g. attached MDF files).
- **ARCHITECTURE.md:** Update data flow (DbContext registration, retry policies, migration strategy).
  Update infrastructure section. Update domain concepts if data types changed.
- **AGENTS.md:** Update tech stack section.

**Impact:** This is a high-impact change. Every agent session that touches the
database will use the wrong commands and assumptions if docs are not updated.

### Scenario 3: "I added a major dependency (e.g., Redis)"

**Documents to update:**
- **.github/copilot-instructions.md:** Add Redis to tech stack table. Add any new commands (e.g.,
  `redis-cli`, cache flush commands). Add pitfalls (e.g., cache invalidation
  patterns, key naming conventions).
- **ARCHITECTURE.md:** Add Redis to the infrastructure diagram. Update data flow
  to show cache interactions. Document cache-aside or write-through pattern
  choice.
- **Specs:** If Redis introduces a new caching module, write a spec for it.

### Scenario 4: "I refactored the auth system"

**Documents to update:**
- **ARCHITECTURE.md:** Update the auth flow description. Update module boundaries
  if auth logic moved between modules. Update dependency directions.
- **.github/copilot-instructions.md:** Update conventions if auth patterns changed (e.g., new
  middleware, new decorator usage). Update pitfalls if old auth gotchas no longer
  apply or new ones emerged.
- **Specs:** Update the auth spec if one exists.

**Note:** Refactors that change architecture are among the most important to
document because the old pattern may exist in the agent's training data or in
stale docs, creating a strong pull toward the old approach.

---

## When NOT to Update

Not every change requires a harness doc update. Updating docs for trivial
changes adds noise and makes the changelog less useful.

**Skip harness doc updates for:**

- **Typo fixes and formatting changes.** These do not affect agent behavior.
- **Minor refactors within a module.** If the change does not affect module
  boundaries, dependency directions, or public interfaces, the architecture
  docs are still accurate.
- **Dependency patch and minor version bumps.** Automated by Renovate or
  Dependabot. These do not change the tech stack in a meaningful way. Only
  update docs for major version bumps that change APIs.
- **Bug fixes that do not change architecture.** Fixing a null pointer exception
  does not require an architecture doc update.
- **Adding tests for existing functionality.** The harness docs describe
  structure and conventions, not individual test coverage.

**The test:** Ask yourself, "If an agent read the current harness docs, would it
make a mistake because of this change?" If the answer is no, skip the update.

---

## Further Reading

- [Entropy Management](entropy-management.md) -- Time-driven maintenance: garbage collection, doc gardening, quality grades.
- [Anti-Patterns](anti-patterns.md#5-context-overload-and-instruction-rot) -- The Instruction Rot anti-pattern that maintenance prevents.
- [Context Engineering](context-engineering.md) -- How harness docs fit into the broader context engineering pillar.
- [Architectural Constraints](architectural-constraints.md) -- Encoding rules in code so they cannot rot.
- [What Is Harness Engineering?](what-is-harness-copilot.md) -- The three pillars and how maintenance connects them.