# Personal TODO Agent Interface

Audience: autonomous or semi-autonomous agents with GitHub access to the private
dashboard repository.

This document is the agent operating contract. Treat it as a small set of
predefined skills plus data contracts. It is not a public write API. The
dashboard is read by humans, but agents submit durable updates by changing
repository files, validating them, committing, and pushing.

## Decision

Use repository-backed JSON as the write interface for v1.

- Do not build or call a public write API.
- Do not write directly to Cloudflare D1, KV, or browser local storage.
- Do not use the private dashboard login as an agent authentication mechanism.
- Use the app-internal APIs only when testing the app itself, not when
  submitting agent updates.

Current app-internal APIs:

- `GET /api/session`: dashboard role discovery behind Cloudflare Access.
- `GET|PUT|POST /api/student-statuses`: owner/teacher UI persistence for manual
  student status chips, backed by D1 with KV fallback.

Those APIs are intentionally not the agent submission interface. Durable agent
updates belong in `src/data/*.json` or `src/data/project-progress/*.json`.

## Repository Target

| Field | Value |
| --- | --- |
| GitHub repository | `neardws/personal-todo-dashboard` |
| HTTPS remote | `https://github.com/neardws/personal-todo-dashboard.git` |
| Default branch | `main` |
| Local working directory | `/Users/neardws/Documents/TODO` |
| Private dashboard | `https://todo.neardws.com` |
| Public agent docs | `https://todo-agent.neardws.com` |
| Private Pages project | `personal-todo-dashboard` |
| Public docs Pages project | `personal-todo-agent-docs` |

Required local checks before committing:

```bash
npm run validate:data
npm run build
```

Preferred extra check:

```bash
npm run lint
```

## Operating Loop

1. Identify the requested skill from the table below.
2. Read the relevant existing JSON before editing; preserve current style,
   ordering, IDs, and wording patterns.
3. Make the smallest file change that represents the new source evidence.
4. Do not touch unrelated files or pre-existing unrelated changes.
5. Run `npm run validate:data` and `npm run build`.
6. Run `npm run lint` unless the owner explicitly asks for a faster local-only
   edit.
7. Commit and push to `main` only when the owner requested publishing or the
   task explicitly includes the normal publish flow.

If a source is ambiguous, stop and report the ambiguity instead of guessing.

## Predefined Agent Skills

| Skill | Use when | Read first | Write target | Verification |
| --- | --- | --- | --- | --- |
| `project-progress-update` | Add a dated update for an existing fund or industry project | `src/data/projects.json` | Append one file in `src/data/project-progress/` | `npm run validate:data` |
| `project-master-update` | Add or change a top-level fund/industry project | `src/data/projects.json` | Edit `src/data/projects.json` | `npm run validate:data` |
| `paper-status-sync` | Sync journal submission state from IEEE or another visible portal/source | `src/data/paper-submissions.json` | Edit one canonical paper group | `npm run validate:data` |
| `student-progress-note` | Add durable meeting notes or update a student's research stage | `src/data/students.json` | Edit one student and its `timeline` | `npm run validate:data` |
| `personal-research-update` | Track the owner's own research work outside formal projects/papers/students | `src/data/personal-research.json` | Edit one item or append one item | `npm run validate:data` |
| `code-project-inventory` | Refresh tracked repository status or add a code project | `src/data/code-projects.json` | Edit one item or append one item | `npm run validate:data` |
| `misc-task-update` | Track school tasks, reviews, courses, surveys, site maintenance, or development tasks | `src/data/misc.json` | Edit one item or append one item | `npm run validate:data` |
| `agent-contract-update` | Improve this agent contract | `docs/agent-submission.md`, `public-agent/agent-submission.md`, optionally `public-agent/index.html` | Keep public and repository copies consistent | `npm run build` |

Do not invent a new skill unless the existing categories cannot represent the
request.

## Read Interface

The source of truth is the repository.

| Data area | File or directory | Notes |
| --- | --- | --- |
| Fund and industry projects | `src/data/projects.json` | Top-level project metadata and current summary |
| Dated project progress | `src/data/project-progress/*.json` | Append-only updates keyed by `projectId` |
| Journal paper submissions | `src/data/paper-submissions.json` | Grouped by canonical paper title |
| Student progress | `src/data/students.json` | Durable profile, stage, risk, and meeting timeline |
| Personal research | `src/data/personal-research.json` | Owner's own research work |
| Code projects | `src/data/code-projects.json` | Repository inventory and latest known status |
| Miscellaneous work | `src/data/misc.json` | School, review, course, survey, site, and development tasks |

