Let phase 1 request a finding-id scheme that does not reuse numbers

Makefile

@@ -57,6 +57,7 @@ help:
 	@printf "\n"
 	@printf "    $(BOLD)make init$(RESET)                     Create/update repo-local virtualenv\n"
 	@printf "    $(BOLD)make phase-1$(RESET)                  Run reconnaissance\n"
+	@printf "        $(BOLD)ID_SCHEME=CC-0142$(RESET)           First finding id for this audit\n"
 	@printf "    $(BOLD)make phase-2$(RESET)                  Run hypothesis generation\n"
 	@printf "    $(BOLD)make phase-3$(RESET)                  Run counter-analysis\n"
 	@printf "    $(BOLD)make phase-4 FINDING=CC-0001$(RESET)  Validate one finding\n"
@@ -188,6 +189,7 @@ env-check:
 # ---------------------------------------------------------------------------
 
 phase-1: env-check
+	@$(PYTHON) tools/record-id-scheme.py $(if $(ID_SCHEME),--scheme "$(ID_SCHEME)") $(if $(ID_START),--start $(ID_START)) $(if $(ID_LEDGER),--ledger "$(ID_LEDGER)")
 	@$(PYTHON) tools/gate-check.py 1
 	@$(PYTHON) tools/run-agent.py --phase 1 --label "Phase 1: Reconnaissance" --agent recon
 

docs/workflow.md

@@ -37,6 +37,15 @@ Run:
 
     make phase-1
 
+To line finding ids up with an internal tracker, pass the first id you want
+when reconnaissance starts. Later findings continue from that number instead
+of minting another `CC-0001`. The request is saved in
+`itemdb/notes/id-scheme.yml` and reused by `make findings-create` and
+`make next-id`.
+
+    make phase-1 ID_SCHEME=CC-0142
+    make phase-1 ID_SCHEME=INT-0007 ID_LEDGER=$HOME/.codecome/finding-ids.json
+
 `make phase-1` is the recommended automatic path (it runs Phase 1a, CodeQL enrichment, Phase 1b, and Phase 1c). For manual invocation, use the individual subphase prompts:
 
     opencode run --agent recon "$(cat prompts/phase-1a-profile.md)"

tests/test_id_scheme.py

