Keep tool roots separate from project roots

These examples and illustrative results are independently authored teaching materials, not measured model results.

Use case

Installed brand helper code lives in tools/brand/, while the task reads shop’s docs/brand-guidelines.md and produces assets/design-tokens.json. Changing into the helper directory can redirect cwd-based reads and writes into the installed package.

Mechanism

Record tool and project roots and inspect the trusted helper’s input/output path contract. Resolve the script relative to its tool root while keeping cwd at shop’s root, or pass an explicit project argument if supported. List resolved absolute artifact paths before execution; preview and inspect existing token sources. Resolve replacement intent rather than hiding conflicts with force. Afterward verify artifact locations and logs.

Bad example

Sync shop's brand tokens by changing into tools/brand and running scripts/sync-brand-to-tokens.cjs. Create missing files and add force when conflicts are detected.

Good example

Before syncing shop's tokens, verify helper trust and its path contract. Resolve the full script path from the tool root while keeping cwd at shop. List resolved brand-document and token paths and preview existing sources. Report specific conflicts and establish the replacement scope before writing, then verify actual output locations.

Why the change matters

Installed code and task data have different roots. Making both explicit prevents cwd changes from silently redirecting inputs and outputs. Previewed paths also expose helpers that search upward for a project root.

Observable expectation

A teaching record should place script in tools/brand, cwd in shop, and both input and output in shop. Missing guidelines cause an error; existing token sources produce a conflict rather than new project files inside the tool package. Compare installation hashes to detect unintended writes.

Limits

Helpers may resolve paths from cwd, explicit arguments, configuration locations or upward searches; one contract cannot represent every tool. Root separation is not permission or confinement. Check symlinks, relative outputs and child processes too. Neither preview nor force grants arbitrary overwrite permission.