@basementuniverse/kanbn 0.9.0 → 1.0.0

package/docs/commands/burndown.txt

@@ -5,6 +5,12 @@ Show a burndown chart between a date range, or for a particular sprint.
 If no dates or sprint identifiers are specified, show data for the current sprint.
 If no sprints are defined, show data from the earliest created date to the current date.
 
+Burndown data source:
+  When a task has a structured `History` section, burndown uses its lifecycle events (created, moved, progress,
+  archived, restored) to reconstruct task activity over time.
+  For older tasks without history, burndown falls back to metadata/date inference (created/started/completed +
+  startedColumns/completedColumns).
+
 Options:
   {b}kanbn burndown --json{b}
   {b}kanbn burndown -j{b}
@@ -31,5 +37,5 @@ Options:
 
   {b}kanbn burndown --normalise "days"|"hours"|"minutes"|"seconds"{b}
   {b}kanbn burndown --n "days"|"hours"|"minutes"|"seconds"{b}
-    Normalise dates. Task created, started and completed times will be rounded down to the nearest day, hour, minute or second. This may cause task events to be grouped together.
+    Normalise dates. Task event times (history events or legacy created/started/completed dates) will be rounded down to the nearest day, hour, minute or second. This may cause task events to be grouped together.
     If this option is set to a blank or unsupported value, the normalisation mode will be automatically selected based on the date range.

package/docs/commands/gantt.txt

@@ -0,0 +1,36 @@
+{b}kanbn gantt{b}
+{b}kanbn gt{b}
+
+Show a gantt chart for tracked tasks.
+
+Tasks are ordered using `depends-on` relations when present. The chart uses task dates, workload, and the optional
+`postponed` metadata field to estimate when work can start.
+The rendered chart includes:
+  • A unified date axis at the bottom for easy time reference
+  • A vertical "now" line marking the current date (if within the chart range)
+  • Dependency arrows (└─→) showing which tasks depend on others
+  • Task bars with progress indicators: █ (completed), ▓ (in progress), ░ (not started)
+  • A blocked indicator (⧗) showing tasks delayed by dependencies
+
+Options:
+  {b}kanbn gantt --json{b}
+  {b}kanbn gantt -j{b}
+    Output raw data instead of rendering a chart. The data will be returned in JSON format.
+
+  {b}kanbn gantt --assigned "user"{b}
+  {b}kanbn gantt -a "user"{b}
+    Filter for tasks that are assigned to a particular user.
+
+  {b}kanbn gantt --column "column"{b}
+  {b}kanbn gantt -c "column"{b}
+    Filter for tasks in a particular column. This option can be repeated to include multiple columns.
+
+  {b}kanbn gantt --date "date"{b}
+  {b}kanbn gantt -d "date"{b}
+    Filter for tasks created within a specified date range.
+    If only one date is provided, show tasks created from this date up to the present date.
+    If more than one date is provided, show tasks created between the earliest and latest date.
+
+  {b}kanbn gantt --now "date"{b}
+  {b}kanbn gantt -n "date"{b}
+    Mock the current date used for the "now" line and single-date range filtering.

package/docs/commands/help.txt

@@ -19,6 +19,7 @@ Where {b}<command>{b} is one of:
   {b}sort{b} {d}..........{d} Sort a column in the index
   {b}sprint{b} {d}........{d} Start a new sprint
   {b}burndown{b} {d}......{d} View a burndown chart
+  {b}gantt{b} {d}.........{d} View a gantt chart
   {b}validate{b} {d}......{d} Validate index and task files
   {b}archive{b} {d}.......{d} Archive a task
   {b}restore{b} {d}.......{d} Restore a task from the archive

package/docs/index-structure.md

@@ -146,12 +146,15 @@ dueMessage
 column
 workload
 progress
