docassert 0.2.1__tar.gz → 0.3.0__tar.gz

{docassert-0.2.1/docassert.egg-info → docassert-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docassert
-Version: 0.2.1
+Version: 0.3.0
 Summary: Unit testing for business documents — validate structured Markdown docs against a configurable audit standard.
 Author: C4G Enterprises Inc.
 License: Apache-2.0
@@ -64,7 +64,8 @@ pip install "docassert[ai]"
 ## Quickstart
 
 ```bash
-docassert init                        # scaffold criteria/schema/profiles/templates into your repo
+docassert new project --code AUR --name "Aurora"   # anchor a project (auto-numbered id)
+docassert new charter --project PRJ-001-AUR        # scaffold a charter into it
 docassert validate documents/**/*.md  # unit-test your documents
 docassert consistency                 # cross-document traceability + profile completeness
 docassert status --index              # derived RAG per project
@@ -86,6 +87,7 @@ you can customize them.
 | `docassert status [--project ID] [--index]` | Derived project status (md / json / html). |
 | `docassert pages --out DIR` | Build the portfolio site (index + a page per project). |
 | `docassert projects [--out] [--check]` | Generate / verify the project registry. |
+| `docassert new <kind> --project ID` | Scaffold a document from its template with identity filled in (`new project --code XYZ` auto-numbers the id); suggests the next free item ids. |
 | `docassert init [DIR]` | Scaffold the default config into a repo. |
 | `docassert extract <file>` | Extract plain text from a source `.docx` / `.pdf` / `.md` / `.txt` (the first step of doc-to-pmo conversion). Needs the `convert` extra: `pip install "docassert[convert]"`. |
 

{docassert-0.2.1 → docassert-0.3.0}/README.md

@@ -26,7 +26,8 @@ pip install "docassert[ai]"
 ## Quickstart
 
 ```bash
-docassert init                        # scaffold criteria/schema/profiles/templates into your repo
+docassert new project --code AUR --name "Aurora"   # anchor a project (auto-numbered id)
+docassert new charter --project PRJ-001-AUR        # scaffold a charter into it
 docassert validate documents/**/*.md  # unit-test your documents
 docassert consistency                 # cross-document traceability + profile completeness
 docassert status --index              # derived RAG per project
@@ -48,6 +49,7 @@ you can customize them.
 | `docassert status [--project ID] [--index]` | Derived project status (md / json / html). |
 | `docassert pages --out DIR` | Build the portfolio site (index + a page per project). |
 | `docassert projects [--out] [--check]` | Generate / verify the project registry. |
+| `docassert new <kind> --project ID` | Scaffold a document from its template with identity filled in (`new project --code XYZ` auto-numbers the id); suggests the next free item ids. |
 | `docassert init [DIR]` | Scaffold the default config into a repo. |
 | `docassert extract <file>` | Extract plain text from a source `.docx` / `.pdf` / `.md` / `.txt` (the first step of doc-to-pmo conversion). Needs the `convert` extra: `pip install "docassert[convert]"`. |
 

{docassert-0.2.1 → docassert-0.3.0}/docassert/__init__.py

@@ -5,4 +5,4 @@ standard: deterministic structural checks that gate a merge, plus optional
 AI-graded semantic checks that advise.
 """
 
-__version__ = "0.2.1"
+__version__ = "0.3.0"

{docassert-0.2.1 → docassert-0.3.0}/docassert/_data/templates/adr.template.md

@@ -1,6 +1,7 @@
 ---
 kind: adr
-id: my-adr-log
+project: PRJ-000-XXX      # the owning project's id
+id: XXX-adr       # <CODE>-<slug>; the project code namespaces it
 title: My Architecture Decision Log
 owner: jane.doe
 status: draft

{docassert-0.2.1 → docassert-0.3.0}/docassert/_data/templates/benefits-realization.template.md

@@ -1,6 +1,7 @@
 ---
 kind: benefits-realization
-id: my-benefits
+project: PRJ-000-XXX      # the owning project's id
+id: XXX-benefits-realization       # <CODE>-<slug>; the project code namespaces it
 title: My Benefits Realization Plan
 owner: jane.doe
 status: draft

{docassert-0.2.1 → docassert-0.3.0}/docassert/_data/templates/brd.template.md

@@ -1,6 +1,7 @@
 ---
 kind: brd
-id: my-brd
+project: PRJ-000-XXX      # the owning project's id
+id: XXX-brd       # <CODE>-<slug>; the project code namespaces it
 title: My Business Requirements Document
 owner: jane.doe
 status: draft   # draft | proposed | approved | baselined

{docassert-0.2.1 → docassert-0.3.0}/docassert/_data/templates/business-case.template.md

@@ -1,6 +1,7 @@
 ---
 kind: business-case
-id: my-business-case
+project: PRJ-000-XXX      # the owning project's id
+id: XXX-business-case       # <CODE>-<slug>; the project code namespaces it
 title: My Business Case
 sponsor: jane.doe
 status: draft

{docassert-0.2.1 → docassert-0.3.0}/docassert/_data/templates/charter.template.md

@@ -1,6 +1,7 @@
 ---
 kind: charter
-id: my-project            # lowercase, hyphenated, unique across documents/
+project: PRJ-000-XXX      # the owning project's id
+id: XXX-charter       # <CODE>-<slug>; the project code namespaces it
 title: My Project Charter
 sponsor: jane.doe         # the accountable individual, not a team
 budget:

{docassert-0.2.1 → docassert-0.3.0}/docassert/_data/templates/data-migration-plan.template.md

@@ -1,6 +1,7 @@
 ---
 kind: data-migration-plan
-id: my-data-migration
+project: PRJ-000-XXX      # the owning project's id
+id: XXX-data-migration-plan       # <CODE>-<slug>; the project code namespaces it
 title: My Data Migration Plan
 owner: jane.doe
 status: draft

{docassert-0.2.1 → docassert-0.3.0}/docassert/_data/templates/frnfr.template.md

@@ -1,6 +1,7 @@
 ---
 kind: frnfr
-id: my-frnfr
+project: PRJ-000-XXX      # the owning project's id
+id: XXX-frnfr       # <CODE>-<slug>; the project code namespaces it
 title: My Functional & Non-Functional Requirements
 owner: jane.doe
 status: draft

{docassert-0.2.1 → docassert-0.3.0}/docassert/_data/templates/hypercare-plan.template.md

@@ -1,6 +1,7 @@
 ---
 kind: hypercare-plan
-id: my-hypercare-plan
+project: PRJ-000-XXX      # the owning project's id
+id: XXX-hypercare-plan       # <CODE>-<slug>; the project code namespaces it
 title: My Hypercare Plan
 owner: jane.doe
 status: draft

{docassert-0.2.1 → docassert-0.3.0}/docassert/_data/templates/post-implementation-review.template.md

@@ -1,6 +1,7 @@
 ---
 kind: post-implementation-review
-id: my-pir
+project: PRJ-000-XXX      # the owning project's id
+id: XXX-post-implementation-review       # <CODE>-<slug>; the project code namespaces it
 title: My Post-Implementation Review
 owner: jane.doe
 status: draft

{docassert-0.2.1 → docassert-0.3.0}/docassert/_data/templates/prd.template.md

@@ -1,6 +1,7 @@
 ---
 kind: prd
-id: my-prd
+project: PRJ-000-XXX      # the owning project's id
+id: XXX-prd       # <CODE>-<slug>; the project code namespaces it
 title: My Product Requirements Document
 owner: jane.doe
 status: draft

{docassert-0.2.1 → docassert-0.3.0}/docassert/_data/templates/qa-test-plan.template.md

@@ -1,6 +1,7 @@
 ---
 kind: qa-test-plan
-id: my-test-plan
+project: PRJ-000-XXX      # the owning project's id
+id: XXX-qa-test-plan       # <CODE>-<slug>; the project code namespaces it
 title: My QA / Test Plan
 owner: jane.doe
 status: draft

{docassert-0.2.1 → docassert-0.3.0}/docassert/_data/templates/raci-stakeholder.template.md

@@ -1,6 +1,7 @@
 ---
 kind: raci-stakeholder
-id: my-raci
+project: PRJ-000-XXX      # the owning project's id
+id: XXX-raci-stakeholder       # <CODE>-<slug>; the project code namespaces it
 title: My RACI / Stakeholder Register
 owner: jane.doe
 status: draft

{docassert-0.2.1 → docassert-0.3.0}/docassert/_data/templates/release-cutover-plan.template.md

@@ -1,6 +1,7 @@
 ---
 kind: release-cutover-plan
-id: my-cutover-plan
+project: PRJ-000-XXX      # the owning project's id
+id: XXX-release-cutover-plan       # <CODE>-<slug>; the project code namespaces it
 title: My Release / Cutover Plan
 owner: jane.doe
 status: draft

{docassert-0.2.1 → docassert-0.3.0}/docassert/_data/templates/risk-register.template.md

@@ -1,6 +1,7 @@
 ---
 kind: risk-register
-id: my-risk-register
+project: PRJ-000-XXX      # the owning project's id
+id: XXX-risk-register       # <CODE>-<slug>; the project code namespaces it
 title: My Risk Register
 owner: jane.doe
 status: draft

{docassert-0.2.1 → docassert-0.3.0}/docassert/_data/templates/rollback-plan.template.md

@@ -1,6 +1,7 @@
 ---
 kind: rollback-plan
-id: my-rollback-plan
+project: PRJ-000-XXX      # the owning project's id
+id: XXX-rollback-plan       # <CODE>-<slug>; the project code namespaces it
 title: My Rollback Plan
 owner: jane.doe
 status: draft

{docassert-0.2.1 → docassert-0.3.0}/docassert/_data/templates/runbook.template.md

@@ -1,6 +1,7 @@
 ---
 kind: runbook
-id: my-runbook
+project: PRJ-000-XXX      # the owning project's id
+id: XXX-runbook       # <CODE>-<slug>; the project code namespaces it
 title: My Runbook
 owner: jane.doe
 status: draft

{docassert-0.2.1 → docassert-0.3.0}/docassert/_data/templates/status-report.template.md

@@ -1,6 +1,7 @@
 ---
 kind: status-report
-id: my-status-2026-07-01
+project: PRJ-000-XXX      # the owning project's id
+id: XXX-status-2026-07-01       # <CODE>-<slug>; the project code namespaces it
 title: My Project — Status Report
 owner: jane.doe
 period: 2026-07-01

{docassert-0.2.1 → docassert-0.3.0}/docassert/_data/templates/test-cases.template.md

@@ -1,6 +1,7 @@
 ---
 kind: test-cases
-id: my-test-cases
+project: PRJ-000-XXX      # the owning project's id
+id: XXX-test-cases       # <CODE>-<slug>; the project code namespaces it
 title: My Test Cases
 owner: jane.doe
 status: draft

{docassert-0.2.1 → docassert-0.3.0}/docassert/_data/templates/user-story.template.md

@@ -1,6 +1,7 @@
 ---
 kind: user-story
-id: my-user-stories
+project: PRJ-000-XXX      # the owning project's id
+id: XXX-user-story       # <CODE>-<slug>; the project code namespaces it
 title: My User Stories
 owner: jane.doe
 status: draft

{docassert-0.2.1 → docassert-0.3.0}/docassert/cli.py

@@ -261,6 +261,22 @@ def cmd_extract(args: argparse.Namespace) -> int:
     return 0
 
 
+def cmd_new(args: argparse.Namespace) -> int:
+    """Scaffold a document of a kind from its template, with identity filled in."""
+    from . import scaffold
+    try:
+        dest, notes = scaffold.new_document(
+            args.kind, documents_dir=args.documents_dir, project=args.project,
+            code=args.code, name=args.name, out=args.out)
+    except (ValueError, FileExistsError) as exc:
+        print(f"docassert: {exc}", file=sys.stderr)
+        return 2
+    print(f"docassert: created {dest}")
+    for note in notes:
+        print(f"docassert: {note}")
+    return 0
+
+
 def main(argv: list[str] | None = None) -> int:
     from . import __version__
     parser = argparse.ArgumentParser(prog="docassert",
@@ -327,6 +343,15 @@ def main(argv: list[str] | None = None) -> int:
     ex.add_argument("--out", help="Write to this path instead of stdout.")
     ex.set_defaults(func=cmd_extract)
 
+    n = sub.add_parser("new", help="Scaffold a document of a kind from its template, identity filled in.")
+    n.add_argument("kind", help="Document kind (e.g. charter, brd, project).")
+    n.add_argument("--project", help="Owning project id, PRJ-NNN-CODE (for `new project`: the id to create).")
+    n.add_argument("--code", help="For `new project`: 2–6 letter code; the sequence number is auto-picked.")
+    n.add_argument("--name", help="For `new project`: the project name.")
+    n.add_argument("--out", help="Write to this path instead of the default location.")
+    docs_dir_opt(n)
+    n.set_defaults(func=cmd_new)
+
     args = parser.parse_args(argv)
     return args.func(args)
 

{docassert-0.2.1 → docassert-0.3.0}/docassert/config.py

@@ -66,6 +66,24 @@ def read_consistency_config() -> dict:
     return _read_yaml(path) if path is not None else {}
 
 
+# ── templates ───────────────────────────────────────────────────────────────
+def template_path(kind: str) -> Path | None:
+    return _resolve(Path("templates") / f"{kind}.template.md",
+                    f"templates/{kind}.template.md")
+
+
+def available_kinds() -> list[str]:
+    """Every kind with criteria, local and packaged."""
+    names: set[str] = set()
+    local = Path("criteria")
+    if local.is_dir():
+        names |= {p.name.removesuffix(".criteria.yaml") for p in local.glob("*.criteria.yaml")}
+    packaged = DATA_DIR / "criteria"
+    if packaged.is_dir():
+        names |= {p.name.removesuffix(".criteria.yaml") for p in packaged.glob("*.criteria.yaml")}
+    return sorted(names)
+
+
 # ── profiles ────────────────────────────────────────────────────────────────
 def profile_path(name: str) -> Path | None:
     return _resolve(Path("profiles") / f"{name}.yaml", f"profiles/{name}.yaml")

docassert-0.3.0/docassert/scaffold.py

@@ -0,0 +1,128 @@
+"""Scaffold new documents from the templates (`docassert new`).
+
+Fills a kind's template with the right identity — `project:`, a namespaced
+`id:` (AUR-brd), and for project anchors an auto-numbered PRJ-NNN-CODE — and
+suggests the next free item ids so authoring starts from a valid document
+instead of a hand-edited copy.
+"""
+from __future__ import annotations
+
+import datetime as dt
+import re
+from pathlib import Path
+
+from . import config
+from .graph import build_graph
+from .projects import load_projects
+
+PROJECT_ID_RE = re.compile(r"^PRJ-(?P<seq>\d{3,})-(?P<code>[A-Z]{2,6})$")
+_ITEM_NUM_RE = re.compile(r"-(\d+)$")
+
+
+def _set_field(text: str, field: str, value: str) -> str:
+    """Set a frontmatter field, replacing its line (comments and all) if present,
+    else inserting it right after `kind:`."""
+    lines = text.split("\n")
+    end = lines.index("---", 1)
+    for i in range(1, end):
+        if re.match(rf"{field}\s*:", lines[i]):
+            lines[i] = f"{field}: {value}"
+            return "\n".join(lines)
+    for i in range(1, end):
+        if re.match(r"kind\s*:", lines[i]):
+            lines.insert(i + 1, f"{field}: {value}")
+            return "\n".join(lines)
+    lines.insert(1, f"{field}: {value}")
+    return "\n".join(lines)
+
+
+def _read_template(kind: str) -> str:
+    path = config.template_path(kind)
+    if path is None:
+        kinds = ", ".join(config.available_kinds())
+        raise ValueError(f"unknown kind '{kind}' (available: {kinds})")
+    return path.read_text(encoding="utf-8")
+
+
+def _next_project_id(code: str, anchors: list[dict]) -> str:
+    seqs = [int(m.group("seq")) for a in anchors
+            if (m := PROJECT_ID_RE.match(a["id"]))]
+    return f"PRJ-{max(seqs, default=0) + 1:03d}-{code}"
+
+
+def _item_hints(kind: str, code: str, documents_dir: str | Path) -> list[str]:
+    """Next free item id per item type the kind declares (e.g. AUR-BR-003)."""
+    specs = config.read_criteria(kind).get("item_sections", []) or []
+    if not specs:
+        return []
+    graph = build_graph(documents_dir)
+    hints = []
+    for spec in specs:
+        type_ = spec["prefix"]
+        nums = [int(m.group(1)) for item in graph.by_type.get(type_, [])
+                if item.project == code and (m := _ITEM_NUM_RE.search(item.id))]
+        hints.append(f"{code}-{type_}-{max(nums, default=0) + 1:03d}")
+    return hints
+
+
+def new_document(kind: str, documents_dir: str | Path = "documents",
+                 project: str | None = None, code: str | None = None,
+                 name: str | None = None, out: str | Path | None = None,
+                 ) -> tuple[Path, list[str]]:
+    """Create a document of `kind` from its template. Returns (path, notes)."""
+    docs = Path(documents_dir)
+    text = _read_template(kind)
+    anchors = load_projects(docs) if docs.is_dir() else []
+    notes: list[str] = []
+
+    if kind == "project":
+        if project:
+            m = PROJECT_ID_RE.match(project)
+            if not m:
+                raise ValueError(f"project id {project!r} must match PRJ-NNN-CODE (e.g. PRJ-001-AUR)")
+            pid, pcode = project, m.group("code")
+        elif code:
+            if not re.fullmatch(r"[A-Z]{2,6}", code):
+                raise ValueError(f"code {code!r} must be 2–6 uppercase letters")
+            pid, pcode = _next_project_id(code, anchors), code
+        else:
+            raise ValueError("new project needs --project PRJ-NNN-CODE or --code CODE")
+        clash = [a["id"] for a in anchors if a["id"] == pid or a["code"] == pcode]
+        if clash:
+            raise ValueError(f"project id/code already taken by {', '.join(clash)}")
+        text = _set_field(text, "id", pid)
+        text = _set_field(text, "code", pcode)
+        if name:
+            text = _set_field(text, "name", name)
+        dest = Path(out) if out else docs / pid / "project.md"
+    else:
+        if not project:
+            raise ValueError(f"new {kind} needs --project PRJ-NNN-CODE (the owning project)")
+        anchor = next((a for a in anchors if a["id"] == project), None)
+        if anchor:
+            pcode = anchor["code"]
+        else:
+            m = PROJECT_ID_RE.match(project)
+            if not m:
+                raise ValueError(f"project id {project!r} must match PRJ-NNN-CODE")
+            pcode = m.group("code")
+            notes.append(f"no project.md anchor for {project} yet — "
+                         f"create it with: docassert new project --project {project}")
+        today = dt.date.today().isoformat()
+        if kind == "status-report":
+            doc_id = f"{pcode}-status-{today}"
+            text = _set_field(text, "period", today)
+            default_dest = docs / project / "status-reports" / f"{today}.md"
+        else:
+            doc_id = f"{pcode}-{kind}"
+            default_dest = docs / project / f"{kind}.md"
+        text = _set_field(text, "id", doc_id)
+        text = _set_field(text, "project", project)
+        dest = Path(out) if out else default_dest
+        notes.extend(f"next item id: {h}" for h in _item_hints(kind, pcode, docs))
+
+    if dest.exists():
+        raise FileExistsError(f"{dest} already exists — refusing to overwrite")
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    dest.write_text(text, encoding="utf-8")
+    return dest, notes

{docassert-0.2.1 → docassert-0.3.0/docassert.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docassert
-Version: 0.2.1
+Version: 0.3.0
 Summary: Unit testing for business documents — validate structured Markdown docs against a configurable audit standard.
 Author: C4G Enterprises Inc.
 License: Apache-2.0
@@ -64,7 +64,8 @@ pip install "docassert[ai]"
 ## Quickstart
 
 ```bash
-docassert init                        # scaffold criteria/schema/profiles/templates into your repo
+docassert new project --code AUR --name "Aurora"   # anchor a project (auto-numbered id)
+docassert new charter --project PRJ-001-AUR        # scaffold a charter into it
 docassert validate documents/**/*.md  # unit-test your documents
 docassert consistency                 # cross-document traceability + profile completeness
 docassert status --index              # derived RAG per project
@@ -86,6 +87,7 @@ you can customize them.
 | `docassert status [--project ID] [--index]` | Derived project status (md / json / html). |
 | `docassert pages --out DIR` | Build the portfolio site (index + a page per project). |
 | `docassert projects [--out] [--check]` | Generate / verify the project registry. |
+| `docassert new <kind> --project ID` | Scaffold a document from its template with identity filled in (`new project --code XYZ` auto-numbers the id); suggests the next free item ids. |
 | `docassert init [DIR]` | Scaffold the default config into a repo. |
 | `docassert extract <file>` | Extract plain text from a source `.docx` / `.pdf` / `.md` / `.txt` (the first step of doc-to-pmo conversion). Needs the `convert` extra: `pip install "docassert[convert]"`. |
 

{docassert-0.2.1 → docassert-0.3.0}/docassert.egg-info/SOURCES.txt

@@ -15,6 +15,7 @@ docassert/profiles.py
 docassert/projects.py
 docassert/report.py
 docassert/rtm.py
+docassert/scaffold.py
 docassert/semantic.py
 docassert/status.py
 docassert/structural.py
@@ -99,5 +100,6 @@ tests/test_kinds_operate.py
 tests/test_kinds_reporting.py
 tests/test_profiles.py
 tests/test_projects.py
+tests/test_scaffold.py
 tests/test_status.py
 tests/test_structural.py

docassert-0.3.0/tests/test_scaffold.py

@@ -0,0 +1,147 @@
+"""Tests for `docassert new` (docassert/scaffold.py)."""
+import datetime as dt
+
+import pytest
+
+from docassert import scaffold
+from docassert.cli import main
+from docassert.loader import load
+
+BRD_MD = """---
+kind: brd
+id: AAA-brd
+project: PRJ-001-AAA
+title: T
+owner: o.owner
+status: draft
+---
+
+## Purpose
+p.
+
+## Business Requirements
+- **AAA-BR-001**: The business shall do a thing by 2 days.
+- **AAA-BR-002**: The business shall do another thing by 3 days.
+
+## Out of Scope
+n/a
+"""
+
+
+def _anchor(docs, pid="PRJ-001-AAA", code="AAA"):
+    d = docs / pid
+    d.mkdir(parents=True)
+    (d / "project.md").write_text(f"""---
+kind: project
+id: {pid}
+code: {code}
+name: Test
+sponsor: s.person
+status: proposed
+---
+
+## Overview
+o.
+
+## Scope
+s.
+""", encoding="utf-8")
+
+
+# ── new <kind> into an anchored project ──────────────────────────────────────
+def test_new_charter_fills_identity(tmp_path):
+    docs = tmp_path / "documents"
+    _anchor(docs)
+    dest, _ = scaffold.new_document("charter", docs, project="PRJ-001-AAA")
+    assert dest == docs / "PRJ-001-AAA" / "charter.md"
+    doc = load(dest)
+    assert doc.frontmatter["kind"] == "charter"
+    assert doc.frontmatter["project"] == "PRJ-001-AAA"
+    assert doc.frontmatter["id"] == "AAA-charter"
+
+
+def test_new_status_report_dated(tmp_path):
+    docs = tmp_path / "documents"
+    _anchor(docs)
+    today = dt.date.today().isoformat()
+    dest, _ = scaffold.new_document("status-report", docs, project="PRJ-001-AAA")
+    assert dest == docs / "PRJ-001-AAA" / "status-reports" / f"{today}.md"
+    fm = load(dest).frontmatter
+    assert fm["id"] == f"AAA-status-{today}" and str(fm["period"]) == today
+
+
+def test_new_without_anchor_notes_it(tmp_path):
+    docs = tmp_path / "documents"
+    docs.mkdir()
+    dest, notes = scaffold.new_document("charter", docs, project="PRJ-002-BBB")
+    assert load(dest).frontmatter["id"] == "BBB-charter"
+    assert any("no project.md anchor" in n for n in notes)
+
+
+def test_new_suggests_next_item_ids(tmp_path):
+    docs = tmp_path / "documents"
+    _anchor(docs)
+    (docs / "PRJ-001-AAA" / "brd.md").write_text(BRD_MD, encoding="utf-8")
+    _, notes = scaffold.new_document("prd", docs, project="PRJ-001-AAA")
+    joined = " ".join(notes)
+    assert "AAA-PR-001" in joined and "AAA-AC-001" in joined
+    # with the brd (and its items) gone, the BR counter resets
+    (docs / "PRJ-001-AAA" / "brd.md").unlink()
+    _, notes2 = scaffold.new_document("brd", docs, project="PRJ-001-AAA",
+                                      out=tmp_path / "brd2.md")
+    assert any("AAA-BR-001" in n for n in notes2)
+
+
+def test_new_brd_counts_existing_items(tmp_path):
+    docs = tmp_path / "documents"
+    _anchor(docs)
+    (docs / "PRJ-001-AAA" / "brd.md").write_text(BRD_MD, encoding="utf-8")
+    _, notes = scaffold.new_document("brd", docs, project="PRJ-001-AAA",
+                                     out=tmp_path / "brd2.md")
+    assert any("AAA-BR-003" in n for n in notes)
+
+
+# ── new project ──────────────────────────────────────────────────────────────
+def test_new_project_auto_numbers(tmp_path):
+    docs = tmp_path / "documents"
+    _anchor(docs, "PRJ-001-AAA", "AAA")
+    dest, _ = scaffold.new_document("project", docs, code="BBB", name="Bravo")
+    assert dest == docs / "PRJ-002-BBB" / "project.md"
+    fm = load(dest).frontmatter
+    assert fm["id"] == "PRJ-002-BBB" and fm["code"] == "BBB" and fm["name"] == "Bravo"
+
+
+def test_new_project_rejects_duplicate_code(tmp_path):
+    docs = tmp_path / "documents"
+    _anchor(docs, "PRJ-001-AAA", "AAA")
+    with pytest.raises(ValueError, match="already taken"):
+        scaffold.new_document("project", docs, code="AAA")
+
+
+# ── guardrails ───────────────────────────────────────────────────────────────
+def test_unknown_kind_lists_available(tmp_path):
+    with pytest.raises(ValueError, match="charter"):
+        scaffold.new_document("nope", tmp_path)
+
+
+def test_refuses_overwrite(tmp_path):
+    docs = tmp_path / "documents"
+    _anchor(docs)
+    scaffold.new_document("charter", docs, project="PRJ-001-AAA")
+    with pytest.raises(FileExistsError):
+        scaffold.new_document("charter", docs, project="PRJ-001-AAA")
+
+
+def test_cli_new_missing_project_exits_2(tmp_path, monkeypatch, capsys):
+    monkeypatch.chdir(tmp_path)
+    assert main(["new", "charter"]) == 2
+    assert "needs --project" in capsys.readouterr().err
+
+
+def test_cli_new_creates_and_hints(tmp_path, monkeypatch, capsys):
+    docs = tmp_path / "documents"
+    _anchor(docs)
+    monkeypatch.chdir(tmp_path)
+    assert main(["new", "brd", "--project", "PRJ-001-AAA"]) == 0
+    out = capsys.readouterr().out
+    assert "created" in out and "AAA-BR-001" in out