The private dashboard can be used for visual inspection after deployment, but it
is not the write source. Local browser state such as daily focus items and star
overrides is intentionally not part of the durable agent contract.

## Write Rules

1. Write only repository files.
2. Prefer append-only updates when a category supports them.
3. Edit master lists only when explicitly asked or when the update cannot be
   represented append-only.
4. Preserve existing IDs unless the item is truly new.
5. Use ISO dates: `YYYY-MM-DD`.
6. Keep source links stable and non-sensitive.
7. Never store cookies, one-time login URLs, Cloudflare Access tokens, portal
   URLs with signed query parameters, `state`, `nonce`, or `meta` values.
8. Store portal links as path-only values when possible, for example
   `/submission/submissionBoard/example/finalReview`.

Any top-level item in the main JSON data files can be pinned to the home page by
adding `"focus": true`.

## Fund Project Master List

File:

```txt
src/data/projects.json
```

Required fields:

- `id`
- `name`
- `status`
- `kind`
- `priority`
- `startDate`
- `deadline`
- `source`
- `projectType`
- `role`
- `amount`
- `nextAction`
- `progress`
- `latestUpdate`
- `owner`

Validation requirements:

- `kind` must be `横向项目` or `纵向项目`.
- `progress` must be an integer from 0 to 100.
- `startDate` and `deadline` must be ISO dates.
- `id` must be unique.

Optional common fields include `number`, `repository`, and `focus`.

## Fund Project Progress Updates

Use the `project-progress-update` skill for dated updates about an existing
project. This is the preferred way to add new progress without rewriting the
master project record.

Directory:

```txt
src/data/project-progress/
```

Filename format:

```txt
yyyy-mm-dd-project-slug.json
```

Required shape:

```json
{
  "id": "2026-06-15-example",
  "projectId": "todo-dashboard",
  "date": "2026-06-15",
  "summary": "Short human-readable update.",
  "completed": ["Concrete completed item"],
  "blocked": [],
  "next": ["Concrete next action"],
  "status": "active",
  "dueDate": "2026-06-21",
  "links": ["https://example.com"]
}
```

Required fields: `id`, `projectId`, `date`, `summary`, `completed`, `blocked`,
and `next`.

Optional fields: `status`, `dueDate`, and `links`.

Validation requirements:

- `projectId` must exist in `src/data/projects.json`.
- `id` must be unique across project progress updates.
- `date` and `dueDate` must be ISO dates.
- `completed`, `blocked`, `next`, and `links` must be arrays.

## Journal Paper Submission Status

File:

```txt
src/data/paper-submissions.json
```

The top-level unit is one canonical paper title. Multiple venues, rejections,
revisions, and resubmissions for the same paper belong under the same top-level
paper record in the nested `submissions` array.

### Paper Grouping Rules

- Normalize whitespace and colon spacing before comparing titles.
- If the normalized title matches an existing `canonicalTitle`, update that
  paper group. Do not create a duplicate top-level record.
- If a manuscript was retitled but is substantively the same paper, update the
  existing group deliberately instead of creating a second group. Put prior
  titles in `aliases`.
- Create a new top-level paper group only when it is truly a different paper.
- A `manuscriptId` must appear only once across all submission attempts.
- `currentStatus`, `currentVenue`, and `lastStatusDate` must match one nested
  submission attempt and represent the latest concrete source status.

### Paper Group Shape

```json
{
  "id": "example-paper-slug",
  "canonicalTitle": "Example Paper Title",
  "aliases": ["Prior Example Paper Title"],
  "currentStatus": "Under Review",
  "currentVenue": "IEEE Example Transactions",
  "lastStatusDate": "2026-06-15",
  "deadline": "2026-08-11",
  "nextAction": "Wait for review result or prepare revision.",
  "relatedAuthors": ["Author Name"],
  "submissions": [
    {
      "id": "example-2026-001",
      "source": "IEEE Author Portal",
      "publication": "IEEE Example Transactions",
      "submissionType": "Regular",
      "manuscriptId": "EXAMPLE-2026-001",
      "status": "Under Review",
      "statusDate": "2026-06-15",
      "submittedOn": "2026-06-15",
      "actor": "Author Name",
      "portalPath": "/submission/submissionBoard/example/finalReview"
    }
  ]
}
```

Required paper group fields: `id`, `canonicalTitle`, `currentStatus`,
`currentVenue`, `lastStatusDate`, `nextAction`, `relatedAuthors`, and
`submissions`.

