Guru documentation

Projects, nested tasks, priorities, estimates and comments, with a list view and a board view drawn from identical data — the board always returns every status column, even the empty ones, so a column never silently disappears.

Will not: Sync in realtime — clients poll. Accept a task field whose key looks like a surveillance signal (keystroke, screenshot, idle_time, gps, location…) — that is a 403, with a redirect to set an estimate instead.

A blocks dependency is checked against every existing edge in the workspace before it is written — a depth-first walk from the proposed blocked task forward through the graph — and refused with a 409 the instant it would close a loop. Reading a task's dependencies also returns the whole transitive downstream tail, not just its direct successors.

Will not: Allow a dependency that would create a cycle, at any depth — refused before the write, not defended against later in a background job.

Per-week load summed from open tasks' own estimated minutes, computed fresh on every read and never stored. Unestimated tasks are counted separately rather than as zero, so a workload that looks light is never actually a task nobody sized yet.

Will not: Report anyone's throughput, completion rate or speed — not built, at any role. Sort people by how much they have on their plate — rows come back ordered by user id. Let a peer view another peer's workload — only an owner, admin, manager, or the person themselves can see it.

Daily, weekly and monthly rules run in the shop's own timezone. Every occurrence is keyed to a local wall-clock slot, unique at the database level, so a DST shift or calling generate twice cannot double-book the same occurrence. Pausing takes effect immediately, not at the next already-planned run.

Will not: Produce a second copy of an occurrence across a timezone change or a repeated call — the uniqueness is enforced by the database, not by trusting the caller. Keep generating after being paused until whatever was already scheduled finishes — the generator checks the pause flag at call time.

Facts, observations and gaps as three separate lists. Every observation carries the rule that produced it, and the gaps list names exactly what the data does not know — tasks stale for 30+ days, and tasks with no due date at all, which are invisible to every deadline check.

Will not: Use a language model to write the summary — it is assembled from task rows, so it cannot say anything the numbers do not.

A new SOP is always a draft. Editing changes the draft, never the published text — a published version is immutable, so a dispute or an audit can always answer 'which text did the staff member acknowledge.'

Will not: Let an edit change a published version's text in place — publishing closes the draft and opens the next one a version above it.

Assignment is keyed to a specific published version, so republishing an SOP reopens acknowledgment against the new text. A confirmation is yes/no plus a timestamp, with nowhere to put anything else.

Will not: Let anyone but the assignee confirm their own acknowledgment — not even a manager on their behalf. That is a 403: 'a confirmation somebody else pressed is not evidence they read it.' Assign against an unpublished SOP — that is a 409.

Templates copy their steps into a fresh instance at run time, so editing a template later cannot change a process somebody is halfway through. Completing a step out of order is refused, and reassignment is an append-only trail rather than an overwritten field. A template can now also carry a recurrence rule, using the same local-slot idempotency device recurring-task-templates uses, and generating the runs due in a horizon is safe to call repeatedly or from any scheduler. A separate route flags an in-progress run untouched for two weeks or more, apart from ordinary open work, so a stalled process reads as something to act on rather than routine backlog.

Will not: Complete a step before an earlier one closes — that is a 409 naming which step is still open, unless the step is explicitly skipped. Double-generate an occurrence that already exists — recurring runs use the same unique local-slot device as recurring task templates, so calling generate twice cannot duplicate one.

Folder-pathed pages carry a last-reviewed date and a computed staleness flag on every read (180 days since the last review or edit). Confirming a page is 'still correct' is a separate action from editing it, so a staff member does not have to touch the text to say they checked it.

Will not: Run a ranked full-text search — it is a case-insensitive substring match across title and content, said plainly rather than presented as more than it is. Mark a page reviewed just because someone opened it — reviewing is an explicit confirm action.

Decisions are kept structurally separate from prose, and any action item converted into a task carries a permanent link back to the note it came from.

Will not: Record, transcribe or join a call — a note is only ever what a person typed. The specification puts capturing a live call out of scope entirely.

