@we-scrum/cli 6.9.2 → 6.9.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@we-scrum/cli",
-  "version": "6.9.2",
+  "version": "6.9.3",
   "description": "Cli tool for we-scrum application",
   "main": "dist/cli.js",
   "bin": {
@@ -37,12 +37,12 @@
     "@types/node": "^24.13.3",
     "tsup": "^8.5.1",
     "typescript": "^6.0.3",
+    "@my-devkit/cli": "2.1.0",
+    "@we-scrum/enums": "1.0.0",
     "@we-scrum/commands": "1.0.0",
     "@we-scrum/models": "1.0.0",
     "@my-devkit/core": "1.0.0",
-    "@we-scrum/utils": "1.0.0",
-    "@we-scrum/enums": "1.0.0",
-    "@my-devkit/cli": "2.1.0"
+    "@we-scrum/utils": "1.0.0"
   },
   "scripts": {
     "start": "node dist/cli.js",

package/src/cli.ts

@@ -4,6 +4,7 @@ import { Command } from 'commander';
 import { version } from '../package.json';
 import {
     registerAuthCommands,
+    registerChangeThreadCommands,
     registerIterationCommands,
     registerPolicyCommands,
     registerProjectCommands,
@@ -23,5 +24,6 @@ registerStoryCommands(program);
 registerTaskCommands(program);
 registerPolicyCommands(program);
 registerIterationCommands(program);
+registerChangeThreadCommands(program);
 
 program.parse(process.argv);

package/src/commands/change-thread.ts

@@ -0,0 +1,53 @@
+import { WeScrumHelper } from '@helpers';
+import { Logger } from '@my-devkit/core';
+import { runProjectCommand } from '@utils';
+import { ChangeThreadStatus } from '@we-scrum/enums';
+import { Command, Option } from 'commander';
+
+export function registerChangeThreadCommands(program: Command): void {
+    program
+        .command('get-change-threads')
+        .description('Get the open change threads for a change')
+        .requiredOption('-c, --changeId <id>', 'Unique identifier of the change')
+        .action(
+            runProjectCommand<{ changeId: string }>(async (options) => {
+                return WeScrumHelper.getOpenChangeThreads(options.changeId);
+            }),
+        );
+
+    program
+        .command('create-change-thread')
+        .description('Open a new change thread with a first comment')
+        .requiredOption('-c, --changeId <id>', 'Unique identifier of the change')
+        .requiredOption('-m, --comment <comment>', 'Comment body (markdown supported)')
+        .action(
+            runProjectCommand<{ changeId: string; comment: string }>(async (options) => {
+                const changeThreadId = await WeScrumHelper.createChangeThread(options.changeId, options.comment);
+                Logger.info(`Change thread "${changeThreadId}" created successfully.`);
+            }),
+        );
+
+    program
+        .command('update-change-thread-status')
+        .description('Update the status of a change thread')
+        .requiredOption('-t, --changeThreadId <id>', 'Unique identifier of the change thread')
+        .addOption(new Option('-s, --status <status>', 'New status').choices(ChangeThreadStatus.helper.members).makeOptionMandatory())
+        .action(
+            runProjectCommand<{ changeThreadId: string; status: ChangeThreadStatus }>(async (options) => {
+                await WeScrumHelper.updateChangeThreadStatus(options.changeThreadId, options.status);
+                Logger.info('Change thread status updated successfully.');
+            }),
+        );
+
+    program
+        .command('add-comment-to-change-thread')
+        .description('Reply to an existing change thread')
+        .requiredOption('-t, --changeThreadId <id>', 'Unique identifier of the change thread')
+        .requiredOption('-m, --comment <comment>', 'Comment body (markdown supported)')
+        .action(
+            runProjectCommand<{ changeThreadId: string; comment: string }>(async (options) => {
+                await WeScrumHelper.addCommentToChangeThread(options.changeThreadId, options.comment);
+                Logger.info('Comment added successfully.');
+            }),
+        );
+}

package/src/commands/index.ts

@@ -1,4 +1,5 @@
 export * from './auth';
+export * from './change-thread';
 export * from './iteration';
 export * from './policy';
 export * from './project';

package/src/commands/task.ts

@@ -8,10 +8,10 @@ export function registerTaskCommands(program: Command): void {
         .command('start-task')
         .description('Mark a specific task as in progress')
         .requiredOption('-i, --identificationNumber <id>', 'Story identification number')
-        .requiredOption('-t, --taskId <id>', 'Unique identifier of the change to act on')
+        .requiredOption('-c, --changeId <id>', 'Unique identifier of the change to act on')
         .action(
-            runProjectCommand<{ identificationNumber: string; taskId: string }>(async (options) => {
-                await WeScrumHelper.startTask(options.identificationNumber, options.taskId);
+            runProjectCommand<{ identificationNumber: string; changeId: string }>(async (options) => {
+                await WeScrumHelper.startTask(options.identificationNumber, options.changeId);
                 Logger.info('Task started successfully. You can now make changes to the codebase.');
             }),
         );
@@ -20,10 +20,10 @@ export function registerTaskCommands(program: Command): void {
         .command('complete-task')
         .description('Mark the current in-progress task as done')
         .requiredOption('-i, --identificationNumber <id>', 'Story identification number')
-        .requiredOption('-t, --taskId <id>', 'Unique identifier of the change to act on')
+        .requiredOption('-c, --changeId <id>', 'Unique identifier of the change to act on')
         .action(
-            runProjectCommand<{ identificationNumber: string; taskId: string }>(async (options) => {
-                await WeScrumHelper.completeTask(options.identificationNumber, options.taskId);
+            runProjectCommand<{ identificationNumber: string; changeId: string }>(async (options) => {
+                await WeScrumHelper.completeTask(options.identificationNumber, options.changeId);
                 Logger.info('Task completed successfully.');
             }),
         );

package/src/helpers/we-scrum.helper.ts

@@ -1,5 +1,7 @@
-import { _sortBy, assert, Command, serialize, TypeHelper } from '@my-devkit/core';
+import { _sortBy, assert, Command, ContributionOrigin, serialize, TypeHelper } from '@my-devkit/core';
 import {
+    AddCommentToChangeThreadCommand,
+    CreateChangeThreadCommand,
     MarkEnumerationChangeAsDoneCommand,
     MarkObjectChangeAsDoneCommand,
     MarkRelationChangeAsDoneCommand,
@@ -11,11 +13,13 @@ import {
     TakeRelationChangeCommand,
     TakeRouteChangeCommand,
     TakeTaskCommand,
+    UpdateChangeThreadStatusCommand,
     UpdateIterationCommand,
 } from '@we-scrum/commands';
-import { ContentType, ProgressStatus } from '@we-scrum/enums';
+import { ChangeThreadStatus, ContentType, ProgressStatus } from '@we-scrum/enums';
 import {
     DevelopmentPolicyModel,
+    ProjectChangeThreadModel,
     ProjectIterationModel,
     ProjectStoryModel,
     ProjectStorySectionModel,
@@ -63,6 +67,8 @@ export class WeScrumHelper {
             });
         }
 
+        this.appendOpenThreadsHint(nextChange);
+
         const analysisChange = StorySectionHelper.mapSingleChange(nextChange);
         const isTodo = nextChange.progress.status === ProgressStatus.ToDo;
         const developmentPolicy = await this.getChangeDevelopmentPolicy(nextChange);
@@ -74,7 +80,7 @@ export class WeScrumHelper {
             unitTestsPath: developmentPolicy?.areUnitTestsMandatory ? unitTestsPath : null,
             isTodo,
             identificationNumber,
-            taskId: analysisChange.id,
+            changeId: analysisChange.id,
         });
     }
 
@@ -85,11 +91,7 @@ export class WeScrumHelper {
 
         const sections = await this.getStorySections(story.storyId);
 
-        const task = _sortBy(sections, (s) => s.name)
-            .flatMap((s) => [...s.enumerationChanges, ...s.objectChanges, ...s.routeChanges, ...s.relationChanges, ...s.tasks])
-            .find((t) => t.progress?.status !== ProgressStatus.Done);
-
-        return task;
+        return this.getAllChanges(sections).find((t) => t.progress?.status !== ProgressStatus.Done);
     }
 
     public static async getChangeById(identificationNumber: string, changeId: string) {
@@ -98,23 +100,14 @@ export class WeScrumHelper {
 
         const sections = await this.getStorySections(story.storyId);
 
-        const change = _sortBy(sections, (s) => s.name)
-            .flatMap((s) => [...s.enumerationChanges, ...s.objectChanges, ...s.routeChanges, ...s.relationChanges, ...s.tasks])
-            .find((t) => {
-                if (t instanceof ProjectStorySectionModelEnumerationChange) return t.enumerationChangeId === changeId;
-                if (t instanceof ProjectStorySectionModelObjectChange) return t.objectChangeId === changeId;
-                if (t instanceof ProjectStorySectionModelRouteChange) return t.routeChangeId === changeId;
-                if (t instanceof ProjectStorySectionModelRelationChange) return t.relationChangeId === changeId;
-                if (t instanceof ProjectStorySectionModelTask) return t.taskId === changeId;
-                return false;
-            });
+        const change = this.getAllChanges(sections).find((t) => this.getChangeIdentifier(t) === changeId);
 
         assert(!!change, `Change "${changeId}" not found in story "${identificationNumber}".`);
         return change;
     }
 
-    public static async startTask(identificationNumber: string, taskId: string): Promise<void> {
-        const change = await this.getChangeById(identificationNumber, taskId);
+    public static async startTask(identificationNumber: string, changeId: string): Promise<void> {
+        const change = await this.getChangeById(identificationNumber, changeId);
 
         assert(change.progress.status === ProgressStatus.ToDo, `Task is not in ToDo status (current status: ${change.progress.status}).`);
 
@@ -143,8 +136,8 @@ export class WeScrumHelper {
         }
     }
 
-    public static async completeTask(identificationNumber: string, taskId: string): Promise<void> {
-        const change = await this.getChangeById(identificationNumber, taskId);
+    public static async completeTask(identificationNumber: string, changeId: string): Promise<void> {
+        const change = await this.getChangeById(identificationNumber, changeId);
 
         assert(change.progress.status === ProgressStatus.Doing, `Task is not in progress (current status: ${change.progress.status}).`);
 
@@ -237,11 +230,87 @@ export class WeScrumHelper {
         assert(!!story, `Story "${identificationNumber}" not found in the active project.`);
 
         const sections = await this.getStorySections(story.storyId);
+        this.getAllChanges(sections).forEach((change) => this.appendOpenThreadsHint(change));
+
         const ast = StorySectionHelper.mapSectionsToAnalysisAst(sections);
 
         return AnalysisDsl.stringify(ast);
     }
 
+    public static async getOpenChangeThreads(changeId: string): Promise<string> {
+        const threads = await FirebaseHelper.getCollection<ProjectChangeThreadModel>(`/projects/${this.projectId}/change-threads`, {
+            where: [
+                ['changeId', '==', changeId],
+                ['status', '==', ChangeThreadStatus.Open],
+            ],
+        });
+
+        if (threads.length === 0) {
+            return `No open threads for change "${changeId}".`;
+        }
+
+        return threads.map((thread) => this.formatChangeThread(thread)).join('\n\n---\n\n');
+    }
+
+    public static async createChangeThread(changeId: string, comment: string): Promise<string> {
+        return this.post(
+            'project-management/create-change-thread',
+            TypeHelper.transform(CreateChangeThreadCommand, { changeId, commentBody: comment }),
+        );
+    }
+
+    public static async addCommentToChangeThread(changeThreadId: string, comment: string): Promise<void> {
+        await this.post(
+            'project-management/add-comment-to-change-thread',
+            TypeHelper.transform(AddCommentToChangeThreadCommand, { changeThreadId, commentBody: comment }),
+        );
+    }
+
+    public static async updateChangeThreadStatus(changeThreadId: string, status: ChangeThreadStatus): Promise<void> {
+        await this.post(
+            'project-management/update-change-thread-status',
+            TypeHelper.transform(UpdateChangeThreadStatusCommand, { changeThreadId, status }),
+        );
+    }
+
+    private static formatChangeThread(thread: ProjectChangeThreadModel): string {
+        const comments = thread.comments
+            .map((comment) => {
+                const author = comment.contributionOrigin === ContributionOrigin.Cli ? 'Claude Code' : comment.createdByUserFullName;
+                return `**${author}** (${comment.createdAt.toISOString()}):\n${comment.body}`;
+            })
+            .join('\n\n');
+
+        return `## Thread ${thread.changeThreadId} (${thread.status})\n\n${comments}`;
+    }
+
+    private static getAllChanges(sections: ProjectStorySectionModel[]): DevelopmentPolicyHelper.Change[] {
+        return _sortBy(sections, (s) => s.name).flatMap((s) => [
+            ...s.enumerationChanges,
+            ...s.objectChanges,
+            ...s.routeChanges,
+            ...s.relationChanges,
+            ...s.tasks,
+        ]);
+    }
+
+    private static getChangeIdentifier(change: DevelopmentPolicyHelper.Change): string {
+        if (change instanceof ProjectStorySectionModelEnumerationChange) return change.enumerationChangeId;
+        if (change instanceof ProjectStorySectionModelObjectChange) return change.objectChangeId;
+        if (change instanceof ProjectStorySectionModelRouteChange) return change.routeChangeId;
+        if (change instanceof ProjectStorySectionModelRelationChange) return change.relationChangeId;
+        return change.taskId;
+    }
+
+    private static appendOpenThreadsHint(change: DevelopmentPolicyHelper.Change): void {
+        const openThreadCount = change.threads.filter((t) => t.status === ChangeThreadStatus.Open).length;
+        if (openThreadCount === 0) return;
+
+        const changeId = this.getChangeIdentifier(change);
+        const hint = `${openThreadCount} open ${openThreadCount === 1 ? 'thread' : 'threads'} on this change — run \`we-scrum get-change-threads --changeId "${changeId}"\` to view them.`;
+        change.description = change.description ? `${change.description}\n\n${hint}` : hint;
+    }
+
     private static async findStoryByIterationNumber(identificationNumber: string) {
         return FirebaseHelper.findDocument<ProjectStoryModel>(`/projects/${this.projectId}/stories`, [
             ['identificationNumber', '==', identificationNumber],
@@ -287,6 +356,7 @@ export class WeScrumHelper {
             headers: {
                 'Content-Type': 'application/json',
                 Authorization: `Bearer ${userIdToken}`,
+                'X-Contribution-Origin': ContributionOrigin.Cli,
             },
             signal: AbortSignal.timeout(60 * 1000),
         });

package/templates/get-next-task.hbs

@@ -12,14 +12,25 @@
 
 ## Next steps
 {{#if isTodo}}
-1. Run `we-scrum start-task --identificationNumber "{{identificationNumber}}" --taskId "{{taskId}}"` before making any changes.
-2. Implement the task described above.
-3. Commit your changes.
-4. Run `we-scrum complete-task --identificationNumber "{{identificationNumber}}" --taskId "{{taskId}}"` when done.
-5. Call `get_next_task` to continue with the next task.
-{{else}}
-1. Implement the task described above.
-2. Commit your changes.
-3. Run `we-scrum complete-task --identificationNumber "{{identificationNumber}}" --taskId "{{taskId}}"` when done.
-4. Call `get_next_task` to continue with the next task.
+1. Run `we-scrum start-task --identificationNumber "{{identificationNumber}}" --changeId "{{changeId}}"` before making any changes.
 {{/if}}
+1. If the task above mentions open threads, run `we-scrum get-change-threads --changeId "{{changeId}}"` before implementing. If a thread requests an adjustment to this task, make it part of the implementation below, then resolve the thread once done:
+   ```bash
+   we-scrum add-comment-to-change-thread --changeThreadId <changeThreadId> --comment "<markdown explaining what was done>"
+   we-scrum update-change-thread-status --changeThreadId <changeThreadId> --status Resolved
+   ```
+   Leave a thread open (with a reply explaining why) if it does not call for a change to this task, or if you disagree with the request.
+1. Implement the task described above.
+1. If your implementation deviates in any way from what this task describes (different naming, different location, a sub-step skipped or altered, a workaround for a blocker, a mistake you had to correct mid-way, etc.), post a comment explaining the deviation and why, before completing the task:
+   ```bash
+   we-scrum create-change-thread --changeId "{{changeId}}" --comment "<markdown explaining the deviation>"
+   ```
+   Group related deviations into a single thread. If there are several unrelated deviations, a few separate threads is fine, but do not open one thread per minor deviation — use judgment to keep the count reasonable. Skip this step entirely if the task was implemented exactly as described.
+1. If the development guidelines or the unit tests guidelines referenced above were incomplete, outdated, or missing for this kind of task — meaning you had to spend extra effort figuring out conventions they should have covered — open a change thread with a concrete suggested addition or correction:
+   ```bash
+   we-scrum create-change-thread --changeId "{{changeId}}" --comment "<markdown: what was missing/outdated, and a suggested fix>"
+   ```
+   Use at most one thread for all development guidelines feedback, and, separately, at most one thread for all unit tests guidelines feedback — do not mix the two guidelines together, and do not mix guideline feedback into the deviation thread above. Skip whichever guideline was accurate and sufficient.
+1. Commit your changes.
+1. Run `we-scrum complete-task --identificationNumber "{{identificationNumber}}" --changeId "{{changeId}}"` when done.
+1. Call `get_next_task` to continue with the next task.

package/templates/review-analysis-skill.hbs

@@ -34,7 +34,27 @@ we-scrum get-story-analysis --identificationNumber <identificationNumber>
 
 ---
 
-## Step 2 — Review and return comments
+## Step 2 — Review existing threads
+
+The analysis DSL may annotate a change with a note such as _"N open thread(s) — run `we-scrum get-change-threads --changeId <id>` to view them."_ This means earlier review comments are already open on that change.
+
+For every change annotated this way:
+
+```bash
+we-scrum get-change-threads --changeId <changeId>
+```
+
+For each thread returned:
+- If the current state of the analysis addresses the concern raised in the thread, resolve it and explain why:
+  ```bash
+  we-scrum add-comment-to-change-thread --changeThreadId <changeThreadId> --comment "<markdown explaining why this is resolved>"
+  we-scrum update-change-thread-status --changeThreadId <changeThreadId> --status Resolved
+  ```
+- If the concern still stands, leave the thread open. Only add a follow-up comment via `add-comment-to-change-thread` if you have new information to add — do not just repeat the original comment.
+
+---
+
+## Step 3 — Review the analysis
 
 {{> analysis-dsl-legend}}
 
@@ -60,4 +80,18 @@ Review the story description and analysis DSL together. Check for:
 - Any change that adds, removes, or renames a field on an Aggregate or a Model must be accompanied by a migration script task in the analysis
 - If such a structural change is present but no corresponding migration task exists, raise it as a blocking issue — shipping without a migration will corrupt existing data or break reads
 
-Return your comments to the user.
+---
+
+## Step 4 — Post findings as change threads
+
+Do not just report new findings in the chat — open a change thread on the change each finding concerns:
+
+```bash
+we-scrum create-change-thread --changeId <changeId> --comment "<markdown-formatted finding>"
+```
+
+- The comment body supports Markdown (headings, lists, bold, code spans) — it renders as such in the we-scrum UI.
+- Group every finding for a given change into a single thread/comment rather than opening one thread per bullet point.
+- Skip changes that already have an open thread covering the same concern (see Step 2) — reply on the existing thread instead of duplicating it.
+
+Once threads are created or resolved, give the user a short summary in the chat: what was found, what was posted or resolved, and why — do not skip this summary just because the details live in we-scrum.