Skip to content

Fix what the first run against a foreign repository showed - #37

Merged
junixlabs merged 1 commit into
mainfrom
init-honesty
Sep 11, 2026
Merged

junixlabs merged 1 commit into
mainfrom
init-honesty

Conversation

@junixlabs

Copy link
Copy Markdown
Owner

Three Forge sessions reviewed this tool over two days 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.

What the run showed

The External guesser suggested these, in order:

getcontent · type · vitest · tanstack · react · hono · node:crypto
zod · node:path · lucide-react · node:url · node:fs · radix-ui
modelcontextprotocol · dotenv
  • type is a parse artifact — import type { X } from 'y' read as a package named type.
  • getcontent is the repository itself, offered as its own External.
  • All fifteen are wrong against the spec's own test: an External is something whose behavior you cannot change by editing this repository. The standard library, the test runner and the UI toolkit are how the repository is built, not behavior outside it.

The fixes

The guesser is deleted, along with IMPORT_PATTERNS, SOURCE_SUFFIXES and suggest_externals — 48 lines. externals.md now explains what an External is, gives examples of what is and is not one, and states that nothing is suggested on purpose. That removes the type artifact and the self-reference as symptoms of the same heuristic rather than patching each.

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. Now resolved lazily via __getattr__, which keeps main and parse_context importable — 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:

  1. edit the file you cited, run validate again, and watch confidence fall.
    That is the whole mechanism. Everything else is more of it.

A claim of mine that did not survive

DEVELOPMENT-PLAN.md lists "no way in" as a carried risk and claimed it was held back by traceos init plus coverage_declared: partial being 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.

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>
@junixlabs
junixlabs merged commit 0b8774f into main Sep 11, 2026
9 checks passed
@junixlabs
junixlabs deleted the init-honesty branch September 11, 2026 16:25
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