Optional paper group fields: `aliases`, `deadline`, and `focus`.

Required submission attempt fields: `id`, `source`, `publication`,
`submissionType`, `manuscriptId`, `status`, and `statusDate`.

Optional submission attempt fields: `submittedOn`, `submissionStarted`,
`revisedOn`, `rejectedOn`, `acceptedOn`, `lastModified`, `dueBy`, `actor`, and
`portalPath`.

### IEEE Author Portal Extraction

When the owner asks an agent to use the IEEE Author Portal:

1. Use the currently authenticated browser session only if explicitly provided.
2. Read visible submission records. Do not change IEEE portal data.
3. Convert visible dates to ISO dates.
4. Preserve exact visible status text, for example `Under Review`,
   `Rejected`, `Accepted`, or `In Revision(Revision 1)`.
5. Group same-title papers together before writing JSON.
6. Store manuscript IDs exactly as shown.
7. Store only path-only portal links. Strip host query strings and any signed
   login parameters.

## Student Progress

File:

```txt
src/data/students.json
```

Use this file for durable student progress: research stage, next action, risk,
report due date, and meeting-note timeline. Do not use this file for the manual
dashboard status chips; those are app-internal D1/KV state.

Required student fields:

- `id`
- `name`
- `category`
- `grade`
- `direction`
- `stage`
- `lastUpdate`
- `nextAction`
- `reportDueDate`
- `risk`
- `timeline`

Required timeline fields:

- `date`
- `source`
- `stage`
- `summary`
- `nextAction`
- `risk`

Validation requirements:

- `category` must be `博士生`, `硕士生`, `本科生`, or `未确认`.
- `grade` must look like `2026级` or be `未确认`.
- `timeline` must contain at least one entry.
- `lastUpdate`, `stage`, and `risk` must match the latest timeline entry by
  date.
- All timeline dates and due dates must be ISO dates.

When adding a new meeting note, append a timeline entry and update the student's
top-level `lastUpdate`, `stage`, `risk`, and `nextAction` to match the latest
durable status.

## Personal Research Work

File:

```txt
src/data/personal-research.json
```

Use this category for the owner's own research work that is not a formal
project, paper submission, student progress, or miscellaneous item.

Required fields: `id`, `name`, `scope`, `status`, `priority`, `recordedOn`, and
`nextAction`.

Optional common field: `focus`.

## Code Projects

File:

```txt
src/data/code-projects.json
```

Required fields: `id`, `name`, `status`, `priority`, `recordedOn`, and
`nextAction`.

Common optional fields: `repository`, `description`, `group`, `groupLabel`,
`groupDetail`, `relatedArea`, `relatedItem`, `language`, `visibility`,
`isFork`, `defaultBranch`, `latestCommit`, `recentCommits`, `repoMeta`, and
`focus`.

If refreshing GitHub repository inventory, preserve the current object shape and
only change fields supported by visible repository metadata.

## Miscellaneous Items

File:

```txt
src/data/misc.json
```

Use this category for work that is not a formal project, not a paper, not
student progress, and not personal research work.

Required fields: `id`, `name`, `category`, `kind`, `scope`, `status`,
`priority`, `recordedOn`, and `nextAction`.

Current visible categories are:

- `学校杂事`
- `审稿相关`
- `课程`
- `调研`
- `网站维护`
- `开发项目`

Optional common fields: `dueDate`, `repository`, `latestCommitUrl`,
`sourceCodeProjectId`, `relatedProjects`, and `focus`.

If `relatedProjects` is present, each entry must include:

- `codeProjectId`: an existing `src/data/code-projects.json` ID.
- `role`: the relationship label.

## Commit Protocol

Recommended sequence:

```bash
git status --short
npm run validate:data
npm run build
npm run lint
git add <only relevant files>
git commit -m "Update dashboard data"
git push origin main
```

Use a more specific commit message when possible:

- `Add project progress update`
- `Update paper submission status`
- `Update student progress notes`
- `Refine public agent contract`

After push, confirm the deployment source commit matches the pushed commit when
deployment access is available.

## Stop Conditions

Stop and report instead of guessing when:

- GitHub access to `neardws/personal-todo-dashboard` is missing.
- The local working tree has unrelated changes in the same file you need to
  edit.
- A source system shows ambiguous dates, statuses, titles, or IDs.
- The requested update would require storing secrets or signed portal URLs.
- `npm run validate:data` or `npm run build` fails.
- Cloudflare does not manage the required deployment target.