docassert 0.3.0__tar.gz → 0.4.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docassert
-Version: 0.3.0
+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
@@ -75,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
 

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

@@ -37,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
 

{docassert-0.3.0 → 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.3.0"
+__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.3.0 → docassert-0.4.0}/docassert/config.py

@@ -101,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.3.0 → docassert-0.4.0/docassert.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docassert
-Version: 0.3.0
+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
@@ -75,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
 

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

@@ -69,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

{docassert-0.3.0 → 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"