@tiqora/tiqora 0.0.2-dev → 0.0.3-dev

package/_tiqora/agents/dev.md

@@ -24,7 +24,8 @@ You must fully embody this agent persona and follow activation rules exactly.
     <reflex id="pm-mcp-context">If pm_tool is not none and ticket context is missing or stale, fetch ticket details via configured PM MCP connector before implementation decisions.</reflex>
     <reflex id="branch-discipline">Before implementation starts, resolve branch name from branch_pattern plus ticket identifier and create/switch branch.</reflex>
     <reflex id="mr-readiness">When work reaches review-ready state, prepare MR content with intent, scope, validation, and risks; create MR through provider integration when available, otherwise produce a ready-to-paste draft.</reflex>
-    <reflex id="status-sync">At workflow milestones, push PM status and summary updates when integration is configured.</reflex>
+    <reflex id="status-sync">At workflow milestones, push PM status and summary updates when integration is configured: start => In Progress, finish => In Review/Done, blocked => Blocked when available.</reflex>
+    <reflex id="worklog-sync">At workflow completion, push worklog using run timestamps (or user-provided duration fallback) when PM tool supports worklog operations.</reflex>
     <reflex id="sync-fallback">If remote PM or MR operations fail, do not block delivery; append retry metadata to .tiqora/sync/queue.json and continue with explicit warning.</reflex>
   </operational-reflexes>
 

package/_tiqora/workflows/4-implementation/create-story/checklist.md

