docs(kb): plan the local:// hub migration (ADR-0044, closes #123 spec obligation) - #136
docs(kb): plan the local:// hub migration (ADR-0044, closes #123 spec obligation)#136Sumit1993 wants to merge 3 commits into
Conversation
…on (#123) Vehicle: extend mage migrate; doctor detects but never auto-fixes a directory move. Deterministic basename-fold naming with an identity-check conflict chain; hub_path rewritten to the derived location so old mage still resolves through the fallback; journaled rollback. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughThe PR adds an ADR-0044 implementation plan for migrating legacy local-hub metadata to ChangesLocal-Hub Migration
Estimated code review effort: 2 (Simple) | ~10 minutes Possibly related issues
Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches 💡 1🛠️ Fix failing CI checks 💡
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
|
🐇 CodeRabbit CLI review ran locally against this diff at This is the durable record the Posted by |
… atomic claim, phased journal Remote-backed old-shape files are explicitly in scope (field-only path); absent hub_repo detects like null; file:// converts via fileURLToPath before realpath; the atomic name claim is the rename itself (no lockfile, per house convention); the journal records per-phase completion and re-runs resume or refuse; rollback restores journaled fields surgically and refuses on divergence; docs artifacts carry invalidation triggers. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
|
🐇 CodeRabbit CLI review ran locally against this diff at This is the durable record the Posted by |
…can resume, fold-collision order migrated_from is the identity anchor (a moved source can't re-derive its realpath); resume scans for incomplete journals and refuses on plurality; ordering and collisions key on folded names globally; rollback compares the recorded HEAD id, not a commit count; hub-side metadata invariant stated; the empty-dir takeover property of the rename claim documented in place of a stronger primitive. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
|
@coderabbitai review |
✅ Action performedReview finished.
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 10
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@mage/work/plan-adr-0044-local-hub-migration.md`:
- Around line 24-29: Extract the reusable migration procedure, insight, and
relevant ADR pointers from this plan into an appropriate durable note under
mage/notes/ or via /mage:learn, without copying the plan verbatim; then run mage
index to register the new knowledge.
- Around line 108-111: Update the migration name-assignment rules around global
hub ordering and folded-name collision handling so results remain identical
across separate invocations. Account for all repository-local hubs before
reserving bare names, or use a fallback derived solely from the complete
starting set rather than migration order; preserve deterministic realpath
ordering and folded-candidate collision detection.
- Around line 162-164: Update the migration plan’s shared-hub move flow to
handle repositories outside the current walk-up scope before moving the hub:
either update every referrer, retain a discoverable redirect mapping the old hub
path to the new local:// address, or block the move until all references are
handled. Ensure the resulting behavior remains compatible with the fallback
resolution in link-checks.ts, particularly chosenHubRoot and stored hub_path
handling.
- Around line 200-213: Update the migration journal design to record each
affected metadata file’s post-migration field values and post-migration content
hash, in addition to its prior state. Capture these post-state values after the
migration changes are applied and before marking the corresponding phase
complete, so rollback can compare the current state against the exact migrated
state.
- Around line 56-60: Separate remote-backed metadata cleanup from the local-hub
move branch: preserve each remote record’s hub_repo, remove only obsolete
hub_path fields, and reshape references without deriving a local name, assigning
local:// or _local/ paths, or moving directories. Apply the existing
confirmation, journal, and rollback flow to both branches while ensuring
local-only path derivation remains confined to local hubs.
- Around line 127-136: Update the migration flow to validate hub metadata and
repository identity during preflight, before the directory move in Step 1,
rejecting hand-edited or non-hub metadata without changing its location. After
the move, retain arrival verification to confirm the hub exists at the derived
destination and still satisfies the identity checks.
- Around line 241-242: Update the `Docs surfaces` entry in the ADR to name the
affected documentation file explicitly, using `README.md — no update required`
if that is the intended scope, or identifying the exact README file requiring
changes. Replace the vague “README quickstart” wording while preserving the
stated quickstart impact.
- Line 229: Update the resolution precedence text in the ADR so the literal
_local token is formatted as inline code using backticks, while preserving the
surrounding wording and precedence notation.
- Around line 113-117: The migration claim flow must prevent replacing a
destination directory, including one that is empty. Update the destination claim
around the documented rename operation to use an atomic no-replace primitive or
reservation protocol before moving the hub, and on claim failure re-derive
against current _local contents without overwriting any existing destination.
- Around line 90-93: Update the claimed-name registry rules to derive the local
destination from hubsRoot()/_local/<name> instead of hard-coding
~/.mage/hubs/_local/<name>. Ensure serialized hub_path values use the expanded
absolute destination path, preserving a canonical resolved path even when
MAGE_HOME is configured.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro Plus
Run ID: ac8dde4b-4170-4066-8860-a4c32616281d
📒 Files selected for processing (1)
mage/work/plan-adr-0044-local-hub-migration.md
| # Plan — the `local://` hub migration (ADR-0044, issue #123) | ||
|
|
||
| The one-time migration ADR-0044 names in its Consequences: existing local-only | ||
| hubs carry a filesystem path in `hub_repo` (or only a `hub_path`), which throws | ||
| on canonicalization once the `local://` scheme lands. This plan is the | ||
| implementation design; it blocks the removal of `hub_path` (ADR-0043 §6). |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick win
Record the durable procedure in mage/notes/ or via /mage:learn.
This plan adds durable knowledge under mage/**/*.md. Extract the reusable insight, procedure, and pointers into a note or /mage:learn, then run mage index. Do not copy this plan verbatim.
As per coding guidelines, durable knowledge in mage/**/*.md requires a reusable note or /mage:learn entry followed by mage index.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@mage/work/plan-adr-0044-local-hub-migration.md` around lines 24 - 29, Extract
the reusable migration procedure, insight, and relevant ADR pointers from this
plan into an appropriate durable note under mage/notes/ or via /mage:learn,
without copying the plan verbatim; then run mage index to register the new
knowledge.
Source: Coding guidelines
| Case 4 is IN scope, deliberately: the migration's unit is "old-shape metadata | ||
| file", not "local hub". For remote-backed files the plan is field-only — drop | ||
| the dead `hub_path`, reshape refs, bump `schema` — with no move, no name | ||
| derivation, and the same confirmation/journal/rollback path as every other | ||
| rewrite. One detection rule, one flow; local hubs are the subset that also |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift
Keep remote-backed cleanup out of the local-hub move branch.
Lines 56-60 define canonical remote metadata as field-only cleanup. Lines 143-149 then assign local://<name> and _local/<name> paths to each referrer. If one generic flow applies both rules, a remote hub can be converted into a local hub incorrectly.
Define the remote branch explicitly: retain the remote hub_repo, remove only obsolete hub_path fields, and do not derive a local name or move a directory.
Also applies to: 143-149
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@mage/work/plan-adr-0044-local-hub-migration.md` around lines 56 - 60,
Separate remote-backed metadata cleanup from the local-hub move branch: preserve
each remote record’s hub_repo, remove only obsolete hub_path fields, and reshape
references without deriving a local name, assigning local:// or _local/ paths,
or moving directories. Apply the existing confirmation, journal, and rollback
flow to both branches while ensuring local-only path derivation remains confined
to local hubs.
| The claimed-name registry is the `_local/` directory itself plus each hub's | ||
| self-address (below). For candidate `<name>`: | ||
|
|
||
| - `~/.mage/hubs/_local/<name>` absent → claim it. |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
rg -n -C 6 '\bhubsRoot\b|MAGE_HOME|absolutePath|hub_path' src --glob '*.ts'Repository: Sumit1993/mage-memory
Length of output: 50378
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '--- candidate files ---\n'
fd -a '^plan-adr-0044-local-hub-migration\.md$|hub-url\.test\.ts$|paths\.ts$|hub-url\.ts$' .
printf '\n--- target ADR excerpt ---\n'
sed -n '70,160p' mage/work/plan-adr-0044-local-hub-migration.md
printf '\n--- hub-url tests around MAGE_HOME (first occurrences) ---\n'
rg -n -C 8 'MAGE_HOME|choose|hubsRoot|local|_local|hub_path' src/hub-url.test.ts --max-count 8
printf '\n--- path module absolutePath/tilde relevant implementation ---\n'
sed -n '700,745p' src/paths.ts
rg -n -C 4 'function absolutePath|export function absolutePath|tilde|home' src/paths.ts src/hub-url.tsRepository: Sumit1993/mage-memory
Length of output: 250
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '%s\n' '--- candidate files ---'
fd -a '^plan-adr-0044-local-hub-migration\.md$|hub-url\.test\.ts$|paths\.ts$|hub-url\.ts$' .
printf '%s\n' ''
printf '%s\n' '--- target ADR excerpt ---'
sed -n '70,160p' mage/work/plan-adr-0044-local-hub-migration.md
printf '%s\n' ''
printf '%s\n' '--- hub-url tests around MAGE_HOME (first occurrences) ---'
rg -n -C 8 'MAGE_HOME|choose|hubsRoot|local|_local|hub_path' src/hub-url.test.ts --max-count 8 || true
printf '%s\n' ''
printf '%s\n' '--- path module absolutePath/tilde relevant implementation ---'
sed -n '700-745p' src/paths.ts
rg -n -C 4 'function absolutePath|export function absolutePath|tilde|home' src/paths.ts src(hub-url.ts
printf '%s\n' ''
printf '%s\n' '--- behavioral probe: path.join/resolve with tilde ---'
node - <<'JS'
const path = require('node:path');
console.log(path.join('~/.mage/hubs/_local/foo', 'bar'));
console.log(path.resolve('~/.mage/hubs/_local/foo'));
console.log(path.join('/tmp/mage-home/hubs/_local/foo', 'bar'));
console.log(path.resolve('/tmp/mage-home/hubs/_local/foo'));
JSRepository: Sumit1993/mage-memory
Length of output: 8479
Use the configured hub root and store an expanded hub_path.
The plan hard-codes ~/.mage/hubs/_local, but hubsRoot() returns $MAGE_HOME/hubs when set. Also, Node path functions do not expand ~, so a metadata value starting with ~ would not resolve to the default hubs root on subsequent reads.
Define the destination as hubsRoot()/_local/<name> and serialize hub_path as the expanded absolute path so ~/.mage/hubs/_local/<name> is canonical regardless of MAGE_HOME.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@mage/work/plan-adr-0044-local-hub-migration.md` around lines 90 - 93, Update
the claimed-name registry rules to derive the local destination from
hubsRoot()/_local/<name> instead of hard-coding ~/.mage/hubs/_local/<name>.
Ensure serialized hub_path values use the expanded absolute destination path,
preserving a canonical resolved path even when MAGE_HOME is configured.
| Hubs migrate in realpath-sorted order GLOBALLY, and collisions are detected on | ||
| FOLDED candidates, not raw basenames — `My Hub` and `my-hub` are different | ||
| basenames but one folded name. Which hub gets the bare name is therefore | ||
| reproducible for any starting set. |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift
Make name assignment stable across separate migration runs.
Global sorting only applies to hubs visible in one invocation. With the stated repository-local scope, another invocation can claim the bare name first. The same starting set can then produce different names based on invocation order.
Scan and reserve all relevant hubs before assignment, or define a fallback that is independent of migration order.
Also applies to: 162-164
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@mage/work/plan-adr-0044-local-hub-migration.md` around lines 108 - 111,
Update the migration name-assignment rules around global hub ordering and
folded-name collision handling so results remain identical across separate
invocations. Account for all repository-local hubs before reserving bare names,
or use a fallback derived solely from the complete starting set rather than
migration order; preserve deterministic realpath ordering and folded-candidate
collision detection.
| **The claim is the rename itself — no lockfile.** `rename(2)` into | ||
| `~/.mage/hubs/_local/<name>` fails (`ENOTEMPTY`/`EEXIST`) if the destination | ||
| appeared after the plan was shown, so the atomic conflict check happens at the | ||
| only moment that matters. On that failure the run re-derives against the now- | ||
| current `_local/` contents and re-confirms; it never overwrites. A lockfile |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
tmp="$(mktemp -d)"
trap 'rm -rf "$tmp"' EXIT
mkdir "$tmp/src" "$tmp/dst"
python3 - "$tmp/src" "$tmp/dst" <<'PY'
import os
import sys
os.rename(sys.argv[1], sys.argv[2])
PY
test ! -e "$tmp/src"
test -d "$tmp/dst"
echo "rename replaced an existing empty directory"Repository: Sumit1993/mage-memory
Length of output: 203
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "Locate file and inspect relevant lines"
wc -l mage/work/plan-adr-0044-local-hub-migration.md || true
sed -n '90,150p' mage/work/plan-adr-0044-local-hub-migration.md
echo
echo "Search for rename/renameall/claim/lockfile in mage docs/work"
rg -n "rename\\(2\\)|rename\\(|renameall|lockfile|no-replace|EEXIST|ENOTEMPTY|never overwrites|overwrites|_local" mage/work mage -g '*.md' -g '*.mdx' || trueRepository: Sumit1993/mage-memory
Length of output: 9757
🌐 Web query:
POSIX rename directory destination empty directory on POSIX failure error ENOTEMPTY EEXIST
💡 Result:
Under the POSIX standard, the rename function behaves as follows when the destination (new argument) is a directory: If the source (old argument) is a directory, the destination must either not exist or be an empty directory [1][2][3]. If the destination is an existing, non-empty directory, the rename operation will fail [1][4][5]. Regarding the specific error codes when this operation fails: POSIX permits implementations to return either EEXIST or ENOTEMPTY in this scenario [5]. Specifically, the POSIX specification for rename states that if the link named by new is a directory that is not an empty directory, the function shall fail with [EEXIST] or [ENOTEMPTY] [5]. In practice, different operating systems may choose one or the other. For instance, GNU/Linux and GNU/Hurd systems typically return ENOTEMPTY, while other POSIX-compliant systems may return EEXIST [4]. Because both are permitted by the standard, portable software should be prepared to handle both error codes when attempting to rename a directory over an existing destination [4][5].
Citations:
- 1: https://pubs.opengroup.org/onlinepubs/9799919799/functions/rename.html
- 2: https://pubs.opengroup.org/onlinepubs/9699919799.orig/functions/rename.html
- 3: https://pubs.opengroup.org/onlinepubs/009695399/functions/rename.html
- 4: https://sourceware.org/glibc/manual/latest/html_node/Renaming-Files.html
- 5: https://man7.org/linux/man-pages/man3/rename.3p.html
Use a no-replace claim for the destination.
POSIX allows rename() to replace an existing empty directory. Since the plan explicitly treats empty destinations as stale and replaces them, a directory created after confirmation can still be overwritten, which contradicts the “never overwrites” claim. Use an atomic no-replace primitive or reservation protocol before moving the hub directory.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@mage/work/plan-adr-0044-local-hub-migration.md` around lines 113 - 117, The
migration claim flow must prevent replacing a destination directory, including
one that is empty. Update the destination claim around the documented rename
operation to use an atomic no-replace primitive or reservation protocol before
moving the hub, and on claim failure re-derive against current _local contents
without overwriting any existing destination.
| 1. **Move** the hub directory to `~/.mage/hubs/_local/<name>` — `rename(2)` | ||
| only; a cross-device move (EXDEV) is refused with the exact `mv` command | ||
| printed for the user instead. The ADR's identity check requires the hub AT | ||
| the derived path, so registering-in-place is not an option. | ||
| 2. **Hub-side self-address**: the hub's own `metadata.json` records | ||
| `local://<name>` plus `migrated_from` (the pre-move realpath), and takes the | ||
| same `schema` bump. Invariant, stated rather than assumed: hub-side metadata | ||
| is hub-shaped — it never carries top-level `hub_path` or `hub_refs[]` | ||
| (those are referrer fields); if a hand-edited hub file carries them anyway, | ||
| migrate refuses and names the file rather than guess. The self-address is |
There was a problem hiding this comment.
🩺 Stability & Availability | 🟠 Major | ⚡ Quick win
Validate the hub before the directory move.
Step 2 can refuse hand-edited or non-hub metadata only after Step 1 has moved the directory. A failed validation can therefore leave an incomplete migration with the hub at a new location.
Validate the hub metadata and repository identity during preflight. Repeat arrival verification after the move.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@mage/work/plan-adr-0044-local-hub-migration.md` around lines 127 - 136,
Update the migration flow to validate hub metadata and repository identity
during preflight, before the directory move in Step 1, rejecting hand-edited or
non-hub metadata without changing its location. After the move, retain arrival
verification to confirm the hub exists at the derived destination and still
satisfies the identity checks.
| A single `mage migrate` run only rewrites metadata files it can see (the current | ||
| repo/walk-up, per existing migrate scope). Other machines/repos referencing the | ||
| same hub are caught by the doctor advisory when they next run anything. |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift
Handle unvisited referrers before moving the shared hub.
The move applies to the hub, but metadata updates apply only to the current repository and walk-up. An unvisited repository keeps the old hub_repo or hub_path. After the move, chosenHubRoot falls back to the old path, which is no longer reachable.
The plan defines no mapping from the old path to the new local:// address. Update all referrers, leave a discoverable redirect, or block the move until unvisited references are handled.
This relies on src/doctor/link-checks.ts, Lines [76]-[162], where the fallback resolves the stored hub_path.
Also applies to: 177-187
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@mage/work/plan-adr-0044-local-hub-migration.md` around lines 162 - 164,
Update the migration plan’s shared-hub move flow to handle repositories outside
the current walk-up scope before moving the hub: either update every referrer,
retain a discoverable redirect mapping the old hub path to the new local://
address, or block the move until all references are handled. Ensure the
resulting behavior remains compatible with the fallback resolution in
link-checks.ts, particularly chosenHubRoot and stored hub_path handling.
| Before any write, the run journals to | ||
| `~/.mage/state/migrations/local-hub-<ISO timestamp>.json`: every metadata | ||
| file's prior field values plus a content hash of the file at journal time, the | ||
| directory move (`src`, `dst`), and per-phase completion flags (see Rewrite | ||
| surface). Then `mage migrate --rollback <journal>`: | ||
|
|
||
| - **Restores journaled FIELDS only** — a surgical rewrite of the recorded | ||
| values, never `git checkout` of the whole file, so an unrelated edit made | ||
| after migration survives rollback. | ||
| - **Refuses on divergence rather than guess**: a metadata file whose relevant | ||
| fields no longer match the migrated values, or a moved hub whose `HEAD` | ||
| commit id differs from the one recorded in the journal at migration time | ||
| (identity, not a commit-count heuristic — counts miss amend/rebase), stops | ||
| the rollback with both states named. Git remains the deeper restore for tracked files; the journal |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift
Journal the post-migration values needed for rollback.
The journal records prior fields and a hash from journal time. Rollback must compare the current fields with the migrated values. Without exact post-migration values or a post-migration hash, rollback cannot reliably distinguish the expected state from a later edit.
Store the post-state for every affected metadata file and phase before marking the phase complete.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@mage/work/plan-adr-0044-local-hub-migration.md` around lines 200 - 213,
Update the migration journal design to record each affected metadata file’s
post-migration field values and post-migration content hash, in addition to its
prior state. Capture these post-state values after the migration changes are
applied and before marking the corresponding phase complete, so rollback can
compare the current state against the exact migrated state.
|
|
||
| - `docs/src/content/docs/model/modes.md` + `reference/commands.mdx` — replace | ||
| the ADR-0043 forward-marker asides with real behavior; the mixed-version | ||
| resolution precedence (hub_repo → derived, local:// → derived _local, |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Format _local as code.
The plain _local token triggers the reported Markdown emphasis warning. Write it as `_local`.
Static analysis reports MD037 on Line 229.
Proposed fix
- resolution precedence (hub_repo → derived, local:// → derived _local,
+ resolution precedence (`hub_repo` → derived, `local://` → derived `_local`,📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| resolution precedence (hub_repo → derived, local:// → derived _local, | |
| resolution precedence (`hub_repo` → derived, `local://` → derived `_local`, |
🧰 Tools
🪛 markdownlint-cli2 (0.23.1)
[warning] 229-229: Spaces inside emphasis markers
(MD037, no-space-in-emphasis)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@mage/work/plan-adr-0044-local-hub-migration.md` at line 229, Update the
resolution precedence text in the ADR so the literal _local token is formatted
as inline code using backticks, while preserving the surrounding wording and
precedence notation.
Source: Linters/SAST tools
| - README quickstart: unaffected (local hubs are not the quickstart path) — | ||
| stated per the docs-surfaces rule rather than omitted. |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Name the README file explicitly in Docs surfaces.
The entry says “README quickstart” but does not identify a file. Change it to README.md — no update required, or name the exact README file that must change.
As per coding guidelines, the Docs surfaces section must name specific files or explicitly state that no file is affected.
Proposed wording
- README quickstart: unaffected (local hubs are not the quickstart path) —
+ README.md — no update required (local hubs are not the quickstart path) —📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| - README quickstart: unaffected (local hubs are not the quickstart path) — | |
| stated per the docs-surfaces rule rather than omitted. | |
| - README.md — no update required (local hubs are not the quickstart path) — | |
| stated per the docs-surfaces rule rather than omitted. |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@mage/work/plan-adr-0044-local-hub-migration.md` around lines 241 - 242,
Update the `Docs surfaces` entry in the ADR to name the affected documentation
file explicitly, using `README.md — no update required` if that is the intended
scope, or identifying the exact README file requiring changes. Replace the vague
“README quickstart” wording while preserving the stated quickstart impact.
Source: Coding guidelines
1 participant
Implementation design for the one-time migration ADR-0044 names in its Consequences — issue #123 (Spec the local:// hub migration before hub_path is removed).
Answers all six required questions:
mage migrate(the existing one-time-shape home); doctor detects but never auto-runs a directory move.--nameoverride.~/.mage/hubs/_local/<name>(rename(2) only, EXDEV refused with the mv printed), hub-side self-address written, referrers'hub_repo/hub_refs[]rewritten, schema bumped to piggyback the existing doctor drift check.hub_pathdeliberately rewritten to the NEW location so old mage resolves through its fallback; the one accepted gap (old mage + reshaped hybrid refs) is named and warned at confirmation.mage migrate --rollback; git restores the tracked metadata.Docs surfaces section included per AGENTS.md (names #113's checklist files; the resolution precedence carries a worked-example table + transcript per the illustration standard).
Related: #113 (0.0.18 docs checklist), ADR-0043 §6 (hub_path removal this unblocks).
🤖 Generated with Claude Code
Summary by CodeRabbit
local://addresses.