+{...customFields}
 ```
 
 The default task template is `^+^_${overdue ? '^R' : ''}${name}^: ${created ? ('\\n^-^/' + created) : ''}`.
 
 This string can contain markup sequences. See [terminal-kit](https://github.com/cronvel/terminal-kit/blob/21607fb51749853dd9193c6aaf205b14c63b2768/doc/markup.md#markup) for markup reference.
 
+*Note: custom fields can also be interpolated into the task template, but only if they are defined in `customFields` (see below).*
+
 ### `dateFormat`
 
 The date format to use for dates on the kanbn board and burndown chart views. See [dateformat](https://www.npmjs.com/package/dateformat) for date format reference.
@@ -180,8 +183,24 @@ Additionally, if a custom field has type `date`, the custom field can have a str
 
 ### `{customFieldName}Columns`
 
-A list of column names. `{customFieldName}` should match a custom field with type `date`. When a task is created in or dragged into one of these columns, the matching custom field in the task can be set to the current time.
+A list of column names. `{customFieldName}` should be the name of a custom field with type `date` (see the `customFields` section above for more information).
+
+When a task is created in or dragged into one of these columns, the matching custom field in the task can be set to the current time.
 
 If the custom field has `updateDate` set to `once`, the field will only be updated if it doesn't already have a value.
 
 If the custom field has `updateDate` set to `always`, the field will be updated every time the task is moved into a linked column.
+
+Here's an example of how this could be used:
+
+* Assume we have added a column called `Testing`
+* In `index.md` (or `kanbn.json` / `kanbn.yml` if using a separate configuration file), we have:
+  ```
+  customFields:
+    - name: testedAt
+      type: date
+      updateDate: once
+  testedAtColumns:
+    - Testing
+  ```
+* When a task is moved into the `Testing` column and the task doesn't already have a `testedAt` value in its metadata, this value will be automatically populated with the current date/time.

package/docs/quick-start.md

@@ -55,7 +55,7 @@ This will show a kanbn board, something like this:
 kanbn edit "my-new-task" -t "Large"
 ```
 
-This will add a "Huge" tag to the task and modify the task's updated date. If you're using the default settings, this will also affect the task's workload.
+This will add a "Large" tag to the task and modify the task's updated date. If you're using the default settings, this will also affect the task's workload.
 
 Run `kanbn edit --help` for more information on editing tasks.
 

package/docs/task-structure.md

@@ -13,6 +13,7 @@ progress: 0.5
 started: 2021-03-21T04:58:38.653Z
 completed: 2021-03-21T04:58:38.653Z
 due: 2021-03-21T04:58:38.653Z
+postponed: 2021-03-20T04:58:38.653Z
 ---
 
 # Task Name
@@ -34,6 +35,26 @@ Task description...
 - author: Username
   date: 2021-03-31T07:47:05.775Z
   This is a comment...
+
+## History
+
+- type: created
+  date: 2021-03-18T02:08:42.293Z
+  column: Backlog
+- type: moved
+  date: 2021-03-21T04:58:38.653Z
+  fromColumn: Backlog
+  toColumn: In Progress
+- type: progress
+  date: 2021-03-22T09:30:00.000Z
+  fromProgress: 0.25
+  toProgress: 0.5
+- type: archived
+  date: 2021-03-31T07:47:05.775Z
+  fromColumn: In Progress
+- type: restored
+  date: 2021-04-01T10:00:00.000Z
+  toColumn: Backlog
 ```
 
 The task file can optionally begin with YAML front-matter containing task metadata.
@@ -96,6 +117,11 @@ The date and time that the task was completed.
 
 The date and time that the task is due to be completed.
 
+### `postponed`
+
+The date and time after which the task should be scheduled. Gantt chart rendering uses this value as an explicit
+start-floor when present.
+
 ## Sub-tasks
 
 This should be a list of strings. Each string can optionally start with `[ ]` (incomplete) or `[x]` (completed).
@@ -104,6 +130,27 @@ This should be a list of strings. Each string can optionally start with `[ ]` (i
 
 This should be a list of links to other task files. The link text can optionally begin with a relation type.
 
+The `depends-on` relation type is reserved for gantt scheduling. It means the current task should not start until the
+linked task has finished.
+
 ## Comments
 
 An array of comments, where each comment has an `author` and `date` property, and some text.
+
+## History
+
+An optional array of structured lifecycle events used for richer timeline reporting (including burndown).
+
+Supported event types:
+
+- `created`: requires `date` and `column`
+- `moved`: requires `date`, `fromColumn`, `toColumn`
+- `progress`: requires `date`, `fromProgress`, `toProgress`
+- `archived`: requires `date`, `fromColumn`
+- `restored`: requires `date`, `toColumn`
+
+Notes:
+
+- History entries are stored in the reserved `## History` section as list items.
+- `date` should be an ISO timestamp.
+- Additional fields (for example `author`) are preserved if present.