A goal's current_value rolls up from the weighted completion of the tasks and projects linked to it — nobody types in a progress number by hand. A link's weight is refused if it would push a goal's total past 100%, so the same piece of work cannot be double-counted into one goal's progress, and the rollup recalculates inline the instant a linked task or project's status changes. 'Achieved' is set only from that real completion — a person can only move a goal to 'abandoned' by hand.

Will not: Accept a progress percentage or 'achieved' status typed directly — current_value is computed from real linked completion, and status can only be set to 'abandoned' through the edit route. Let a workspace link the same task or project into a goal twice, or link weights past 100% of a goal's total.

Setting a cadence on a goal schedules its first review; completing a review schedules the next one per that same cadence, so nothing regenerates a sitting that was never actually held — a due-list flags an overdue one instead of silently doubling it. Review notes are visible only to the goal's own owner and to an owner, admin or manager, the same visibility rule the workload view already applies to a person's own data.

Will not: Auto-generate a second review on top of one that was simply never completed — /goal-reviews/due names the overdue one instead. Show a review's notes to anyone but the goal's owner or a manager — a peer cannot read another person's goal-review commentary.

An opt-in mode, not a default every task list gets. Closing a sprint can optionally roll only its incomplete tasks into a named follow-on sprint, preserving which sprint a task was originally committed to — nothing closes or rolls on its own, and /sprints/overdue names what a human or a scheduler could act on. Daily burndown is a route callable more than once a day, upserting that day's point rather than duplicating it.

Will not: Auto-close a sprint on its end date, or auto-roll its tasks — closing, and rolling, both need an explicit call naming what to do. Force every project into sprints — a project with no sprint simply has none.

Skill tags and weekly availability are stored per person and visible only to that person and their manager, never team-wide. Matching a task to who could take it reports only the required tags a candidate has or lacks against a task category's eligibility rule — never a candidate's whole skill sheet — which is the direct answer to the specification's own warning against this becoming a ranked leaderboard.

Needs: is_on_leave is set by hand today. Syncing it automatically from an approved leave request needs a payroll or HR module this deployment does not have.

Will not: Show a candidate's full skill sheet to a task's assigner — only whether they meet each required tag for that specific task. Let a peer set or read another peer's skill tags or availability — self, or a manager, only. Flip is_on_leave on its own from a leave request — nothing here reads a leave-approval workflow that does not exist yet.

Its own three tables rather than a reuse of process-checklist's, so HR-sensitive visibility is enforced by construction: an onboarding instance is readable by the employee themselves and by an owner, admin or manager — never an unrelated peer. Steps complete in order, the same gate process-checklist uses, and a step naming no assignee defaults to the new hire's own task rather than to nobody.

Will not: Let an unrelated peer read a colleague's onboarding progress — only the employee themselves, or an owner, admin or manager. Let a later step close before an earlier one does — the same in-order completion gate process-checklist enforces. Change a ramp-up already in progress when its template is edited later — steps are copied into the instance at start time. Let a step's assignee complete it unless they are the new hire themselves or an owner, admin or manager. Completion runs through the same HR-sensitive visibility rule as reading the instance, so a step assigned to an unrelated colleague (IT, facilities) is refused with a 403 when that colleague tries to tick it off — assign such steps to the new hire or to a manager, and have the colleague confirm out of band.

Steps are decided strictly in order. Every step carries a delegate from the moment the request is created — not added later, once a single-approver bottleneck has already blocked the business. Personnel requests (hiring, firing, pay change, promotion, disciplinary action) cannot be approved by their own requester.

Will not: Let a request resolve itself on a timeout — reminders nudge; there is no auto-approve-after column and no default decision anywhere in the schema. Let a non-human actor decide anything — 'system', 'bot', 'cron' and similar are refused; an approval needs a named person. Let a requester approve their own hiring, firing, pay-change, promotion, demotion, disciplinary or leave-denial request — self-approval on a non-personnel request (a stationery order) is fine.

The token is stored only as a SHA-256 digest and shown once at creation. A fixed field allowlist governs what a client link can ever expose, checked again at read time even if a stored value were ever corrupted, and the projection function is never given a comment, an assignee or another project to begin with.

