v1.92.18.0 fix(install): --project resolves to its git toplevel and refuses a repo slug (GST-743) (#3783)

* test(install): a --project repo slug is a usage error, not a project-less verdict (GST-743, failing first)

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* fix(install): --project refuses a value that is not a directory (GST-743)

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* fix: pre-landing review fixes (GST-743: key --project by its git toplevel, refuse a non-directory before cloning, ignore CDPATH)

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* fix: pre-landing review fixes (GST-743: --project resolves to its git toplevel for pins and the key; an unenterable directory is refused)

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* changelog: GST-743 fragment names the subpackage-pin and admission-key behavior

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* docs: capy-install names how --project resolves (GST-743)

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

---------

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

test/gstack-capy-install.test.ts

@@ -156,6 +156,30 @@ describe('gstack-capy-install', () => {
     expect(run(f, ['--revision']).status).toBe(2);
   });
 
+  // Value: protects=--project names the project the verdict and launch file are keyed to;
+  //   fails_when=a repo slug (owner/name) that is no directory silently keys the verdict to no project, so a later check reads a stale one;
+  //   why_new=GST-743, HARN-12 lost three pregate runs to it; seam=bin/gstack-capy-install --project; no_claim=resolving slugs
+  test('--project that is not a directory (a repo slug) is a usage error: exit 2, no setup, no verdict', () => {
+    const f = fixture();
+    const r = run(f, ['--for', 'ship', '--project', 'garrytan/harness-evals']);
+    expect([r.status, r.stderr.trim()]).toEqual([2, "gstack-capy-install: --project takes a directory path; 'garrytan/harness-evals' is not a directory (pass the project checkout's path, not a repo slug)"]);
+    expect(f.calls().filter(l => l.startsWith('setup') || l.startsWith('doctor '))).toEqual([]);
+    expect(fs.existsSync(path.join(f.home, '.gstack-state/install-verdicts'))).toBe(false);
+  });
+
+  // Value: protects=the installer keys the verdict by the project's git toplevel, the key pregate admission reads (lib/install-verdict.ts installProject);
+  //   fails_when=--project <repo>/<subdir> writes a verdict at the subdirectory's key, which admission never reads; seam=bin/gstack-capy-install --project
+  test('--project names a subdirectory: the verdict is keyed by its git toplevel, the same file --project <toplevel> writes', () => {
+    const f = fixture();
+    const project = path.join(f.base, 'proj');
+    fs.mkdirSync(path.join(project, 'packages/x'), { recursive: true });
+    sh('git init -q', project);
+    const verdictOf = (r: { stdout: string; status: number | null; stderr: string }) => { expect(r.status, r.stdout + r.stderr).toBe(0); return r.stdout.match(/GSTACK_INSTALL_VERDICT=(\S+)/)![1]!; };
+    const sub = verdictOf(run(f, ['--for', 'autoplan', '--project', path.join(project, 'packages/x')]));
+    expect(sub).toBe(verdictOf(run(f, ['--for', 'autoplan', '--project', project])));
+    expect(JSON.parse(fs.readFileSync(sub, 'utf8')).project).toBe(fs.realpathSync(project));
+  });
+
   test('preflight: a missing tool stops with exit 3 and INSTALL_PREFLIGHT_FAILED before ./setup runs', () => {
     const f = fixture({ jq: false });
     const r = run(f);