Implement external tool evaluation profiles

AGENTS.md

@@ -202,5 +202,5 @@ go run ./cmd/portolan scan --help
 <!-- SPECKIT START -->
 For additional context about technologies to be used, project structure,
 shell commands, and other important information, read the current plan:
-`docs/specs/083-tool-acquisition-guidance/plan.md`
+`docs/specs/084-external-tool-evaluation-profiles/plan.md`
 <!-- SPECKIT END -->

docs/adapter-contracts/external-tool-evaluation-profiles.md

@@ -0,0 +1,140 @@
+# External Tool Evaluation Profiles
+
+Last refreshed: 2026-06-05
+
+These profiles record adoption decisions for external code-understanding tools.
+They are planning and guidance artifacts, not Portolan evidence graph facts.
+
+## Decision Summary
+
+| Project | Role | Fit | Recommended Portolan Action |
+| --- | --- | --- | --- |
+| `defendend/Claude-ast-index-search` | `producer_candidate` | Strongest current symbol/reference producer candidate. | Plan future import of explicitly supplied local ast-index output in spec 085; do not install or run it by default. |
+| `colbymchenry/codegraph` | `producer_candidate` | Useful but lower-fit optional candidate because default workflows can write target-local state and include install/watch/MCP behavior. | Keep as optional evaluation profile; require approval and output-boundary review before any use. |
+| `Lum1104/Understand-Anything` | `ux_pattern_source` | Useful navigation and teaching patterns, but LLM-authored graph output is not verified Portolan evidence. | Borrow UX patterns only through spec 086; reject graph claims as evidence unless a future deterministic local output path is proven. |
+
+Profile role labels are product-facing guidance only. Machine-readable producer
+evidence continues to use the existing producer-family `Decision` and
+`SupportState` records until a future spec changes that contract.
+
+## Role Mapping Boundary
+
+| Profile Role | Producer-Family Decision | Producer-Family Support State | Required Follow-Up |
+| --- | --- | --- | --- |
+| `producer_candidate` | `not_assessed` until local evaluation exists | `candidate_only` | Keep as guidance; open a future importer/evaluation spec before support is claimed. |
+| `ux_pattern_source` | `not_assessed` for evidence production | `candidate_only` or `rejected` for evidence use | Route useful interaction ideas to a UX/navigation spec; do not emit producer evidence. |
+| `ready_for_import_planning` | `narrowed` only after a local output contract is reviewed | `narrowed` | Open or update an importer spec and validate explicit local output. |
+| `blocked` | `blocked` | `blocked` | Record blocker and required approval or redesign before any execution/import work. |
+| `rejected` | `rejected` | `rejected` | Record why it cannot satisfy Portolan evidence boundaries; do not recommend as producer evidence. |
+
+## Common Rules
+
+- Profiles do not create graph facts.
+- Profiles do not promote symbol/reference/call/runtime evidence to
+  `source-visible`, `metadata-visible`, or `runtime-visible`.
+- Candidate tools remain `not_assessed` until explicit local output exists and
+  a Portolan importer or producer-evaluation record covers it.
+- Network download, tool install, target mutation, hook install, MCP install,
+  watcher startup, daemon startup, and global configuration writes require
+  explicit human or spec-level approval.
+- LLM-authored summaries, dashboards, and architecture graphs are claims until a
+  future spec proves deterministic, locally supplied, evidence-bounded output.
+- Refresh public metadata before depending on a profile if more than one day has
+  passed since `Last refreshed`.
+
+## Profile: ast-index
+
+- Project identity: `defendend/Claude-ast-index-search`
+- URL: https://github.com/defendend/Claude-ast-index-search
+- License: MIT observed by GitHub API on 2026-06-05.
+- Maintenance snapshot: default branch `main`, pushed at
+  2026-06-03T14:46:59Z, 415 stars, 32 forks.
+- Role: `producer_candidate`.
+- Relevant output surfaces: local index/search CLI, SQLite/cache-style index,
+  JSON CLI surfaces, name/string-based reference and caller-style outputs.
+- Local execution posture: may create local index/cache output; optional
+  watcher, hook, or MCP installation commands require approval.
+- Target mutation risk: unknown until exact command and output path are
+  reviewed; treat any target-local cache/write as approval-gated.
+- Network/install risk: package acquisition or repository clone requires
+  approval.
+- Daemon/watch risk: watcher or MCP behavior is not approved by this slice.
+- Privacy risk: index/cache/search output may include source paths, symbols,
+  snippets, or customer-sensitive identifiers.
+- Integration cost: medium; future importer spec must validate exact output
+  format and map name/string references without treating them as complete call
+  graphs.
+- Approval boundary: do not install, run, watch, hook, or start MCP behavior
+  without explicit approval and a selected output directory.
+- Recommended Portolan action: strongest current candidate for future
+  symbol/reference import planning in `docs/specs/085-ast-index-producer-import/`.
+- Evidence limitations: no ast-index output is supplied in this slice; symbol,
+  reference, caller, and call-graph evidence remain `not_assessed`.
+
+## Profile: CodeGraph
+
+- Project identity: `colbymchenry/codegraph`
+- URL: https://github.com/colbymchenry/codegraph
+- License: MIT observed by GitHub API on 2026-06-05.
+- Maintenance snapshot: default branch `main`, pushed at
+  2026-06-05T04:54:11Z, 41920 stars, 2584 forks.
+- Role: `producer_candidate`.
+- Relevant output surfaces: local code knowledge graph, agent-facing query
+  surfaces, installable CLI/runtime, possible MCP/watch workflows.
+- Local execution posture: useful local graph workflow, but default usage can
+  write `.codegraph/` in the target and may involve install, watch, or MCP
+  behavior.
+- Target mutation risk: target-local `.codegraph/` writes are incompatible with
+  Portolan defaults unless explicitly approved or redirected outside the target.
+- Network/install risk: install scripts or package downloads require approval.
+- Daemon/watch risk: watch/MCP behavior is not approved by this slice.
+- Privacy risk: graph/index output may include source paths, symbols, labels,
+  prompts, or summaries that should not be committed as fixtures.
+- Integration cost: medium to high; future work must prove deterministic output
+  shape and evidence-state mapping before import.
+- Approval boundary: do not install, run, write `.codegraph/`, watch, or start
+  MCP behavior without explicit approval and an output isolation plan.
+- Recommended Portolan action: keep as lower-fit optional producer candidate;
+  prefer ast-index for near-term symbol/reference import planning.
+- Evidence limitations: no CodeGraph output is supplied in this slice; graph,
+  relationship, and architecture claims remain `not_assessed`.
+
+## Profile: Understand-Anything
+
+- Project identity: `Lum1104/Understand-Anything`
+- URL: https://github.com/Lum1104/Understand-Anything
+- License: MIT observed by GitHub API on 2026-06-05.
+- Maintenance snapshot: default branch `main`, pushed at
+  2026-06-04T05:46:14Z, 52578 stars, 4315 forks.
+- Role: `ux_pattern_source`.
+- Relevant output surfaces: interactive knowledge graph, search/tour patterns,
+  agent/plugin guidance, LLM-authored graph and architecture explanations.
+- Local execution posture: plugin/agent workflow may install assets, write
+  generated graph outputs, and depend on LLM-authored processing.
+- Target mutation risk: generated graph or plugin state must be reviewed before
+  any target-local writes are allowed.
+- Network/install risk: marketplace or package installation requires approval.
+- Daemon/watch risk: any background or plugin runtime is not approved by this
+  slice.
+- Privacy risk: generated knowledge graphs and summaries may contain source
+  snippets, file paths, prompts, or architecture claims.
+- Integration cost: high for evidence; lower for UX pattern inspiration.
+- Approval boundary: do not install, run, or treat generated graph output as
+  evidence without a future deterministic-output spec.
+- Recommended Portolan action: borrow navigation UX ideas only in
+  `docs/specs/086-evidence-navigation-ux-patterns/`.
+- Evidence limitations: LLM-authored graph content is not Portolan evidence;
+  all symbol/reference/architecture claims remain `not_assessed`.
+
+## Refresh Procedure
+
+1. Re-check project identity, license, default branch, and latest pushed date.
+2. Review install, output, watcher, hook, MCP, daemon, and target-write behavior.
+3. Update only the affected profile section and `Last refreshed` date.
+4. If a tool moves from guidance to import planning, create or update a future
+   SpecKit slice and map the decision to producer-family `Decision` and
+   `SupportState` records.
+5. Use `schema/producer-family.schema.json` and the producer-family precedent in
+   `docs/specs/053-language-agnostic-producers/` before emitting or changing any
+   machine-readable producer-family record.
+6. Keep unrelated profiles unchanged unless their metadata was refreshed too.