Will not: Store the plaintext token anywhere, or show it again after creation. Run longer than 180 days — expiry is mandatory, not a nullable field. Read a comment, an assignee or another project through the portal — the internal data is never fetched, not fetched and then hidden. Keep a per-visit log of who looked — only a view count and the last-viewed timestamp are kept, because a per-visit access log of a named outside person is the same surveillance record Guru refuses to keep about staff.

Operations metrics (open tasks, overdue tasks, unassigned tasks, pending approvals, outstanding SOP acknowledgments, running processes) are all workspace-wide counts, none per-person. Business metrics — open conversations, open leads, pipeline value — are fetched from Ank unchanged and returned with the SQL that produced them. A per-user widget layout can now be saved, and each widget's figure is refreshed lazily on read past a five-minute interval rather than recomputed on every single request. Restricted to an owner, admin or manager, matching the access the underlying company-wide data already requires.

Will not: Compute a second version of a number Ank already answers — two counts of the same thing that could disagree by a join is worse than one dashboard. Answer a metric question outside a closed, published list — /operations-metrics enumerates exactly what Guru counts. Let anyone below owner, admin or manager view it — matching the access the underlying company-wide numbers already require.

Workspace member. Projects, nested tasks, priorities, estimates and comments, with a list view and a board view drawn from identical data — the board always returns every status column, even the empty ones, so a column never silently disappears.

{ "title": "Draft the vendor contract", "priority": "high",
  "due_date": "2026-08-22", "estimated_minutes": 90, "assignee_user_id": "u_204" }

{ "id": "…", "project_id": "…", "title": "Draft the vendor contract",
  "status": "todo", "priority": "high", "estimated_minutes": 90,
  "assignee_user_id": "u_204", "created_at": "…" }

Workspace member. Every status appears as a key, even with zero tasks in it.

{ "project": {…}, "statuses": ["todo","in_progress","blocked","done","skipped","cancelled"],
  "columns": { "todo": [ {…task…} ], "in_progress": [], "blocked": [], "done": [], "skipped": [], "cancelled": [] },
  "total": 1 }

Workspace member. If t_881 already (transitively) depends on t_902, this is a 409: "That would make a loop — these tasks would each be waiting for the other, and neither could ever start."

{ "blocking_task_id": "t_881", "type": "blocks" }

{ "id": "…", "blocking_task_id": "t_881", "blocked_task_id": "t_902", "type": "blocks" }

Workspace member. `ripple` is the full downstream tail, walked transitively, not only the direct successor.

{ "task_id": "…", "waiting_for": [ {…} ], "blocked_now": true,
  "open_blockers": [ { "id": "…", "title": "Sign vendor contract", "status": "todo" } ],
  "ripple": [ "t_910", "t_944" ] }

Self, or owner/admin/manager for anyone else. Requesting another person's id without a manager role is a 403.

{ "week_of": "2026-08-17", "people": [
  { "user_id": "u_101", "assigned_minutes": 420, "unestimated_tasks": 1, "task_count": 5,
    "over_by_minutes": null, "basis": "Sum of estimated minutes on open tasks assigned to this person and due in this week. …" },
  { "user_id": "u_204", "assigned_minutes": 900, "unestimated_tasks": 0, "task_count": 6, "over_by_minutes": 100 } ],
  "note": "Built only from tasks the team entered — an estimate somebody typed and a due date somebody set. Guru holds no record of how anyone spent their time, and reports no per-person speed or completion rate." }

Workspace member. Safe to call repeatedly — an occurrence already generated is skipped, not duplicated.

{ "horizon_days": 14, "created": 3, "already_existed": 1, "tasks": [ {…}, {…}, {…} ] }

Workspace member. Facts, observations and gaps as three separate lists. Every observation carries the rule that produced it, and the gaps list names exactly what the data does not know — tasks stale for 30+ days, and tasks with no due date at all, which are invisible to every deadline check.

{ "text": "Rebrand website: 3 of 8 tasks done, 5 still open. 1 overdue. Read with care: 2 tasks have no due date.",
  "facts": [ { "label": "Overdue", "value": 1 } ],
  "observations": [ { "observation": "1 task is past its due date.", "basis": "…" } ],
  "gaps": [ { "gap": "2 tasks have no due date.", "detail": "They cannot be overdue and are invisible to every deadline check." } ] }

