dotagents-cli 0.7.2__tar.gz → 0.7.4__tar.gz

{dotagents_cli-0.7.2 → dotagents_cli-0.7.4}/CHANGELOG.md

@@ -7,6 +7,39 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.7.4] - 2026-10-14
+
+### Added
+
+- `findings index --requote` quotes, in the findings already on disk, the frontmatter
+  values YAML cannot read as they stand. Only those lines change: bodies, the other
+  lines and line endings are kept.
+
+### Changed
+
+- The private-sync guide describes the default ignore rules the overlay's
+  `sync-project` now writes, once, into the `.gitignore` of a store kept in git:
+  `scratch/`, `tmp/`, `__pycache__/`, hidden files and the machine-local overrides
+  stay out of the private repository.
+
+### Fixed
+
+- `findings` writes frontmatter any YAML parser reads. A description that opens with
+  `[` or a backtick, or holds `: `, was written bare, and a markdown viewer or any
+  other tool reading the frontmatter rejected the file. Such a value is now a
+  double-quoted string; a plain one is still written bare, and a finding written
+  before reads as it did.
+
+## [0.7.3] - 2026-10-04
+
+### Changed
+
+- The command guide and the shipped API header now say that every command except
+  `env`, built-in or discovered, is served as an MCP tool when `dotagents` starts with
+  `DOTAGENTS_MCP=stdio`, and that `AGENT_HELP=1` turns `--help` into a JSON document.
+  The authoring guide asks overlays to ship command modules rather than loose
+  scripts, and skills to name the tools they use.
+
 ## [0.7.2] - 2026-10-03
 
 ### Added
@@ -1384,7 +1417,9 @@ Patch release: the PATH/POSIX-conversion fix above (the only change since 0.3.0)
   affected module sources (`dotagents.cli`, `duho.presets`) to extracted temp files
   before dispatch; a no-op for a plain install.
 
-[Unreleased]: https://github.com/jose-pr/dotagents/compare/v0.7.2...HEAD
+[Unreleased]: https://github.com/jose-pr/dotagents/compare/v0.7.4...HEAD
+[0.7.4]: https://github.com/jose-pr/dotagents/compare/v0.7.3...v0.7.4
+[0.7.3]: https://github.com/jose-pr/dotagents/compare/v0.7.2...v0.7.3
 [0.7.2]: https://github.com/jose-pr/dotagents/compare/v0.7.1...v0.7.2
 [0.7.1]: https://github.com/jose-pr/dotagents/compare/v0.7.0...v0.7.1
 [0.7.0]: https://github.com/jose-pr/dotagents/compare/v0.6.3...v0.7.0