package/example/.kanbn/index.md

@@ -0,0 +1,63 @@
+---
+startedColumns:
+  - In Progress
+completedColumns:
+  - Done
+sprints:
+  - start: 2026-05-06T09:00:00.000Z
+    name: Foundation Sprint
+    description: Baseline product and infrastructure work.
+  - start: 2026-06-10T09:00:00.000Z
+    name: Workflow Sprint
+    description: Core team workflow and onboarding features.
+  - start: 2026-07-08T09:00:00.000Z
+    name: Stabilisation Sprint
+    description: Reliability and release readiness improvements.
+taskWorkloadTags:
+  Tiny: 1
+  Small: 2
+  Medium: 3
+  Large: 5
+  Huge: 8
+---
+
+# Example SaaS Project
+
+A realistic in-flight product board with active development, completed work, and future backlog items.
+
+## Backlog
+
+- [define-product-pricing-strategy](tasks/define-product-pricing-strategy.md)
+- [legal-review-terms-and-privacy](tasks/legal-review-terms-and-privacy.md)
+- [design-onboarding-checklist](tasks/design-onboarding-checklist.md)
+- [implement-feature-flags-foundation](tasks/implement-feature-flags-foundation.md)
+- [build-email-template-system](tasks/build-email-template-system.md)
+- [create-sandbox-environment-provisioner](tasks/create-sandbox-environment-provisioner.md)
+- [implement-data-retention-policy-jobs](tasks/implement-data-retention-policy-jobs.md)
+- [design-team-invite-expiry-flow](tasks/design-team-invite-expiry-flow.md)
+- [prototype-report-export-scheduler](tasks/prototype-report-export-scheduler.md)
+
+## Todo
+
+- [implement-project-creation-wizard](tasks/implement-project-creation-wizard.md)
+- [add-passwordless-login-option](tasks/add-passwordless-login-option.md)
+- [integrate-crm-lead-sync](tasks/integrate-crm-lead-sync.md)
+- [build-invoice-download-endpoint](tasks/build-invoice-download-endpoint.md)
+- [add-usage-alert-email-thresholds](tasks/add-usage-alert-email-thresholds.md)
+- [create-self-serve-cancellation-flow](tasks/create-self-serve-cancellation-flow.md)
+
+## In Progress
+
+- [build-tenant-settings-page](tasks/build-tenant-settings-page.md)
+- [implement-team-permissions-ui](tasks/implement-team-permissions-ui.md)
+- [optimize-dashboard-first-load](tasks/optimize-dashboard-first-load.md)
+- [migrate-legacy-events-to-new-schema](tasks/migrate-legacy-events-to-new-schema.md)
+- [implement-stripe-webhook-signature-check](tasks/implement-stripe-webhook-signature-check.md)
+
+## Done
+
+- [setup-ci-pipeline](tasks/setup-ci-pipeline.md)
+- [implement-user-signup-and-login](tasks/implement-user-signup-and-login.md)
+- [create-organization-switcher](tasks/create-organization-switcher.md)
+- [add-basic-activity-feed](tasks/add-basic-activity-feed.md)
+- [publish-internal-qa-checklist](tasks/publish-internal-qa-checklist.md)

package/example/.kanbn/tasks/add-basic-activity-feed.md

