overleaf-codex 0.1.0-rc.1

package/docs/cli-behavior.md

@@ -0,0 +1,95 @@
+# CLI Behavior
+
+This document is the v1 command-line behavior contract for `olcx`. It defines
+the user-facing behavior for auth, init, endpoint, sync, compile, watch,
+status, and doctor workflows.
+
+`olcx` is a lightweight CLI. It must not require local LaTeX for the core
+workflow, must not silently overwrite local or remote changes, and must not
+print credentials, cookies, session values, passwords, or private project
+identifiers.
+
+## Command Surface
+
+| Command | Required parameters | Optional parameters | Environment variables | Interactive input | Non-interactive behavior |
+| --- | --- | --- | --- | --- | --- |
+| `olcx auth` | In non-interactive mode, one auth source is required: `--cookie <value>` or `--from-env <name>`. | `--cookie <value>`, `--from-env <name>`. | The variable named by `--from-env`; recommended local name is `OLCX_OVERLEAF_SESSION`. `OLCX_NON_INTERACTIVE=1` and `CI=true` force non-interactive mode. | In interactive mode, may prompt on stderr for a pasted session cookie. It must never ask for or store an Overleaf password. | If no auth source is available, fail with `USER_INPUT_ERROR` and print a next-step hint. Do not wait forever for input. |
+| `olcx init --project <overleaf-url-or-id>` | `--project <overleaf-url-or-id>`. | None. | `OLCX_NON_INTERACTIVE=1` and `CI=true` force non-interactive mode. | None in v1. | Missing or invalid `--project` fails with `USER_INPUT_ERROR`; conflicting local files fail with an actionable error instead of overwriting. Init creates or repairs local VS Code settings/tasks by default. |
+| `olcx endpoint status` | Bound project config. | None. | None. | None. | Reads `overleaf.baseUrl`, performs no network access, and returns `CONFIG_ERROR` if config is missing or invalid. |
+| `olcx endpoint test` | Bound project config. | `--timeout <ms>`, `--apply`. | None. | None. | Probes only `https://www.overleaf.com/project` and `https://cn.overleaf.com/project`. Without `--apply`, never writes config. With `--apply`, writes only the fastest available endpoint. If both fail, returns `NETWORK_ERROR` and leaves config unchanged. Invalid timeout returns `USER_INPUT_ERROR`. |
+| `olcx endpoint set cn` | Bound project config and endpoint alias `www` or `cn`. | None. | None. | None. | Writes `overleaf.baseUrl` without probing. Invalid aliases return `USER_INPUT_ERROR` and leave config unchanged. |
+| `olcx sync` | Bound project config and auth. | `--dry-run`. | `OLCX_NON_INTERACTIVE=1` and `CI=true` force non-interactive mode. | None in v1. | Missing config returns `CONFIG_ERROR`; missing auth returns `AUTH_ERROR`; conflicts return `SYNC_CONFLICT`; `--dry-run` must not mutate local or remote files. |
+| `olcx compile` | Bound project config and auth. | `--pdf <path>`, `--disable-fast-fallback`, `--fast-fallback-attempts <count>`, and `--fast-fallback-timeout <ms>`. | `OLCX_NON_INTERACTIVE=1` and `CI=true` force non-interactive mode. | None in v1. | Missing config returns `CONFIG_ERROR`; missing auth returns `AUTH_ERROR`; network failures return `NETWORK_ERROR`; compile failures or timeouts return `COMPILE_FAILED`. |
+| `olcx watch` | Bound project config and auth. | `--debounce <ms>` defaults to `2500`. | `OLCX_NON_INTERACTIVE=1` and `CI=true` force non-interactive mode. | None in v1. | Must not prompt while watching. On sync conflict or compile failure, pause the automatic loop and print the next manual command to run. |
+| `olcx status` | None. | None. | `OLCX_NON_INTERACTIVE=1` and `CI=true` force non-interactive mode. | None. | Must return a redacted local summary. Missing config or auth is reported as status, not as leaked detail. |
+| `olcx doctor` | None. | None. | `OLCX_NON_INTERACTIVE=1` and `CI=true` force non-interactive mode. | None. | Must run local checks without real Overleaf access by default. Failures return the most specific exit code and a next-step hint. |
+
+## Exit Codes
+
+| Name | Number | Meaning |
+| --- | ---: | --- |
+| `SUCCESS` | `0` | Successful command, help, or version output. |
+| `INTERNAL_ERROR` | `1` | Unexpected thrown error or uncategorized local I/O failure. |
+| `USER_INPUT_ERROR` | `2` | Invalid arguments, missing required options, invalid option values, unsupported command usage, or required non-interactive input not provided. |
+| `CONFIG_ERROR` | `3` | Missing or invalid `.olcx/config.json`. |
+| `AUTH_ERROR` | `4` | Missing, invalid, expired, or rejected project-local auth. |
+| `NETWORK_ERROR` | `5` | Backend network or protocol failure while talking to Overleaf. |
+| `SYNC_CONFLICT` | `6` | Sync conflict or unsafe sync operation that pauses instead of overwriting. |
+| `COMPILE_FAILED` | `7` | Overleaf compile failure, compile timeout, or failed PDF retrieval. |
+
+## Output Streams
+
+- stdout is for successful command results, help, version output, status
+  summaries, dry-run summaries, sync plans, compile summaries, and future JSON
+  payloads.
+- stderr is for prompts, warnings, errors, conflict notices, compile failure
+  summaries, and next-step hints.
+- A failed command must not write partial machine-readable data to stdout. It
+  should write a redacted error and a `Next:` hint to stderr.
+- Help requested directly with `--help` exits `0`. Help shown after a usage
+  error exits `2`.
+- Endpoint test failures where neither `www` nor `cn` is reachable write the
+  formatted probe result to stderr and exit `NETWORK_ERROR`.
+- `olcx endpoint test --apply` writes `.olcx/config.json` only after a
+  successful probe finds at least one reachable endpoint.
+
+## Human Output
+
+- Human-readable output should be short, direct, and actionable.
+- Failure output uses this shape:
+
+```text
+Error: <redacted failure message>
+Next: <one command or action the user can take>
+```
+
+- Stack traces are not printed for expected failures.
+- Commands must not use local LaTeX in the core compile path.
+- When fast/draft fallback produces the PDF, stdout must show
+  `Status: fallback-success` and a `Fallback: fast/draft` line. The command must
+  not present the fallback PDF as a full normal compile artifact.
+
+## Future JSON Output
+
+JSON output is reserved for a future `--json` mode. Until that mode is
+implemented, command implementations must not print ad hoc JSON. When
+introduced, JSON payloads will go to stdout, warnings and errors will remain on
+stderr, and secrets will still be redacted before serialization.
+
+## Redaction
+
+All command output, errors, diagnostics, test fixtures, snapshots, docs, and
+handoff reports must redact:
+
+- Overleaf cookies and session values.
+- Password-like, token-like, auth-like, and CSRF-like values.
+- Account-private values such as raw emails when they appear in errors or
+  diagnostic details.
+- Overleaf project URLs and project-id-like values.
+- Endpoint base URLs such as `https://www.overleaf.com` and
+  `https://cn.overleaf.com` are not secrets, but project URLs under either host
+  must be redacted.
+
+Use placeholders such as `<redacted-secret>`, `<redacted-account>`, and
+`<redacted-project-id>`. Do not write real credentials or private project IDs to
+tests, fixtures, docs, QuickDev handoff files, terminal output, or CI logs.

