Functional Specification Document

Kavanah recognizes five kinds of actor. Role is assigned per workspace, so the same person may be an owner in one workspace and a member in another; the session carries the role of the workspace currently selected.

The agent never widens access

A persona's capability scopes are a ceiling, not a grant. When a member asks an agent to summarize a project they cannot see, the agent does not refuse on ethical grounds — the project is simply not in the result set it can read, and it answers as though the project does not exist. This is the same non-enumeration behavior described in section 9, applied to the agent's data path.

2.1 Creating work

A task is created from the board, the list view, a project page, the agent, an intake form, an automation rule, or the API. Creation requires a title; everything else — project, assignee, due date, status, custom fields — is optional and may be filled in later. A task created without a status enters open. A task created without a project is a workspace-level task and appears in the creator's own views but not on any project board.

2.2 Assignment

A task carries at most one assignee. Assigning notifies the new assignee; reassigning notifies the new assignee and leaves the prior assignee's notification history intact. A task may be deliberately left unassigned, in which case it is a candidate for the triage queue (section 6). Where a workspace has enabled automated routing, an unassigned task can be routed to the best-matched member and the decision is written to the assignment-decision ledger with the factors that produced it, so a lead can later ask why the system chose that person.

2.3 Status transitions

Status is a four-state model. All transitions are permitted in both directions — work moves backwards in the real world, and a product that forbids it produces lying boards — with one conditional gate: where a task has an approval configured, the move into completed is held until the designated approver records a decision.

2.4 Sub-tasks and dependencies

A sub-task is a task with a parent. It carries the same fields, statuses, assignee and due date as any other task and is completed independently — completing a parent does not silently complete its children, and open children do not hard-block a parent, they are shown as outstanding on it. Dependencies are a separate relation: declaring that task A is blocked by task B records the constraint, surfaces it on both tasks, and draws it on the timeline view. The dependency is advisory rather than enforced at the status layer, for the same reason transitions are bidirectional.

2.5 Dates, fields, and attachments

A due date may be set, changed, or cleared at any time. Overdue is a derived state, computed against the viewer's context rather than stored, so clearing a due date immediately clears the overdue treatment. Custom fields are defined once per workspace by an admin and then available on tasks; removing a field definition removes it from the task form. Attachments upload against the task and are retrievable by anyone who can view that task — access to an attachment is exactly access to its task, never a separate share.

2.6 Escalation and SLA behavior

SLA policies attach response and resolution expectations to work matching their conditions and track elapsed time against them. Escalation rules act when a task meets a configured condition — for example remaining unattended past a threshold — and produce a notification or assignment change. Both are admin-configured and workspace-scoped; a member sees their effects, not their definitions.

Filters are view-independent: switching from board to list or timeline preserves the active project, assignee, and field filters, so a user who has narrowed to one person's overdue work keeps that narrowing when they change how it is drawn. Every view is subject to access control — the counts on a board reflect what the viewer can see, not the true totals.

The client portal is a separate front door for external stakeholders. A portal user is invited against a specific client record and receives their own account; they are not workspace members, do not consume a workspace seat's permissions, and never obtain a workspace role.

What a portal user can never do

Portal users cannot see workspace member management, time entries, budgets, planning surfaces, usage analytics, integrations, audit logs, or any other client. They cannot invoke the AI agent. They cannot be granted a workspace scope without first being invited as a workspace member, which is a separate act with its own approval path.

Intake forms let people outside the workspace — internal colleagues without a seat, clients, the public — submit work without an account.

6.1 Timers and entries

A member logs time either by starting a timer against a task or by entering a duration directly. A member has at most one active timer; starting a second one stops the first and writes its entry rather than silently double-counting. Stopping a timer produces a normal time entry that can then be edited or deleted like any other. Members edit and delete their own entries; changes are visible in reporting immediately.

6.2 Reporting and budgets

Logged time aggregates by member, task, project, and period. Where a project has a budget, budget entries record committed and consumed amounts and the project reports consumption against its budget. Time reporting respects access control: a member sees their own time in full and project totals only for projects they can see.

6.3 Triage queue

Unassigned and unrouted work — typically from intake forms, integrations, or bulk creation — collects in a triage queue. A lead works the queue by assigning, deferring, or routing items. Automated routing, where enabled, drains the queue by matching work to member skill profiles and experience profiles, which are themselves updated from completed work, so the match improves as the workspace delivers.

The agent is not a text box that returns prose. A request becomes tool calls against the same authorization model that governs the UI, each one governed, recorded, and where possible reversible.

8.1 Safe mode versus approval parking

These are different mechanisms and both exist deliberately. Safe mode strips write tools entirely: the agent has no capability to change anything, so there is nothing to approve and no prompt to fatigue a user with. Approval parking applies when the agent does hold write capability but the action policy classifies a specific action as risky: the action is held, described, and executed only on explicit approval. A workspace can run permissive personas with parking and read-only personas in safe mode at the same time.

8.2 Personas

An AI Employee is a named identity with its own instructions, model selection, capability scopes, and list of members permitted to use it. Two personas in the same workspace can therefore have materially different reach — a research persona with read-only scopes available to everyone, and an operations persona with write scopes available to three leads. The persona's scopes narrow what tools exist; the invoking user's access narrows what data those tools return. Neither can widen the other.

8.3 Persistent agent context

Agent memory, follow-ups, goals, and runbooks give the agent continuity across conversations: what it has been told, what it promised to come back to, what it is working toward, and the procedure to follow for a recurring situation. Where scheduled runs are enabled, the agent executes on a schedule with no user present — and every governance stage above still applies, including parking, which simply waits for a human rather than proceeding unattended.

Quiet hours are a delivery control, not a filter: nothing is lost during quiet hours, it is simply not pushed at the user. When quiet hours end the in-app centre already holds everything that arrived.

10.1 Lacking access: non-enumeration

When a user lacks access to an object, Kavanah does not show the object and deny the action. The object is not listed: it is absent from search, absent from board and list results, excluded from counts and aggregates, and a direct request for its identifier is answered as though it does not exist. The rationale is that a “you may not view this task” message is itself a disclosure — it confirms the identifier is real, and often leaks a title. This applies uniformly to per-project access control, per-task access control, client-portal boundaries, and the workspace boundary itself.

10.2 Validation and conflicts

10.3 Deletion and recovery

Deleting a task or project moves it to trash, from which an authorized user restores it with its relationships intact. Deletion is therefore reversible by default rather than by support ticket. Where legal hold is applied to a user, project, or workspace, deletion is frozen outright and cannot be completed until the hold is lifted — hold takes precedence over any user-initiated erasure. Erasure performed through a GDPR or CCPA data-subject request is a separate, deliberate, owner-initiated act and is not reversible through trash.

10.4 Undoing agent actions

Agent actions with a defined inverse are reversible from the undo stack: the inverse operation is applied, and both the original action and the reversal appear in the action ledger. Actions with no meaningful inverse — an email that has already been sent, for instance — are exactly the class the action policy is configured to park for approval before they happen, because after-the-fact undo is not available for them.

The invariants below hold across every entry point — user interface, REST API, and agent tool call. They are the rules a test plan should assert directly.