From e8ef6397939a3ae26ed1228c542a24bbed9b30bc Mon Sep 17 00:00:00 2001 From: Julian Noble Date: Sat, 11 Jul 2026 02:47:52 +1000 Subject: [PATCH] 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 | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) 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