package/docs/compile.md

@@ -0,0 +1,51 @@
+# Compile
+
+`olcx compile` asks Overleaf to compile the bound project and downloads the PDF.
+The core workflow does not require local LaTeX.
+
+## Default Compile
+
+```bash
+olcx compile
+```
+
+The default PDF output path is:
+
+```text
+build/overleaf/main.pdf
+```
+
+## PDF Path
+
+```bash
+olcx compile --pdf build/overleaf/main.pdf
+```
+
+Use `--pdf` when a project needs a different local preview path.
+
+## Fast Fallback
+
+`olcx compile` can use a fast/draft fallback when normal compilation times out.
+For debugging, compare these modes:
+
+```bash
+olcx compile --disable-fast-fallback
+olcx compile --fast-fallback-timeout 60000
+```
+
+When fallback produces the PDF, command output includes `Status:
+fallback-success` and `Fallback: fast/draft`. Treat that PDF as a recovery
+artifact, not a full normal compile result.
+
+If both modes fail, inspect the compile output, fix the LaTeX source locally or
+on Overleaf, run `olcx sync --dry-run`, and compile again.
+
+## Troubleshooting
+
+If the PDF is not updated, check the exact file path and timestamp:
+
+```bash
+olcx compile
+ls -l build/overleaf/main.pdf
+olcx status
+```

package/docs/design.md

