docs: repair scanner contribution guidance

[steipete]

The contribution guide linked to three removed pages and a scanner-adapter heading that did not exist. Remove the redundant links, point ClawHub research to the current benchmark guide, and document the existing adapter registry, evidence, Docker, and fixture-test contracts at the advertised heading.

This repairs the documentation gap noted in #53 without changing the scanner-adoption proposal or its product decision. Independent Codex review is clean through P2. The generated docs site is validated before merge.

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

ClawSweeper review complete

ClawSweeper finished reviewing this revision. The review result is being finalized.

View the workflow run.

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed September 22, 2026, 5:31 AM ET / 09:31 UTC.

ClawSweeper review

What this changes

Repairs contribution-guide links and documents how to register, sandbox, and test built-in scanner adapters.

Merge readiness

⛔ Blocked before merge - 2 items remain

The documentation repair remains useful and is absent from the reviewed main branch. No introduced correctness or security defect was found; the related scanner-adoption proposal remains a separate decision.

Priority: P3
Reviewed head: 857069c005f3bca9146a6a55febd703e922f233e

Review scores

Measure	Result	What it means
Overall readiness	🦪 silver shellfish (2/6)	The patch is focused and source-consistent, but the applicable proof gate remains unfulfilled.
Proof confidence	🦪 silver shellfish (2/6)	Needs real behavior proof before merge: The changed surface is contributor navigation and adapter guidance, but no rendered-page or link-navigation result is supplied. Because CONTRIBUTING.md lies outside docs/, the directory-only exemption does not apply; a screenshot or short transcript showing the repaired destinations, plus the docs build result, would cover this change. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Needs proof	Needs real behavior proof before merge: The changed surface is contributor navigation and adapter guidance, but no rendered-page or link-navigation result is supplied. Because CONTRIBUTING.md lies outside docs/, the directory-only exemption does not apply; a screenshot or short transcript showing the repaired destinations, plus the docs build result, would cover this change. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
Evidence reviewed	7 items	Verified introduced scope: The pinned introduction changes only CONTRIBUTING.md and docs/scanners.md: 19 additions and 3 deletions, all prose or links. The diff check passed and the checkout remained clean. Repair remains necessary: The reviewed main contribution guide still links three removed pages and the absent adapter heading. The replacement benchmark section exists at docs/benchmarks.md:30; the docs renderer's slug function supports its proposed anchor. Guidance matches implementation: The adapter interface and default registry expose environment requirements, installation and verification commands, target support, and execution. Sandbox resolution defaults to Docker; runtime dependencies are pinned. Existing Socket tests cover malformed JSON, process failures, and secret-safe error reporting.
Findings	None	None.
Security	None	None.

How this fits together

ClawScan connects security scanners to a common CLI through registered adapters. Contributor documentation explains how adapters preserve scanner evidence, declare dependencies, and use the Docker execution boundary.

flowchart LR
  A[Scanner contributor] --> B[Contribution guide]
  B --> C[Custom profile evaluation]
  C --> D[Built-in adoption discussion]
  D --> E[Adapter registry and Docker dependencies]
  E --> F[Fixture tests and scanner documentation]

Loading

Before merge

• Add real behavior proof - Needs real behavior proof before merge: The changed surface is contributor navigation and adapter guidance, but no rendered-page or link-navigation result is supplied. Because CONTRIBUTING.md lies outside docs/, the directory-only exemption does not apply; a screenshot or short transcript showing the repaired destinations, plus the docs build result, would cover this change. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
• Complete next step (P2) - Add the docs build result and a screenshot or transcript demonstrating the repaired link destinations. Redact private details. Updating the PR body should trigger review; otherwise ask a maintainer to comment @clawsweeper re-review.

Agent review details

Security

None.

Review metrics

None.

Technical review

Best possible solution:

Keep one accurate adapter contribution section linked from the contribution guide, with custom-profile evaluation preceding built-in adoption.

Do we have a high-confidence way to reproduce the issue?

Not applicable to runtime reproduction: source inspection verifies the missing main-branch heading and obsolete contribution links.

Is this the best way to solve the issue?

Yes. Updating the existing guide and linking the existing benchmark instructions is a narrow repair that avoids a competing documentation path.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning medium; reviewed against ca811e0e73ce.

Labels

Label changes:

• add P3: This is a focused contribution-documentation repair with no runtime behavior change.
• add rating: 🦪 silver shellfish: Overall readiness is 🦪 silver shellfish; proof is 🦪 silver shellfish and patch quality is 🐚 platinum hermit.
• add status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: The changed surface is contributor navigation and adapter guidance, but no rendered-page or link-navigation result is supplied. Because CONTRIBUTING.md lies outside docs/, the directory-only exemption does not apply; a screenshot or short transcript showing the repaired destinations, plus the docs build result, would cover this change. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Label justifications:

• P3: This is a focused contribution-documentation repair with no runtime behavior change.
• rating: 🦪 silver shellfish: Overall readiness is 🦪 silver shellfish; proof is 🦪 silver shellfish and patch quality is 🐚 platinum hermit.
• status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: The changed surface is contributor navigation and adapter guidance, but no rendered-page or link-navigation result is supplied. Because CONTRIBUTING.md lies outside docs/, the directory-only exemption does not apply; a screenshot or short transcript showing the repaired destinations, plus the docs build result, would cover this change. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Evidence

What I checked:

• Verified introduced scope: The pinned introduction changes only CONTRIBUTING.md and docs/scanners.md: 19 additions and 3 deletions, all prose or links. The diff check passed and the checkout remained clean. (docs/scanners.md:26, 857069c005f3)
• Repair remains necessary: The reviewed main contribution guide still links three removed pages and the absent adapter heading. The replacement benchmark section exists at docs/benchmarks.md:30; the docs renderer's slug function supports its proposed anchor. (CONTRIBUTING.md:50, ca811e0e73ce)
• Guidance matches implementation: The adapter interface and default registry expose environment requirements, installation and verification commands, target support, and execution. Sandbox resolution defaults to Docker; runtime dependencies are pinned. Existing Socket tests cover malformed JSON, process failures, and secret-safe error reporting. (internal/runner/scanner_registry.go:200, 857069c005f3)
• Related discussion preserves adoption boundary: [Scanner]: skills-inspector — offline static analyzer for agent extensions #53 identifies the missing documentation section. Its author supplied packaging and corpus updates and explicitly supported custom-profile evaluation before bundling. This PR addresses that documentation gap without implementing or approving the requested scanner.
• Release and related-work check: The v0.1.8 scanner page proceeds directly from catalog discovery to profile configuration and lacks the new adapter section. Recent pull-request metadata revealed no merged replacement for this repair. (docs/scanners.md, 6190d96d7fc4)
• Area history and routing: Main-branch history identifies prior documentation and scanner work by Peter Steinberger and Jesse Merhi; GitHub maps these commits to steipete and jesse-merhi. Some historical blob reads and blame failed, so GitHub commit metadata and the exact documentation patch supplemented local history; no broader introduction claim is made. (docs/scanners.md:20, 84ee99ce015b)

Likely related people:

• unknown: The claimed source-line change could not be verified from bounded local history. (role: source history unknown; confidence: low)
• jesse-merhi: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)

Rank-up moves

Optional improvements that raise the rating; they are not merge blockers.

• Record the docs build result and show that the repaired contribution links reach the intended rendered sections.

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Workflow

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.