Accepted
A defect was found where, in an external project (todo2, in which the app itself sits at the repository root and markharness’s knowledge/ etc. is initialized under docs/ via markharness init --dir docs), running markharness execution record failed in a layout where markharness’s project directory (--dir) does not coincide with the root of the git repository (i.e., is placed in a subdirectory within the repository). This is a primary-source case demonstrating that real users do attempt this layout in practice, and before fixing it, a design decision was needed on whether this layout should be formally supported at all.
Option 2 was adopted. The project directory (the parent of knowledge/ etc., the root specified via --dir/cwd) need not coincide with the root of the git repository.
Rationale:
todo2 primary-source case already demands this layout in actual operation.changes compute is designed to compare only the tree SHA of the subtree under knowledge/ between milestones, while the milestone itself (a git tag) is a global concept for the entire repository. It is natural, and consistent with subdirectory placement, for the product’s own release tags to be reused directly as milestones while markharness looks only at the subtree it cares about.knowledge//generated/ etc. directly under the product’s source tree — both unnatural as repository structures. No structural downside on the subdirectory-placement side was found that offsets this disadvantage.<rev>:<path> syntax used by tree_sha/show_blob in src/git.rs is always interpreted as a path relative to the repository root unless it begins with ./ or ../ (changing the current directory via git -C <root> does not affect this interpretation rule). Meanwhile, the caller id_cache::resolve_feature_versions passed paths obtained via git ls-tree’s pathspec syntax (correctly resolved relative to -C root) directly into <rev>:<path>, causing paths to become misaligned and fail when root was a subdirectory of the repository.tree_sha was rewritten from git rev-parse --verify <rev>:<path> to a git ls-tree-based approach (a pathspec relative to -C root). The path-based show_blob was removed and replaced with show_blob_by_sha (git cat-file -p), which directly takes the content-addressed SHA already returned by ls_tree_recursive. Since a SHA does not go through path interpretation, it is unaffected by where root is located within the repository.--dir in docs/cli-manual.md was corrected from “the target project directory (the root of the git repository)” to the effect of “any directory within a git repository (need not be the repository’s own root)” (§1.11/1.12/1.13/1.14).execution record and changes compute actually succeed for a subdirectory layout equivalent to todo2.docs/nested-project-dir-git-path-fix-spec.md, but with the response complete, its key points were transcribed into this decision record and the file was deleted.--dir at all (equivalent to git rev-parse --show-toplevel) is a natural next step to operationally complete this decision, but remains a separate future issue.