feat: add agent-assisted secondary development workflow

[samuel--hu]

Summary

• Put a business-goal/material-driven start → assess → needsInput → doctor → execute → verify path in front of the existing agent workflow.
• Let ordinary users describe the outcome, available materials, and target context while the agent selects compatible repository assets and official toolchain routes.
• Treat a development host plus credentials plus an explicit connect/check/develop request as task-scoped remote-execution authority without storing credentials in workflow records.
• Enforce chip, artifact, and toolchain compatibility at doctor admission using repository-backed facts while keeping unknown routes explorable.
• Separate conversion evidence from device and business acceptance, add deterministic verification seals, and make evidence lifecycle explicit and revocable.

Root cause

The earlier workflow exposed implementation choices too early and treated credential-bearing user input primarily as something to reject. A normal user could provide a valid isolated development machine and explicitly ask the agent to connect, yet still encounter extra forms, SSH-key setup, or a blocked execution path.

Its fixed-version posture also made repository examples look like universal requirements. Compatible environments supported by current upstream instructions could therefore be rejected even when the required compiler capabilities were callable.

Finally, a generic verified label could be overread as device or business acceptance. Downstream documentation and example promotion had no machine-readable proof of the completed chain, no explicit device-validation gap, and no lifecycle state for retracting invalid evidence.

What changed

Intent and remote environment entry

• scripts/agent/start.sh / start.ps1 creates a private run from ordinary intent, copies named material into the ignored run directory, and performs the first assessment.
• --user-requested-remote-access records authority already expressed by the user. It grants remote-execution and, when material is named for the remote task, model-transfer.
• Credential-like text and private addresses are sanitized in task records instead of blocking creation.
• scripts/agent/connect.sh / connect.ps1 opens task-authorized interactive OpenSSH. The password is accepted only by the OpenSSH prompt; it is not a script argument, environment value, task JSON field, or evidence field.
• Remote read-only discovery may begin while the route still has unrelated NEEDS_INPUT; an explicitly UNSUPPORTED route still stops connection. Formal doctor admission requires a current READY assessment.
• Windows remains a supported orchestration, assessment, and SSH entry; Sophon conversion routes to an admitted isolated Linux x86_64 environment.

Capability-based admission

• Doctor now checks a repository-derived compatibility matrix across target chip, artifact type, and toolchain.
• Explicit contradictions, such as BM1688 paired with CV186X-only material, fail with both mismatching parties named.
• Missing repository facts produce UNVERIFIED, not a guessed pass or a forced recipe, so upstream-supported routes can still be investigated.
• The workflow continues to admit callable capabilities rather than one globally fixed version or exhaustive scaffold list.

Evidence declaration boundary

• Example status is now candidate | conversion-verified; legacy verified records are read as conversion-verified.
• Human-readable verification and recording output always states the status, covered conversion stages, device/business exclusions, device-validation state, and seal.
• Successful verification writes seal.json with the chain status, run ID, toolchain digest, commit, tree, and issue time, plus a short CE1-... reference code.
• Promotion to conversion-verified requires a valid seal. A missing seal still permits a candidate record.
• Optional device evidence is stored only as a sanitized opaque reference. It is not a prerequisite for conversion verification and does not copy customer evidence into the repository.
• Evidence lifecycle is orthogonal to verification level: records are active or revoked; revoked records remain auditable but cannot be promoted, selected, or used for new recordings.
• Official example eligibility requires conversion-verified + active + valid seal. The short code is only a reference and is not proof by itself.
• The example index and promotion mechanism remain marked Beta until the first qualifying example is produced.

User and developer impact

A user can say, in one private interaction, “connect to this isolated Linux development machine, inspect readiness, and continue,” then provide the host, account, and password. The repository mechanism records only sanitized task authority and lets the agent connect without another authorization round trip.

Users do not need to preselect conversion internals. The agent can explore routes supported by repository facts or official upstream guidance, while mechanical constraints apply only when compatibility or verification claims enter shared artifacts.

Credentials alone are not interpreted as authority. Dependency installation, sudo, global configuration changes, production access, and test-device writes remain separate decisions when necessary. Conversation or terminal history may still retain connection details, so the documented path requires an isolated machine, least-privilege or temporary account, and a rotatable password.

Scope and data boundaries

• Private materials and run records remain under Git-ignored output/agent-runs/<run-id>/.
• Raw host, account, password, customer/site data, transcripts, runtime outputs, model binaries, and device evidence contents are not included.
• Repository events store only sanitized connection results; no password API is exposed.
• No production or test device was contacted by the implementation or test suite.
• MERGE_PLAN.md remains local process material and is not part of this PR.

Candidate identity

• Candidate commit: db8343d19b11b3006e59204b9aff050fe668e6b4
• Candidate tree: ed033702dd8c6d087ff251a90eef812bbc6c3401
• Branch: codex/agent-assisted-development

Local verification

• python3 -m unittest discover -s test/agent -p 'test_*.py' — 55 tests passed.
• Focused evidence lifecycle, status migration, and seal tests — 3 tests passed.
• Tutorial documentation check — 10 core pages, 2 indexes, bilingual pairs, links, images, and navigation passed.
• VitePress 1.6.4 documentation build — passed.
• Rendered tutorial smoke — 10 bilingual pages passed.
• Bash and PowerShell syntax checks — passed.
• Python compilation, JSON parsing, sensitive-data scope audit, and git diff --check — passed.

Acceptance and remaining evidence

Local deterministic validation is complete for this candidate. GitHub checks for the new head are evaluated separately from the previously green commit.

No live SSH login, real TPU-MLIR conversion, or device acceptance was performed for this candidate. Those layers remain NOT_RUN and are explicitly outside this PR acceptance claim. Ready-for-review status qualifies only the repository workflow implementation; it is not a conversion, device, or production acceptance result.