@@ -0,0 +1,53 @@
+---
+created: 2026-07-01T10:00:00.000Z
+updated: 2026-07-02T10:00:00.000Z
+tags:
+  - Billing
+  - Medium
+assigned: Sofia
+progress: 1
+started: 2026-07-03T10:00:00.000Z
+completed: 2026-07-04T10:00:00.000Z
+due: 2026-07-05T10:00:00.000Z
+---
+
+# Add Basic Activity Feed
+
+Add Basic Activity Feed for the SaaS platform roadmap.
+
+Focus is on incremental delivery with low-risk rollout and measurable outcomes.
+
+This shipped and has been validated for the current release.
+
+## Sub-tasks
+
+- [ ] Confirm acceptance criteria with product and engineering.
+- [ ] Document edge-cases and rollout notes for support.
+- [ ] Add final QA checklist items before release.
+
+
+## History
+
+- type: created
+  date: 2026-07-06T10:00:00.000Z
+  column: Backlog
+- type: moved
+  date: 2026-07-07T10:00:00.000Z
+  fromColumn: Backlog
+  toColumn: Todo
+- type: moved
+  date: 2026-07-08T10:00:00.000Z
+  fromColumn: Todo
+  toColumn: In Progress
+- type: progress
+  date: 2026-07-09T10:00:00.000Z
+  fromProgress: 0
+  toProgress: 0.5
+- type: progress
+  date: 2026-07-10T10:00:00.000Z
+  fromProgress: 0.5
+  toProgress: 1
+- type: moved
+  date: 2026-07-11T10:00:00.000Z
+  fromColumn: In Progress
+  toColumn: Done

package/example/.kanbn/tasks/add-passwordless-login-option.md

@@ -0,0 +1,34 @@
+---
+created: 2026-07-02T10:00:00.000Z
+updated: 2026-07-03T10:00:00.000Z
+tags:
+  - Billing
+  - Medium
+progress: 0
+due: 2026-07-04T10:00:00.000Z
+---
+
+# Add Passwordless Login Option
+
+Add Passwordless Login Option for the SaaS platform roadmap.
+
+Focus is on incremental delivery with low-risk rollout and measurable outcomes.
+
+This has a clear scope and is ready to be picked up next.
+
+## Sub-tasks
+
+- [ ] Confirm acceptance criteria with product and engineering.
+- [ ] Document edge-cases and rollout notes for support.
+- [ ] Add final QA checklist items before release.
+
+
+## History
+
+- type: created
+  date: 2026-07-05T10:00:00.000Z
+  column: Backlog
+- type: moved
+  date: 2026-07-06T10:00:00.000Z
+  fromColumn: Backlog
+  toColumn: Todo

package/example/.kanbn/tasks/add-usage-alert-email-thresholds.md

@@ -0,0 +1,35 @@
+---
+created: 2026-07-03T10:00:00.000Z
+updated: 2026-07-04T10:00:00.000Z
+tags:
+  - Growth
+  - Small
+assigned: Noah
+progress: 0
+due: 2026-07-05T10:00:00.000Z
+---
+
+# Add Usage Alert Email Thresholds
+
+Add Usage Alert Email Thresholds for the SaaS platform roadmap.
+
+Focus is on incremental delivery with low-risk rollout and measurable outcomes.
+
+This has a clear scope and is ready to be picked up next.
+
+## Sub-tasks
+
+- [ ] Confirm acceptance criteria with product and engineering.
+- [ ] Document edge-cases and rollout notes for support.
+- [ ] Add final QA checklist items before release.
+
+
+## History
+
+- type: created
+  date: 2026-07-06T10:00:00.000Z
+  column: Backlog
+- type: moved
+  date: 2026-07-07T10:00:00.000Z
+  fromColumn: Backlog
+  toColumn: Todo

package/example/.kanbn/tasks/build-email-template-system.md

@@ -0,0 +1,30 @@
+---
+created: 2026-07-04T10:00:00.000Z
+updated: 2026-07-05T10:00:00.000Z
+tags:
+  - Backend
+  - Medium
+progress: 0
+due: 2026-07-06T10:00:00.000Z
+---
+
+# Build Email Template System
+
+Build Email Template System for the SaaS platform roadmap.
+
+Focus is on incremental delivery with low-risk rollout and measurable outcomes.
+
+This is still in discovery and scoped as a future increment.
+
+## Sub-tasks
+
+- [x] Confirm acceptance criteria with product and engineering.
+- [ ] Document edge-cases and rollout notes for support.
+- [ ] Add final QA checklist items before release.
+
+
+## History
+
+- type: created
+  date: 2026-07-07T10:00:00.000Z
+  column: Backlog

