diff --git a/CHANGELOG.md b/CHANGELOG.md index fedbb1e..fd4abea 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,20 @@ This project follows Keep a Changelog principles and uses semantic versioning for tagged releases. +## [2026-10-19] + +### Added + +- A PDF-to-Markdown skill for faithful, human-readable conversion from a freshly supplied source URL. + +### Changed + +- DTM task guidance now keeps incidental opportunities to polish, check, reformat, or extend work as context unless they are necessary to complete the agreed outcome. + +### Fixed + +- The task-envelope regression test now locates the tool in both the source-vault and published-framework layouts. + ## [2026-10-11] ### Changed diff --git a/framework/DTM.md b/framework/DTM.md index 8b38763..3ba9c15 100644 --- a/framework/DTM.md +++ b/framework/DTM.md @@ -288,6 +288,12 @@ references according to the normal Daily Note rules. follow-up task unless the user explicitly asks to track that action. When a completed-work hand-off confirms that delivery has already happened, do not create or carry a delivery task; correct any stale Daily Note entry instead. +- Do not derive follow-up tasks from a work report merely because an output + could be polished, checked, reformatted, or extended further. Create a task + only when the user explicitly asks for it, an existing assigned outcome is + still incomplete, or the follow-up is necessary to complete the agreed work. + Record incidental limitations as context in `Notes & Activity` or the + relevant artefact; do not turn them into new tasks by default. - In the current Daily Note, preserve visible completion by checking completed items off instead of removing them. Do not silently delete completed tasks from today's note unless the user explicitly asks for cleanup or removal. diff --git a/framework/skills/pdf-to-markdown/SKILL.md b/framework/skills/pdf-to-markdown/SKILL.md new file mode 100644 index 0000000..42ff418 --- /dev/null +++ b/framework/skills/pdf-to-markdown/SKILL.md @@ -0,0 +1,30 @@ +--- +name: pdf-to-markdown +description: Convert a supplied PDF into a faithful, human-readable Markdown copy, preserving reading order, notes, references, and meaningful visuals. Requires a fresh online URL from the user for each conversion. Use for PDF-to-Markdown transcription or source-format replacement, not for wiki ingestion or a summary. +--- + +# PDF to Markdown + +Create a Markdown version of the supplied PDF that a person can read without opening the PDF. Preserve the author's content and sequence; do not paraphrase, correct substantive claims, or replace the article with an extraction dump. + +Each invocation needs a fresh online URL for that PDF from the user. If the request omits it, ask for the URL while continuing any PDF inspection that does not depend on it. Do not reuse a URL from an earlier conversion or substitute a guessed DOI or local PDF link. + +## Read the PDF + +1. Inspect page count, metadata, text extraction, and images. Useful tools include `pdfinfo`, `pdftotext -layout`, and `pdfimages -list`. +2. Render every page at thumbnail size to check reading order, columns, tables, figures, and page-specific exceptions. Inspect relevant pages at readable size. A PDF can contain vector visuals even when `pdfimages` reports none. +3. For scans, use OCR if available and compare its output against rendered pages. Do not present uncertain OCR as verified text. + +## Build the Markdown + +- Keep the title, author and publication details, abstract, epigraphs, section hierarchy, prose, quotations, lists, tables, equations, captions, notes, acknowledgements, references, and licence text when present. Preserve the wording, including apparent source errors; flag unreadable passages rather than inventing text. +- Remove repeated running headers, page numbers, download stamps, and similar page furniture. Rejoin lines and paragraphs in reading order. Resolve soft line-break hyphens individually so genuine compound words and URLs remain intact. Normalize extraction-only glyphs such as private-use numerals. +- Use Markdown headings, lists, block quotes, tables, and footnotes where they make the original structure easier to read. Keep footnote calls attached to their sentences and all corresponding note text, including notes that continue on another page. +- Decide how to carry each meaningful visual: use Mermaid for a simple semantic diagram; embed an extracted or cropped image when visual fidelity matters; use a concise, located placeholder when either option would be misleading or disproportionately complex. Do not invent a visual when the PDF has none. In this vault, place source-derived image assets under `raw/assets/` and treat them as immutable once placed there. +- Put the Markdown at the requested location, or beside the PDF with the same stem if no location was specified. Link to the fresh online URL supplied for this conversion. Follow the user's link instructions exactly, including any request not to link the local PDF. + +## Verify before delivery + +- Compare the Markdown with the PDF page by page, checking that no text block, note, reference entry, table, or visual is missing or out of order. Extraction word counts or sequence comparisons can help find omissions, but do not replace visual review. +- Check section order, footnote calls and definitions, reference boundaries, broken words and URLs, unreadable characters, and accidental inclusion of page furniture. Correct extraction errors against the rendered original. +- Report any passage or visual that could not be faithfully transcribed. Leave the PDF untouched. Conversion alone does not authorize wiki ingestion, source archival, or deletion. diff --git a/framework/skills/pdf-to-markdown/agents/openai.yaml b/framework/skills/pdf-to-markdown/agents/openai.yaml new file mode 100644 index 0000000..826f2a9 --- /dev/null +++ b/framework/skills/pdf-to-markdown/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "PDF to Markdown" + short_description: "Transcribe a PDF into verified Markdown" + default_prompt: "Use $pdf-to-markdown to convert this PDF into Markdown; I will provide its online URL." diff --git a/tests/test_task_envelopes.py b/tests/test_task_envelopes.py index 4f8702e..3bd8883 100644 --- a/tests/test_task_envelopes.py +++ b/tests/test_task_envelopes.py @@ -6,7 +6,10 @@ ROOT = Path(__file__).resolve().parent.parent -SPEC = importlib.util.spec_from_file_location("task_envelopes", ROOT / "framework" / "tools" / "task_envelopes.py") +TOOL = ROOT / "tools" / "task_envelopes.py" +if not TOOL.exists(): + TOOL = ROOT / "framework" / "tools" / "task_envelopes.py" +SPEC = importlib.util.spec_from_file_location("task_envelopes", TOOL) assert SPEC and SPEC.loader task_envelopes = importlib.util.module_from_spec(SPEC) SPEC.loader.exec_module(task_envelopes)