docs/product-backlog.md

@@ -165,7 +165,7 @@ fixtures are preflight evidence only.
 | P6-081 | `docs/specs/081-maven-sharded-producer-plan/` | Context packs emit repository-sharded Maven/CycloneDX next actions for multi-repo JVM landscapes so agents do not treat one sample `pom.xml` as a landscape rollout plan. | Merged via PR #59; local baseline, fresh Bigtop context smoke, Cursor Composer 2.5 stress, three assessed non-GPT review lanes, GitHub checks, explicit user merge approval, squash merge `a89a965`, and remote branch cleanup verified. Maven execution, dependency evidence, JVM relationship claims, and GitHub review approval remain `not_assessed` |
 | P6-082 | `docs/specs/082-syft-sharded-sbom-plan/` | Context packs emit repository-sharded Syft/CycloneDX SBOM next actions for multi-repo landscapes so component/dependency evidence can be acquired incrementally without full-root SBOM scans. | Merged via PR #60; local baseline, fresh Bigtop context smoke, Cursor Composer 2.5 stress, three assessed non-GPT review lanes, GitHub checks, explicit user merge approval, squash merge `9390379`, and remote branch cleanup verified. Syft execution, component inventory, dependency evidence, and GitHub review approval remain `not_assessed` |
 | P6-083 | `docs/specs/083-tool-acquisition-guidance/` | Context packs make tool acquisition guidance explicit and stack-agnostic: agents can pull in the right local producer tools without treating Portolan as a PHP/JVM/Gradle adapter stack. | Merged via PR #61; local baseline, fresh Bigtop context smoke, Cursor Composer 2.5 stress, integrated PR #57-#61 stack-agnostic stress, three assessed non-GPT review lanes, GitHub checks, explicit user merge approval, squash merge `847e84e`, post-merge Bigtop context smoke, and remote branch cleanup verified. Native producer execution, tool install/acquisition, component inventory, dependency relationships, duplication metrics, runtime topology, and GitHub review approval remain `not_assessed` |
