docs: align write-up report naming with the findings schema

[mariohercules]

Fixes #47.

Problem

The findings schema requires a write-up's file name to equal its directory slug, via a backreference:

"reportPath": { "type": "string", "pattern": "^findings/([a-z0-9][a-z0-9._-]*)/\\1\\.md$" }

The orchestrating skills state that convention (deep-security-scan, security-diff-scan, references/scan-artifacts.md, references/final-report.md all say findings/<slug>/<slug>.md). But vulnerability-writeup — the skill whose sub-agent actually creates the file — asked for an "appropriately-named" report and gave two different example file names, neither of which satisfies the pattern. Its sub-agent prompt template passed only Output directory: <reports-dir>/<slug>, so the constraint never reached the worker.

Checked against the plugin's own validator (finalize_scan_contract.validate_against_schema):

ACCEPT  findings/unsafe-archive-extraction/unsafe-archive-extraction.md
REJECT  findings/unsafe-archive-extraction/freebsd-shm-uaf.md
        -> findings.schema.findings[0].writeup.reportPath: string does not match schema pattern
REJECT  findings/archive/freebsd-shm-ftruncate-uaf-lpe.md
        -> findings.schema.findings[0].writeup.reportPath: string does not match schema pattern

The two rejected names are exactly the examples the guidance gave. When the worker follows them, either finalization rejects the document at seal time — after all analysis work is done — or writeup.reportPath points at a file that does not exist.

Change

State the findings/<slug>/<slug>.md rule in three places that previously contradicted it:

• skills/vulnerability-writeup/SKILL.md step 7
• skills/vulnerability-writeup/references/report-format.md
• the sub-agent prompt template, which now passes the output file, not just the directory

The original intent is preserved: the slug must stay descriptive, so report is still called out as the thing not to fall back to.

Notes

This is documentation only — no behavior change, and the schema already enforces the rule at runtime. I did not add a test: the repository has no harness for skill prose, and a text-matching assertion would be brittle without catching the real invariant.

Verified on this branch: pnpm run types, pnpm run format, pnpm run check:package all clean, and the full suite passes (717 pass, 5 skip, 0 fail).

[mldangelo-oai]

@codex review exact head 116c59e

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Another round soon, please!

Reviewed commit: 116c59e2cd

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Security review completed. No security issues were found in this pull request.

Reviewed commit: 116c59e2cd

View security finding report

Only the user who started this review can view the report in Codex.

ℹ️ About Codex security reviews in GitHub

This is an experimental Codex feature. Security reviews are triggered when:

• You comment "@codex security review"
• A regular code review gets triggered (for example, "@codex review" or when a PR is opened), and you’re opted in so security review runs alongside code review

Once complete, Codex will leave suggestions, or a comment if no findings are found.