msd-course-maintenance

name	msd-course-maintenance
description	Use when maintaining the MSD course lab manual, short-term student handbook, grading documents, or repository-facing teaching guidance for agentic software development.

MSD Course Maintenance

Purpose

Maintain the MSD course materials as student-facing delivery documents. The manual must let 同学们 independently reproduce the course workflow, produce auditable evidence, and avoid leaking local credentials, teacher-specific context, or private machine details.

This skill applies to README.md, instruction.md, grading documents, student-facing short-term/*.md, short-term/控制文档/, and project-level Agent guidance such as AGENTS.md or .codex/skills/*/SKILL.md.

Core Position

• Write for 同学 or 同学们, not for a teacher, a maintainer machine, or a single local identity.
• Use objective, common assumptions. Do not imply that every student already has a specific old Ubuntu, a specific account, or a specific credential.
• The main student environment is Windows 11 + Ubuntu（WSL2）24.04 LTS.
• Whenever Ubuntu is mentioned in the handbook, write Ubuntu（WSL2） unless the context is explicitly a generic Linux note.
• The short-term handbook is the delivery artifact. Student-facing Markdown lives directly under short-term/; internal calibration logs and maintainer materials belong under short-term/控制文档/, not in student-facing docs.
• Never delete the root short-term directory.

Student Handbook Contract