@@ -0,0 +1,139 @@
+from __future__ import annotations
+
+import sys
+from argparse import Namespace
+from pathlib import Path
+
+import pytest
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT / "tools"))
+
+from findings.constants import FindingsContext  # noqa: E402
+from findings.create import create_finding  # noqa: E402
+from findings.ids import next_finding_id  # noqa: E402
+from findings.scheme import (  # noqa: E402
+    IdSchemeError,
+    allocate_next_id,
+    load_id_scheme,
+    parse_id_scheme,
+    save_id_scheme,
+)
+
+
+def _workspace(tmp_path: Path) -> FindingsContext:
+    notes = tmp_path / "itemdb" / "notes"
+    findings = tmp_path / "itemdb" / "findings"
+    evidence = tmp_path / "itemdb" / "evidence"
+    template_dir = tmp_path / "templates"
+    notes.mkdir(parents=True)
+    (findings / "PENDING").mkdir(parents=True)
+    evidence.mkdir(parents=True)
+    template_dir.mkdir(parents=True)
+    (template_dir / "finding.md").write_text(
+        "---\n"
+        'id: "CC-0000"\n'
+        'title: "Short vulnerability title"\n'
+        'status: "PENDING"\n'
+        'severity: "MEDIUM"\n'
+        'confidence: "LOW"\n'
+        'category: "Unclassified"\n'
+        'language: "unknown"\n'
+        'target_area: "unknown"\n'
+        "validation:\n"
+        '  evidence_dir: "itemdb/evidence/CC-0000"\n'
+        "exploitation:\n"
+        '  artifacts_dir: "itemdb/evidence/CC-0000/exploits"\n'
+        'created_at: "YYYY-MM-DD"\n'
+        'updated_at: "YYYY-MM-DD"\n'
+        "---\n\n"
+        "Briefly describe the suspected vulnerability.\n",
+        encoding="utf-8",
+    )
+    return FindingsContext(
+        root=tmp_path,
+        findings_root=findings,
+        evidence_root=evidence,
+        notes_root=notes,
+        template_path=template_dir / "finding.md",
+        evidence_template_path=template_dir / "evidence-readme.md",
+    )
+
+
+def test_parse_specimen_sets_width_and_start():
+    scheme = parse_id_scheme("CC-0142")
+    assert scheme.prefix == "CC"
+    assert scheme.width == 4
+    assert scheme.start == 142
+    assert scheme.format(142) == "CC-0142"
+
+
+def test_parse_rejects_free_form_text():
+    with pytest.raises(IdSchemeError):
+        parse_id_scheme("start at one")
+
+
+def test_default_numbering_still_starts_at_cc_0001(tmp_path):
+    ctx = _workspace(tmp_path)
+    assert next_finding_id(findings_root=ctx.findings_root, notes_root=ctx.notes_root) == "CC-0001"
+
+
+def test_phase1_scheme_is_reused_by_the_next_finding(tmp_path):
+    ctx = _workspace(tmp_path)
+    save_id_scheme(parse_id_scheme("CC-0142"), ctx.notes_root)
+    assert next_finding_id(findings_root=ctx.findings_root, notes_root=ctx.notes_root) == "CC-0142"
+
+    pending = ctx.findings_root / "PENDING"
+    (pending / "CC-0142-first.md").write_text("id: CC-0142\n", encoding="utf-8")
+    assert next_finding_id(findings_root=ctx.findings_root, notes_root=ctx.notes_root) == "CC-0143"
+
+
+def test_requested_start_does_not_reuse_a_taken_number(tmp_path):
+    ctx = _workspace(tmp_path)
+    pending = ctx.findings_root / "PENDING"
+    (pending / "CC-0001-old.md").write_text("id: CC-0001\n", encoding="utf-8")
+    (pending / "CC-0002-old.md").write_text("id: CC-0002\n", encoding="utf-8")
+    save_id_scheme(parse_id_scheme("CC-0001"), ctx.notes_root)
+    assert next_finding_id(findings_root=ctx.findings_root, notes_root=ctx.notes_root) == "CC-0003"
+
+
+def test_other_prefix_does_not_collide_with_cc(tmp_path):
+    ctx = _workspace(tmp_path)
+    pending = ctx.findings_root / "PENDING"
+    (pending / "CC-0001-old.md").write_text("id: CC-0001\n", encoding="utf-8")
+    save_id_scheme(parse_id_scheme("INT-0007"), ctx.notes_root)
+    assert next_finding_id(findings_root=ctx.findings_root, notes_root=ctx.notes_root) == "INT-0007"
+
+
+def test_ledger_continues_across_audits(tmp_path):
+    ledger = tmp_path / "finding-ids.json"
+    first = parse_id_scheme("CC-0001")
+    first = type(first)(first.prefix, first.width, first.start, ledger)
+    assert allocate_next_id(first, []) == "CC-0001"
+    second_notes = tmp_path / "other" / "notes"
+    second_notes.mkdir(parents=True)
+    save_id_scheme(first, second_notes)
+    loaded = load_id_scheme(second_notes)
+    assert loaded is not None
+    assert allocate_next_id(loaded, []) == "CC-0002"
+
+
+def test_create_finding_uses_saved_scheme(tmp_path):
+    ctx = _workspace(tmp_path)
+    save_id_scheme(parse_id_scheme("CC-0142"), ctx.notes_root)
+    out = create_finding(
+        Namespace(
+            title="Missing auth check",
+            id=None,
+            slug=None,
+            severity="HIGH",
+            confidence="MEDIUM",
+            category="Auth",
+            language="python",
+            target_area="api",
+            force=False,
+        ),
+        ctx=ctx,
+    )
+    assert out.name.startswith("CC-0142-")
+    assert 'id: "CC-0142"' in out.read_text(encoding="utf-8")

tools/codecome.py

@@ -690,9 +690,9 @@ def command_status(_: argparse.Namespace) -> int:
 
 
 def command_next_id(_: argparse.Namespace) -> int:
-    ids = collect_finding_ids(iter_finding_files())
-    next_id = max(ids, default=0) + 1
-    print(f"CC-{next_id:04d}")
+    from findings.ids import next_finding_id
+
+    print(next_finding_id())
     return 0
 
 

tools/findings/create.py

@@ -20,6 +20,7 @@
 )
 from findings.constants import FindingsContext
 from findings.ids import next_finding_id, slugify
+from findings.scheme import load_id_scheme
 from findings.frontmatter import replace_scalar_frontmatter, replace_nested_value
 
 
