pi-maestro-flow 0.2.0

package/skills/scholar-thesis-docx/references/failure-patterns-and-quality-gates.md

@@ -0,0 +1,178 @@
+# Failure Patterns and Quality Gates
+
+Use this reference before bulk thesis formatting and before claiming the
+document is fully checked.
+
+## 1. Common Failure Patterns
+
+### A. Global Over-Normalization
+
+Symptoms:
+
+- the user asked for headings, but page headers/footers changed too
+- code boxes or table internals changed even though the school guide did not
+  regulate them
+- the assistant says "done" after a style pass, but the user immediately finds
+  obvious visual regressions
+
+Rule:
+
+- If the school guide does not define a format, preserve the current state
+  unless the user explicitly asks for redesign.
+
+### B. Style Name Looks Right, Effective Formatting Is Wrong
+
+Symptoms:
+
+- a paragraph uses the expected style name but still looks wrong
+- Word and WPS render the same paragraph differently
+
+Likely causes:
+
+- direct paragraph formatting overrides the style
+- direct run formatting overrides the style
+- the visual style name is mapped to an unexpected style ID
+- the style inherits hidden indentation or spacing from `Normal`
+
+Check:
+
+- style ID
+- paragraph direct formatting
+- run direct formatting
+- basedOn chain
+
+### C. Hidden Indentation
+
+Symptoms:
+
+- headings appear indented even after `firstLineIndent = 0`
+- the user can manually delete what looks like "two leading spaces"
+
+Likely causes:
+
+- `firstLineChars`
+- numbering indentation
+- direct `w:ind` on the paragraph
+
+Check both:
+
+- `w:firstLine`
+- `w:firstLineChars`
+
+### D. First-Page Section Drift
+
+Symptoms:
+
+- some pages have page headers, some do not
+- some pages have page numbers, some do not
+- abstract, TOC, or chapter-first pages behave inconsistently
+
+Likely causes:
+
+- `differentFirstPageHeaderFooter`
+- `titlePg`
+- broken section references to header/footer parts
+
+### E. Cross-Reference Drift
+
+Symptoms:
+
+- the caption says `图6-1`, but the body still shows `图5-43`
+- the cross-reference field exists, but the rendered text is stale
+- the field result contains extra leftover text such as `图6-15-43`
+
+Likely causes:
+
+- REF fields not refreshed in Word
+- stale display text run not removed
+- caption renumbered without updating field result text
+
+### F. Code Box Header Row Clipping
+
+Symptoms:
+
+- WPS shows the title row correctly, Word shows only the top half
+- title rows look left-aligned even though the table looks centered
+
+Likely causes:
+
+- title paragraph has direct `jc=left`
+- row height uses `EXACT` and is too small for Word
+- cell margins differ across tables
+- `keepNext` / `keepLines` remain on title paragraphs
+
+Preferred fix:
+
+- center the paragraph itself
+- clear keep flags
+- use `AT_LEAST` instead of `EXACT` when Word clips glyphs
+
+### G. Punctuation Over-Correction
+
+Symptoms:
+
+- DOI, URL, code, or English references get rewritten with Chinese punctuation
+
+Rule:
+
+- Chinese prose, captions, abstracts, acknowledgements: full-width Chinese
+  punctuation
+- code, variables, URL, DOI, English references: half-width English punctuation
+- do not mass-rewrite formulas, citations, or technical identifiers without an
+  explicit rule
+
+## 2. Required Quality Gates
+
+Do not say the thesis is complete until these gates pass.
+
+### Gate 1: Requirements Boundary
+
+You must know:
+
+- which items are explicitly regulated by the school guide
+- which items are user-specific house rules
+- which items are unspecified and must be preserved
+
+### Gate 2: Structure Audit
+
+Check:
+
+- page size and margins
+- heading hierarchy
+- abstracts and keywords
+- TOC title and TOC levels
+- figure/table captions
+- references
+- acknowledgements
+- section breaks and page number scheme
+
+### Gate 3: OOXML Audit for Hidden Overrides
+
+Check at least when something still looks wrong:
+
+- `styleId`
+- `firstLine`
+- `firstLineChars`
+- direct `w:ind`
+- `titlePg`
+- section header/footer references
+- REF field display text
+
+### Gate 4: Word PDF Review
+
+Export the Word document to PDF and inspect all pages, not just selected pages.
+
+At minimum verify:
+
+- cover
+- abstract pages
+- TOC
+- first page of body
+- pages with dense figures or tables
+- references
+- acknowledgements
+
+### Gate 5: Delivery Honesty
+
+If any page was not visually reviewed, or if Word automation/PDF export was not
+available, say so explicitly. Do not imply full completion.

