com.blockether.vis.internal.agents — com.blockether/vis 0.1.2

Project-guidance discovery — internal, no extension required.

STACKED context files, pi-style: guidance is collected from THREE layers and all of them ride into the PROJECT-INSTRUCTIONS system block, outermost first:

1. user-global ~/.vis/AGENTS.md (or ~/.vis/CLAUDE.md)
2. ancestors AGENTS.md / CLAUDE.md in every ancestor directory of the workspace root (outermost first)
3. workspace AGENTS.md / CLAUDE.md at the workspace root
4. added roots AGENTS.md / CLAUDE.md at each ADDED filesystem root's own directory (folders granted beyond the primary workspace — no ancestor walk)

Per DIRECTORY precedence is strict: AGENTS.md wins; CLAUDE.md is only consulted when AGENTS.md is absent in that directory. Across directories nothing is dropped — nearer files are rendered LATER so they positionally override outer rules on conflict.

Size policy: NO truncation. Every file goes into the system prompt verbatim. Provider prompt caching amortizes the cost across every iter in the session; trimming would risk dropping the very rule the user is testing. The cwd + per-file (path, mtime, length) marker cache below ensures files are re-read at most once per change.

Failure modes (file unreadable, permissions, I/O error) land in the read-warning vec, NOT in the rendered prompt. The model isn't bound by rules it can't see, but the host knows something is broken.

This namespace replaces the foundation-core/environment/agents.clj that used to live in the extension. Project-guidance discovery is core functionality (drives the system prompt + slim ctx digest); the extension layer no longer owns it.

current clj

(current)

Return the cached scan, recomputing when cwd or any stacked AGENTS.md/CLAUDE.md marker changes. Common path is stat-only — content is re-read only when a marker changes.

instructions clj

(instructions)

Return the structured map behind (vis/main-agent-instructions). Always a map. :found? discriminates present vs absent.

present: {:found? true :files [{:scope :source :path :bytes :content} …] :source <legacy kw> :path "…" :bytes N :content "…"} absent: {:found? false}

:files is the stacked view (user-global → ancestors → workspace root, outermost first). The top-level :source/:path describe the INNERMOST file and :content is the combined origin-headed render — the legacy single-file consumers keep working unchanged.

No truncation: every :content is the full file verbatim. Caller-side display limits (e.g. tape pretty-printing) are caller business.

origin-label clj

(origin-label {:keys [scope source]})

Human label for a stacked-file entry: file name + scope qualifier.

read-warnings clj

(read-warnings)

Vec of warning maps for AGENTS.md / CLAUDE.md read failures. Empty when no file is present at all (absence isn't a warning) or when every present file read cleanly.

reload! clj

(reload!)

Revalidate project guidance and return the current scan result.

scan clj

(scan)

Scan the user-global ~/.vis dir, the active workspace root's ancestor chain, and each added filesystem root's own directory for project-guidance files (stacked).

scan-in clj

(scan-in root)

Scan root for project-guidance files. Pure I/O. Single-directory, legacy result shape (:source :repo / :repo:claude-md-fallback); the stacked multi-file scan is scan-roots / scan. Exposed for testing against fixture roots.

scan-roots clj

(scan-roots global-dir workspace-root)

(scan-roots global-dir workspace-root extra-roots)

Stacked scan: guidance file in global-dir first (when non-nil), then AGENTS.md / CLAUDE.md from every ancestor of workspace-root (outermost first) down to the workspace root itself, then each added extra-root's OWN directory (no ancestor walk — only what the user granted). Pure I/O; exposed for testing against fixture roots.

Precedence is render order: user-global → ancestors → workspace root → added roots. Nearer files land LATER and positionally override outer rules, so the primary workspace stays authoritative over any added folder. An extra-root whose guidance file coincides with an already-seen path (the workspace root, an ancestor, or a duplicate) is dropped.

Returns {:result r :warnings [...]} where r is:

present: {:found? true :files [{:scope :global|:ancestor|:project|:extra-root :source :agents-md|:claude-md :path "…" :bytes N :content "…"} …] ;; legacy single-file view (innermost file + combined content) :source <legacy kw> :path "…" :bytes <total> :content "…"} absent: {:found? false}