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
3 changes: 3 additions & 0 deletions .gitattributes
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
* text=auto eol=lf

*.gif binary
5 changes: 5 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

## [Unreleased]

### Added

- **Goal postponement**: Added `jumbo goal postpone --id <goalId>` to move a defined goal to `postponed`. Postponed goals remain visible in CLI and TUI goal views but are excluded from automatic work selection.
- **Goal reinstatement**: Added `jumbo goal reinstate --id <goalId>` to return a postponed goal to `defined` status and make it eligible for refinement again.

### Fixed

- **Adding relations after removal**: Adding the same connection again creates a new relation with the supplied guidance while preserving the removed relation and its event history.
Expand Down
18 changes: 17 additions & 1 deletion docs/guides/goal-management.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,22 @@ Keep goals small and focused. Keep objectives specific — "Implement JWT auth"

See [goal add reference](../reference/commands/goal.md) for the full list of options.

### Postponing defined goals

Postpone defined work that should remain recorded but should not be selected by automatic work streams:

```bash
jumbo goal postpone --id goal_abc123
```

The goal remains visible in CLI lists and the TUI under the `postponed` status. When the work becomes relevant again, return it to `defined` status and renewed refinement eligibility:

```bash
jumbo goal reinstate --id goal_abc123
```

Only postponed goals can be reinstated. Automatic refinement continues to exclude postponed goals until this explicit transition occurs.

### Prerequisite goals

Goals can declare prerequisites that must be completed before they can start:
Expand Down Expand Up @@ -189,7 +205,7 @@ jumbo goals list --status doing
jumbo goals list --status doing,blocked
```

Valid status filters: `defined`, `doing`, `blocked`, `paused`, `refined`, `in-refinement`, `in-review`, `approved`, `done`.
Valid status filters: `defined`, `postponed`, `doing`, `blocked`, `paused`, `refined`, `in-refinement`, `in-review`, `approved`, `done`.

---

Expand Down
54 changes: 54 additions & 0 deletions docs/reference/commands/goal.md
Original file line number Diff line number Diff line change
Expand Up @@ -80,6 +80,60 @@ Start refinement of a goal — displays details and transitions to `in-refinemen

---

## jumbo goal postpone

Postpone a defined goal so it remains visible without entering automatic work-selection streams. This transitions the goal from `defined` to `postponed`.

### Synopsis

```bash
> jumbo goal postpone --id <goalId>
```

### Options

| Option | Description |
|--------|-------------|
| `-i, --id <goalId>` | ID of the defined goal to postpone (required) |

### Examples

```bash
> jumbo goal postpone --id goal_abc123
```

:::note
Postponed goals remain available in goal lists and TUI filters. Use `jumbo goal reinstate` when the work should become eligible for refinement again.
:::

---

## jumbo goal reinstate

Return a postponed goal to `defined` status so it becomes eligible for refinement again.

### Synopsis

```bash
> jumbo goal reinstate --id <goalId>
```

### Options

| Option | Description |
|--------|-------------|
| `-i, --id <goalId>` | ID of the postponed goal to reinstate (required) |

### Examples

```bash
> jumbo goal reinstate --id goal_abc123
```

Only postponed goals can be reinstated. Other source statuses are rejected without changing the goal.

---

## jumbo goal commit

Commit a goal after refinement is complete — transitions from `in-refinement` to `refined`.
Expand Down
2 changes: 1 addition & 1 deletion docs/reference/commands/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ Complete reference for all Jumbo CLI commands.
|---------------|-------------|
| [Search Command](search.md) | search |
| [Index Commands](search-index.md) | rebuild |
| [Goal Commands](goal.md) | add, refine, commit, start, pause, resume, block, unblock, submit, review, approve, reject, codify, close, qualify, reset, update, update-progress, show, remove, list |
| [Goal Commands](goal.md) | add, refine, postpone, reinstate, commit, start, pause, resume, block, unblock, submit, review, approve, reject, codify, close, qualify, reset, update, update-progress, show, remove, list |
| [Session Commands](session.md) | start, end, list, compact |
| [Project Commands](project.md) | init, update |
| [Architecture Commands](architecture.md) | define, update, view |
Expand Down
5 changes: 5 additions & 0 deletions src/application/context/goals/get/IGetGoalViewReader.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
import { GoalView } from "../GoalView.js";

export interface IGetGoalViewReader {
findById(goalId: string): Promise<GoalView | null>;
}
1 change: 1 addition & 0 deletions src/application/context/goals/get/LocalGetGoalsGateway.ts
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@ const VALID_STATUSES: readonly string[] = Object.values(GoalStatus);