For student-facing short-term/*.md:

• 00-学习方式.md is the entry document and must carry the learning method, dependencies, evidence policy, and D01-D11/提交期 navigation.
• D files are named D01.md through D11.md for stable sorting.
• D01 includes all required software installation, configuration, verification, and safety notes.
• D02 covers local models, domestic mirror or offline fallback, online API purchase/configuration, OpenCode Go, Hermes Studio/CLI, and Key handling.
• D03-D05 build the runnable project skeleton, Agent rules, roles, project-level skill, model roster, and task-card method.
• D06-D07 produce PRD/SPEC/DESIGN/ADR. Loop Engineering belongs here as evidence-based review of requirements and design, not as a vague “iterate with AI” slogan.
• D08 covers remote repositories, GitHub/Gitee or equivalent platforms, PR/MR/合并请求, local CI, and account-permission options.
• D09-D11 cover task cards, vertical slice implementation, UAT, evidence, and the transition into the submission period.
• 提交期.md is a separate self-chosen project delivery phase of no less than 4 weeks, not a 4-hour cleanup step. Final submission format is fixed: two weekly journals, one final report, and one defense PPT; repository assets such as README, PROCESS, docs, process, and evidence are evidence sources to be summarized or indexed in those four submitted files, not extra submitted file categories.
• 附录.md should support both D01-D11 and 提交期 with reusable checks, templates, and troubleshooting.
• arena-lite-参考规格.md is the student-facing D06 reference spec and should stay in short-term/ root unless the public packaging contract changes.
• arena-lite-reference/ is the student-facing reference implementation for the follow-along arena-lite project and should stay in short-term/ root unless the public packaging contract changes. It is for comparison, troubleshooting, and boundary understanding, not a student submission answer.
• 00-学习方式.html is the student-facing import demo for 00-学习方式.md and should stay in short-term/ root unless the public packaging contract changes.
• short-term/README.md is a thin student entrypoint. Maintainer routing, legacy handbooks, retest plans, internal demos, scratch work, and audit records stay under short-term/控制文档/.

Reproducibility Rules

Prefer CLI first. Every student-executed CLI step should include:

• the exact command,
• where to run it,
• expected output or status,
• common failure modes and QA,
• a verification command when possible.

For anything claimed as “run through”, record the actual command and evidence. If an online API, payment, login, remote permission, or Key entry needs human authorization, mark it as an artificial authorization node until authorized and retested.

Do not write “let AI finish it” as the only step. AI/Agent work must include prompt, role/model, expected files changed, verification command, and review result.

GUI/TUI Policy

Do not embed screenshots or image assets in the student handbook source. The handbook should describe what students must capture, where to save it, and how to redact it; it should not contain real .png/.jpg evidence or Markdown image embeds.

Students may be required to submit screenshot evidence for GUI-only confirmations, account authorization pages, provider/model status pages, PR/MR pages, and other visual states. Screenshot evidence must have a redacted filename and path, be referenced from the relevant Dxx evidence list or PROCESS.md, and never expose API Keys, tokens, balances, payment details, private accounts, private domains, or unredacted personal information.

When GUI or TUI use is required, embed text operation records in the relevant Dxx document, not in a detached screenshot appendix. GUI/TUI records should capture:

• Tool: OpenCode TUI/Desktop, Hermes CLI/Studio, browser GUI, Docker Desktop, or equivalent.
• Project path or workspace, with private user paths redacted when submitted.
• Role and Model when an Agent is involved.
• Prompt summary, without secrets or full pasted source.
• Agent output summary and files changed.
• Follow-up verification command and result.
• Review conclusion.

Configuration can be done by CLI when safer or more reproducible; GUI should confirm visible status only with text such as connected, logged in, model available, or equivalent.

Identity and Naming

• Student IDs are 10 digits.
• Use <10位学号> in student-facing placeholders.
• Concentrated D01-D11 work uses MSD_STUDENT_ID.
• Submission-period group projects use MSD_GROUP_ID, MSD_PROJECT_ID, and MSD_DELIVERY_ID.
• Workspaces, branches, model aliases, records, logs, reports, PR/MR titles, and evidence files must include the required identifier.
• Do not mix personal student ID and group delivery ID in the same submission-phase filename unless the document is an explicit member mapping.

Style and Language

• Main explanations are in Chinese.
• Address readers as 同学 or 同学们.
• Keep structure fields and technical identifiers in English: filenames, YAML/JSON keys, function names, command names, parameter names, API fields, branch names.
• Trigger descriptions in project skills may mix Chinese and English, but skill name, frontmatter keys, and machine-readable fields stay English.
• Explain a specialized term the first time it appears.
• Chapter introductions should be warm, concrete, and case-based. Explain why the chapter matters, where it sits in the whole manual, and what breaks later if skipped.
• Do not make chapter openings stiff checklist prose when a short scenario can make the purpose clearer.

Code and Follow-Along Projects

• Generate complete follow-along project code in the project workspace.
• Do not paste full business source code into the manual.
• In the manual, include CLI commands, prompts, expected outputs, verification commands, acceptance criteria, and only small core code snippets when necessary.
• Daily workload should be balanced against actual implementation effort. If a task-card set exceeds a day’s capacity, either narrow the required slice or adjust the estimated work time.

Model and Agent Policy

Teach multi-model collaboration, not one model pretending to be every role.

Model rosters should discuss:

• capability,
• cost,
• latency,
• context length,
• privacy boundary,
• allowed data,
• forbidden data,
• budget cap,
• fallback,
• evidence.

Use stronger reasoning models for PRD/SPEC/DESIGN/ADR audit, coding-oriented models for implementation, cheaper models for summarization or task-card cleanup, and local models for offline drafts or privacy-sensitive material when suitable.

OpenCode Go, Hermes, Ollama, domestic mirrors, ModelScope, and offline model packages must have clear credential, endpoint, model-name, fallback, and verification rules. Do not let students search arbitrary model files without a course-approved repository, file name, checksum, license, or an explicit “await course package” node.

Safety and Privacy

Never persist real secrets in student-facing docs:

• API Keys, Tokens, passwords, OTPs,
• private endpoints,
• personal payment details,
• private SSH keys,
• real maintainer account names,
• real remote URLs from calibration,
• local machine-only paths or credential filenames that identify a maintainer.

Student docs may show placeholders such as <GITHUB_ORG>, <REMOTE_URL>, <COURSE_DEVICE_LABEL>, <COMMIT_SHA>, and <10位学号>.

Real run-through details, calibration repository URLs, local account names, and full commit SHAs belong in short-term/控制文档/复测/ or private operational notes, not in student-facing short-term/*.md.

Do not provide destructive copy-paste commands such as WSL unregister, broad recursive deletion, or project-external cleanup. If cleanup is unavoidable, make it non-destructive, scoped, and clearly bounded.

API Key guidance should prefer tool credential stores or session-only variables. If a file such as ~/.hermes/.env is used, label it plaintext-sensitive, require restrictive permissions, and include cleanup/rotation guidance.

Repository and Remote Policy

Remote repository documentation must be generic and portable:

• Explain both HTTPS + credential manager and SSH public-key paths.
• SSH public keys identify an account; repository access still depends on platform permissions.
• For students, prefer Gitee when the course does not specify another platform. Student instructions should present HTTPS + credential manager and SSH public-key as two credential options; students choose one route unless the teacher explicitly assigns otherwise.
• Do not require student GitHub/Gitee dual push in the handbook. If teachers or course maintainers publish materials to two platforms, keep that as maintainer-facing guidance, not as a student Dxx requirement. Maintainer dual push should use clear named remotes such as github and gitee; do not mix it with an ambiguous origin flow.
• PR/MR/合并请求 evidence must include platform, URL or redacted URL, source branch, target branch, latest SHA, status, review summary, and verification summary.
• git remote -v and git ls-remote records must redact real account names, organizations, private domains, and credential-bearing URLs.

Evidence and Assessment

Each day should define required deliverables and evidence records. Evidence must be committed or explicitly indexed:

• CLI outputs,
• GUI/TUI text records,
• redacted GUI screenshot evidence when the chapter requires visual confirmation,
• Agent prompt and output summaries,
• files changed,
• tests and scripts/check.sh or equivalent checks,
• security scan result,
• known limits and follow-up actions.

For final/submission work, include a rubric or scoring contract when the document is used for assessment. The rubric should cover PRD/SPEC, DESIGN/ADR, task cards, implementation quality, UAT, safety, process evidence, and defense materials.

For the submission period, collect all required submitted content into:

• submissions/${MSD_DELIVERY_ID}-weekly-1.md,
• submissions/${MSD_DELIVERY_ID}-weekly-2.md,
• submissions/${MSD_DELIVERY_ID}-final-report.md,
• submissions/${MSD_DELIVERY_ID}-defense.pptx.

Do not present README, PROCESS, docs, process, evidence, Gate records, UAT records, or separate defense outline/demo-script files as additional submitted files; they may remain in the repo as linked evidence sources.

Teacher Editing Consistency

These are maintainer rules for teachers or agents editing the handbook; do not push them into student daily tasks.

• Run a whole-handbook consistency pass after cross-cutting edits. The same concept must have one policy across 00-学习方式.md, D01-D11, 提交期.md, 附录.md, and this skill.
• If a contract changes in one chapter, update its producers, consumers, evidence lists, PROCESS.md index, appendix templates, and final checks in the same edit.
• Screenshot policy must stay consistent: students submit redacted screenshot evidence when required; handbook source does not embed screenshots.
• Remote policy must stay consistent: students use one platform, Gitee preferred unless the course says otherwise, and choose one credential route. Teacher/course-maintainer dual publication is not a student requirement.
• Internal calibration details, real run paths, test identities, full commit SHAs, real account names, real remote URLs, and maintainer credential labels stay in short-term/控制文档/复测/ or private notes, not in student-facing short-term/*.md.
• Do not write unqualified claims such as "已实测", "已验证", "已跑通", or "照做即可" in student-facing docs unless the same edit points to a public, reproducible student evidence command or a calibration record kept outside the handbook. Prefer "以同学本机生成的 evidence 为准" for student instructions.
• Do not put raw angle-bracket placeholders such as <10位学号> or <REMOTE_URL> in shell syntax positions inside executable bash, sh, or powershell code blocks. Use shell-safe quoted placeholder values or variables, plus an explicit validation command when possible. Angle-bracket fields are acceptable inside generated template bodies such as here-doc content.
• Use ## 本章证据 as the D01-D11 evidence section title. If a 产出物 list names all materials produced during the day, distinguish that from the smaller required-evidence list with wording such as "最终必交项见本章“本章证据”".
• Before finishing, check that Dxx evidence filenames, git add commands, appendix naming templates, and PROCESS.md indexes agree.

Verification Before Finishing

Before claiming the manual update is complete, run checks appropriate to the touched scope:

rg -n '!\[|<img|\]\([^)]*\.(png|jpe?g|webp|gif)' short-term --glob '*.md' --glob '!**/控制文档/**'
rg -n "额外截图|Do not use screenshots or image requirements|GitHub/Gitee 双平台|双平台交付|git push -u github|git push -u gitee|本机复测|short-term/控制文档/复测/runs|20260706-msd-2026000101" short-term --glob '*.md' --glob '!**/控制文档/**'
rg -n "已实测|已验证|已跑通|验证过|照做即可|主线已经" short-term --glob '*.md' --glob '!**/控制文档/**'
rg -n "required_votes.{0,40}3" short-term --glob '*.md' --glob '!**/控制文档/**' --glob '!D07.md'
rg -n "学习者|读者|新电脑|一台新电脑|<学号>|msd-<学号>" short-term --glob '*.md' --glob '!**/控制文档/**'
rg --pcre2 -n "sk-[A-Za-z0-9]{20,}|ghp_[A-Za-z0-9_]{20,}|github_pat_[A-Za-z0-9_]{20,}|glpat-[A-Za-z0-9_-]{20,}|AKIA[0-9A-Z]{16}|wsl --unregister|Remove-Item -Recurse|rm -rf /|git reset --hard|git checkout --" short-term --glob '*.md' --glob '!**/控制文档/**'
rg -n "[ \t]+$" short-term --glob '*.md' --glob '!**/控制文档/**'
rg -n "```(bash|sh|powershell)" short-term --glob '*.md' --glob '!**/控制文档/**'
git diff --check -- short-term ':!short-term/控制文档/**'

Also check Markdown fences:

Get-ChildItem -LiteralPath 'short-term' -Filter '*.md' |
  Sort-Object Name |
  ForEach-Object {
    $count = (Select-String -LiteralPath $_.FullName -Pattern '^```|^````' -Encoding UTF8).Count
    if ($count % 2 -eq 0) { "FENCE_OK $($_.Name) $count" } else { "FENCE_BAD $($_.Name) $count" }
  }

For executable command blocks, extract bash/sh fences and run them through bash -n; extract powershell fences and run them through the PowerShell AST parser. Treat raw angle-bracket placeholder syntax errors as documentation defects unless the block is explicitly marked as text or the placeholder is inside a generated template body.

For D01-D11, do not require a fixed GUI/TUI heading in student-facing text. Instead, verify semantically that GUI/TUI evidence and screenshot requirements only appear where the chapter workflow needs them, use evidence/ or evidence/screenshots/ paths, and do not expose editor-only consistency instructions to students.

Parallel Work

When using subagents or parallel workers, split by disjoint file ownership. Do not let two workers edit the same Dxx file. After workers return, the main agent must run a total integration pass for terminology, safety, evidence paths, Markdown structure, and cross-chapter dependencies.