Promote #123 legacy root doc normalization fix family end-to-end from corrected local truth

[fujiwaranosai850]

Purpose

Create a fresh end-to-end promotion package for the legacy root doc normalization fix family, without relying on pre-existing PR state.

Source of truth

Current corrected local truth is on devclaw-local-current after rollback and reapply.

Relevant local-truth commits in order:

• 938dc64 fix: manage workspace root bootstrap files with tagged blocks (#522) (first required prerequisite in this family)
• 442bd22 fix: collapse duplicated legacy root docs (#123) (final fix)

Non-upstream local-only docs on local truth:

• 87e0af7 docs: tighten local-current promotion and live install handoff

Historical failed/stale promotion chain that must NOT be reused as the release package:

• PR fix: normalize legacy managed root docs #143 / fix: normalize legacy managed root docs #146 / revert: roll back failed #123 local-truth release #147 / fix: collapse duplicated legacy root docs #155 / revert: demote merged #123 review package before corrected re-promotion #158
• old branches like review/123-legacy-root-doc-normalization and pr/123-legacy-root-doc-normalization

Required release outcome

Build a fresh promotion that does not sit on any pre-existing PR.

Required outputs:

• fresh review/<issue-number>-<slug> branch and local-truth PR state recorded truthfully
• fresh pr/<issue-number>-<slug> branch from upstream/main
• upstreamable commit set should cover the actual fix family from the first related code commit to the last related code commit
• prepare compare URL and proposed upstream PR body

Constraints

• Follow dev/runbooks/developing-devclaw-with-openclaw.md
• Do not treat the old merged review/export branches as reusable release state
• Preserve local-only /dev/ docs on devclaw-local-current, but omit them from upstream export unless needed
• Record exact source commits, branch heads, PR URLs, and remaining human-only steps

[fujiwaranosai850]

🎛️ ORCHESTRATOR: ## Fresh end-to-end release package for the #123 root doc normalization family

Built a new promotion package from the corrected local-truth lane, without relying on the stale pr/123-legacy-root-doc-normalization line.

Source commit map

Local-truth family used for this release package:

1. 938dc64522931b659e8522d64bf1f68410a2893f fix: manage workspace root bootstrap files with tagged blocks (#522)
2. 442bd222833632c31e84940d459a42c3bbca59c4 fix: collapse duplicated legacy root docs (#123)

Local-only docs on devclaw-local-current, intentionally not included in upstream export:

• 87e0af71f38abaeb3f716c7af572d3f95f5b4c53 docs: tighten local-current promotion and live install handoff

Fresh branch set

• review branch: review/159-root-doc-normalization-e2e
  • head: 87e0af71f38abaeb3f716c7af572d3f95f5b4c53
• upstream export branch: pr/159-root-doc-normalization-e2e
  • head: 35bbd4d9e8f65a211518fb3fe353fcb0e376eef3

Export branch contents

Fresh curated upstreamable commits on pr/159-root-doc-normalization-e2e:

1. 6fcd1e87d43ca848d8e6b987a7cbe914becb135e fix: manage workspace root bootstrap files with tagged blocks (#522)
2. 35bbd4d9e8f65a211518fb3fe353fcb0e376eef3 fix: collapse duplicated legacy root docs (#123)

Local-truth PR state

I attempted to create a brand new local-truth PR from review/159-root-doc-normalization-e2e into devclaw-local-current, but GitHub rejected it with:

No commits between devclaw-local-current and review/159-root-doc-normalization-e2e

That is the truthful state because the corrected family is already present on devclaw-local-current after rollback + reapply, and the live environment is already running from that corrected local-truth branch.

Validation

Fresh export branch validation on /tmp/pr-159-root-doc-normalization-e2e:

• npm run build ✅
• npx tsx --test lib/setup/workspace.test.ts ✅
• focused acceptance covered by passing subtests including:
  • should normalize legacy full-file DevClaw root docs into a single managed block without duplication
  • should collapse the real legacy-plus-tagged duplicate shape into one managed section

Upstream handoff

Compare URL for operator PR opening:

• laurentenhoor/devclaw@main...yaqub0r:pr/159-root-doc-normalization-e2e

Proposed upstream PR title:

• fix: collapse duplicated legacy root docs

Proposed upstream PR body:

## Summary
- manage workspace root bootstrap files with tagged blocks so legacy root docs can be normalized safely
- collapse duplicated legacy root doc content into a single managed section during migration
- add regression coverage for the real duplicate-data shape and the legacy full-file normalization path

## Validation
- npm run build
- npx tsx --test lib/setup/workspace.test.ts

Remaining human-only step

• open the upstream DevClaw official PR from pr/159-root-doc-normalization-e2e using the compare URL above

[fujiwaranosai850]

🎛️ ORCHESTRATOR: ## Final upstream handoff after operator-reported testing completion

The operator reported testing complete, so this handoff now includes the final upstream issue linkage plus the proposed upstream PR text.

Upstream issue linkage

Existing related upstream issue:

• laurentenhoor/devclaw#522 DevClaw still overwrites workspace-root AGENTS.md/HEARTBEAT.md/TOOLS.md on startup, despite conflicting history
  • comment added: DevClaw still overwrites workspace-root AGENTS.md/HEARTBEAT.md/TOOLS.md on startup, despite conflicting history laurentenhoor/devclaw#522 (comment)

New discrete upstream bug record created for the duplicate-normalization problem itself:

• laurentenhoor/devclaw#536 Legacy full-file workspace root docs can duplicate content during tagged-block normalization
  • issue: Legacy full-file workspace root docs can duplicate content during tagged-block normalization laurentenhoor/devclaw#536
  • fix comment: Legacy full-file workspace root docs can duplicate content during tagged-block normalization laurentenhoor/devclaw#536 (comment)

Compare URL

• laurentenhoor/devclaw@main...yaqub0r:pr/159-root-doc-normalization-e2e

Final proposed upstream PR title

fix: normalize legacy workspace root docs without duplicate managed content

Final proposed upstream PR body

## Summary
- fix workspace-root bootstrap ownership so tagged managed sections can be applied safely
- normalize legacy full-file root docs into a single managed section without duplicating DevClaw-managed content
- add regression coverage for both the real duplicate-data shape and the legacy full-file normalization path

## Issue links
- closes #536
- related to #522

## Validation
- npm run build
- npx tsx --test lib/setup/workspace.test.ts

Remaining human-only step

• open the upstream DevClaw official PR from pr/159-root-doc-normalization-e2e using the compare URL above

[fujiwaranosai850]

🎛️ ORCHESTRATOR: ## Upstream PR tracking started

The upstream DevClaw official PR is now open:

• laurentenhoor/devclaw#537 fix: normalize legacy workspace root docs without duplicate managed content laurentenhoor/devclaw#537

Tracking rule going forward:

• this local promotion issue remains the canonical release tracker
• upstream PR state changes should be recorded here until resolution
• after upstream resolution, local cleanup should include closing this promotion issue and deleting no-longer-needed release-only artifacts such as the associated pr/* branch

[fujiwaranosai850]

🎛️ ORCHESTRATOR: ## Local #159 artifact cleanup completed

Cleaned up non-essential local release artifacts for this active upstream promotion while preserving the active upstream PR vehicle.

Removed:

• remote review branch review/159-root-doc-normalization-e2e
• local review branch review/159-root-doc-normalization-e2e
• local export branch pr/159-root-doc-normalization-e2e
• temp export worktree /tmp/pr-159-root-doc-normalization-e2e

Intentionally preserved:

• remote export branch origin/pr/159-root-doc-normalization-e2e because it backs upstream PR laurentenhoor/devclaw#537
• the active daily watch tracking upstream PR resolution

[fujiwaranosai850]

Closing the replacement promotion tracker as part of 123-family cleanup.

Completed locally:

• corrected fix family was repackaged from local truth
• stale 123-family release artifacts were cleaned up
• only the active upstream export branch backing laurentenhoor/devclaw#537 was intentionally preserved

Remaining upstream-facing status is now embodied by the upstream PR itself:

• laurentenhoor/devclaw#537 fix: normalize legacy workspace root docs without duplicate managed content laurentenhoor/devclaw#537

So this local promotion issue is no longer needed as an open tracker.

[fujiwaranosai850]

Reopening this local promotion tracker to match the /dev runbook while upstream PR laurentenhoor/devclaw#537 remains unresolved.

Current upstream state check:

• PR: fix: normalize legacy workspace root docs without duplicate managed content laurentenhoor/devclaw#537
• state: OPEN
• review decision: none recorded
• reviews/comments since tracking start: no meaningful new review or resolution activity detected

No release-artifact cleanup is appropriate yet because the active upstream export branch origin/pr/159-root-doc-normalization-e2e is still the PR vehicle, and the scheduled watch should remain in place until the upstream lane resolves.