@@ -0,0 +1,82 @@
+# Design
+
+## Product intent
+
+`olcx` connects a local paper repository to one Overleaf project. The local side
+owns editing, Git history, VS Code preview, and Codex-assisted writing. Overleaf
+owns LaTeX compilation and PDF generation.
+
+The target experience is:
+
+1. Author edits locally.
+2. `olcx watch` detects a quiet period after changes.
+3. `olcx` synchronizes safe changes with Overleaf.
+4. `olcx` triggers Overleaf compilation.
+5. `olcx` downloads the PDF to `build/overleaf/main.pdf`.
+6. VS Code previews that file.
+
+## Architecture
+
+The first implementation is an npm/TypeScript CLI named `olcx`.
+
+The Overleaf backend will be based on a one-time integration of MIT-licensed
+`aloth/olcli` code. Users install `olcx` only; they do not install `olcli`
+separately. This repository owns future behavior, maintenance, docs, and release
+packaging.
+
+The CLI should remain split into small units:
+
+- command parsing and user-facing output;
+- project config and auth file handling;
+- Overleaf backend adapter;
+- sync and conflict policy;
+- compile and PDF download flow;
+- watch and debounce queue;
+- diagnostics.
+
+## Project-local state
+
+Each real paper repository has a `.olcx/` directory.
+
+`config.json` is intended to be shareable:
+
+```json
+{
+  "projectId": "overleaf-project-id",
+  "pdfPath": "build/overleaf/main.pdf",
+  "sync": {
+    "mode": "bidirectional",
+    "conflictPolicy": "pause"
+  }
+}
+```
+
+`auth.local.json` is local-only:
+
+```json
+{
+  "account": "user@example.com",
+  "sessionCookie": "redacted",
+  "updatedAt": "2026-06-25T00:00:00.000Z"
+}
+```
+
+The exact schema can evolve, but auth stays project-local and ignored by Git.
+
+## Sync policy
+
+The default sync mode is bidirectional, but not destructive.
+
+If local and Overleaf versions changed the same file, `olcx` pauses the automatic
+queue and reports the conflict. It must not choose a winner silently. Manual
+commands can later resolve conflicts by choosing local, remote, or a user-merged
+file.
+
+## Non-goals for v1
+
+- No GUI.
+- No VS Code extension.
+- No local LaTeX dependency.
+- No multi-project workspace manager.
+- No silent overwrites.
+- No committed credentials or cookies.

package/docs/endpoint.md

@@ -0,0 +1,84 @@
+# Endpoint Management
+
+`olcx` supports the public Overleaf web endpoints:
+
+- `https://www.overleaf.com`
+- `https://cn.overleaf.com`
+
+The default is `https://www.overleaf.com`. Endpoint selection is manual by
+default and is stored per paper repository.
+
+## Status
+
+Show the configured endpoint without network access:
+
+```bash
+olcx endpoint status
+```
+
+This reads `.olcx/config.json` and prints the current alias and URL.
+
+## Read-only Test
+
+Probe public endpoint reachability:
+
+```bash
+olcx endpoint test
+```
+
+`olcx endpoint test` probes only:
+
+```text
+https://www.overleaf.com/project
+https://cn.overleaf.com/project
+```
+
+It does not sync, upload, compile, validate auth, read project-specific URLs, or
+modify remote projects. Without `--apply`, it never writes config.
+
+## Manual Switch
+
+Set the endpoint explicitly:
+
+```bash
+olcx endpoint set cn
+olcx endpoint set www
+```
+
+This writes `.olcx/config.json` and does not contact Overleaf.
+
+## Apply Fastest Available
+
+Probe both endpoints and write the fastest reachable one:
+
+```bash
+olcx endpoint test --apply
+```
+
+`--apply` writes config only when at least one endpoint is available. If both
+endpoints fail, `olcx` returns `NETWORK_ERROR`, prints both redacted failure
+reasons, and leaves `.olcx/config.json` unchanged.
+
+## Configuration
+
+Endpoint state lives in `overleaf.baseUrl`:
+
+```json
+{
+  "overleaf": {
+    "baseUrl": "https://www.overleaf.com"
+  }
+}
+```
+
+Allowed values are `https://www.overleaf.com` and `https://cn.overleaf.com`.
+Legacy configs without `overleaf.baseUrl` default to `https://www.overleaf.com`
+in memory.
+
+## Security
+
+Endpoint base URLs are not secrets. Probe failure messages are still redacted
+because network errors can include cookies, session values, project URLs, or
+project-id-like strings. Do not paste real cookies, account labels, private
+project IDs, or private paper content into docs, tests, issues, or handoff
+files.

package/docs/npm-packaging.md

