docassert 0.2.0__tar.gz → 0.3.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docassert
-Version: 0.2.0
+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
@@ -80,15 +81,20 @@ you can customize them.
 
 | Command | What it does |
 |---|---|
-| `docassert validate <globs>` | Validate documents against their kind's criteria. Exit code = number of blocking failures. |
+| `docassert validate <globs>` | Validate documents against their kind's criteria. Exit code = number of blocking failures (capped at 125). |
 | `docassert consistency` | Cross-document checks: referential integrity, coverage, required links, profile completeness. |
 | `docassert rtm [--project ID]` | Requirements traceability matrix (Markdown or CSV). |
 | `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]"`. |
 
+Every document-reading command accepts `--documents-dir` (default `documents/`).
+AI alignment grades at most `alignment_limit` links per run (default 25; set it
+in `consistency.yaml`, `0` = no cap) so API cost stays bounded on large graphs.
+
 ## Document kinds
 
 Twenty kinds, each a `templates/<kind>.template.md` + `schema/<kind>.schema.json`

{docassert-0.2.0 → 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
@@ -42,15 +43,20 @@ you can customize them.
 
 | Command | What it does |
 |---|---|
-| `docassert validate <globs>` | Validate documents against their kind's criteria. Exit code = number of blocking failures. |
+| `docassert validate <globs>` | Validate documents against their kind's criteria. Exit code = number of blocking failures (capped at 125). |
 | `docassert consistency` | Cross-document checks: referential integrity, coverage, required links, profile completeness. |
 | `docassert rtm [--project ID]` | Requirements traceability matrix (Markdown or CSV). |
 | `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]"`. |
 
+Every document-reading command accepts `--documents-dir` (default `documents/`).
+AI alignment grades at most `alignment_limit` links per run (default 25; set it
+in `consistency.yaml`, `0` = no cap) so API cost stays bounded on large graphs.
+
 ## Document kinds
 
 Twenty kinds, each a `templates/<kind>.template.md` + `schema/<kind>.schema.json`

{docassert-0.2.0 → 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.0"
+__version__ = "0.3.0"

{docassert-0.2.0 → docassert-0.3.0}/docassert/_data/consistency.yaml

@@ -35,6 +35,10 @@ coverage:
 
 # Advisory AI alignment: for each relation, judge whether the child genuinely
 # fulfils the parent it links to. Never blocks.
+# Each graded link costs one API call; `alignment_limit` caps calls per run
+# (0 = no cap).
+alignment_limit: 25
+
 alignment:
   - relation: traces
     prompt: >

{docassert-0.2.0 → 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.0 → 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.0 → 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.0 → 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.0 → 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.0 → 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.0 → 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.0 → 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.0 → 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.0 → 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.0 → 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.0 → 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.0 → 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.0 → 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.0 → 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.0 → 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.0 → 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.0 → 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.0 → 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.0 → docassert-0.3.0}/docassert/cli.py

@@ -3,8 +3,10 @@
     docassert validate documents/charters/aurora.md
     docassert validate documents/**/*.md --junit out.xml --markdown comment.md
 
-Exit code = number of BLOCKING (structural) failures. Advisory (AI) failures
-never affect the exit code, so CI is gated only by deterministic checks.
+Exit code = number of BLOCKING (structural) failures, capped at 125 so large
+counts can't wrap around the 8-bit exit-status space (256 failures must never
+read as success). Advisory (AI) failures never affect the exit code, so CI is
+gated only by deterministic checks.
 """
 from __future__ import annotations
 
@@ -23,15 +25,24 @@ from .models import CheckResult
 from .semantic import run_semantic
 from .structural import run_structural
 
-# The user's documents live here; criteria / schema / consistency.yaml / profiles
-# resolve via `config` (local override → packaged default).
-DOCUMENTS_DIR = Path("documents")
+# Default documents location; every document-reading command accepts
+# --documents-dir to override it. Criteria / schema / consistency.yaml /
+# profiles resolve via `config` (local override → packaged default).
+DEFAULT_DOCUMENTS_DIR = "documents"
 
+# POSIX exit statuses are 8-bit; 126+ carry shell meanings. Cap so a failure
+# count can never wrap to 0.
+_EXIT_CAP = 125
 
-def _build_id_index() -> dict[str, list[str]]:
-    """Map document id -> [paths] across all documents/, for uniqueness checks."""
+
+def _capped(failures: int) -> int:
+    return min(failures, _EXIT_CAP)
+
+
+def _build_id_index(documents_dir: Path) -> dict[str, list[str]]:
+    """Map document id -> [paths] across the documents tree, for uniqueness checks."""
     index: dict[str, list[str]] = defaultdict(list)
-    for path in DOCUMENTS_DIR.rglob("*.md"):
+    for path in documents_dir.rglob("*.md"):
         try:
             doc = load(path)
         except ValueError:
@@ -86,7 +97,7 @@ def cmd_validate(args: argparse.Namespace) -> int:
         print("docassert: no markdown documents matched.", file=sys.stderr)
         return 0
 
-    id_index = _build_id_index()
+    id_index = _build_id_index(Path(args.documents_dir))
     results_by_doc: dict[str, list[CheckResult]] = {}
     for path in files:
         try:
@@ -106,12 +117,12 @@ def cmd_validate(args: argparse.Namespace) -> int:
     if args.markdown:
         Path(args.markdown).write_text(report.markdown(results_by_doc))
 
-    return sum(1 for rs in results_by_doc.values()
-               for r in rs if r.is_blocking_failure)
+    return _capped(sum(1 for rs in results_by_doc.values()
+                       for r in rs if r.is_blocking_failure))
 
 
 def cmd_consistency(args: argparse.Namespace) -> int:
-    results = run_consistency(DOCUMENTS_DIR, with_semantic=not args.no_semantic)
+    results = run_consistency(args.documents_dir, with_semantic=not args.no_semantic)
     results_by_doc = {"consistency (cross-document)": results}
 
     print(report.console(results_by_doc))
@@ -123,7 +134,7 @@ def cmd_consistency(args: argparse.Namespace) -> int:
         Path(args.markdown).write_text(
             report.markdown(results_by_doc, title="docassert consistency"))
 
-    return sum(1 for r in results if r.is_blocking_failure)
+    return _capped(sum(1 for r in results if r.is_blocking_failure))
 
 
 def _project_code(value: str | None) -> str | None:
@@ -132,7 +143,7 @@ def _project_code(value: str | None) -> str | None:
 
 
 def cmd_rtm(args: argparse.Namespace) -> int:
-    graph = build_graph(DOCUMENTS_DIR)
+    graph = build_graph(args.documents_dir)
     code = _project_code(args.project)
     text = rtm.render_csv(graph, code) if args.csv else rtm.render_markdown(graph, code)
     if args.out:
@@ -145,7 +156,7 @@ def cmd_rtm(args: argparse.Namespace) -> int:
 
 def cmd_projects(args: argparse.Namespace) -> int:
     from . import projects as proj
-    plist = proj.load_projects(DOCUMENTS_DIR)
+    plist = proj.load_projects(args.documents_dir)
     issues = proj.registry_issues(plist)
     for issue in issues:
         print(f"docassert: {issue}", file=sys.stderr)
@@ -172,7 +183,7 @@ def cmd_projects(args: argparse.Namespace) -> int:
 def cmd_status(args: argparse.Namespace) -> int:
     from . import status as status_mod
     if args.index:
-        index = status_mod.build_index(DOCUMENTS_DIR)
+        index = status_mod.build_index(args.documents_dir)
         if args.format == "json":
             text = status_mod.render_json(index)
         elif args.format == "html":
@@ -181,7 +192,7 @@ def cmd_status(args: argparse.Namespace) -> int:
             text = status_mod.render_index_markdown(index)
         tag = index["overall"]["rag"]
     else:
-        model = status_mod.build_status(DOCUMENTS_DIR, project=args.project)
+        model = status_mod.build_status(args.documents_dir, project=args.project)
         if args.project and not model["documents"]:
             print(f"docassert: no documents for project {args.project!r}", file=sys.stderr)
             return 2
@@ -206,16 +217,17 @@ def cmd_pages(args: argparse.Namespace) -> int:
     from . import status as status_mod
     out = Path(args.out)
     out.mkdir(parents=True, exist_ok=True)
+    docs_dir = args.documents_dir
 
-    index = status_mod.build_index(DOCUMENTS_DIR)
+    index = status_mod.build_index(docs_dir)
     (out / "index.html").write_text(status_mod.render_index_html(index))
 
-    plist = projects_mod.load_projects(DOCUMENTS_DIR)
+    plist = projects_mod.load_projects(docs_dir)
     for p in plist:
-        model = status_mod.build_status(DOCUMENTS_DIR, project=p["id"])
+        model = status_mod.build_status(docs_dir, project=p["id"])
         (out / f"{p['id']}.html").write_text(status_mod.render_html(model))
 
-    (out / "RTM.md").write_text(rtm.render_markdown(build_graph(DOCUMENTS_DIR)))
+    (out / "RTM.md").write_text(rtm.render_markdown(build_graph(docs_dir)))
     print(f"docassert: wrote {out}/ — index + {len(plist)} project page(s) + RTM.md "
           f"(portfolio: {index['overall']['rag']})")
     return 0
@@ -249,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",
@@ -256,10 +284,15 @@ def main(argv: list[str] | None = None) -> int:
     parser.add_argument("--version", action="version", version=f"docassert {__version__}")
     sub = parser.add_subparsers(dest="command", required=True)
 
+    def docs_dir_opt(sp: argparse.ArgumentParser) -> None:
+        sp.add_argument("--documents-dir", default=DEFAULT_DOCUMENTS_DIR,
+                        help=f"Documents tree to read (default: {DEFAULT_DOCUMENTS_DIR}/).")
+
     v = sub.add_parser("validate", help="Validate documents against their criteria.")
     v.add_argument("paths", nargs="+", help="Markdown files or globs.")
     v.add_argument("--junit", help="Write a JUnit XML report to this path.")
     v.add_argument("--markdown", help="Write a PR-comment markdown report to this path.")
+    docs_dir_opt(v)
     v.set_defaults(func=cmd_validate)
 
     c = sub.add_parser("consistency", help="Check cross-document traceability.")
@@ -267,12 +300,14 @@ def main(argv: list[str] | None = None) -> int:
     c.add_argument("--markdown", help="Write a PR-comment markdown report to this path.")
     c.add_argument("--no-semantic", action="store_true",
                    help="Skip AI alignment (structural consistency only).")
+    docs_dir_opt(c)
     c.set_defaults(func=cmd_consistency)
 
     r = sub.add_parser("rtm", help="Generate the requirements traceability matrix.")
     r.add_argument("--out", help="Write to this path instead of stdout.")
     r.add_argument("--csv", action="store_true", help="Emit CSV instead of Markdown.")
     r.add_argument("--project", help="Scope to one project (PRJ-NNN-CODE id or CODE).")
+    docs_dir_opt(r)
     r.set_defaults(func=cmd_rtm)
 
     s = sub.add_parser("status", help="Derive a project status page from the documents.")
@@ -284,16 +319,19 @@ def main(argv: list[str] | None = None) -> int:
     s.add_argument("--index", action="store_true",
                    help="Render the multi-project portfolio index instead of one status.")
     s.add_argument("--out", help="Write to this path instead of stdout.")
+    docs_dir_opt(s)
     s.set_defaults(func=cmd_status)
 
     pg = sub.add_parser("pages", help="Build the full Pages site (portfolio index + a page per project).")
     pg.add_argument("--out", default="_site", help="Output directory (default: _site).")
+    docs_dir_opt(pg)
     pg.set_defaults(func=cmd_pages)
 
     p = sub.add_parser("projects", help="Generate the project registry from the project.md anchors.")
     p.add_argument("--out", help="Write to this path instead of stdout (e.g. projects.yaml).")
     p.add_argument("--check", action="store_true",
                    help="Exit non-zero if the registry file is stale (CI freshness gate).")
+    docs_dir_opt(p)
     p.set_defaults(func=cmd_projects)
 
     ini = sub.add_parser("init", help="Scaffold the default criteria/schema/profiles/templates into a repo.")
@@ -305,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.0 → 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.2.0 → docassert-0.3.0}/docassert/consistency.py

@@ -130,6 +130,12 @@ def check_profile_completeness(documents_dir: str | Path = "documents") -> Check
 
 
 # ── semantic (advisory) ────────────────────────────────────────────────────
+# Each alignment edge costs one API call, so a large graph could otherwise run
+# away on cost. Cap per run; tune with `alignment_limit` in consistency.yaml
+# (0 disables the cap).
+DEFAULT_ALIGNMENT_LIMIT = 25
+
+
 def run_alignment_checks(graph, config) -> list[CheckResult]:
     edges = []  # (prompt, parent, child, relation)
     for rule in config.get("alignment", []):
@@ -142,12 +148,26 @@ def run_alignment_checks(graph, config) -> list[CheckResult]:
 
     if not edges:
         return []
+
+    limit = int(config.get("alignment_limit", DEFAULT_ALIGNMENT_LIMIT) or 0)
+    note: CheckResult | None = None
+    if limit and len(edges) > limit:
+        note = CheckResult(
+            "alignment-limit", True, False,
+            f"graded {limit} of {len(edges)} link(s) — raise `alignment_limit` "
+            f"in consistency.yaml to grade more per run",
+            kind="semantic", score=None)
+        edges = edges[:limit]
+
     if not os.environ.get("ANTHROPIC_API_KEY"):
         return [CheckResult("alignment", True, False,
                             f"skipped — no ANTHROPIC_API_KEY ({len(edges)} link(s) to grade)",
                             kind="semantic", score=None)]
-    return [run_alignment(f"align:{c.id}-{rel}-{p.id}", prompt, p.text, c.text)
-            for prompt, p, c, rel in edges]
+    results = [run_alignment(f"align:{c.id}-{rel}-{p.id}", prompt, p.text, c.text)
+               for prompt, p, c, rel in edges]
+    if note is not None:
+        results.append(note)
+    return results
 
 
 def run_consistency(documents_dir: str | Path = "documents",