From edc9fc719a75c3d1f417ae2eee040e704098572b Mon Sep 17 00:00:00 2001
From: Brett Heap <service@opensoft.dev>
Date: Tue, 20 Oct 2026 16:06:19 +0000
Subject: [PATCH 1/3] scripts/shape_materialize.py and family.py: a
 `family.yaml` or `project.yaml` the template's own reader makes something
 other than a mapping is `-manifest-invalid` still, but its remedy says it is
 a defect in the copy of the standard and names
 `templates/family-root/family.yaml` or
 `templates/assembly-root/project.yaml`, and no longer says to choose a value
 the validator accepts; `manifest_invalid`'s docstring says a line
 `passed_over` names is a note, not a WARNING for the holder too (#1059)

Two notes from the reviews of #1057 (#925), both words only. No refusal
code changes.

1. `manifest_invalid`'s docstring said a WARNING of the validator "is a note
   and never a refusal, exactly as the project's own exit code treats it",
   which is false for the holder since #1057 (`HOLDER_MANIFEST.passed_over`
   is empty). It now says a line `manifest_kind.passed_over` names is a note
   and never a refusal, as that validator's own exit code treats it (the
   project's WARNING and `  note`, #990), and that the holder passes over
   none (#925). Its other project-only words are neutral.

2. The not-a-mapping sentence went out as `invalid`, with "choose a value the
   ... validate-manifest.py accepts; the words after each value are the
   validator's own". No value reaches that case (RV1057 tried 51), and the
   words are the reader's. It is a kind of its own now, `KIND_NOT_A_MAPPING`,
   with a remedy in each manifest's table: the defect-of-the-standard one
   main's project had before #1057, aimed at the right file. One builder,
   `manifest_not_a_mapping_remediation`, says it for both manifests, so the
   holder's and the project's cannot drift. Lane openRepoShape-5 agreed on
   #473 (issuecomment-6295099581). The refusal codes are kept.

`test_a_manifest_that_is_not_a_mapping_keeps_its_kind_and_remedy` (#960's
round 1) holds the new remedy, so #960's mutant M2 (the kind moved to
`unreadable`) and a swap back to the invalid-value remedy both fail it.
The scaffold's row for `project.yaml` holds the same, and two new tests hold
the kind, `manifest_judged`'s None and each manifest's own file.

Closes #1059

Lane: openreposhape-3 (openRepoShape-3)
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 scripts/family.py                      |  16 +++-
 scripts/shape_materialize.py           | 103 ++++++++++++++++++-------
 tests/test_family_init_yaml_words.py   |  65 ++++++++++++++--
 tests/test_scaffold_manifest_values.py |  41 ++++++++--
 4 files changed, 182 insertions(+), 43 deletions(-)

diff --git a/scripts/family.py b/scripts/family.py
index 82270793..b6d75c30 100755
--- a/scripts/family.py
+++ b/scripts/family.py
@@ -197,9 +197,10 @@
 # `project.yaml`, asked of `family.yaml` (#925), and the first sentence of
 # the remedy where the holder's reader refuses it (#929).
 from shape_materialize import (  # noqa: E402
-    FAMILY_TEMPLATED, KIND_INVALID, KIND_MISREAD, KIND_UNREADABLE,
-    UNREADABLE_CHOICE, TemplateManifest, manifest_invalid, manifest_misreads,
-    manifest_validator, manifest_value_problems, refuse_manifest_problems,
+    FAMILY_TEMPLATED, KIND_INVALID, KIND_MISREAD, KIND_NOT_A_MAPPING,
+    KIND_UNREADABLE, UNREADABLE_CHOICE, TemplateManifest, manifest_invalid,
+    manifest_misreads, manifest_not_a_mapping_remediation, manifest_validator,
+    manifest_value_problems, refuse_manifest_problems,
 )
 # How every command this prints for a person to paste spells its paths
 # (#486), the quoting the holder's `scripts/siblings.py` uses too.
@@ -3554,10 +3555,17 @@ def _print_next_steps(args, work: Path, folder: Path | None) -> None:
     "red from its first commit, because `make validate` and the `validate` "
     "workflow run that validator first, and `init` cannot be run again over "
     "a pushed holder: there is no --force.")
+#: Where the holder's own reader reads the template's `family.yaml` as
+#: something other than a mapping (#1059), no value `init` is handed did it,
+#: so the remedy is the defect of the standard, aimed at that file, and it
+#: is the project's sentence (`shape_materialize`), said of the holder's.
+MANIFEST_NOT_A_MAPPING_REMEDIATION = manifest_not_a_mapping_remediation(
+    "family-root", MANIFEST, "the holder's own YAML reader")
 #: The remedy for each kind of problem the questions name.
 KIND_REMEDIATIONS = {KIND_MISREAD: MANIFEST_MISREAD_REMEDIATION,
                      KIND_INVALID: MANIFEST_INVALID_REMEDIATION,
-                     KIND_UNREADABLE: MANIFEST_UNREADABLE_REMEDIATION}
+                     KIND_UNREADABLE: MANIFEST_UNREADABLE_REMEDIATION,
+                     KIND_NOT_A_MAPPING: MANIFEST_NOT_A_MAPPING_REMEDIATION}
 
 
 def _holder_findings(validator, manifest: dict, policy: NamingPolicy):
