Skip to content

docs(registry): profile.md has no writer, and both surfaces that claimed one now say so (refs #58) - #614

Open
atomchung wants to merge 1 commit into
mainfrom
claude/xenodochial-fermi-33ad71
Open

docs(registry): profile.md has no writer, and both surfaces that claimed one now say so (refs #58)#614
atomchung wants to merge 1 commit into
mainfrom
claude/xenodochial-fermi-33ad71

Conversation

@atomchung

Copy link
Copy Markdown
Owner

What this fixes

Two surfaces asserted that ~/.trade-coach/profile.md is written by the agent per SKILL.md. Nothing writes it.

Location The claim
docs/maintainer-guide.md:137 `profile.md` (the agent writes it directly per `SKILL.md`)
tests/test_coach_data_cli.py:303-304 profile.md (written directly by the agent per SKILL.md, never by engine code)

Verified against main@94b7e5f: grep -rn "profile" skills/fomo-kernel/SKILL.md skills/fomo-kernel/flows/ skills/fomo-kernel/references/ returns exactly two hits, both profile.json — a different file holding max_position_pct and muted_rules. No profile.md on any agent instruction surface, and no engine/ module writes it. It is a vestige of an earlier design that stayed registered.

Why both, and why together

git log -S puts the test comment first (6a82ec8, #471, when the registry-completeness scanner was written) and the guide's copy second (78aedc4, #587, when the shared contract left CLAUDE.md). The guide did not invent the claim — it inherited it.

Correcting only the guide would have left the assertion alive in the very file the guide's row cites as its coverage evidence: the mirrored-surface defect docs/maintainer-guide.md names as this repository's most frequent. Each corrected statement now names the other as its mirror, so a future edit to one is prompted to check the other.

The test comment also carried a second, smaller error the guide did not: it said both scan-invisible entries "are written from outside that scope", when only ux/ is. The two are now separated — they are unseen for different reasons, and only one of them has a writer.

What is deliberately unchanged

  • coach.py's DATA_FILES. The entry stays registered, so data-status/data-export/data-reset keep seeing a file an older root may hold. Deregistering it would change export and reset coverage.
  • Its user-facing description 「第一次復盤時建立,Claude 直接寫檔」 — the same stale claim in the one place a user reads it — and README.md:111 / README.zh-TW.md:111 / README.zh-CN.md:108, which still tell the user to cat it as "the baseline each review compares against".

Both are downstream of the revive / re-home / retire choice #58 owns, and are recorded there rather than fixed here. #597 separately ruled profile.md may not become a second canonical truth for provisional principles. This PR makes the maintainer authority stop testifying that a writer exists, so that choice gets made from measurement rather than from the guide.

Checked and left alone: tests/test_sizing_literal_gate.py:58 cites "the two paths it names as outside its own reach" as a scope-naming precedent. That statement stays true after this change, so it carries no drift.

Verification

python3 tests/run_all.py46/46 suites pass. tests/test_doc_language.py's maintainer-guide gate is presence-based ("a later edit to a row is that row's own business"), so a row rewrite is in scope for it.

Doc and comment text only; no behavior change, no schema change, no engine change.

Refs #58. Records the second location #597's evidence section flagged for re-homing.

Claim comment: #58 (comment)

🤖 Generated with Claude Code

…med one now say so (refs #58)

`docs/maintainer-guide.md`'s coach-root registry row and the scope comment in
`tests/test_coach_data_cli.py` both asserted that `profile.md` is "written
directly by the agent per SKILL.md". No instruction surface says that: the only
`profile` in `skills/fomo-kernel/references/` is `profile.json`, a different
file holding `max_position_pct` and `muted_rules`, and neither `SKILL.md` nor
any `flows/*.md` mentions `profile.md` at all. Nothing in `engine/` writes it
either. It is a vestige of an earlier design that stayed registered.

The test comment is where the sentence was written first (#471, when the
registry-completeness scanner was added); the maintainer guide inherited it in
#587, when the shared contract left `CLAUDE.md`. Correcting only the guide
would leave the claim alive in the very file the guide's row cites as its
coverage evidence -- the mirrored-surface defect that guide names as this
repository's most frequent -- so both move together and each now names the
other as its mirror.

The test comment carried a second, smaller error: it said both scan-invisible
entries "are written from outside that scope", when only `ux/` is. The two are
now separated, because they are unseen for different reasons and only one of
them has a writer.

Behavior unchanged. `coach.py`'s `DATA_FILES` entry stays registered so
`data-status`/`data-export`/`data-reset` keep seeing a file an older root may
hold; its own user-facing description and the three README lines carry the same
stale claim and are recorded on #58 rather than fixed here, because whether
`profile.md` is revived, re-homed into an append-only projection, or retired is
that issue's call. #597 separately ruled it may not become a second canonical
truth for provisional principles.

`tests/test_sizing_literal_gate.py`'s citation of "the two paths it names as
outside its own reach" was checked and left alone: that statement stays true.

`python3 tests/run_all.py`: 46/46 suites pass.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Copy link
Copy Markdown
Owner Author

Blocking documentation correction before merge (could not submit REQUEST_CHANGES because the PR author and reviewer account are the same).

The measured defect and the two-surface correction are sound, but this branch now writes a stale owner into the shared maintainer authority.

docs/maintainer-guide.md says the revive / re-home / retire choice is #58's open call. Since this PR was opened, #619 was created specifically as the current decision owner, with #58 treated as the historical writer proposal and #446 as the structured successor. #27 and the bounded hygiene record on #538 now route the same way. Merging this wording would fix one false claim while installing a new stale execution pointer in the file maintainers are told to trust.

Please make the smallest correction:

Also rebase/verify on latest main@9d6cb9a and report the current full offline suite rather than the pre-#611 46-suite count. No runtime widening is requested; coach.py, README and the actual retire/re-home decision remain out of this PR.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant