[calvin-archastro]

Review on ArchCode

Problem

In a live Factory run on 2026-09-28 (archdev 0.46.12), workers failed risk-backed event posts 9+ times in the first hour. The skill text caused each failure:

1. task.lifecycle requires a risk assessment. In 6 of 7 cases the worker had already run extract brief and extract finalize, but left the sealed result out of the event value's "risk" field. Nothing in the skill said to put it there. The Report steps had workers author the value before sealing and never mentioned risk.
2. /producer/role enum error. The worker used "implementer". The allowed values are author, assessor and human, and the skill never listed them.
3. Risk definition must be risk.<type>[@<version>], got "risk.task.started". The skill used one <type> placeholder for both extract brief risk.<type> and log post --event <type>, so the worker took the event name to be the definition.

A coordinator also saw this on 0.46.12: extract run --sink file:<dir>/ writes a nested envelope {key, provenance, schema, value}. Passing that file to log post --payload-file, as the <envelope> placeholder suggests, fails with Unrecognized keys: "schema", "key", "provenance", "value".

This is the skill-side companion to https://archdev.ai/ArchAstro/firstlanding/pull/15749. That PR changes the CLI's contract text, the extract guide output and the errors. It also adds risk-event-steps.ts, so extract context <extractor> <ref> prints the filled-in sequence under authoring.

What changed

Docs only: archdev/references/monitor.md and archdev/SKILL.md.

• Report: one ordered sequence that matches the CLI's authoring steps: extract brief risk.task → author {input, assessment} (producer.role is author/assessor/human) → extract finalize risk.task → mitigate and recompute → extract context task.lifecycle <id> → author the value with "risk" set to the whole sealed result.json → optional extract run → log post --event task.started --assessment <dir>/sealed/result.json. A table maps each family (task, plan, pr) to its risk definition, extractor ref, subject source and event names.
• It states plainly that the definition is the resource type (risk.task, risk.plan, risk.pr), never the event name.
• Placeholders: <resource> for the risk definition, <event> for --event, and <dir> for scratch output. <type> is no longer used for either.
• PR subject: the source is archdev:pr:<owner/repo>#<num>, never a pull request URL. This matches the #15749 review fix. Code-region seals still keep the collected URL subject, as before.
• Risk assessments: the steps are reordered the same way (brief, judgment, seal, mitigate, event value, post). producer.role values are listed, and the text explains why a missing risk fails extract run while log post takes the seal from --assessment. Cross-references from the Focus range seals section are renumbered.
• Events without an assessment: --payload-file takes the value object, never the envelope. The text shows how to find the nested sink file (find <dir>/out -name '*.json') and pull out the envelope value file (jq .value <envelope.json> > <dir>/event.json).
• SKILL.md: the stopping-point summary repeats the definition-vs-event rule, the role values and the "risk" field.

Unchanged: the text stays generic, with no repo-specific content. The mitigate-and-recompute rules and the PR annotation flow are the same.

Scope / risk / user impact

• Scope: docs only (skill text).
• Risk: low. No code changes. The bootstrap scripts are untouched.
• User impact: agents that load the skill get a sequence that passes validation on the first attempt. The authoring block in extract context needs the CLI release that includes #15749, so the text says "current CLIs" for that part.

Testing

• scripts/test-skill-bootstrap.sh: all cases pass. This is the repo's only local check, and it covers the bootstrap script rather than the docs. pwsh was not available locally, so CI runs the PowerShell variants.
• markdownlint-cli2 on both files: no new errors besides the MD013/MD060 table and line-length style the existing files already have. Two <dir>-leading line wraps that broke code spans were fixed.
• No end-to-end test applies to skill prose. The CLI side's end-to-end proof is src/ts/archdev/src/__tests__/e2e/archdev-risk-event-sequence.e2e.test.ts in #15749.

Follow-ups

• The CLI's own hook and nudge text still says --payload-file <envelope>: repo/activity.ts, repo/monitor-nudges.ts and the log help in org-log.ts. That belongs in firstlanding, not this repo.

🤖 Generated with Claude Code