diff --git a/scripts/shape_materialize.py b/scripts/shape_materialize.py
index d7f897cb..d77b3f22 100644
--- a/scripts/shape_materialize.py
+++ b/scripts/shape_materialize.py
@@ -5038,11 +5038,13 @@ def _placeholders_of(line: str) -> list[str]:
 
 #: The kinds of problem `manifest_value_problems` names, each spelled once
 #: (#708): a value the project's reader reads back as something else, one
-#: its validator refuses, and a manifest the reader refuses before the
-#: validator can be asked, which `refuse_manifest_values` refuses under the
+#: its validator refuses, a manifest the reader refuses before the validator
+#: can be asked, and a manifest the reader reads as something other than a
+#: mapping (#1059), which no value a person types can make (only a broken
+#: template does). `refuse_manifest_values` refuses the last three under the
 #: code `invalid` still.
-KIND_MISREAD, KIND_INVALID, KIND_UNREADABLE = (
-    "misread", "invalid", "unreadable")
+KIND_MISREAD, KIND_INVALID, KIND_UNREADABLE, KIND_NOT_A_MAPPING = (
+    "misread", "invalid", "unreadable", "not-a-mapping")
 
 #: The remediation, without the sentence only the caller can write (what was
 #: or was not created, whether `--dry-run` refuses the same).
@@ -5087,11 +5089,38 @@ def _placeholders_of(line: str) -> list[str]:
     "which refuses the manifest this run would write before its "
     "validate-manifest.py can be asked, and a project whose manifest it "
     "refuses is one whose first bootstrap would fail.")
+
+
+def manifest_not_a_mapping_remediation(template: str, manifest: str,
+                                       reader: str) -> str:
+    """The remedy where the template's own manifest is not a mapping to its
+    reader (#1059), for the manifest `manifest` in `templates/<template>/`
+    and the reader `reader` names (`the project's own YAML reader`).
+
+    NO VALUE A PERSON TYPES MAKES IT ONE, and only a broken template does:
+    `validate-manifest.py` and `validate-family.py` each refuse a file that
+    is not a mapping before they ask a question, and no value on the
+    template's lines turns a mapping into a list. So the remedy is the
+    defect-of-the-standard one (`_validator_unusable`'s) aimed at the right
+    file, the template's manifest, and not the invalid-value one, which
+    sends a person to retype a value that was never wrong. One sentence for
+    both manifests, so that the holder's and the project's cannot drift.
+    """
+    return (
+        "Remediation: this is a defect in the copy of this standard you ran, "
+        f"not in your values: templates/{template}/{manifest} is broken "
+        f"there, as {reader} makes no mapping of it. Restore it from the "
+        "standard's repository, or reinstall the standard, and run again.")
+
+
+MANIFEST_NOT_A_MAPPING_REMEDIATION = manifest_not_a_mapping_remediation(
+    "assembly-root", MANIFEST_TEMPLATE, "the project's own YAML reader")
 #: The remedy for each kind of problem, so a refusal names it by its kind
 #: (#708), with no conditional nested in another.
 KIND_REMEDIATIONS = {KIND_MISREAD: MANIFEST_MISREAD_REMEDIATION,
                      KIND_INVALID: MANIFEST_INVALID_REMEDIATION,
-                     KIND_UNREADABLE: MANIFEST_UNREADABLE_REMEDIATION}
+                     KIND_UNREADABLE: MANIFEST_UNREADABLE_REMEDIATION,
+                     KIND_NOT_A_MAPPING: MANIFEST_NOT_A_MAPPING_REMEDIATION}
 
 
 def _project_findings(validator, manifest: dict, policy: NamingPolicy):
