Skip to content

Weekly cron harness mirror with work specifics redacted

  • Date: 2026-07-30
  • Status: Accepted
  • Tags: tooling workflow process

Context

ADR-0005 decided to keep this repo in sync with live tool configs using an fswatch watcher, hourly batch commits, and a daily PR driven by a launchd agent. That mechanism is not running, and appears never to have survived install:

  • No com.phazeight.ai-tools-sync plist in ~/Library/LaunchAgents/
  • No state file at ~/.local/state/ai-tools-sync.json
  • claude/ was last modified on 2026-04-21, by a hand-written documentation commit
  • The live harness carries 28 skills; this repo documented 5 of them

So the exact failure ADR-0005 existed to prevent — drift accumulating until reconstructing what changed means comparing files by hand — happened anyway, by a different route: the automation was never durably installed.

cron-ai (~/.cronai/cronai.yml) has meanwhile proven durable for scheduled agent work, with several jobs running to schedule and a run history of consistent successes. It needs no launchd plist and no resident daemon.

Three further constraints shaped this decision:

  • ~/.claude is roughly 3.5GB, of which about 300KB is authored configuration. The rest is session transcripts, plugin checkouts, caches, and binary assets. A file-copy watcher with no allowlist is the wrong instrument.
  • ~/.claude/settings.json holds a live API key in plaintext, so a mirror needs redaction as a build step rather than as reviewer vigilance.
  • The harness is shared between personal and employer work. This repo is personal, so a naive mirror would copy employer material into it. A first unfiltered run confirmed this concretely: employer references appeared across a dozen files, in 11 components.

Decision

A weekly cron-ai job (weekly-harness-sync, Fridays at 4pm) runs the syncing-harness-inventory skill, which:

  1. Copies an allowlisted subset of ~/.claude into claude/harness/ — a generated subtree kept distinct from the hand-authored claude/* documentation. One-way only: ~/.claude is read-only to this process and is never written from the repo.
  2. Redacts employer specifics rather than dropping the file. Every rule in the skill's redactions.txt rewrites an identifier to a descriptive placeholder — internal repos, AWS account ids and profiles, ticket ids, chat channels, the internal GitHub org. The tooling and the pattern survive; only the specifics go. A component is excluded only when redaction cannot clean it: unreadable bytes, or a marker surviving its own rule. The written tree is then re-scanned and the run aborts non-zero if any identifier slipped through. The rule file itself is never mirrored, since it names employers by design. Generic industry vocabulary is deliberately left alone.
  3. Redacts every env value, then asserts no known secret literal reached the tree.
  4. Records claude/harness/manifest.json (path → sha256) as the anchor the following week diffs against, so each entry is a true weekly delta rather than a cumulative count. Redacted and withheld files appear there as bare counts, never by name.
  5. Prepends a dated entry to claude/harness/CHANGELOG.md.
  6. Opens one PR per run from sync/harness-<YYYY-MM-DD>, or does nothing when the diff is empty.

settings.user.json is the authored settings file; settings.json is not mirrored, because it carries _generated: {by: merge-plugin-hooks.py} and is a build artifact. Its plugin enablement record is kept with the marketplace name redacted — that an internal-marketplace plugin is enabled is useful to record, the marketplace's name is not.

The ADR gate is computed, not judged. inventory.py diff emits adr_required, true only when the set of components changes — a skill, hook, command, or agent added or removed. Routine weeks carry the skip-adr label instead. A baseline run is explicitly not structural, so the job never authors this ADR's successor for a first snapshot.

PRs are created with a per-command token for the personal GitHub account, because the globally active gh account cannot resolve this repository. This avoids mutating global auth state as a side effect of a scheduled job.

This supersedes ADR-0005, whose status is updated to point here. Its scripts/ai-tools-sync.py, ai-tools-watcher.sh, and install-watcher.sh are left in place for reference rather than deleted.

Alternatives Considered

Option Why Rejected
Repair ADR-0005's watcher + launchd agent The failure was durability of the install, not the logic. A resident daemon on a laptop that sleeps and reboots reintroduces exactly the fragility that produced four months of drift.
Mirror directly into claude/* beside curated docs Collides with hand-authored files that document artifacts no longer installed, and leaves every future run re-litigating "mirror or prose?" against this repo's docs-only convention. A separate generated subtree settles it.
Prose-only weekly report, no file mirror Tidy, but abandons version history of the actual configs — the specific value ADR-0005 existed to capture. Three trial agents independently chose this and produced readable essays with no diffable record.
Filter employer content by path/filename Filenames lie. A personally-named skill can contain employer specifics in its body, and a rename silently defeats the filter. Content matching is the only test that holds.
Drop every file containing an employer reference The first implementation. It withheld a fifth of the harness — including a multi-account SSO login pattern and the global-instructions layout — to protect identifiers that a substitution removes just as well. Exclusion is now the fallback, not the default.
Name withheld files in the committed record Auditability is real, but filenames themselves carry employer project and ticket identifiers. The count is committed; the full list goes to the run output where the operator reviews it.
Author an ADR every week Faithful to the ADR-on-tool-change convention, but burns numbering on typo-level weeks and buries real decisions in noise.
Always apply skip-adr Never fails CI, but stops decisions/ reflecting tooling adoption at all.

Consequences

Positive:

  • Drift becomes visible weekly, in a diff, instead of accumulating for months.
  • The allowlist keeps the mirror around 300KB, so the repo stays reviewable.
  • Employer specifics are removed by a rule with an assertion behind it, not by vigilance, while the tooling and patterns they were embedded in are retained.
  • Secret redaction is likewise a build step with a gate.
  • adr_required removes the weekly judgment call that three trial agents each got wrong.
  • No resident daemon, no launchd plist, nothing to survive a reboot.

Negative / Trade-offs:

  • A weekly PR to review, even when the content is mechanical.
  • Redacted files are no longer byte-faithful copies, so the mirror documents patterns and history rather than serving as a restore source.
  • A placeholder loses real distinctions: several internal repos with the same purpose word would collapse onto one token.
  • Friday runs only happen if the machine is awake. A missed week is absorbed by the next run's diff, but the changelog will show a gap.
  • A rule that is too broad silently rewrites personal content; a rule that is too narrow leaks. Only the counts surface either.
  • The skill's prose was shipped without the subagent verification its own method prescribes; only the script half carries tests.

Ongoing obligations:

  • Add a rule to redactions.txt whenever new employer tooling lands in the harness, giving it its own descriptive placeholder.
  • Review the run output: a rising redaction count is normal, a rising exclusion count means a rule is failing to clean something.
  • Extend the allowlist when a genuinely new harness surface appears — an unlisted directory is silently absent from the mirror.
  • Keep redaction current if configuration gains new secret-bearing fields.
  • Reconcile the stale curated docs the first snapshot exposed under claude/.

ADRs are immutable. If this decision changes, create a new ADR with status "Superseded by" pointing here, and update this record's status.