-| P6-084 | `docs/specs/084-external-tool-evaluation-profiles/` | Portolan keeps dated evaluation profiles for CodeGraph, Understand-Anything, and ast-index so external tool adoption stays explicit, evidence-honest, and refreshable. | Draft spec; backlog-only. No plan/tasks yet. External tool metadata, profile implementation, and generated guidance remain `not_assessed` until planning and verification refresh the 2026-06-04 review snapshot |
+| P6-084 | `docs/specs/084-external-tool-evaluation-profiles/` | Portolan keeps dated evaluation profiles for CodeGraph, Understand-Anything, and ast-index so external tool adoption stays explicit, evidence-honest, and refreshable. | Implemented locally; baseline, context smoke, and story review cycles verified. PR review, GitHub checks, real external tool execution/output, and merge approval remain `not_assessed` |
 | P6-085 | `docs/specs/085-ast-index-producer-import/` | Explicit local ast-index outputs can be imported as bounded symbol/reference/module producer evidence without Portolan installing, executing, watching, or mutating targets. | Draft spec; backlog-only. No plan/tasks yet. ast-index execution, real output acquisition, importer implementation, CodeGraph import, and call-graph parity remain `not_assessed` |
 | P6-086 | `docs/specs/086-evidence-navigation-ux-patterns/` | Useful navigation ideas from Understand-Anything, CodeGraph, and ast-index are adopted as evidence-backed guide patterns without accepting LLM-authored graphs or live dashboards as truth. | Draft spec; backlog-only. No plan/tasks yet. UX implementation, dashboard/MCP surfaces, LLM workflows, and agent acceptance impact remain `not_assessed` |
 

