diff --git a/goals/G-016-projects-work-git-discovery.md b/goals/G-016-projects-work-git-discovery.md
index 4bab8b0e..d2238d65 100644
--- a/goals/G-016-projects-work-git-discovery.md
+++ b/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