RL-018 A bounded workspace map for small models and reviewers

Observation

The user asked for “the tiny workspace to easily be navigable for the slm's and the large language models who review and improve the project” and for the harness to work “both ways.” The current list_files result contains a count and at most 50 files ordered by modification time. It does not identify the project type, instructions, entry points, important configuration, directory shape, file-type distribution, or how many paths were omitted from the list.

Because tool observations are compacted to 600 characters, a large flat file array can also be cut before an important older file appears. A small model must guess which path matters; a larger reviewer receives the same weak starting point and spends context reconstructing the tree.

Baseline

• list_files returns {ok,count,files}.
• files is capped at 50 and sorted newest first.
• There is no bounded structural map or omission count.
• The first 600 characters of a large result are file rows, with no guaranteed instructions, entry point, or project metadata.

Hypotheses

• H1 — landmarks survive a large workspace. In a fixture with more than 50 files, the result names root instructions/configuration and likely source entry points even when those paths fall outside the 50 displayed file rows.
• H2 — the map fits the small-model observation. The map appears before the flat file list and remains wholly present in the existing 600-character compact observation for the fixture.
• H3 — compatibility is preserved. Existing count and files fields, path safety, permission level, and the 50-row cap do not change.
• H4 — both directions share facts. The repository documents one discovery contract: models begin with the same generated map, then read only relevant files. The map is evidence and grants no additional capability.

Intervention

• describeWorkspace derives a bounded kind, readFirst, areas and types map from the already bounded workspace listing. It reads no file contents and is stable across modification order.
• list_files places that map before its compatible count and files fields, and adds the number of omitted file rows.
• WORKSPACE-DESIGN.md, README.md and AGENTS.md define the same discovery contract for local workers and reviewing models.
• HARNESS_VERSION is 2026-09-13-workspace-map-7.

Method

1. Create a workspace fixture containing root instructions, Node/TypeScript configuration, src/main.ts, and 60 feature files (65 files total).
2. Call the real list_files tool and inspect its returned map, compatibility fields and the existing compact(result) representation.
3. Test an empty workspace to ensure the additional fields remain bounded and well formed.
4. Run the full test suite, typecheck and build.

Results

• H1 supported (C): all five expected landmarks remained in readFirst; the flat list contained 50 of 65 paths and reported 15 omitted.
• H2 supported (C): the 600-character compact observation retained project kind, all landmarks, src:61, .ts:61 and omitted:15 before truncating recent file rows.
• H3 supported (C): count, files, the 50-row cap and all permission and path tests remain unchanged. The targeted file-tool suite passed 23/23.
• H4 supported for the written contract (C): all model sizes receive the same live map and still need read_file for contents. Behaviour with live models has not yet been measured.
• Full suite: 705 tests, 0 failures. Typecheck and build pass.

Threats to validity

• Landmark detection is deliberately heuristic. Unusual entry-point names will not appear in readFirst, although their folder and extension still appear.
• The 600-character measurement is the harness's character cap, not a tokenizer count from a real model server.
• Fixture tests prove that the evidence is available. They do not prove a 1.5B model chooses the right file or that a large reviewer needs fewer reads.
• The flat rows remain modification-ordered for compatibility; only the map is stable across modification order.

Conclusion

H1–H3 are supported by the deterministic fixture. H4 is supported as a shared contract and remains untested as a model-quality claim.

Follow-ups

1. Run paired navigation tasks on the 1.5B worker and a larger reviewer; record correct first-file choice, reads, prompt tokens and task completion.
2. Add a landmark only after an observed project layout is missed; do not grow the map speculatively.
3. If reviewers need change context, test a separate bounded diff summary rather than placing Git output in every workspace map.

Reproduce

node --import tsx --test tests/fileTools.test.ts
npm test
npm run typecheck
npm run build