const DEFAULT_STATUSES: readonly GoalStatusType[] = [
GoalStatus.TODO,
GoalStatus.POSTPONED,
GoalStatus.REFINED,
GoalStatus.DOING,
GoalStatus.BLOCKED,
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
import { BaseEvent } from "../../../../domain/BaseEvent.js";
import { GoalPostponedEvent } from "../../../../domain/goals/postpone/GoalPostponedEvent.js";
import { IEventHandler } from "../../../messaging/IEventHandler.js";
import { IGoalPostponedProjector } from "./IGoalPostponedProjector.js";

export class GoalPostponedEventHandler implements IEventHandler {
constructor(private readonly projector: IGoalPostponedProjector) {}

async handle(event: BaseEvent): Promise<void> {
await this.projector.applyGoalPostponed(event as GoalPostponedEvent);
}
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
import { GoalEvent } from "../../../../domain/goals/EventIndex.js";

export interface IGoalPostponedEventReader {
readStream(streamId: string): Promise<GoalEvent[]>;
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
import { BaseEvent } from "../../../../domain/BaseEvent.js";
import { AppendResult } from "../../../persistence/IEventStore.js";

export interface IGoalPostponedEventWriter {
append(event: BaseEvent): Promise<AppendResult>;
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
import { GoalPostponedEvent } from "../../../../domain/goals/postpone/GoalPostponedEvent.js";

export interface IGoalPostponedProjector {
applyGoalPostponed(event: GoalPostponedEvent): Promise<void>;
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
import { PostponeGoalRequest } from "./PostponeGoalRequest.js";
import { PostponeGoalResponse } from "./PostponeGoalResponse.js";

export interface IPostponeGoalGateway {
postponeGoal(request: PostponeGoalRequest): Promise<PostponeGoalResponse>;
}
14 changes: 14 additions & 0 deletions src/application/context/goals/postpone/LocalPostponeGoalGateway.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
import { GoalStatus } from "../../../../domain/goals/Constants.js";
import { IPostponeGoalGateway } from "./IPostponeGoalGateway.js";
import { PostponeGoalCommandHandler } from "./PostponeGoalCommandHandler.js";
import { PostponeGoalRequest } from "./PostponeGoalRequest.js";
import { PostponeGoalResponse } from "./PostponeGoalResponse.js";

export class LocalPostponeGoalGateway implements IPostponeGoalGateway {
constructor(private readonly commandHandler: PostponeGoalCommandHandler) {}

async postponeGoal(request: PostponeGoalRequest): Promise<PostponeGoalResponse> {
await this.commandHandler.execute({ goalId: request.goalId });
return { status: GoalStatus.POSTPONED };
}
}
4 changes: 4 additions & 0 deletions src/application/context/goals/postpone/PostponeGoalCommand.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
/** Command that transitions a goal from defined to postponed. */
export interface PostponeGoalCommand {
readonly goalId: string;
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
import { Goal } from "../../../../domain/goals/Goal.js";
import { GoalErrorMessages, formatErrorMessage } from "../../../../domain/goals/Constants.js";
import { IEventBus } from "../../../messaging/IEventBus.js";
import { IGetGoalViewReader } from "../get/IGetGoalViewReader.js";
import { IGoalPostponedEventReader } from "./IGoalPostponedEventReader.js";
import { IGoalPostponedEventWriter } from "./IGoalPostponedEventWriter.js";
import { PostponeGoalCommand } from "./PostponeGoalCommand.js";

export class PostponeGoalCommandHandler {
constructor(
private readonly eventWriter: IGoalPostponedEventWriter,
private readonly eventReader: IGoalPostponedEventReader,
private readonly goalReader: IGetGoalViewReader,
private readonly eventBus: IEventBus
) {}

async execute(command: PostponeGoalCommand): Promise<{ status: string }> {
const view = await this.goalReader.findById(command.goalId);
if (!view) {
throw new Error(
formatErrorMessage(GoalErrorMessages.GOAL_NOT_FOUND, { id: command.goalId })
);
}

const history = await this.eventReader.readStream(command.goalId);
const goal = Goal.rehydrate(command.goalId, history);
const event = goal.postpone();

await this.eventWriter.append(event);
await this.eventBus.publish(event);

return { status: event.payload.status };
}
}
11 changes: 11 additions & 0 deletions src/application/context/goals/postpone/PostponeGoalController.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
import { IPostponeGoalGateway } from "./IPostponeGoalGateway.js";
import { PostponeGoalRequest } from "./PostponeGoalRequest.js";
import { PostponeGoalResponse } from "./PostponeGoalResponse.js";

export class PostponeGoalController {
constructor(private readonly gateway: IPostponeGoalGateway) {}

async handle(request: PostponeGoalRequest): Promise<PostponeGoalResponse> {
return this.gateway.postponeGoal(request);
}
}
4 changes: 4 additions & 0 deletions src/application/context/goals/postpone/PostponeGoalRequest.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
/** Request model for postponing a defined goal. */
export interface PostponeGoalRequest {
readonly goalId: string;
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
/** Minimal result returned after a goal is postponed. */
export interface PostponeGoalResponse {
readonly status: string;
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
import { BaseEvent } from "../../../../domain/BaseEvent.js";
import { GoalReinstatedEvent } from "../../../../domain/goals/reinstate/GoalReinstatedEvent.js";
import { IEventHandler } from "../../../messaging/IEventHandler.js";
import { IGoalReinstatedProjector } from "./IGoalReinstatedProjector.js";

export class GoalReinstatedEventHandler implements IEventHandler {
constructor(private readonly projector: IGoalReinstatedProjector) {}

async handle(event: BaseEvent): Promise<void> {
await this.projector.applyGoalReinstated(event as GoalReinstatedEvent);
}
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
import { GoalEvent } from "../../../../domain/goals/EventIndex.js";

export interface IGoalReinstatedEventReader {
readStream(streamId: string): Promise<GoalEvent[]>;
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
import { BaseEvent } from "../../../../domain/BaseEvent.js";
import { AppendResult } from "../../../persistence/IEventStore.js";

export interface IGoalReinstatedEventWriter {
append(event: BaseEvent): Promise<AppendResult>;
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
import { GoalReinstatedEvent } from "../../../../domain/goals/reinstate/GoalReinstatedEvent.js";

export interface IGoalReinstatedProjector {
applyGoalReinstated(event: GoalReinstatedEvent): Promise<void>;
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
import { ReinstateGoalRequest } from "./ReinstateGoalRequest.js";
import { ReinstateGoalResponse } from "./ReinstateGoalResponse.js";

export interface IReinstateGoalGateway {
reinstateGoal(request: ReinstateGoalRequest): Promise<ReinstateGoalResponse>;
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
import { GoalStatus } from "../../../../domain/goals/Constants.js";
import { IReinstateGoalGateway } from "./IReinstateGoalGateway.js";
import { ReinstateGoalCommandHandler } from "./ReinstateGoalCommandHandler.js";
import { ReinstateGoalRequest } from "./ReinstateGoalRequest.js";
import { ReinstateGoalResponse } from "./ReinstateGoalResponse.js";

export class LocalReinstateGoalGateway implements IReinstateGoalGateway {
constructor(private readonly commandHandler: ReinstateGoalCommandHandler) {}

async reinstateGoal(request: ReinstateGoalRequest): Promise<ReinstateGoalResponse> {
await this.commandHandler.execute({ goalId: request.goalId });
return { status: GoalStatus.TODO };
}
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
/** Command that transitions a goal from postponed to defined. */
export interface ReinstateGoalCommand {
readonly goalId: string;
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
import { Goal } from "../../../../domain/goals/Goal.js";
import { GoalErrorMessages, formatErrorMessage } from "../../../../domain/goals/Constants.js";
import { IEventBus } from "../../../messaging/IEventBus.js";
import { IGetGoalViewReader } from "../get/IGetGoalViewReader.js";
import { IGoalReinstatedEventReader } from "./IGoalReinstatedEventReader.js";
import { IGoalReinstatedEventWriter } from "./IGoalReinstatedEventWriter.js";
import { ReinstateGoalCommand } from "./ReinstateGoalCommand.js";

export class ReinstateGoalCommandHandler {
constructor(
private readonly eventWriter: IGoalReinstatedEventWriter,
private readonly eventReader: IGoalReinstatedEventReader,
private readonly goalReader: IGetGoalViewReader,
private readonly eventBus: IEventBus
) {}

async execute(command: ReinstateGoalCommand): Promise<{ status: string }> {
const view = await this.goalReader.findById(command.goalId);
if (!view) {
throw new Error(
formatErrorMessage(GoalErrorMessages.GOAL_NOT_FOUND, { id: command.goalId })
);
}

const history = await this.eventReader.readStream(command.goalId);
const goal = Goal.rehydrate(command.goalId, history);
const event = goal.reinstate();

await this.eventWriter.append(event);
await this.eventBus.publish(event);

return { status: event.payload.status };
}
}
11 changes: 11 additions & 0 deletions src/application/context/goals/reinstate/ReinstateGoalController.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
import { IReinstateGoalGateway } from "./IReinstateGoalGateway.js";
import { ReinstateGoalRequest } from "./ReinstateGoalRequest.js";
import { ReinstateGoalResponse } from "./ReinstateGoalResponse.js";

export class ReinstateGoalController {
constructor(private readonly gateway: IReinstateGoalGateway) {}

async handle(request: ReinstateGoalRequest): Promise<ReinstateGoalResponse> {
return this.gateway.reinstateGoal(request);
}
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
/** Request model for reinstating a postponed goal. */
export interface ReinstateGoalRequest {
readonly goalId: string;
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
/** Minimal result returned after a goal is reinstated. */
export interface ReinstateGoalResponse {
readonly status: string;
}
Loading
Loading