package/example/.kanbn/tasks/build-invoice-download-endpoint.md

@@ -0,0 +1,43 @@
+---
+created: 2026-07-05T10:00:00.000Z
+updated: 2026-07-06T10:00:00.000Z
+tags:
+  - Platform
+  - Medium
+progress: 0
+due: 2026-07-07T10:00:00.000Z
+---
+
+# Build Invoice Download Endpoint
+
+Build Invoice Download Endpoint for the SaaS platform roadmap.
+
+Focus is on incremental delivery with low-risk rollout and measurable outcomes.
+
+This has a clear scope and is ready to be picked up next.
+
+## Sub-tasks
+
+- [ ] Confirm acceptance criteria with product and engineering.
+- [ ] Document edge-cases and rollout notes for support.
+- [ ] Add final QA checklist items before release.
+
+## Relations
+
+- [blocks create-self-serve-cancellation-flow](create-self-serve-cancellation-flow.md)
+
+## Comments
+
+- author: Liam
+  date: 2026-07-08T10:00:00.000Z
+  Captured initial implementation notes and identified one external dependency.
+
+## History
+
+- type: created
+  date: 2026-07-09T10:00:00.000Z
+  column: Backlog
+- type: moved
+  date: 2026-07-10T10:00:00.000Z
+  fromColumn: Backlog
+  toColumn: Todo

package/example/.kanbn/tasks/build-tenant-settings-page.md

@@ -0,0 +1,48 @@
+---
+created: 2026-07-06T10:00:00.000Z
+updated: 2026-07-07T10:00:00.000Z
+tags:
+  - Ops
+  - Small
+assigned: Ravi
+progress: 0.65
+started: 2026-07-08T10:00:00.000Z
+due: 2026-07-09T10:00:00.000Z
+---
+
+# Build Tenant Settings Page
+
+Build Tenant Settings Page for the SaaS platform roadmap.
+
+Focus is on incremental delivery with low-risk rollout and measurable outcomes.
+
+Implementation is active and this is currently being worked.
+
+## Sub-tasks
+
+- [ ] Confirm acceptance criteria with product and engineering.
+- [ ] Document edge-cases and rollout notes for support.
+- [ ] Add final QA checklist items before release.
+
+
+## History
+
+- type: created
+  date: 2026-07-10T10:00:00.000Z
+  column: Backlog
+- type: moved
+  date: 2026-07-11T10:00:00.000Z
+  fromColumn: Backlog
+  toColumn: Todo
+- type: moved
+  date: 2026-07-12T10:00:00.000Z
+  fromColumn: Todo
+  toColumn: In Progress
+- type: progress
+  date: 2026-07-13T10:00:00.000Z
+  fromProgress: 0
+  toProgress: 0.45
+- type: progress
+  date: 2026-07-14T10:00:00.000Z
+  fromProgress: 0.45
+  toProgress: 0.65

package/example/.kanbn/tasks/create-organization-switcher.md

@@ -0,0 +1,53 @@
+---
+created: 2026-07-07T10:00:00.000Z
+updated: 2026-07-08T10:00:00.000Z
+tags:
+  - Ops
+  - Small
+assigned: Ravi
+progress: 1
+started: 2026-07-09T10:00:00.000Z
+completed: 2026-07-10T10:00:00.000Z
+due: 2026-07-11T10:00:00.000Z
+---
+
+# Create Organization Switcher
+
+Create Organization Switcher for the SaaS platform roadmap.
+
+Focus is on incremental delivery with low-risk rollout and measurable outcomes.
+
+This shipped and has been validated for the current release.
+
+## Sub-tasks
+
+- [ ] Confirm acceptance criteria with product and engineering.
+- [ ] Document edge-cases and rollout notes for support.
+- [ ] Add final QA checklist items before release.
+
+
+## History
+
+- type: created
+  date: 2026-07-12T10:00:00.000Z
+  column: Backlog
+- type: moved
+  date: 2026-07-13T10:00:00.000Z
+  fromColumn: Backlog
+  toColumn: Todo
+- type: moved
+  date: 2026-07-14T10:00:00.000Z
+  fromColumn: Todo
+  toColumn: In Progress
+- type: progress
+  date: 2026-07-15T10:00:00.000Z
+  fromProgress: 0
+  toProgress: 0.5
+- type: progress
+  date: 2026-07-16T10:00:00.000Z
+  fromProgress: 0.5
+  toProgress: 1
+- type: moved
+  date: 2026-07-17T10:00:00.000Z
+  fromColumn: In Progress
+  toColumn: Done

