.ralph-context.json

{
  "stories": [
    {
      "id": "story-mlsqzwdh",
      "title": "Refactor response envelope to match cli-design standard",
      "status": "completed",
      "filesModified": [
        "cmd/secrets/daemon_start_unix.go",
        "cmd/secrets/daemon_start_windows.go",
        "cmd/secrets/update.go",
        "cmd/secrets/add.go",
        "cmd/secrets/audit.go",
        "cmd/secrets/cleanup.go",
        "cmd/secrets/env.go",
        "cmd/secrets/exec.go",
        "cmd/secrets/health.go",
        "cmd/secrets/init.go",
        "cmd/secrets/lease.go",
        "cmd/secrets/revoke.go",
        "cmd/secrets/scan.go",
        "cmd/secrets/serve.go",
        "cmd/secrets/status.go",
        "internal/output/output.go",
        "internal/output/raw.go",
        "internal/output/table.go",
        "internal/types/exitcodes.go"
      ],
      "learnings": "Technical Discovery: `internal/update/update.go` depends on `output.UpdateInfo` as a type, even after removing `Response.Update`; keeping `UpdateInfo` as a standalone type in `internal/output/output.go` avoids breaking update-check flows while still conforming the envelope.\nGotcha: `output.Success` no longer carries a top-level message, so any user-facing status text must be placed inside `result` (for example as `result.message`) if the command needs it. Also, removing `Action.Name`/`Dangerous` requires updating every inline `output.Action{...}` literal.\nFiles Context: `internal/output/output.go` is the contract center (envelope types + helper constructors + action builders). `internal/output/raw.go` and `internal/output/table.go` must stay aligned with `Response` fields. Command wiring is concentrated under `cmd/secrets/*.go` where each `output.Success/Error/ErrorMsg` call now passes an explicit command string. `internal/types/exitcodes.go` now provides string code mapping via `ErrorCodeFromExitCode` for `error.code`."
    },
    {
      "id": "story-mlsr055z",
      "title": "Make lease default to raw value output",
      "status": "completed",
      "filesModified": [
        "bin/secrets",
        "cmd/secrets/add.go",
        "cmd/secrets/audit.go",
        "cmd/secrets/cleanup.go",
        "cmd/secrets/env.go",
        "cmd/secrets/exec.go",
        "cmd/secrets/health.go",
        "cmd/secrets/init.go",
        "cmd/secrets/lease.go",
        "cmd/secrets/revoke.go",
        "cmd/secrets/scan.go",
        "cmd/secrets/serve.go",
        "cmd/secrets/status.go",
        "cmd/secrets/update.go",
        "internal/output/output.go",
        "internal/output/output_test.go",
        "internal/output/raw.go",
        "internal/output/table.go",
        "internal/types/exitcodes.go",
        "prd.json",
        "progress.txt"
      ],
      "learnings": "Technical Discovery: `cmd/secrets/lease.go` can safely bypass formatter/output modes for the default path by directly printing `result.Value`; using `--json` keeps the standardized envelope via `output.Success(\"secrets lease\", ...)`. This preserves shell substitution UX while retaining structured responses on demand.\nGotcha: After this flip, any suggested command intended for machine chaining must explicitly include `--json`; otherwise `secrets lease` returns only raw secret text. `internal/output/output.go` action helpers are the key place this can silently regress.\nFiles Context: `cmd/secrets/lease.go` now owns the raw-vs-json branch and lease command docs/flags. `internal/output/output.go` contains reusable action builders (`ActionLease`, `ActionLeaseWithTTL`) used by other commands’ `next_actions`. `cmd/secrets/lease_test.go` provides command-level behavior coverage with a local Unix socket RPC stub. `internal/output/output_test.go` guards action helper command strings."
    },
    {
      "id": "story-mlsr0ekt",
      "title": "Remove TTY detection and legacy output format flags — JSON always",
      "status": "completed",
      "filesModified": [
        ".ralph-context.json",
        ".ralph-iterations.jsonl",
        "cmd/secrets/lease.go",
        "cmd/secrets/lease_test.go",
        "internal/output/output.go",
        "internal/output/output_test.go",
        "prd.json",
        "progress.txt",
        "cmd/secrets/health.go",
        "cmd/secrets/root.go",
        "cmd/secrets/scan.go",
        "internal/output/formatter.go",
        "internal/output/formatter_test.go",
        "internal/output/table.go",
        "internal/update/update.go"
      ],
      "learnings": "Technical Discovery: Removing `HumanMode`/`OutputFormat` from `internal/output/output.go` requires scanning outside `internal/output`; `internal/update/update.go` had a hidden dependency (`CheckForUpdateInBackground`) that breaks compilation and JSON-only behavior if left in place.\nGotcha: JSON output escapes `&` as `\\u0026` by default, so tests should decode JSON and assert fields instead of raw substring matching for fix messages or commands.\nFiles Context: `cmd/secrets/root.go` controls global CLI flags and pre-run behavior; `internal/output/formatter.go` is now a JSON-only shim; `internal/output/output.go` is the envelope/printing core; `internal/update/update.go` can inject background stderr noise if not kept JSON-safe; `cmd/secrets/root_test.go` and `internal/output/*_test.go` are the key guardrails for this story."
    },
    {
      "id": "story-mlsr0q1z",
      "title": "Self-documenting root command with command tree",
      "status": "completed",
      "filesModified": [
        ".ralph-context.json",
        ".ralph-iterations.jsonl",
        "cmd/secrets/health.go",
        "cmd/secrets/lease_test.go",
        "cmd/secrets/root.go",
        "cmd/secrets/root_test.go",
        "cmd/secrets/scan.go",
        "internal/output/formatter.go",
        "internal/output/formatter_test.go",
        "internal/output/output.go",
        "internal/output/output_test.go",
        "internal/output/table.go",
        "internal/update/update.go",
        "prd.json",
        "progress.txt"
      ],
      "learnings": "Technical Discovery: `cmd/secrets/root.go` can override Cobra’s default no-args help with `rootCmd.Run` and still keep detailed help available via `--help`; emitting through `output.Success` preserves the standard response envelope automatically.\nGotcha: `rootCmd.Execute()` in tests can trigger `PersistentPreRunE` update checks unless `noUpdateCheck` is forced true. Keep this isolated in root tests to avoid nondeterministic behavior.\nFiles Context: `cmd/secrets/root.go` now contains the command-tree contract (description/version/commands/next_actions). `cmd/secrets/root_test.go` validates this contract and includes reusable stdout capture + test-global setup helpers."
    },
    {
      "id": "story-mlsr0zv6",
      "title": "Add fix field to all error responses",
      "status": "completed",
      "filesModified": [
        ".ralph-context.json",
        ".ralph-iterations.jsonl",
        "cmd/secrets/root.go",
        "cmd/secrets/root_test.go",
        "prd.json",
        "progress.txt",
        "cmd/secrets/add.go",
        "cmd/secrets/lease.go",
        "cmd/secrets/lease_test.go",
        "cmd/secrets/status.go",
        "internal/output/output.go",
        "internal/output/output_test.go",
        "internal/types/errors.go"
      ],
      "learnings": "Technical Discovery: `internal/output/output.go` is the best enforcement point for story-wide fix consistency because most command failures are wrapped (`fmt.Errorf(...: %w, err)`) or stringified RPC errors. A message+`errors.Is` hybrid matcher in `inferFix(...)` catches both sentinel errors (e.g. `types.ErrStoreNotInitialized`) and daemon RPC strings (e.g. `RPC error ... secret not found`) without requiring per-command duplication.\nGotcha: JSON encoding escapes `&` to `\\u0026`, so tests that assert fix strings containing `secrets serve &` must either decode JSON or assert the escaped literal in raw output. Also, some commands still return non-nil after printing JSON errors; that can produce stderr duplicates under Cobra unless error handling is globally silenced.\nFiles Context: `internal/output/output.go` now owns fix inference and explicit helpers (`ErrorWithFix`, `ErrorMsgWithFix`). `cmd/secrets/lease.go` has command-specific handling for daemon/secret-not-found fixes. `cmd/secrets/add.go` covers the empty-value path with required remediation text. `internal/types/errors.go` now maps `UserError.Suggestion` to JSON `fix`. Regression coverage is in `internal/output/output_test.go` and `cmd/secrets/lease_test.go`."
    },
    {
      "id": "story-mlsr197b",
      "title": "Add list command to show all stored secret names",
      "status": "completed",
      "filesModified": [
        ".ralph-context.json",
        ".ralph-iterations.jsonl",
        "cmd/secrets/add.go",
        "cmd/secrets/lease.go",
        "cmd/secrets/lease_test.go",
        "cmd/secrets/status.go",
        "internal/output/output.go",
        "internal/output/output_test.go",
        "internal/types/errors.go",
        "prd.json",
        "progress.txt",
        "cmd/secrets/root.go",
        "cmd/secrets/root_test.go",
        "internal/daemon/handlers.go",
        "internal/daemon/handlers_test.go",
        "internal/daemon/protocol.go"
      ],
      "learnings": "Technical Discovery: `handleList()` in `internal/daemon/handlers.go` must sort by `SecretMetadata.Name` because `store.List()` is map-backed and nondeterministic; otherwise list ordering and downstream `next_actions` ordering can drift between runs.\nGotcha: Even with daemon-side sorting, `cmd/secrets/list.go` intentionally keeps client-side sorting so older daemons still produce deterministic CLI output; removing it can regress compatibility in mixed-version environments.\nFiles Context: `cmd/secrets/list.go` handles RPC decode and HATEOAS `next_actions`; `internal/daemon/handlers.go` computes `ActiveLeases` and sorted metadata; `internal/daemon/handlers_test.go` contains the new TDD regression test for sorted ordering."
    },
    {
      "id": "story-mlsr1icp",
      "title": "Update README, SKILL.md, and AGENTS.md for new CLI design",
      "status": "completed",
      "filesModified": [
        ".ralph-context.json",
        ".ralph-iterations.jsonl",
        "cmd/secrets/list.go",
        "cmd/secrets/list_test.go",
        "cmd/secrets/root.go",
        "cmd/secrets/root_test.go",
        "internal/daemon/handlers.go",
        "internal/daemon/handlers_test.go",
        "internal/daemon/protocol.go",
        "prd.json",
        "progress.txt",
        "AGENTS.md",
        "README.md",
        "skills/secret-management/SKILL.md"
      ],
      "learnings": "Technical Discovery: `cmd/secrets/lease.go` is intentionally dual-mode: raw secret output by default for shell substitution, with HATEOAS envelope only on `--json`. Documentation must show both paths clearly or agent workflows break.\nGotcha: Do not document semantic error codes like `not_found` for lease failures; output code currently maps from process exit codes in `internal/types/exitcodes.go` (often `generic_error`) while actionable remediation is carried by the `fix` field.\nFiles Context: `README.md` is the public CLI contract (quick start + command reference), `skills/secret-management/SKILL.md` is the agent runtime playbook, and `AGENTS.md` is contributor/operator guidance. These three must stay aligned with `cmd/secrets/root.go`, `cmd/secrets/list.go`, and `cmd/secrets/lease.go` behavior."
    },
    {
      "id": "story-mlsuuq2i",
      "title": "Add update and delete commands for secrets",
      "status": "completed",
      "filesModified": [
        ".ralph-context.json",
        ".ralph-iterations.jsonl",
        "cmd/secrets/exec.go",
        "cmd/secrets/status.go",
        "internal/daemon/handlers_test.go",
        "cmd/secrets/root.go",
        "cmd/secrets/root_test.go",
        "cmd/secrets/update.go",
        "internal/daemon/handlers.go",
        "internal/daemon/protocol.go",
        "internal/output/output.go",
        "internal/update/update.go",
        "prd.json"
      ],
      "learnings": "Technical Discovery: `internal/daemon/handlers.go` must enforce update-only behavior by checking existence before mutation; in this codebase `store.Add` rejects duplicates and does not overwrite, so `handleUpdate` should use `store.Get` then `store.Update` with optional `RotateVia` handling.\nGotcha: `secrets update` is now secret mutation, not binary updater. Any place that surfaces updater commands must use `secrets self-update` (`cmd/secrets/update.go`, `cmd/secrets/root.go`, `internal/output/output.go`, `internal/update/update.go`) or users will get wrong guidance.\nFiles Context: Command wiring and command-tree docs live in `cmd/secrets/root.go`. Secret mutation CLI logic is in `cmd/secrets/update_secret.go` and `cmd/secrets/delete.go`. RPC API surface is in `internal/daemon/protocol.go` and execution logic in `internal/daemon/handlers.go`. Behavioral coverage was added in `internal/daemon/handlers_test.go`, `cmd/secrets/update_secret_test.go`, `cmd/secrets/delete_test.go`, and `cmd/secrets/root_test.go`."
    },
    {
      "id": "story-mlsvicrr",
      "title": "Backwards compatibility: restore deprecated flags with warnings",
      "status": "completed",
      "filesModified": [
        "cmd/secrets/delete.go",
        "cmd/secrets/delete_test.go",
        "cmd/secrets/root.go",
        "cmd/secrets/root_test.go",
        "cmd/secrets/update.go",
        "cmd/secrets/update_secret.go",
        "cmd/secrets/update_secret_test.go",
        "internal/daemon/handlers.go",
        "internal/daemon/handlers_test.go",
        "internal/daemon/protocol.go",
        "internal/output/output.go",
        "internal/update/update.go",
        "prd.json",
        "progress.txt",
        ".ralph-context.json",
        ".ralph-iterations.jsonl",
        "README.md",
        "cmd/secrets/lease.go",
        "cmd/secrets/lease_test.go",
        "internal/output/output_test.go"
      ],
      "learnings": "Technical Discovery: In this Cobra setup, deprecated no-op flags are best handled as hidden flags plus explicit warning emission in pre-run/run paths. Using `cmd.Flags().Changed(\"...\")` correctly detects explicit user use, but tests must restore `pflag.Flag.Changed` state when commands are reused across tests.\nGotcha: If a command checks `Flags().Changed(...)`, test helpers must reset both the flag value and the `Changed` bit; otherwise later tests can get stale warning behavior from shared global command instances.\nFiles Context: `cmd/secrets/lease.go` handles lease raw/json behavior and now owns `--raw` compatibility warning. `cmd/secrets/root.go` owns global backward-compatible output flags and warning emission in `PersistentPreRunE`. `internal/output/output.go` is the envelope contract layer (`ok`/`success`) and central stderr deprecation helper. README migration guidance is in `README.md` under the new v0.4.x -> v0.5.x section."
    },
    {
      "id": "story-mlt0pwra",
      "title": "Remove MCP references, credit Alex Hillman, clean up README",
      "status": "completed",
      "filesModified": [
        ".ralph-context.json",
        ".ralph-iterations.jsonl",
        "README.md",
        "cmd/secrets/lease.go",
        "cmd/secrets/lease_test.go",
        "cmd/secrets/root.go",
        "cmd/secrets/root_test.go",
        "internal/output/output.go",
        "internal/output/output_test.go",
        "prd.json",
        "progress.txt",
        "skills/secret-management/SKILL.md"
      ],
      "learnings": "Technical Discovery: For docs-only stories in this repo, pipeline verification can still reject the iteration if required target files are not in the diff; explicitly checking `git status --short README.md skills/secret-management/SKILL.md` before validation prevents another `verification_rejected` cycle.\nGotcha: When using shell commands that include backticks in quoted memory text, zsh will attempt command substitution; use single-quoted strings for `swarm memory store` payloads to avoid accidental command execution/noise.\nFiles Context: `README.md` contains product narrative sections (`Why?`, integration notes, bottom-of-file context blocks) and was the right place for both MCP removal and the new Inspiration credit. `skills/secret-management/SKILL.md` mirrors agent-facing workflow guidance and had a separate MCP section that also needed removal to keep docs consistent."
    },
    {
      "id": "story-mlt170vk",
      "title": "Test coverage: internal/output envelope and formatters",
      "status": "completed",
      "filesModified": [
        "README.md",
        ".ralph-context.json",
        ".ralph-iterations.jsonl",
        "internal/output/json.go",
        "internal/output/output_test.go",
        "prd.json"
      ],
      "learnings": "Technical Discovery: `JSONFormatter.Format` in `internal/output/json.go` was encoding `Response` without normalizing aliases, so direct formatter usage could emit `ok=true` with `success=false`. Setting `r.Success = r.OK` in the formatter aligns it with `printJSON` and preserves backward compatibility.\nGotcha: `ActionsAfterScan(2)` currently returns `ActionImportSecret(\"\", \"\")`, which produces command `secrets add ` (trailing space). Tests now lock this current behavior in `internal/output/output_test.go`; changing it will require updating expectations.\nFiles Context: `internal/output/output_test.go` now covers envelope shape, fix propagation, next_actions serialization, action builders, contextual action sets, deprecation stderr behavior, and print fallback path. `internal/output/json_test.go` covers envelope serialization, omitempty behavior, and fix inclusion. `internal/output/raw_test.go` covers raw outputs for strings/maps/slices/default types/nil and error+fix rendering. `internal/output/json.go` now mirrors `success` from `ok` before encoding."
    },
    {
      "id": "story-mlt171hg",
      "title": "Test coverage: daemon handlers (list, update, delete)",
      "status": "completed",
      "filesModified": [
        ".ralph-context.json",
        ".ralph-iterations.jsonl",
        "internal/output/json.go",
        "internal/output/json_test.go",
        "internal/output/output_test.go",
        "internal/output/raw_test.go",
        "prd.json",
        "progress.txt",
        "internal/daemon/handlers_test.go"
      ],
      "learnings": "Technical Discovery: `internal/daemon/handlers_test.go` can validate CLI remediation behavior indirectly by wrapping handler errors with `output.Error(...)`, while still keeping daemon logic tests isolated. This gives coverage for fix-field expectations (including daemon startup guidance) without changing daemon protocol types.\nGotcha: `handleList()` itself does not return `next_actions`; contextual lease actions are derived from listed secret names at higher layers. Avoid writing brittle tests that expect daemon list results to include command actions unless protocol structs are intentionally extended.\nFiles Context: `internal/daemon/handlers_test.go` now contains the added list/update/delete/error coverage. Existing command-layer next_action/fix behavior remains primarily tested in `cmd/secrets/list_test.go`, `cmd/secrets/delete_test.go`, and `cmd/secrets/update_secret_test.go`."
    },
    {
      "id": "story-mlt172li",
      "title": "Test coverage: internal/update and internal/types",
      "status": "completed",
      "filesModified": [
        ".ralph-context.json",
        ".ralph-iterations.jsonl",
        "cmd/secrets/root_test.go",
        "prd.json",
        "progress.txt",
        "internal/types/exitcodes.go",
        "internal/update/update_test.go"
      ],
      "learnings": "Technical Discovery: `ExitCodeFromError` helper predicates in `internal/types/exitcodes.go` must use `errors.Is` instead of direct equality; otherwise wrapped sentinel errors incorrectly fall through to `ExitGenericError` despite carrying typed context.\nGotcha: When running `swarm memory store` in zsh, avoid backticks in the payload text because they trigger command substitution and noisy shell errors; use single-quoted plain text.\nFiles Context: `internal/update/update_test.go` now includes a success-path `getLatestRelease` test (header + parse). `internal/types/types_test.go` covers wrapped-error exit-code mapping. `internal/types/exitcodes.go` contains the unwrap-aware logic that keeps CLI exit codes stable for wrapped sentinel errors."
    }
  ],
  "failures": [
    {
      "storyId": "story-mlsr197b",
      "storyTitle": "Add list command to show all stored secret names",
      "category": "verification_rejected",
      "error": "[verification_rejected] Required target files not modified: cmd/secrets/list.go. Changed files: .ralph-context.json, .ralph-iterations.jsonl, cmd/secrets/root.go, cmd/secrets/root_test.go, internal/daemon/handlers.go, internal/daemon/handlers_test.go, internal/daemon/protocol.go",
      "toolNames": [
        "/usr/bin/zsh -lc",
        "sed -n",
        "rg \\",
        "swarm memory",
        "nl -ba"
      ],
      "iterationNumber": 6
    },
    {
      "storyId": "story-mlsr197b",
      "storyTitle": "Add list command to show all stored secret names",
      "category": "verification_rejected",
      "error": "[verification_rejected] Required target files not modified: cmd/secrets/list.go. Changed files: .ralph-context.json, .ralph-iterations.jsonl, cmd/secrets/root.go, cmd/secrets/root_test.go, internal/daemon/handlers.go, internal/daemon/handlers_test.go, internal/daemon/protocol.go, prd.json, progress.txt",
      "toolNames": [
        "/usr/bin/zsh -lc",
        "sed -n",
        "rg -n",
        "swarm memory",
        "nl -ba"
      ],
      "iterationNumber": 7
    },
    {
      "storyId": "story-mlt172li",
      "storyTitle": "Test coverage: internal/update and internal/types",
      "category": "verification_rejected",
      "error": "[verification_rejected] Required target files not modified: internal/types. Changed files: internal/update/update_test.go",
      "toolNames": [
        "/usr/bin/zsh -lc",
        "sed -n",
        "nl -ba",
        "swarm memory"
      ],
      "iterationNumber": 4
    },
    {
      "storyId": "story-mlt172li",
      "storyTitle": "Test coverage: internal/update and internal/types",
      "category": "verification_rejected",
      "error": "[verification_rejected] Required target files not modified: internal/types. Changed files: .ralph-context.json, .ralph-iterations.jsonl, internal/update/update_test.go, prd.json, progress.txt",
      "toolNames": [
        "/usr/bin/zsh -lc",
        "sed -n",
        "swarm memory",
        "nl -ba"
      ],
      "iterationNumber": 5
    }
  ]
}