Weekly cron harness mirror with work specifics redacted¶
- Date: 2026-07-30
- Status: Accepted
- Tags:
toolingworkflowprocess
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-syncplist 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:
~/.claudeis 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.jsonholds 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:
- Copies an allowlisted subset of
~/.claudeintoclaude/harness/— a generated subtree kept distinct from the hand-authoredclaude/*documentation. One-way only:~/.claudeis read-only to this process and is never written from the repo. - Redacts employer specifics rather than dropping the file. Every rule in the skill's
redactions.txtrewrites 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. - Redacts every
envvalue, then asserts no known secret literal reached the tree. - 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. - Prepends a dated entry to
claude/harness/CHANGELOG.md. - 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_requiredremoves 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.txtwhenever 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.