package/skills/scholar-thesis-docx/references/figure-and-code-rules.md

@@ -0,0 +1,33 @@
+# Figure and Code Rules
+
+## 1. Mermaid Usage Rules
+
+1. Generate Mermaid only when the user needs an architecture diagram, flow
+   chart, E-R diagram, state diagram, or similar thesis figure and has provided
+   real source material.
+2. Base the diagram on actual code, schema definitions, API docs, project docs,
+   or thesis text from the user.
+3. Do not guess entities, fields, relationships, module boundaries, or call
+   chains when the evidence is incomplete.
+4. Ask for the missing material before generating the figure.
+
+## 2. Thesis Diagram Style
+
+1. Keep the structure clean and avoid decorative nodes.
+2. Use neutral academic terminology.
+3. Avoid chatty labels and extra explanatory filler.
+4. Keep directions and relationships faithful to the real system.
+5. For E-R diagrams, emphasize entities, keys, core attributes, and cardinality.
+6. For architecture diagrams, emphasize layers, modules, and interactions.
+
+## 3. Code Listing Rules
+
+1. Prefer LaTeX-oriented code typesetting when the thesis includes code.
+2. Keep only the parts needed for the thesis argument.
+3. Use real identifiers from the user's code or design.
+4. Do not fabricate code or pseudocode for padding.
+
+## 4. Output Rules
+
+- Every diagram and code listing must be traceable to user-provided material.
+- If any fact is uncertain, ask for evidence instead of guessing.

package/skills/scholar-thesis-docx/references/paper-format-workflow.md

@@ -0,0 +1,68 @@
+# Thesis Word Formatting Workflow
+
+## 1. Environment Gate
+
+1. 先运行 `scripts/check_word_com.ps1 -Json`。
+2. 若 `wordInstalled=false` 或 `comAvailable=false` 或 `domAvailable=false`：
+   - Stop the automation-heavy plan.
+   - Tell the user to install desktop Microsoft Word.
+   - Explain that WPS and similar tools often distort styles, pagination,
+     captions, tables of contents, and cross-references.
+3. 只有在 Word COM/DOM 可用时，才进入自动化文档编辑流程。
+
+## 2. Formatting Rules
+
+1. If the user provides a school template, style guide, screenshots, or page
+   header/footer rules, follow them strictly.
+2. If the user does not provide rules, do not invent school-specific standards.
+3. Control formatting through styles, not scattered manual formatting.
+4. Reuse and repair existing styles before creating new ones.
+
+## 3. Suggested Style Groups
+
+- `Body Text`
+- `Heading 1` / `Heading 2` / `Heading 3`
+- `Figure Caption`
+- `Table Caption`
+- `Code Listing`
+- `References`
+- `Abstract`, `Keywords`, and `Appendix Title`
+
+## 4. Editing Order
+
+1. Read the user requirements and current document structure.
+2. Separate formatting scope into:
+   - school-explicit requirements
+   - user-explicit house rules
+   - unspecified regions that must be preserved
+3. Inspect style names, style IDs, fonts, spacing, indentation, numbering,
+   section settings, and page-break behavior.
+4. Map target styles to document styles.
+5. Normalize only the parts that are justified by the rules.
+6. Then fix page numbers, table of contents, sections, references, and figure
+   numbering.
+7. Export to PDF from Word and review every page.
+8. Only after the PDF review passes, describe the task as complete.
+
+## 4.1 Hidden Word Checks
+
+When the visual result contradicts the style readout, inspect:
+
+- `firstLine`
+- `firstLineChars`
+- direct paragraph `w:ind`
+- numbering indentation
+- `titlePg`
+- `differentFirstPageHeaderFooter`
+- REF field display text
+- direct run formatting
+
+Do not assume `python-docx` style inspection is enough for thesis work.
+
+## 5. Do Not Do This
+
+- Do not mix heavy direct formatting with style-driven formatting.
+- Do not invent school rules when the template evidence is missing.
+- Do not treat WPS rendering as the final Word result.
+- Do not globally normalize the entire document before finishing a full audit.
+- Do not claim the thesis is fully checked before page-level PDF review.

