From 1644677124fd5e41b93c246b47d71153705efb22 Mon Sep 17 00:00:00 2001 From: Benjamin Borbe Date: Tue, 17 Nov 2026 00:51:00 +0100 Subject: [PATCH 1/3] chore: add prompt making goal set write the flag as a boolean with provenance --- prompts/goal-set-flag-boolean-provenance.md | 79 +++++++++++++++++++++ 1 file changed, 79 insertions(+) create mode 100644 prompts/goal-set-flag-boolean-provenance.md diff --git a/prompts/goal-set-flag-boolean-provenance.md b/prompts/goal-set-flag-boolean-provenance.md new file mode 100644 index 0000000..0bff969 --- /dev/null +++ b/prompts/goal-set-flag-boolean-provenance.md @@ -0,0 +1,79 @@ +--- +status: draft +created: "2026-11-16T22:40:00Z" +--- + +# Write goal flags as booleans and record their provenance + + +- `vault-cli goal set flag true` stores a real YAML boolean, not the quoted string `"true"` it stores today. +- `goal set flag true --by ` records who set the flag, and when, in the same file write that sets the flag. +- A truthy flag with no recorded writer is refused before anything is written. +- Setting a goal's flag provenance directly is refused, exactly as the task verb refuses it. +- The refusal names the goal verb, so the hint the user is shown is a command that works. +- Other goal fields are written exactly as before — only `flag` gains boolean handling. +- Goal flags now behave like task flags, which have done all of this since the flag-provenance change landed. +- The changelog records the fix under `## Unreleased`; no version string is bumped and no tag is created. + + + +Make `vault-cli goal set` write the flag as a real YAML boolean and record its provenance in the same write, so a flagged goal is readable by strict readers and the flag carries evidence of who set it. + + + +Read `CLAUDE.md` first, then `docs/dod.md`. + +Read these before editing: + +- `pkg/domain/goal_frontmatter.go` — `SetField` (line 321) and `ClearField` (line 416). The `switch` in `SetField` has no `flag` case, so `flag` falls to `default: f.Set(key, value)` and stores the raw string; yaml.v3 then quotes it. +- `pkg/domain/task_frontmatter.go` — the exemplar for all three pieces: `setFlagField` (line 481), `SetField`'s `case "flag"` (line 530), `SetFlag` (line 335), `ClearFlag` (line 345). +- `pkg/domain/frontmatter_map.go` line 63 — `GetBool` accepts a bool and the strings `true` / `yes` / `false` / `no` case-insensitively. +- `pkg/ops/frontmatter.go` — `writeFlagProvenance` (line 243) and `flagProvenanceSetRefusal` (line 276). Both are task-specific today: the first takes `*domain.Task`, the second hardcodes `vault-cli task set`. +- `pkg/ops/frontmatter_entity.go` — `EntitySetOperation` (line 105) and `goalSetOperation.Execute` (line 115). `Execute` carries no actor, so the goal path cannot record provenance. +- `pkg/cli/cli.go` — `createEntitySetCommand` (line 1001), the goal-only flag registration at line 1054, and the task verb's `--by` binding at line 2740. + + + +1. **Boolean flag on the goal frontmatter.** In `pkg/domain/goal_frontmatter.go`, add `SetFlag(ctx context.Context, v bool) error`, `ClearFlag()`, and `setFlagField(ctx context.Context, value string) error`, mirroring `TaskFrontmatter`'s three methods. `SetFlag` stores a real `bool` via `f.Set("flag", v)`. `ClearFlag` deletes `flag`, `flag_set_by` and `flag_set_at`. `setFlagField` accepts `true` / `yes` / `false` / `no` case-insensitively with surrounding whitespace trimmed, clears on `""`, and rejects any other value with the task path's error shape. Also extend `GoalFrontmatter.ClearField` so `key == "flag"` additionally deletes `flag_set_by` and `flag_set_at`, mirroring `TaskFrontmatter.ClearField` — otherwise `goal clear flag` leaves a stale actor behind and defeats the provenance contract. + +2. **Wire it into `SetField`.** Add `case "flag": return f.setFlagField(ctx, value)` to `GoalFrontmatter.SetField`'s switch, ahead of the `default` arm. Every other key keeps its current behaviour. + +3. **Thread the actor through the entity-set path.** Add a trailing `actor string` parameter to `EntitySetOperation.Execute`. The goal implementation consults it; the theme, objective, vision and topic implementations ignore it (name the parameter `_` where unused, as `SetFlag` already does). Update `createEntitySetCommand`'s call site and every `EntitySetOperation.Execute` call site in `pkg/cli/cli.go` and in the `pkg/ops/*_test.go` files — `frontmatter_entity_test.go`, `frontmatter_entity_session_takeover_test.go`, `wikilink_roundtrip_test.go` and `blocked_by_set_test.go` — plus `mocks/entity-set-operation.go` (counterfeiter regenerates it from the interface). + +4. **Write goal provenance in the same write.** Before `SetField`, when `key == "flag"`, the goal operation applies the same three outcomes `writeFlagProvenance` applies to a task: truthy → `flag_set_by` is the actor and `flag_set_at` is the injected `currentDateTime` stored as a bare `time.Time` (so yaml.v3 renders it unquoted); falsy → both provenance keys are deleted; empty → nothing is done here, because the frontmatter's `ClearFlag` removes them. A truthy flag with a blank actor is refused before any mutation, with the task path's error shape naming the goal. Share the truthiness switch with the task helper rather than duplicating it: extract a package-level helper in `pkg/ops/frontmatter.go` taking the frontmatter map, the flag value, the actor and the `currentDateTime`, and call it from both the task and goal paths. + +5. **Generalise the direct-provenance refusal.** `flagProvenanceSetRefusal` takes the verb it is refusing for, and emits ``use `vault-cli goal set "" flag true --by ` `` from the goal path and the existing task wording from the task path. Call it from `goalSetOperation.Execute` before any mutation, with the same byte-identical refusal guarantee the task path has. + +6. **Add `--by` to `goal set` only.** In `createEntitySetCommand`, register `--by` (default `"unknown"`, the same help text as the task verb's at line 2740) when `entityType == "goal"`, and pass its value into `Execute`. The theme, objective, vision and topic verbs keep their current flag sets. When `--by` was explicitly passed (`cmd.Flags().Changed("by")`) and `key != "flag"`, refuse with `validation.Error` before dispatch, mirroring the task verb's guard in `createTaskSetCommand` — the hint must name `vault-cli goal set`. + +7. **Tests.** Add Ginkgo/Gomega tests that: + - write `flag true` on a goal and assert the serialized bytes contain `flag: true` and NOT `flag: "true"` — assert on the written file, so the YAML serialization boundary is actually traversed, not just the in-memory map; + - write `flag false` and assert `flag: false` unquoted; + - write `flag true` with actor `operator` and assert `flag_set_by: operator` plus a `flag_set_at` that parses as a time; + - assert a blank actor on a truthy flag is refused and the file is byte-identical; + - assert a bare `goal set flag_set_by ` is refused and the message names `goal set`; + - assert `goal clear flag` removes `flag`, `flag_set_by` and `flag_set_at`; + - assert a non-boolean goal field (e.g. `phase`) still round-trips unchanged; + - add one CLI-level end-to-end test in `integration/cli_test.go` that runs `goal set flag true --by operator` and asserts the written file, so the cobra wiring — `--by` registered for goal, default `unknown` — is exercised rather than only the ops layer. + +8. **Changelog.** Add a `## Unreleased` section directly below the preamble (the `All notable changes…` line and the three `* MAJOR/MINOR/PATCH` bullets) and above `## v0.194.2`, never between `# Changelog` and the preamble. Give it a `- fix:` bullet stating that `goal set` now writes the flag as an unquoted boolean and records its provenance, matching `task set`. + +9. **Docs.** Add a short paragraph to `docs/goal-writing.md` documenting `goal set flag true --by `: the flag is a boolean, `flag_set_by` / `flag_set_at` are written in the same write, and a direct provenance write is refused. `docs/task-writing.md` (lines 172–181) is the wording exemplar. + +10. **Self-check.** Before finishing, re-run `` and confirm it passes; walk each numbered requirement and each test above against the change. + + + +- Do NOT commit — dark-factory handles git. +- Do NOT bump any version string in `CHANGELOG.md`, `.claude-plugin/plugin.json` or `.claude-plugin/marketplace.json`, and do NOT create a tag. `.maintainer.yaml: release.autoRelease: true` — the releaser owns the bump after merge. +- Do NOT run `go mod vendor`, and do NOT use `-mod=vendor` anywhere. +- Existing tests must still pass, except where requirement 3 changes a call signature. +- Use `errors.Wrap` / `errors.Wrapf` from `github.com/bborbe/errors`, never `fmt.Errorf`. +- Inject time through the existing `libtime.CurrentDateTime`, never `time.Now()`. +- Do NOT change `task set`'s behaviour; only generalise the shared refusal helper. +- Do NOT add flag handling to the theme, objective, vision or topic frontmatters. + + + +Run `ROOTDIR=/workspace make precommit` — must pass. + From ac7e4c7f13e00842f766f2f5dc567e1e5984ec33 Mon Sep 17 00:00:00 2001 From: Benjamin Borbe Date: Tue, 17 Nov 2026 01:30:17 +0100 Subject: [PATCH 2/3] chore: queue prompt 282 (approved) --- .../282-goal-set-flag-boolean-provenance.md} | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) rename prompts/{goal-set-flag-boolean-provenance.md => in-progress/282-goal-set-flag-boolean-provenance.md} (99%) diff --git a/prompts/goal-set-flag-boolean-provenance.md b/prompts/in-progress/282-goal-set-flag-boolean-provenance.md similarity index 99% rename from prompts/goal-set-flag-boolean-provenance.md rename to prompts/in-progress/282-goal-set-flag-boolean-provenance.md index 0bff969..410b38c 100644 --- a/prompts/goal-set-flag-boolean-provenance.md +++ b/prompts/in-progress/282-goal-set-flag-boolean-provenance.md @@ -1,6 +1,7 @@ --- -status: draft +status: approved created: "2026-11-16T22:40:00Z" +queued: "2026-11-16T23:52:09Z" --- # Write goal flags as booleans and record their provenance From 1f7d8df8dc22106c3dce468b5e5c083ef4fcf1d9 Mon Sep 17 00:00:00 2001 From: Benjamin Borbe Date: Tue, 17 Nov 2026 03:38:57 +0100 Subject: [PATCH 3/3] Write goal flags as booleans and record their provenance --- CHANGELOG.md | 4 + docs/goal-writing.md | 4 + integration/cli_test.go | 27 ++++ mocks/entity-set-operation.go | 18 ++- pkg/cli/cli.go | 18 ++- pkg/domain/goal_frontmatter.go | 45 ++++++ pkg/ops/blocked_by_set_test.go | 2 +- pkg/ops/frontmatter.go | 49 +++--- pkg/ops/frontmatter_entity.go | 32 +++- ...rontmatter_entity_session_takeover_test.go | 10 +- pkg/ops/frontmatter_entity_test.go | 144 +++++++++++++++++- pkg/ops/wikilink_roundtrip_test.go | 8 +- .../282-goal-set-flag-boolean-provenance.md | 7 +- 13 files changed, 317 insertions(+), 51 deletions(-) rename prompts/{in-progress => completed}/282-goal-set-flag-boolean-provenance.md (96%) diff --git a/CHANGELOG.md b/CHANGELOG.md index 52ffed1..97bb4a4 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 + +- fix: `goal set` now writes the flag as an unquoted YAML boolean and records `flag_set_by` / `flag_set_at` in the same write via `--by`, matching `task set` + ## v0.195.0 - feat: report `EXPIRED_DEFER_DATE` when a task sits at `in_progress` with a past `defer_date` diff --git a/docs/goal-writing.md b/docs/goal-writing.md index 2402ba1..f69627d 100644 --- a/docs/goal-writing.md +++ b/docs/goal-writing.md @@ -163,6 +163,10 @@ The walk ends at `done`, and both terminal statuses end it the same way: a termi A goal with no `phase` key is exempt from the gate and cannot be approved; set `phase: todo` first. A goal that already carries `approved_by` or `approved_at` is refused rather than re-approved, and the refusal writes nothing. +### The flag (`flag`) + +A goal's `flag` is a real YAML boolean, written by `vault-cli goal set "" flag true --by ` — the same contract as `task set`. The write stores `flag: true` (or `flag: false`) unquoted and, for a truthy value, records the actor as `flag_set_by` and the instant as `flag_set_at` in the **same single write**, so no reader can observe a flagged goal without its provenance. `--by` defaults to the literal `unknown`, is accepted only for the `flag` key, and a truthy flag with a blank actor is refused before anything is written. Writing `flag_set_by` or `flag_set_at` directly is refused: they exist only as evidence of the invocation that set the flag. `vault-cli goal clear "" flag` removes the flag and both provenance keys together. + ### Dependencies (`blocked_by`) `blocked_by` declares the goals this goal cannot start before. It is a YAML list of goal names; each entry may be a plain name (`Blocker Goal`) or a wikilink (`[[Blocker Goal]]`) — both forms resolve the same way. A scalar value (`blocked_by: Blocker Goal`) is malformed and reads as an empty list, so it never blocks. `vault-cli goal lint` reports a goal whose `blocked_by` is shaped this way; `vault-cli task validate` and `vault-cli task lint` report the task-side equivalent. diff --git a/integration/cli_test.go b/integration/cli_test.go index 54312ad..13beddc 100644 --- a/integration/cli_test.go +++ b/integration/cli_test.go @@ -6542,6 +6542,33 @@ page_type: goal Expect(showPhaseField(configPath, "goal", "Phase Target")).To(Equal("ai_review")) }) + It("goal set writes the flag as a boolean and records --by in the same write", func() { + vaultPath, configPath, cleanup := createTempVaultWithTopicPages( + "Topics", + nil, + map[string]string{ + "Flag Target": "---\nstatus: in_progress\n---\n# Flag Target\n", + }, + ) + defer cleanup() + + cmd := exec.Command( + binPath, "--config", configPath, "--vault", "test", + "goal", "set", "Flag Target", "flag", "true", "--by", "operator", + ) + session, err := gexec.Start(cmd, GinkgoWriter, GinkgoWriter) + Expect(err).NotTo(HaveOccurred()) + Eventually(session).Should(gexec.Exit(0)) + + content, err := os.ReadFile(filepath.Join(vaultPath, "Goals", "Flag Target.md")) + Expect(err).NotTo(HaveOccurred()) + out := string(content) + Expect(out).To(ContainSubstring("flag: true")) + Expect(out).NotTo(ContainSubstring(`flag: "true"`)) + Expect(out).To(ContainSubstring("flag_set_by: operator")) + Expect(out).To(ContainSubstring("flag_set_at:")) + }) + It("goal set accepts human_review and writes it to the page on disk", func() { vaultPath, configPath, cleanup := createTempVaultWithTopicPages( "Topics", diff --git a/mocks/entity-set-operation.go b/mocks/entity-set-operation.go index 8ff7d9e..c679f32 100644 --- a/mocks/entity-set-operation.go +++ b/mocks/entity-set-operation.go @@ -9,7 +9,7 @@ import ( ) type EntitySetOperation struct { - ExecuteStub func(context.Context, string, string, string, string, string, string) error + ExecuteStub func(context.Context, string, string, string, string, string, string, string) error executeMutex sync.RWMutex executeArgsForCall []struct { arg1 context.Context @@ -19,6 +19,7 @@ type EntitySetOperation struct { arg5 string arg6 string arg7 string + arg8 string } executeReturns struct { result1 error @@ -30,7 +31,7 @@ type EntitySetOperation struct { invocationsMutex sync.RWMutex } -func (fake *EntitySetOperation) Execute(arg1 context.Context, arg2 string, arg3 string, arg4 string, arg5 string, arg6 string, arg7 string) error { +func (fake *EntitySetOperation) Execute(arg1 context.Context, arg2 string, arg3 string, arg4 string, arg5 string, arg6 string, arg7 string, arg8 string) error { fake.executeMutex.Lock() ret, specificReturn := fake.executeReturnsOnCall[len(fake.executeArgsForCall)] fake.executeArgsForCall = append(fake.executeArgsForCall, struct { @@ -41,13 +42,14 @@ func (fake *EntitySetOperation) Execute(arg1 context.Context, arg2 string, arg3 arg5 string arg6 string arg7 string - }{arg1, arg2, arg3, arg4, arg5, arg6, arg7}) + arg8 string + }{arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8}) stub := fake.ExecuteStub fakeReturns := fake.executeReturns - fake.recordInvocation("Execute", []interface{}{arg1, arg2, arg3, arg4, arg5, arg6, arg7}) + fake.recordInvocation("Execute", []interface{}{arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8}) fake.executeMutex.Unlock() if stub != nil { - return stub(arg1, arg2, arg3, arg4, arg5, arg6, arg7) + return stub(arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8) } if specificReturn { return ret.result1 @@ -61,17 +63,17 @@ func (fake *EntitySetOperation) ExecuteCallCount() int { return len(fake.executeArgsForCall) } -func (fake *EntitySetOperation) ExecuteCalls(stub func(context.Context, string, string, string, string, string, string) error) { +func (fake *EntitySetOperation) ExecuteCalls(stub func(context.Context, string, string, string, string, string, string, string) error) { fake.executeMutex.Lock() defer fake.executeMutex.Unlock() fake.ExecuteStub = stub } -func (fake *EntitySetOperation) ExecuteArgsForCall(i int) (context.Context, string, string, string, string, string, string) { +func (fake *EntitySetOperation) ExecuteArgsForCall(i int) (context.Context, string, string, string, string, string, string, string) { fake.executeMutex.RLock() defer fake.executeMutex.RUnlock() argsForCall := fake.executeArgsForCall[i] - return argsForCall.arg1, argsForCall.arg2, argsForCall.arg3, argsForCall.arg4, argsForCall.arg5, argsForCall.arg6, argsForCall.arg7 + return argsForCall.arg1, argsForCall.arg2, argsForCall.arg3, argsForCall.arg4, argsForCall.arg5, argsForCall.arg6, argsForCall.arg7, argsForCall.arg8 } func (fake *EntitySetOperation) ExecuteReturns(result1 error) { diff --git a/pkg/cli/cli.go b/pkg/cli/cli.go index 7abe26b..45ca497 100644 --- a/pkg/cli/cli.go +++ b/pkg/cli/cli.go @@ -1008,7 +1008,7 @@ func createEntitySetCommand( entityType string, newSetOp func(cfg *storage.Config) ops.EntitySetOperation, ) *cobra.Command { - var reason, gateSuccessor string + var reason, gateSuccessor, by string cmd := &cobra.Command{ Use: "set ", Short: fmt.Sprintf("Set a frontmatter field value on a %s", entityType), @@ -1018,6 +1018,19 @@ func createEntitySetCommand( key := args[1] value := args[2] + // --by names the actor that set the flag, and is meaningful only for + // the flag key; it is not a general-purpose actor field. The check + // runs here, before the dispatcher, because the JSON branch below + // swallows an error raised inside the callback. It is keyed on + // Changed("by"), not on the value, so the "unknown" default does not + // break every existing non-flag `goal set`. + if cmd.Flags().Changed("by") && key != "flag" { + return errors.Wrapf(ctx, validation.Error, + "--by is accepted only for the flag key; got --by with key %q. Use `vault-cli %s set %q flag true --by `", + key, entityType, entityName, + ) + } + vaults, err := getVaults(ctx, configLoader, vaultName) if err != nil { return errors.Wrap(ctx, err, "get vaults") @@ -1027,7 +1040,7 @@ func createEntitySetCommand( err = dispatcher.FirstSuccess(ctx, vaults, func(vault *config.Vault) error { storageConfig := storage.NewConfigFromVault(vault) setOp := newSetOp(storageConfig) - if err := setOp.Execute(ctx, vault.Path, entityName, key, value, reason, gateSuccessor); err != nil { + if err := setOp.Execute(ctx, vault.Path, entityName, key, value, reason, gateSuccessor, by); err != nil { return err } if OutputFormat(*outputFormat).IsJSON() { @@ -1056,6 +1069,7 @@ func createEntitySetCommand( if entityType == "goal" { cmd.Flags().StringVar(&reason, "reason", "", "Close-out reason (aborted_reason); required for aborted, optional for completed") cmd.Flags().StringVar(&gateSuccessor, "gate-successor", "", "Where any risk gate moves, or 'none' (gate_successor); required for aborted, optional for completed") + cmd.Flags().StringVar(&by, "by", "unknown", "Who is setting the flag; recorded as flag_set_by. Accepted only for the flag key") } return cmd } diff --git a/pkg/domain/goal_frontmatter.go b/pkg/domain/goal_frontmatter.go index e44d6f8..afd4bf9 100644 --- a/pkg/domain/goal_frontmatter.go +++ b/pkg/domain/goal_frontmatter.go @@ -344,6 +344,8 @@ func (f *GoalFrontmatter) SetField(ctx context.Context, key, value string) error return f.setDeferDateFromString(ctx, value) case "claude_session_id": f.SetClaudeSessionID(value) + case "flag": + return f.setFlagField(ctx, value) default: f.Set(key, value) } @@ -412,7 +414,50 @@ func (f *GoalFrontmatter) setDeferDateFromString(ctx context.Context, value stri return nil } +// setFlagField parses a boolean string and stores the flag, or clears on empty. +// Accepted values match GetBool's coercion: "true"/"yes" and "false"/"no", +// case-insensitive with surrounding whitespace trimmed. The canonical form +// stored is a real YAML bool (true or false). +func (f *GoalFrontmatter) setFlagField(ctx context.Context, value string) error { + if value == "" { + f.ClearFlag() + return nil + } + switch strings.ToLower(strings.TrimSpace(value)) { + case "true", "yes": + return f.SetFlag(ctx, true) + case "false", "no": + return f.SetFlag(ctx, false) + default: + return errors.Wrapf(ctx, validation.Error, "invalid flag value '%s' (accepted values: true/yes/false/no)", value) + } +} + +// SetFlag stores the flag in the map as a real bool. A bool has no invalid +// state, so this setter mirrors TaskFrontmatter.SetFlag: it always returns nil +// and validation happens at the string boundary in setFlagField. The parameter +// is named `_` because the unparam linter rejects an unused named parameter. +func (f *GoalFrontmatter) SetFlag(_ context.Context, v bool) error { + f.Set("flag", v) + return nil +} + +// ClearFlag removes the flag key entirely, so the goal reads back as un-flagged +// and the key is never emitted on the next write. The two provenance keys are +// removed with it: a cleared flag has no writer to attribute, and leaving +// flag_set_by behind would make the next reader attribute a stale actor to a +// flag that is no longer set. +func (f *GoalFrontmatter) ClearFlag() { + f.Delete("flag") + f.Delete("flag_set_by") + f.Delete("flag_set_at") +} + // ClearField removes a frontmatter field by key. func (f *GoalFrontmatter) ClearField(key string) { f.Delete(key) + if key == "flag" { + f.Delete("flag_set_by") + f.Delete("flag_set_at") + } } diff --git a/pkg/ops/blocked_by_set_test.go b/pkg/ops/blocked_by_set_test.go index 6cd29e2..e0ca5b2 100644 --- a/pkg/ops/blocked_by_set_test.go +++ b/pkg/ops/blocked_by_set_test.go @@ -133,7 +133,7 @@ var _ = Describe("goal set refusal for blocked_by", func() { }) setValue := func(k, v string) { - err = setOp.Execute(ctx, "/vault", "Beta", k, v, "", "") + err = setOp.Execute(ctx, "/vault", "Beta", k, v, "", "", "") } It("refuses a non-empty blocked_by and writes nothing", func() { diff --git a/pkg/ops/frontmatter.go b/pkg/ops/frontmatter.go index cca363d..4938916 100644 --- a/pkg/ops/frontmatter.go +++ b/pkg/ops/frontmatter.go @@ -119,7 +119,7 @@ func (o *frontmatterSetOperation) Execute( // Refuse a direct provenance write before anything is mutated — see // flagProvenanceSetRefusal. Nothing below runs on this path, so the task file // stays byte-identical. - if err := flagProvenanceSetRefusal(ctx, taskName, key); err != nil { + if err := flagProvenanceSetRefusal(ctx, "task", taskName, key); err != nil { return err } @@ -128,7 +128,10 @@ func (o *frontmatterSetOperation) Execute( // observe a flag without its writer. The refusal for a blank actor leaves the // file byte-identical because it runs before any mutation. if key == "flag" { - if err := o.writeFlagProvenance(ctx, task, taskName, value, actor); err != nil { + if err := writeFlagProvenance( + ctx, &task.FrontmatterMap, + value, actor, "task", taskName, o.currentDateTime, + ); err != nil { return err } } @@ -221,11 +224,12 @@ func writeTaskCloseOutFieldsIfCloseOut( } // writeFlagProvenance records who set the flag and when, on the same map the -// flag itself is written to — so the caller's single WriteTask persists the -// flag and its provenance together and no read can observe an unattributed -// flag. The value is normalised exactly as setFlagField normalises it -// (case-insensitive, surrounding whitespace trimmed), so `set flag TRUE` and -// `set flag yes` write provenance just as `set flag true` does. +// flag itself is written to — so the caller's single WriteTask / WriteGoal +// persists the flag and its provenance together and no read can observe an +// unattributed flag. The value is normalised exactly as setFlagField normalises +// it (case-insensitive, surrounding whitespace trimmed), so `set flag TRUE` and +// `set flag yes` write provenance just as `set flag true` does. entityType names +// the verb in the refusal message ("task" or "goal"). // // Three outcomes, mirroring the field contract: // - truthy: flag_set_by is the actor and flag_set_at is the injected instant, @@ -240,25 +244,26 @@ func writeTaskCloseOutFieldsIfCloseOut( // // A value outside those three sets is left alone; SetField reports it as an // invalid flag value and nothing is written. -func (o *frontmatterSetOperation) writeFlagProvenance( +func writeFlagProvenance( ctx context.Context, - task *domain.Task, - taskName, value, actor string, + frontmatter *domain.FrontmatterMap, + value, actor, entityType, entityName string, + currentDateTime libtime.CurrentDateTime, ) error { switch strings.ToLower(strings.TrimSpace(value)) { case "true", "yes": if actor == "" { return errors.Errorf( ctx, - "flag_set_by must not be empty: refusing to record a blank actor on task %q", - taskName, + "flag_set_by must not be empty: refusing to record a blank actor on %s %q", + entityType, entityName, ) } - task.Set("flag_set_by", actor) - task.Set("flag_set_at", o.currentDateTime.Now().Time()) + frontmatter.Set("flag_set_by", actor) + frontmatter.Set("flag_set_at", currentDateTime.Now().Time()) case "false", "no": - task.Delete("flag_set_by") - task.Delete("flag_set_at") + frontmatter.Delete("flag_set_by") + frontmatter.Delete("flag_set_at") } return nil } @@ -267,20 +272,20 @@ func (o *frontmatterSetOperation) writeFlagProvenance( // flag_set_by or flag_set_at directly, and nil for every other key. // // The two keys exist only as evidence of the write that set the flag: they are -// composed onto the same map, in the same WriteTask, as `flag` itself. A direct -// `task set flag_set_by ` would attach provenance to a flag that -// is already on disk, and the window between the two writes is exactly the +// composed onto the same map, in the same write, as `flag` itself. A direct +// ` set flag_set_by ` would attach provenance to a flag +// that is already on disk, and the window between the two writes is exactly the // unattributed-flag bypass the field exists to close. The refusal is absolute: // --force is scoped to the phase guard and does not bypass it, and nothing is // written on this path because the check runs before any mutation. -func flagProvenanceSetRefusal(ctx context.Context, taskName, key string) error { +func flagProvenanceSetRefusal(ctx context.Context, entityType, entityName, key string) error { if key != "flag_set_by" && key != "flag_set_at" { return nil } return errors.Errorf( ctx, - "refusing to set %q on %q: %s is written only by the same invocation that sets the flag; use `vault-cli task set %q flag true --by `", - key, taskName, key, taskName, + "refusing to set %q on %q: %s is written only by the same invocation that sets the flag; use `vault-cli %s set %q flag true --by `", + key, entityName, key, entityType, entityName, ) } diff --git a/pkg/ops/frontmatter_entity.go b/pkg/ops/frontmatter_entity.go index 349c24d..606a711 100644 --- a/pkg/ops/frontmatter_entity.go +++ b/pkg/ops/frontmatter_entity.go @@ -103,7 +103,7 @@ func NewTopicGetOperation(topicStorage storage.TopicStorage) EntityGetOperation // //counterfeiter:generate -o ../../mocks/entity-set-operation.go --fake-name EntitySetOperation . EntitySetOperation type EntitySetOperation interface { - Execute(ctx context.Context, vaultPath, entityName, key, value, reason, gateSuccessor string) error + Execute(ctx context.Context, vaultPath, entityName, key, value, reason, gateSuccessor, actor string) error } type goalSetOperation struct { @@ -114,7 +114,7 @@ type goalSetOperation struct { // Execute sets the value of a frontmatter field on the named goal. func (o *goalSetOperation) Execute( ctx context.Context, - vaultPath, entityName, key, value, reason, gateSuccessor string, + vaultPath, entityName, key, value, reason, gateSuccessor, actor string, ) error { goal, err := o.goalStorage.FindGoalByName(ctx, vaultPath, entityName) if err != nil { @@ -132,6 +132,13 @@ func (o *goalSetOperation) Execute( return err } + // Refuse a direct provenance write before anything is mutated — see + // flagProvenanceSetRefusal. Nothing below runs on this path, so the goal file + // stays byte-identical. + if err := flagProvenanceSetRefusal(ctx, "goal", entityName, key); err != nil { + return err + } + // Refuse a direct todo -> planning move before anything is mutated — see // goalTodoPlanningSetRefusal. Nothing below runs on this path, so the goal // file stays byte-identical. @@ -155,6 +162,19 @@ func (o *goalSetOperation) Execute( }) } + // Flag provenance is composed onto the same map as the flag itself, so the + // single WriteGoal below persists all three keys together and no reader can + // observe a flag without its writer. The refusal for a blank actor leaves the + // file byte-identical because it runs before any mutation. + if key == "flag" { + if err := writeFlagProvenance( + ctx, &goal.FrontmatterMap, + value, actor, "goal", entityName, o.currentDateTime, + ); err != nil { + return err + } + } + if err := goal.SetField(ctx, key, value); err != nil { if key == "status" && strings.Contains(err.Error(), "missing close-out field(s)") { err = errors.Errorf(ctx, @@ -254,7 +274,7 @@ type themeSetOperation struct { // Execute sets the value of a frontmatter field on the named theme. func (o *themeSetOperation) Execute( ctx context.Context, - vaultPath, entityName, key, value, reason, gateSuccessor string, + vaultPath, entityName, key, value, reason, gateSuccessor, _ string, ) error { theme, err := o.themeStorage.FindThemeByName(ctx, vaultPath, entityName) if err != nil { @@ -281,7 +301,7 @@ type objectiveSetOperation struct { // Execute sets the value of a frontmatter field on the named objective. func (o *objectiveSetOperation) Execute( ctx context.Context, - vaultPath, entityName, key, value, reason, gateSuccessor string, + vaultPath, entityName, key, value, reason, gateSuccessor, _ string, ) error { objective, err := o.objectiveStorage.FindObjectiveByName(ctx, vaultPath, entityName) if err != nil { @@ -308,7 +328,7 @@ type visionSetOperation struct { // Execute sets the value of a frontmatter field on the named vision. func (o *visionSetOperation) Execute( ctx context.Context, - vaultPath, entityName, key, value, reason, gateSuccessor string, + vaultPath, entityName, key, value, reason, gateSuccessor, _ string, ) error { vision, err := o.visionStorage.FindVisionByName(ctx, vaultPath, entityName) if err != nil { @@ -340,7 +360,7 @@ type topicSetOperation struct { // status, so neither is consulted here. func (o *topicSetOperation) Execute( ctx context.Context, - vaultPath, entityName, key, value, reason, gateSuccessor string, + vaultPath, entityName, key, value, reason, gateSuccessor, _ string, ) error { topic, err := o.topicStorage.FindTopicByName(ctx, vaultPath, entityName) if err != nil { diff --git a/pkg/ops/frontmatter_entity_session_takeover_test.go b/pkg/ops/frontmatter_entity_session_takeover_test.go index 6d57182..c7c3106 100644 --- a/pkg/ops/frontmatter_entity_session_takeover_test.go +++ b/pkg/ops/frontmatter_entity_session_takeover_test.go @@ -64,7 +64,7 @@ var _ = Describe("goal/topic set session take-over", func() { setOp = ops.NewGoalSetOperation(mockGoalStorage, pinned) seedGoal(map[string]any{"status": "active"}) bind = func(value string) error { - return setOp.Execute(ctx, vaultPath, "Alpha", "claude_session_id", value, "", "") + return setOp.Execute(ctx, vaultPath, "Alpha", "claude_session_id", value, "", "", "") } }) @@ -160,7 +160,7 @@ var _ = Describe("goal/topic set session take-over", func() { }) Expect( - setOp.Execute(ctx, vaultPath, "Alpha", "status", "active", "", ""), + setOp.Execute(ctx, vaultPath, "Alpha", "status", "active", "", "", ""), ).To(BeNil()) Expect(goal.ClaudeSessionID()).To(Equal(sessionA)) @@ -199,7 +199,7 @@ var _ = Describe("goal/topic set session take-over", func() { setOp = ops.NewTopicSetOperation(mockTopicStorage, pinned) seedTopic(map[string]any{"status": "active"}) bind = func(value string) error { - return setOp.Execute(ctx, vaultPath, "Alpha", "claude_session_id", value, "", "") + return setOp.Execute(ctx, vaultPath, "Alpha", "claude_session_id", value, "", "", "") } }) @@ -294,7 +294,7 @@ var _ = Describe("goal/topic set session take-over", func() { }) Expect( - setOp.Execute(ctx, vaultPath, "Alpha", "status", "active", "", ""), + setOp.Execute(ctx, vaultPath, "Alpha", "status", "active", "", "", ""), ).To(BeNil()) Expect(topic.GetField("claude_session_id")).To(Equal(sessionA)) @@ -345,7 +345,7 @@ body line cfg := &storage.Config{GoalsDir: "23 Goals"} Expect( ops.NewGoalSetOperation(storage.NewGoalStorage(cfg), pinned). - Execute(ctx, vaultPath, "Alpha", "claude_session_id", sessionB, "", ""), + Execute(ctx, vaultPath, "Alpha", "claude_session_id", sessionB, "", "", ""), ).To(Succeed()) raw, err := os.ReadFile(filepath.Join(goalsDir, "Alpha.md")) diff --git a/pkg/ops/frontmatter_entity_test.go b/pkg/ops/frontmatter_entity_test.go index 1fddc8b..c9579cf 100644 --- a/pkg/ops/frontmatter_entity_test.go +++ b/pkg/ops/frontmatter_entity_test.go @@ -7,15 +7,21 @@ package ops_test import ( "context" "errors" + "os" + "path/filepath" + "strings" "time" libtime "github.com/bborbe/time" + libtimetest "github.com/bborbe/time/test" . "github.com/onsi/ginkgo/v2" . "github.com/onsi/gomega" + "gopkg.in/yaml.v3" "github.com/bborbe/vault-cli/mocks" "github.com/bborbe/vault-cli/pkg/domain" "github.com/bborbe/vault-cli/pkg/ops" + "github.com/bborbe/vault-cli/pkg/storage" ) var _ = Describe("NewGoalGetOperation", func() { @@ -180,7 +186,7 @@ var _ = Describe("NewGoalSetOperation", func() { }) JustBeforeEach(func() { - err = setOp.Execute(ctx, vaultPath, goalName, key, value, reason, gateSuccessor) + err = setOp.Execute(ctx, vaultPath, goalName, key, value, reason, gateSuccessor, "") }) Context("setting a string field", func() { @@ -1329,7 +1335,7 @@ var _ = Describe("NewTopicSetOperation", func() { }) JustBeforeEach(func() { - err = setOp.Execute(ctx, vaultPath, topicName, key, value, "", "") + err = setOp.Execute(ctx, vaultPath, topicName, key, value, "", "", "") }) Context("setting a string field", func() { @@ -1958,3 +1964,137 @@ var _ = Describe("NewTopicShowOperation", func() { }) }) }) + +// The goal flag contract mirrors the task flag contract: the flag is stored as +// a real YAML boolean and its provenance is composed onto the same map and +// persisted by the operation's single WriteGoal, so the serialized file — not +// just the in-memory map — carries the unquoted boolean and the attribution. +var _ = Describe("NewGoalSetOperation flag provenance", func() { + var ( + ctx context.Context + err error + setOp ops.EntitySetOperation + clearOp ops.EntityClearOperation + pinned libtime.CurrentDateTime + vaultPath string + goalsDir string + goalPath string + ) + + const goalFixture = `--- +status: in_progress +page_type: goal +--- +body line +` + + BeforeEach(func() { + ctx = context.Background() + pinned = libtime.NewCurrentDateTime() + pinned.SetNow(libtimetest.ParseDateTime("2026-09-30T08:00:00Z")) + + vaultPath, err = os.MkdirTemp("", "vault-goal-flag-*") + Expect(err).NotTo(HaveOccurred()) + goalsDir = filepath.Join(vaultPath, "23 Goals") + Expect(os.MkdirAll(goalsDir, 0755)).To(Succeed()) + goalPath = filepath.Join(goalsDir, "Alpha.md") + Expect(os.WriteFile(goalPath, []byte(goalFixture), 0600)).To(Succeed()) + + cfg := &storage.Config{GoalsDir: "23 Goals"} + goalStore := storage.NewGoalStorage(cfg) + setOp = ops.NewGoalSetOperation(goalStore, pinned) + clearOp = ops.NewGoalClearOperation(goalStore) + }) + + AfterEach(func() { + if vaultPath != "" { + _ = os.RemoveAll(vaultPath) + } + }) + + read := func() string { + raw, readErr := os.ReadFile(goalPath) + Expect(readErr).NotTo(HaveOccurred()) + return string(raw) + } + + It("writes flag true as an unquoted boolean", func() { + Expect(setOp.Execute( + ctx, vaultPath, "Alpha", "flag", "true", "", "", "operator", + )).To(Succeed()) + + out := read() + Expect(out).To(ContainSubstring("flag: true")) + Expect(out).NotTo(ContainSubstring(`flag: "true"`)) + }) + + It("writes flag false as an unquoted boolean", func() { + Expect(setOp.Execute( + ctx, vaultPath, "Alpha", "flag", "false", "", "", "operator", + )).To(Succeed()) + + out := read() + Expect(out).To(ContainSubstring("flag: false")) + Expect(out).NotTo(ContainSubstring(`flag: "false"`)) + }) + + It("records the actor and a parseable instant in the same write", func() { + Expect(setOp.Execute( + ctx, vaultPath, "Alpha", "flag", "true", "", "", "operator", + )).To(Succeed()) + + out := read() + Expect(out).To(ContainSubstring("flag_set_by: operator")) + Expect(out).To(ContainSubstring("flag_set_at: 2026-09-30T08:00:00Z")) + Expect(out).NotTo(ContainSubstring(`flag_set_at: "2026-09-30T08:00:00Z"`)) + + var parsed map[string]any + Expect(yaml.Unmarshal([]byte(out), &parsed)).To(Succeed()) + _, ok := parsed["flag_set_at"].(time.Time) + Expect(ok).To(BeTrue()) + }) + + It("refuses a blank actor on a truthy flag and leaves the file byte-identical", func() { + before := read() + + err = setOp.Execute(ctx, vaultPath, "Alpha", "flag", "true", "", "", "") + + Expect(err).To(HaveOccurred()) + Expect(err.Error()).To(ContainSubstring("flag_set_by")) + Expect(read()).To(Equal(before)) + }) + + It("refuses a direct provenance write and names the goal verb", func() { + before := read() + + err = setOp.Execute(ctx, vaultPath, "Alpha", "flag_set_by", "someone", "", "", "operator") + + Expect(err).To(HaveOccurred()) + Expect(err.Error()).To(ContainSubstring("goal set")) + Expect(read()).To(Equal(before)) + }) + + It("removes the flag and both provenance keys on clear", func() { + Expect(setOp.Execute( + ctx, vaultPath, "Alpha", "flag", "true", "", "", "operator", + )).To(Succeed()) + Expect(read()).To(ContainSubstring("flag_set_by: operator")) + + Expect(clearOp.Execute(ctx, vaultPath, "Alpha", "flag")).To(Succeed()) + + out := read() + Expect(out).NotTo(ContainSubstring("flag:")) + Expect(out).NotTo(ContainSubstring("flag_set_by")) + Expect(out).NotTo(ContainSubstring("flag_set_at")) + }) + + It("round-trips a non-boolean goal field unchanged", func() { + Expect(setOp.Execute( + ctx, vaultPath, "Alpha", "phase", "execution", "", "", "", + )).To(Succeed()) + + out := read() + Expect(out).To(ContainSubstring("phase: execution")) + Expect(strings.Count(out, "phase:")).To(Equal(1)) + }) +}) diff --git a/pkg/ops/wikilink_roundtrip_test.go b/pkg/ops/wikilink_roundtrip_test.go index b684ff3..3c100de 100644 --- a/pkg/ops/wikilink_roundtrip_test.go +++ b/pkg/ops/wikilink_roundtrip_test.go @@ -127,25 +127,25 @@ body return ops.NewGoalSetOperation( storage.NewGoalStorage(cfg), libtime.NewCurrentDateTime(), - ).Execute(ctx, vaultPath, name, key, value, "", "") + ).Execute(ctx, vaultPath, name, key, value, "", "", "") }), Entry("theme", "21 Themes", func( ctx context.Context, cfg *storage.Config, vaultPath, name, key, value string, ) error { return ops.NewThemeSetOperation(storage.NewThemeStorage(cfg)). - Execute(ctx, vaultPath, name, key, value, "", "") + Execute(ctx, vaultPath, name, key, value, "", "", "") }), Entry("objective", "22 Objectives", func( ctx context.Context, cfg *storage.Config, vaultPath, name, key, value string, ) error { return ops.NewObjectiveSetOperation(storage.NewObjectiveStorage(cfg)). - Execute(ctx, vaultPath, name, key, value, "", "") + Execute(ctx, vaultPath, name, key, value, "", "", "") }), Entry("vision", "20 Vision", func( ctx context.Context, cfg *storage.Config, vaultPath, name, key, value string, ) error { return ops.NewVisionSetOperation(storage.NewVisionStorage(cfg)). - Execute(ctx, vaultPath, name, key, value, "", "") + Execute(ctx, vaultPath, name, key, value, "", "", "") }), ) diff --git a/prompts/in-progress/282-goal-set-flag-boolean-provenance.md b/prompts/completed/282-goal-set-flag-boolean-provenance.md similarity index 96% rename from prompts/in-progress/282-goal-set-flag-boolean-provenance.md rename to prompts/completed/282-goal-set-flag-boolean-provenance.md index 410b38c..9415719 100644 --- a/prompts/in-progress/282-goal-set-flag-boolean-provenance.md +++ b/prompts/completed/282-goal-set-flag-boolean-provenance.md @@ -1,7 +1,12 @@ --- -status: approved +status: completed +summary: Goal flag writes now store an unquoted YAML boolean and record flag_set_by/flag_set_at in the same write via goal set --by, matching task set +execution_id: vault-cli-goal-flag-exec-282-goal-set-flag-boolean-provenance +dark-factory-version: v0.199.1 created: "2026-11-16T22:40:00Z" queued: "2026-11-16T23:52:09Z" +started: "2026-11-17T02:32:59Z" +completed: "2026-11-17T02:38:55Z" --- # Write goal flags as booleans and record their provenance