@@ -5386,12 +5415,14 @@ def manifest_invalid(values: dict, policy: NamingPolicy, what: dict,
 
     The WHOLE manifest is rendered and read, so a rule about how one value
     relates to another (`topic` to `id`, a leg's repository to its role) is
-    asked as the project asks it. `values` must be the complete table;
-    `policy` is the naming policy the project carries a copy of. A WARNING of
-    the validator (a chain link it cannot check offline) is a note and never
-    a refusal, exactly as the project's own exit code treats it, and so is
-    its `  note` (a `SHAPE_PIN_SOURCE_<LINK>` the run guard passed over,
-    #990). Where the project's own YAML reader refuses the file before the
+    asked as the manifest's own validator asks it. `values` must be the
+    complete table; `policy` is the naming policy the validator is handed.
+    A line `manifest_kind.passed_over` names is a note and never a refusal,
+    as that validator's own exit code treats it: the project's WARNING (a
+    chain link it cannot check offline) and its `  note` (a
+    `SHAPE_PIN_SOURCE_<LINK>` the run guard passed over, #990). The holder
+    passes over none (#925), so every line its validator makes is a refusal.
+    Where the manifest's own YAML reader refuses the file before the
     validator can be asked, each sentence is the reader's, naming the value
     on the line it refuses (`_unread_sentences`, #708).
     """
@@ -5404,12 +5435,16 @@ def _invalid_problems(values: dict, policy: NamingPolicy, what: dict,
                       manifest_kind: TemplateManifest = PROJECT_MANIFEST
                       ) -> list[tuple[str, str]]:
     """`manifest_invalid`'s sentences, each with its kind: `invalid` for a
-    finding of the validator's, and `unreadable` where the reader refuses
-    the file the validator would read (#708, the holder's #929), whose
-    words are the reader's and whose remedy is its own
-    (`MANIFEST_UNREADABLE_REMEDIATION`)."""
+    finding of the validator's, `unreadable` where the reader refuses the
+    file the validator would read (#708, the holder's #929), whose words are
+    the reader's and whose remedy is its own
+    (`MANIFEST_UNREADABLE_REMEDIATION`), and `not-a-mapping` where the
+    reader reads that file as something other than a mapping (#1059), whose
+    remedy aims at the template's manifest."""
     notes = _validator_notes(values, policy, template_dir, ignore,
                              manifest_kind)
+    if isinstance(notes, _NotAMapping):
+        return [(KIND_NOT_A_MAPPING, notes.sentence)]
     if isinstance(notes, YamlError):
         return [(KIND_UNREADABLE, sentence) for sentence in _unread_sentences(
             values, what, template_dir, notes, manifest_kind)]
@@ -5459,16 +5494,25 @@ def _unread_sentences(values: dict, what: dict, template_dir: Path,
             f"{' '.join(words)}" for key, words in said.items()]
 
 
+class _NotAMapping(NamedTuple):
+    """What `_validator_notes` answers where the manifest these values render
+    is read as something other than a mapping (#1059): the one `sentence`
+    that says so, a problem of its own kind and not a finding."""
+
+    sentence: str
+
+
 def _validator_notes(values: dict, policy: NamingPolicy, template_dir: Path,
                      ignore: tuple,
                      manifest_kind: TemplateManifest = PROJECT_MANIFEST
-                     ) -> list[str] | YamlError:
+                     ) -> list[str] | YamlError | _NotAMapping:
     """The FINDINGs the validator of the manifest of `manifest_kind` (the
     project's, by default) makes of the manifest these `values` render, less
     the lines `manifest_kind.passed_over` names and the codes in `ignore`;
-    or the `YamlError` its reader raised, where it cannot read that file.
-    The project's WARNINGs and `  note`s are no finding, as its validator's
-    own `main` counts them (#990): `_findings` returns its
+    or the `YamlError` its reader raised, where it cannot read that file, or
+    a `_NotAMapping`, where it reads the file as something other than a
+    mapping. The project's WARNINGs and `  note`s are no finding, as its
+    validator's own `main` counts them (#990): `_findings` returns its
     `link-source-collides` note beside the findings, and read as one,
     `manifest_invalid` gave it as a refusal and `manifest_judged` said None
     (RV1011's SHOULD-1). The holder's validator keeps its findings apart
@@ -5477,7 +5521,11 @@ def _validator_notes(values: dict, policy: NamingPolicy, template_dir: Path,
 
     A MANIFEST THAT IS NOT A MAPPING is one sentence that says so, and is
     about no value: each validator's own `main` refuses such a file before
-    it asks a question, so its question is never put to one (#307).
+    it asks a question, so its question is never put to one (#307). It is
+    a `_NotAMapping` and not a list, because no value a person types makes
+    it and only a broken template does: its kind has the remedy that says
+    so (`KIND_NOT_A_MAPPING`, #1059), and the invalid-value one would send
+    a person to retype a value that was never wrong.
 
     THE VALIDATOR'S OWN DEFECT, NEVER A FINDING (#307). One that raises,
     one that EXITS (a `sys.exit(0)` would end this run with a zero, having
@@ -5493,8 +5541,9 @@ def _validator_notes(values: dict, policy: NamingPolicy, template_dir: Path,
     except YamlError as exc:
         return exc
     if not isinstance(manifest, dict):
-        return ["the manifest this run would write is not a mapping, which "
-                f"is what {manifest_kind.reader} makes of it."]
+        return _NotAMapping(
+            "the manifest this run would write is not a mapping, which "
+            f"is what {manifest_kind.reader} makes of it.")
     validator = manifest_validator(template_dir, manifest_kind=manifest_kind)
     try:
         notes = list(manifest_kind.findings(validator, manifest, policy))
@@ -5537,7 +5586,7 @@ def manifest_judged(values: dict, policy: NamingPolicy,
     """
     notes = _validator_notes(values, policy, template_dir, ignore,
                              manifest_kind)
-    if isinstance(notes, YamlError):
+    if isinstance(notes, (YamlError, _NotAMapping)):
         return None
     judged = {manifest_kind.finding_placeholder.get(_code_of(note))
               for note in notes}
@@ -5551,8 +5600,9 @@ def manifest_value_problems(values: dict, policy: NamingPolicy, what: dict,
                             manifest_kind: TemplateManifest = PROJECT_MANIFEST
                             ) -> list[tuple[str, str]]:
     """`(kind, sentence)` for everything wrong with the values, `kind` being
-    `misread`, `invalid` or `unreadable` (`_invalid_problems`); `[]` when
-    the manifest of `manifest_kind` would hold every one.
+    `misread`, `invalid`, `unreadable` or `not-a-mapping`
+    (`_invalid_problems`); `[]` when the manifest of `manifest_kind` would
+    hold every one.
 
     A misread comes FIRST and alone: a value the reader turns into something
     else makes the manifest invalid in ways that are its consequence (`id:
@@ -5578,7 +5628,8 @@ def refuse_manifest_values(prefix: str, values: dict, policy: NamingPolicy,
     its `tail` finishes the remediation with what only it knows. A manifest
     the project's reader refuses is `-invalid` still, the code a value it
     refuses had when the validator was the one to refuse it, with the
-    reader's remedy (#708)."""
+    reader's remedy (#708); so is one it reads as something other than a
+    mapping, with the remedy for a defect of the standard (#1059)."""
     refuse_manifest_problems(
         prefix, manifest_value_problems(values, policy, what,
                                         misreads=misreads), tail)
diff --git a/tests/test_family_init_yaml_words.py b/tests/test_family_init_yaml_words.py
index 49e46f2b..ff4ccd1f 100644
--- a/tests/test_family_init_yaml_words.py
+++ b/tests/test_family_init_yaml_words.py
@@ -26,6 +26,7 @@
 
 from __future__ import annotations
 
+import re
 import sys
 
 import pytest
@@ -54,8 +55,7 @@
     "`init` cannot be run again over a pushed holder: there is no --force.")
 
 #: The validator's remedy, as `init` gives it, before the sentence it ends
-#: with: what a finding of the validator's is told, and what the manifest
-#: that is not a mapping is still told (lane 5's review of #960, NIT 3).
+#: with: what a finding of the validator's is told.
 VALIDATOR_REMEDY = (
     "Remediation: choose a value the holder's own validate-family.py "
     "accepts; the words after each value are the validator's own. A holder "
@@ -63,6 +63,18 @@
     "the `validate` workflow run it first, and `init` cannot be run again "
     "over a pushed holder: there is no --force.")
 
+#: What the manifest that is not a mapping is told (#1059): the defect of the
+#: standard, aimed at the template's own `family.yaml`, and not the
+#: validator's remedy above, which it was told until #1059 (lane 5's review
+#: of #960, NIT 3, asked a test to hold its kind and remedy; lane 5 agreed on
+#: #473 that this was the better remedy, as no value reaches it).
+NOT_A_MAPPING_REMEDY = (
+    "Remediation: this is a defect in the copy of this standard you ran, "
+    "not in your values: templates/family-root/family.yaml is broken "
+    "there, as the holder's own YAML reader makes no mapping of it. Restore "
+    "it from the standard's repository, or reinstall the standard, and run "
+    "again.")
+
 #: The misread remedy, as `init` gives it, before the sentence it ends with.
 MISREAD_REMEDY = (
     "Remediation: choose another value for each one named, as nothing here "
@@ -135,11 +147,14 @@ def test_a_finding_of_the_validator_keeps_the_validators_remedy():
 
 def test_a_manifest_that_is_not_a_mapping_keeps_its_kind_and_remedy(
         tmp_path):
-    """LANE 5'S REVIEW OF #960, NIT 3. The manifest that is not a mapping
-    is still `invalid` in `_manifest_problems`, so it keeps main's words
-    and the validator's remedy, as the body says. The existing test of it
-    (`test_family_init_values.py`) holds only the sentence; this holds the
-    remedy too, so moving its kind to the reader's fails a test."""
+    """LANE 5'S REVIEW OF #960, NIT 3, MOVED BY #1059. The manifest that is
+    not a mapping keeps its code, `family-manifest-invalid`, and its words,
+    and its kind is `not-a-mapping`, whose remedy is the defect of the
+    standard and names `templates/family-root/family.yaml`. The existing
+    test of it (`test_family_init_values.py`) holds only the sentence; this
+    holds the remedy too, so a change of its kind (#960's mutant M2 made it
+    `unreadable`) fails a test, and so does a return to the validator's
+    remedy, which sends a person to retype a value that was never wrong."""
     template = template_copy(tmp_path, "list", quoted=True)
     (template / "family.yaml").write_bytes(b"- one\n- two\n")
     module = family_module()
@@ -149,7 +164,41 @@ def test_a_manifest_that_is_not_a_mapping_keeps_its_kind_and_remedy(
     assert caught.value.detail == (
         "the manifest this run would write is not a mapping, which is what "
         "the holder's own YAML reader makes of it.")
-    assert caught.value.remediation == VALIDATOR_REMEDY + NOTHING
+    assert caught.value.remediation == NOT_A_MAPPING_REMEDY + NOTHING
+
+
+def test_the_not_a_mapping_remedy_names_each_manifests_own_template():
+    """#1059: the remedy is one sentence, built once, for both manifests, and
+    each names the template file its own reader reads (`family.yaml` under
+    `family-root`, `project.yaml` under `assembly-root`) and no other; the
+    file it names is there. Every kind of problem has a remedy in each
+    manifest's table, so a kind added to one and not the other is a
+    `KeyError` where a person was to be told what to do."""
+    family = family_module()
+    project = shape_materialize.PROJECT_MANIFEST
+    holder = family.HOLDER_MANIFEST
+    kinds = {shape_materialize.KIND_MISREAD, shape_materialize.KIND_INVALID,
+             shape_materialize.KIND_UNREADABLE,
+             shape_materialize.KIND_NOT_A_MAPPING}
+    assert set(project.remediations) == kinds
+    assert set(holder.remediations) == kinds
+    assert family.KIND_NOT_A_MAPPING is shape_materialize.KIND_NOT_A_MAPPING
+    assert holder.remediations[family.KIND_NOT_A_MAPPING] == (
+        NOT_A_MAPPING_REMEDY)
+    assert project.remediations[shape_materialize.KIND_NOT_A_MAPPING] == (
+        "Remediation: this is a defect in the copy of this standard you ran, "
+        "not in your values: templates/assembly-root/project.yaml is broken "
+        "there, as the project's own YAML reader makes no mapping of it. "
+        "Restore it from the standard's repository, or reinstall the "
+        "standard, and run again.")
+    for each, template, manifest in (
+            (holder, "family-root", "family.yaml"),
+            (project, "assembly-root", "project.yaml")):
+        remedy = each.remediations[shape_materialize.KIND_NOT_A_MAPPING]
+        named = re.findall(r"templates/[A-Za-z0-9./_-]+?(?=\s)", remedy)
+        assert named == [f"templates/{template}/{manifest}"], remedy
+        assert (REPO / named[0]).is_file(), named
+        assert (each.template, each.manifest) == (template, manifest)
 
 
 def test_the_projects_remedy_keeps_its_words():
diff --git a/tests/test_scaffold_manifest_values.py b/tests/test_scaffold_manifest_values.py
index c0eecb21..1d0084ce 100644
--- a/tests/test_scaffold_manifest_values.py
+++ b/tests/test_scaffold_manifest_values.py
@@ -1040,14 +1040,20 @@ def test_a_validator_that_failed_to_load_is_not_remembered(tmp_path):
 
 #: What the scaffold says where its template's `project.yaml` is not a
 #: mapping: the sentence `family.py init` says of the holder's, in the
-#: project's words, where it was the validator's `AttributeError`.
+#: project's words, where it was the validator's `AttributeError`. The code
+#: is `-manifest-invalid` still, and the remedy is the defect of the
+#: standard, aimed at `templates/assembly-root/project.yaml` (#1059): no
+#: value reaches this case, so the validator's remedy ("choose a value ...
+#: accepts"), which it carried from #1057 to #1059, sent a person to retype
+#: a value that was never wrong.
 NOT_A_MAPPING = (
     "REFUSED scaffold-manifest-invalid: the manifest this run would write is "
     "not a mapping, which is what the project's own YAML reader makes of "
-    "it.\nRemediation: choose a value the project's own validate-manifest.py "
-    "accepts; the words after each value are the validator's own, and a "
-    "project it refuses is one whose first bootstrap would fail. Nothing was "
-    "created, and `--dry-run` refuses the same.\n")
+    "it.\nRemediation: this is a defect in the copy of this standard you "
+    "ran, not in your values: templates/assembly-root/project.yaml is broken "
+    "there, as the project's own YAML reader makes no mapping of it. Restore "
+    "it from the standard's repository, or reinstall the standard, and run "
+    "again. Nothing was created, and `--dry-run` refuses the same.\n")
 
 
 def test_a_manifest_that_is_not_a_mapping_is_said_and_not_a_validator_defect(
@@ -1072,6 +1078,31 @@ def test_a_manifest_that_is_not_a_mapping_is_said_and_not_a_validator_defect(
     assert sorted(p.name for p in run.iterdir()) == [SCRATCH]
 
 
+def test_a_manifest_that_is_not_a_mapping_is_a_kind_of_its_own(tmp_path):
+    """#1059: the questions name the problem `not-a-mapping`, which is
+    neither a finding (`invalid`) nor a line the reader refuses
+    (`unreadable`), because its remedy is the defect of the standard and not
+    a value to choose. The public sentences are the same list of text they
+    were, and no value can be said to pass the validator of a file it was
+    never asked about (`manifest_judged` is None, as for a line the reader
+    refuses)."""
+    copy = tmp_path / "assembly-root"
+    shutil.copytree(REPO / "templates" / "assembly-root", copy,
+                    ignore=shutil.ignore_patterns("__pycache__", "*.pyc"))
+    (copy / "project.yaml").write_text("- one\n- two\n", encoding="utf-8")
+    policy = shape_materialize.NamingPolicy.load(
+        REPO / shape_materialize.NAMING_POLICY_YAML)
+    sentence = ("the manifest this run would write is not a mapping, which "
+                "is what the project's own YAML reader makes of it.")
+    assert shape_materialize.KIND_NOT_A_MAPPING == "not-a-mapping"
+    assert shape_materialize.manifest_value_problems(
+        {}, policy, {}, template_dir=copy) == [
+        (shape_materialize.KIND_NOT_A_MAPPING, sentence)]
+    assert shape_materialize.manifest_invalid({}, policy, {}, copy) == [
+        sentence]
+    assert shape_materialize.manifest_judged({}, policy, copy) is None
+
+
 def test_a_validator_that_cannot_be_asked_says_so_in_the_projects_words(
         tmp_path):
     """The refusal `family.py init` gives its holder's validator, byte for

From 7fa6d10532f8e629e7a294fc0d634f433f61852a Mon Sep 17 00:00:00 2001
From: Brett Heap <service@opensoft.dev>
Date: Tue, 20 Oct 2026 16:16:31 +0000
Subject: [PATCH 2/3] adopt-project.py: `check` of a plan against a template
 whose `project.yaml` the reader makes no mapping of gives the remedy `plan`
 and the scaffold give (a defect in the copy of the standard, naming
 `templates/assembly-root/project.yaml`), and no longer says to choose a value
 the validator accepts or to correct the plan's values, none of which is at
 fault (#1059)

`_manifest_findings` chose `MANIFEST_UNREADABLE_REMEDIATION` for a reader that
refuses the manifest and `MANIFEST_INVALID_REMEDIATION` for every other kind,
so the not-a-mapping kind #1064's first commit added got the invalid-value
remedy, followed by "`execute` writes the plan's values into the project's
`project.yaml` as they stand, so correct each one named here in the plan, or
re-run `plan` with a value the validator accepts." No value is at fault where
the template's manifest is no mapping. The remedy now comes from
`PROJECT_MANIFEST.remediations[kind]`, as `plan`'s does, and the sentence
about the plan's values is left out for that kind alone. The finding code
(`plan-manifest-invalid`) and every other kind's words are as they were.

`tests/test_adopt_plan_yaml_quoting.py` names the reader's remedy through
`shape_materialize` now, because `adopt-project.py` no longer imports it.

Part of #1059

Lane: openreposhape-3 (openRepoShape-3)
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 adopt-project.py                      | 33 ++++++++-----
 tests/test_adopt_manifest_values.py   | 69 ++++++++++++++++++++++++---
 tests/test_adopt_plan_yaml_quoting.py |  3 +-
 3 files changed, 86 insertions(+), 19 deletions(-)

diff --git a/adopt-project.py b/adopt-project.py
index a8b1ef34..86dd27b4 100755
--- a/adopt-project.py
+++ b/adopt-project.py
@@ -278,9 +278,8 @@
 # into its manifest, and whether a repository's name can be a directory's:
 # asked of the plan's values by `plan`, `check` and `execute` (#261).
 from shape_materialize import (  # noqa: E402
-    KIND_UNREADABLE, MANIFEST_INVALID_REMEDIATION,
-    MANIFEST_UNREADABLE_REMEDIATION, manifest_judged, manifest_value_problems,
-    refuse_manifest_values, refuse_unstorable_names,
+    KIND_NOT_A_MAPPING, PROJECT_MANIFEST, manifest_judged,
+    manifest_value_problems, refuse_manifest_values, refuse_unstorable_names,
 )
 # What GitHub keeps a repository's name, a topic and an organisation's name
 # to, asked by `execute` before either leg exists where GitHub is (#838).
@@ -5581,6 +5580,12 @@ def _manifest_findings(plan: Plan) -> tuple[list[str], list[str]]:
     what was read (`_named_as_read`), because the sentence goes on to
     quote `str` of it, the text `execute` would write and not what the
     plan says.
+
+    A MANIFEST THE READER MAKES NO MAPPING OF is one finding about no value
+    (`KIND_NOT_A_MAPPING`, #1059): its remedy is the one for a defect of the
+    copy of the standard, which `PROJECT_MANIFEST.remediations` gives the
+    kind, and it has no sentence about the plan's values, none of which is
+    at fault.
     """
     naming = NamingPolicy.load(NAMING_POLICY)
     values = _manifest_values(plan, naming)
@@ -5591,17 +5596,21 @@ def _manifest_findings(plan: Plan) -> tuple[list[str], list[str]]:
                                        ignore=_validator_ignores(plan))
     if not problems:
         return [], []
-    # Where the project's own YAML reader refuses the manifest, the words
-    # are the reader's, and so is the remedy (#708).
-    remedy = (MANIFEST_UNREADABLE_REMEDIATION
-              if problems[0][0] == KIND_UNREADABLE
-              else MANIFEST_INVALID_REMEDIATION)
+    # The remedy is the kind's own: where the project's own YAML reader
+    # refuses the manifest, the words are the reader's, and so is the remedy
+    # (#708); where it reads the template's manifest as something other than
+    # a mapping, no value is at fault and only the template is, so the remedy
+    # is the defect-of-the-standard one and the sentence about the plan's
+    # values is left out (#1059).
+    kind = problems[0][0]
+    values_tail = (
+        "" if kind == KIND_NOT_A_MAPPING
+        else " `execute` writes the plan's values into the project's "
+        "`project.yaml` as they stand, so correct each one named here in "
+        "the plan, or re-run `plan` with a value the validator accepts.")
     return ([f"FINDING plan-manifest-invalid: {sentence}"
              for _, sentence in problems],
-            [f"{remedy} `execute` writes the plan's "
-             "values into the project's `project.yaml` as they stand, so "
-             "correct each one named here in the plan, or re-run `plan` with "
-             "a value the validator accepts."])
+            [f"{PROJECT_MANIFEST.remediations[kind]}{values_tail}"])
 
 
 def _validator_judged(plan: Plan) -> frozenset[str] | None:
diff --git a/tests/test_adopt_manifest_values.py b/tests/test_adopt_manifest_values.py
index 6feab907..d8823636 100644
--- a/tests/test_adopt_manifest_values.py
+++ b/tests/test_adopt_manifest_values.py
@@ -940,11 +940,12 @@ def test_a_text_value_the_template_now_holds_is_no_finding_in_the_list_check_pri
 
 # --- a validator that cannot be asked ---------------------------------------
 
-def a_copy_of_the_standard(base: Path, remake) -> Path:
+def a_copy_of_the_standard(base: Path, remake,
+                           rel: str = "scripts/validate-manifest.py") -> Path:
     """The standard, as its own git checkout (the tools name their revision),
-    with its template's `validate-manifest.py` made over by `remake`, which is
-    given the real text and returns the text to put there, or None to remove
-    the file."""
+    with its template's `validate-manifest.py`, or the template file `rel`,
+    made over by `remake`, which is given the real text and returns the text
+    to put there, or None to remove the file."""
     copy = base / "standard"
     shutil.copytree(REPO, copy, symlinks=True, ignore=shutil.ignore_patterns(
         ".git", "__pycache__", ".pytest_cache", "tests", "docs", "handoffs"))
@@ -952,8 +953,7 @@ def a_copy_of_the_standard(base: Path, remake) -> Path:
     git("add", "-A", cwd=copy)
     git("-c", "user.name=t", "-c", "user.email=t@t", "commit", "-q",
         "--no-gpg-sign", "-m", "a copy of the standard", cwd=copy)
-    path = copy / "templates" / "assembly-root" / "scripts" / (
-        "validate-manifest.py")
+    path = copy / "templates" / "assembly-root" / rel
     remade = remake(path.read_text(encoding=UTF8))
     if remade is None:
         path.unlink()
@@ -995,3 +995,60 @@ def test_plan_and_check_name_a_validator_that_cannot_be_asked(
         assert "a defect in the copy of this standard you ran" in result.stderr
         assert "Traceback" not in result.stderr
     assert not out.exists(), "a plan was written"
+
+
+# --- a template's manifest that is no mapping (#1059) ------------------------
+
+#: What `plan` and `check` say where the template's `project.yaml` is read as
+#: something other than a mapping: the code is `plan-manifest-invalid` still,
+#: and the remedy is the defect of the standard, aimed at the template file.
+#: No value of the plan is at fault, so `check` says nothing of the plan's
+#: values: the invalid-value remedy ("choose a value ... accepts") and the
+#: sentence `check` adds to it (`execute` writes the plan's values as they
+#: stand, so correct each one) sent a person to retype a value that was never
+#: wrong.
+NOT_A_MAPPING = ("the manifest this run would write is not a mapping, which "
+                 "is what the project's own YAML reader makes of it.")
+NOT_A_MAPPING_REMEDY = (
+    "Remediation: this is a defect in the copy of this standard you ran, not "
+    "in your values: templates/assembly-root/project.yaml is broken there, as "
+    "the project's own YAML reader makes no mapping of it. Restore it from "
+    "the standard's repository, or reinstall the standard, and run again.")
+
+
+@pytest.mark.parametrize("made", [
+    pytest.param("- one\n- two\n", id="a-list"),
+    pytest.param("# nothing here but a comment\n", id="only-a-comment"),
+])
+def test_check_says_a_template_that_is_no_mapping_is_the_standards_defect(
+        world, tmp_path, made):
+    """`check` gave this case the invalid-value remedy, and its sentence about
+    the plan's values, though `plan` and the scaffold said the defect was the
+    copy's (#1059): the remedy comes from the kind, as the other tools' does,
+    and no sentence names a value, for none is at fault."""
+    copy = a_copy_of_the_standard(tmp_path, lambda real: made, "project.yaml")
+    checked = run_script(copy / "adopt-project.py", "check", "--plan",
+                         str(world["plan"]))
+    assert checked.returncode == 1, checked.stderr + checked.stdout
+    # The whole of what `check` says: one finding, and the remedy on the
+    # line after it, which ends where the remedy does.
+    assert (f"{FINDING}: {NOT_A_MAPPING}\n{NOT_A_MAPPING_REMEDY}\n\n"
+            "1 finding(s) in ") in checked.stderr, checked.stderr
+    assert checked.stderr.count("Remediation: ") == 1, checked.stderr
+    for words in (shape_materialize.MANIFEST_INVALID_REMEDIATION,
+                  "`execute` writes the plan's values",
+                  "correct each one named here in the plan",
+                  "re-run `plan` with a value the validator accepts"):
+        assert words not in checked.stderr, checked.stderr
+    assert "Traceback" not in checked.stderr
+    # `plan` asks the same question of the same template, and says it in the
+    # same remedy, with its own sentence after it.
+    out = tmp_path / "not-written.yaml"
+    planned = run_script(
+        copy / "adopt-project.py", "plan", "--source", str(world["source"]),
+        "--project", PROJECT, "--org", "testorg", "--elected-by", "Test Human",
+        "--elected-on", "2026-09-02", "--out", str(out))
+    assert planned.returncode == 2, planned.stderr + planned.stdout
+    assert (f"REFUSED {INVALID}: {NOT_A_MAPPING}\n{NOT_A_MAPPING_REMEDY} "
+            "No plan was written.\n") in planned.stderr, planned.stderr
+    assert not out.exists(), "a plan was written"
diff --git a/tests/test_adopt_plan_yaml_quoting.py b/tests/test_adopt_plan_yaml_quoting.py
index e1f42c47..127e5b28 100644
--- a/tests/test_adopt_plan_yaml_quoting.py
+++ b/tests/test_adopt_plan_yaml_quoting.py
@@ -1788,7 +1788,8 @@ def test_a_manifest_its_reader_refuses_is_the_validators_alone(
                            "refuses: "), stderr
     assert stderr.count("Remediation: ") == 1, stderr
     # The words are the reader's, and since #708 so is the remedy.
-    assert adopter.MANIFEST_UNREADABLE_REMEDIATION in stderr, stderr
+    assert sys.modules["shape_materialize"].MANIFEST_UNREADABLE_REMEDIATION \
+        in stderr, stderr
     assert VALIDATOR_REMEDIATION_START not in stderr, stderr
 
 

From 166ae7bde8961745ea2ce0e72ebe3be99f0d9e80 Mon Sep 17 00:00:00 2001
From: Brett Heap <service@opensoft.dev>
Date: Tue, 20 Oct 2026 17:17:49 +0000
Subject: [PATCH 3/3] tests/test_reader_refusals_named.py and
 scripts/shape_materialize.py: the test that the adopt tool gives the one
 reader remedy reads it through `PROJECT_MANIFEST`, which `adopt-project.py`
 imports, and `manifest_invalid`'s docstring says every line the holder's
 `findings` returns is a refusal (#1059)

Review round on #1064 (RV1064, MUST-1 and NIT-1). Item 4 stopped
`adopt-project.py` importing `MANIFEST_UNREADABLE_REMEDIATION`, so
`test_adopt_gives_the_one_reader_remedy` raised AttributeError at the head.
It keeps its point, one reader remedy and not a second copy, through
`adopter.PROJECT_MANIFEST is shape_materialize.PROJECT_MANIFEST` and that
table's `KIND_UNREADABLE` row being `shape_materialize`'s own constant.
The docstring's "every line its validator makes" also counted the holder
validator's `  ok` notes, which `_holder_findings` never asks for.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 scripts/shape_materialize.py        | 2 +-
 tests/test_reader_refusals_named.py | 4 +++-
 2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/scripts/shape_materialize.py b/scripts/shape_materialize.py
index d77b3f22..e55f092c 100644
--- a/scripts/shape_materialize.py
+++ b/scripts/shape_materialize.py
@@ -5421,7 +5421,7 @@ def manifest_invalid(values: dict, policy: NamingPolicy, what: dict,
     as that validator's own exit code treats it: the project's WARNING (a
     chain link it cannot check offline) and its `  note` (a
     `SHAPE_PIN_SOURCE_<LINK>` the run guard passed over, #990). The holder
-    passes over none (#925), so every line its validator makes is a refusal.
+    passes over none (#925), so every line its `findings` returns is a refusal.
     Where the manifest's own YAML reader refuses the file before the
     validator can be asked, each sentence is the reader's, naming the value
     on the line it refuses (`_unread_sentences`, #708).
diff --git a/tests/test_reader_refusals_named.py b/tests/test_reader_refusals_named.py
index b16e990d..8dbfdaf8 100644
--- a/tests/test_reader_refusals_named.py
+++ b/tests/test_reader_refusals_named.py
@@ -349,7 +349,9 @@ def test_the_validators_sentence_is_left_out_where_unsafe_value_fires(
 
 def test_adopt_gives_the_one_reader_remedy(adopter):
     """`check`'s remedy is the scaffold's and `plan`'s, not a second copy."""
-    assert adopter.MANIFEST_UNREADABLE_REMEDIATION is (
+    assert adopter.PROJECT_MANIFEST is shape_materialize.PROJECT_MANIFEST
+    assert adopter.PROJECT_MANIFEST.remediations[
+        shape_materialize.KIND_UNREADABLE] is (
         shape_materialize.MANIFEST_UNREADABLE_REMEDIATION)
     assert NOT_THE_VALIDATORS not in (
         shape_materialize.MANIFEST_UNREADABLE_REMEDIATION)