package/skills/scholar-thesis-docx/references/script-usage.md

@@ -0,0 +1,157 @@
+# Script Usage
+
+## 1. Audit DOCX OOXML before risky edits
+
+Use `scripts/audit_docx_ooxml.py` before batch formatting when the document has
+already gone through multiple rounds of editing or when the visible result does
+not match the style readout.
+
+Example:
+
+```powershell
+python scripts/audit_docx_ooxml.py .\draft.docx `
+  --output_json .\draft.audit.json `
+  --output_txt .\draft.audit.txt
+```
+
+The script reports:
+
+1. style IDs and key style definitions
+2. section settings such as `titlePg` and header/footer references
+3. heading paragraphs with direct indentation overrides
+4. paragraphs using `firstLineChars`
+5. suspicious REF fields with multiple result runs
+
+The JSON output is suitable for agents and downstream tooling.
+The TXT output is intended for quick human review.
+
+Use this script before you decide whether a problem can be fixed through styles
+or requires OOXML-level patching.
+
+## 2. Normalize Word styles
+
+Use `scripts/normalize_word_styles.ps1` after `check_word_com.ps1` confirms
+that Word COM automation is available.
+
+Example:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File scripts/normalize_word_styles.ps1 `
+  -InputPath .\draft.docx `
+  -OutputPath .\draft.normalized.docx
+```
+
+Dry-run audit example:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File scripts/normalize_word_styles.ps1 `
+  -InputPath .\draft.docx `
+  -AuditOnly
+```
+
+The script:
+
+1. Opens the Word document through COM automation.
+2. Resolves or creates target styles.
+3. Applies style definitions for body text, Heading 1-3, figure captions, and
+   table captions.
+4. Uses existing style hints first, then falls back to text-pattern detection.
+5. Saves a new file unless `-InPlace` is provided.
+
+When `-AuditOnly` is used, the script does not save document changes. It only
+returns the predicted paragraph-to-style mappings and summary counts.
+
+Use `-ConfigPath` to pass a UTF-8 JSON file with custom style names or school
+rules.
+
+Repository example:
+
+```text
+examples/word-style-config.sample.json
+examples/final-audit-checklist.sample.md
+```
+
+Example JSON:
+
+```json
+{
+  "styles": {
+    "Body": {
+      "TargetStyleName": "正文",
+      "FontName": "Times New Roman",
+      "EastAsiaFontName": "宋体",
+      "Size": 12,
+      "LineSpacingMultiple": 1.5
+    },
+    "FigureCaption": {
+      "TargetStyleName": "图标注"
+    },
+    "TableCaption": {
+      "TargetStyleName": "表标注"
+    }
+  }
+}
+```
+
+## 3. Render Mermaid figures
+
+Use `scripts/render_mermaid_figure.ps1` to render Mermaid source into thesis
+figure assets.
+
+Example:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File scripts/render_mermaid_figure.ps1 `
+  -InputPath .\architecture.mmd `
+  -OutputPath .\figures\architecture.svg `
+  -Theme base `
+  -Width 1800 `
+  -Height 1200 `
+  -Scale 2
+```
+
+The script:
+
+1. Prefers local `mmdc` when it exists.
+2. Falls back to `npx @mermaid-js/mermaid-cli` when needed.
+3. Generates a clean academic default theme config if no config is provided.
+4. Produces SVG, PNG, or PDF output depending on the output filename and CLI
+   behavior.
+
+Repository example:
+
+```text
+examples/architecture.sample.mmd
+```
+
+For thesis work, prefer SVG first, then convert to PNG only when the target
+submission system or Word workflow requires raster images.
+
+## 4. Export Word document to PDF for page audit
+
+Use `scripts/export_word_pdf.ps1` after important formatting changes and before
+you claim the thesis is fully checked.
+
+Example:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File scripts/export_word_pdf.ps1 `
+  -DocPath .\draft.docx `
+  -PdfPath .\draft.audit.pdf
+```
+
+The script:
+
+1. Opens the document through Word COM automation.
+2. Tries to refresh TOC and field results first.
+3. Exports the document to PDF.
+4. Produces a stable artifact for page-by-page review.
+
+Use this whenever the task involves:
+
+- headers/footers
+- page numbers
+- table of contents
+- cross-references
+- figure/table pagination
+- final pre-delivery format review