Workspace member. Publishing with no draft is a 409; publishing a draft with no steps is a 400. Every prior assignment against the old version is carried forward at the new version number, which is why 4 people were reassigned for acknowledgment here.

{ "id": "…", "state": "published", "current_version": 2,
  "published_version": { "version_number": 2, "state": "published", "published_at": "…" },
  "reassigned_for_acknowledgment": 4 }

The assignee only. Called by anyone other than the assignee, this is a 403 naming exactly that: only the person it was assigned to can confirm they read it.

{ "assignment_id": "…", "acknowledged": true, "acknowledged_at": "…" }

Workspace member. If an earlier step in the same instance is still pending or in_progress, this is a 409 naming that step, unless skip is set.

{ "skip": false, "note": "Confirmed with the client by phone." }

{ …process instance, with this step's status now "done"… }

Workspace member. Two weeks or more untouched, reported apart from ordinary open work.

{ "items": [ { "id": "…", "template_name": "Vendor onboarding", "status": "in_progress", "days_untouched": 16 } ], "total": 1 }

Workspace member. Folder-pathed pages carry a last-reviewed date and a computed staleness flag on every read (180 days since the last review or edit). Confirming a page is 'still correct' is a separate action from editing it, so a staff member does not have to touch the text to say they checked it.

{ "query": "refund", "items": [ { "id": "…", "title": "Refund policy", "folder": "policies/customer", "stale": false } ], "total": 1 }

Workspace member. Decisions are kept structurally separate from prose, and any action item converted into a task carries a permanent link back to the note it came from.

{ "project_id": "…", "items": [ { "title": "Send the revised quote", "assignee_user_id": "u_204" } ] }

{ "meeting_note_id": "…", "tasks": [ { "id": "…", "source_meeting_note_id": "…", … } ] }

Workspace member. A weight that would push the goal's linked total past 100% is refused with a 400 before it is written.

{ "linked_type": "task", "linked_id": "t_881", "weight": 0.25 }

{ "id": "…", "goal": { "id": "…", "title": "Launch the loyalty programme",
  "target_value": 1, "current_value": 0, "progress_pct": 0, "status": "active" } }

The goal's owner, or an owner/admin/manager. Setting a cadence on a goal schedules its first review; completing a review schedules the next one per that same cadence, so nothing regenerates a sitting that was never actually held — a due-list flags an overdue one instead of silently doubling it. Review notes are visible only to the goal's own owner and to an owner, admin or manager, the same visibility rule the workload view already applies to a person's own data.

{ "frequency": "monthly" }

{ "goal_id": "…", "frequency": "monthly", "next_review": { "id": "…", "scheduled_for": "…", "status": "scheduled" } }

Own goals, or every goal for an owner/admin/manager. Setting a cadence on a goal schedules its first review; completing a review schedules the next one per that same cadence, so nothing regenerates a sitting that was never actually held — a due-list flags an overdue one instead of silently doubling it. Review notes are visible only to the goal's own owner and to an owner, admin or manager, the same visibility rule the workload view already applies to a person's own data.

{ "items": [ { "id": "…", "goal_title": "Launch the loyalty programme", "days_overdue": 3, "status": "scheduled" } ], "total": 1 }

Workspace member. Rolling is opt-in per call — omit roll_incomplete_to_sprint_id and the sprint just closes.

{ "roll_incomplete_to_sprint_id": "spr_204" }

{ "id": "spr_190", "status": "closed", "closed_at": "…" }

Workspace member. An opt-in mode, not a default every task list gets. Closing a sprint can optionally roll only its incomplete tasks into a named follow-on sprint, preserving which sprint a task was originally committed to — nothing closes or rolls on its own, and /sprints/overdue names what a human or a scheduler could act on. Daily burndown is a route callable more than once a day, upserting that day's point rather than duplicating it.

{ "sprint_id": "…", "points": [ { "day": "2026-08-17", "remaining_points": 34 }, { "day": "2026-08-18", "remaining_points": 29 } ], "total": 2 }

Workspace member. Skill tags and weekly availability are stored per person and visible only to that person and their manager, never team-wide. Matching a task to who could take it reports only the required tags a candidate has or lacks against a task category's eligibility rule — never a candidate's whole skill sheet — which is the direct answer to the specification's own warning against this becoming a ranked leaderboard.

{ "task_id": "…", "task_category": "electrical", "required_skill_tags": ["licensed_electrician"],
  "items": [ { "user_id": "u_204", "eligible": true, "missing_skill_tags": [], "available": true } ],
  "total": 1, "note": "'available' reflects this task's due date's weekday against stored availability; a person with no availability row is treated as available rather than as on leave." }

Workspace member. A step with no assignee_user_id in the template defaults to the new hire's own task, not to nobody. Both steps above are assigned to the new hire on purpose: only the employee themselves or an owner/admin/manager can complete a step, so assigning one to an unrelated colleague produces a step nobody who holds it can close.

{ "employee_user_id": "u_310" }

{ "id": "…", "employee_user_id": "u_310", "status": "in_progress",
  "steps": [ { "step_order": 1, "title": "Sign the offer letter", "assignee_user_id": "u_310", "status": "in_progress" },
             { "step_order": 2, "title": "Provision laptop", "assignee_user_id": "u_310", "status": "pending" } ] }

Workspace member. Steps are decided strictly in order. Every step carries a delegate from the moment the request is created — not added later, once a single-approver bottleneck has already blocked the business. Personnel requests (hiring, firing, pay change, promotion, disciplinary action) cannot be approved by their own requester.

{ "type": "hiring", "title": "Hire a second stylist",
  "steps": [ { "approver_user_id": "u_owner", "delegate_user_id": "u_manager" } ] }

{ "id": "…", "status": "pending", "current_step": 0, "steps": [ {…} ] }

The current step's approver or delegate. The requester deciding their own hiring request is a 403. A non-human actor id is a 403. Someone who is neither the approver nor the delegate on the current step is a 403.

{ "decision": "approved", "comment": "Budget confirmed." }

{ …request, status now "approved" or advanced to current_step + 1… }

Workspace member. The token is stored only as a SHA-256 digest and shown once at creation. A fixed field allowlist governs what a client link can ever expose, checked again at read time even if a stored value were ever corrupted, and the projection function is never given a comment, an assignee or another project to begin with.

{ "label": "For the client's PM", "expires_in_days": 30, "visible_fields": ["name","status","due_date"] }

{ "id": "…", "token": "kX9f…(shown once)", "token_prefix": "kX9fA2b1",
  "expires_at": "…", "visible_fields": ["name","status","due_date"],
  "note": "Copy the token now. Only a hash of it is stored, so it cannot be shown again." }

Unauthenticated — a valid, unexpired, unrevoked token is the only credential. An invalid, expired or revoked token, and a token that never existed, all return the identical 404 — deliberately indistinguishable.

{ "project": { "name": "…", "status": "active", "due_date": "…" },
  "milestones": [ { "title": "…", "status": "in_progress", "due_date": "…" } ], "note": "…" }

Owner, admin or manager. Operations metrics (open tasks, overdue tasks, unassigned tasks, pending approvals, outstanding SOP acknowledgments, running processes) are all workspace-wide counts, none per-person. Business metrics — open conversations, open leads, pipeline value — are fetched from Ank unchanged and returned with the SQL that produced them. A per-user widget layout can now be saved, and each widget's figure is refreshed lazily on read past a five-minute interval rather than recomputed on every single request. Restricted to an owner, admin or manager, matching the access the underlying company-wide data already requires.

{ "window_days": 30,
  "operations": [ { "slug": "guru-tasks-overdue", "value": 4, "counted": "…", "sql": "…" } ],
  "business": [ { "slug": "leads-open", "value": 12, "counted": "…", "sql": "…" } ],
  "note": "…" }

Owner, admin or manager. Per-user — one manager's saved arrangement never changes what another manager sees.

{ "widgets": ["ops-overdue", "goals", "leads-open"] }

{ "widgets": ["ops-overdue", "goals", "leads-open"] }