{dotagents_cli-0.7.2 → dotagents_cli-0.7.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: dotagents-cli
-Version: 0.7.2
+Version: 0.7.4
 Summary: The dotagents CLI: install and manage a portable ~/.agents config for AI coding agents
 Project-URL: Homepage, https://github.com/jose-pr/dotagents/
 Project-URL: Repository, https://github.com/jose-pr/dotagents

{dotagents_cli-0.7.2 → dotagents_cli-0.7.4}/docs/guide/authoring.md

@@ -149,7 +149,26 @@ parser cannot be built. The bundled `findings` and `launch` are ordinary command
 modules discovered from the package, and the private-sync overlay ships
 `link-project` / `sync-project` from its own `cmds/` the same way.
 
+**Prefer a command module to a loose script.** A script under `tools/` is something
+an agent has to find, quote and spawn. A command module is discovered, shows up in
+`dotagents --help`, and is served as an MCP tool with a typed schema when `dotagents`
+runs with `DOTAGENTS_MCP=stdio` (see
+[Commands → As tools for an agent](commands.md#as-tools-for-an-agent)). Write it to be
+a good tool:
+
+- the logic lives in the command class — `__call__` and its methods — not in one
+  function that `__call__` forwards every field to;
+- each field's help says what the value is, since it becomes the schema's description;
+- the output is short: one line for a change, the smallest useful part for a read,
+  `--json` for a program;
+- it never prompts, and a command that deletes or publishes needs an explicit flag.
+
 ## Skills
 
 Put `skills/<skill-name>/` directories in your overlay to publish shared skills into
 the scope on install. See [Overlays → Skills](overlays.md#skills).
+
+A skill that relies on commands says so, in its own text: which `dotagents` commands
+it uses, that they are available as MCP tools (`dotagents.<command>`) when the
+server is registered, and the command-line form to fall back to when it is not. An
+agent reading the skill should not have to discover either.

{dotagents_cli-0.7.2 → dotagents_cli-0.7.4}/docs/guide/commands.md

@@ -59,6 +59,38 @@ into `<store>/dotagents/cmds/` (create the dir — `init` does not) and it becom
 subcommand, no registration needed; see
 [Authoring → Custom commands](authoring.md#custom-commands).
 
+## As tools for an agent
+
+Every command above except `env`, and every discovered one, is also an **MCP tool**.
+Start `dotagents` with `DOTAGENTS_MCP=stdio` in its environment and it serves that
+command set over stdio instead of running a command:
+
+```sh
+DOTAGENTS_MCP=stdio dotagents        # register this as a stdio MCP server in your agent
+```
+
+- One tool per leaf command, named with dots: `dotagents.findings.add`,
+  `dotagents.overlays.list`, and for an overlay's commands `dotagents.<command>`.
+- A tool's input schema is generated from the command's fields; its result is what
+  the command prints.
+- The command set is discovered once, when the server starts, for the directory it
+  starts in. Restart it after installing an overlay or changing project.
+
+Use it for a command an agent calls many times in a session — a findings queue, a
+plan's progress, a lookup. A tool call skips the interpreter start-up and the
+command discovery that every `dotagents <command>` process pays, and its arguments
+are typed values, not strings quoted through a shell.
+
+`env` is not served: it prints resolved values, which can be secrets. Everything
+else is, including the commands that change the store (`init`, `overlays add`,
+`overlays remove`). Register the server only where the agent is meant to be able to
+run them.
+
+For a machine-readable description without a server, set `AGENT_HELP=1` and ask for
+`--help`: `dotagents findings --help` then prints one JSON document for that command
+tree. It is complete and long; a single subcommand's plain `--help` is shorter when
+that is all that is needed.
+
 ## init
 
 See [Install](install.md) for the full walkthrough. In brief:
@@ -410,6 +442,7 @@ dotagents findings done <name> -r "fixed in _context; test added"
 dotagents findings reopen <name>
 dotagents findings remove <name>            # an active finding recorded by mistake
 dotagents findings index                    # regenerate INDEX.md after hand edits
+dotagents findings index --requote          # ...and quote frontmatter values YAML cannot read
 dotagents findings path                     # where this scope's queue lives
 ```
 
@@ -431,6 +464,11 @@ dotagents findings path                     # where this scope's queue lives
   without a frontmatter is still listed (name = file stem, description = its
   first heading or line) and gains one the first time the command rewrites it;
   a note that is not UTF-8 is skipped with a warning and never rewritten.
+- The frontmatter is YAML a viewer or another tool can parse: a value is written
+  bare when YAML reads it back as the same text, and double-quoted otherwise (a
+  description that opens with `[` or a backtick, or holds `: `). `index --requote`
+  does the same for findings an earlier version wrote, and for hand-written ones,
+  changing only the lines that need it.
 - `add` refuses the names `index` and `readme` (on a case-insensitive
   filesystem they are `INDEX.md` / `README.md`). `done` and `reopen` refuse to
   move onto an existing file, and `remove` deletes active findings only: reopen
@@ -501,13 +539,13 @@ There is no `dotagents audit`. The dotagents source repo has its own
 it is not a validator for an installed `~/.agents` and is deliberately not shipped
 in the package or the `.pyz`.
 
-### Personal pre-push scanning (not in this repo)
+### Pre-push scanning (an overlay's command)
 
-Scanning a repo for personal leaks before publishing it — machine paths, private
-plan names, `.agents/` refs, agent-session trailers in commit messages — enforces
-personal conventions rather than dotagents' own mechanism, so no such tool is
-shipped here. Keep one as a discovered command module in your own private
-`<scope>/dotagents/cmds/` and run it locally before a push.
+Scanning a repo for leaks before publishing it — machine paths, private plan names,
+`.agents/` refs, agent-session trailers in commit messages — enforces a convention
+rather than dotagents' own mechanism, so the package ships no such command. The
+opt-in `engineering` overlay does: `dotagents leak-check <repo>`. Its patterns for
+what is personal to you stay in a machine-local file, never in a repository.
 
 ## link-project / sync-project
 

{dotagents_cli-0.7.2 → dotagents_cli-0.7.4}/docs/guide/overlays.md

@@ -44,7 +44,7 @@ or `--repo <checkout>/overlays` for a local checkout of the branch.
 
 | Overlay | What it carries |
 | --- | --- |
-| `engineering` | One opinionated engineering process. `rules/ENGINEERING.md` — always-on discipline merged into `AGENTS.md` (commit shape, release-tag consent, benchmark-as-evidence, token discipline, draft follow-ups). `flows/` — `PLAN.md` (a strong model writes precise, autonomous plans), `EXEC.md` (a cheaper model executes them without re-deriving context), `REVIEW.md` (file-threaded multi-agent plan review), `REPO.md` (the repo standard); `kb/MODELS.md` (executor/model selection). `references/` — language-neutral repo-file templates (README, CHANGELOG, LICENSE, `.gitignore`, docs-index, the plan template). `tools/` — `summarize_run` (command → verdict) and `compare_bench` (diff benchmark JSONs). The language overlays require it. |
+| `engineering` | One opinionated engineering process. `rules/ENGINEERING.md` — always-on discipline merged into `AGENTS.md` (commit shape, release-tag consent, benchmark-as-evidence, token discipline, draft follow-ups). `flows/` — `PLAN.md` (a strong model writes precise, autonomous plans), `EXEC.md` (a cheaper model executes them without re-deriving context), `REVIEW.md` (file-threaded multi-agent plan review), `REPO.md` (the repo standard); `kb/MODELS.md` (executor/model selection). `references/` — language-neutral repo-file templates (README, CHANGELOG, LICENSE, `.gitignore`, docs-index, the plan template). `cmds/` — `plans`, `leak-check`, `eol`, `summarize-run` (command → verdict) and `compare-bench` (diff benchmark JSONs), each a `dotagents` command. The language overlays require it. |
 | `python`, `node`, `rust` | Per-language `kb/` conventions + manifest templates + CI workflow templates. |
 | `release` | A host-agnostic release helper: an agent-driven commit-plan loop plus tag/CI monitoring across GitHub (`gh`) and GitLab. |
 | `private-sync` | The one-private-repo, per-project `.agents` model (`kb/PRIVATE_SYNC.md` + cloud hooks) — see [Private sync](private-sync.md). |

{dotagents_cli-0.7.2 → dotagents_cli-0.7.4}/docs/guide/private-sync.md

@@ -49,6 +49,14 @@ leaves the machine is a perfectly valid setup.
   links the store instead.
 - **Copy mode** (`--copy`) makes `.agents` a real directory rather than a symlink;
   `sync-project` copies edits back into the store.
+- **Default ignore rules.** A project's `.agents/scratch/` lives inside the store, so
+  the built-in git path would commit it. The first `sync-project` on that path
+  appends a block to the store's `.gitignore` that leaves out `scratch/`, `tmp/`,
+  `__pycache__/`, hidden files (`.*`, keeping `.gitignore`, `.gitattributes`,
+  `.gitkeep`, `.ignore` and `.dotagents-install.json`) and the machine-local
+  overrides (`*.local.*`, `local.env`). It is written once, under a marker line:
+  edit the block freely and keep that line. The overlay's `kb/PRIVATE_SYNC.md` has
+  the block in full.
 
 ## Cloud sessions
 

{dotagents_cli-0.7.2 → dotagents_cli-0.7.4}/src/dotagents/AGENTS.md

@@ -40,10 +40,20 @@ and an error saying a command is required, and exits 2.
 | `path [-g] [--lib] [--format list\|native\|posix\|json]` | Print the bin dirs `env` puts on `PATH` (`--lib`: the existing lib dirs it puts on `PYTHONPATH`), highest precedence first; runs no env file. `posix` is `:`-joined, MSYS2 form on Windows. |
 | `env [-g] [--format F] [--diff] [--cache] [--into FILE]` | Print the assembled environment (`--diff`: only what differs from the caller's; `--cache`: replay the previous output while `env_cache_key` holds, up to `ENV_CACHE_TTL`; `--into FILE`: write it into FILE as the one block this command owns there) in format `F`: `auto` (default: the calling shell), `export`/`posix`/`sh`/`bash`, `dotenv`/`env`, `powershell`/`pwsh`/`ps`, `cmd`/`bat`/`batch`, `fish`, `json`, `ini`, `yaml`. |
 | `launch [AGENT] [-g] [--command PROG] [--no-context] [--inline] [--write-agent] [--dry-run] [-- ARGS...]` | Run the agent's CLI with the env applied and the context handed over; the exit code is the harness's (`128+N` on signal N). |
-| `findings add\|list\|show\|done\|reopen\|remove\|index\|path [-g] [--dir D]` | The findings queue at `<store>/findings/` (`--dir` overrides): one markdown file per finding, `done` moves it to `processed/` with a required resolution, `INDEX.md` regenerated on every change. |
+| `findings add\|list\|show\|done\|reopen\|remove\|index\|path [-g] [--dir D]` | The findings queue at `<store>/findings/` (`--dir` overrides): one markdown file per finding, `done` moves it to `processed/` with a required resolution, `INDEX.md` regenerated on every change. The frontmatter is valid YAML (a value is double-quoted when it must be); `index --requote` fixes values written bare in existing files, touching nothing else. |
 | `about [--json]` | `dotagents-cli <version>`, then `<distribution> <version>` per bundled (`.pyz`) or installed package. |
 | `build-pyz [--out P] [--python SHEBANG] [--duho-version V] [--pathlib-next-version V] [--extras a,b]` | Build a zipapp from a source checkout; errors elsewhere. |
 
+**Every command but `env` is also an MCP tool.** With `DOTAGENTS_MCP=stdio` in its
+environment, `dotagents` serves the command set — built-in, bundled and discovered —
+over stdio instead of running one: a tool per leaf command, named with dots
+(`dotagents.findings.add`, `dotagents.overlays.list`), its input schema generated from
+the command's fields, its result the command's output. `env` is not served: it prints
+resolved, possibly secret values. The set is fixed when the server starts, for the
+scope it starts in. With `AGENT_HELP=1`, `--help` prints one
+JSON document (`duho/agent-help@1`) for the command tree it is asked about, in place
+of the human text.
+
 Scope flags: `-g` / `--global` selects the user store; `--agents-dir D` overrides the
 store the command resolves to (the project store for `init` / `overlays` / `findings`
 without `-g`, the user store otherwise). For `env`, `context` and `launch`, `-g` means

{dotagents_cli-0.7.2 → dotagents_cli-0.7.4}/src/dotagents/__init__.py

@@ -1,3 +1,3 @@
 """dotagents: installable CLI for the dotagents agent-config payload."""
 
-__version__ = "0.7.2"
+__version__ = "0.7.4"

{dotagents_cli-0.7.2 → dotagents_cli-0.7.4}/src/dotagents/_overlay/dotagents/cmds/findings.py

@@ -37,6 +37,10 @@ line, the details in the body::
 
     <the decision, evidence, or why no action was needed>
 
+The frontmatter is YAML a viewer or another tool can parse: a value is written
+bare when YAML reads it back as the same text, and as a double-quoted string
+otherwise (a description that opens with ``[`` or a backtick, or holds ``: ``).
+
 ``INDEX.md`` is one line per finding, active first, then processed -- the cheap
 thing to read at session start. Hand-written notes without frontmatter are
 still listed (name = file stem, description = first heading or line), and gain
@@ -90,6 +94,69 @@ def slugify(text: str) -> str:
     return slug
 
 
+#: A value cannot be written bare when it opens with one of these: YAML reads
+#: ``[`` as a list, a quote as a quoted string, a backtick as reserved.
+_YAML_INDICATORS = frozenset("-?:,[]{}#&*!|>'\"%@`")
+#: Bare words YAML reads as a boolean or as nothing rather than as text.
+_YAML_WORDS = frozenset(("true", "false", "yes", "no", "on", "off", "null", "~"))
+#: Line breaks to YAML that JSON leaves as they are, escaped inside a quoted value.
+_YAML_BREAKS = {"\x85": "\\u0085", "
": "\\u2028", "
": "\\u2029"}
+
+
+def _yaml_scalar(value: str) -> str:
+    """``value`` as a one-line YAML scalar: bare when YAML reads it back as the
+    same text, double-quoted when it would read something else (a list, a
+    mapping, a comment) or nothing at all."""
+    plain = (
+        value == value.strip()
+        and value[:1] not in _YAML_INDICATORS
+        and ": " not in value
+        and " #" not in value
+        and not value.endswith(":")
+        and value.lower() not in _YAML_WORDS
+        and not any(ord(c) < 32 or c == "\x7f" or c in _YAML_BREAKS for c in value)
+    )
+    if plain and value:
+        return value
+    quoted = json.dumps(value, ensure_ascii=False)  # a JSON string is a YAML one
+    for char, escape in _YAML_BREAKS.items():
+        quoted = quoted.replace(char, escape)
+    return quoted
+
+
+def _yaml_text(scalar: str) -> str:
+    """The text of a one-line scalar as :func:`_yaml_scalar` writes it. Anything
+    that is not one whole quoted string is its own text, which is how a value
+    this command wrote bare, before it quoted, still reads as it did."""
+    if len(scalar) >= 2 and scalar[0] == scalar[-1] == '"':
+        try:
+            value = json.loads(scalar)
+        except ValueError:
+            return scalar
+        return value if isinstance(value, str) else scalar
+    if len(scalar) >= 2 and scalar[0] == scalar[-1] == "'":
+        inner = scalar[1:-1]
+        if "'" not in inner.replace("''", ""):
+            return inner.replace("''", "'")
+    return scalar
+
+
+def _requoted(block: str) -> str:
+    """A frontmatter block with every bare value YAML would misread quoted.
+    A value that is already one quoted string, or reads back as itself, keeps
+    its line as it is; so do keys, order, line endings and any line that is
+    not ``key: value``."""
+    out = []
+    for line in block.splitlines(True):
+        text = line.rstrip("\r\n")
+        key, sep, value = text.partition(":")
+        bare = value.strip()
+        if sep and key.strip() and bare and _yaml_text(bare) == bare and _yaml_scalar(bare) != bare:
+            text = "%s: %s" % (key, _yaml_scalar(bare))
+        out.append(text + line[len(line.rstrip("\r\n")):])
+    return "".join(out)
+
+
 def _today() -> str:
     return datetime.date.today().isoformat()
 
@@ -153,7 +220,7 @@ class Finding:
             for line in m.group(1).splitlines():
                 key, sep, value = line.partition(":")
                 if sep and key.strip():
-                    meta[key.strip()] = value.strip()
+                    meta[key.strip()] = _yaml_text(value.strip())
             body = text[m.end():]
         else:
             body = text
@@ -178,10 +245,10 @@ class Finding:
         lines = ["---"]
         for key in _META_KEYS:
             if self.meta.get(key):
-                lines.append("%s: %s" % (key, self.meta[key]))
+                lines.append("%s: %s" % (key, _yaml_scalar(self.meta[key])))
         for key, value in self.meta.items():
             if key not in _META_KEYS and value:
-                lines.append("%s: %s" % (key, value))
+                lines.append("%s: %s" % (key, _yaml_scalar(value)))
         lines.append("---")
         body = self.body.rstrip("\r\n")
         return "\n".join(lines) + "\n\n" + (body + "\n" if body else "")
@@ -372,6 +439,26 @@ class FindingsStore:
         self.write_index()
         return path
 
+    def requote(self) -> "list[Path]":
+        """Write again every frontmatter whose values are not in the form this
+        command writes now: a description an earlier version left bare where
+        YAML needs it quoted. Only those lines change; the body, the other
+        lines and the line endings stay byte for byte. Returns the files
+        changed."""
+        changed = []
+        for finding in self.all():
+            text = finding.path.read_bytes().decode("utf-8")
+            m = _FRONTMATTER_RE.match(text[1:] if text.startswith("") else text)
+            if not m:
+                continue
+            shift = 1 if text.startswith("") else 0
+            start, end = m.start(1) + shift, m.end(1) + shift
+            block = _requoted(text[start:end])
+            if block != text[start:end]:
+                write_text_lf(finding.path, text[:start] + block + text[end:])
+                changed.append(finding.path)
+        return changed
+
     # -- index ---------------------------------------------------------------
 
     def render_index(self) -> str:
@@ -605,12 +692,24 @@ class Findings(LoggingArgs, Cli):
             return 0
 
     class Index(_Base):
-        """Regenerate INDEX.md from the files (after hand edits)."""
+        """Regenerate INDEX.md from the files (after hand edits).
+
+        `--requote` first quotes any frontmatter value YAML cannot read as it
+        stands: what an earlier version wrote for a description opening with
+        `[` or a backtick, or holding `: `."""
 
         _parsername_ = "index"
 
+        requote: bool = False
+        "Also quote frontmatter values YAML cannot read bare (bodies are not touched)."
+        ("--requote",)
+
         def __call__(self) -> int:
-            _write_stdout("%s\n" % (self.store().write_index(),))
+            store = self.store()
+            if self.requote:
+                changed = store.requote()
+                self._logger_.info("requoted the frontmatter of %d finding(s)", len(changed))
+            _write_stdout("%s\n" % (store.write_index(),))
             return 0
 
     class PathCmd(_Base):

{dotagents_cli-0.7.2 → dotagents_cli-0.7.4}/tests/test_findings_cmd.py

@@ -336,3 +336,84 @@ def test_a_finding_named_like_the_index_is_refused(findings_mod, tmp_path):
         with pytest.raises(SystemExit, match="reserved"):
             store.add(title, body="important details")
     assert not root.exists() or not [p for p in root.iterdir() if p.suffix == ".md"]
+
+
+# --------------------------------------------------------------------------- #
+# The frontmatter is YAML another tool can read
+# --------------------------------------------------------------------------- #
+
+AWKWARD = [
+    "[low][correctness] off Linux, sniff with an interface name raises",
+    "`dotagents pyvenv` broken on the new machine",
+    "perf rule: two hosted-runner runs are not a before/after",
+    '"It compiles" is not evidence',
+    "'first', 'second' and a third",
+    '"quoted"',
+    "ends with a colon:",
+    "a marker # that starts a comment",
+    "*starred* and &anchored",
+    'a back\\slash and a "quote": both',
+    "- a leading dash",
+    "{braces} and a percent %",
+    "em dash — and an accent: é",
+    "true",
+]
+
+
+@pytest.mark.parametrize("text", AWKWARD)
+def test_any_description_is_frontmatter_yaml_can_read(findings_mod, tmp_path, text):
+    yaml = pytest.importorskip("yaml")
+    store = findings_mod.FindingsStore(tmp_path / "findings")
+    finding = store.add(text, name="x")
+    front = yaml.safe_load(finding.path.read_text(encoding="utf-8").split("---\n")[1])
+    assert front["name"] == "x" and str(front["description"]) == text
+    assert findings_mod.Finding.load(finding.path).description == text
+    assert "— %s\n" % text in store.index_path.read_text(encoding="utf-8")
+
+
+def test_a_plain_description_is_written_bare(findings_mod, tmp_path):
+    store = findings_mod.FindingsStore(tmp_path / "findings")
+    text = "bare kb/X.md refs were never inlined (3 files, 2026-09-09)"
+    raw = store.add(text).path.read_text(encoding="utf-8")
+    assert "\ndescription: %s\n" % text in raw
+
+
+@pytest.mark.parametrize("text", [
+    "[low][api] a consumer: rewrites `x`",
+    '"It compiles" is not evidence',
+    "'one', 'two'",
+    '"a" and "b"',
+])
+def test_a_finding_written_bare_still_reads_as_it_did(findings_mod, tmp_path, text):
+    """What an earlier version wrote: the description as typed, whatever it held."""
+    path = tmp_path / "findings" / "old.md"
+    path.parent.mkdir(parents=True)
+    path.write_bytes(("---\nname: old\ndescription: %s\nstatus: active\n---\n\nbody\n" % text).encode("utf-8"))
+    assert findings_mod.Finding.load(path).description == text
+
+
+def test_index_requote_changes_only_the_values_yaml_cannot_read(findings_mod, tmp_path, capsys):
+    yaml = pytest.importorskip("yaml")
+    root = tmp_path / "findings"
+    (root / "processed").mkdir(parents=True)
+    bad = root / "processed" / "bad.md"  # CRLF, odd spacing, blank lines: all kept
+    bad.write_bytes(b"---\r\nname: bad\r\ndescription: [low][api] a: b\r\nstatus: processed\r\n---\r\n\r\n\r\nbody kept  \r\n\r\n\r\n")
+    kept = {
+        root / "quoted.md": b'---\nname: quoted\ndescription: "already: quoted"\n---\nbody\n',
+        root / "plain.md": b"---\nname: plain\ndescription:   nothing to do\nextra: 1\n---\n\nbody\n",
+        root / "note.md": b"# a hand note\n\n---\nnot: [frontmatter\n---\n",
+    }
+    for path, data in kept.items():
+        path.write_bytes(data)
+
+    assert _run(findings_mod.Findings.Index, dir=root, requote=True) == 0
+    assert capsys.readouterr().out.strip() == str(root / "INDEX.md")
+
+    assert bad.read_bytes() == (
+        b'---\r\nname: bad\r\ndescription: "[low][api] a: b"\r\nstatus: processed\r\n---\r\n\r\n\r\nbody kept  \r\n\r\n\r\n')
+    assert yaml.safe_load(bad.read_bytes().decode().split("---\r\n")[1])["description"] == "[low][api] a: b"
+    for path, data in kept.items():
+        assert path.read_bytes() == data, path.name
+    assert "— [low][api] a: b" in (root / "INDEX.md").read_text(encoding="utf-8")
+    # A second pass has nothing left to do.
+    assert findings_mod.FindingsStore(root).requote() == []