@@ -0,0 +1,82 @@
+---
+title: "Tiqora Create-Story - Definition of Done Checklist"
+validation-target: "New story creation run (conversational elicitation)"
+validation-criticality: "HIGH"
+---
+
+# Tiqora Create-Story - DoD Checklist
+
+## 1) Configuration & Setup
+
+- [ ] Effective config built from `~/.tiqora.yaml` + project `.tiqora.yaml`.
+- [ ] Required keys present: `pm_tool`, `git_host`, `branch_pattern`.
+- [ ] Ready to discuss story with user.
+
+## 2) Story Discussion (Natural Conversation)
+
+- [ ] User described what they want to build/fix.
+- [ ] Agent asked clarifying questions (not as a form, as natural conversation).
+- [ ] Problem statement captured and understood.
+- [ ] Expected outcome discussed and clear.
+- [ ] User/stakeholder identified.
+- [ ] Priority discussed (low/medium/high/critical).
+- [ ] Scope boundaries discussed (what's in, what's out).
+
+## 3) Acceptance Criteria (Conversational)
+
+- [ ] User explained how they'd know when it's done.
+- [ ] Agent clarified measurable outcomes (3-5 criteria).
+- [ ] ACs captured in natural language (format not forced).
+- [ ] Both agent and user agree on what "done" means.
+- [ ] No critical ambiguities remain.
+
+## 4) Dependencies & Gotchas (Discussed)
+
+- [ ] Blockers/dependencies discussed naturally (if any).
+- [ ] Risks or tricky parts identified.
+- [ ] Impact on ecosystem considered.
+- [ ] (May be "none" for simple stories - that's ok)
+
+## 5) Story Document (From Our Conversation)
+
+- [ ] Story title generated from problem statement (max 80 chars, searchable).
+- [ ] Story description summarizes what we discussed:
+  - Problem statement (our words)
+  - Expected outcome
+  - User/Stakeholder
+  - Priority
+  - Acceptance criteria (as we described them)
+  - Scope (in/out)
+  - Dependencies & risks (if any)
+- [ ] Document is clear enough for dev to challenge and implement.
+
+## 6) User Approval
+
+- [ ] Story document displayed to user.
+- [ ] User reviewed and confirmed it matches their intent.
+- [ ] Any edits applied before creation.
+- [ ] User explicitly approved creation.
+
+## 7) PM Tool Creation
+
+- [ ] Story created in {{pm_tool}} using MCP connector.
+- [ ] Story ID/Key captured as {{ticketId}}.
+- [ ] Story is accessible and viewable in PM tool.
+- [ ] (If creation failed, locally saved with sync queued)
+
+## 8) Local Artifact Persistence
+
+- [ ] Story artifact persisted to `.tiqora/workflows/stories/{{ticketId}}.json`.
+- [ ] Includes all discussion details (problem, outcome, ACs, scope, etc).
+- [ ] Includes metadata (pm_tool, git_host, document_language, created_at).
+
+## 9) Communication
+
+- [ ] Conversation in `communication_language` (natural).
+- [ ] Story document in ENGLISH (clarity for dev).
+- [ ] Clear next steps offered (dev-story, view, etc).
+
+## Final Result
+
+- [ ] **PASS**: Story created from natural discussion, ready for dev-story challenge.
+- [ ] **FAIL**: Unresolved ambiguities or user not satisfied with story.

package/_tiqora/workflows/4-implementation/create-story/instructions.xml

@@ -0,0 +1,239 @@
+<workflow>
+  <critical>The workflow execution engine is governed by: {project-root}/_tiqora/core/tasks/workflow.xml</critical>
+  <critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
+  <critical>YOU MUST ALWAYS SPEAK OUTPUT in the configured communication_language resolved from merged tiqora config.</critical>
+  <critical>This is a CONVERSATIONAL workflow, not a form. Have a natural discussion with the user.</critical>
+  <critical>Generate story artifact in ENGLISH for clarity, but the conversation is in communication_language.</critical>
+  <critical>Execute ALL steps in exact order; do NOT skip steps.</critical>
+
+  <step n="1" goal="Load configuration">
+    <action>Load project config from {project_config} as required input.</action>
+    <action if="project config does not exist">HALT: "✗ No project .tiqora.yaml found. Run 'npx tiqora init' first."</action>
+
+    <action>Load profile config from {profile_config} when available (optional).</action>
+    <action>Build effective config as: profile config (base) + project config (override).</action>
+    <action>Apply defaults when missing: user_name={default_user_name}, communication_language={default_communication_language}, document_language={default_document_language}.</action>
+
+    <action>Validate required project keys: pm_tool, git_host, branch_pattern.</action>
+    <action if="any required project key is missing">HALT: "✗ Blocking configuration error in {project_config}: missing pm_tool, git_host, or branch_pattern. Edit .tiqora.yaml and add these keys."</action>
+
+    <output>[WORKFLOW] ✓ Config loaded and ready to discuss</output>
+  </step>
+
+  <step n="2" goal="Start conversational discussion about the story">
+    <critical>This is a natural conversation, not interrogation. Listen more than ask. Build on what the user says.</critical>
+
+    <action>Start by asking the user to describe what they want to build/fix:
+      "What do you want to work on? Tell me about it."
+    </action>
+
+    <action>Listen to their initial description and capture the core idea as {{initial_intent}}.</action>
+
+    <ask>[Start the conversation]
+Tell me about what you want to build or fix. What's the idea?</ask>
+
+    <action>Based on their response, engage in natural back-and-forth. Ask clarifying questions when needed:
+      - If unclear: "Help me understand the problem better..."
+      - If scope seems big: "Is this everything, or are there phases?"
+      - If impact is unclear: "Who would benefit from this?"
+      - If success criteria missing: "How would we know this worked?"
+    </action>
+
+    <action>Keep iterating until {{problem_statement}}, {{expected_outcome}}, {{user_role}}, {{priority}}, {{scope_boundaries}} are captured naturally in the conversation.</action>
+
+    <output>[WORKFLOW] ✓ Initial understanding captured | Ready to refine</output>
+  </step>
+
+  <step n="3" goal="Refine acceptance criteria together">
+    <critical>Don't impose format. Guide naturally toward measurable outcomes.</critical>
+
+    <action>Ask the user how they'd know when this is done:
+      "What needs to be true for this to be 'done'?"
+      "How do we test/verify this works?"
+    </action>
+
+    <action>As they describe acceptance criteria, help clarify and structure them naturally. Examples:
+      - "So when a user [does X], they should [see Y]?"
+      - "Let's make sure this is testable: how would we verify that?"
+    </action>
+
+    <action>Capture {{acceptance_criteria}} through conversation (don't need Given/When/Then if they describe it differently).</action>
+
+    <action>Iterate until you have 3-5 clear, measurable outcomes that the user agrees on.</action>
+
+    <output>[WORKFLOW] ✓ Acceptance criteria refined and agreed</output>
+  </step>
+
+  <step n="4" goal="Identify dependencies, risks, and gotchas (conversational)">
+    <critical>Ask about blockers and complications naturally. Some stories don't have many.</critical>
+
+    <action>Engage in natural conversation about potential blockers:
+      "Are there any blockers or dependencies we should know about?"
+      "Does this depend on other work being done first?"
+      "Any tricky parts or things that could go wrong?"
+      "Any performance, security, or infrastructure concerns?"
+    </action>
+
+    <action>Capture {{dependencies}}, {{risks}}, {{constraints}} from user responses. If none, that's fine too.</action>
+
+    <output>[WORKFLOW] ✓ Dependencies and risks discussed</output>
+  </step>
+
+  <step n="5" goal="Generate story document from our discussion">
+    <critical>This is a summary of what we discussed. It should be clear enough for dev to challenge and implement.</critical>
+
+    <action>Generate story title from {{problem_statement}}:
+      - Format: "[FEATURE] Brief description" or "[BUG] Brief description"
+      - Max 80 characters
+      - Make it clear and searchable
+    </action>
+
+    <action>Generate story description (ENGLISH) as a clean summary of our conversation:
+      "## Problem Statement
+
+      {{problem_statement}}
+
+      ## Expected Outcome
+
+      {{expected_outcome}}
+
+      ## User / Stakeholder
+
+      {{user_role}}
+
+      ## Priority
+
+      {{priority}}
+
+      ## Acceptance Criteria
+
+      [List the outcomes we discussed - can be natural language, not forced format]
+
+      ## Scope
+
+      In Scope:
+      - [What we agreed is included]
+
+      Out of Scope:
+      - [What we explicitly said is NOT included]
+
+      ## Dependencies & Gotchas
+
+      {{dependencies}}
+      {{risks}}
+
+      ## Notes
+
+      Created via Tiqora create-story workflow (conversational elicitation).
+      Ready for dev challenge and implementation."
+    </action>
+
+    <action>Store complete story as {{story_document}}.</action>
+
+    <output>[WORKFLOW] ✓ Story document created from our discussion</output>
+  </step>
+
+  <step n="6" goal="Review story together and get approval">
+    <critical>This is our chance to refine before creating. Make sure the story matches your intent.</critical>
+
+    <action>Display {{story_document}} to user for review.</action>
+
+    <ask>Here's what we discussed, structured as a story:
+
+---
+{{story_document}}
+---
+
+Does this look right? Anything you want to change before we create it?
+
+Choose:
+- (yes) Good, create it in {{pm_tool}}
+- (edit) Let me tweak [section]
+- (no) Actually, let's not do this</ask>
+
+    <check if="user chooses edit">
+      <ask>What needs to change? (You can describe what you want, I'll update it)</ask>
+      <action>Listen to user's suggested edits and apply them to {{story_document}}.</action>
+      <goto step="6" />
+    </check>
+
+    <check if="user chooses no">
+      <output>[WORKFLOW] ⏸ Story creation cancelled</output>
+      <action>HALT workflow.</action>
+    </check>
+
+    <check if="user chooses yes">
+      <action>Proceed to step 7 (create in PM tool).</action>
+    </check>
+  </step>
+
+  <step n="7" goal="Create story in PM tool">
+    <critical>Use PM MCP to create the story in Jira/GitHub/GitLab with the info we discussed.</critical>
+
+    <action if="pm_tool is not none">
+      Use PM MCP connector to create story:
+      - Title: {{story_title}}
+      - Description: {{story_description}}
+      - Project: {jira.project_key} or equivalent
+      - Priority: {{priority}}
+      - Type: "Story"
+    </action>
+
+    <check if="story creation succeeds">
+      <action>Capture returned story ID/key as {{ticketId}}.</action>
+      <action>Ensure directory exists: {story_artifact_dir}.</action>
+      <action>Persist story artifact to {created_story_file} (JSON) with all the details from our conversation.</action>
+      <output>[WORKFLOW] ✓ Story created in {{pm_tool}}
+      ID: {{ticketId}}
+      Artifact: {created_story_file}
+      </output>
+    </check>
+
+    <check if="story creation fails">
+      <ask>Couldn't create the story in {{pm_tool}}. Want to:
+      (retry) Try again?
+      (queue) Save locally and retry later?
+      (skip) Just keep it locally for now?</ask>
+
+      <check if="user chooses queue">
+        <action>Persist story locally with status = "pending_sync".</action>
+        <action>Queue retry in .tiqora/sync/queue.json.</action>
+        <output>⚠ Story saved locally, will try to create in {{pm_tool}} later.</output>
+      </check>
+
+      <check if="user chooses retry">
+        <goto step="7" />
+      </check>
+
+      <check if="user chooses skip">
+        <action>Persist story locally (not created in PM tool yet).</action>
+        <output>Story saved locally. You can create it manually later if needed.</output>
+      </check>
+    </check>
+  </step>
+
+  <step n="8" goal="Done — offer next steps">
+    <output>[WORKFLOW] ✅ STORY CREATED
+    ID: {{ticketId}}
+    Title: {{story_title}}
+    Artifact: {created_story_file}
+    </output>
+
+    <ask>What would you like to do next?
+    (dev) Start dev-story with {{ticketId}} (challenge + implementation)
+    (view) Show me the full story again
+    (done) We're good for now</ask>
+
+    <check if="user chooses dev">
+      <output>Great! Next: Run /tiq:workflow:dev-story {{ticketId}} to start the challenge and implementation flow.</output>
+    </check>
+
+    <check if="user chooses view">
+      <action>Display {{story_document}}.</action>
+    </check>
+
+    <check if="user chooses done">
+      <output>Story is ready whenever you want to start dev-story.</output>
+    </check>
+  </step>
+</workflow>

package/_tiqora/workflows/4-implementation/create-story/workflow.yaml

@@ -0,0 +1,27 @@
+name: create-story
+description: "Elicit and create implementation-ready story with PM persona, clear acceptance criteria, and scope boundaries"
+author: "Tiqora"
+
+# Workflow engine bootstrap (required by _tiqora/core/tasks/workflow.xml)
+config_source: "{project-root}/.tiqora.yaml"
+date: system-generated
+
+# Workflow components
+installed_path: "{project-root}/_tiqora/workflows/4-implementation/create-story"
+instructions: "{installed_path}/instructions.xml"
+validation: "{installed_path}/checklist.md"
+
+# Runtime paths
+story_artifact_dir: "{project-root}/.tiqora/workflows/stories"
+created_story_file: "{story_artifact_dir}/{{ticketId}}.json"
+
+# PM defaults
+pm_in_progress_status: "In Progress"
+pm_review_status: "In Review"
+pm_done_status: "Done"
+
+# Defaults applied by instructions.xml after config merge
+default_user_name: "Developer"
+default_idle_threshold_minutes: 15
+default_communication_language: "Français"
+default_document_language: "English"

package/_tiqora/workflows/4-implementation/dev-story/checklist.md

@@ -8,40 +8,105 @@ validation-criticality: "HIGHEST"
 
 ## 1) Config and Context
 
-- [ ] Effective config was built from `~/.tiqora/config.yaml` (optional) + project `.tiqora.yaml` (required, override).
-- [ ] Required project keys are present: `pm_tool`, `git_host`, `branch_pattern`.
-- [ ] Ticket context was retrieved from PM MCP when ticket ID was provided (or fallback choice explicitly confirmed).
+- [ ] Effective config built: `~/.tiqora/config.yaml` (optional) + project `.tiqora.yaml` (required).
+- [ ] Required keys present: `pm_tool`, `git_host`, `branch_pattern`.
+- [ ] Ticket retrieved via PM MCP or fallback explicitly confirmed.
+- [ ] PM tracking identifiers (key/id, transitions, workspace IDs) captured.
 
-## 2) Challenge Gate
+## 2) Jira State Transitions (CRITICAL)
 
-- [ ] Challenge artifact exists in `.tiqora/workflows/steps/{runId}-challenge.md`.
-- [ ] PM persona was loaded from `_tiqora/agents/pm.md` specifically for the challenge gate, then restored to implementation persona.
-- [ ] PM challenge was executed for clarity, consistency, implementation completeness, dependency coverage, and acceptance testability.
-- [ ] Intent, acceptance criteria, PM verdict, risks, and implementation approach are explicit.
-- [ ] Ambiguities were resolved before implementation started.
+- [ ] **Step 3**: Ticket moved to `In Progress` immediately after fetch (worklog tracking started).
+- [ ] **Step 4**: Challenge gate completed; artifact at `.tiqora/workflows/steps/{runId}-challenge.md` (ENGLISH).
+- [ ] **Step 4**: Challenge summary comment posted to ticket with verdict, scope, risks.
+- [ ] **Step 9**: Ticket moved to `Review` (or `Done` if no review stage) after commit and MR creation.
+- [ ] **Step 9**: Final completion comment posted with MR link and time spent.
 
-## 3) Implementation Quality
+## 3) Challenge Gate (Rigorous)
 
-- [ ] Developer persona was loaded from `_tiqora/agents/dev.md` for implementation and test execution.
-- [ ] Changes map to approved scope; no out-of-scope work was introduced.
-- [ ] Tests were added/updated for changed behavior.
-- [ ] Regression checks were run and passed.
-- [ ] Lint/type/quality checks were run when available.
+- [ ] PM persona loaded from `_tiqora/agents/pm.md`.
+- [ ] Challenge analyzed 6 dimensions: clarity, consistency, scope, alignment, testability, risks.
+- [ ] Challenge artifact includes: intent, AC checklist, PM verdict (PASS/FAIL), scope boundaries, approach, risks, dependencies, testability notes.
+- [ ] PM verdict is PASS (not vague "ok, let's go").
+- [ ] Ambiguities resolved BEFORE implementation started.
+- [ ] Persona restored to entry persona before implementation.
 
-## 4) Run-State and Traceability
+## 4) Implementation & Testing (Test-First)
 
-- [ ] Branch naming follows configured `branch_pattern`.
-- [ ] Active run is persisted in `.tiqora/state/active-run.json`.
-- [ ] Run artifact is persisted in `.tiqora/workflows/runs/`.
-- [ ] Status transitions are consistent (`initialized` / `awaiting_user` / `in_progress` / `completed`).
+- [ ] Dev persona loaded from `_tiqora/agents/dev.md`.
+- [ ] Changes map 100% to approved challenge scope; no out-of-scope features.
+- [ ] Tests written first (red), implementation (green), refactoring (refactor) when feasible.
+- [ ] All unit tests passing.
+- [ ] All regression tests passing.
+- [ ] Lint/type/quality checks run and passing (if configured).
+- [ ] At least one progress comment published during implementation (done/next/blockers format).
 
-## 5) Communication and Output
+## 5) Git Commit (MANDATORY)
 
-- [ ] User-facing communication follows configured `communication_language`.
-- [ ] Generated artifacts follow configured `document_language` unless user requested otherwise.
-- [ ] Output is concise, with no unnecessary internal execution noise.
+- [ ] Changes staged: `git add .`
+- [ ] Commit created with conventional message format:
+  - `feat:` for new features (or `fix:`, `refactor:`, `test:`)
+  - Ticket ID in message: `Fixes {{ticketId}}`
+  - Descriptive commit body with implementation details
+- [ ] Commit includes all changes (no untracked files left).
+- [ ] `git log` shows the commit on the branch.
+
+## 6) MR Report
+
+- [ ] MR Report generated at `.tiqora/workflows/runs/{runId}-mr-report.md` (in `document_language`).
+- [ ] MR Report includes sections:
+  - Title + Description (what was built and why)
+  - Technical Choices (architecture decisions + justification)
+  - Changes Made (file-by-file explanation)
+  - Testing (unit/integration/manual steps)
+  - How to Run (step-by-step instructions)
+  - Deployment Notes (migrations, env vars, breaking changes, rollback plan)
+- [ ] Developer reviewed and approved MR Report before push.
+- [ ] MR/PR created in Git host (GitHub/GitLab) with MR Report as description.
+
+## 7) Run-State and Traceability
+
+- [ ] Branch name follows configured `branch_pattern`.
+- [ ] Active run persisted to `.tiqora/state/active-run.json`.
+- [ ] Run artifact persisted to `.tiqora/workflows/runs/{{runId}}.json` with:
+  - ticketId, branchName, runId
+  - Timestamps: challenge_started_at, implementation_started_at, mr_report_approved_at, completed_at
+  - worklog_start_time (for final calculation)
+  - final_mr_url (for traceability)
+- [ ] Status transitions consistent: in_progress → review → completed.
+
+## 8) Worklog Tracking
+
+- [ ] Worklog tracking started at Step 3 (`worklog_start_time` captured).
+- [ ] Worklog includes challenge + implementation time (from start to commit).
+- [ ] Worklog computed: from {{worklog_start_time}} to commit time, rounded to {worklog_rounding_minutes} minutes, minimum {minimum_worklog_minutes} minutes.
+- [ ] If timestamps unavailable, user explicitly provided time in minutes.
+- [ ] Worklog pushed to PM tool (Jira/GitHub/etc.) at Step 9.
+
+## 9) PM Sync (CRITICAL)
+
+- [ ] **Challenge comment**: Posted with challenge verdict, scope, risks.
+- [ ] **Progress comment(s)**: Posted during implementation (done/next/blockers).
+- [ ] **Final comment**: Posted with MR link, time spent, validation evidence.
+- [ ] **Status transitions**: In Progress (Step 3) → Review/Done (Step 9).
+- [ ] **Worklog**: Pushed to PM tool.
+- [ ] Any failed sync queued in `.tiqora/sync/queue.json` for retry.
+
+## 10) Communication and Languages
+
+- [ ] User-facing communication in `communication_language` (from config).
+- [ ] Technical artifacts (challenge, implementation) in ENGLISH for clarity.
+- [ ] Reports (MR Report, daily, retrospective) in `document_language` for team.
+- [ ] Output concise; no unnecessary internal execution noise.
+
+## 11) Final Artifact Structure
+
+- [ ] `.tiqora/workflows/runs/{{runId}}/` contains:
+  - `{{runId}}.json` — run manifest (metadata, timestamps)
+  - `{{runId}}-challenge.md` — challenge artifact (ENGLISH)
+  - `{{runId}}-mr-report.md` — MR report (document_language)
+  - Any additional implementation notes
 
 ## Final Result
 
-- [ ] PASS: all items above are satisfied.
-- [ ] FAIL: unresolved blockers are listed with concrete next actions.
+- [ ] **PASS**: All items above satisfied. Workflow is complete and ready for code review.
+- [ ] **FAIL**: Unresolved blockers listed with concrete next actions.

package/_tiqora/workflows/4-implementation/dev-story/instructions.xml

@@ -2,22 +2,23 @@
   <critical>The workflow execution engine is governed by: {project-root}/_tiqora/core/tasks/workflow.xml</critical>
   <critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
   <critical>YOU MUST ALWAYS SPEAK OUTPUT in the configured communication_language resolved from merged tiqora config.</critical>
-  <critical>Generate artifacts in document_language resolved from merged tiqora config, unless user explicitly asks otherwise.</critical>
+  <critical>Generate technical artifacts (challenge, implementation, validation) in ENGLISH for clarity.</critical>
+  <critical>Generate developer-facing reports (MR Report, Daily, Retrospective) in document_language from config.</critical>
   <critical>Execute ALL steps in exact order; do NOT skip steps.</critical>
-  <critical>Do not report "completed" until all implementation and validation activities are truly finished.</critical>
+  <critical>Do not report "completed" until all implementation, validation, and PM sync activities are truly finished.</critical>
 
-  <step n="1" goal="Load and merge tiqora configuration">
+  <step n="1" goal="Load and validate tiqora configuration (silent mode)">
     <action>Load project config from {project_config} as required input.</action>
-    <action if="project config does not exist">HALT: "✗ No project .tiqora.yaml found. Run npx tiqora init in the project root."</action>
+    <action if="project config does not exist">HALT: "✗ No project .tiqora.yaml found. Run 'npx tiqora init' first."</action>
 
     <action>Load profile config from {profile_config} when available (optional).</action>
     <action>Build effective config as: profile config (base) + project config (override).</action>
     <action>Apply defaults when missing: user_name={default_user_name}, idle_threshold_minutes={default_idle_threshold_minutes}, communication_language={default_communication_language}, document_language={default_document_language}.</action>
 
     <action>Validate required project keys: pm_tool, git_host, branch_pattern.</action>
-    <action if="any required project key is missing">HALT: "✗ Blocking configuration error in {project_config}: missing required keys pm_tool, git_host, and/or branch_pattern."</action>
+    <action if="any required project key is missing">HALT: "✗ Blocking configuration error in {project_config}: missing pm_tool, git_host, or branch_pattern. Edit .tiqora.yaml and add these keys."</action>
 
-    <output>[WORKFLOW] dev-story config loaded — project + profile merged</output>
+    <output>[WORKFLOW] ✓ Config loaded and validated</output>
   </step>
 
   <step n="2" goal="Apply active run guard">
@@ -34,79 +35,280 @@
     </check>
   </step>
 
-  <step n="3" goal="Resolve ticket context">
+  <step n="3" goal="Resolve ticket context and transition to In Progress">
     <action>If a ticket ID is provided, retrieve the ticket via configured PM MCP connector before challenge/implementation.</action>
-    <action>If pm_tool is configured and no ticket provided, ask user to choose: existing ticket or create ticket.</action>
+    <action>If pm_tool is configured and no ticket provided, ask user to choose: work on existing ticket or create new ticket.</action>
+    <action if="pm_tool is not none and ticket was retrieved">Capture PM tracking identifiers (ticket key/id, workspace/project identifiers, available transitions) needed for status, comments, and worklog operations.</action>
+
     <check if="MCP retrieval fails">
-      <ask>Ticket retrieval failed. Retry MCP fetch or continue in standalone short-description mode? (retry/standalone)</ask>
+      <ask>Ticket retrieval failed. Retry MCP fetch or continue in standalone mode? (retry/standalone)</ask>
       <check if="user chooses retry">
         <action>Retry retrieval once and continue if successful.</action>
       </check>
       <check if="user chooses standalone">
-        <action>Continue with explicit ambiguity warning and queue sync retry metadata in .tiqora sync area.</action>
+        <action>Continue with explicit ambiguity warning and queue sync retry metadata in .tiqora/sync/queue.json.</action>
       </check>
     </check>
+
+    <action if="pm_tool is not none and ticket was retrieved">IMMEDIATELY transition ticket to {pm_in_progress_status} via PM MCP connector with comment: "Starting analysis and implementation. Branch: {{branchName}}, Run ID: {{runId}}"</action>
+    <action if="pm_tool is not none and ticket was retrieved">Capture timestamp as {{worklog_start_time}} for worklog calculation (includes challenge + implementation duration).</action>
+
+    <check if="PM In Progress transition fails">
+      <action>Log warning: "⚠ Could not transition ticket to In Progress. Queued in .tiqora/sync/queue.json for retry. Continuing with implementation."</action>
+    </check>
+
+    <output>[WORKFLOW] ✓ Ticket context resolved | Jira status: In Progress | Worklog tracking started</output>
   </step>
 
-  <step n="4" goal="Run mandatory challenge gate">
-    <critical>No implementation starts before challenge is passed.</critical>
+  <step n="4" goal="Run mandatory PM challenge gate (rigorous)">
+    <critical>No implementation starts before challenge is thoroughly passed. This is a critical gate.</critical>
     <action>Capture current active persona as {{entry_persona}}.</action>
-    <action>Load PM persona from {project-root}/_tiqora/agents/pm.md for the challenge gate.</action>
-    <action>Run a PM-quality challenge on the current ticket before implementation with checks for: clarity, logical consistency, implementation completeness, dependency coverage, and acceptance testability.</action>
-    <action>Create challenge artifact at {workflow_steps_dir}/{{runId}}-challenge.md with: intent, AC checklist, PM challenge verdict, feasibility notes, risks/blockers, and high-level approach.</action>
-    <check if="PM challenge finds ticket quality gaps">
-      <action>Restore persona to {{entry_persona}} before waiting for user clarifications.</action>
-      <action>Set run state to awaiting_user.</action>
-      <ask>PM challenge found ticket gaps. Clarify or update the ticket before implementation proceeds.</ask>
-    </check>
-    <check if="ticket or acceptance criteria are ambiguous">
-      <action>Restore persona to {{entry_persona}} before waiting for user clarifications.</action>
+    <action>Load PM persona from {project-root}/_tiqora/agents/pm.md for this challenge gate.</action>
+
+    <action>Conduct rigorous PM-quality challenge on the ticket analyzing:
+      1. CLARITY: Is the user story or ticket description clear and unambiguous?
+      2. CONSISTENCY: Do acceptance criteria align with ticket intent? Any contradictions?
+      3. SCOPE: Is the scope bounded and realistic? Any hidden dependencies?
+      4. ALIGNMENT: Does this ticket make sense in the project context? Check against project goals/architecture if available.
+      5. TESTABILITY: Are acceptance criteria measurable and testable? Can QA/user verify completion?
+      6. RISKS: What could go wrong? What dependencies exist? What's the impact of this work?
+    </action>
+
+    <action>Create challenge artifact at {workflow_steps_dir}/{{runId}}-challenge.md (ENGLISH) with these sections:
+      - **Ticket Intent**: What problem does this solve?
+      - **Acceptance Criteria** (checked): ✓ or ✗ for each AC
+      - **PM Challenge Verdict**: PASS or FAIL with justification
+      - **Scope Boundaries**: What's included, what's out-of-scope
+      - **Implementation Approach**: High-level technical direction
+      - **Risks & Blockers**: What could go wrong? Any known issues?
+      - **Dependencies**: Other tickets, external systems, prerequisites
+      - **Testability Notes**: How to verify implementation is complete
+    </action>
+
+    <check if="PM challenge identifies critical gaps or ambiguities">
+      <action>Restore persona to {{entry_persona}}.</action>
       <action>Set run state to awaiting_user.</action>
-      <ask>Provide clarifications to remove ambiguity before implementation proceeds.</ask>
+      <ask>⚠️ Challenge gate FAILED. Issues found:
+      [List the specific gaps/ambiguities]
+
+      Please clarify the ticket or update it in Jira before implementation can proceed. Waiting for your input.</ask>
     </check>
-    <check if="challenge is clear">
+
+    <check if="ticket is clear and challenge passes">
+      <action if="pm_tool is not none and ticket was retrieved">Post challenge summary comment on ticket (ENGLISH):
+        "✓ Challenge Gate PASSED
+        - Scope: [1-2 sentences on what will be built]
+        - Approach: [1-2 sentences on technical direction]
+        - Key Risks: [bullet points if any]
+        - Branch: {{branchName}} | Run: {{runId}}"
+      </action>
       <action>Restore persona to {{entry_persona}} before step 5+ implementation work.</action>
-      <output>[CHALLENGE] clarity passed — ready for implementation</output>
+      <output>[CHALLENGE] ✓ Gate PASSED — ready for implementation</output>
     </check>
   </step>
 
-  <step n="5" goal="Create/switch branch and persist run state">
+  <step n="5" goal="Create/switch git branch and persist run state">
     <action>Resolve branch name from ticket ID + slug using branch_pattern from effective config.</action>
-    <action>Create or switch to target branch.</action>
+    <action>Create or switch to target branch using git.</action>
     <action>Ensure directories exist: {workflow_runs_dir} and {workflow_steps_dir}.</action>
-    <action>Persist active run state atomically to {active_run_file} and run artifact in {workflow_runs_dir}.</action>
-    <output>[WORKFLOW] dev-story started — {{ticketId}} | branch: {{branchName}}</output>
-    <output>[WORKFLOW] dev-story initialized — challenge in progress</output>
+
+    <action>Persist active run state to {active_run_file} and run artifact to {workflow_runs_dir}/{{runId}}.json, including:
+      - ticketId, branchName, runId
+      - status: "in_progress"
+      - timestamps: challenge_started_at, implementation_started_at, last_activity_at
+      - worklog_start_time: {{worklog_start_time}} (for final worklog calculation)
+      - pm_tool, git_host, document_language (for later reporting)
+    </action>
+
+    <output>[WORKFLOW] ✓ Branch created: {{branchName}} | Run ID: {{runId}} | Worklog: tracking</output>
   </step>
 
-  <step n="6" goal="Implement scope with test-first discipline">
-    <critical>Follow the approved challenge scope; do not implement out-of-scope features.</critical>
+  <step n="6" goal="Implement scope with test-first discipline + mandatory commit">
+    <critical>Follow the approved challenge scope EXACTLY; do not implement out-of-scope features.</critical>
+    <critical>At the end of this step, you MUST make a git commit with conventional commit messages.</critical>
+
     <action>Load Developer persona from {project-root}/_tiqora/agents/dev.md for implementation and test execution.</action>
     <action>Plan concrete implementation tasks from challenge + ticket context.</action>
     <action>Write failing tests first when feasible (red), implement minimal code (green), then refactor safely (refactor).</action>
     <action>Run targeted and regression tests.</action>
     <action>Update run artifacts and notes under .tiqora as work progresses.</action>
-    <action if="required dependency or architectural change exceeds scope">ASK user approval before proceeding.</action>
+
+    <action if="pm_tool is not none and ticket was retrieved">Publish at least one progress comment during implementation with done/next/blockers. Format: "✓ Done: [X] | Next: [Y] | Blockers: [Z]" and update last_activity_at in run state.</action>
+
+    <check if="implementation is blocked and pm_tool is not none and ticket was retrieved">
+      <action>Transition ticket to {pm_blocked_status} via PM MCP (if available), otherwise add explicit blocker comment.</action>
+    </check>
+
+    <action if="required dependency or architectural change exceeds scope">ASK user approval: "This change exceeds approved scope. Approve to proceed? (yes/no)"</action>
+
+    <action>After all implementation is complete:
+      1. Run all tests one final time (regression check).
+      2. Generate conventional commit messages based on changes:
+         - Use "feat:" for new features (from ticket intent)
+         - Use "fix:" for bug fixes
+         - Use "refactor:" for code refactoring
+         - Use "test:" for test-only changes
+         - Add ticket ID in footer: "Fixes {{ticketId}}"
+      3. Stage all changes: git add .
+      4. Commit with message(s):
+         "feat: [brief description from ticket] ({{ticketId}})
+
+         - Implementation detail 1
+         - Implementation detail 2
+         - Testing notes
+
+         Fixes {{ticketId}}"
+    </action>
+
+    <action>Update run state: mark implementation_completed_at timestamp.</action>
+
+    <output>[WORKFLOW] ✓ Implementation complete | Changes committed to {{branchName}}</output>
   </step>
 
-  <step n="7" goal="Validate definition of done">
+  <step n="7" goal="Generate MR Report and request developer validation">
+    <critical>MR Report is mandatory and must be validated by the developer before pushing.</critical>
+
+    <action>Analyze git diff from branch_base..HEAD to understand all changes made.</action>
+
+    <action>Generate MR Report at {workflow_runs_dir}/{{runId}}-mr-report.md in {{document_language}} with sections:
+
+      **Title**: [Brief summary of what was implemented]
+
+      **Description**:
+      [1-2 paragraphs explaining the feature/fix and its purpose]
+
+      **Technical Choices**:
+      - [Key architecture decision 1 and why]
+      - [Key architecture decision 2 and why]
+      - [Any libraries/tools introduced and justification]
+
+      **Changes Made**:
+      - [File path 1]: [What was changed and why]
+      - [File path 2]: [What was changed and why]
+      [List all significant changes]
+
+      **Testing**:
+      - Unit tests: [Where, what's tested]
+      - Integration tests: [Where, what's tested]
+      - Manual testing steps: [How to verify this works]
+
+      **How to Run**:
+      1. [Prerequisites/setup steps]
+      2. [Build/install command if needed]
+      3. [Running the feature/fix]
+      4. [Expected output/behavior]
+
+      **Deployment Notes**:
+      - [Any database migrations? Yes/No]
+      - [Any environment variables needed? List]
+      - [Breaking changes? Yes/No, describe]
+      - [Rollback plan if needed]
+
+      **Reviewed By**: [Developer name]
+      **Reviewed At**: [Timestamp]
+    </action>
+
+    <action>Display the generated MR Report to the developer and ask for validation.</action>
+
+    <ask>MR Report generated. Please review and validate:
+      [ ] Are technical choices explained clearly?
+      [ ] Are testing instructions complete and accurate?
+      [ ] Are deployment notes accurate?
+
+      Choose: (approve/edit/regenerate)</ask>
+
+    <check if="developer chooses edit or regenerate">
+      <action>If edit: Display prompt for developer to provide modifications. Apply changes to the report file.
+      If regenerate: Re-run the MR Report generation with developer guidance.</action>
+    </check>
+
+    <action>Once approved, mark run state: mr_report_approved_at = now.</action>
+
+    <output>[WORKFLOW] ✓ MR Report validated</output>
+  </step>
+
+  <step n="8" goal="Validate definition of done checklist">
     <action>Load and execute validation checklist from {validation}.</action>
     <action>If checklist fails, return to implementation/validation until pass or HALT with explicit blockers.</action>
   </step>
 
-  <step n="8" goal="Finalize run status and output">
+  <step n="9" goal="Move to Review, push MR, sync Jira and finalize worklog">
+    <critical>This is the final step. Ensure all syncs are complete before marking done.</critical>
     <action>Restore persona to {{entry_persona}} before final workflow status communication.</action>
-    <check if="work is complete and validation passed">
-      <action>Mark run state as completed and persist atomically.</action>
-      <output>[WORKFLOW] dev-story completed — summary published</output>
+
+    <check if="work is complete and validation passed and MR report approved">
+      <!-- STEP 9.1: Compute Worklog -->
+      <action if="pm_tool is not none and ticket was retrieved">
+        Compute time spent from {{worklog_start_time}} to now, rounding to {worklog_rounding_minutes} minutes with minimum {minimum_worklog_minutes} minutes.
+        If timestamps unavailable, ask user: "How much time did you spend on this ticket (in minutes)?"
+        Store as {{total_worklog_minutes}}.
+      </action>
+
+      <!-- STEP 9.2: Create/Push MR -->
+      <action>Push branch to remote: git push -u origin {{branchName}}</action>
+
+      <action>Create MR/PR in {{git_host}}:
+        - Title: "[{{ticketId}}] " + [MR Report title]
+        - Description: [MR Report content from step 7]
+        - Link to challenge artifact: {workflow_steps_dir}/{{runId}}-challenge.md
+        - Link to implementation notes: available in branch
+      </action>
+
+      <action>Capture MR/PR URL as {{mr_url}} for Jira comment.</action>
+
+      <!-- STEP 9.3: Transition Jira to Review -->
+      <action if="pm_tool is not none and ticket was retrieved">
+        Transition ticket to {pm_review_status} (or {pm_done_status} if no review stage) via PM MCP connector.
+      </action>
+
+      <!-- STEP 9.4: Push Final Jira Sync -->
+      <action if="pm_tool is not none and ticket was retrieved">
+        Add final completion comment to ticket (ENGLISH):
+        "✓ IMPLEMENTATION COMPLETE
+
+        Branch: {{branchName}}
+        MR: {{mr_url}}
+        Time spent: {{total_worklog_minutes}} minutes
+
+        Delivered:
+        - All acceptance criteria met
+        - Tests passing (unit + regression)
+        - Code review ready
+
+        Next: Await code review"
+      </action>
+
+      <action if="pm_tool is not none and ticket was retrieved">
+        Push worklog via PM MCP: {{total_worklog_minutes}} minutes
+      </action>
+
+      <check if="final PM/MR sync fails">
+        <action>Log warning: "⚠ Final PM/MR sync failed. Queued in .tiqora/sync/queue.json for retry."</action>
+        <action>Queue retry metadata with MR URL, worklog, and status transition details.</action>
+      </check>
+
+      <!-- STEP 9.5: Mark Complete -->
+      <action>Mark run state as completed and persist to {active_run_file} and {workflow_runs_dir}/{{runId}}.json.</action>
+      <action>Update run state: completed_at = now, status = "completed", final_mr_url = {{mr_url}}</action>
+
+      <output>[WORKFLOW] ✅ COMPLETE
+      ├─ Ticket: {{ticketId}} → Review
+      ├─ Branch: {{branchName}}
+      ├─ MR: {{mr_url}}
+      ├─ Time: {{total_worklog_minutes}} minutes
+      └─ Artifacts: {workflow_runs_dir}/{{runId}}/
+      </output>
     </check>
+
+    <check if="validation failed">
+      <action>Restore run state to in_progress.</action>
+      <output>[WORKFLOW] ✗ DoD validation failed. Return to implementation.</output>
+    </check>
+
     <check if="waiting on user input">
+      <action if="pm_tool is not none and ticket was retrieved">Add ticket comment: "Awaiting clarification on [topic]. Paused implementation."</action>
       <action>Mark run state as awaiting_user and persist atomically.</action>
-      <output>[WORKFLOW] dev-story awaiting_user — clarification required</output>
-    </check>
-    <check if="implementation remains in progress">
-      <action>Keep run state as in_progress and persist atomically.</action>
-      <output>[WORKFLOW] dev-story in_progress — next implementation step queued</output>
+      <output>[WORKFLOW] ⏸ AWAITING_USER — clarification needed before proceeding</output>
     </check>
   </step>
 </workflow>

package/_tiqora/workflows/4-implementation/dev-story/workflow.yaml

@@ -18,6 +18,14 @@ active_run_file: "{project-root}/.tiqora/state/active-run.json"
 workflow_runs_dir: "{project-root}/.tiqora/workflows/runs"
 workflow_steps_dir: "{project-root}/.tiqora/workflows/steps"
 
+# PM tracking defaults used by instructions.xml
+pm_in_progress_status: "In Progress"
+pm_review_status: "In Review"
+pm_done_status: "Done"
+pm_blocked_status: "Blocked"
+worklog_rounding_minutes: 15
+minimum_worklog_minutes: 15
+
 # Defaults applied by instructions.xml after config merge
 default_user_name: "Developer"
 default_idle_threshold_minutes: 15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiqora/tiqora",
-  "version": "0.0.2-dev",
+  "version": "0.0.3-dev",
   "description": "Agentic delivery CLI for solo devs: challenge tickets, orchestrate PM/SM/Dev flows, and keep execution synced.",
   "type": "module",
   "main": "dist/index.cjs",