adopt-project.py: plan --pin takes product@<40 hex> and execute writes its pin file as the scaffold does, so an adopted root passes validate-pins.py (#273); a --pin-source that cannot answer is pin-source-unreadable (#339)

docs/cli.md

@@ -364,7 +364,9 @@ usage: adopt-project.py plan [-h] --source SOURCE --project PROJECT
                              [--elected-on ELECTED_ON] [--reference REFERENCE]
                              [--tracking-branch TRACKING_BRANCH]
                              [--spec-path SPEC_PATH] [--code-path CODE_PATH]
-                             [--pin PIN] [--allow-empty-leg {spec,code}]
+                             [--pin openProduct@COMMIT]
+                             [--pin-owner PIN_OWNER] [--pin-source PIN_SOURCE]
+                             [--allow-empty-leg {spec,code}]
                              [--path-policy PATH_POLICY] [--out OUT]
                              [--work-dir WORK_DIR]
 
@@ -428,12 +430,26 @@ options:
                         `code` pass. Either refusal writes no plan and
                         rewrites nothing, and its `Remediation:` line states
                         the whole rule; you pass the value again.
-  --pin PIN             a neutral product this project declares a pin on — a
-                        NAME only, e.g. --pin openGlass or --pin
-                        opensoft/openGlass to name the owner explicitly.
-                        Adopting a project pins no commit at plan time, so a
-                        trailing @<commit> (scaffold-project.py's syntax) is
-                        refused.
+  --pin openProduct@COMMIT
+                        declare a neutral-product pin, as scaffold-project.py
+                        --pin does, e.g. --pin openGlass@<40 hex>. `plan`
+                        reads the digest of the product's tree at that commit
+                        (from --pin-source, or `gh api`) and records it in the
+                        plan; `execute` writes
+                        contracts/<openproduct>-pin.yaml from it and lists the
+                        product in the manifest. A name with no @<commit>, a
+                        product named spec, code or shape, and one product
+                        twice are refused. Repeatable.
+  --pin-owner PIN_OWNER
+                        the organisation an UNQUALIFIED --pin name resolves
+                        under (default: opensoft, where every neutral
+                        open<Product> lives — never the adopted repository's
+                        own --org). Name the owner in --pin itself
+                        (owner/openProduct@<sha>) to override it for one pin.
+  --pin-source PIN_SOURCE
+                        a local clone to compute --pin digests from, instead
+                        of reading the forge with `gh api` (the TEST path; no
+                        network)
   --allow-empty-leg {spec,code}
                         record in the plan that this leg having NO path is
                         intended, so it may be SEEDED from the shape's

tests/test_adopt_manifest_values.py

@@ -242,12 +242,22 @@ def test_plan_asks_what_check_asks_of_the_same_keys(adopter, tmp_path,
     monkeypatch.setattr(adopter, "_flag_plan",
                         lambda *a: built.append(real(*a)) or built[-1])
     source = make_source_repo(tmp_path / "Thing")
+    # A pin is `<product>@<40 hex>` with its digest read at `plan` (#273):
+    # a local stand-in for `openGlass` answers it, with no network.
+    glass = tmp_path / "openGlass"
+    glass.mkdir()
+    git("init", "-q", "-b", "main", cwd=glass)
+    (glass / "README.md").write_bytes(b"# openGlass\n")
+    git("add", "-A", cwd=glass)
+    git("commit", "-qm", "seed", cwd=glass)
+    commit = git("rev-parse", "HEAD", cwd=glass).stdout.strip()
     out = tmp_path / "plan.yaml"
     code = adopter.main(["plan", "--source", str(source), "--project",
                          PROJECT, "--org", "testorg", "--elected-by",
                          "Test Human", "--elected-on", "2026-09-02",
                          "--visibility", "internal", "--tracking-branch",
-                         "trunk", "--pin", "openGlass", "--out", str(out)])
+                         "trunk", "--pin", f"openGlass@{commit}",
+                         "--pin-source", str(glass), "--out", str(out)])
     assert code == 0, capsys.readouterr().err
     (flag_plan,) = built
     written = adopter.Plan.load(out)