docs: record retirement — superseded by j4k-align - #41
Conversation
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
There was a problem hiding this comment.
Approach Review: Approach looks good. Committing the retirement record directly into the repository (RETIREMENT.md pointing to the successor tool, plus byte-verbatim snapshots of the final config and global-target renders under archive/, kept out of the formatter so they stay exact) is the right shape for an archival PR: once the repo is archived on GitHub, in-tree files remain browsable and linkable, which a release asset or external tarball would not be. The considered alternative — attaching the snapshots to a GitHub Release instead of committing them — has no advantage here since repository size no longer matters for an archived repo, and in-tree files are easier to discover. The honest note about the missing Phase-0 baseline tar (with a pointer to the recorded hashes in j4k-align) is exactly the kind of provenance detail an archival record should carry.
Approach review by Claude Code Fable (CI review) (fable)
There was a problem hiding this comment.
Approach Review: Approach looks good. Verbatim archival in archive/ with formatting/alignment exclusions is the right pattern for retiring a project while preserving its final state for reference. The retirement document clearly points to the successor and records the cutover version.
Approach review by Approach Review 3 (OpenCode Wafer) (GLM-5.2)
There was a problem hiding this comment.
Approach Review: Recording the retirement in-repo, as a final commit before archival, is the right shape — git in an archived repo is durable, needs no external hosting, and the two ignore entries (.oxfmtrc.json, j4kAlignIgnorePatterns) are the minimal way to keep the snapshots byte-verbatim without a .gitattributes/tooling detour. No objection to the mechanism.
One approach-level gap: the retirement notice isn't on the surface people actually land on. README.md is untouched and still reads as a live tool (npm install -g sync-rules, usage, pipeline examples), and it is both what GitHub renders on the repo home page and what npm renders on the package page (it's in files). RETIREMENT.md only appears in the file listing, so the default path for a visitor — and for an agent following this repo's own "read @README.md for project context" rule — is the stale instructions, not the "do not run the CLI" warning. See the inline note.
Secondary, non-blocking: archive/global-targets/ is a migration-verification artifact (bytes immediately pre-regeneration, the counterpart to docs/pre-cutover-hashes.json), and its natural home is next to the retirement plan in j4k/align rather than duplicated into the repo being frozen. Keeping it here does buy independence from that repo's availability, so it's a defensible trade either way. Worth a conscious call that the verbatim config.json and renders publish workstation paths (/Users/jercik/...) and machine details to a public repo — no credentials in them, and presumably intentional.
Approach review by Claude Code Opus (opus)
| @@ -0,0 +1,22 @@ | |||
| # sync-rules is retired | |||
There was a problem hiding this comment.
💡 Alternative approach: Lead with the notice in README.md instead of relying on a separate file. A short banner at the top of the README (retired, superseded by j4k-align, don't run the CLI, link to RETIREMENT.md for the full record) is the conventional pattern for a retired project, and it's the only placement that reaches the GitHub landing page and the npm package page — README.md is in package.json's files, so the last published tarball keeps showing live install/usage instructions. RETIREMENT.md can stay as-is for the detailed record; the change is making the README the entry point to it rather than a sibling that gets scrolled past.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: addef57a60
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| The npm package is deprecated, never unpublished. This repository is archived; | ||
| do not run the CLI — a run would overwrite j4k-align-generated files with this | ||
| repository's stale corpus rendering. |
There was a problem hiding this comment.
When a user or agent opens this archived repository, the still-unchanged README remains the primary entry point and actively instructs them to install and run sync-rules; nothing there links to this warning. That is especially dangerous because these lines say a run can overwrite the replacement tool's generated files, and repository agents are explicitly required to read README for project context. Add a prominent retirement banner and replacement link at the top of README before archiving.
AGENTS.md reference: AGENTS.md:L1-L3
Useful? React with 👍 / 👎.
| retirement plan was no longer present on the retiring machine, and its | ||
| per-file hashes remain recorded in j4k-align's `docs/pre-cutover-hashes.json`. | ||
|
|
||
| The npm package is deprecated, never unpublished. This repository is archived; |
There was a problem hiding this comment.
🟡 Medium: This line states two things as accomplished facts that are not true at review time. Verified against the registry: npm view sync-rules deprecated returns empty for latest (5.11.5), and the packument's time.modified is 2026-07-06 — so no npm deprecate has run yet. Likewise the repository is not yet archived (CI is still running on this PR). If deprecation and archival are the next steps of Phase 5, consider either running npm deprecate before merging, or rewording to future tense ("will be deprecated"). Note the sequencing trap: once the repo is archived, correcting this document requires unarchiving.
| @@ -0,0 +1,22 @@ | |||
| # sync-rules is retired | |||
There was a problem hiding this comment.
🟢 Low: README.md (unchanged in this PR) still presents the tool as fully active — installation instructions, usage workflow, no mention of retirement. GitHub's archive banner will appear after archival, but RETIREMENT.md itself doesn't render on the repo landing page, so visitors arriving from the npm package page will see only the active-looking README. A one-line notice at the top of README linking to RETIREMENT.md would close that gap, and could double as the npm deprecate message.
| repository's `rules/` directory. The full migration record is | ||
| `docs/sync-rules-retirement-plan.md` in `j4k/align`. | ||
|
|
||
| - Deployed version read from the npm registry at cutover: **5.11.5**. |
There was a problem hiding this comment.
ℹ️ Info: Verified: the registry's dist-tags.latest for sync-rules is indeed 5.11.5, matching this recorded cutover version. (The repo's own package.json says 5.1.0, consistent with the release workflow not committing version bumps back.)
| @@ -0,0 +1,570 @@ | |||
| { | |||
There was a problem hiding this comment.
ℹ️ Info: Scanned all archived snapshots (config.json and the five global-target renders) for credential-like content — no tokens, keys, or secrets present; matches are only rule prose about token handling. The snapshots do publish workstation home-directory paths (/Users/jercik/...) and internal hostnames (code.j4k.dev), which appears deliberate per the PR description. No action needed.
| retirement plan was no longer present on the retiring machine, and its | ||
| per-file hashes remain recorded in j4k-align's `docs/pre-cutover-hashes.json`. | ||
|
|
||
| The npm package is deprecated, never unpublished. This repository is archived; |
There was a problem hiding this comment.
🟡 Medium: This line asserts two states in the present tense that aren't true yet as of this commit.
"The npm package is deprecated" — it isn't. Verified against the registry:
$ npm view sync-rules deprecated
(empty)
$ npm view sync-rules --json | node -e "..." # top-level deprecated: undefined
$ npm view sync-rules@5.11.5 deprecated
(empty)
Neither the package nor 5.11.5 carries a deprecated field, so npm install -g sync-rules today installs silently with no warning — which is exactly the outcome the next sentence ("do not run the CLI — a run would overwrite j4k-align-generated files") is trying to prevent.
"This repository is archived" — also not yet, since this PR is open against a writable repo.
Both are presumably later steps of the retirement plan, which is fine — but a record that states pending steps as completed is misleading to whoever reads it next. Either run npm deprecate sync-rules "..." and archive before merging, or reword to pending ("The npm package will be deprecated, never unpublished; this repository will be archived"). The version claim itself checks out: registry latest is 5.11.5, matching line 9. (Note package.json says 5.1.0, but that's expected — semantic-release doesn't commit version bumps back.)
| }, | ||
| "packageManager": "pnpm@11.8.0" | ||
| "packageManager": "pnpm@11.8.0", | ||
| "j4kAlignIgnorePatterns": [ |
There was a problem hiding this comment.
🟡 Medium: The retirement notice never reaches the people most likely to act on it, because of the files allowlist a few lines up (lines 24-29):
"files": ["bin/", "dist/", "README.md", "LICENSE"]RETIREMENT.md isn't in that list, so it won't be in the npm tarball and won't render on the npm page. Meanwhile README.md — which is shipped, and is also what GitHub renders on the repo landing page — has no retirement notice at all. I grepped it: zero matches for retire, deprecat, archiv, or j4k-align. It still opens with npm install -g sync-rules and a full "Usage" walkthrough, which directly contradicts RETIREMENT.md:21 ("do not run the CLI").
A reader arriving from npm or from the repo root sees active install instructions and no signal that running the tool will clobber j4k-align-generated files. A three-line notice at the top of README.md linking to RETIREMENT.md is the highest-leverage fix here, since README.md is the file readers actually land on. Adding RETIREMENT.md to files helps only if a future release publishes — and with this branch's docs: commit, @semantic-release/commit-analyzer won't cut one, so the README is the path that matters.
| }, | ||
| "projects": [ | ||
| { | ||
| "path": "/Users/jercik/Developer/j4k/ia-lcp-books", |
There was a problem hiding this comment.
🟢 Low: This snapshot publishes 47 absolute local paths under /Users/jercik/Developer/... into a public repo, naming every project directory on the workstation — including ones not otherwise public (kap-staking, cc-restoration, miniread-lab, propolis-v0.8.0, claude-code-reconstruction-workbench, and the jercik/ and j4k/ trees).
The username adds nothing new (it's the GitHub account name), and I found no credentials — I scanned archive/ for api[_-]?key|secret|token|password|bearer|ghp_|sk-|BEGIN PRIVATE KEY and every hit was prose about tokens in the rule text, not a value. So this is disclosure of project names only.
I recognize verbatim-ness is the whole point of the archive, so this is entirely your call — flagging it only so the tradeoff is a decision rather than an oversight. If it matters, the rules globs are the part with archival value; the path values are not.
| "AGENTS.md", | ||
| "CLAUDE.md" | ||
| "CLAUDE.md", | ||
| "archive/**" |
There was a problem hiding this comment.
ℹ️ Info: Verified this ignore entry and the archive's internal consistency; both hold up.
The archive/** glob works. oxfmt's ignorePatterns here uses directory-suffix form elsewhere (.claude/, .codex/), so ** was worth confirming. Reproduced against oxfmt@0.57.0 in a scratch dir with a deliberately misformatted archive/config.json plus an identical copy outside archive/ — only the outside copy was flagged. And npx oxfmt@0.57.0 --check --config .oxfmtrc.json . passes on this branch (51 files), so the snapshots stay byte-verbatim as intended.
The archived renders match what sync-rules would have produced, which is a nice property for a record whose value is fidelity:
gemini-AGENTS.mdandopencode-AGENTS.mdare byte-identical (same md5, 377 lines) — consistent witharchive/config.jsondeclaringglobalOverridesfor onlycodex,copilot, andclaude.claude-CLAUDE.md(404),codex-AGENTS.md(388), andcopilot-copilot-instructions.md(427) each contain the 377-line gemini render as an exact line-prefix, matching the documented "override rules are appended after the sharedglobalrules" semantics inREADME.md:84.- The five filenames map 1:1 onto
HARNESS_REGISTRYinsrc/core/harness-registry.ts:14-20. archive/config.jsonsatisfies theConfigschema insrc/config/config.ts: the threeglobalOverrideskeys are all validHarnessNames,globaland every project'srulescarry at least one positive glob, andprojectsis non-empty with no duplicate paths.
No action needed.
| "AGENTS.md", | ||
| "CLAUDE.md" | ||
| "CLAUDE.md", | ||
| "archive/**" |
There was a problem hiding this comment.
🟢 Low: Excluding archive/** from oxfmt keeps the snapshots byte-verbatim, but there is a second mechanism that can interfere with that goal: .githooks/pre-commit runs git diff --cached --check with an exclude list (.agents/**, .claude/**, .clawpatch/**, .codex/**) that does not include archive/**. A future verbatim snapshot containing trailing whitespace would be rejected at commit time, pressuring someone to alter the bytes. I checked the current archive with grep -rlP ' +$' archive/ — it is clean, so nothing is broken today, and since the repo is being archived after this merge this is discretionary. If any follow-up snapshot lands before archival, consider adding :(exclude)archive/** to ignored_staged_paths.
| repository's `rules/` directory. The full migration record is | ||
| `docs/sync-rules-retirement-plan.md` in `j4k/align`. | ||
|
|
||
| - Deployed version read from the npm registry at cutover: **5.11.5**. |
There was a problem hiding this comment.
ℹ️ Info: Verified the factual claims in this record against reality, all consistent:
npm view sync-rules versionreturns5.11.5(latest, last modified 2026-07-06), matching this line even though the committedpackage.jsonsays5.1.0(expected with semantic-release).archive/config.jsonparses cleanly against this repo's ownConfigschema (src/config/config.ts): 47 projects, all with positive globs, and theglobalOverrideskeys (codex,copilot,claude) are valid names persrc/core/harness-registry.ts.- The config path claim matches the code:
envPaths("sync-rules", { suffix: "" })insrc/config/constants.tsresolves to~/Library/Preferences/sync-rules/config.jsonon macOS. - The five archived renders are internally consistent with the archived config:
gemini-AGENTS.mdandopencode-AGENTS.mdare byte-identical (neither harness has overrides), and the claude/codex/copilot files each begin with that exact shared render followed by their override rules (verified withcmp).
1 participant
Final commit before archival (sync-rules retirement plan Phase 5 step 1, in j4k/align
docs/sync-rules-retirement-plan.md):RETIREMENT.md(deployed version 5.11.5 read from the registry; pointer to j4k-align),archive/config.json(verbatim final config),archive/global-targets/(the last live sync-rules renders of the five workstation globals), plus the regeneratedAGENTS.mdriding along per the generated-drift rule.archive/**is excluded from formatting so the snapshots stay byte-verbatim.