# Personal TODO Agent Interface

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

This document is an operating contract. It is not a web API. There is no public
write endpoint, no database endpoint, and no application login. The only write
path is GitHub file changes.

## 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 commands before committing:

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

Optional but preferred check:

```bash
npm run lint
```

## Operating Rules

1. Write only to repository files. Do not attempt to POST to the dashboard.
2. Use JSON or Markdown only. Do not introduce a backend, database, login, or
   browser-side write path.
3. Keep unrelated local changes out of the commit. Stage only files needed for
   the current update.
4. Run validation and build before committing.
5. Commit to `main` and push to GitHub unless the owner explicitly asks for a
   branch or pull request.
6. Never store cookies, one-time login URLs, Cloudflare Access tokens, IEEE
   access URLs with `state`, `nonce`, `meta`, or other signed parameters.
7. Store portal links as path-only values when possible, for example
   `/submission/submissionBoard/example/finalReview`.

## File Map

| Task | File or directory | Write mode |
| --- | --- | --- |
| Fund project progress update | `src/data/project-progress/*.json` | Append one new file |
| Fund project master list | `src/data/projects.json` | Edit only when explicitly requested |
| Personal research work | `src/data/personal-research.json` | Edit only when explicitly requested |
| Code projects | `src/data/code-projects.json` | Edit only when explicitly requested |
| Miscellaneous items | `src/data/misc.json` | Edit only when explicitly requested |
| Journal paper submission status | `src/data/paper-submissions.json` | Update canonical journal paper group |
| Student progress | `src/data/students.json` | Edit only when explicitly requested |
| Agent contract copy | `docs/agent-submission.md` | Keep in sync with this public contract |

## Fund Project Progress Updates

Fund project progress is append-only. Add one JSON file per update under:

```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`.
- Fund projects in `src/data/projects.json` must use `kind` values of
  `横向项目` or `纵向项目`.
- `date` and `dueDate` must be ISO dates: `YYYY-MM-DD`.
- `completed`, `blocked`, `next`, and `links` must be arrays.
- `id` must be unique across project progress updates.

## Personal Research Work

Personal research work is stored in:

```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`.

## Code Projects

Code projects are stored in:

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

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

## Miscellaneous Items

Miscellaneous items are stored in:

```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. Current subcategories are
`调研工作` and `私人项目`.

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

## Journal Paper Submission Status

Journal paper submission status is stored in:

```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` and `deadline`.

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.

## 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`
- `Refine public agent contract`

After push, confirm the deployment source commit matches the pushed commit.

## 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 or statuses.
- `npm run validate:data` or `npm run build` fails.
- Cloudflare does not manage the required deployment target.