[V2:02] Split Preprocessor CLI and Command Modules

[ritorhymes]

Part of V2: Multi-repo local build system.

Summary

This PR establishes the preprocessor module boundaries that the rest of the V2 stack builds on. It is a behavior-preserving split of main.rs into owned modules (cli, context, layout, changed), so review should focus on where code lives rather than what it does.

• Move the clap command surface and command argument types into cli.rs.
• Move root path resolution into context.rs.
• Move shared build layout constants into layout.rs.
• Move changed-file command execution and the shared is_proposal_path classifier into changed.rs.
• Add initial module/test ownership notes in src/README.md.

Review Notes

This is the module foundation for the preprocessor stack. Later preprocessor PRs build on these extracted modules rather than continuing to grow main.rs.

Review this as a structural split of existing behavior. CLI surface and runtime behavior should remain unchanged.

Prepared::prepare now calls changed::is_proposal_path; the helper moved out of Prepared because both the changed command and the build pipeline filter on proposal paths.

Feature-specific command behavior still lands with the later PRs that expose those features.

Verification

• Review main.rs for reduced top-level orchestration.
• Review cli.rs for the moved clap command surface.
• Review changed.rs, context.rs, and layout.rs for extracted helper ownership.
• Review src/README.md for the initial module and test ownership guidance.

[SamWilsn]

I assume this is somewhat for/by LLMs? I've seen people use .claude or .agents. Would that be more appropriate?

[ritorhymes]

It's intended to be useful for humans and agents alike.

I do think agent-first guidance files would be useful to include: an AGENTS.md in each repo and for the generated workspace to serve as entrypoints routing to other md files as needed, perhaps inside .agents/.

If there were dedicated folders like .agents/, I'm not sure I would put that particular file directly in one unless we committed to consolidating broader general documentation that humans are meant to consume there too.

I would like to think more about this, but I do not want it to block this review process. I think it would be better to confirm how the architecture stands first, then build an agent guidance system around the final shape so it can help with maintenance and contributions without getting anchored to transitional scaffolding.

[SamWilsn]

This line is only relevant while the pull request is in flight. After merge, it loses meaning. Existing when?

[ritorhymes]

Removed in the latest push.

[SamWilsn]

This is an unnecessary clone.

[ritorhymes]

Yeah, good catch. I'll drop the clone by making the argument mutable directly.

[ritorhymes]

Fixed in the latest push.

[SamWilsn]

This file could be a mod layout { ... } instead. Doesn't seem to get much more complex in the later PRs either.

[ritorhymes]

In V2:02 here, this is a small constants module because that PR is still laying scaffolding for later runtime boundaries. I kept it as a file module because it becomes shared prepared-runtime layout vocabulary once V2:10 lands.

By V2:10, layout.rs owns helpers like output_path, mounted_theme_path, and theme_config_path. By V2:18, layout::* is imported across unrelated modules like find_root, git, pipeline, proposal, serve, and zola, while still having no dependencies of its own. So I do not think there is a natural file to nest it inside as mod layout { ... } without assigning it an arbitrary parent.

[SamWilsn]

There's an argument to be made for putting the *_DIR constants, root and is_proposal_path into one module dedicated to paths. What do you think?

[ritorhymes]

I think this is one of the awkward parts of slicing the system up for review. In V2:02, layout.rs is mostly scaffolding for boundaries that become clearer later, so it looks heavier than the immediate code requires.

I think the later stack justifies keeping the split. By V2:10, layout.rs owns the shared prepared-runtime layout helpers like output_path, mounted_theme_path, and theme_config_path. Separately, context.rs grows into CLI/workspace root and input-path resolution.

The proposal-path part follows the same pattern. In V2:02, changed.rs carrying is_proposal_path is narrower than the eventual ownership boundary. The later stack moves that logic toward the proposal domain rather than a generic paths module: proposal.rs starts owning proposal-number and proposal-path classification in V2:13, and by V2:18 changed.rs calls proposal::is_proposal_path instead of carrying that logic itself.

I do want to fix things to ensure a stable and scalable final architecture, but I am trying not to over-optimize intermediate scaffolding when the later stack gives the code a clearer home. I can try to adjust scaffolding where it materially improves reviewability within reason, but there is no perfect way to split a system like this without tradeoffs, and chasing that across every intermediate branch is not really feasible.

[SamWilsn]

The later stack moves that logic toward the proposal domain rather than a generic paths module: proposal.rs starts owning proposal-number and proposal-path classification in V2:13, and by V2:18 changed.rs calls proposal::is_proposal_path instead of carrying that logic itself.

Ah, that makes sense. I was questioning whether is_proposal_path in changed.rs made sense.

[ritorhymes]

@SamWilsn I am open to feedback on how to make the stack easier to review as a stack, especially where an intermediate slice looks awkward before later PRs give it its final owner. I do not want to churn every transitional boundary just to make each slice look perfect in isolation, but if there are recurring patterns that make review harder and you have actionable feedback I can apply, I would like to know so I can address those deliberately.

[SamWilsn]

I'll try to pay more attention to the future pull requests. I did quickly look ahead for layout and I'm still not entirely sure I'm convinced it needs a whole module, but it's fine for now.