docassert 0.2.1__tar.gz → 0.4.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docassert
-Version: 0.2.1
+Version: 0.4.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
@@ -74,7 +75,11 @@ docassert pages --out _site           # a portfolio dashboard + a page per proje
 Config resolves **local override → packaged default**: docassert ships sensible
 defaults, and your repo's own `criteria/` (or `schema/`, `profiles/`,
 `consistency.yaml`) wins when present. `docassert init` copies the defaults in so
-you can customize them.
+you can customize them — including the **doc-to-pmo Claude skill** into
+`.claude/skills/`, so Claude Code in your repo knows how to convert existing
+Word/PDF documents into testable docassert documents (faithfully — gaps are
+flagged as TODOs, never invented). The skill's source is
+[`skills/doc-to-pmo/SKILL.md`](skills/doc-to-pmo/SKILL.md).
 
 ## Commands
 
@@ -86,6 +91,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.4.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
@@ -36,7 +37,11 @@ docassert pages --out _site           # a portfolio dashboard + a page per proje
 Config resolves **local override → packaged default**: docassert ships sensible
 defaults, and your repo's own `criteria/` (or `schema/`, `profiles/`,
 `consistency.yaml`) wins when present. `docassert init` copies the defaults in so
-you can customize them.
+you can customize them — including the **doc-to-pmo Claude skill** into
+`.claude/skills/`, so Claude Code in your repo knows how to convert existing
+Word/PDF documents into testable docassert documents (faithfully — gaps are
+flagged as TODOs, never invented). The skill's source is
+[`skills/doc-to-pmo/SKILL.md`](skills/doc-to-pmo/SKILL.md).
 
 ## Commands
 
@@ -48,6 +53,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.4.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.4.0"

