From 81c6e8d73503cd213c0b61a6bda3531eb42e285f Mon Sep 17 00:00:00 2001 From: migmcc Date: Fri, 16 Oct 2026 23:36:57 +0100 Subject: [PATCH 1/8] docs: restructure README as product showcase with real demo --- README.md | 153 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 78 insertions(+), 75 deletions(-) diff --git a/README.md b/README.md index 3d8912d..99b124f 100644 --- a/README.md +++ b/README.md @@ -1,58 +1,75 @@ -# quality-docs-validator +# Quality Docs Validator + +### Catch potential inconsistencies between PFMEA and Control Plan — before technical review + +A **local-first Python CLI** for quality, process and manufacturing engineers. Compare two `.xlsx` workbooks, surface severity-classified **potential findings**, and produce Markdown or JSON reports without sending your files to a cloud service. [![CI](https://github.com/migmcc/quality-docs-validator/actions/workflows/ci.yml/badge.svg)](https://github.com/migmcc/quality-docs-validator/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) [![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/) -> Detect **potential inconsistencies between PFMEA and Control Plan** before audits, customer -> submissions or production issues — locally, with simple files, explicit rules and clear reports. +**[Quick start](#quick-start)** · **[See a real example](#see-it-in-action)** · **[What it checks](#what-it-validates)** · **[Limitations](#what-it-does-not-validate-by-design)** · **[Architecture](docs/ARCHITECTURE.md)** -`quality-docs-validator` (CLI: `qdv`) is a **local-first, forkable** tool for quality engineers. +--- -## The problem +## See it in action + +Run the **bundled synthetic example** containing deliberately seeded gaps: + +```bash +git clone https://github.com/migmcc/quality-docs-validator.git +cd quality-docs-validator +pip install -e . +qdv pfmea-control-plan \ + --pfmea examples/pfmea.xlsx \ + --control-plan examples/control-plan.xlsx \ + --out report.md +``` + +**Documented sample terminal output (abridged):** + +```text +Potential findings + UNMATCHED_PROCESS_STEP warning Op 40 + SPECIAL_CHARACTERISTIC_NOT_CONTROLLED critical Op 20 + MISSING_REACTION_PLAN critical Op 20 + WEAK_DETECTION_METHOD warning Op 20 + HIGH_SEVERITY_WEAK_CONTROL warning Op 20 + MISSING_CONTROL critical Op 30 + +Score: 43/100 Verdict: FAIL +Critical: 3 Warnings: 3 +``` -Quality documents are reviewed one at a time, but the real risk lives **between** them: a -high-severity PFMEA failure mode with no matching Control Plan control, a special characteristic -missing from the inspection plan, a missing reaction plan exactly where risk is highest. These gaps -surface late — at audits, customer submissions or as field complaints. This tool cross-checks the -two documents and surfaces those gaps as **severity-classified potential findings**. +[Read the full committed sample report →](examples/report.md) -> ⚠️ It **supports, and does not replace, human technical review.** Findings are *potential* -> inconsistencies for an engineer to judge; the tool makes no regulatory or normative conformance -> claim. +> **Important:** Findings are *potential inconsistencies* for an engineer to judge. This is **not** a regulatory or standards compliance certification and **does not replace human technical review**. + +## The problem + +A PFMEA and its Control Plan can look complete when reviewed separately while disagreeing **between** documents: an unmatched process step, a special characteristic not reflected in controls, or no reaction plan where severity is high. Those gaps deserve attention before an audit or submission. ## Who it's for -Quality / Process / Manufacturing Engineers, SQEs, internal auditors and APQP/PPAP teams — and -anyone using coding agents to automate quality workflows. Runs entirely on your machine, so -confidential supplier/customer data never leaves it. +Quality / Process / Manufacturing Engineers, supplier-quality teams, internal auditors and APQP/PPAP teams working with Excel-based documents. ## What it validates -A single module: **PFMEA ↔ Control Plan consistency checker**. - -- Reads a PFMEA `.xlsx` and a Control Plan `.xlsx` (recommended template + common header aliases — - e.g. `Operation No`, `Op #`, `Severity Rating`, `Special Characteristic`, `Reaction Plan`). -- Matches rows by `operation_id` / process step. -- Applies six explicit, documented checks (see [docs/FINDINGS.md](docs/FINDINGS.md)): - `UNMATCHED_PROCESS_STEP`, `MISSING_CONTROL`, `SPECIAL_CHARACTERISTIC_NOT_CONTROLLED`, - `MISSING_REACTION_PLAN`, `WEAK_DETECTION_METHOD` (warning), `HIGH_SEVERITY_WEAK_CONTROL` (warning). -- Computes a **severity-weighted score (0–100)** with verdict bands - (PASS / PASS-WITH-WARNINGS / NEEDS-REVIEW / FAIL). -- Generates a **Markdown report** plus a **rich terminal summary**. +The current module is a **PFMEA ↔ Control Plan consistency checker**. -## What it does *not* validate (by design) +| Capability | How it works | +| --- | --- | +| Excel input | Reads PFMEA and Control Plan `.xlsx` workbooks, with a recommended template and common header aliases. | +| Matching | Matches normalised operation IDs and process steps. | +| Six checks | Flags unmatched steps, missing controls, uncontrolled special characteristics, missing reaction plans and two warning-level weak-method heuristics. | +| Scoring | Severity-weighted 0–100 score with PASS / PASS-WITH-WARNINGS / NEEDS-REVIEW / FAIL verdicts. | +| Reports | Rich terminal summary plus Markdown or JSON, suitable for review and automation. | -- ❌ CSV / other input formats — `.xlsx` only (CSV planned for v0.2). -- ❌ Configurable column mapping — recommended template + fixed aliases only (v0.2). -- ❌ Other document pairs (Process Flow ↔ PFMEA, Work Instructions, PPAP, 8D, SPC, MSA). -- ❌ Web UI, ERP/MES/QMS integration, PDF/OCR, or any AI dependency. -- ❌ Regulatory/standard conformance certification, or replacing human judgement. +**[Read the exact finding triggers and scoring rules →](docs/FINDINGS.md)** -Scope is deliberately narrow — see [docs/MVP_SCOPE.md](docs/MVP_SCOPE.md), -[docs/DECISIONS.md](docs/DECISIONS.md) and the [roadmap](docs/ROADMAP.md). +## Quick start -## Quickstart +**Requirements:** Python 3.12+ and a local checkout of this repository. ```bash pip install -e . @@ -62,35 +79,9 @@ qdv pfmea-control-plan \ --out report.md ``` -This runs against the bundled synthetic examples (which contain a deliberately seeded gap) and -writes `report.md` plus a terminal summary. Regenerate the examples with -`python examples/generate_examples.py`. - -Expected terminal summary (abridged): - -```text - Potential findings - Type Level Op Detail - ───────────────────────────────────────────────────────────────── - UNMATCHED_PROCESS_STEP warning 40 no Control Plan row - SPECIAL_CHARACTERISTIC_NOT_CONTROLLED critical 20 not marked special in CP - MISSING_REACTION_PLAN critical 20 S=9, no reaction plan - WEAK_DETECTION_METHOD warning 20 visual inspection - HIGH_SEVERITY_WEAK_CONTROL warning 20 S=9 + weak control - MISSING_CONTROL critical 30 no control method - -╭───────────────── quality-docs-validator ─────────────────╮ -│ Score: 43/100 Verdict: FAIL Critical: 3 Warnings: 3 │ -╰───────────────────────────────────────────────────────────╯ -``` - -The full Markdown report is written to `report.md`; a committed sample lives at -[examples/report.md](examples/report.md). Finding types and scoring are documented in -[docs/FINDINGS.md](docs/FINDINGS.md). - -### JSON output +The bundled examples are synthetic and intentionally contain a gap. To regenerate them, run `python examples/generate_examples.py`. -For automation, emit a machine-readable report with `--format json`: +### JSON output for automation ```bash qdv pfmea-control-plan \ @@ -99,13 +90,9 @@ qdv pfmea-control-plan \ --format json --out report.json ``` -Markdown remains the default. The JSON contains `metadata` (tool, version, UTC timestamp), -`verdict`, `score`, a `summary` (counts by severity and by finding type) and the full `findings` -list. +The JSON report includes metadata, verdict, score, summary and findings. -### Multi-sheet workbooks - -If a workbook has several sheets, pick the right one by name (otherwise the active sheet is used): +### Select sheets in multi-sheet workbooks ```bash qdv pfmea-control-plan \ @@ -114,12 +101,28 @@ qdv pfmea-control-plan \ --out report.md ``` -If the named sheet does not exist, the error lists the available sheet names. +If a specified sheet does not exist, the error lists available sheet names. + +## What it does not validate (by design) + +- Formats other than `.xlsx`; CSV is not currently supported. +- Arbitrary column mapping beyond the recommended template and supported aliases. +- Other document pairs (Process Flow, Work Instructions, PPAP, 8D, SPC, MSA). +- Web interface, ERP / MES / QMS integration, PDF / OCR or AI-based interpretation. +- Regulatory conformity, audit certification or replacements for engineering judgement. + +See [scope](docs/MVP_SCOPE.md), [decisions](docs/DECISIONS.md) and [roadmap](docs/ROADMAP.md). + +## How it works + +`PFMEA.xlsx + Control Plan.xlsx → operation matching → six checks → scoring → terminal / Markdown / JSON` -## Architecture +The rules and scoring are explicitly documented and testable rather than based on an LLM. For implementation details, see [architecture](docs/ARCHITECTURE.md) and [finding reference](docs/FINDINGS.md). -See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the module layout and data flow. +## Get involved -## License +- [Explore the repository](https://github.com/migmcc/quality-docs-validator) +- [Open an issue](https://github.com/migmcc/quality-docs-validator/issues) +- [Contribute](CONTRIBUTING.md) -[MIT](LICENSE). Contributions welcome — see [CONTRIBUTING.md](CONTRIBUTING.md). +Licensed under [MIT](LICENSE). From fc6a5850e457de22c389d273770fbf6a33ce697f Mon Sep 17 00:00:00 2001 From: migmcc Date: Fri, 16 Oct 2026 23:47:16 +0100 Subject: [PATCH 2/8] docs: add accurate visual diagram for README showcase --- docs/assets/validation-flow.svg | 1 + 1 file changed, 1 insertion(+) create mode 100644 docs/assets/validation-flow.svg diff --git a/docs/assets/validation-flow.svg b/docs/assets/validation-flow.svg new file mode 100644 index 0000000..a8b2723 --- /dev/null +++ b/docs/assets/validation-flow.svg @@ -0,0 +1 @@ +Quality Docs Validator workflowPFMEA and Control Plan workbooks feed a deterministic six-rule checker, which generates severity-classified potential findings for a human engineer.PFMEA ↔ Control Plan consistency checksPFMEA.xlsx workbookControl Plan.xlsx workbook6 explicit checksOperation matchingSeverity-weighted scorePotential findingsMarkdown · JSONTerminal summaryHuman reviewEngineer judgesthe findingsConceptual workflow diagram — not an application screenshot or compliance certification. \ No newline at end of file From a28642b5c110df28372b1bab9caa3e34a7dc5b31 Mon Sep 17 00:00:00 2001 From: migmcc Date: Fri, 16 Oct 2026 23:47:26 +0100 Subject: [PATCH 3/8] docs: embed accessible visual hero in showcase README --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index 99b124f..3c566d3 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,8 @@ ### Catch potential inconsistencies between PFMEA and Control Plan — before technical review +![Workflow diagram: PFMEA and Control Plan XLSX files are checked against six explicit rules, then reviewed by a human engineer](docs/assets/validation-flow.svg) + A **local-first Python CLI** for quality, process and manufacturing engineers. Compare two `.xlsx` workbooks, surface severity-classified **potential findings**, and produce Markdown or JSON reports without sending your files to a cloud service. [![CI](https://github.com/migmcc/quality-docs-validator/actions/workflows/ci.yml/badge.svg)](https://github.com/migmcc/quality-docs-validator/actions/workflows/ci.yml) From 26fa5efba88c5dfa7a77c5321a9fe0caf5c5f343 Mon Sep 17 00:00:00 2001 From: migmcc Date: Fri, 16 Oct 2026 23:56:35 +0100 Subject: [PATCH 4/8] docs: show accurate synthetic sample output in illustrated terminal --- docs/assets/example-output.svg | 1 + 1 file changed, 1 insertion(+) create mode 100644 docs/assets/example-output.svg diff --git a/docs/assets/example-output.svg b/docs/assets/example-output.svg new file mode 100644 index 0000000..7e44ed7 --- /dev/null +++ b/docs/assets/example-output.svg @@ -0,0 +1 @@ +Quality Docs Validator sample terminal resultDocumented synthetic example shows six potential findings, score 43 out of 100, FAIL, three critical and three warning findings.qdv · synthetic sample outputPotential findingsTYPELEVELOPUNMATCHED_PROCESS_STEPwarning40SPECIAL_CHARACTERISTIC_NOT_CONTROLLEDcritical20MISSING_REACTION_PLANcritical20WEAK_DETECTION_METHODwarning20HIGH_SEVERITY_WEAK_CONTROLwarning20MISSING_CONTROLcritical30Score: 43/100 | Verdict: FAIL | Critical: 3 | Warnings: 3Illustration reconstructed from the committed example report; not an actual terminal screenshot. \ No newline at end of file From 375925a24ed6470990a0d14c803959d32f087f8b Mon Sep 17 00:00:00 2001 From: migmcc Date: Fri, 16 Oct 2026 23:56:41 +0100 Subject: [PATCH 5/8] docs: feature authentic sample results prominently --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index 3c566d3..d15f8fe 100644 --- a/README.md +++ b/README.md @@ -28,6 +28,8 @@ qdv pfmea-control-plan \ --out report.md ``` +![Illustrated terminal output from bundled synthetic example: 43/100, FAIL, three critical and three warnings](docs/assets/example-output.svg) + **Documented sample terminal output (abridged):** ```text From 5ab5ce981a4f930e9cf36a2583bca8a14d03a758 Mon Sep 17 00:00:00 2001 From: migmcc Date: Sat, 17 Oct 2026 00:03:44 +0100 Subject: [PATCH 6/8] fix: clear Ruff CI errors without changing CLI behavior --- pyproject.toml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/pyproject.toml b/pyproject.toml index 98e9398..d320868 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -58,3 +58,7 @@ addopts = "-q" line-length = 100 target-version = "py312" src = ["src", "tests"] + +[tool.ruff.lint.per-file-ignores] +# Typer declares CLI arguments with Option(...) defaults by design. +"src/quality_docs_validator/cli.py" = ["B008"] From bed584e7c5cc2cf092cf369de13fdd03fd52c270 Mon Sep 17 00:00:00 2001 From: migmcc Date: Sat, 17 Oct 2026 00:03:47 +0100 Subject: [PATCH 7/8] fix: clear Ruff CI errors without changing CLI behavior --- src/quality_docs_validator/core/report.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/quality_docs_validator/core/report.py b/src/quality_docs_validator/core/report.py index 516cc4f..3057902 100644 --- a/src/quality_docs_validator/core/report.py +++ b/src/quality_docs_validator/core/report.py @@ -9,7 +9,7 @@ import json from collections import Counter -from datetime import datetime, timezone +from datetime import UTC, datetime from pathlib import Path from rich.console import Console @@ -36,7 +36,7 @@ def render_markdown(result: ValidationResult, pfmea_name: str, control_plan_name: str) -> str: - generated = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M UTC") + generated = datetime.now(UTC).strftime("%Y-%m-%d %H:%M UTC") lines: list[str] = [] lines.append("# PFMEA ↔ Control Plan Validation Report") lines.append("") @@ -93,7 +93,7 @@ def build_report_data( "metadata": { "tool": TOOL_NAME, "version": __version__, - "generated_at": datetime.now(timezone.utc).isoformat(), + "generated_at": datetime.now(UTC).isoformat(), "format": "json", }, "inputs": { From 7f2acc3796af7724bfc11e32f31e3c78738b456d Mon Sep 17 00:00:00 2001 From: migmcc Date: Sat, 17 Oct 2026 00:03:50 +0100 Subject: [PATCH 8/8] fix: clear Ruff CI errors without changing CLI behavior --- tests/test_json_output.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/test_json_output.py b/tests/test_json_output.py index 375d8f1..206f1d4 100644 --- a/tests/test_json_output.py +++ b/tests/test_json_output.py @@ -55,7 +55,7 @@ def test_json_generated_with_flag(example_files, tmp_path: Path) -> None: assert out.exists() # Parseable JSON. data = json.loads(out.read_text(encoding="utf-8")) - assert set(["metadata", "verdict", "score", "summary", "findings"]) <= set(data) + assert {"metadata", "verdict", "score", "summary", "findings"} <= set(data) def test_json_metadata_shape(example_files, tmp_path: Path) -> None: