---
url: /handbook/discovery/task-cards.md
description: >-
  One piece of recurring work: what a Task Card holds, how it becomes evidence,
  and how it relates to an agent's permissions today and in the target design.
---

# Task Cards

A **Task Card** describes one piece of recurring work: what triggers it, the steps, the systems it touches, who owns it and who performs it.

In governance, a Task Card is not a standard operating procedure (SOP). It is evidence that a real person does this work. The target is that it also becomes the **record of business necessity** for each permission an agent holds. Today that second role is **Partial**. See [What links a Task Card to scopes today](#what-links-a-task-card-to-scopes-today).

## What a Task Card holds

| Field | Example |
| --- | --- |
| Owner | The person accountable for the work |
| Performer | The person who does the work today |
| Duty | The ongoing responsibility the task belongs to |
| Trigger and frequency | "Every Monday, after the vendor statement arrives" |
| Inputs and output | What arrives, and what the finished result looks like |
| Steps | Each step is marked `[H]` human, `[A]` AI or `[S]` shared |
| Systems | The systems the work touches, linked to the [System Catalog](../governance/system-catalog.md) |
| Human gate | Where a person must check or decide |
| AI mode | A proposed mode, such as "AI drafts for review" or "AI not allowed", with a plain reason |
| Hours | Hours a week, from the person's own answer |
| State | The Repo state of the card's file: Inferred, Observed, Confirmed, Proposed or Disputed |

A Task Card lives in the [Company Repo](company-repo.md) at `tasks/<slug>/task.md`, with a stable id such as `TSK-3fa85f64`. Where a prompt exists, a runbook sits beside it as `run.md`.

### AI modes

Every mode other than "People only" is a **proposed** mode. A proposed mode is not an approved agent.

People only · AI assists the person · AI drafts for review · AI recommends, a person decides · AI acts after a person approves · AI acts within set limits · AI not allowed

"People only" and "AI not allowed" never lead to a proposed agent.

### Hours

Hours come from the person who does the work. They tap a range on the [team ask](team-asks.md), such as "5–10 hours". Code reads the range with no AI and records a **Reported** reading. Hours can also come from runs a month × minutes per run. A card with no hours shows **time not captured**. It never shows 0.

## Where Task Cards come from

* **Draft task cards.** In Discovery, the advisor accepts a returned answer and selects **Draft task cards**. This uses OpenAI. Each drafted card is Proposed and Inferred.
* **Create task card from this answer.** The advisor selects a passage in an answer and writes the card. The person who answered is the performer, and their answer is the evidence.
* **Proposals from answers.** With an approved AI connection, DutyGraph reads answers and proposes Task Cards in **Repo › To review**.
* **By hand.** In **Work Map › Task Cards**, select a card, then **Open Task Card** and **Edit record**.

After a card is drafted or changed, a code-only pass proposes an AI mode with its reason, the performer, and the performer's manager as the owner. Each proposal waits in **Repo › To review**. Nothing applies until the advisor accepts it.

## How a Task Card becomes evidence

### The person describes the work

The person who does the work answers a team ask, usually on their phone. DutyGraph stores the answer "as understood".

### DutyGraph drafts the card

The card is Proposed and Inferred. An owner or a role can be missing. The card says so.

### The advisor reviews it

The advisor accepts the answer, assigns an owner and marks the card reviewed. A reviewed card stays Inferred until a person's accepted confirmation backs it.

### The people confirm it

**Prepare personal task checks** asks the owner and the performer to confirm the exact version. A confirmation moves the card to Observed or Confirmed. It is recorded, not a signature. A changed description needs another check.

### An agent request pins it

When an agent is requested, the manifest pins the Task Card by **record version and content hash**. A later edit does not silently change what was approved.

A card whose review date has passed shows as Disputed, and `findings/gaps.md` lists it.

## From work to authority: five different things

Confirmed work is not the same as approved access. DutyGraph keeps these apart.

| Layer | Question it answers | Who establishes it | Status |
| --- | --- | --- | --- |
| **Task existence** | Does this work happen, and who owns and performs it? | The owner and performer confirm | Built |
| **Steps** | How is the work done, step by step? | The performer describes; steps are marked `[H]`, `[A]` or `[S]` | Built, as text |
| **Business capabilities** | What action does each step require, in business terms? | Proposed from the steps; the manager confirms | Planned |
| **Technical entitlements** | Which permission in which system provides that capability? | An application or IAM owner validates the mapping | Planned |
| **Authorization (Agent Grant)** | What authority is issued to this one agent, and under which conditions? | The [approval chain](../governance/approval-chain.md) decides; IAM issues | Built for approval and issuance; Partial for its link to the layers above |

```mermaid
flowchart LR
    TC["Task Card<br/>confirmed work<br/>Built"] --> ST["Task step<br/>human, AI or shared<br/>Built"]
    ST --> BC["Business capability<br/>the action the step needs<br/>Planned"]
    BC --> TE["Technical entitlement<br/>a permission in one system,<br/>validated by its owner<br/>Planned"]
    TE --> AG["Agent Grant<br/>authority issued to one agent<br/>under conditions<br/>approval Built, link Partial"]
    classDef built fill:#d9f2e3,stroke:#2e7d4f,color:#123;
    classDef partial fill:#fff3cd,stroke:#a07800,color:#321;
    classDef planned fill:#eeeeee,stroke:#888,color:#333,stroke-dasharray: 4 3;
    class TC,ST built;
    class BC,TE planned;
    class AG partial;
```

In the target design, each mapping carries its source, evidence, version, validator, confirmation state and effective dates. The evaluator would allow a scope only when confirmed work needs it, the owner holds it and every rule allows it. Missing evidence would fail closed.

## What links a Task Card to scopes today

Today the link is coarse.

* DutyGraph takes the scope lines listed on the Task Card in the scope grammar, `system/action:object`.
* If the card lists none, it treats **every catalog scope of the systems the card names** as needed.
* When the System Catalog is built from Task Cards and a system has no listed scopes, that system gets generic read and update scopes.

The evaluator does not yet limit an agent's requested scopes to this set. It checks that each selected Task Card exists, then keeps scopes within the owner's holdings and the rules. See [The key join](../governance/the-key-join.md).

## Holdings are a ceiling, not a justification

An agent's scopes must stay within its owner's [holdings](../governance/holdings.md). That is a ceiling. It is not a reason to grant a scope.

An employee may hold highly privileged access. A scope inside their holdings can still be unnecessary, or unsafe, for an agent. A wrong Task Card is a real risk, not a harmless one. Each permission an agent holds must be:

* **necessary** for confirmed work;
* **justified** by evidence a reviewer can read;
* **approved** by the right people; and
* **controlled** for its whole lifetime.

Until the Task Card requirement check is enforced, approvers should check each scope against the work themselves.

A confirmed Task Card records that the work exists and who does it. It does not approve company policy or give anyone permission to act.

## Mission lineage (Planned)

::: warning
**Planned.** Mission lineage is not built.
:::

Each task would link to why it exists: a strategic goal, a department mandate, a compliance control, a legal requirement, a contract, an operational dependency or a customer commitment. The Repo's existing **Up**, **Down** and **Across** links would carry these links.

A task with no confirmed reason would be marked **Unresolved Mission Lineage**. That never means the task is unnecessary. It means nobody has confirmed why it exists yet.

::: info
**Status.** **Built:** Task Cards with `[H]`, `[A]` and `[S]` steps, proposed AI modes, reported hours, **Draft task cards** (needs OpenAI), the code-only proposals for modes and owners, personal task checks, and manifest pinning. **Partial:** the link from a Task Card to scopes, which is coarse and not enforced by the evaluator. **Simulated:** the hours and predictions on the sample companies are authored sample values, labelled "sample". **Planned:** business capabilities per step, entitlement mappings validated by application owners, mission lineage, and [Just-in-time task capture](../roadmap/just-in-time-task-capture.md).
:::
