Add stack-agnostic tool acquisition guidance

.specify/feature.json

@@ -1,3 +1,3 @@
 {
-  "feature_directory": "docs/specs/082-syft-sharded-sbom-plan"
+  "feature_directory": "docs/specs/083-tool-acquisition-guidance"
 }

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/082-syft-sharded-sbom-plan/plan.md`
+`docs/specs/083-tool-acquisition-guidance/plan.md`
 <!-- SPECKIT END -->

docs/product-backlog.md

@@ -164,6 +164,7 @@ fixtures are preflight evidence only.
 | P6-080 | `docs/specs/080-clean-start-artifact-guard/` | Context packs and acceptance guidance make the current artifact boundary explicit so Cursor/agent stress lanes do not mix stale `.portolan/stress`, root-level `run`, or unrelated generated outputs into clean-start evidence. | Ready-for-review PR #58; post-Cursor local baseline, fresh Bigtop context smoke, final Cursor Composer 2.5 clean-start stress, and three final assessed non-GPT review lanes verified; merge approval `not_assessed` |
 | 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. | Ready-for-review PR #59; local baseline, fresh Bigtop context smoke, Cursor Composer 2.5 stress, three assessed non-GPT review lanes, and GitHub checks verified. Maven execution, dependency evidence, JVM relationship claims, GitHub review approval, and merge 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. | Ready-for-review PR #60; local baseline, fresh Bigtop context smoke, Cursor Composer 2.5 stress, three assessed non-GPT review lanes, and GitHub checks verified. Syft execution, component inventory, dependency evidence, GitHub review approval, and merge 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. | Ready-for-review 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, and GitHub checks verified. Native producer execution, tool install/acquisition, component inventory, dependency relationships, duplication metrics, runtime topology, GitHub review approval, and merge approval remain `not_assessed` |
 
 ## Backlog Rules
 

docs/specs/083-tool-acquisition-guidance/plan.md

@@ -0,0 +1,54 @@
+# Implementation Plan: Tool Acquisition Guidance
+
+**Branch**: `codex/083-tool-acquisition-guidance`
+
+**Date**: 2026-06-02
+
+**Spec**: `docs/specs/083-tool-acquisition-guidance/spec.md`
+
+## Summary
+
+Clarify the producer-planning surface so Portolan stays stack-agnostic while
+still telling agents which local tools to pull in for missing evidence families.
+The slice adds generic acquisition/risk guidance around existing OSS tool plans;
+it does not add a new scanner, install tools, run native producers, or create a
+language-specific adapter.
+
+## Decision Gate
+
+- **Simpler/Faster**: Leave the existing `oss-plan.json` text as-is. Rejected
+  because Cursor and operator discussion showed the guidance can be misread as
+  incremental stack-specific adapter work.
+- **Blocking Edge Cases**: External tools can install packages, hit networks,
+  write caches, mutate targets, or expose private dependency coordinates.
+  Therefore acquisition guidance is descriptive and approval-gated; no native
+  command is run by Portolan.
+- **Existing Open Source**: Continue composing mature OSS/native producer tools
+  such as Syft, CycloneDX plugins, jscpd, and Semgrep. Portolan owns the
+  evidence contract and normalization boundary, not their scanner logic.
+
+## Technical Context
+
+**Language/Version**: Go.
+
+**Primary Dependencies**: Standard library only. No new dependency.
+
+**Storage**: Local context artifacts and SpecKit docs.
+
+**Testing**: Focused `internal/contextprep` test, then full baseline.
+
+**Constraints**: Local-first/read-only defaults. No installs, network access,
+producer execution, daemon behavior, credentials, or target mutation.
+
+## Verification
+
+```bash
+go test ./internal/contextprep
+go test ./...
+go vet ./...
+jq empty schema/*.json
+git diff --check
+```
+
+Fresh Bigtop smoke and Cursor Composer 2.5 stress must use a clean context path
+and must not run native producers.

docs/specs/083-tool-acquisition-guidance/research.md

@@ -0,0 +1,25 @@
+# Research: Tool Acquisition Guidance
+
+## Decision: Generic acquisition guidance over per-stack adapters
+
+- **Decision**: Keep producer planning organized by evidence family and local
+  tool candidate, not by programming-language adapter.
+- **Rationale**: The operator needs practical next actions such as "pull in a
+  local SBOM producer" or "run a duplication tool", but Portolan must not become
+  a JVM/PHP/Gradle scanner.
+- **Rejected alternative**: Add a Gradle-specific slice after integrated stress.
+  Rejected because it turns a residual tool gap into stack ownership.
+
+## OSS posture
+
+- Mature OSS/native tools remain the right acquisition targets when they
+  produce local files that Portolan can normalize.
+- Tool recommendations are options, not evidence.
+- Missing or unrun candidate tools remain `not_assessed`.
+
+## Risk posture
+
+- Tool acquisition can involve network access, cache writes, project mutation,
+  dependency coordinate exposure, or runtime side effects.
+- Portolan must surface those risks before suggesting any command as a next
+  action.

docs/specs/083-tool-acquisition-guidance/reviews/bigtop-context-and-cursor-stress-2026-06-02.md

@@ -0,0 +1,69 @@
+# Bigtop Context Smoke And Cursor Stress
+
+Date: 2026-06-02
+
+Spec: `docs/specs/083-tool-acquisition-guidance/`
+
+## Fresh Context Smoke
+
+Command:
+
+```bash
+go run ./cmd/portolan context prepare \
+  --root /home/fall_out_bug/projects/bigtop-landscape \
+  --out /home/fall_out_bug/projects/bigtop-landscape/.portolan/stress/20260602-083-tool-acquisition-guidance/context \
+  --profile cursor \
+  --force
+```
+
+verified:
+
+- Context pack was written under:
+  `/home/fall_out_bug/projects/bigtop-landscape/.portolan/stress/20260602-083-tool-acquisition-guidance/context`
+- `context/tool-outputs` is absent; no native producer was executed.
+- JSON validation passed for `repos.json`, `tool-registry.json`,
+  `oss-plan.json`, and `gaps.jsonl`.
+- Selected tool acquisition states:
+  - `cyclonedx`: installed / `not_assessed`
+  - `jscpd`: installed / `not_assessed`
+  - `maven-cyclonedx`: installed / `not_assessed`
+  - `gradle-cyclonedx`: installed but requires local evaluation /
+    `not_assessed`
+
+not_assessed:
+
+- Actual Syft, jscpd, Maven, Gradle, Semgrep, Docker, or producer execution.
+- Actual producer output validity.
+- Component inventory, dependency relationships, duplication metrics, and
+  runtime topology.
+
+## Cursor Composer 2.5 Stress
+
+Command:
+
+```bash
+cursor-agent --print --mode ask --model composer-2.5 --trust "$(cat docs/specs/083-tool-acquisition-guidance/stress/cursor-tool-acquisition-prompt-2026-06-02.md)"
+```
+
+verified:
+
+- `forbidden_read: false`
+- `artifacts_read_count: 8`
+- `acquisition_guidance_present: true`
+- `acquisition_tool_count: 5`
+- `stack_specific_adapter_requested: false`
+- `candidate_tools_as_evidence: false`
+- `installed_tools_claimed_as_supported_evidence: false`
+- `approval_boundary_present: true`
+- `risks_named: true`
+- `evidence_until_output: not_assessed`
+- `component_dependency_claimable: false`
+- `runtime_topology_claimable: false`
+- `verdict: pass`
+
+disposition:
+
+- Accepted as a passing stress lane for the tool acquisition guidance
+  correction.
+- Residual clean-start producer-run handling is owned by pending PR #58 and was
+  already verified in the integrated PR #57-#60 scratch stress.

docs/specs/083-tool-acquisition-guidance/reviews/pr-readiness-closeout-2026-06-02.md

@@ -0,0 +1,91 @@
+# PR Readiness Closeout
+
+Date: 2026-06-02
+
+Spec: `docs/specs/083-tool-acquisition-guidance/`
+
+PR: https://github.com/fcon-tech/portolan/pull/61
+
+Branch: `codex/083-tool-acquisition-guidance`
+
+Head at PR creation: `da2b2072b1c7decdc7954327d8f0a29b3bc4fbe6`
+
+## Implementation State
+
+verified:
+
+- `oss-plan.json` tool plans include stack-agnostic acquisition guidance.
+- Candidate tools are represented as native producer options, not
+  Portolan-owned stack adapters.
+- Tool availability remains separate from evidence.
+- `evidence_until_output` remains `not_assessed` until local output is produced
+  and re-ingested.
+- Answer and query guidance reject defaulting to PHP/JVM/Scala/Gradle adapter
+  requests.
+
+not_assessed:
+
+- Actual native producer execution.
+- Actual tool install/acquisition.
+- Component inventory, dependency relationships, duplication metrics, and
+  runtime topology.
+
+## Local Verification
+
+verified:
+
+- `go test ./internal/contextprep`
+- `go test ./...`
+- `go vet ./...`
+- `jq empty schema/*.json`
+- `git diff --check`
+- Fresh Bigtop context smoke.
+- Cursor Agent `composer-2.5` bounded tool-acquisition stress.
+
+## Review Evidence
+
+verified:
+
+- Requirements/product-vision drift review recorded.
+- Cursor Composer 2.5 stress recorded.
+- Three assessed non-GPT review lanes recorded:
+  - `openrouter/moonshotai/kimi-k2.6`
+  - `openrouter/deepseek/deepseek-v4-pro`
+  - `openrouter/qwen/qwen3-coder`
+- Degraded MiMo/MiniMax attempts recorded as non-counting evidence.
+
+## PR State
+
+verified at PR creation:
+
+- PR #61 exists.
+- PR is open.
+- PR is not draft.
+- PR head branch is `codex/083-tool-acquisition-guidance`.
+
+not_assessed at PR creation:
+
+- GitHub checks were queued.
+- GitHub review approval absent/not_assessed.
+- Ready-to-merge approval absent/not_assessed.
+
+verified after current-head refresh:
+
+- Current PR head: `bd6e15fad6981b15c14975e59a828c1f364da5f3`
+- PR is open and not draft.
+- `mergeStateStatus=CLEAN`.
+- Current GitHub checks: all reported checks completed successfully.
+- Integrated PR #57-#61 stack-agnostic stress is recorded under
+  `docs/specs/083-tool-acquisition-guidance/reviews/integrated-stack-agnostic-navigation-stress-2026-06-02.md`
+  on the scratch integration branch.
+
+## Readiness
+
+- Ready-for-review PR: yes.
+- Ready-to-merge PR: no.
+
+Stop reason:
+
+- PR is ready for review.
+- Do not merge without explicit user approval and current merge-state/check
+  verification.

docs/specs/083-tool-acquisition-guidance/reviews/requirements-product-vision-drift-2026-06-02.md

@@ -0,0 +1,42 @@
+# Requirements And Product-Vision Drift Review
+
+Date: 2026-06-02
+
+Spec: `docs/specs/083-tool-acquisition-guidance/`
+
+## Inputs
+
+- Integrated Cursor Composer 2.5 stress for PR #57-#60.
+- User correction: Portolan must be stack-agnostic, but should help pull in the
+  right tools.
+- Portolan product boundary in `AGENTS.md`.
+- Constitution local-first, evidence-state, and OSS-composition principles.
+
+## Drift Assessment
+
+Requirements:
+
+- Aligned. The slice improves the navigation surface for missing evidence
+  families without adding a stack-specific scanner or adapter.
+
+Product boundary:
+
+- Aligned. Portolan remains a read-only local discovery substrate and
+  normalizer for local producer evidence.
+- The slice explicitly rejects defaulting to PHP/JVM/Gradle adapters.
+- Tool candidates remain options for local acquisition, not observed evidence.
+
+Evidence semantics:
+
+- Aligned. Candidate tools, install suggestions, and approval-gated commands
+  remain `not_assessed` until local output exists and is re-ingested.
+
+Open-source posture:
+
+- Aligned. Mature OSS/native producer tools stay outside Portolan ownership;
+  Portolan documents how to acquire and normalize their outputs safely.
+
+Decision:
+
+- Proceed with a focused context guidance correction.
+- Do not create a Gradle-specific implementation slice.