@@ -0,0 +1,148 @@
+# npm Packaging
+
+The npm package is intentionally small and user-facing. Check it with:
+
+```bash
+npm pack --dry-run --json --ignore-scripts
+```
+
+`npm run prepublish:check` runs the same dry-run package inspection after build,
+typecheck, tests, audit, license checks, notice checks, and release text scans.
+
+## Required Package Surface
+
+The package must include:
+
+- `dist/`
+- `docs/`
+- `examples/`
+- `assets/`
+- `README.md`
+- `LICENSE`
+- `NOTICE.md`
+- `package.json`
+- `src/backend/olcli/LICENSE`
+- `src/backend/olcli/README.md`
+
+Focused user docs such as `docs/usage.md`, `docs/auth.md`, `docs/endpoint.md`,
+`docs/sync.md`, `docs/compile.md`, `docs/troubleshooting.md`,
+`docs/release-gates.md`, `docs/npm-packaging.md`, and
+`docs/release-notes-v1.md` are required package files.
+
+## Excluded Content
+
+The package gate rejects tests, scripts, `.github/`, `tmp/`, `node_modules/`,
+local auth files, local or secret JSON files, environment files, logs, generated
+Overleaf output, and real E2E output.
+
+The only tracked `.olcx` files allowed in the package are sanitized example
+files under `examples/minimal-paper/`.
+
+## Manual npm Publish
+
+Run all release gates before any manual publish:
+
+```bash
+npm run build
+npm run typecheck
+npm test
+OLCX_E2E_IGNORE_LOCAL_ENV=1 OLCX_E2E_ENABLE_REAL=0 npm run test:e2e:real
+npm audit --audit-level=high
+npm pack --dry-run --json --ignore-scripts
+npm run prepublish:check
+```
+
+Confirm the package name and current registry state before publishing:
+
+```bash
+npm view overleaf-codex version
+npm login
+npm whoami
+npm publish --dry-run
+```
+
+For the current unscoped package name, the real manual publish command is:
+
+```bash
+npm publish
+```
+
+If the package is ever renamed to a scoped public package, use
+`npm publish --access public` and update `package.json`, this document, the
+Trusted Publisher binding, and the workflow tests together.
+
+Interactive npm publishes or package settings changes can prompt for `2FA` or
+an `OTP`. Enter those values only in the npm prompt. Do not write OTPs,
+passwords, npm auth values, or session values into docs, scripts, CI, or Git.
+
+Stable release is not approved until a sanitized disposable real Overleaf E2E pass is recorded. The forced skip smoke is not a stable-release substitute.
+
+## GitHub Actions Trusted Publishing
+
+Prefer GitHub Actions Trusted Publisher configuration over long-lived npm
+tokens. The repository workflow is `.github/workflows/npm-publish.yml`; it uses
+OIDC with `permissions: id-token: write` and publishes only from explicit
+GitHub release publication events.
+
+Do not configure repository `NPM_TOKEN`, `NODE_AUTH_TOKEN`, npm automation
+token material, `_authToken`, or a checked-in `.npmrc` for publishing.
+
+Configure the npm Trusted Publisher binding on npm with these fields:
+
+- `owner: umiskky`
+- `repository: overleaf-codex`
+- `workflow filename: npm-publish.yml`
+- `environment: npm-publish`
+- `package: overleaf-codex`
+- `allowed action: npm publish`
+
+The workflow runs on GitHub-hosted `ubuntu-latest`, installs a trusted
+publishing capable npm CLI, runs the forced E2E skip smoke, then runs
+`npm run prepublish:check` before `npm publish --tag "$NPM_DIST_TAG"`.
+Trusted publishing is expected to generate npm provenance automatically; verify
+the published package provenance after release from npm or the package page.
+
+## Version, Tag, And Release Strategy
+
+GitHub release tags must match the `package.json` version exactly after removing
+the leading `v`.
+
+- Stable package versions use non-prerelease GitHub releases such as `vX.Y.Z`
+  and publish with npm dist-tag `latest`.
+- Prerelease package versions use GitHub prereleases such as `vX.Y.Z-rc.1` and
+  publish with npm dist-tag `next`.
+
+The stable workflow path checks `docs/release-notes-v1.md` for explicit stable
+approval and a concrete sanitized real E2E artifact reference before publishing
+`latest`. The required format is:
+
+```text
+Sanitized real E2E artifact: gh-release://umiskky/overleaf-codex/vX.Y.Z/sanitized-real-e2e.md
+```
+
+Concrete sanitized real E2E artifact reference means the path names a reviewed
+release artifact. Placeholder text such as `not recorded`, `placeholder`, or
+`not evidence` must be removed before stable npm publish can proceed.
+
+## Stable Release Block
+
+Stable npm publication remains blocked in the current repository state. The
+release notes must continue to say the release is not approved until the
+sanitized disposable real Overleaf E2E result is recorded and reviewed.
+
+The forced skip smoke proves CI does not read local E2E secrets or contact
+Overleaf. It is required for safety, but it is not proof that a disposable real
+Overleaf project passed the E2E flow.
+
+## Rollback, Unpublish, And Deprecate
+
+Prefer fixing forward with a new patch version for a bad release. If users need
+a warning on an already-published version, use:
+
+```bash
+npm deprecate overleaf-codex@<version> "<message>"
+```
+
+`npm unpublish overleaf-codex@<version>` is time-limited and policy-limited.
+After a version has been published, that exact package name and version cannot
+be reused. Use unpublish only when npm policy allows it and deprecate otherwise.

package/docs/quickdev-queue-audit.md