docs/specs/084-external-tool-evaluation-profiles/contracts/external-tool-profile.md

@@ -0,0 +1,41 @@
+# Contract: External Tool Evaluation Profile
+
+External tool profiles are committed planning artifacts, not graph evidence.
+Their product-facing role labels are companion guidance only; they do not
+replace existing machine-readable producer-family `Decision` or `SupportState`
+records.
+
+## Required Sections
+
+- Project identity.
+- Last refreshed date.
+- Role classification.
+- Observed license and maintenance snapshot.
+- Useful output surfaces.
+- Local execution posture.
+- Target mutation, network/install, daemon/watch, and privacy risks.
+- Approval boundary.
+- Recommended Portolan action.
+- Evidence limitations.
+
+## Evidence Rules
+
+- A profile may recommend a local producer candidate.
+- A profile must not create graph facts.
+- A profile must not create a parallel machine-readable producer decision
+  scheme; future importer specs must map profile decisions to the existing
+  producer-family record contract.
+- Role mapping must follow
+  `docs/adapter-contracts/external-tool-evaluation-profiles.md` and
+  `schema/producer-family.schema.json`.
+- A profile must not promote symbol/reference/call/runtime evidence to
+  `source-visible`, `metadata-visible`, or `runtime-visible`.
+- A profile must preserve stale upstream metadata as stale until refreshed.
+
+## Safety Rules
+
+- Network download, tool install, target mutation, hook install, MCP install,
+  watcher startup, daemon startup, and global configuration writes require
+  explicit human or spec-level approval.
+- LLM-authored summaries and dashboards are not evidence unless a future spec
+  proves deterministic, locally supplied, evidence-bounded output.

docs/specs/084-external-tool-evaluation-profiles/data-model.md

@@ -0,0 +1,59 @@
+# Data Model: External Tool Evaluation Profiles
+
+## Tool Evaluation Profile
+
+Fields:
+
+- `project_identity`: canonical repository owner/name and URL.
+- `last_refreshed`: date when public metadata was checked.
+- `license`: observed SPDX license from the refresh snapshot.
+- `role`: one of `producer_candidate`, `ux_pattern_source`,
+  `ready_for_import_planning`, `blocked`, or `rejected`.
+- `fit`: short product-fit rationale.
+- `output_surfaces`: deterministic local outputs, indexes, graph files,
+  dashboards, MCP surfaces, or LLM-authored summaries identified by review.
+- `local_execution_posture`: whether use is read-only, writes caches, writes in
+  target, installs tools, starts watchers, or starts daemon/MCP behavior.
+- `risks`: target mutation, network/install, daemon/watch, privacy, schema
+  stability, and evidence-state risks.
+- `approval_boundary`: action that requires human or future-spec approval.
+- `recommended_portolan_action`: current adoption decision and next step.
+- `evidence_limitations`: what remains `not_assessed`, `unknown`, or
+  `cannot_verify`.
+
+Validation rules:
+
+- Every profile must include `last_refreshed`.
+- The profile `role` is product-facing guidance only. Machine-readable producer
+  evidence must continue to use existing producer-family decision/support-state
+  records until a future spec changes that contract.
+- Every execution, install, watcher, daemon, hook, MCP, or target-mutation path
+  must be approval-gated.
+- Profiles must not state that candidate output is observed Portolan evidence
+  until a local output/import path exists.
+
+## Candidate Role
+
+Allowed states:
+
+- `producer_candidate`: may be a useful local producer after approval and output
+  review.
+- `ux_pattern_source`: useful design/reference input, not a verified evidence
+  producer.
+- `ready_for_import_planning`: deterministic output is promising enough for a
+  future importer spec.
+- `blocked`: current behavior blocks safe adoption without redesign or
+  approval.
+- `rejected`: incompatible with Portolan's evidence boundary.
+
+## Approval Boundary
+
+An approval boundary records the exact class of action that Portolan does not
+take by default:
+
+- network download or package installation;
+- target repository mutation or cache write;
+- global agent/editor configuration write;
+- hook installation;
+- watcher, daemon, server, or MCP startup;
+- LLM-authored graph or summary use as evidence.