docassert-0.4.0/docassert/_data/skills/doc-to-pmo/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: doc-to-pmo
+description: Convert an existing business document (Word .docx, PDF, or pasted text) into a docassert Markdown document so it can be unit-tested and gated in CI. Use when someone wants to bring an existing charter, BRD, PRD, risk register, or any other supported kind into a PMO-as-Code repo.
+---
+
+# doc-to-pmo
+
+Convert a source document into a standard docassert document. **Map the content
+faithfully — never invent missing facts to make the audit pass.** A document
+that lacks measurable success criteria *should* fail the audit; your job is to
+surface that, not hide it.
+
+Requires docassert (`pipx install docassert`; add `"docassert[convert]"` for
+.docx/.pdf extraction).
+
+## Steps
+
+1. **Identify the kind.** Supported kinds: `charter`, `business-case`, `brd`,
+   `prd`, `frnfr`, `user-story`, `test-cases`, `adr`, `risk-register`,
+   `raci-stakeholder`, `qa-test-plan`, `data-migration-plan`,
+   `release-cutover-plan`, `rollback-plan`, `hypercare-plan`, `runbook`,
+   `status-report`, `post-implementation-review`, `benefits-realization`.
+   One source file may yield several documents (a "BRD" is often really a
+   BRD + PRD + NFRs + risks). Propose the split to the user before writing.
+
+2. **Anchor the project.** Every document belongs to a project
+   (`PRJ-NNN-CODE`). Check `projects.yaml` or `documents/` for an existing
+   anchor; if there is none, create one (ask the user for the code, name, and
+   sponsor — don't guess):
+
+   ```bash
+   docassert new project --code AUR --name "Aurora — Customer Onboarding"
+   ```
+
+3. **Extract the source text** (`.docx`, `.pdf`, `.md`, `.txt`):
+
+   ```bash
+   docassert extract path/to/source.docx
+   ```
+
+   For pasted text or Google Docs, ask the user to paste the content or export
+   to `.docx`/`.pdf` first.
+
+4. **Scaffold, then fill.** Let docassert create the file with the identity
+   (frontmatter `project:`, namespaced `id:`) already correct, then map the
+   source content into its sections:
+
+   ```bash
+   docassert new brd --project PRJ-001-AUR
+   # docassert: created documents/PRJ-001-AUR/brd.md
+   # docassert: next item id: AUR-BR-001
+   ```
+
+   Keep `status: draft` unless the source clearly states an approval.
+
+5. **Author traceable items where the kind defines them.** Requirements,
+   criteria, tests, risks, and decisions are bullets with a stable namespaced
+   id and typed links — use the `next item id` hints for numbering:
+
+   ```
+   - **AUR-BR-001**: The business shall reduce onboarding time to under 2 days.
+   - **AUR-PR-001** (traces: AUR-BR-001): The product shall provide a self-serve flow.
+   - **AUR-RISK-001** (threatens: AUR-BR-001): Migration may slip. Probability: High.
+     Impact: High. Owner: alex.kim. Response: dual-run for two weeks.
+   ```
+
+   Relations: `traces` (child → parent requirement), `verifies` (AC → PR/FR),
+   `tests` (TC → AC), `threatens` (RISK → BR/PR), `affects` (ADR → FR/NFR).
+   Only link items that genuinely relate in the source.
+
+6. **Flag gaps honestly.** Wherever the source does not supply required
+   information, insert a bullet or note beginning with `TODO:` describing what
+   is missing (e.g. `- TODO: no measurable success criteria found in the
+   source — add a metric and threshold.`). Do **not** fabricate a number, an
+   owner, a date, or a mitigation.
+
+7. **Validate and report.**
+
+   ```bash
+   docassert validate documents/PRJ-001-AUR/*.md
+   docassert consistency
+   ```
+
+   Summarise what passed, what blocks, and exactly which TODOs the user must
+   resolve before the document can merge.
+
+8. **Hand off.** Tell the user to review the generated files, resolve the
+   TODOs, then commit and open a pull request — CI re-runs the same audit and
+   gates the merge.
+
+## Guardrails
+
+- **Faithful over passing**: it is correct and expected for a weak source to
+  produce a document that fails the audit. That is the pipeline working.
+- Never invent approvals, owners, budgets, dates, or measurable thresholds.
+- Never mark a document `approved`; that is a human decision made in review.
+- If you are unsure whether something in the source is a real measurable
+  criterion, leave it as written and let the audit judge it.
+- Confidential sources stay local: don't push converted content to a public
+  repo without the user's say-so.

{docassert-0.2.1 → docassert-0.4.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.4.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.4.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.4.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.4.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.4.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.4.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.4.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.4.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.4.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.4.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.4.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.4.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.4.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.4.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.4.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.4.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.4.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.4.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.4.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.4.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")
@@ -83,22 +101,32 @@ def available_profiles() -> list[str]:
 
 
 # ── scaffolding (docassert init) ────────────────────────────────────────────
-_INIT_TREE = ["criteria", "schema", "profiles", "templates", "consistency.yaml"]
+# (packaged source, destination in the repo). The doc-to-pmo Claude skill lands
+# under .claude/skills/ so Claude Code discovers it in the user's repo.
+_INIT_TREE = [
+    ("criteria", "criteria"),
+    ("schema", "schema"),
+    ("profiles", "profiles"),
+    ("templates", "templates"),
+    ("consistency.yaml", "consistency.yaml"),
+    ("skills", ".claude/skills"),
+]
 
 
 def init(dest: str | Path = ".") -> list[str]:
     """Copy the packaged defaults into `dest`, skipping anything already present.
-    Returns the top-level names that were created."""
+    Returns the destination names that were created."""
     dest = Path(dest)
     created: list[str] = []
-    for name in _INIT_TREE:
-        target = dest / name
+    for src_name, dest_name in _INIT_TREE:
+        target = dest / dest_name
         if target.exists():
             continue
-        src = DATA_DIR / name
+        src = DATA_DIR / src_name
         if src.is_dir():
             shutil.copytree(src, target)
         else:
+            target.parent.mkdir(parents=True, exist_ok=True)
             target.write_text(src.read_text(encoding="utf-8"), encoding="utf-8")
-        created.append(name)
+        created.append(dest_name)
     return created

docassert-0.4.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.4.0/docassert.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docassert
-Version: 0.2.1
+Version: 0.4.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
@@ -74,7 +75,11 @@ docassert pages --out _site           # a portfolio dashboard + a page per proje
 Config resolves **local override → packaged default**: docassert ships sensible
 defaults, and your repo's own `criteria/` (or `schema/`, `profiles/`,
 `consistency.yaml`) wins when present. `docassert init` copies the defaults in so
-you can customize them.
+you can customize them — including the **doc-to-pmo Claude skill** into
+`.claude/skills/`, so Claude Code in your repo knows how to convert existing
+Word/PDF documents into testable docassert documents (faithfully — gaps are
+flagged as TODOs, never invented). The skill's source is
+[`skills/doc-to-pmo/SKILL.md`](skills/doc-to-pmo/SKILL.md).
 
 ## Commands
 
@@ -86,6 +91,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.4.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
@@ -68,6 +69,7 @@ docassert/_data/schema/runbook.schema.json
 docassert/_data/schema/status-report.schema.json
 docassert/_data/schema/test-cases.schema.json
 docassert/_data/schema/user-story.schema.json
+docassert/_data/skills/doc-to-pmo/SKILL.md
 docassert/_data/templates/adr.template.md
 docassert/_data/templates/benefits-realization.template.md
 docassert/_data/templates/brd.template.md
@@ -99,5 +101,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.2.1 → docassert-0.4.0}/tests/test_config.py

@@ -23,6 +23,9 @@ def test_packaged_data_mirrors_root_config():
                 f"{name}/{fn} drifted between the repo root and packaged _data"
     assert filecmp.cmp(ROOT / "consistency.yaml",
                        config.DATA_DIR / "consistency.yaml", shallow=False)
+    assert filecmp.cmp(ROOT / "skills" / "doc-to-pmo" / "SKILL.md",
+                       config.DATA_DIR / "skills" / "doc-to-pmo" / "SKILL.md",
+                       shallow=False), "doc-to-pmo skill drifted between root and packaged copy"
 
 
 # ── resolution: packaged default when there's no local config ───────────────
@@ -52,8 +55,19 @@ def test_unknown_kind_raises(monkeypatch, tmp_path):
 # ── init scaffolds, and is idempotent ──────────────────────────────────────
 def test_init_scaffolds_defaults(tmp_path):
     created = config.init(tmp_path)
-    assert set(created) == {"criteria", "schema", "profiles", "templates", "consistency.yaml"}
+    assert set(created) == {"criteria", "schema", "profiles", "templates",
+                            "consistency.yaml", ".claude/skills"}
     assert (tmp_path / "criteria" / "charter.criteria.yaml").is_file()
     assert (tmp_path / "schema" / "project.schema.json").is_file()
     assert (tmp_path / "consistency.yaml").is_file()
+    assert (tmp_path / ".claude" / "skills" / "doc-to-pmo" / "SKILL.md").is_file()
     assert config.init(tmp_path) == []  # second run creates nothing
+
+
+def test_init_keeps_existing_skills(tmp_path):
+    mine = tmp_path / ".claude" / "skills"
+    mine.mkdir(parents=True)
+    (mine / "my-skill.md").write_text("mine", encoding="utf-8")
+    created = config.init(tmp_path)
+    assert ".claude/skills" not in created          # existing dir left alone
+    assert (mine / "my-skill.md").read_text() == "mine"

docassert-0.4.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