# G-022 Scriptable safe fossil move/rename in `dev repo`; rename this project's fossil repo to punkshell

Status: proposed
Scope: src/modules/punk/mix/commandset/repo-999999.0a1.0.tm, src/modules/punk/repo-999999.0a1.0.tm, src/tests/modules/punk/mix/testsuites/repo/
Goal: the `dev repo` commandset can move and rename fossil repositories non-interactively and safely - all checkouts repointed, no phantom central config-db entries, no dangling old repo db, fossil project-name renamable with project-code unchanged - and this project's fossil repo (currently project-name 'shellspy') is renamed to 'punkshell' through that mechanism via a G-015 piped script call, not by hand.
Acceptance: the commandset provides a flag-driven (no stdin prompts) move/rename operation which on a scratch repo with an open checkout: repoints every registered checkout, leaves the central config-db listing only the new path, removes or archives the old repo db file (per option), clears stale ckout: back-references, and applies a requested project-name change while preserving project-code; the GAP characterization tests in src/tests/modules/punk/mix/testsuites/repo/fossilmove.test are updated to assert the clean behaviour and pass; after G-015 is achieved, this repo's fossil db (shellspy.fossil / project-name shellspy) is renamed to punkshell via the new operation invoked through a piped `script` call, with `fossil info` in this checkout showing the new repository path and project-name and `fossil all ls` free of the old path.

## Context

This project's fossil repository is recorded as project-name 'shellspy'
(C:/Users/sleek/.fossils/shellspy.fossil at the time of writing) but the
desired project name is punkshell ('shellspy' names only the experimental
launch subcommand). Rather than having an agent perform ad-hoc repo surgery,
the rename should go through the `dev repo` system - which makes the
prerequisite the reliability of agent-driven `script` calls (G-015).

Current capability (examined 2026-07-06, characterized by
src/tests/modules/punk/mix/testsuites/repo/fossilmove.test):

- `punk::mix::commandset::repo::fossil-move-repository` exists but is fully
  interactive (punk::repo::askuser prompts throughout) - unusable from a
  piped script call.
- Its move primitive is `file copy` + `fossil test-move-repository` per
  checkout. Verified in a FOSSIL_HOME-isolated sandbox, this sequence:
  - correctly repoints the checkout's repository link (the part that works);
  - leaves the old .fossil file on disk (copy, never delete);
  - leaves a phantom `repo:` entry for the old path in the central fossil
    config-db (`fossil all ls` lists both old and new paths);
  - leaves a stale `ckout:` back-reference in the old repo db.
- Nothing renames the fossil project-name: moving/renaming the db file leaves
  `project-name` in the repo db config table untouched, and fossil has no
  plain CLI setter for it (web UI Admin/Configuration, or a config-table
  update e.g. via `fossil sql`).

Phantom central-db entries matter beyond hygiene: `dev projects.work`
(G-016/G-017's agent-facing project discovery) reads the central config-db, so
phantoms surface directly in agent search results.

## Approach

- Extend the commandset with a non-interactive mode (explicit flags for
  target path/name, project-name change, old-db disposition) alongside the
  existing interactive flow; punk::args-documented per module conventions.
- Safe-move sequence: copy to target, repoint every registered checkout
  (`fossil test-move-repository` per checkout, or direct checkout-db vvar
  update), remove the old central-db `repo:` entry, clear/transfer stale
  `ckout:` records, then remove or archive the old db file - ordered so a
  failure mid-way never leaves checkouts pointing at a missing db.
- Project-name rename: update `project-name` in the repo db config table
  (project-code must never change - it is the repo's identity); surface both
  names in the operation's report.
- The fossilmove.test GAP tests (3.2, 3.3, 3.4, 4.1) pin today's behaviour;
  flipping them to assert clean behaviour is part of this goal's verification.
- The final application to this repo runs through a G-015 piped `script`
  call, as the proving use of agent-driven `dev repo` operations.

## Alternatives considered

- Ad-hoc agent-performed rename (fossil sql + file rename + manual central-db
  cleanup by hand) - rejected: the point is that repo surgery goes through
  audited `dev repo` tooling agents can reuse, not one-off incantations.
- Renaming only the .fossil file and leaving project-name as shellspy -
  rejected: the project-name is the visible identity in `fossil info`,
  timelines and project listings; it is the thing actually wrong.

## Notes

- Dependent on G-015 (reliable piped script calls) for the application step -
  satisfied: G-015 achieved 2026-07-07, see
  goals/archive/G-015-script-subcommand-piped-stdin.md.
- The working-tree directory name (C:/repo/jn/shellspy) is out of scope -
  fossil does not require checkout dirs to match the project name.
- Other checkouts of shellspy.fossil (e.g. a shellspy_copy working tree, if
  open) must be enumerated and repointed by the same run.
- Test isolation pattern for anything touching fossil state: set FOSSIL_HOME
  to a temp dir and verify `fossil info` reports config-db under it before
  mutating (see fossilmove.test fixture guard).