Fix what the first run against a foreign repository showed - #37
Merged
Merged
Conversation
Three Forge sessions reviewed this tool and none executed it. The first real run - `traceos init` against an unrelated 1,097-file repository - produced four defects in thirty seconds, one of which needs no knowledge of TraceOS to see. **The External guesser is gone.** It scanned imports and, measured on that repository, was wrong on all fifteen suggestions: the language's standard library, the test runner, the UI toolkit, the bundler's type keyword parsed as a package name, and the repository itself. `externals.md` now explains what an External is and says plainly that nothing is suggested, because a wrong suggestion at step one is worse than no suggestion. That also removes the `type` artifact and the self-reference, which were symptoms of the same heuristic. **`python3 -m traceos.cli` no longer prints a RuntimeWarning** into the user's first command. `__init__` imported `.cli` at module scope, so `-m` found it already in `sys.modules`. Resolved lazily through `__getattr__`, which keeps `main` and `parse_context` importable for the embedders that were the stated reason for the re-export. **The printed next steps asked for the hardest thing first.** Step 2 was "replace example.md with your most important flow" - the flow you can least afford to get wrong, chosen while still learning the vocabulary - and step 4 handed the reader a nine-step whole-system skill. The steps now ask for a small flow the reader already understands, and end at the one thing worth seeing: edit a cited file, re-validate, watch confidence fall. The "no way in" row in DEVELOPMENT-PLAN claimed this risk was mitigated by `init` plus `coverage_declared: partial`. It was not, and the row now says so along with what the first run actually showed. 4 new assertions; 36/36 groups, 162/162. Falsified: restoring the eager import re-prints the warning, and restoring the candidates heading fails the scaffold check. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Three Forge sessions reviewed this tool over two days and none executed it. The first real run —
traceos initagainst an unrelated 1,097-file repository — produced four defects in thirty seconds, one of which needs no knowledge of TraceOS to see.What the run showed
The External guesser suggested these, in order:
typeis a parse artifact —import type { X } from 'y'read as a package namedtype.getcontentis the repository itself, offered as its own External.The fixes
The guesser is deleted, along with
IMPORT_PATTERNS,SOURCE_SUFFIXESandsuggest_externals— 48 lines.externals.mdnow explains what an External is, gives examples of what is and is not one, and states that nothing is suggested on purpose. That removes thetypeartifact and the self-reference as symptoms of the same heuristic rather than patching each.python3 -m traceos.clino longer prints a RuntimeWarning into the user's first command.__init__imported.cliat module scope, so-mfound it already insys.modules. Now resolved lazily via__getattr__, which keepsmainandparse_contextimportable — the embedders that were the stated reason for the re-export in #23.The printed steps asked for the hardest thing first. Step 2 was "replace example.md with your most important flow" — the flow you can least afford to get wrong, chosen while still learning the vocabulary — and step 4 pointed at a nine-step whole-system skill. The steps now ask for a small flow the reader already understands and end at the one thing worth seeing:
A claim of mine that did not survive
DEVELOPMENT-PLAN.mdlists "no way in" as a carried risk and claimed it was held back bytraceos initpluscoverage_declared: partialbeing documented as normal. The scaffold exists, but it pointed straight at a whole-system methodology and handed over fifteen wrong guesses on the way. The row now records that the mitigation did not hold and what the first run showed.Verification
4 new assertions, 36/36 groups, 162/162. Falsified: restoring the eager import re-prints the warning; restoring the candidates heading fails the scaffold check.