templates/assembly-root/project.yaml and the two leg pins write eight text placeholders bare (id, elected_on, visibility, tracking_branch, the two leg paths and submodule_paths), so a checked value YAML reads as another type (007, 2026, true, null) is misread by the project or refused by the tool; quoting them reads every one back exactly and lets numeric branch names adopt #259

(lane openRepoShape-1, 2026-10-11T21:42:44Z)

Found by this lane's re-verification of the #181 branch (fix/adopt-plan-quote-yaml-keywords at a0ff15b), as the one change that would fix the scaffold's twin of #181 and keep numeric branch names working. Pre-existing on main 39ac59c. It is a proposal as much as a defect, and it is filed so the choice is made once, for every tool that renders these templates.

What is wrong. The assembly root's three YAML templates write eight text placeholders bare. The repository's own YAML loader reads a bare 007 as the number 7, 2026 as 2026, true as True and null as None. So any checked value that YAML reads as another type is misread by the project that receives it, or the tool has to refuse it:

• scaffold-project.py misreads it: scaffold-project.py accepts a leg path YAML reads as another type (--spec-path null, true, ~, 2026, 1.5), so it creates all three repositories and the new project's own bootstrap fails manifest-leg-path #225 for the leg paths, and scaffold-project.py writes --id and --tracking-branch into project.yaml unquoted, so --id null or --id true scaffolds a project whose first bootstrap fails manifest-id, and --tracking-branch true, 007 or null puts the clone's legs on True, 7 or main with no upstream: #181's defect on the scaffold side, beside #225 #258 for --id and --tracking-branch.
• adopt-project.py on main misreads it too (adopt-project.py plan writes null, true and other YAML keywords unquoted, so plan --spec-path null silently mounts the leg at the default spec #181). --tracking-branch 007 puts the clone's legs on 7 with no upstream.
• The adopt-project.py plan writes null, true and other YAML keywords unquoted, so plan --spec-path null silently mounts the leg at the default spec #181 branch refuses every such value at plan, including numeric branch names that main adopts correctly by accident. Main's readers turn the value back into text with str() (checked_value at adopt-project.py:2427-2428, and templates/assembly-root/scripts/bootstrap.py:347-349), and str(2026) gives 2026 back.

Quoted, every one of these values reads back exactly.

SHAPE=<openRepoShape checkout on main>; SHAPE181=<checkout of fix/adopt-plan-quote-yaml-keywords>
export GIT_AUTHOR_NAME=T GIT_AUTHOR_EMAIL=t@example.invalid GIT_COMMITTER_NAME=T GIT_COMMITTER_EMAIL=t@example.invalid
cd "$SHAPE" || exit 1
grep -n -E '^[a-z_]+: \{\{|^    path: \{\{' templates/assembly-root/project.yaml templates/assembly-root/contracts/spec-pin.yaml \
    templates/assembly-root/contracts/code-pin.yaml | grep -v -E 'REPOSITORY|DIGEST_DEFINITION|NEUTRAL_PRODUCT_PINS|TOPIC'
python3 - <<'EOF'
import sys; sys.path.insert(0, "scripts")
from repo_shape import parse_yaml
for v in ("2026", "007", "1.5", "true", "null", "20261011"):
    bare = parse_yaml(f"tracking_branch: {v}\n")["tracking_branch"]
    quoted = parse_yaml(f'tracking_branch: "{v}"\n')["tracking_branch"]
    print(f"tracking_branch: {v:<9} reads back {bare!r:<9}  quoted: {quoted!r}")
EOF
TMP=$(mktemp -d)
git init -q -b main "$TMP/Thing" && (cd "$TMP/Thing" && printf '# Thing\n' > README.md && git add -A && git commit -qm init)
for tree in "$SHAPE" "$SHAPE181"; do
  for tb in 2026 007; do
    python3 "$tree/adopt-project.py" plan --source "$TMP/Thing" --project Northwind --org testorg \
        --elected-by 'T H' --elected-on 2026-09-02 --tracking-branch $tb --out "$TMP/plan.yaml" > "$TMP/out" 2>&1
    rc=$?
    echo "$(git -C "$tree" rev-parse --short HEAD): plan --tracking-branch $tb: exit $rc $(grep -o -m1 '^REFUSED [a-z-]*' "$TMP/out")"
  done
done

Observed on main 39ac59c and on the #181 branch at a0ff15b:

templates/assembly-root/project.yaml:31:id: {{PROJECT_ID}}
templates/assembly-root/project.yaml:47:elected_on: {{ELECTED_ON}}
templates/assembly-root/project.yaml:62:visibility: {{VISIBILITY}}
templates/assembly-root/project.yaml:67:tracking_branch: {{TRACKING_BRANCH}}
templates/assembly-root/project.yaml:159:    path: {{SPEC_PATH}}
templates/assembly-root/project.yaml:163:    path: {{CODE_PATH}}
templates/assembly-root/contracts/spec-pin.yaml:22:submodule_path: {{SPEC_PATH}}
templates/assembly-root/contracts/code-pin.yaml:22:submodule_path: {{CODE_PATH}}
tracking_branch: 2026      reads back 2026       quoted: '2026'
tracking_branch: 007       reads back 7          quoted: '007'
tracking_branch: 1.5       reads back 1.5        quoted: '1.5'
tracking_branch: true      reads back True       quoted: 'true'
tracking_branch: null      reads back None       quoted: 'null'
tracking_branch: 20261011  reads back 20261011   quoted: '20261011'
39ac59c: plan --tracking-branch 2026: exit 0
39ac59c: plan --tracking-branch 007: exit 0
a0ff15b: plan --tracking-branch 2026: exit 2 REFUSED adopt-manifest-misread
a0ff15b: plan --tracking-branch 007: exit 2 REFUSED adopt-manifest-misread

End to end on main 39ac59c, adopting with --tracking-branch 2026 puts both legs on 2026 with upstream origin/2026, and bootstrap exits 0. With --tracking-branch 007, both leg repositories are pushed on 007, while the clone's legs land on 7 with no upstream (fatal: no upstream configured for branch '7'), and bootstrap still exits 0.

Why it matters. Today the choice is between two losses:

• Refuse, as the adopt-project.py plan writes null, true and other YAML keywords unquoted, so plan --spec-path null silently mounts the leg at the default spec #181 branch does. A project whose tracking branch is a number (2026, 1.5) then cannot be adopted at all, though main adopts it correctly.
• Misread, as the scaffold and main do. The project is pushed on one branch and checked out on another, or its gate fails manifest-id or manifest-leg-path at the first bootstrap.

Every new reader of these fields also has to repeat the str() and the None fallback.

Where (main 39ac59c):

• The eight bare lines above. name: (templates/assembly-root/project.yaml:32), reference: (:42) and elected_by: (:46) are already quoted, so quoting is the templates' own convention for text.
• scripts/shape_materialize.py:210-225: project.yaml and both leg pins are TEMPLATED, which the module says are "NOT digest-pinned in the shape pin". So quoting changes no pinned digest in any project. update-shape.py renders no template: in an existing project.yaml it rewrites only the shape: block's pin lines, which none of the eight lines is. scaffold-project.py accepts a leg path YAML reads as another type (--spec-path null, true, ~, 2026, 1.5), so it creates all three repositories and the new project's own bootstrap fails manifest-leg-path #225 says quoting "moves the shape digest": it moves only the standard's own tree_sha256, as every commit to this repository does.
• templates/family-root/family.yaml:33, :41, :46 and :51 hold id, created_on, visibility and tracking_branch bare too.
• The readers that cope with a misread today: templates/assembly-root/scripts/bootstrap.py:347-349 and adopt-project.py:2427-2428.

What would fix it.

• Quote the text placeholders ("{{TRACKING_BRANCH}}" and the others above) in the three assembly-root YAML templates, and in family.yaml.
• What the flags admit is checked by checked_value, PROJECT_ID_RE, argparse choices and election_date, and none of those admits " or \. So double quotes read each value back exactly. A plan's hand-edited values, such as visibility, are checked nowhere (the companion issue on validator-refused values), and they would need the same check before they are quoted.
• Then adopt-project.py plan writes null, true and other YAML keywords unquoted, so plan --spec-path null silently mounts the leg at the default spec #181's misread guard can be dropped for these fields, numeric branch names adopt again, and scaffold-project.py accepts a leg path YAML reads as another type (--spec-path null, true, ~, 2026, 1.5), so it creates all three repositories and the new project's own bootstrap fails manifest-leg-path #225 and the scaffold's --id and --tracking-branch twin close with one change.
• Tests that read rendered lines such as tracking_branch: main change with it. Projects scaffolded or adopted before the change keep their bare lines, which still read correctly for every name that is plain text.

Related. #181: adopt's plan writer and manifest. Its branch refuses these values instead. #225: the scaffold's leg paths; its option (b) quotes the four leg-path lines. #251: the scaffold's --referent-chain links, which naming_block writes into project.yaml as typed. #258: the scaffold's --id and --tracking-branch.

Not claimed.

🤖 Generated with Claude Code