Timewarrior Project
===================
Timewarrior is a program that records tagged time blocks that represent tracked
time. This data is then used to create reports that shwo how time was spent.

To make this task easier, and more useful, Timewarrior can access holidays, a
pre-defined working schedule, and support flexible time/date specifications,
implement a simple stop-watch tracking feature, generate custom reports, and
apply a set of rules to impose constraints and check the data.

Using a hook scripts, Timewarrior can be used as a backend time-tracking
feature for Taskwarrior, any other program, or as a standalone utility.

Timewarrior aims to be the tool of choice if you need to track time and generate
timesheets.


Goals
-----
- Provide a personal tools to easily track time spent and generate reports with
  low friction.
- Support all workflows.
- Provide an extension-friendly tool.
- Support policies via the rules system.
- Integrate with Taskwarrior, Tasksh.
- Store data in plain UTF-8 text.


Non-Goals
---------
- Completely independent from Taskwarrior, Taskserver, Tasksh.
- No cloud support, no sync support, all data is local. Tracked time is
  sensitive personal data and wll not be transmitted.
- No explicit multi-user support, although using tags to track individuals is
  possible.
- There is no hook system as Timewarrior is a data sink, not a data source.
- No features without a compelling use case.


Tags
----
Tags represent tracking categories. Tags are arbitrary UTF8 strings. A tag may
be a single unquoted word, or a quoted string if it includes spaces.

A tag may be used without being defined, but if a tag is defined, then it may
have associated metadata, such as a start date representing the first date on
which it may be used, or an end date, when it expires. A tag may have a budget,
which is the maximum trackable time for a period.

An interval may have multiple tags associated with it, but the tags apply to the
whole interval only. In this example, there are overlapping tags:

  $ timew start tag1
  ...
  $ timew start tag2
  ...
  $ timew stop tag1
  ...
  $ timew stop

By default, when the interval for 'tag2' starts, the interval for 'tag1' is
automatically stopped, because tags do not overlap. This then makes the next
command ('timew stop tag1') yield an error, because 'tag1' was not active. If
however, both 'tag1' and 'tag2' are defined with the 'overlap' metadata, then
there will not be an automatic stop for 'tag1'.


Macros
------
A macro is a keyword that can take arguments, and expands to a set of one or
more other timew commands, with some dynamic aspect. For example, the macro
named 'staff meeting' could be an interval that is on Wednesdays at 10:00, and
has a set of associated tags. This would then create an appropriately tagged
interval.


Commands
--------
The command set may include:

  define         Modify configuration
  track          Record tracked time
  report         Run a report
  undo           Undo a change
  tags           Show all tags
  gaps           Show untracked gaps in the schedule
  import         Import JSON data
  export         Export JSON data
  help           Show help text
  x              Run extension 'x'


Undo
----
All commands than change configuration or data need to be logged as-is in the
undo.data file, so that an 'undo' command can later rewind the changes.

All undo will happen at the command level, not the delta level.


Extensions
----------
A simple extension mechanism allows custom reports to be written and shared.

---

- Given this:
    $ timew track yesterday 9am - 5pm tag1
  What does this do:
    $ timew track yesterday 10am - 11am tag2
  Does it yield:
    a) yesterday 540-1020 tag, 600-660 tag2                      # overlap
    b) yesterday 540-600 tag1, 600-660 tag2, 660-1020 tag1       # no overlap
    c) yesterday 540-600 tag1, 600-660 tag1 tag2, 660-1020 tag1  # explicit overlap
  Stating 'track yesterday 10am - 11am tag2' sounds imperative, thus overriding any existing tags in that interval. Perhaps a 'merge' keyword could be added to combined the results (track yesterday 10am - 11am tag2 merge)?

- Need an undo feature.

- Intervals for different tags may overlap. We multitask.

- Need syntax to adjust any recorded data.

- It should be forgiving when you forgot to stop a task. Maybe a specific command, instead of "stop" use "forgot" or directly "edit".  Then I would like to express either "stopped 30min ago" or "it lasted only 1hour”.

- There is no hook system, but there will be rules that accomplish the same thing, almost.