knowme-careerforge-skill 0.0.4 → 0.0.7

package/scripts/evidence/extract-evidence.py

@@ -225,86 +225,133 @@ def scan_repo(repo_path: Path) -> Dict[str, Any]:
     return facts
 
 def build_master_profile(facts: Dict[str, Any], user_overrides: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+    """Build structured candidate profile from codebase facts + optional user overrides.
+
+    Placeholder discipline:
+    - repo_mode=True : facts dict is populated from real repo scan; safe to synthesize
+      experience/education skeletons because they'll be user-reviewed before use.
+    - repo_mode=False: only user_overrides carry real data. NEVER emit fabricated placeholder
+      strings (fake company, fake school, fake dates). Use null / empty list instead.
+    """
     overrides = user_overrides or {}
     author = facts.get("author_info", {})
-    
-    name = overrides.get("name") or author.get("name") or "求职者"
-    title = overrides.get("title") or "资深工程师 / 技术专家"
-    email = overrides.get("email") or author.get("email") or "candidate@example.com"
-    phone = overrides.get("phone") or "138-0000-0000"
-    github = overrides.get("github") or author.get("git_remote") or "https://github.com"
-    
+    repo_mode: bool = bool(facts.get("detected_tech_stacks") or facts.get("evidence_items"))
+
+    # ── Basics ────────────────────────────────────────────────────────────────
+    name  = overrides.get("name")  or author.get("name")  or (None if not repo_mode else "候选人")
+    title = overrides.get("title") or (None if not repo_mode else "资深工程师 / 技术专家")
+    email = overrides.get("email") or author.get("email") or (None if not repo_mode else "candidate@example.com")
+    phone = overrides.get("phone") or (None if not repo_mode else None)
+    github = overrides.get("github") or author.get("git_remote") or None
+    location = overrides.get("location") or (None if not repo_mode else None)
+
     tech_stacks = facts.get("detected_tech_stacks", [])
-    languages = list(facts.get("detected_languages", {}).keys())
-
-    profile = {
-        "basics": {
-            "name": name,
-            "title": title,
-            "email": email,
-            "phone": phone,
-            "location": overrides.get("location") or "北京 / 远程",
-            "github": github,
-            "summary": f"拥有坚实的技术研发与工程化落地实战经验，主导过多个基于 {', '.join((tech_stacks + languages)[:3])} 的核心系统设计与交付。"
-        },
-        "skills": [
-            {
-                "category": "核心技术栈",
-                "items": tech_stacks if tech_stacks else ["Python", "TypeScript", "FastAPI", "React", "Docker"],
-                "highlighted": tech_stacks[:4]
-            },
-            {
-                "category": "工程化与架构",
-                "items": facts.get("architectural_signals", ["CI/CD", "微服务架构", "自动化测试", "性能优化"]),
-                "highlighted": ["CI/CD", "性能优化"]
-            }
-        ],
-        "experience": [
+    languages   = list(facts.get("detected_languages", {}).keys())
+
+    # ── Skills ────────────────────────────────────────────────────────────────
+    all_tech = tech_stacks + [l for l in languages if l not in tech_stacks]
+    arch_signals = facts.get("architectural_signals", [])
+    skills: list = []
+    if all_tech:
+        skills.append({"category": "核心技术栈", "items": all_tech, "highlighted": all_tech[:4]})
+    if arch_signals:
+        skills.append({"category": "工程化与架构", "items": arch_signals, "highlighted": arch_signals[:2]})
+
+    # ── Experience ────────────────────────────────────────────────────────────
+    bullets = [
+        {
+            "text": item["claim"],
+            "evidenceLevel": item["evidenceLevel"],
+            "evidenceSource": item["evidenceSource"],
+            "keywords": item.get("keywords", [])
+        }
+        for item in facts.get("evidence_items", [])
+    ]
+
+    if repo_mode and bullets:
+        # Repo mode: synthesize a single experience entry from code evidence.
+        # Company / dates are placeholders that the user MUST review.
+        experience = [
             {
-                "company": overrides.get("company") or "创新科技企业",
-                "role": title,
-                "startDate": "2022.06",
-                "endDate": "至今",
-                "location": "北京",
+                "company": overrides.get("company") or "[请填写：公司名称]",
+                "role": title or "[请填写：职位名称]",
+                "startDate": overrides.get("startDate") or "[请填写：开始时间]",
+                "endDate": overrides.get("endDate") or "至今",
+                "location": location or "[请填写：工作地点]",
                 "summary": "负责核心产品研发与关键架构攻坚",
-                "bullets": [
-                    {
-                        "text": item["claim"],
-                        "evidenceLevel": item["evidenceLevel"],
-                        "evidenceSource": item["evidenceSource"],
-                        "keywords": item["keywords"]
-                    }
-                    for item in facts.get("evidence_items", [])
-                ]
+                "bullets": bullets
             }
-        ],
-        "projects": [
+        ]
+    elif overrides.get("experience"):
+        experience = overrides["experience"]
+    else:
+        experience = []
+
+    # ── Projects ──────────────────────────────────────────────────────────────
+    if repo_mode and tech_stacks:
+        projects = [
             {
-                "name": facts.get("repo_name", "CoreSystem"),
+                "name": facts.get("repo_name") or "[请填写：项目名称]",
                 "role": "核心负责人 / 主力开发者",
                 "techStack": tech_stacks[:5],
                 "repoUrl": github,
-                "startDate": "2023.01",
+                "startDate": "[请填写：开始时间]",
                 "endDate": "至今",
                 "bullets": [
-                    {
-                        "text": item["claim"],
-                        "evidenceLevel": item["evidenceLevel"],
-                        "evidenceSource": item["evidenceSource"]
-                    }
+                    {"text": item["claim"], "evidenceLevel": item["evidenceLevel"], "evidenceSource": item["evidenceSource"]}
                     for item in facts.get("evidence_items", [])
                 ]
             }
-        ],
-        "education": [
+        ]
+    elif overrides.get("projects"):
+        projects = overrides["projects"]
+    else:
+        projects = []
+
+    # ── Education ─────────────────────────────────────────────────────────────
+    if overrides.get("education"):
+        education = overrides["education"]
+    elif overrides.get("school") or overrides.get("degree"):
+        education = [
+            {
+                "institution": overrides.get("school") or "[请填写：学校名称]",
+                "degree": overrides.get("degree") or "[请填写：学历与专业]",
+                "startDate": overrides.get("edu_start") or "[请填写：入学时间]",
+                "endDate": overrides.get("edu_end") or "[请填写：毕业时间]"
+            }
+        ]
+    elif repo_mode:
+        # Repo mode: emit a reminder skeleton so the user knows to fill it in.
+        education = [
             {
-                "institution": overrides.get("school") or "重点大学",
-                "degree": overrides.get("degree") or "计算机科学与技术 本科",
-                "startDate": "2016.09",
-                "endDate": "2020.06"
+                "institution": "[请填写：学校名称]",
+                "degree": "[请填写：学历与专业]",
+                "startDate": "[请填写：入学时间]",
+                "endDate": "[请填写：毕业时间]"
             }
         ]
-    }
+    else:
+        education = []
+
+    # ── Assemble ──────────────────────────────────────────────────────────────
+    basics: Dict[str, Any] = {}
+    if name:    basics["name"]     = name
+    if title:   basics["title"]    = title
+    if email:   basics["email"]    = email
+    if phone:   basics["phone"]    = phone
+    if location: basics["location"] = location
+    if github:  basics["github"]   = github
+    if all_tech:
+        basics["summary"] = (
+            f"拥有坚实的技术研发与工程化落地实战经验，"
+            f"主导过多个基于 {', '.join(all_tech[:3])} 的核心系统设计与交付。"
+        )
+
+    profile: Dict[str, Any] = {"basics": basics}
+    if skills:     profile["skills"]     = skills
+    if experience: profile["experience"] = experience
+    if projects:   profile["projects"]   = projects
+    if education:  profile["education"]  = education
     return profile
 
 def main():

package/scripts/pipeline/forge.py

@@ -1,142 +1,282 @@
 #!/usr/bin/env python3
-"""
-KnowMe CareerForge — Unified End-to-End Forge Engine
-一键打通：代码仓事实挖掘 (repo-to-resume) ➔ JD 深度解析 ➔ 多维模板检索 ➔ HTML 工作区装配 ➔ Dual-QA 质检 ➔ 确定性 PDF 导出。
-"""
-
-import sys, os, json, argparse, subprocess
+"""Run an isolated user-input resume build with explicit artifact and QA states."""
+import argparse
+import contextlib
+import copy
+import hashlib
+import importlib.util
+import io
+import json
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+import uuid
+from datetime import datetime, timezone
 from pathlib import Path
 
-def get_project_root() -> Path:
-    curr = Path(__file__).resolve().parent
-    for _ in range(5):
-        if (curr / "SKILL.md").exists() or (curr / "package.json").exists():
-            return curr
-        curr = curr.parent
-    return Path.cwd()
+ROOT = Path(__file__).resolve().parents[2]
 
-def main():
-    parser = argparse.ArgumentParser(description="KnowMe CareerForge — One-Shot Unified Forge Engine")
-    parser.add_argument("--repo", "-r", default=".", help="Target code repository path (default: current directory)")
-    parser.add_argument("--role", help="Target job title / role (e.g. 'AI Agent Engineer', '资深前端专家')")
-    parser.add_argument("--jd", help="Path to JD file or raw JD text")
-    parser.add_argument("--template", "-t", default="minimal", help="Template ID (minimal, modern, executive, classic)")
-    parser.add_argument("--name", help="Candidate full name override")
-    parser.add_argument("--email", help="Candidate email override")
-    parser.add_argument("--phone", help="Candidate phone override")
-    parser.add_argument("--output", "-o", default="workspace/resume.pdf", help="Output PDF file path")
-    parser.add_argument("--html-output", default="workspace/resume.html", help="Intermediate working canvas HTML path")
-    parser.add_argument("--quiet", "-q", action="store_true", help="Quiet mode (compact JSON output for AI Agent)")
 
-    args = parser.parse_args()
-    root = get_project_root()
-    scripts_dir = root / "scripts"
-
-    if not args.quiet:
-        print("==============================================================")
-        print("  KnowMe CareerForge — One-Shot Resume Engineering Pipeline")
-        print(f"  Target Role : {args.role or 'Auto-Detect'}")
-        print(f"  Repo Source : {args.repo}")
-        print(f"  Template    : {args.template}")
-        print("==============================================================")
-
-    # 1. 证据挖掘 (Stage 1: Evidence Mining)
-    evidence_json = Path("workspace/evidence-master.json")
-    
-    extract_script = scripts_dir / "evidence" / "extract-evidence.py"
-    if not extract_script.exists():
-        extract_script = scripts_dir / "extract-evidence.py"
-
-    evidence_cmd = [sys.executable, str(extract_script), "--repo", args.repo, "--output", str(evidence_json), "--quiet"]
-    if args.name: evidence_cmd.extend(["--name", args.name])
-    if args.role: evidence_cmd.extend(["--role", args.role])
-    if args.email: evidence_cmd.extend(["--email", args.email])
-    if args.phone: evidence_cmd.extend(["--phone", args.phone])
-
-    subprocess.run(evidence_cmd, check=True)
-    if not args.quiet:
-        print("[✓] Stage 1: Codebase evidence mined -> workspace/evidence-master.json")
-
-    # 2. JD 分析与关键词提取 (Stage 2: JD Analysis)
-    keywords = []
-    if args.jd:
-        try:
-            analyze_script = scripts_dir / "evidence" / "analyze-jd.py"
-            if not analyze_script.exists():
-                analyze_script = scripts_dir / "analyze-jd.py"
-
-            jd_cmd = [sys.executable, str(analyze_script)]
-            if Path(args.jd).exists():
-                jd_cmd.extend(["--jd", args.jd])
+def load_module(name, relative):
+    spec = importlib.util.spec_from_file_location(name, ROOT / 'scripts' / relative)
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+contract = load_module('profile_contract', 'contracts/profile.py')
+
+
+def atomic_write(path, data):
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, temp = tempfile.mkstemp(prefix='.' + path.name + '-', dir=path.parent)
+    try:
+        with os.fdopen(fd, 'wb') as stream:
+            stream.write(data if isinstance(data, bytes) else data.encode('utf-8'))
+        os.replace(temp, path)
+    finally:
+        if os.path.exists(temp):
+            os.unlink(temp)
+
+
+def write_json(path, value):
+    atomic_write(path, json.dumps(value, ensure_ascii=False, indent=2) + '\n')
+
+
+def file_hash(path):
+    return hashlib.sha256(Path(path).read_bytes()).hexdigest()
+
+
+def publish_aliases(pairs):
+    """Stage every requested copy before publishing; rollback ordinary write failures.
+
+    The run directory remains canonical. Lock files reject concurrent publishers
+    to the same requested destination instead of interleaving their outputs.
+    """
+    staged, locks, replaced = [], [], []
+    try:
+        for source, target in pairs:
+            target.parent.mkdir(parents=True, exist_ok=True)
+            lock = target.with_name('.' + target.name + '.knowme-lock')
+            fd = os.open(lock, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)
+            os.close(fd)
+            locks.append(lock)
+            if target.exists() and not target.is_file():
+                raise ValueError('Output is not a regular file: ' + str(target))
+            backup = target.read_bytes() if target.exists() else None
+            fd, temp = tempfile.mkstemp(prefix='.knowme-export-', dir=target.parent)
+            os.close(fd)
+            staged.append((Path(temp), target, backup))
+            shutil.copyfile(source, temp)
+        for temp, target, backup in staged:
+            os.replace(temp, target)
+            replaced.append((target, backup))
+    except Exception:
+        for target, backup in reversed(replaced):
+            if backup is None:
+                target.unlink(missing_ok=True)
             else:
-                jd_cmd.extend(["--text", args.jd])
-            jd_res = subprocess.run(jd_cmd, stdout=subprocess.PIPE, text=True, check=True)
-            for line in jd_res.stdout.splitlines():
-                if "Must-have Skills" in line or "Detected" in line:
-                    parts = line.split(":")[-1].strip().split(",")
-                    keywords.extend([p.strip() for p in parts if p.strip()])
-        except Exception:
-            pass
-
-    # 3. 模板装配到工作区 (Stage 3 & 4: Template Instantiation)
-    kw_arg = ",".join(keywords[:8]) if keywords else "TypeScript,Playwright,Python,Docker"
-    
-    instantiate_script = scripts_dir / "template" / "instantiate-resume.py"
-    if not instantiate_script.exists():
-        instantiate_script = scripts_dir / "instantiate-resume.py"
-
-    instantiate_cmd = [
-        sys.executable, str(instantiate_script),
-        "--template", args.template,
-        "--profile", str(evidence_json),
-        "--keywords", kw_arg,
-        "--output", args.html_output
-    ]
-    subprocess.run(instantiate_cmd, stdout=subprocess.DEVNULL if args.quiet else None, check=True)
-    if not args.quiet:
-        print(f"[✓] Stage 2: HTML Working Canvas instantiated -> {args.html_output}")
-
-    # 4. 质检与自愈校验 (Stage 5: Dual QA Validation)
-    val_script = scripts_dir / "validation" / "validate-resume.py"
-    if not val_script.exists():
-        val_script = scripts_dir / "validate-resume.py"
-
-    validator_cmd = [
-        sys.executable, str(val_script),
-        args.html_output
-    ]
-    subprocess.run(validator_cmd, stdout=subprocess.DEVNULL if args.quiet else None, check=True)
-    if not args.quiet:
-        print("[✓] Stage 3: Dual QA Validation Passed 100%")
-
-    # 5. 确定性渲染导出 PDF (Stage 6: PDF Export)
-    render_script = scripts_dir / "rendering" / "render-pdf.py"
-    if not render_script.exists():
-        render_script = scripts_dir / "render-pdf.py"
-
-    render_cmd = [
-        sys.executable, str(render_script),
-        args.html_output, args.output
-    ]
-    if args.quiet:
-        render_cmd.append("--quiet")
-    subprocess.run(render_cmd, check=True)
-
-    if not args.quiet:
-        print("==============================================================")
-        print(f"  [✓] ALL STAGES COMPLETED SUCCESSFULLY!")
-        print(f"  HTML Working Canvas : {Path(args.html_output).resolve()}")
-        print(f"  Final Verified PDF  : {Path(args.output).resolve()}")
-        print("==============================================================")
-    else:
-        result = {
-            "status": "SUCCESS",
-            "htmlCanvas": str(Path(args.html_output).resolve()),
-            "pdfDelivery": str(Path(args.output).resolve()),
-            "evidenceProfile": str(evidence_json.resolve()),
-            "templateUsed": args.template
-        }
-        print(json.dumps(result, ensure_ascii=False, indent=2))
-
-if __name__ == "__main__":
-    main()
+                atomic_write(target, backup)
+        raise
+    finally:
+        for temp, _, _ in staged:
+            temp.unlink(missing_ok=True)
+        for lock in locks:
+            lock.unlink(missing_ok=True)
+
+
+class Parser(argparse.ArgumentParser):
+    def error(self, message):
+        print(json.dumps({'status': 'FAIL', 'stage': 'arguments', 'errors': [message],
+                          'warnings': [], 'checks': {}, 'outputs': {}}, ensure_ascii=False))
+        self.exit(1)
+
+
+def main():
+    parser = Parser(description=__doc__)
+    parser.add_argument('--profile-json', required=True, help='User/Agent supplied facts or Draft/Master document; never a repository')
+    parser.add_argument('--workspace', default='workspace/runs', help='Parent directory for unique run directories')
+    parser.add_argument('--draft', action='store_true', help='Create an incomplete draft canvas without claiming PDF delivery')
+    parser.add_argument('--role')
+    parser.add_argument('--jd', help='Optional JD path or inline text; used only as highlighting/search hints')
+    parser.add_argument('--template', '-t')
+    parser.add_argument('--font-preset', choices=('system', 'arial-unicode'), default='system', help='Explicit local font choice; missing fonts fail verification')
+    for key in ('name', 'email', 'phone'):
+        parser.add_argument('--' + key)
+    parser.add_argument('--output', '-o', help='Optional verified PDF copy; default is the isolated run PDF')
+    parser.add_argument('--html-output', help='Optional verified HTML copy; default is the isolated run canvas')
+    parser.add_argument('--expected-pages', type=int, choices=(1, 2), default=1)
+    parser.add_argument('--auto-heal', action='store_true')
+    parser.add_argument('--quiet', '-q', action='store_true')
+    parser.add_argument('--summary', action='store_true', help='Compact report with manifest path; full diagnostics stay on disk')
+    args = parser.parse_args()
+    report = {'schemaVersion': '1.0', 'runId': uuid.uuid4().hex, 'status': 'RUNNING',
+              'stage': 'input', 'errors': [], 'warnings': [], 'checks': {}, 'outputs': {}}
+    run = None
+    exit_code = 1
+    try:
+        parent = Path(args.workspace).resolve()
+        parent.mkdir(parents=True, exist_ok=True)
+        run = parent / report['runId']
+        run.mkdir(mode=0o700)
+        report['runDirectory'] = str(run)
+        report['startedAt'] = datetime.now(timezone.utc).isoformat()
+        write_json(run / 'manifest.json', report)
+        source = Path(args.profile_json).resolve()
+        aliases = [Path(p).resolve() for p in (args.html_output, args.output) if p]
+        if len(set([source] + aliases)) != len([source] + aliases):
+            raise ValueError('Input, HTML and PDF output paths must be distinct')
+        for target in aliases:
+            if target == run or run in target.parents:
+                raise ValueError('Explicit output cannot replace an internal run artifact')
+        raw_bytes = source.read_bytes()
+        atomic_write(run / 'input.json', raw_bytes)
+        supplied = contract.load_document(json.loads(raw_bytes))
+        if supplied['kind'] == 'variant':
+            raise ValueError('A Variant is not a Master; use its original Master to derive another resume')
+        if supplied['kind'] == 'draft' and not args.draft:
+            raise ValueError('Draft input cannot be delivered; review facts and provide a Master, or use --draft')
+        facts = copy.deepcopy(supplied['profile'])
+        for key in ('name', 'email', 'phone'):
+            if getattr(args, key) is not None:
+                facts['basics'][key] = getattr(args, key)
+        kind = 'draft' if args.draft else 'master'
+        master = contract.document(kind, facts, {'type': 'user-input', 'path': str(source),
+                     'inputSha256': hashlib.sha256(raw_bytes).hexdigest(),
+                     'suppliedKind': supplied['kind'], 'suppliedSource': supplied['source']})
+        write_json(run / (kind + '.json'), master)
+        report['checks']['missingFields'] = master['missingFields']
+        report['warnings'].extend('Missing optional contact/position field: ' + v for v in master['missingFields'] if v != 'basics.name')
+        if not args.draft:
+            errors = contract.delivery_errors(master['profile'])
+            if errors:
+                raise ValueError('; '.join(errors))
+        profile = copy.deepcopy(master['profile'])
+        if args.role is not None:
+            profile['basics']['title'] = args.role
+        keywords = []
+        if args.jd:
+            report['stage'] = 'jd'
+            try:
+                jd_file = Path(args.jd)
+                jd = jd_file.read_text(encoding='utf-8') if jd_file.is_file() else args.jd
+            except OSError:
+                jd = args.jd
+            atomic_write(run / 'jd.txt', jd)
+            analyzer = load_module('jd_analyzer', 'evidence/analyze-jd.py')
+            with contextlib.redirect_stdout(io.StringIO()):
+                result = analyzer.analyze_jd_text(jd)
+            write_json(run / 'jd-analysis.json', result)
+            keywords = result.get('detectedSkills', [])
+        report['stage'] = 'template'
+        template = args.template
+        if not template:
+            search = load_module('template_search', 'template/search-template.py')
+            with contextlib.redirect_stdout(io.StringIO()):
+                results = search.search_templates(role=args.role or profile['basics'].get('title') or '',
+                                                  keywords=','.join(keywords), target_pages=args.expected_pages, engine='hybrid')
+            if not results:
+                raise ValueError('No matching template available')
+            template = results[0].get('id') or results[0]['template']['id']
+        variant = contract.document('draft' if args.draft else 'variant', profile,
+                     {'masterSha256': master['profileSha256'], 'masterPath': str(run / (kind + '.json')),
+                      'template': template, 'targetRole': args.role, 'fontPreset': args.font_preset})
+        variant_path = run / ('draft-canvas-profile.json' if args.draft else 'variant.json')
+        write_json(variant_path, variant)
+        report['templateUsed'] = template
+        report['fontPreset'] = args.font_preset
+        report['stage'] = 'binding'
+        inst = load_module('instantiate_resume', 'template/instantiate-resume.py')
+        canvas, pdf = run / 'resume.html', run / 'resume.pdf'
+        with contextlib.redirect_stdout(io.StringIO()):
+            inst.instantiate_workspace(template, str(variant_path), ','.join(keywords), str(canvas), font_preset=args.font_preset)
+        if args.draft:
+            report.update(status='DRAFT', stage='draft', outputs={'draft': str(run / 'draft.json'), 'htmlCanvas': str(canvas)})
+            exit_code = 0
+        else:
+            report['stage'] = 'qa'
+            cmd = ['node', str(ROOT / 'scripts/rendering/browser-engine.js'), str(canvas),
+                   '--expected-pages', str(args.expected_pages), '--output', str(pdf)]
+            if args.auto_heal:
+                cmd.append('--auto-heal')
+            process = subprocess.run(cmd, capture_output=True, text=True, timeout=120)
+            try:
+                qa = json.loads(process.stdout)
+                if not isinstance(qa, dict):
+                    raise ValueError('QA result must be an object')
+                expected_exit = {'PASS': 0, 'FAIL': 1, 'UNVERIFIED': 2}.get(qa.get('status'))
+                if expected_exit is None or process.returncode != expected_exit:
+                    raise ValueError('QA status and exit code disagree')
+                if (not isinstance(qa.get('checks'), dict)
+                        or any(not isinstance(v, dict) for v in qa['checks'].values())
+                        or any(not isinstance(qa.get(key), list) or any(not isinstance(v, str) for v in qa[key])
+                               for key in ('errors', 'warnings'))):
+                    raise ValueError('Malformed QA diagnostics')
+            except (ValueError, TypeError) as error:
+                report['status'] = 'UNVERIFIED'
+                raise ValueError('Browser returned no valid QA result: ' + str(error) + '; ' + process.stderr[:400])
+            write_json(run / 'qa.json', qa)
+            report['checks']['qa'] = qa
+            report['warnings'].extend(qa.get('warnings', []))
+            if process.returncode != 0 or qa.get('status') != 'PASS':
+                report['status'] = 'UNVERIFIED' if qa.get('status') == 'UNVERIFIED' else 'FAIL'
+                raise ValueError('; '.join(qa.get('errors', [])) or 'PDF validation did not pass')
+            checks = qa.get('checks', {})
+            required_checks = ('input', 'fonts', 'dom', 'pdf', 'text', 'output')
+            if qa.get('errors') or any(checks.get(key, {}).get('status') != 'PASS' for key in required_checks):
+                report['status'] = 'UNVERIFIED'
+                raise ValueError('Incomplete or contradictory QA result; refusing delivery')
+            accepted = checks['output']
+            if not accepted.get('committed') or accepted.get('path') != str(pdf):
+                report['status'] = 'UNVERIFIED'
+                raise ValueError('QA did not commit this run PDF')
+            if not pdf.is_file() or not pdf.read_bytes().startswith(b'%PDF-'):
+                raise ValueError('Verified PDF was not produced by this run')
+            if accepted.get('pdfSha256') != file_hash(pdf) or accepted.get('htmlSha256') != file_hash(canvas):
+                raise ValueError('Output changed after QA or acceptance hashes are missing')
+            report['stage'] = 'publish'
+            pairs = []
+            if args.html_output:
+                pairs.append((canvas, Path(args.html_output).resolve()))
+            if args.output:
+                pairs.append((pdf, Path(args.output).resolve()))
+            publish_aliases(pairs)
+            report.update(status='PASS', stage='complete', outputs={
+                'master': str(run / 'master.json'), 'variant': str(variant_path),
+                'htmlCanvas': str(canvas), 'pdfDelivery': str(pdf), 'qa': str(run / 'qa.json'),
+                'copies': [str(target) for _, target in pairs]},
+                sha256={'html': file_hash(canvas), 'pdf': file_hash(pdf), 'master': master['profileSha256']})
+            exit_code = 0
+    except Exception as error:
+        if report['status'] == 'RUNNING':
+            report['status'] = 'UNVERIFIED' if (report['stage'] == 'qa' and isinstance(error, (subprocess.TimeoutExpired, FileNotFoundError))) or not isinstance(error, (OSError, ValueError, TypeError, RuntimeError)) else 'FAIL'
+        report['errors'].append(str(error))
+        report['outputs'] = {}
+        exit_code = 2 if report['status'] == 'UNVERIFIED' else 1
+    finally:
+        report['finishedAt'] = datetime.now(timezone.utc).isoformat()
+        if run:
+            try:
+                write_json(run / 'manifest.json', report)
+            except OSError as error:
+                report.update(status='FAIL', outputs={})
+                report['errors'].append('Could not persist manifest: ' + str(error))
+                exit_code = 1
+        emitted = report
+        if args.summary:
+            emitted = {key: report[key] for key in ('runId', 'status', 'stage', 'templateUsed', 'fontPreset', 'errors', 'warnings', 'outputs') if key in report}
+            emitted['outputs'] = {}
+            if report['status'] in ('PASS', 'DRAFT'):
+                emitted['outputs']['html'] = str(Path(args.html_output).resolve()) if report['status'] == 'PASS' and args.html_output else report['outputs']['htmlCanvas']
+            if report['status'] == 'PASS':
+                emitted['outputs']['pdf'] = str(Path(args.output).resolve()) if args.output else report['outputs']['pdfDelivery']
+            emitted['manifest'] = str(run / 'manifest.json') if run else None
+        print(json.dumps(emitted, ensure_ascii=False, indent=None if args.quiet else 2))
+    return exit_code
+
+
+if __name__ == '__main__':
+    sys.exit(main())