G-016 detail: record the -return design decisions (completes 222886c0)

The prior commit message described these detail-file notes but the file edit had not landed (tool sequencing miss) - this commit adds them: dict-first assembly with table rendered from it, suggested per-checkout record shape, json via tcllib json::write as the G-017 parse target, markdown deliberately not offered as a machine form.

Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com

goals/G-016-projects-work-git-discovery.md

@@ -50,6 +50,24 @@ Result-shape considerations:
 - Relying on external tools' state (e.g. IDE/zoxide/gh caches) - rejected:
   non-portable, not present on all machines, opaque formats.
 
+## Machine-parsable returns (added to contract 2026-07-11)
+
+- `-return table|dict|json` (default table, existing display unchanged), following the
+  house convention (cmdhelp `-return dict`, parse_status - G-049): the dict is the
+  canonical machine form and the single source the other renderings derive from -
+  build it FIRST, render the table from it (avoids maintaining parallel assembly).
+- Suggested dict shape: list of per-checkout records - workdir, projectname,
+  projectcode, vcs (fossil|git|both - this goal's addition), repo db/enumeration
+  source path, multi-checkout dup info, optional -detail file-state - plus overall
+  keys (globs, counts). Document the structure in the PUNKARGS argdoc like
+  ::punk::args::parse_status does.
+- json = faithful rendering of the dict (tcllib json::write is available in kits via
+  tcllibc) - the parse target G-017's agent guidance standardizes on: self-delimiting
+  and language-neutral over a pipe.
+- Markdown deliberately NOT offered as a machine form (2026-07-11 decision): agents
+  parsing should use json; the human table remains for eyeballing - a markdown
+  rendering would be a third sync burden, lossier than json.
+
 ## Notes
 
 - Depends on nothing, but its value to agents is realised through G-015