Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
41 changes: 41 additions & 0 deletions integration/cli_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
18 changes: 13 additions & 5 deletions pkg/cli/cli.go
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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 " +
Expand Down
9 changes: 8 additions & 1 deletion pkg/ops/task_approve.go
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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)
}

Expand Down
142 changes: 142 additions & 0 deletions pkg/ops/task_approve_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
Loading
Loading