@@ -0,0 +1,193 @@
+# QuickDev Queue Audit
+
+## Scope And Inputs
+
+Audit timestamp: `2026-06-25T18:53:52+08:00`.
+
+Source of truth for the current queue is `todo.md` as observed top to bottom during this audit. `done.md` contains no completed task blocks. The audit is documentation-only: no task was marked complete, blocked, skipped, deleted, archived, or reordered.
+
+Files inspected:
+
+- `AGENTS.md`
+- `goal.md`
+- `todo.md`
+- `done.md`
+- `package.json`
+- `README.md`
+- `ROADMAP.md`
+- `docs/design.md`
+- `docs/usage.md`
+- `docs/security.md`
+- every current `tmp/*/00-task.md` handoff copy for the 20 queued tasks
+- current `git status --short`
+
+Important input note: `todo.md` has the current task text. The current real E2E queue block is more specific than its `00-task.md` handoff copy because it names placeholder environment variables and says missing local secrets should block rather than prompting for values. Use the current `todo.md` block when that task is executed, or refresh the handoff copy before planning it.
+
+## Current Queue
+
+| Pos | Task ID | Title | Status | Created At | Handoff Dir |
+| --- | --- | --- | --- | --- | --- |
+| 1 | `20260625-163340-992326` | 审计 QuickDev 队列顺序与任务可执行性 | `todo` | `2026-06-25T16:33:40+08:00` | `tmp/20260625-163340-992326-审计 QuickDev 队列顺序与任务可执行性` |
+| 2 | `20260625-163153-333824` | 冻结 v1 架构模块与公共接口契约 | `todo` | `2026-06-25T16:31:53+08:00` | `tmp/20260625-163153-333824-冻结 v1 架构模块与公共接口契约` |
+| 3 | `20260625-163246-549133` | 统一 CLI 行为输出与退出码规范 | `todo` | `2026-06-25T16:32:46+08:00` | `tmp/20260625-163246-549133-统一 CLI 行为输出与退出码规范` |
+| 4 | `20260625-163308-046461` | 定义同步状态机快照与冲突报告格式 | `todo` | `2026-06-25T16:33:08+08:00` | `tmp/20260625-163308-046461-定义同步状态机快照与冲突报告格式` |
+| 5 | `20260625-160751-353900` | 引入 olcli 后端代码与许可证合规 | `todo` | `2026-06-25T16:07:51+08:00` | `tmp/20260625-160751-353900-引入 olcli 后端代码与许可证合规` |
+| 6 | `20260625-160853-429297` | 实现 Overleaf 后端适配层 | `todo` | `2026-06-25T16:08:53+08:00` | `tmp/20260625-160853-429297-实现 Overleaf 后端适配层` |
+| 7 | `20260625-160804-867992` | 建立项目配置认证与安全基础设施 | `todo` | `2026-06-25T16:08:04+08:00` | `tmp/20260625-160804-867992-建立项目配置认证与安全基础设施` |
+| 8 | `20260625-160819-417512` | 实现 olcx init 与 VS Code 配置生成 | `todo` | `2026-06-25T16:08:19+08:00` | `tmp/20260625-160819-417512-实现 olcx init 与 VS Code 配置生成` |
+| 9 | `20260625-160836-699088` | 实现 olcx auth status doctor | `todo` | `2026-06-25T16:08:36+08:00` | `tmp/20260625-160836-699088-实现 olcx auth status doctor` |
+| 10 | `20260625-160912-750072` | 实现安全双向同步与冲突暂停 | `todo` | `2026-06-25T16:09:12+08:00` | `tmp/20260625-160912-750072-实现安全双向同步与冲突暂停` |
+| 11 | `20260625-160925-146032` | 实现远程编译和 PDF 下载 | `todo` | `2026-06-25T16:09:25+08:00` | `tmp/20260625-160925-146032-实现远程编译和 PDF 下载` |
+| 12 | `20260625-165248-545991` | 实现 Overleaf 编译超时快速模式降级恢复 | `todo` | `2026-06-25T16:52:48+08:00` | `tmp/20260625-165248-545991-实现 Overleaf 编译超时快速模式降级恢复` |
+| 13 | `20260625-160938-324045` | 实现 olcx watch 自动工作流 | `todo` | `2026-06-25T16:09:38+08:00` | `tmp/20260625-160938-324045-实现 olcx watch 自动工作流` |
+| 14 | `20260625-162413-873208` | 全链路本地沙箱回归测试 | `todo` | `2026-06-25T16:24:13+08:00` | `tmp/20260625-162413-873208-全链路本地沙箱回归测试` |
+| 15 | `20260625-160946-910101` | 真实 Overleaf 集成 E2E 测试 | `todo` | `2026-06-25T16:09:46+08:00` | `tmp/20260625-160946-910101-真实 Overleaf 集成 E2E 测试` |
+| 16 | `20260625-162426-756284` | 跨平台与无头环境兼容性验证 | `todo` | `2026-06-25T16:24:26+08:00` | `tmp/20260625-162426-756284-跨平台与无头环境兼容性验证` |
+| 17 | `20260625-162438-154174` | 安全许可证与供应链发布门禁 | `todo` | `2026-06-25T16:24:38+08:00` | `tmp/20260625-162438-154174-安全许可证与供应链发布门禁` |
+| 18 | `20260625-162447-918619` | 示例论文项目与故障排查资料 | `todo` | `2026-06-25T16:24:47+08:00` | `tmp/20260625-162447-918619-示例论文项目与故障排查资料` |
+| 19 | `20260625-161006-526237` | 文档发布与社区维护完善 | `todo` | `2026-06-25T16:10:06+08:00` | `tmp/20260625-161006-526237-文档发布与社区维护完善` |
+| 20 | `20260625-162518-364796` | v1 发布候选总验收与冻结 | `todo` | `2026-06-25T16:25:18+08:00` | `tmp/20260625-162518-364796-v1 发布候选总验收与冻结` |
+
+## Completeness Matrix
+
+All current task blocks contain the required QuickDev fields: target/goal, scope, acceptance criteria, constraints, and notes. The matrix focuses on whether the text is sufficient for independent `plan`, `actor`, and `verify` roles.
+
+| Pos | Task ID | Required Fields | Implementation Context | Actor Executable | Verifier Independent | Main Prerequisites Or Blockers |
+| --- | --- | --- | --- | --- | --- | --- |
+| 1 | `20260625-163340-992326` | Present | Sufficient for docs audit | Yes | Yes | None; current audit task |
+| 2 | `20260625-163153-333824` | Present | Sufficient; builds on existing design docs | Yes | Yes | Should run before most implementation tasks |
+| 3 | `20260625-163246-549133` | Present | Sufficient after architecture contract | Yes | Yes | Depends on architecture vocabulary and command list |
+| 4 | `20260625-163308-046461` | Present | Sufficient after architecture contract | Yes | Yes | Depends on architecture vocabulary; should precede sync/watch |
+| 5 | `20260625-160751-353900` | Present | Sufficient, but requires current olcli source/license lookup | Yes | Yes | Architecture should define adapter boundary; network access may be needed |
+| 6 | `20260625-160853-429297` | Present | Sufficient after olcli import and architecture contract | Yes | Yes | Depends on olcli import, backend interface, and auth model |
+| 7 | `20260625-160804-867992` | Present | Sufficient; security paths are documented | Yes | Yes | Should follow CLI behavior contract; should precede command flows |
+| 8 | `20260625-160819-417512` | Present | Sufficient after config/auth and CLI behavior | Yes | Yes | Depends on config schema, ignore rules, CLI output/exit codes |
+| 9 | `20260625-160836-699088` | Present | Sufficient after config/auth, init, CLI behavior | Yes | Yes | Uses placeholder auth values only; no real account required |
+| 10 | `20260625-160912-750072` | Present | Sufficient after sync state, backend, config/auth | Yes | Yes | Depends on fake backend, sync plan contract, ignore rules |
+| 11 | `20260625-160925-146032` | Present | Sufficient after backend, config/auth, CLI behavior | Yes | Yes | Depends on compile adapter and PDF path ownership |
+| 12 | `20260625-165248-545991` | Present | Medium; real private interface behavior is uncertain | Yes with fake tests | Yes for fake tests | Depends on compile flow and adapter; real behavior belongs in E2E |
+| 13 | `20260625-160938-324045` | Present | Sufficient after sync and compile | Yes | Yes | Depends on sync safety, compile command, watch queue contract |
+| 14 | `20260625-162413-873208` | Present | Sufficient after core fake-backend commands exist | Yes | Yes | Depends on init, auth, sync, compile, watch flows |
+| 15 | `20260625-160946-910101` | Present | Sufficient in current `todo.md`; handoff copy should be refreshed | Conditional | Conditional | Requires pre-provided local E2E placeholders; blocks if missing or invalid |
+| 16 | `20260625-162426-756284` | Present | Sufficient but broad | Yes | Yes | Depends on stable core behavior; CI/platform access needed |
+| 17 | `20260625-162438-154174` | Present | Sufficient after code and notices stabilize | Yes | Yes | Depends on olcli notice state and package contents |
+| 18 | `20260625-162447-918619` | Present | Sufficient after core commands and docs stabilize | Yes | Yes | Must use placeholders only; depends on stable config examples |
+| 19 | `20260625-161006-526237` | Present | Sufficient but broad final-doc task | Yes | Yes | Depends on core implementation, examples, gates, E2E decision |
+| 20 | `20260625-162518-364796` | Present | Sufficient as final gate | Yes | Yes | Must wait for all prior tasks; cannot fake real E2E status |
+
+## Dependency Graph
+
+Primary prerequisite relationships:
+
+- `20260625-163340-992326` audit completes first so any queue reorder has a documented basis.
+- `20260625-163153-333824` architecture contract should precede CLI, config/auth, backend, sync, compile, watch, diagnostics, fixtures, and docs that refer to internal module boundaries.
+- `20260625-163246-549133` CLI behavior and exit-code contract should precede command implementation tasks: init, auth/status/doctor, sync, compile, watch, status-like diagnostics, and integration tests.
+- `20260625-163308-046461` sync state machine should precede sync and watch so conflict semantics and snapshot ownership are shared.
+- `20260625-160804-867992` config/auth security should precede init, auth/status/doctor, sync, compile, watch, local sandbox, real E2E, examples, and release gates.
+- `20260625-160751-353900` olcli import/license should precede `20260625-160853-429297` backend adapter.
+- `20260625-160853-429297` backend adapter should precede sync, compile, fast fallback, local sandbox, and real E2E.
+- `20260625-160819-417512` init should precede auth/status/doctor and most user-flow integration tests because it establishes project binding.
+- `20260625-160912-750072` sync and `20260625-160925-146032` compile should precede `20260625-160938-324045` watch.
+- `20260625-160925-146032` compile should precede `20260625-165248-545991` fast/draft fallback.
+- `20260625-162413-873208` local sandbox regression should run after the fake-backend core flows exist.
+- `20260625-160946-910101` real E2E should run only after gated test handling, local secret loading, sync, compile, and fallback fake coverage exist.
+- `20260625-162426-756284`, `20260625-162438-154174`, `20260625-162447-918619`, and `20260625-161006-526237` are hardening, package, example, and documentation tasks that should follow stable core behavior.
+- `20260625-162518-364796` release-candidate freeze is last and depends on every prior result.
+
+## Recommended Execution Order
+
+This order preserves every current `todo.md` task exactly once. It is a recommendation only; no automatic reorder was performed.
+
+1. `20260625-163340-992326` - 审计 QuickDev 队列顺序与任务可执行性. Finish and verify the current governance task before changing execution strategy.
+2. `20260625-163153-333824` - 冻结 v1 架构模块与公共接口契约. Establish module boundaries, shared types, file ownership, and adapter boundaries.
+3. `20260625-163246-549133` - 统一 CLI 行为输出与退出码规范. Lock command UX, output streams, non-interactive behavior, redaction, and exit codes.
+4. `20260625-163308-046461` - 定义同步状态机快照与冲突报告格式. Lock sync/watch conflict semantics before implementation.
+5. `20260625-160804-867992` - 建立项目配置认证与安全基础设施. Implement config/auth, local-only secret storage, schema validation, redaction, and ignore handling before user-flow commands.
+6. `20260625-160751-353900` - 引入 olcli 后端代码与许可证合规. Bring in backend foundation with MIT attribution before wrapping it.
+7. `20260625-160853-429297` - 实现 Overleaf 后端适配层. Encapsulate imported backend details behind the stable internal adapter and fake backend.
+8. `20260625-160819-417512` - 实现 olcx init 与 VS Code 配置生成. Implement binding and local project setup after config schema and CLI contract exist.
+9. `20260625-160836-699088` - 实现 olcx auth status doctor. Implement auth entry and diagnostics after project binding and config/auth storage exist.
+10. `20260625-160912-750072` - 实现安全双向同步与冲突暂停. Implement safe sync using the state-machine contract, backend adapter, and ignore rules.
+11. `20260625-160925-146032` - 实现远程编译和 PDF 下载. Implement compile and PDF download using the backend adapter and config ownership.
+12. `20260625-165248-545991` - 实现 Overleaf 编译超时快速模式降级恢复. Extend compile after the baseline compile flow exists; verify real behavior later through gated E2E where possible.
+13. `20260625-160938-324045` - 实现 olcx watch 自动工作流. Compose sync and compile into the debounced watcher only after both manual commands are stable.
+14. `20260625-162413-873208` - 全链路本地沙箱回归测试. Validate the complete fake-backend CLI journey before real external testing.
+15. `20260625-160946-910101` - 真实 Overleaf 集成 E2E 测试. Run only when local E2E placeholders are already provided; if missing or invalid, this task should block per its own constraints.
+16. `20260625-162426-756284` - 跨平台与无头环境兼容性验证. Broaden platform confidence after the core flow is stable.
+17. `20260625-162438-154174` - 安全许可证与供应链发布门禁. Add publish gates once code, notices, package contents, and E2E skip behavior are known.
+18. `20260625-162447-918619` - 示例论文项目与故障排查资料. Create placeholder-only examples and troubleshooting after behavior and gates stabilize.
+19. `20260625-161006-526237` - 文档发布与社区维护完善. Finalize public docs after examples, gates, platform notes, and E2E status are known.
+20. `20260625-162518-364796` - v1 发布候选总验收与冻结. Final gate; must not claim stable release readiness without honest E2E status.
+
+## Directly Executable Tasks
+
+Directly executable here means the task has enough information for `plan`, `actor`, and `verify` roles and does not require real Overleaf account participation. It may still need earlier prerequisite tasks to complete first.
+
+- Immediate under current FIFO: `20260625-163340-992326`.
+- Directly executable after the current audit is archived: `20260625-163153-333824`, `20260625-163246-549133`, `20260625-163308-046461`.
+- Directly executable after their prerequisites complete, using fake backends or placeholders only: `20260625-160804-867992`, `20260625-160751-353900`, `20260625-160853-429297`, `20260625-160819-417512`, `20260625-160836-699088`, `20260625-160912-750072`, `20260625-160925-146032`, `20260625-165248-545991`, `20260625-160938-324045`, `20260625-162413-873208`, `20260625-162426-756284`, `20260625-162438-154174`, `20260625-162447-918619`, `20260625-161006-526237`, `20260625-162518-364796`.
+
+## Should Be Frontloaded
+
+- `20260625-163153-333824` architecture contract: prevents command, backend, sync, compile, watch, and fixture tasks from inventing incompatible module boundaries.
+- `20260625-163246-549133` CLI behavior contract: prevents inconsistent help text, exit codes, output streams, non-interactive behavior, and redaction behavior across commands.
+- `20260625-163308-046461` sync state machine: prevents sync and watch from diverging on conflict, delete, ignore, and snapshot semantics.
+- `20260625-160804-867992` config/auth security infrastructure: should be implemented before user-flow commands because it owns `.olcx/config.json`, `.olcx/auth.local.json`, redaction, and ignore behavior.
+- `20260625-160751-353900` olcli import/license and `20260625-160853-429297` backend adapter: should precede network-facing sync, compile, fallback, and E2E work.
+
+## Needs User Or Test Account Participation
+
+- `20260625-160946-910101` real Overleaf E2E requires pre-provided local-only test values such as `OLCX_E2E_ENABLE_REAL`, `OLCX_E2E_OVERLEAF_SESSION`, `OLCX_E2E_PROJECT_ID`, optional `OLCX_E2E_ACCOUNT_LABEL`, and optional `OLCX_E2E_PROJECT_URL`, or equivalent `.env.e2e.local` entries. Do not write real values into git, queue files, docs, or handoff reports.
+- `20260625-165248-545991` fast/draft fallback can be implemented and verified with fake backend coverage, but real fallback behavior depends on Overleaf private interface availability and should be covered by the gated E2E task when feasible.
+- `20260625-162518-364796` release-candidate freeze needs a user/release decision if real E2E was skipped, blocked, or unavailable. It must report that limitation instead of treating stable release readiness as verified.
+- Any reorder of `todo.md` requires explicit user confirmation before editing queue state.
+
+## Needs Split Or Clarification
+
+No task is missing required QuickDev fields. These are execution-risk clarifications, not reasons to mutate status during this audit.
+
+- `20260625-160946-910101`: current `todo.md` and its existing `00-task.md` handoff copy differ. Before execution, refresh the handoff copy from the current queue block or have the plan role explicitly cite `todo.md` as authoritative.
+- `20260625-165248-545991`: fast/draft fallback may need a small discovery subtask if the adapter cannot safely identify compile-setting APIs. Keep the fallback implementation separate from real E2E proof.
+- `20260625-162426-756284`: broad across CI, platform path handling, environment variables, and watch behavior. Split into CI matrix plus platform-specific test/doc subtasks if the actor cannot keep the change reviewable.
+- `20260625-161006-526237`: broad public documentation and maintenance task. Split README/tutorial, release docs, and contributor docs if it becomes too large for one reviewable actor pass.
+
+## Reorder Safety
+
+QuickDev is FIFO and append-only by default: the manager reads `todo.md` from top to bottom and selects the first task with `status: todo`. Skipping, deleting, or moving blocks without explicit confirmation would violate `goal.md` and could hide user intent.
+
+No automatic reorder was performed in this audit. Safe manual reorder procedure, only after user confirmation:
+
+1. Stop the queue manager before editing.
+2. Confirm the exact recommended order and whether credential-dependent E2E should remain before later non-secret hardening tasks or be deferred.
+3. Back up `todo.md`.
+4. Move whole `<!-- quickdev-task:start ... -->` through `<!-- quickdev-task:end -->` blocks only; never edit IDs, titles, statuses, handoff directories, or task text while reordering.
+5. Preserve every current task exactly once.
+6. Run a block-count check and inspect `git diff -- todo.md`.
+7. Resume QuickDev only after the user approves the diff.
+
+If no user confirmation is given, keep FIFO execution. Under the current queue, the next implementation-relevant tasks after this audit are already the three frontloaded contract tasks.
+
+## Security Review
+
+This audit includes only policy names, placeholder variable names, paths, and task IDs. It does not include real credentials, raw cookie values, session values, passwords, private Overleaf project IDs, or real paper content.
+
+Security requirements to preserve during future tasks:
+
+- Project-local auth belongs in `.olcx/auth.local.json`.
+- `.olcx/auth.local.json`, `.olcx/*.local.json`, `.olcx/*.secret.json`, and `.env.e2e.local` must remain ignored by Git.
+- `.env.e2e.example` may contain empty placeholder variable names only.
+- Fixtures, examples, docs, QuickDev handoff files, CI logs, and npm packages must not contain real credentials, private project IDs, or private paper content.
+- Sync, watch, and package gates must explicitly avoid uploading or publishing local auth, generated PDFs, build artifacts, and unredacted logs.
+
+## Git State Notes
+
+Pre-audit `git status --short` showed:
+
+- `M .gitignore`
+- `?? .env.e2e.example`
+- `?? done.md`
+- `?? goal.md`
+- `?? tmp/`
+- `?? todo.md`
+
+The `.gitignore` diff observed during audit adds an allowlist entry for `.env.e2e.example`. The QuickDev queue files and `tmp/` directory were already untracked or modified before this actor wrote the audit. This audit is expected to add `docs/quickdev-queue-audit.md` and `tmp/20260625-163340-992326-审计 QuickDev 队列顺序与任务可执行性/20-actor-report.md` only. It must not change `todo.md`, `done.md`, or `goal.md`.