---
name: site-map-maintainer
description: 'Keeps the site map fresh during a feature-development change by patching only the surfaces a flow-relevant diff touches. Use when a changed file is one the map cites or a route, command program, endpoint handler or guard.'
metadata:
  model_tier: medium
  cacheable: 'false'
  output_format: json
  paqad-meta: skill.meta.yaml
---

## What It Does

Watches a feature-development change for edits that would drift the site map: a new route, a
changed guard, a removed screen: and patches only the affected surfaces. It is the reason a
change that touches navigation cannot reach "Safe to merge" with a stale map: the freshness gate
flags the drift, and this skill resolves it with a scoped patch, not a full re-map.

## Use This When

Inside a feature-development change, once the diff is known, when a changed file is one
the map cites or a flow-relevant path (routes, command programs, endpoint handlers, guards).
Skip it when the change touches nothing the map depends on.

## Inputs

- The change's `changed_files`.
- The stored `docs/site-map/app-map.yaml` and its stamped freshness (the broken-anchor count
  the freshness gate reads).
- Read `references/patch-scope.md` before patching.

## Procedure

The drift detection is the engine's (the stamped freshness records which cited anchors no
longer resolve); your job is the scoped patch.

1. Run `paqad-ai sitemap run`; read which cited anchors broke and which surfaces the changed
   files cite.
2. Patch only those surfaces: add the new one, update the changed guard, mark the removed one,
   leaving untouched surfaces exactly as curated.
3. Re-run the verb to confirm the freshness gate is satisfied and the map validates.

## Output Contract

- A JSON object `{ patched_surfaces: [...], anchors_repaired: [...], still_broken: [...] }`.
- Every patched surface carries resolving evidence from the changed files.
- `still_broken` is empty when the change is complete; a non-empty list is a blocking gap.

## Escalate / Stop Conditions

- Do not re-map the whole app for a scoped change; patch only what the diff drifted.
- Do not overwrite a curated surface that the change did not touch.
- Stop and surface the drift when a change removes a surface that journeys still reference, that
  is a decision, not a silent deletion.

## Resources

- `references/patch-scope.md`
- `agents/openai.yaml`