Skip to content

Detect and re-sync imported agent-instruction docs when their source changes #13

Description

@ivklgn

Paths and command updated for v0.7.0 — drift detection moved from skills/audit/lib/drift-detection.md to the actualize track, and /archcore:audit --drift is now /archcore:review --drift. Re-verified: the gap is still open.

Problem

Imported agent-instruction docs (from CLAUDE.md, AGENTS.md, .cursorrules, .cursor/rules/*.mdc, .github/instructions/*.md, .windsurf/rules/*.md) carry imported + source:<slug> tags and an "Imported from <path> on <YYYY-MM-DD>" pointer — see plugins/archcore/skills/init/lib/agent-files.md. Nothing detects or re-syncs when the source file changes afterwards.

Verified in the current tree: neither plugins/archcore/skills/_shared/tracks/actualize.md nor plugins/archcore/skills/review/SKILL.md mentions imported or source:, so the assumed "/archcore:review --drift covers it" fallback is not wired. Imported stubs silently diverge from their sources.

Extract-mode imports raise the stakes: one source file can yield several documents plus an umbrella doc linked by related edges, so a stale source leaves a whole cluster wrong, not one stub.

Expected result

  • Detection: /archcore:review --drift flags imported docs whose source:<slug> file changed since the recorded import date (git mtime vs. the pointer line).
  • Correction (stretch): an /archcore:init --refresh-driven assisted re-import — the --refresh flag already exists and already bypasses the seeded-repo early-exit, so this is a new branch inside an existing path.

Impact

Keeps imported instructions trustworthy over time instead of quietly going stale, so agents don't act on outdated conventions.

Proposed approach (small PRs)

  • Add an imported-doc drift category to the actualize track (detection).
  • Add assisted re-import via /archcore:init --refresh (correction), reusing the umbrella related edges to find every document derived from one source.

Acceptance criteria

  • --drift flags an imported doc after its source file is modified.
  • Re-import updates the doc through MCP and refreshes the recorded import date.

References

Design rationale: .archcore/plugin/zero-content-onboarding-implementation.plan.md (Out of scope) and magic-first-day-init.plan.md. Code: plugins/archcore/skills/init/lib/agent-files.md, plugins/archcore/skills/_shared/tracks/actualize.md, plugins/archcore/skills/review/SKILL.md.

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:onboarding/archcore:init and first-run experiencearea:skillsIntent skills and agentspriority:P2Valuable follow-upsize:M1-3 days

    Type

    No type

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions