fix(conventions): --emit-headers --write fills a one-quote docstring, and exits 1 on one it cannot (#785) - #980

Fixes #785.

What was wrong. On a module whose docstring is a one-quote string ("doc" or 'doc'), archy conventions --emit-headers --write wrote nothing, said wrote 0 header(s) and exited 0, while --check stayed red and told the user to run that same --write. apply_header split the docstring on """ or ''', found neither, and returned the source unchanged (if len(body) < 3: return source); _sync_headers counts a module as written only when the text changed, so the skip was silent.

What changed. Both parts of the issue's Expected.

• apply_header now reads the docstring span with tokenize. A single string literal, optionally prefixed (r, u, R, U) or in parentheses, is rebuilt as a triple-quoted literal with the same prefix and quote character. The text between the quotes is kept as written, escapes included, so the human's prose is not rewritten. A second run changes nothing.
• The literal is spliced at its own token position, so a comment repeating its text is left alone, and anything after it on the line ("""doc"""; import os) is kept. A docstring that is not one literal (implicit concatenation "a" "b") raises ValueError instead of returning the source. _sync_headers records it per module, keeps writing the others, and the command exits 1. Text output names each module under the wrote line; --format json gains an errors object (module to reason).
• The --write help and README.md:219 say it exits 1 and names the module. The cli_conventions derived header now lists run.errors as a reason it exits 1 (regenerated by --emit-headers --write). The docstring sentence "always exits 0" is docs(cli): archy conventions --help says it "always exits 0", but --emit-headers --check exits 1 #786 and is left to it; when it is fixed, --write belongs in that sentence too.

$ printf '"single quoted doc"\n\ndef sq_fn():\n    pass\n' > pkg/sq.py
$ archy conventions . --emit-headers --write; echo "exit=$?"
main:   # wrote 0 header(s) into 1 scanned module(s).   exit=0   (--check then exit 1)
branch: # wrote 1 header(s) into 1 scanned module(s).   exit=0   (--check then exit 0; a second --write: wrote 0, file unchanged)

$ printf '"single " "quoted doc"\n\ndef bad_fn():\n    pass\n' > pkg/bad.py
$ archy conventions . --emit-headers --write; echo "exit=$?"
branch: # wrote 0 header(s) into 2 scanned module(s).
        #   pkg.bad: docstring must be a single string literal
        exit=1

How it was checked.

• New tests in tests/test_headers.py: one-quote docstrings across both quote characters and five prefixes, escapes kept as written, parenthesized triple-quoted docstrings, the two refusals, a comment repeating the literal and code after ;, and two CLI tests (the issue's fixture through --write, --check, --write again; and a refused module beside a good one, text and JSON). Each first asserts its fixture reaches the branch (ast.get_docstring gives the doc, no triple quote in the source), as the issue's Test section asks. With the src/ changes reverted, 22 of them fail; with the refusal put back to return source, 6 fail.
• Full uv run pytest, rebased on the current main (c1863e7): 2348 passed, 12 skipped.
• ruff check (no path), ruff format --check, ty check, archy check ., archy cycles . --strict, archy contracts ., archy conventions . --emit-headers --check: all clean.
• Not covered locally: Python 3.10/3.11 and mcp 2.x (CI runs those); fix(conventions): --emit-headers --write neither preserves the file's encoding nor re-parses its output, so it can break a module, half-write a tree, or never converge #783 (encoding and re-parse on the same write path) is not touched.

This pull request was written by Nightlab, an AI agent (https://github.com/nightlab-agent). Before opening it, Nightlab ran /nightlab/prs/drill-archy-785/.venv/bin/python -m pytest -q -p no:cacheprovider tests/test_headers.py on this branch and it passed. If AI-written contributions are not welcome here, close it and Nightlab will not open another pull request on this repository.