package/example/.kanbn/tasks/create-sandbox-environment-provisioner.md

@@ -0,0 +1,36 @@
+---
+created: 2026-07-08T10:00:00.000Z
+updated: 2026-07-09T10:00:00.000Z
+tags:
+  - Ops
+  - Small
+progress: 0
+due: 2026-07-10T10:00:00.000Z
+---
+
+# Create Sandbox Environment Provisioner
+
+Create Sandbox Environment Provisioner for the SaaS platform roadmap.
+
+Focus is on incremental delivery with low-risk rollout and measurable outcomes.
+
+This is still in discovery and scoped as a future increment.
+
+## Sub-tasks
+
+- [ ] Confirm acceptance criteria with product and engineering.
+- [ ] Document edge-cases and rollout notes for support.
+- [ ] Add final QA checklist items before release.
+
+
+## Comments
+
+- author: Ravi
+  date: 2026-07-11T10:00:00.000Z
+  Captured initial implementation notes and identified one external dependency.
+
+## History
+
+- type: created
+  date: 2026-07-12T10:00:00.000Z
+  column: Backlog

package/example/.kanbn/tasks/create-self-serve-cancellation-flow.md

@@ -0,0 +1,38 @@
+---
+created: 2026-07-09T10:00:00.000Z
+updated: 2026-07-10T10:00:00.000Z
+tags:
+  - UX
+  - Large
+progress: 0
+due: 2026-07-11T10:00:00.000Z
+postponed: 2026-07-20T10:00:00.000Z
+---
+
+# Create Self-serve Cancellation Flow
+
+Create Self-serve Cancellation Flow for the SaaS platform roadmap.
+
+Focus is on incremental delivery with low-risk rollout and measurable outcomes.
+
+This has a clear scope and is ready to be picked up next.
+
+## Sub-tasks
+
+- [ ] Confirm acceptance criteria with product and engineering.
+- [x] Document edge-cases and rollout notes for support.
+- [ ] Add final QA checklist items before release.
+
+## Relations
+
+- [depends on add-usage-alert-email-thresholds](add-usage-alert-email-thresholds.md)
+
+## History
+
+- type: created
+  date: 2026-07-12T10:00:00.000Z
+  column: Backlog
+- type: moved
+  date: 2026-07-13T10:00:00.000Z
+  fromColumn: Backlog
+  toColumn: Todo

package/example/.kanbn/tasks/define-product-pricing-strategy.md

@@ -0,0 +1,37 @@
+---
+created: 2026-07-10T10:00:00.000Z
+updated: 2026-07-11T10:00:00.000Z
+tags:
+  - Product
+  - Small
+assigned: Ava
+progress: 0.1
+due: 2026-07-12T10:00:00.000Z
+---
+
+# Define Product Pricing Strategy
+
+Define Product Pricing Strategy for the SaaS platform roadmap.
+
+Focus is on incremental delivery with low-risk rollout and measurable outcomes.
+
+This is still in discovery and scoped as a future increment.
+
+## Sub-tasks
+
+- [x] Confirm acceptance criteria with product and engineering.
+- [x] Document edge-cases and rollout notes for support.
+- [ ] Add final QA checklist items before release.
+
+
+## Comments
+
+- author: Ava
+  date: 2026-07-13T10:00:00.000Z
+  Captured initial implementation notes and identified one external dependency.
+
+## History
+
+- type: created
+  date: 2026-07-14T10:00:00.000Z
+  column: Backlog