Personal TODO Agent Interface

Operating contract for agents that submit updates to the private personal TODO dashboard. This is not a web API. The write path is GitHub file changes, validation, build, commit, push, deploy.

Markdown contract

Execution Boundary

There is no public write endpoint, no database endpoint, and no application login. Write only to repository files. Never store cookies, one-time login URLs, Cloudflare Access tokens, or signed IEEE portal URLs.

Repository Target

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`

Operating Rules

Use JSON or Markdown only. Do not add a backend, database, login, or browser-side write path.
Keep unrelated local changes out of the commit. Stage only files needed for the current update.
Run npm run validate:data and npm run build before committing.
Run npm run lint when available.
Commit to main and push unless the owner asks for a branch or pull request.
Store portal links as path-only values when possible.

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

Add one append-only JSON file per update under:

src/data/project-progress/

Use a filename like:

yyyy-mm-dd-project-slug.json

Shape

{
  "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.

projectId must exist in src/data/projects.json.
Fund project kind must be 横向项目 or 纵向项目.
Dates 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:

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:

src/data/code-projects.json

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

Miscellaneous Items

Miscellaneous items are stored in:

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:

src/data/paper-submissions.json

The top-level unit is one canonical paper title. If the same paper appears in multiple submissions, venues, or revisions, keep it in one paper group and append or update the nested submissions list.

Grouping Rules

Same normalized title means same paper group.
Do not create a second top-level record for the same paper title.
If a retitled manuscript is substantively the same paper, keep prior titles in aliases.
One manuscriptId appears only once across attempts.
currentStatus, currentVenue, and lastStatusDate must match one nested attempt and represent the latest concrete source status.

Shape

{
  "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"
    }
  ]
}

IEEE Author Portal Extraction

Use the owner-provided authenticated browser session only when explicitly asked.
Read visible submission records. Do not change IEEE portal data.
Convert visible dates to ISO dates.
Preserve exact visible status text.
Group same-title papers before writing JSON.
Store manuscript IDs exactly as shown.
Strip host query strings and signed login parameters from portal links.

Commit Protocol

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

Stop Conditions

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.