@@ -39,10 +40,20 @@ def create_finding(
     if not ctx.template_path.exists():
         raise FileNotFoundError(f"Template not found: {ctx.template_path}")
 
-    finding_id = args.id or next_finding_id(findings_root=ctx.findings_root)
-
-    if args.id and not FINDING_ID_FORMAT_RE.fullmatch(args.id):
-        raise ValueError(f"Invalid finding id format: {args.id!r} (expected CC-NNNN)")
+    scheme = load_id_scheme(ctx.notes_root)
+    if args.id:
+        if scheme is not None and not scheme.matches(args.id):
+            raise ValueError(
+                f"Invalid finding id format: {args.id!r} "
+                f"(expected {scheme.prefix}- and {scheme.width} digits)"
+            )
+        if scheme is None and not FINDING_ID_FORMAT_RE.fullmatch(args.id):
+            raise ValueError(f"Invalid finding id format: {args.id!r} (expected CC-NNNN)")
+
+    finding_id = args.id or next_finding_id(
+        findings_root=ctx.findings_root,
+        notes_root=ctx.notes_root,
+    )
     slug = args.slug or slugify(args.title)
     today = date.today().isoformat()
 

tools/findings/ids.py

@@ -7,7 +7,8 @@
 from pathlib import Path
 from typing import Iterable, List, Optional
 
-from findings.constants import FINDINGS_ROOT, FINDING_ID_RE, FINDING_ID_STRICT_RE, ROOT, STATUSES
+from findings.constants import FINDINGS_ROOT, FINDING_ID_RE, FINDING_ID_STRICT_RE, NOTES_ROOT, ROOT, STATUSES
+from findings.scheme import IdScheme, allocate_next_id, load_id_scheme
 
 
 def extract_id_from_path(path: Path) -> str:
@@ -25,17 +26,27 @@ def slugify(value: str) -> str:
 def iter_finding_files(
     *,
     findings_root: Optional[Path] = None,
+    notes_root: Optional[Path] = None,
 ) -> List[Path]:
     """Recursive CC-*.md glob, sorted. Used by create (next_id), checks."""
     findings_root = findings_root if findings_root is not None else FINDINGS_ROOT
+    notes = notes_root if notes_root is not None else notes_root_for(findings_root)
     files: List[Path] = []
 
     if not findings_root.exists():
         return files
 
-    for path in findings_root.rglob("CC-*.md"):
-        if path.is_file():
-            files.append(path)
+    patterns = ["CC-*.md"]
+    scheme = _scheme_for(notes)
+    if scheme is not None and scheme.prefix != "CC":
+        patterns.append(f"{scheme.prefix}-*.md")
+
+    seen: set[Path] = set()
+    for pattern in patterns:
+        for path in findings_root.rglob(pattern):
+            if path.is_file() and path not in seen:
+                seen.add(path)
+                files.append(path)
 
     return sorted(files)
 
@@ -56,22 +67,56 @@ def iter_findings(
         if not status_dir.exists():
             continue
 
-        yield from sorted(status_dir.glob("CC-*.md"))
+        patterns = ["CC-*.md"]
+        scheme = _scheme_for(notes_root_for(findings_root))
+        if scheme is not None and scheme.prefix != "CC":
+            patterns.append(f"{scheme.prefix}-*.md")
+        for pattern in patterns:
+            yield from sorted(status_dir.glob(pattern))
+
+
+def notes_root_for(findings_root: Optional[Path]) -> Path:
+    if findings_root is None:
+        return NOTES_ROOT
+    return findings_root.parent / "notes"
+
+
+def _scheme_for(notes_root: Optional[Path]) -> Optional[IdScheme]:
+    return load_id_scheme(notes_root)
+
+
+def issued_numbers(
+    scheme: IdScheme,
+    *,
+    findings_root: Optional[Path] = None,
+    notes_root: Optional[Path] = None,
+) -> List[int]:
+    numbers: List[int] = []
+    pattern = scheme.number_re()
+    notes = notes_root if notes_root is not None else notes_root_for(findings_root)
+    for path in iter_finding_files(findings_root=findings_root, notes_root=notes):
+        match = pattern.search(path.name)
+        if match:
+            numbers.append(int(match.group(1)))
+    return numbers
 
 
 def next_finding_id(
     *,
     findings_root: Optional[Path] = None,
+    notes_root: Optional[Path] = None,
 ) -> str:
-    ids: List[int] = []
-
-    for path in iter_finding_files(findings_root=findings_root):
-        match = FINDING_ID_RE.search(path.name)
-        if match:
-            ids.append(int(match.group(1)))
+    notes = notes_root if notes_root is not None else notes_root_for(findings_root)
+    scheme = load_id_scheme(notes)
+    if scheme is None:
+        ids: List[int] = []
+        for path in iter_finding_files(findings_root=findings_root, notes_root=notes):
+            match = FINDING_ID_RE.search(path.name)
+            if match:
+                ids.append(int(match.group(1)))
+        return f"CC-{max(ids, default=0) + 1:04d}"
 
-    next_id = max(ids, default=0) + 1
-    return f"CC-{next_id:04d}"
+    return allocate_next_id(scheme, issued_numbers(scheme, findings_root=findings_root, notes_root=notes))
 
 
 def find_finding(
@@ -87,7 +132,8 @@ def find_finding(
     if candidate.exists():
         return candidate.resolve()
 
-    if not FINDING_ID_STRICT_RE.fullmatch(identifier):
+    scheme = _scheme_for(notes_root_for(findings_root))
+    if not FINDING_ID_STRICT_RE.fullmatch(identifier) and not (scheme and scheme.matches(identifier)):
         raise FileNotFoundError(f"Invalid finding id or path: {identifier}")
 
     matches = sorted(findings_root.rglob(f"{identifier}-*.md"))

tools/findings/package.py

@@ -12,10 +12,14 @@
 import _colors as C
 
 from findings.constants import FINDING_ID_STRICT_RE, ROOT, FindingsContext
+from findings.scheme import load_id_scheme
 
 
-def validate_finding_id(finding_id: str) -> str:
+def validate_finding_id(finding_id: str, *, notes_root: Optional[Path] = None) -> str:
     stripped = finding_id.strip()
+    scheme = load_id_scheme(notes_root)
+    if scheme is not None and scheme.matches(stripped):
+        return stripped
     if not FINDING_ID_STRICT_RE.fullmatch(stripped):
         raise ValueError(f"Invalid finding id format: {finding_id!r} (expected CC-NNNN)")
     return stripped