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

- 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`
Expand Down
4 changes: 4 additions & 0 deletions docs/goal-writing.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 "<name>" flag true --by <actor>` — 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 "<name>" 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.
Expand Down
27 changes: 27 additions & 0 deletions integration/cli_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
18 changes: 10 additions & 8 deletions mocks/entity-set-operation.go

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

18 changes: 16 additions & 2 deletions pkg/cli/cli.go
Original file line number Diff line number Diff line change
Expand Up @@ -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 <name> <key> <value>",
Short: fmt.Sprintf("Set a frontmatter field value on a %s", entityType),
Expand All @@ -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 <actor>`",
key, entityType, entityName,
)
}

vaults, err := getVaults(ctx, configLoader, vaultName)
if err != nil {
return errors.Wrap(ctx, err, "get vaults")
Expand All @@ -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() {
Expand Down Expand Up @@ -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
}
Expand Down
45 changes: 45 additions & 0 deletions pkg/domain/goal_frontmatter.go
Original file line number Diff line number Diff line change
Expand Up @@ -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)
}
Expand Down Expand Up @@ -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")
}
}
2 changes: 1 addition & 1 deletion pkg/ops/blocked_by_set_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -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() {
Expand Down
49 changes: 27 additions & 22 deletions pkg/ops/frontmatter.go
Original file line number Diff line number Diff line change
Expand Up @@ -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
}

Expand All @@ -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
}
}
Expand Down Expand Up @@ -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,
Expand All @@ -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
}
Expand All @@ -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 <name> flag_set_by <actor>` 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
// `<entity> set <name> flag_set_by <actor>` 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 <actor>`",
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 <actor>`",
key, entityName, key, entityType, entityName,
)
}

Expand Down
Loading
Loading