Module project_root 

Issue #88: project-root detection and palace-slug enforcement.

Why: prevents unbounded palace creation by anchoring palace names to the canonical slug of the project directory that contains the CWD, or to the personal sentinel for non-project contexts. What: exports find_project_root, project_slug_at, project_slug, validate_palace_name, PERSONAL_PALACE, and PROJECT_MARKERS. Test: see unit tests inside this module. Project-root detection, palace-slug derivation, and .trusty-tools/ pin file management (issue #88 + Phase 1 of the .trusty-tools/ convention).

Why: unbounded palace creation leads to orphaned namespaces that no longer correspond to any project on disk. Anchoring palace names to a stable, filesystem-derived slug ensures each project gets exactly one palace and makes “which palace am I in?” predictable from the working directory alone. The personal palace is the single sanctioned exception for non-project contexts (global notes, one-off sessions).

Phase 1 adds a pin-file convention: a project may commit .trusty-tools/trusty-memory.yaml at its root to pin the palace slug. This survives directory renames and drive reorganisations because the slug no longer depends solely on the directory basename.

Resolution order for project_slug_at: a. Walk up to the project root. If .trusty-tools/trusty-memory.yaml exists, read palace from it (authoritative — survives renames). b. If absent, compute the slug from the directory basename (existing logic), then lazily write .trusty-tools/trusty-memory.yaml so all future resolutions are stable. The lazy write is best-effort and non-fatal (read-only trees are tolerated; failures are logged to stderr).

What: project_slug_at implements the resolution order above. Helpers read_project_pin, write_project_pin, and project_slug_from_basename are split out so each can be tested independently and called by the trusty-memory link backfill command. Test: project_slug_finds_git_root, project_slug_returns_none_without_markers, project_slug_uses_first_ancestor_marker, project_slug_personal_always_allowed, pin_file_read_when_present, absent_pin_writes_computed_slug, renamed_dir_with_pin_resolves_to_original_slug, trusty_tools_dir_is_project_marker, lazy_write_non_fatal_on_readonly_dir.

Structs

ProjectPin

Serialisable schema for .trusty-tools/trusty-memory.yaml.

Constants

PERSONAL_PALACE

Sentinel palace name that is always valid regardless of project context.

PIN_FILE_REL

Relative path of the pin file within a project root.

PIN_SCHEMA_VERSION

Schema version for .trusty-tools/trusty-memory.yaml.

PROJECT_MARKERS

File names that mark a directory as a project root.

TRUSTY_TOOLS_DIR

The .trusty-tools/ directory name (used as a project marker).

Functions

find_project_root

Walk upward from start and return the first ancestor directory (inclusive) that contains at least one project marker.

project_slug

Derive a palace slug for the current working directory.

project_slug_at

Derive a palace slug from the project root found at or above start.

project_slug_from_basename

Compute the palace slug purely from the directory basename (the pre-Phase-1 logic, now extracted for composability).

read_project_pin

Read the palace pin from .trusty-tools/trusty-memory.yaml at root.

validate_palace_name

Validate a proposed palace name against project-slug enforcement rules.

write_project_pin

Write a palace pin to .trusty-tools/trusty-memory.yaml at root.