@we-scrum/cli 6.9.2 → 6.9.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@we-scrum/cli",
-  "version": "6.9.2",
+  "version": "6.9.5",
   "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",
+    "@my-devkit/core": "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 all the change threads (any status) for a change')
+        .requiredOption('-c, --changeId <id>', 'Unique identifier of the change')
+        .action(
+            runProjectCommand<{ changeId: string }>(async (options) => {
+                return WeScrumHelper.getChangeThreads(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,11 +20,14 @@ 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.');
+                Logger.info(
+                    'Reminder: if the result deviates from the task description (including changes requested by the developer), or if the development guidelines were missing or incomplete, post the matching change thread(s) now with "we-scrum create-change-thread".',
+                );
             }),
         );
 }

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,
@@ -33,6 +37,8 @@ import { FirebaseHelper } from './firebase-helper';
 import { ProjectHelper } from './project-helper';
 import { renderTemplate } from './template.helper';
 
+const CHANGE_THREAD_STATUS_DISPLAY_ORDER = [ChangeThreadStatus.Open, ChangeThreadStatus.Resolved, ChangeThreadStatus.Archived];
+
 export class WeScrumHelper {
     private static readonly backendUrl = 'https://europe-west1-we-scrum-prod.cloudfunctions.net';
     constructor(private userId: string) {}
@@ -63,6 +69,8 @@ export class WeScrumHelper {
             });
         }
 
+        this.appendThreadsHint(nextChange);
+
         const analysisChange = StorySectionHelper.mapSingleChange(nextChange);
         const isTodo = nextChange.progress.status === ProgressStatus.ToDo;
         const developmentPolicy = await this.getChangeDevelopmentPolicy(nextChange);
@@ -74,7 +82,7 @@ export class WeScrumHelper {
             unitTestsPath: developmentPolicy?.areUnitTestsMandatory ? unitTestsPath : null,
             isTodo,
             identificationNumber,
-            taskId: analysisChange.id,
+            changeId: analysisChange.id,
         });
     }
 
@@ -85,11 +93,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 +102,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 +138,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 +232,96 @@ 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.appendThreadsHint(change));
+
         const ast = StorySectionHelper.mapSectionsToAnalysisAst(sections);
 
         return AnalysisDsl.stringify(ast);
     }
 
+    public static async getChangeThreads(changeId: string): Promise<string> {
+        const threads = await FirebaseHelper.getCollection<ProjectChangeThreadModel>(`/projects/${this.projectId}/change-threads`, {
+            where: [['changeId', '==', changeId]],
+        });
+
+        if (threads.length === 0) {
+            return `No threads for change "${changeId}".`;
+        }
+
+        return _sortBy(
+            threads,
+            (thread) => CHANGE_THREAD_STATUS_DISPLAY_ORDER.indexOf(thread.status),
+            (thread) => thread.comments[0]?.createdAt,
+        )
+            .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 appendThreadsHint(change: DevelopmentPolicyHelper.Change): void {
+        const synthesis = CHANGE_THREAD_STATUS_DISPLAY_ORDER.map((status) => ({
+            status,
+            count: change.threads.filter((t) => t.status === status).length,
+        }))
+            .filter(({ count }) => count > 0)
+            .map(({ status, count }) => `${count} ${status}`)
+            .join(' • ');
+        if (!synthesis) return;
+
+        const changeId = this.getChangeIdentifier(change);
+        const hint = `Threads: ${synthesis} — 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 +367,7 @@ export class WeScrumHelper {
             headers: {
                 'Content-Type': 'application/json',
                 Authorization: `Bearer ${userIdToken}`,
+                'X-Contribution-Origin': ContributionOrigin.Cli,
             },
             signal: AbortSignal.timeout(60 * 1000),
         });

package/templates/develop-story-skill.hbs

@@ -56,3 +56,5 @@ Before committing any task, run ESLint on every modified file and fix all report
 ```bash
 npx eslint <file1> <file2> ...
 ```
+
+Every task ends with a mandatory pre-completion check (deviation thread and development guidelines feedback thread, see the task's "Next steps"). Adjustments requested by the developer during or after a task count as deviations. If a thread is needed, post it before running `we-scrum complete-task`; if you realize afterwards that one was missed, post it right away.

package/templates/get-next-task.hbs

@@ -5,21 +5,34 @@
 {{{taskDetails}}}
 
 ## Development guidelines
-{{#if guidelinesPath}}Refer to `{{{guidelinesPath}}}` for coding conventions and project-specific instructions.{{else}}_No development guidelines file configured for this task._{{/if}}
+{{#if guidelinesPath}}Refer to `{{{guidelinesPath}}}` for coding conventions and project-specific instructions.{{else}}_No development guidelines file configured for this task._ **You must therefore open a development guidelines feedback thread before completing the task (see the pre-completion check below).**{{/if}}
 
 ## Unit tests
 {{#if unitTestsPath}}Unit tests are required. Refer to `{{{unitTestsPath}}}` for test writing guidelines.{{else}}No unit tests required.{{/if}}
 
 ## 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 threads, run `we-scrum get-change-threads --changeId "{{changeId}}"` before implementing. It returns **all** threads of the change (Open, Resolved, Archived) so you have the complete history. If an **open** 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. Resolved and Archived threads are history only: do not act on them.
+1. Implement the task described above.
+1. Commit your changes.
+1. **Pre-completion check — mandatory, answer both questions explicitly before running `complete-task`.** Threads posted after completion are late, so do this now:
+   - **Deviations:** does the final result differ 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)? Changes made at the developer's request during the session (after feedback, redesigns, extra options or components added) count as deviations too. If yes, first run `we-scrum get-change-threads` and check the existing threads. If a thread already covers the deviation (whatever its status), reply to it with `we-scrum add-comment-to-change-thread` instead of creating a duplicate; otherwise post **one** thread explaining what differs and why:
+     ```bash
+     we-scrum create-change-thread --changeId "{{changeId}}" --comment "<markdown explaining the deviation>"
+     ```
+     Group related deviations into a single thread; use a few separate threads only for several unrelated deviations, and never one thread per minor deviation. Skip only if the task was implemented exactly as described.
+   - **Guidelines:** was the development guidelines section above "No development guidelines file configured", or were the development / unit tests guidelines incomplete, outdated, or missing for this kind of task (you had to spend extra effort figuring out conventions)? If yes, check the existing threads first (same rule: reply to an existing guidelines thread rather than creating a duplicate), otherwise open a 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 for all unit tests guidelines feedback; do not mix them together, and do not mix guideline feedback into the deviation thread. Skip whichever guideline was accurate and sufficient.
+   - If the developer asks for adjustments **after** the task is completed, add them to the deviation thread (reply with `we-scrum add-comment-to-change-thread`, or open one if none exists).
+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,29 @@ 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 _"Threads: 3 Open • 2 Resolved — run `we-scrum get-change-threads --changeId <id>` to view them."_ This means earlier review comments exist on that change (statuses with no thread are omitted).
+
+For every change annotated this way:
+
+```bash
+we-scrum get-change-threads --changeId <changeId>
+```
+
+The command returns **all** threads of the change (Open, Resolved, Archived), so you have the complete history. Resolved and Archived threads are history only: read them to avoid repeating a concern that was already handled, but do not act on them.
+
+For each **open** 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 +82,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 a thread covering the same concern, whatever its status (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.