Vero Discover

# discovery: {source_path}

Source: `{source_path}` ({N} lines)
Language: {Dafny | Verus | Coq}
Module: {module_name}

## Types
- [ ] category=type `TypeName` — {kind}, {N constructors/fields} — maps to: `{inductive|structure|abbrev}`
  - Visibility: {public|internal|private}
  - Dependencies: {list or "none"}
  - Notes: {considerations, deriving suggestions}

## Functions
- [ ] category={api|api_helper|spec_helper} `funcName(args)` → {ReturnType} — maps to: `def`
  - Visibility: {public|internal|private}
  - Dependencies: [{list}]
  - Reason: {one line — which heuristics drove the category suggestion}
  - Notes: {annotations, ensures clauses, requires clauses}

## Predicates
- [ ] category=spec_helper `predName(args)` — maps to: `def ... : {Bool|Prop}`
  - Visibility: {public|internal|private}
  - Dependencies: [{list}]
  - Notes: {what it checks}

## Theorems / Lemmas
- [ ] category={spec|spec_helper|skip} `theoremName` — maps to: `def spec_<…> (impl : RepoImpl) : Prop`
  - Visibility: {public|internal|private}
  - Dependencies: [{list}]
  - Hypothesis: {preconditions / requires}
  - Conclusion: {postcondition / ensures}
  - Reason: {one line — why this category}

## Tests
- [ ] category=test `testName` — maps to: `#guard` block
  - Values: {input/output pairs or assertion checks}

## External Boundaries
- [ ] category=api_helper `boundaryName` — maps to: `opaque`
  - Properties proved in source: {list → become axioms in Lean}

## Notes
[Human adds review notes here]

{
  "source_language": "dafny",
  "source_dir": "/path/to/source",
  "commit_hash": "abc123",
  "repo_url": "https://github.com/...",
  "items": [
    {
      "name": "Stack",
      "qualified_name": "Stack",
      "suggested_category": "type",
      "visibility": "public",
      "source_file": "Stack.dfy",
      "source_line": 3,
      "signature_summary": "datatype Stack<T> = Empty | Cons(top: T, rest: Stack<T>)",
      "dependencies": [],
      "reason": "datatype declaration; always curator-given",
      "notes": "Generic binary stack, 2 constructors"
    },
    {
      "name": "push",
      "qualified_name": "push",
      "suggested_category": "api",
      "visibility": "public",
      "source_file": "Stack.dfy",
      "source_line": 8,
      "signature_summary": "function method push<T>(s: Stack<T>, v: T) : Stack<T>",
      "dependencies": ["Stack"],
      "reason": "user-facing library entry; has ensures clauses in source",
      "notes": ""
    },
    {
      "name": "toSeq",
      "qualified_name": "toSeq",
      "suggested_category": "spec_helper",
      "visibility": "internal",
      "source_file": "Stack.dfy",
      "source_line": 22,
      "signature_summary": "ghost function toSeq<T>(s: Stack<T>) : seq<T>",
      "dependencies": ["Stack"],
      "reason": "ghost function used only in ensures clauses of other fns; referenced by bare name in specs",
      "notes": ""
    },
    {
      "name": "push_pop_roundtrip",
      "qualified_name": "push_pop_roundtrip",
      "suggested_category": "spec",
      "visibility": "public",
      "source_file": "StackSpec.dfy",
      "source_line": 5,
      "signature_summary": "lemma push_pop_roundtrip<T>(s: Stack<T>, v: T) ensures pop(push(s, v)) == s",
      "dependencies": ["Stack", "push", "pop"],
      "reason": "characterizing lemma about push/pop; becomes def spec_* proof obligation",
      "notes": "Round-trip property"
    }
  ],
  "file_summaries": {
    "Stack.dfy": {"lines": 50, "types": 1, "functions": 5, "theorems": 0},
    "StackSpec.dfy": {"lines": 40, "types": 0, "functions": 0, "theorems": 4}
  }
}

# API Catalog: {project_name}

Source: {repo_url} ({commit_hash})
Language: {language}
Total lines: {N}

## Architecture

{ASCII dependency graph of modules}

## Summary

| File | Types | Spec Fns | Exec Fns | Predicates | Theorems | Axioms | Tests |
|------|------:|--------:|---------:|----------:|---------:|-------:|------:|
| ... | ... | ... | ... | ... | ... | ... | ... |
| **Total** | **N** | **N** | **N** | **N** | **N** | **N** | **N** |

## Per-File Catalogs

[Links to each curation/discovery/{path}.md]

1. Detect language (scan extensions + grep for markers)
2. List all source files (exclude tests/, build/, vendor/)
3. FOR EACH source file, one at a time (NOT in parallel):
   a. Read the source file
   b. Classify its top-level items (category, visibility, spec_kind,
      body_disposition)
   c. Extract dependencies
   d. Write curation/discovery/<path>.md IMMEDIATELY — do not batch
      writes across files
   e. If discovery_report.json exists, Edit to append this file's
      items; otherwise Write it fresh with just these items. Either
      way the JSON stays valid after each file so the run is
      restartable.
4. After the per-file loop, assemble curation/api.md with the summary
   table (this is a small synthesis pass, one Write).
5. Report: total items found, items per category.

curation/
├── discovery/
│   ├── src--module1.dfy.md
│   ├── src--module2.dfy.md
│   └── ...
├── api.md
└── discovery_report.json