diff --git a/CHANGELOG.md b/CHANGELOG.md index d26734c..cc96ff1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,10 @@ Please choose versions by [Semantic Versioning](http://semver.org/). * MINOR version when you add functionality in a backwards-compatible manner, and * PATCH version when you make backwards-compatible bug fixes. +## Unreleased + +- feat: `task approve` writes `reapproved_at` on its re-approval branch, so a re-approval is observable and timestamped where the preserved `approved_at` made it indistinguishable from a row that was never re-approved + ## v0.197.1 - fix: scope ORPHAN_GOAL detection to the goals: block so later frontmatter lists are not reported as missing goals diff --git a/integration/cli_test.go b/integration/cli_test.go index 13beddc..5c69dc3 100644 --- a/integration/cli_test.go +++ b/integration/cli_test.go @@ -4385,6 +4385,47 @@ body line } }) + It("AC1/AC2/AC4: a re-approval writes a timestamp-typed reapproved_at, preserves approved_at, and the field reader returns it", func() { + vaultPath, configPath, cleanup = createTempVault(map[string]string{ + "Alpha": approvedBothFrontmatter, + }) + taskFile := filepath.Join(vaultPath, "Tasks", "Alpha.md") + + session := runEntityCommand("task", "approve", "Alpha") + Eventually(session).Should(gexec.Exit(0)) + + after := readFile(taskFile) + reapprovedAt := strings.Trim(valueOf(after, "reapproved_at"), `"`) + Expect(reapprovedAt).NotTo(BeEmpty(), "reapproved_at must be written on re-approval") + _, parseErr := time.Parse(time.RFC3339, reapprovedAt) + Expect(parseErr).NotTo(HaveOccurred(), "reapproved_at %q is not RFC3339", reapprovedAt) + // AC4: the preserved approval record did not move. + Expect(valueOf(after, "approved_at")).To(Equal("2026-01-01T00:00:00Z")) + Expect(valueOf(after, "approved_by")).To(Equal("someone")) + Expect(valueOf(after, "phase")).To(Equal("planning")) + + // AC2: the existing generic field reader returns the value back. Only a + // non-empty value is asserted — the reader renders a timestamp-typed value + // with Go's %v form, not necessarily RFC3339. + getSession := runEntityCommand("task", "get", "Alpha", "reapproved_at") + Eventually(getSession).Should(gexec.Exit(0)) + Expect(strings.TrimSpace(string(getSession.Out.Contents()))).NotTo(BeEmpty()) + }) + + It("AC3: a first approval writes no reapproved_at", func() { + vaultPath, configPath, cleanup = createTempVaultWithCurrentUser(map[string]string{ + "Alpha": todoFrontmatter, + }) + taskFile := filepath.Join(vaultPath, "Tasks", "Alpha.md") + + session := runEntityCommand("task", "approve", "Alpha") + Eventually(session).Should(gexec.Exit(0)) + + after := readFile(taskFile) + Expect(after).NotTo(ContainSubstring("reapproved_at")) + Expect(valueOf(after, "approved_at")).NotTo(BeEmpty()) + }) + It("AC6b: a terminal row at phase todo is refused, including the `done` alias", func() { // Both the canonical terminal status and its legacy alias must refuse // end-to-end: `done` normalizes to `completed`, so a raw comparison diff --git a/pkg/cli/cli.go b/pkg/cli/cli.go index 45ca497..57fc89f 100644 --- a/pkg/cli/cli.go +++ b/pkg/cli/cli.go @@ -2758,6 +2758,18 @@ func createTaskSetCommand( return cmd } +// taskApprovePreservationHelp is the re-approval paragraph of `task approve`'s +// long help. It is kept out of the constructor so the function stays within the +// length limit. +const taskApprovePreservationHelp = "An existing approved_at is preserved on re-approval: " + + "a row that already carries approved_by or approved_at is already approved, so the " + + "command does not re-approve it. It completes the transition by moving the phase to " + + "planning and leaves the record exactly as it is — it never overwrites either key, " + + "never fabricates a missing one, and never refreshes approved_at. The act of " + + "re-approval is recorded in its own key: reapproved_at is written only on a " + + "re-approval and refreshed by each one, so a reader can tell a row re-approved a " + + "minute ago from one that was never re-approved." + // createTaskApproveCommand builds `vault-cli task approve`, the CLI surface over // the pkg/ops approval operation. It performs the recorded todo -> planning // transition and, unlike the other mutation verbs, exits non-zero when a @@ -2778,11 +2790,7 @@ func createTaskApproveCommand( Short: "Approve a task in the operator's inbox (todo -> planning)", Long: "Approve a task in the operator's inbox: it moves a todo task to planning and " + "records approved_by and approved_at in one write.\n\n" + - "An existing approved_at is preserved on re-approval: a row that already carries " + - "approved_by or approved_at is already approved, so the command does not " + - "re-approve it. It completes the transition by moving the phase to planning and " + - "leaves the record exactly as it is — it never overwrites either key, never " + - "fabricates a missing one, and never refreshes approved_at.\n\n" + + taskApprovePreservationHelp + "\n\n" + "Approval is unbounded: it never refuses on a count of approved rows. What opens " + "a task is governed by flag provenance, not by a count — /supervisor:open --flagged " + "opens only rows whose flag_set_by is operator or legacy, and an agent cannot cause " + diff --git a/pkg/ops/task_approve.go b/pkg/ops/task_approve.go index 3743005..217e4dd 100644 --- a/pkg/ops/task_approve.go +++ b/pkg/ops/task_approve.go @@ -133,7 +133,9 @@ func (o *taskApproveOperation) Execute( // approved; only the phase half of the transition is missing. Advance it and // preserve the record exactly as it is: no approval is written, no missing // key is invented, and no owner is resolved or required, because the owner - // rule governs the approval act, which already happened. + // rule governs the approval act, which already happened. The act of + // re-approval is still recorded — its instant goes into reapproved_at — + // while the approval record itself is left untouched. if hasApprovalRecord(task) { // A terminal row is refused rather than advanced: moving it to planning // would produce the status/phase pair checkPhaseRegression refuses and @@ -149,6 +151,11 @@ func (o *taskApproveOperation) Execute( return MutationResult{Success: false, Error: terminalErr.Error()}, terminalErr } task.SetPhase(domain.TaskPhasePlanning.Ptr()) + // The re-approval is an event with a time of its own: record it in a + // separate key, beside the preserved approval record, in the same single + // write. A first approval never writes this key, so a row that carries it + // was re-approved and the value is when. + task.Set("reapproved_at", now.Time()) return o.write(ctx, task, vaultName) } diff --git a/pkg/ops/task_approve_test.go b/pkg/ops/task_approve_test.go index 21f7520..1f3a340 100644 --- a/pkg/ops/task_approve_test.go +++ b/pkg/ops/task_approve_test.go @@ -284,6 +284,148 @@ var _ = Describe("TaskApproveOperation", func() { }), ) + It("records reapproved_at as a bare time.Time on the re-approval branch", func() { + seedTask(map[string]any{ + "status": "next", "phase": "todo", + "approved_by": "someone", "approved_at": "2026-01-01T00:00:00Z", + }) + + _, execErr := approveOp.Execute(ctx, "/vault", "Alpha", "vault-a", "operator", "", "") + Expect(execErr).To(BeNil()) + + Expect(mockStorage.WriteTaskCallCount()).To(Equal(1)) + _, written := mockStorage.WriteTaskArgsForCall(0) + Expect(written.Phase()).To(Equal(domain.TaskPhasePlanning.Ptr())) + raw, ok := written.Get("reapproved_at").(time.Time) + Expect(ok).To(BeTrue()) + Expect(raw.Equal(pinned.Now().Time())).To(BeTrue()) + // The approval record itself is preserved byte-for-byte. + Expect(written.Get("approved_by")).To(Equal("someone")) + Expect(written.Get("approved_at")).To(Equal("2026-01-01T00:00:00Z")) + }) + + It("serializes reapproved_at unquoted and round-trips it as a time.Time", func() { + seedTask(map[string]any{ + "status": "next", "phase": "todo", + "approved_by": "someone", "approved_at": "2026-01-01T00:00:00Z", + }) + + _, execErr := approveOp.Execute(ctx, "/vault", "Alpha", "vault-a", "operator", "", "") + Expect(execErr).To(BeNil()) + + _, written := mockStorage.WriteTaskArgsForCall(0) + out, marshalErr := yaml.Marshal(written.RawMap()) + Expect(marshalErr).NotTo(HaveOccurred()) + Expect(string(out)).To(ContainSubstring("reapproved_at: 2026-03-03T12:00:00Z")) + Expect(string(out)).NotTo(ContainSubstring(`reapproved_at: "2026-03-03T12:00:00Z"`)) + + var roundTripped map[string]any + Expect(yaml.Unmarshal(out, &roundTripped)).To(Succeed()) + rt, ok := roundTripped["reapproved_at"].(time.Time) + Expect(ok).To(BeTrue()) + Expect(rt.Equal(pinned.Now().Time())).To(BeTrue()) + }) + + It("writes no reapproved_at on a first approval", func() { + seedTask(map[string]any{"status": "next", "phase": "todo", "assignee": "someone"}) + + _, execErr := approveOp.Execute(ctx, "/vault", "Alpha", "vault-a", "operator", "", "") + Expect(execErr).To(BeNil()) + + _, written := mockStorage.WriteTaskArgsForCall(0) + Expect(written.Get("reapproved_at")).To(BeNil()) + Expect(written.Get("approved_at")).NotTo(BeNil()) + }) + + DescribeTable("writes reapproved_at for any presence-only approval record", + func(fields map[string]any) { + seedTask(fields) + // Snapshot before Execute: domain.NewTask stores the caller's map by + // reference, so reading fields[...] afterwards would compare the + // written map against itself. + seededBy := fields["approved_by"] + seededAt := fields["approved_at"] + + _, execErr := approveOp.Execute(ctx, "/vault", "Alpha", "vault-a", "operator", "", "") + Expect(execErr).To(BeNil()) + + Expect(mockStorage.WriteTaskCallCount()).To(Equal(1)) + _, written := mockStorage.WriteTaskArgsForCall(0) + raw, ok := written.Get("reapproved_at").(time.Time) + Expect(ok).To(BeTrue()) + Expect(raw.Equal(pinned.Now().Time())).To(BeTrue()) + expectSameValue := func(actual, expected any) { + if expected == nil { + Expect(actual).To(BeNil()) + return + } + Expect(actual).To(Equal(expected)) + } + expectSameValue(written.Get("approved_by"), seededBy) + expectSameValue(written.Get("approved_at"), seededAt) + }, + Entry("only approved_by", map[string]any{ + "status": "next", "phase": "todo", "approved_by": "someone", + }), + Entry("only approved_at", map[string]any{ + "status": "next", "phase": "todo", "approved_at": "2026-01-01T00:00:00Z", + }), + Entry("an empty approved_by value counts as present", map[string]any{ + "status": "next", "phase": "todo", "approved_by": "", + }), + Entry("a present-but-null approved_by", map[string]any{ + "status": "next", "phase": "todo", "approved_by": nil, + }), + Entry("an unparseable approved_at", map[string]any{ + "status": "next", "phase": "todo", "approved_at": "not-a-date", + }), + ) + + It("refreshes reapproved_at on a second re-approval", func() { + seedTask(map[string]any{ + "status": "next", "phase": "todo", + "approved_by": "someone", "approved_at": "2026-01-01T00:00:00Z", + }) + + _, execErr := approveOp.Execute(ctx, "/vault", "Alpha", "vault-a", "operator", "", "") + Expect(execErr).To(BeNil()) + _, firstWritten := mockStorage.WriteTaskArgsForCall(0) + firstRaw, ok := firstWritten.Get("reapproved_at").(time.Time) + Expect(ok).To(BeTrue()) + Expect(firstRaw.Equal(pinned.Now().Time())).To(BeTrue()) + + // A fresh map literal, not the first one: domain.NewTask stores the map by + // reference, so a reused map would already read phase: planning and the + // second call would be refused by the inbox guard. + seedTask(map[string]any{ + "status": "next", "phase": "todo", + "approved_by": "someone", "approved_at": "2026-01-01T00:00:00Z", + }) + pinned.SetNow(libtimetest.ParseDateTime("2026-03-03T12:00:05Z")) + + _, execErr = approveOp.Execute(ctx, "/vault", "Alpha", "vault-a", "operator", "", "") + Expect(execErr).To(BeNil()) + + Expect(mockStorage.WriteTaskCallCount()).To(Equal(2)) + _, secondWritten := mockStorage.WriteTaskArgsForCall(1) + secondRaw, ok := secondWritten.Get("reapproved_at").(time.Time) + Expect(ok).To(BeTrue()) + Expect(secondRaw.Equal(pinned.Now().Time())).To(BeTrue()) + Expect(secondRaw.Equal(firstRaw)).To(BeFalse()) + }) + + It("refuses a zero clock on the re-approval branch with zero writes", func() { + seedTask(map[string]any{"status": "next", "phase": "todo", "approved_by": "someone"}) + zero := libtime.NewCurrentDateTime() + zero.SetNow(libtime.DateTime(time.Time{})) + zeroOp := ops.NewTaskApproveOperation(mockStorage, zero) + + _, execErr := zeroOp.Execute(ctx, "/vault", "Alpha", "vault-a", "operator", "", "") + Expect(execErr).To(HaveOccurred()) + Expect(execErr.Error()).To(ContainSubstring("approved_at")) + Expect(mockStorage.WriteTaskCallCount()).To(Equal(0)) + }) + It("still refuses an approved row that is past the inbox", func() { seedTask(map[string]any{ "status": "in_progress", "phase": "execution", diff --git a/prompts/completed/284-spec-069-task-approve-records-reapproved-at.md b/prompts/completed/284-spec-069-task-approve-records-reapproved-at.md new file mode 100644 index 0000000..86be7d8 --- /dev/null +++ b/prompts/completed/284-spec-069-task-approve-records-reapproved-at.md @@ -0,0 +1,238 @@ +--- +status: completed +spec: [069-task-approve-records-reapproved-at] +summary: '`task approve` now records `reapproved_at` on its re-approval branch, pinned by unit, integration, and end-to-end probe coverage' +execution_id: vault-cli-reapproved-at-exec-284-spec-069-task-approve-records-reapproved-at +dark-factory-version: v0.198.17 +created: "2026-11-18T09:00:00Z" +queued: "2026-11-18T19:23:12Z" +started: "2026-11-18T19:26:05Z" +completed: "2026-11-18T19:33:38Z" +--- + +# `task approve` records `reapproved_at` on its re-approval branch (spec 069) + + +- A re-approval becomes an observable event with a timestamp, not just a phase change. +- Any consumer reading a task row can answer "was this row re-approved, and when?" from the frontmatter alone. +- The first approval is unchanged: it still records the approver and the instant, and never writes the new key. +- The existing approval record is still preserved byte-for-byte on re-approval, so a first approval and a re-approval stay distinguishable. +- Each further re-approval refreshes the new timestamp, because it records the latest event rather than the first one. +- The re-approval branch stays presence-based, so a row carrying only part of the approval record still gets the new timestamp. +- A finished row is still refused and still writes nothing, including the new key. +- The command's built-in help names the new key and says it is written only on a re-approval, so a reader can discover it without a spec. +- Reading the value back works through the existing field reader — no new verb, no new flag, no new output path. +- One write per invocation, as today; the new key travels in that same write. + + + +Make a re-approval observable and timestamped: when `vault-cli task approve` advances a row that already carries an approval record, it must record the instant of that re-approval in a new frontmatter key, `reapproved_at`, in the same single write that moves the phase to planning. Today the re-approval branch moves the phase and writes nothing else, so the event is invisible — a consumer that must react to "the operator cleared this wait just now" cannot distinguish a re-approval a minute ago from one three weeks ago, nor either of them from a row that was never re-approved. This is spec 069, one prompt covering Desired Behaviors 1–6 and Acceptance Criteria 1–8. + + + +Read `CLAUDE.md` first for project conventions, then `docs/dod.md` for the definition of done this change is graded against. + +Read these files fully before changing anything: + +- `pkg/ops/task_approve.go` — `(*taskApproveOperation).Execute`. The change lands in the `if hasApprovalRecord(task)` branch: after the terminal-status refusal and before `return o.write(ctx, task, vaultName)`. `now := o.currentDateTime.Now()` is captured before every guard (the zero-clock guard); `now.Time()` is the `time.Time` the first-approval path already writes as `approved_at`. `hasApprovalRecord` stays presence-based on `task.Keys()` — do not touch it. +- `pkg/ops/task_approve_test.go` — the Ginkgo/Gomega suite this change extends. Read the existing `It("records the injected instant as a bare time.Time")` and `It("serializes approved_at unquoted and round-trips it as a time.Time")` (the two shape tests the new key mirrors), the `DescribeTable("advances a todo task that already carries an approval record")` block (the preservation pin that must stay byte-identical), `It("refuses a zero clock with zero writes")`, and `DescribeTable("refuses a terminal row that is still at phase todo, with zero writes")`. Note how `seedTask` replaces the task the mock returns and how `pinned.SetNow` moves the injected clock. +- `pkg/cli/cli.go` — `createTaskApproveCommand`, its `Long` field. Only the second paragraph changes; the unbounded-approval paragraph and the operator-flag paragraph are untouched. +- `pkg/cli/task_approve_help_test.go` — the existing help-text pin from spec 067. It requires a clause containing `preserv` that names `approved_at` to appear at or after the phrase `records approved_by and approved_at in one write`. The new sentence must not break it. +- `integration/cli_test.go` — `Describe("task approve", ...)`. Read the helpers `runEntityCommand`, `readFile`, `valueOf`, `frontmatterOf`, `sha256OfFile`, and the fixtures `todoFrontmatter`, `approvedByOnlyFrontmatter`, `approvedAtOnlyFrontmatter`, `approvedBothFrontmatter`. Read `It("AC6: a task carrying any approval record is advanced, per fixture")` — the re-approval case this prompt extends — and `It("AC1: task approve writes phase/approved_by/approved_at in one write")`, whose `Expect(approvedKeys(after)).To(HaveLen(4))` must stay 4 because a first approval writes no new key. +- `CHANGELOG.md` lines 1–16 only — a `## Unreleased` section already exists and already carries the bullet for this change (`task approve` writes `reapproved_at` on its re-approval branch). Do not add a second one. +- `docs/task-writing.md` — read the approval-record paragraph in § Phase transitions and change nothing in it. It stays true: `approved_by` and `approved_at` are neither overwritten nor fabricated. + +Coding-plugin docs (in-container paths): +- `/home/node/.claude/plugins/marketplaces/coding/docs/go-testing-guide.md` — Ginkgo v2 / Gomega suite shape, external test packages, Counterfeiter mocks. +- `/home/node/.claude/plugins/marketplaces/coding/docs/changelog-guide.md` — the `## Unreleased` placement rule and the no-hand-bump rule for an auto-release repository. + + + +The defect: the `hasApprovalRecord` branch in `Execute` advances a row's phase and preserves the approval record exactly — which is correct — but records nothing about the act itself, so a re-approval is only visible as a phase string and carries no time. Add one key, written only on that branch, in the branch's existing single write. + +1. **Write `reapproved_at` on the re-approval branch** in `pkg/ops/task_approve.go`, inside `(*taskApproveOperation).Execute`, in the `if hasApprovalRecord(task)` branch, after the terminal-status refusal and after `task.SetPhase(domain.TaskPhasePlanning.Ptr())`. Reuse the `now` captured before the guards — do not read the clock a second time and do not move or weaken the zero-clock guard. + + Replace this block (the two-line `SetPhase` + `write` adjacency occurs only in this branch): + + ```go + task.SetPhase(domain.TaskPhasePlanning.Ptr()) + return o.write(ctx, task, vaultName) + } + ``` + + with: + + ```go + task.SetPhase(domain.TaskPhasePlanning.Ptr()) + // The re-approval is an event with a time of its own: record it in a + // separate key, beside the preserved approval record, in the same single + // write. A first approval never writes this key, so a row that carries it + // was re-approved and the value is when. + task.Set("reapproved_at", now.Time()) + return o.write(ctx, task, vaultName) + } + ``` + + Then extend the branch's existing explanatory comment (the paragraph beginning "A todo row that already carries an approval record has already been approved") with one sentence saying the branch records the re-approval's instant in `reapproved_at` while leaving the approval record itself untouched. The comment currently says "no approval is written"; it must not be left reading as if nothing at all is written, or a later reader will delete the new line as a contradiction. Leave the `TaskApproveOperation` interface doc comment and `hasApprovalRecord`'s doc comment unchanged — both speak about the approval record, which is still neither rewritten nor fabricated. + +2. **Pin the new key with unit tests** in `pkg/ops/task_approve_test.go`, added after the existing `DescribeTable("advances a todo task that already carries an approval record", ...)` block. Do not modify that table, or any other existing test, in this file. Add these specs, reusing the file's `seedTask` and `pinned` helpers: + + - `It("records reapproved_at as a bare time.Time on the re-approval branch")` — seed `{"status": "next", "phase": "todo", "approved_by": "someone", "approved_at": "2026-01-01T00:00:00Z"}`, execute with `approvedBy "operator"`, then assert on `WriteTaskArgsForCall(0)`: `WriteTaskCallCount()` is 1, `written.Phase()` equals `domain.TaskPhasePlanning.Ptr()`, `written.Get("reapproved_at").(time.Time)` succeeds (`Expect(ok).To(BeTrue())`) and `raw.Equal(pinned.Now().Time())` is true, and `written.Get("approved_by")` / `written.Get("approved_at")` still equal the seeded values. The type assertion is the assertion — a string value must fail this test. + - `It("serializes reapproved_at unquoted and round-trips it as a time.Time")` — mirror `It("serializes approved_at unquoted and round-trips it as a time.Time")`: `yaml.Marshal(written.RawMap())` must contain `reapproved_at: 2026-03-03T12:00:00Z`, must not contain the quoted form, and unmarshalling the output into `map[string]any` must yield a `time.Time` under `reapproved_at` equal to the pinned instant. This is the serialization boundary — the file on disk is what a consumer reads. + - `It("writes no reapproved_at on a first approval")` — seed `{"status": "next", "phase": "todo", "assignee": "someone"}`, execute, assert `written.Get("reapproved_at")` is `BeNil()` while `written.Get("approved_at")` is not nil. + - `DescribeTable("writes reapproved_at for any presence-only approval record", ...)` — one `Entry` per shape, each asserting `written.Get("reapproved_at").(time.Time)` succeeds and the seeded `approved_by` / `approved_at` values are unchanged — snapshot `seededBy := fields["approved_by"]` and `seededAt := fields["approved_at"]` **before** `Execute` (as the existing table's comment at lines 239-242 requires, because `domain.NewTask` stores the caller's map by reference, so reading `fields[...]` after the call compares the written map against itself) and compare with the same nil-aware `expectSameValue` helper shape the existing table uses for absent keys: `Entry("only approved_by", ...)`, `Entry("only approved_at", ...)`, `Entry("an empty approved_by value counts as present", map[string]any{"approved_by": ""})`, `Entry("a present-but-null approved_by", map[string]any{"approved_by": nil})`, `Entry("an unparseable approved_at", map[string]any{"approved_at": "not-a-date"})`. This is what separates a presence-based predicate from a value-based one — a `task.Get("approved_at") != nil` predicate passes the first-approval test and fails every entry here. + - `It("refreshes reapproved_at on a second re-approval")` — seed the both-keys row, execute (assert the written value equals the pinned instant), then call `seedTask(...)` again with a **fresh map literal** of the same fields **before** the second `Execute` — never reuse the first map variable, because `domain.NewTask` stores the caller's map by reference (the existing preservation table's comment at lines 239-242 warns about this), so a reused map would already read `phase: planning` and the second call would be refused by the inbox guard. Then `pinned.SetNow(libtimetest.ParseDateTime("2026-03-03T12:00:05Z"))`, execute again, and assert `WriteTaskCallCount()` is 2, the second written task's `reapproved_at` equals the new pinned instant, and it does not equal the first one. + - `It("refuses a zero clock on the re-approval branch with zero writes")` — seed `{"status": "next", "phase": "todo", "approved_by": "someone"}`, build the operation with a zero `libtime.CurrentDateTime` exactly as `It("refuses a zero clock with zero writes")` does, assert the error contains `approved_at` and `WriteTaskCallCount()` is 0. This pins DB5 on the branch that now writes a timestamp. + +3. **Pin the end-to-end path** in `integration/cli_test.go`, inside `Describe("task approve", ...)`, after `It("AC6: a task carrying any approval record is advanced, per fixture")`. Two specs, each creating its own vault: + + - `It("AC1/AC2/AC4: a re-approval writes a timestamp-typed reapproved_at, preserves approved_at, and the field reader returns it")` — fixture `approvedBothFrontmatter` via `createTempVault` (no owner is resolved on this branch, so no `current_user` is needed). Run `runEntityCommand("task", "approve", "Alpha")`, expect exit 0. From `readFile(taskFile)`: `strings.Trim(valueOf(after, "reapproved_at"), "\"")` must be non-empty and must parse with `time.Parse(time.RFC3339, ...)`; `valueOf(after, "approved_at")` must equal `2026-01-01T00:00:00Z`; `valueOf(after, "approved_by")` must equal `someone`; `valueOf(after, "phase")` must equal `planning`. Then run `runEntityCommand("task", "get", "Alpha", "reapproved_at")`, expect exit 0, and expect `strings.TrimSpace(string(session.Out.Contents()))` to be non-empty. Assert only that the reader returns a non-empty value — do not assert an RFC3339 shape from `task get`, because the generic reader renders a timestamp-typed value with Go's `%v` form. + - `It("AC3: a first approval writes no reapproved_at")` — fixture `todoFrontmatter` via `createTempVaultWithCurrentUser` (the first-approval path resolves an owner, so an empty `assignee` needs a configured `current_user`). Run `task approve Alpha`, expect exit 0, and assert `readFile(taskFile)` contains no `reapproved_at` line (`Expect(after).NotTo(ContainSubstring("reapproved_at"))`) while `valueOf(after, "approved_at")` is non-empty. + +4. **Name the key in the command help.** In `pkg/cli/cli.go`, `createTaskApproveCommand`'s `Long`, extend the second paragraph (the one that begins "An existing approved_at is preserved on re-approval") with a sentence that names `reapproved_at`, says it is written only on a re-approval, and says each re-approval refreshes it. Replace: + + ```go + "fabricates a missing one, and never refreshes approved_at.\n\n" + + ``` + + with: + + ```go + "fabricates a missing one, and never refreshes approved_at. The act of " + + "re-approval is recorded in its own key: reapproved_at is written only on a " + + "re-approval and refreshed by each one, so a reader can tell a row " + + "re-approved a minute ago from one that was never re-approved.\n\n" + + ``` + + Do not reword the rest of the paragraph or the other two paragraphs. The printed help line must contain both `reapproved_at` and `re-approval` on one line — cobra prints `Long` verbatim, so the concatenated sentence satisfies that. Keep the existing spec-067 assertion passing: the phrase `records approved_by and approved_at in one write` must still be followed, at or after it, by a clause containing `preserv` that names `approved_at`. + +5. **Leave the changelog alone.** `CHANGELOG.md` already has exactly one `## Unreleased` section carrying the bullet for this change. Do not add a second bullet, do not move the section, and do not touch any `## vX.Y.Z` section, version string or tag. + +6. **Do not change anything else.** Specifically: + - `pkg/ops/task_approve.go` — no new operation, no new interface method, no new constructor parameter, no change to the first-approval path, no change to `hasApprovalRecord`, no change to `resolveOwner`, no change to `write`. `task approve` performs exactly one `WriteTask` call per invocation, as today. + - `docs/task-writing.md` — no change. Its paragraph stays true and editing it is out of scope. + - `README.md`, `specs/`, `prompts/` — no change. + - No new CLI verb, subcommand or flag, so no integration registration-table entry is needed. + - `pkg/ops/workon.go`'s `advancePhaseIfEntering` operator-flag path is deliberately out of scope: it advances a `todo` row to planning with no `approved_*` write because the flag itself is the approval record there (`docs/task-writing.md` § The approval flag), so it writes no `reapproved_at` either. Do not add one. + - No version string in `.claude-plugin/plugin.json` or `.claude-plugin/marketplace.json` is bumped and no tag is created. + +7. **Self-check before finishing.** Re-run the `` block and confirm every step passes, then walk Acceptance Criteria 1–8 of the spec against the change one by one. For each, name the artefact that proves it: AC1 → the unit type assertion plus the probe's timestamp grep; AC2 → the probe's `task get`; AC3 → the first-approval unit test and integration spec; AC4 → the preserved-value assertions; AC5 → the refresh unit test; AC6 → the existing terminal-row `DescribeTable` (zero writes) plus the probe's digest check; AC7 → the help grep; AC8 → `make precommit`. + + + +- Copied from the spec: `approved_by` and `approved_at` preservation on re-approval is a frozen contract. This change adds a key; it removes and reinterprets nothing. +- Copied from the spec: the key is named exactly `reapproved_at` and holds a timestamp value, matching `approved_at`'s type and formatting. +- Copied from the spec: `hasApprovalRecord` stays presence-based (`task.Keys()`), not value-based. A row whose `approved_at:` is present but blank — or which carries only `approved_by` — still takes the re-approval branch and still receives `reapproved_at`. +- Copied from the spec: the change stays inside the existing re-approval branch and its single write path. No new operation, no new interface method. +- Copied from the spec: `task approve` performs exactly one storage write per invocation; the new key travels in that same write. +- Copied from the spec: `task get "" reapproved_at` reads the value back through the existing generic field reader — no new subcommand, no new output path. +- Copied from the spec: every existing test in `pkg/ops/task_approve_test.go` continues to pass unchanged. Do not edit the preservation `DescribeTable`, the terminal-row `DescribeTable`, or the zero-clock test. +- Copied from the spec: `docs/task-writing.md` is not edited. +- Copied from the spec: do not change `task approve`'s `phase: todo` entry contract, do not give re-approval its own verb, and do not consume the new key anywhere in this repository. +- Do NOT commit — dark-factory handles git. +- Existing tests must still pass, including the whole `pkg/ops` approve suite and the whole `integration` suite. + + + +Run `make precommit` — must exit 0. It includes `test`, plus `check`, which shells out to `trivy`, `osv-scanner`, `vulncheck` and an `addlicense` network fetch; if `check` goes red for an environment reason unrelated to this change, run `make test lint check-changelog` instead and say which step failed and why — `check-changelog` is change-related and must not be dropped with the environment-dependent steps. + +```bash +go test ./pkg/ops/... ./pkg/cli/... ./integration/... +``` + +Then the behavioural probe. Build the binary first — never the installed `vault-cli`, which is a different version: + +```bash +go build -o /tmp/vc-reapproved-bin . && echo built +``` + +```bash +rm -rf /tmp/vc-reapproved-probe && mkdir -p "/tmp/vc-reapproved-probe/25 Tasks" +cat > /tmp/vc-reapproved-probe/config.yaml <<'EOF' +current_user: bborbe +default_vault: probe +vaults: + probe: + path: /tmp/vc-reapproved-probe + name: probe + tasks_dir: 25 Tasks + goals_dir: 24 Goals + topics_dir: 23 Topics +EOF +cat > "/tmp/vc-reapproved-probe/25 Tasks/Probe Re-Approval.md" <<'EOF' +--- +page_type: task +status: next +phase: todo +assignee: bborbe +--- +EOF +F="/tmp/vc-reapproved-probe/25 Tasks/Probe Re-Approval.md" +VC="/tmp/vc-reapproved-bin --config /tmp/vc-reapproved-probe/config.yaml" +fail() { echo "FAIL $1"; exit 1; } + +# AC3 — the first approval writes no reapproved_at +$VC task approve "Probe Re-Approval" >/dev/null +[ "$(grep -c '^reapproved_at:' "$F")" = 0 ] || fail "AC3: first approval wrote reapproved_at" +[ "$(grep -c '^approved_at:' "$F")" = 1 ] || fail "AC3: approved_at missing" +BEFORE_AT=$(grep -m1 '^approved_at:' "$F") + +# AC1 + AC2 + AC4 — revert, re-approve, the key appears and approved_at did not move +$VC task set "Probe Re-Approval" phase todo >/dev/null +sleep 1 +$VC task approve "Probe Re-Approval" >/dev/null +[ "$(grep -cE '^reapproved_at: [0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}' "$F")" = 1 ] \ + || fail "AC1: reapproved_at missing or not a timestamp" +[ -n "$($VC task get 'Probe Re-Approval' reapproved_at)" ] || fail "AC2: reader returned empty" +[ "$(grep -m1 '^approved_at:' "$F")" = "$BEFORE_AT" ] || fail "AC4: approved_at moved" + +# AC5 — a second re-approval refreshes, and the new instant is later +FIRST=$(grep -m1 '^reapproved_at:' "$F") +$VC task set "Probe Re-Approval" phase todo >/dev/null +sleep 1 +$VC task approve "Probe Re-Approval" >/dev/null +SECOND=$(grep -m1 '^reapproved_at:' "$F") +[ "$FIRST" != "$SECOND" ] || fail "AC5: reapproved_at was preserved, not refreshed" +[ "$SECOND" \> "$FIRST" ] || fail "AC5: the refreshed instant is not later" + +# AC6 — a terminal row is refused and nothing is written +cat > "/tmp/vc-reapproved-probe/25 Tasks/Probe Terminal.md" <<'EOF' +--- +page_type: task +status: completed +phase: todo +approved_by: operator +approved_at: 2026-01-01T00:00:00Z +assignee: bborbe +--- +EOF +T="/tmp/vc-reapproved-probe/25 Tasks/Probe Terminal.md" +sha() { { sha256sum "$1" 2>/dev/null || shasum -a 256 "$1"; } | awk '{print $1}'; } +BEFORE_SUM=$(sha "$T") +[ -n "$BEFORE_SUM" ] || fail "AC6: no sha256 tool available (need sha256sum or shasum)" +$VC task approve "Probe Terminal" >/dev/null 2>&1 && fail "AC6: a terminal row was approved" +[ "$(sha "$T")" = "$BEFORE_SUM" ] || fail "AC6: the file changed" + +# AC7 — the help names the key and its condition +$VC task approve --help | grep -qE 'reapproved_at.*re-approval|re-approval.*reapproved_at' \ + || fail "AC7: help does not name reapproved_at as a re-approval key" + +echo "probe: all assertions passed" +``` + +Notes on the probe: run it with `bash`. The `sha()` helper already accepts either `sha256sum` or `shasum`, and refuses loudly when neither exists — the assertion is the digest equality before and after, not the tool. The `sleep 1` calls are load-bearing: the key holds an RFC3339 instant with second precision, so two re-approvals in the same second legitimately write the same value. + +Finally, the durable file-level checks: + +```bash +go run . task approve --help | grep -qE 'reapproved_at.*re-approval|re-approval.*reapproved_at' +grep -c 'reapproved_at' pkg/ops/task_approve.go +grep -c 'reapproved_at' pkg/ops/task_approve_test.go +grep -c 'reapproved_at' pkg/cli/cli.go +grep -c '^## Unreleased' CHANGELOG.md +awk '/^## /{sec=$0} /reapproved_at/ {print "sits under: " sec}' CHANGELOG.md +! grep -q 'reapproved_at' docs/task-writing.md +``` + +Expected: the help grep exits 0; the three source counts are at least 1; the `## Unreleased` count is exactly 1; the `awk` prints `sits under: ## Unreleased`; the `docs/task-writing.md` absence check exits 0. Do not use `git diff` or `git status` here — the daemon may run this container with `.git` masked, and those commands fail with `fatal: not a git repository`. + diff --git a/specs/in-progress/069-task-approve-records-reapproved-at.md b/specs/in-progress/069-task-approve-records-reapproved-at.md new file mode 100644 index 0000000..5951500 --- /dev/null +++ b/specs/in-progress/069-task-approve-records-reapproved-at.md @@ -0,0 +1,184 @@ +--- +status: verifying +approved: "2026-11-17T23:45:39Z" +verifying: "2026-11-18T19:33:38Z" +branch: dark-factory/task-approve-records-reapproved-at +--- + +## Summary + +- A re-approval currently moves a task's phase but leaves no trace of *when* it happened. +- `approved_at` is deliberately preserved, so a re-approval is invisible to anything reading the row. +- The decision-park resume leg keys on "the approval landed after the worker last spoke" and therefore never fires for a re-approved row. +- This spec adds one key — `reapproved_at` — written only on the re-approval branch, at the moment of the event. +- The first approval is unchanged: it remains observable through `approved_at`. + +## Problem + +`vault-cli task approve` refuses any row that is not at `phase: todo`. A row that already carries an approval record is advanced to `planning` with `approved_by` and `approved_at` preserved exactly as they are — a deliberate, documented contract, because the first approval already happened and re-stamping it would make a first approval indistinguishable from a re-approval. + +That leaves a re-approval with exactly one observable trace: the phase string. It carries no time. A consumer that must react to the *act* of re-approval — "the operator cleared this wait just now" — cannot tell a re-approval that happened a minute ago from one that happened three weeks ago, and cannot tell either of them from a row that was never re-approved at all. + +The concrete consumer is `claude-supervisor`'s decision-park resume leg (`scripts/decision-park-resume.py`, `approval_cleared()`: "the approval must be later than the session's last turn"). That claim is about an external repository and is **not verifiable from this repo**; it is cited so the reader can check it, not asserted as this spec's evidence. A re-approved row's `approved_at` predates that turn by construction, so the leg never fires — the operator's most intuitive recovery action produces silence, and the failure reads as a broken leg rather than an approval that was never recorded. + +## Goal + +A re-approval is an event with a timestamp. Any consumer reading a task row can answer "was this row re-approved, and when?" from the frontmatter alone, without git history, without cross-round memory, and without inferring it from the phase string. + +## Non-goals + +- Changing the preservation of `approved_by` / `approved_at` on re-approval. That contract is correct and is what makes the ambiguity resolvable: refreshing `approved_at` would make a first approval indistinguishable from a re-approval, which is why this spec adds a second key instead. +- Making `task approve` runnable from any phase. The `phase: todo` entry contract is unchanged. +- Giving re-approval its own verb. A marker field on the existing verb is the chosen mechanism; a separate verb would be a second way to do one thing. +- Consuming the new key anywhere in this repository. +- **The consuming change in `claude-supervisor`'s decision-park leg — tracked separately.** Until it lands this spec only makes the event observable; the leg stays silent. + +## Acceptance Criteria + +- [ ] A re-approval writes `reapproved_at` as a timestamp value, not a formatted string. Evidence: after `vault-cli task approve ""` on a row that already carries `approved_at` and sits at `phase: todo`, `grep -cE '^reapproved_at: [0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}' ""` returns `1`, **and** the unit test asserts `written.Get("reapproved_at").(time.Time)` succeeds — mirroring the existing `approved_at` assertion at `pkg/ops/task_approve_test.go:88`. ⚠️ The grep alone cannot separate a `time.Time` from an RFC3339 string; the type assertion is what pins DB2's type parity. +- [ ] The key is readable through the existing generic field reader. Evidence: `vault-cli task get "" reapproved_at` prints a non-empty value. ⚠️ **Shape only, never "RFC3339"** — the generic reader returns Go's `%v` form for a timestamp-typed value (`2026-11-18 09:00:00 +0100 CET`), so an RFC3339 assertion against it cannot pass without adding a read path this spec forbids. +- [ ] The first approval writes **no** `reapproved_at`, and the branch is presence-based rather than value-based. Evidence: on a freshly created row at `phase: todo` with no approval record, `vault-cli task approve ""` then `grep -c '^reapproved_at:' ""` returns `0`, while `grep -c '^approved_at:'` returns `1`; **and** a second fixture carrying only `approved_by` (no `approved_at`) still receives `reapproved_at`, asserted in the unit test. A value-based predicate (`task.Get("approved_at") != nil`) would pass the first clause and fail the second. +- [ ] `approved_at` is still preserved on re-approval. Evidence: `grep -m1 '^approved_at:' ""` returns the identical string before and after the re-approval. +- [ ] A second re-approval **refreshes** `reapproved_at` rather than preserving it. Evidence: two re-approvals separated by at least one second produce two different `grep -m1 '^reapproved_at:'` values, and the second sorts later than the first. ⚠️ **Precondition:** `task set phase todo` is refused only when the row is `in_progress` **and** already past planning (`execution` / `ai_review` / `human_review`, `pkg/ops/frontmatter.go:380-395`). A `planning` or `next` row accepts the staging step, so the probe row must not be in a post-planning phase. +- [ ] A terminal row is still refused and nothing is written. Evidence: on a row carrying an approval record at `phase: todo` with `status: completed`, `vault-cli task approve ""` exits non-zero and `shasum -a 256 ""` returns the same digest before and after; the same behaviour is pinned by `pkg/ops/task_approve_test.go:318` ("refuses a terminal row that is still at phase todo, with zero writes"). ⚠️ **Not `git diff`** — the disposable probe vault is not a git repository, so `git diff` exits 129 there. +- [ ] `vault-cli task approve --help` names the new key **and** says it is written only on a re-approval. Evidence: `vault-cli task approve --help | grep -qE 'reapproved_at.*re-approval|re-approval.*reapproved_at'` exits `0`. ⚠️ A bare `grep -c reapproved_at` is not enough — the existing help already says "never refreshes `approved_at`", so an author could add "never writes `reapproved_at`" and satisfy a count while contradicting DB6. +- [ ] `make precommit` exits 0. ⚠️ `precommit` includes `test`; it also runs `check`, which shells out to `trivy` and an `addlicense` network fetch, so it can go red for environment reasons unrelated to this change. If it does, run `make test lint` and say which step failed and why. + +## Verification + +**Both rungs are run by the verifier.** The probe below needs only `go build` and a temp directory, so it is container-executable too — it is separated only because it reads more clearly on its own. + +### Rung 1 — container-executable + +```bash +make precommit +make test # faster inner loop while iterating; precommit already includes it +``` + +### Rung 2 — the behavioural probe, asserting rather than printing + +Build the binary first — never the installed `vault-cli`, which is a different version: + +```bash +go build -o /tmp/vc-reapproved-bin . && echo built +``` + +```bash +rm -rf /tmp/vc-reapproved-probe && mkdir -p "/tmp/vc-reapproved-probe/25 Tasks" +cat > /tmp/vc-reapproved-probe/config.yaml <<'EOF' +current_user: bborbe +default_vault: probe +vaults: + probe: + path: /tmp/vc-reapproved-probe + name: probe + tasks_dir: 25 Tasks + goals_dir: 24 Goals + topics_dir: 23 Topics +EOF +cat > "/tmp/vc-reapproved-probe/25 Tasks/Probe Re-Approval.md" <<'EOF' +--- +page_type: task +status: next +phase: todo +assignee: bborbe +--- +EOF +F="/tmp/vc-reapproved-probe/25 Tasks/Probe Re-Approval.md" +VC="/tmp/vc-reapproved-bin --config /tmp/vc-reapproved-probe/config.yaml" +fail() { echo "FAIL $1"; exit 1; } + +# AC3 — the first approval writes no reapproved_at +$VC task approve "Probe Re-Approval" >/dev/null +[ "$(grep -c '^reapproved_at:' "$F")" = 0 ] || fail "AC3: first approval wrote reapproved_at" +[ "$(grep -c '^approved_at:' "$F")" = 1 ] || fail "AC3: approved_at missing" +BEFORE_AT=$(grep -m1 '^approved_at:' "$F") + +# AC1 + AC2 + AC4 — revert, re-approve, the key appears and approved_at did not move +$VC task set "Probe Re-Approval" phase todo >/dev/null +sleep 1 +$VC task approve "Probe Re-Approval" >/dev/null +[ "$(grep -cE '^reapproved_at: [0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}' "$F")" = 1 ] \ + || fail "AC1: reapproved_at missing or not a timestamp" +[ -n "$($VC task get 'Probe Re-Approval' reapproved_at)" ] || fail "AC2: reader returned empty" +[ "$(grep -m1 '^approved_at:' "$F")" = "$BEFORE_AT" ] || fail "AC4: approved_at moved" + +# AC5 — a second re-approval refreshes, and the new instant is later +FIRST=$(grep -m1 '^reapproved_at:' "$F") +$VC task set "Probe Re-Approval" phase todo >/dev/null +sleep 1 +$VC task approve "Probe Re-Approval" >/dev/null +SECOND=$(grep -m1 '^reapproved_at:' "$F") +[ "$FIRST" != "$SECOND" ] || fail "AC5: reapproved_at was preserved, not refreshed" +[ "$SECOND" \> "$FIRST" ] || fail "AC5: the refreshed instant is not later" + +# AC6 — a terminal row is refused and nothing is written +cat > "/tmp/vc-reapproved-probe/25 Tasks/Probe Terminal.md" <<'EOF' +--- +page_type: task +status: completed +phase: todo +approved_by: operator +approved_at: 2026-01-01T00:00:00Z +assignee: bborbe +--- +EOF +T="/tmp/vc-reapproved-probe/25 Tasks/Probe Terminal.md" +BEFORE_SUM=$(shasum -a 256 "$T" | awk '{print $1}') +$VC task approve "Probe Terminal" >/dev/null 2>&1 && fail "AC6: a terminal row was approved" +[ "$(shasum -a 256 "$T" | awk '{print $1}')" = "$BEFORE_SUM" ] || fail "AC6: the file changed" + +# AC7 — the help names the key and its condition +$VC task approve --help | grep -qE 'reapproved_at.*re-approval|re-approval.*reapproved_at' \ + || fail "AC7: help does not name reapproved_at as a re-approval key" + +echo "probe: all assertions passed" +``` + +## Desired Behavior + +1. On a row at `phase: todo` with **no** approval record, `task approve` behaves exactly as today: it sets `phase: planning`, writes `approved_by` and `approved_at`, and writes no `reapproved_at`. +2. On a row at `phase: todo` that **already carries** an approval record, `task approve` sets `phase: planning`, preserves `approved_by` and `approved_at` byte-for-byte, and writes `reapproved_at` with the current instant as a `time.Time`. +3. Every subsequent re-approval of the same row **refreshes** `reapproved_at` to the current instant. It is an event time, not a record of the first re-approval. +4. A row carrying an approval record whose status is `completed` or `aborted` is still refused, and the refusal writes nothing — including no `reapproved_at`. +5. The zero-clock guard still runs before any mutation: a zero instant refuses the approval rather than writing a placeholder into either key. +6. `vault-cli task approve --help` names `reapproved_at` and says it is written only on a re-approval, so a reader can discover the key without reading this spec. + +## Constraints + +- `approved_by` and `approved_at` preservation on re-approval is a frozen contract. This spec adds a key; it removes and reinterprets nothing. +- **`docs/task-writing.md` is not edited.** Its approval-record paragraph states that the re-approval branch "never overwrites either key, never fabricates a missing one" — a claim that stays true: `approved_by` and `approved_at` are neither overwritten nor fabricated. A third, separate key is added beside them. Editing that paragraph is forbidden by the consuming task's scope, and the paragraph's own assertion survives the change. The key's durable discovery surface is therefore the command help (DB6). +- The key is named exactly `reapproved_at` and holds an RFC3339 instant, matching `approved_at`'s type and formatting. +- `hasApprovalRecord` stays presence-based (`task.Keys()`), not value-based. A row whose `approved_at:` is present but blank — or which carries only `approved_by` — still takes the re-approval branch, so it still receives `reapproved_at`. +- The change stays inside the existing re-approval branch and its single write path. No new operation, no new interface method. +- `task approve` performs exactly **one** storage write per invocation, as it does today; the new key travels in that same write. +- `task get "" reapproved_at` reads the value back through the existing generic field reader — no new subcommand, no new output path. +- Every existing test in `pkg/ops/task_approve_test.go` continues to pass unchanged. + +## Failure Modes + +| Trigger | Expected behavior | Recovery | +|---|---|---| +| Row carries an approval record but `approved_at` is unparseable | The branch is presence-based, so `reapproved_at` is still written; `approved_at` is left untouched | None needed — the new key is the signal, not the old one | +| Clock returns a zero instant | Refused before any mutation; neither key is written | Fix the clock source, then `vault-cli task approve ""` again | +| Row is `completed` / `aborted` at `phase: todo` | Refused; nothing written, no `reapproved_at` | Run `vault-cli task get "" phase` and decide deliberately whether the row is mis-phased; `vault-cli task set "" phase ` if it is | +| The storage write fails | Nothing reaches disk — no phase change and no `reapproved_at` | Re-run `vault-cli task approve ""`; the guard order means a retry is safe | +| Two concurrent re-approvals | Last write wins; the earlier instant is lost, and both rows end at `phase: planning` | Not a supported workflow — an operator acts on one row at a time; the surviving instant is still later than any prior turn, so the consumer is unaffected | +| Two re-approvals in the same second | Both write the same instant; a consumer ordering by this key alone cannot separate them | Consumers that need strict ordering use the phase transition count or a distinct verb; out of scope here | +| A consumer treats `reapproved_at` as "the only approval" | It misses first approvals, which have no such key | Consumers read `approved_at` for the first approval and `reapproved_at` for re-approvals — documented in the consuming repo | + +## Security / Abuse Cases + +The change writes one additional key into a file the command already writes. It introduces no new input, no new path, and no new subprocess. The approver identity and the zero-clock guard are unchanged. + +## Suggested Decomposition + +Single layer, single prompt. + +| # | Prompt focus | Covers DBs | Covers ACs | Depends on | +|---|---|---|---|---| +| 1 | Write `reapproved_at` on the re-approval branch, pin it with tests, and name it in the command help | 1-6 | 1-8 | — | + +## Do-Nothing Option + +Without this, a re-approval stays unobservable and no consumer can distinguish "re-approved a minute ago" from "never re-approved". The consuming leg stays silent, so an operator who re-approves to clear a wait gets no reaction and cannot tell that from a broken leg; the only remaining recovery is a manual session resume. This spec makes the event observable — it does not by itself resume anything.