feat(docx-markdoc)!: remove the deprecated operation=/operations= spellings

[stevenobiajulu]

Summary

The operation= / operations= spellings that #1105 deprecated (shipped in 0.21.2 with a DEPRECATED_EDIT_ATTRIBUTE warning) are now removed. While both were accepted, every agent or reviewer reading a .mdoc file had to know two names for one thing, and agents trained on older examples kept writing the old one because a warning is easy to miss in a compile log.

• editName() in packages/docx-markdoc/src/markdoc.ts: any operation= (on change, replace-source, delete-source, insert-before, insert-after, insert-table-rows, delete-table-row, annotation) or operations= (on change-set) now produces a validation error REMOVED_EDIT_ATTRIBUTE with a migration message, operation= was renamed to edit=; rename the attribute. (operations= to edits= likewise). The error comes from the Markdoc schema itself (a custom attribute type on the retained operation/operations declarations), so raw Markdoc.validate against the exported markdocConfig reports it too, not only parseMarkdoc/CLI/compile It is reported whether or not edit=/edits= is also set, so CONFLICTING_EDIT_ATTRIBUTES is no longer reachable and is gone.
• The old attributes stay declared in the Markdoc schema on purpose (with that custom type): this way the user gets the targeted migration error instead of a generic Markdoc invalid-attribute rejection. The old value still feeds cross-reference resolution, so a not-yet-migrated file gets one error per tag, not a pile of orphan-rationale / missing-name errors on top.
• DEPRECATED_EDIT_ATTRIBUTE is deleted. The general non-fatal warnings channel (ValidationResult.warnings, certificate.markdocWarnings, CLI stderr) stays as-is. It currently has no producer, but removing it would be a separate API change.
• Tests: SDX-MDOC-148 now covers the new error for both spellings and every edit tag plus annotation (code, message, line, requireMarkdoc/compileMarkdoc rejection, raw Markdoc.validate with the exported markdocConfig, and that renaming the attribute makes the same file validate without warnings). SDX-MDOC-149 covers the old spelling beside the new one. SDX-MDOC-147 (unchanged) covers edit=/edits= files, and SDX-MDOC-150 (unchanged) covers byte-identical import. The CLI test SDX-MDOC-152 uses the new code.
• openspec change rename-markdoc-operation-to-edit: requirement text, scenarios 148/149, proposal (BREAKING note) and tasks updated. openspec validate --strict passes.
• README note and a CHANGELOG ## Unreleased entry marked Breaking with the migration: rename the attribute.

Migration for existing .mdoc files: rename operation= to edit= and operations= to edits=.

Checks

npm run build, npm run lint:workspaces, npm run test:run, npm run check:spec-coverage all pass locally. (There is no test:coverage script for @usejunior/docx-markdoc on main yet, so no coverage ratchet applies.)

Closes #1106

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
site	Ready	Preview	Sep 30, 2026 9:27pm UTC

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-30T21:05:10.286056Z	4b8e8c7	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[usejunior-llm-gate]

LLM gate (advisory)

All evaluated rules passed - 5 pass, 0 warn, 0 error, 11 skipped, 16 total

Findings

None.

All 16 rules (5 evaluated, 11 skipped)

Rule	Verdict	Detail
read_file response metadata parity	SKIPPED	paths not touched by this PR
Live DOM namespace-safe OOXML writes	SKIPPED	paths not touched by this PR
Complex-field revisions preserve complete accept/reject state machines	PASS	The PR does not touch field atomization, validateFieldStructure, w:fldChar, w:instrText, w:delInstrText, or collapsed-field comparison logic, as it only removes the deprecated operation attributes in packages/docx-markdoc.
Field validation per story, not global	SKIPPED	paths not touched by this PR
Revision IDs seeded from all revision-bearing side parts	SKIPPED	paths not touched by this PR
Accept/reject sweep side parts and caches	PASS	The PR does not touch DocxDocument.acceptChanges, DocxDocument.rejectChanges, REVISION_STORY_PART_PATHS, accept_changes, reject_changes, or side-part revision markup; it only modifies packages/docx-markdoc to remove the deprecated operation/operations attributes.
DocumentViewNode.heading stays canonical	SKIPPED	paths not touched by this PR
AI-author parity across entry points	SKIPPED	paths not touched by this PR
Property-change wrapper discipline	SKIPPED	paths not touched by this PR
SUPPORT.md Table A drift vs. implementation	SKIPPED	paths not touched by this PR
Table A / Table B boundary on side-part revisions	SKIPPED	paths not touched by this PR
Canonical-emission surface completeness	SKIPPED	paths not touched by this PR
Unit-test quality (avoid tautological / change-detector tests)	PASS	The modified tests in packages/docx-markdoc/src/cli-options.test.ts:126-135 and packages/docx-markdoc/src/edit-attribute.test.ts:111-195 thoroughly exercise the new validation behavior of removed edit attributes. Assertions are independent of the SUT, constructing concrete expected values (such as specific error codes and migration messages) from first principles without any SUT mocking or tautological checks.
Re-derived facts vs canonical sources	PASS	The PR only modifies markdoc attribute validation and parsing in packages/docx-markdoc and does not add any logic that re-computes facts or OOXML structures derived elsewhere.
.openspec tag ↔ test-assertion drift	PASS	The PR modifies and adds tests for [SDX-MDOC-148] and [SDX-MDOC-149] in edit-attribute.test.ts:114-211. Each test body thoroughly and directly asserts all GIVEN/WHEN/THEN scenario clauses (error codes, messages, lines, config-level validation, and successful migration behavior) without any tag-stuffing.
Library stays general (no downstream-domain leakage)	SKIPPED	paths not touched by this PR

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[stevenobiajulu]

Codex peer review (gpt-5.6-sol): REQUEST CHANGES, both findings addressed in d06feed

The reviewer ran the targeted tests, the full docx-markdoc suite, lint/build, spec coverage, strict openspec validation, CLI probes and crafted parser probes. It confirmed:

• one error per tag that still uses the old spelling, with no missing-name or orphan-reference cascade
• independent faults are not masked (ORPHAN_RATIONALE, DUPLICATE_EDIT still fire)
• operation= on an annotation is rejected
• no remaining legacy syntax in docx-mcp, skills or docs

Adjudication

1. HIGH: the exported markdocConfig silently accepted operation=/operations=. Accepted. Raw Markdoc.validate(ast, markdocConfig) returned no errors while parseMarkdoc rejected the same file. The retained declarations now use a custom attribute type (RemovedEditAttribute) whose validate returns REMOVED_EDIT_ATTRIBUTE. The schema therefore emits the targeted error on every surface, and editName() no longer pushes a duplicate. The old value still feeds cross-reference resolution. The message is now operation= was renamed to edit=; rename the attribute.: the tag name was dropped because Markdoc's type validator gets only the attribute name, and the line number still pinpoints the tag. A new test (SDX-MDOC-148) runs raw Markdoc.validate with markdocConfig, imported from the package entry, over the singular, plural and both-spellings cases, plus a clean edits= control. The spec scenario is updated to match.
2. LOW: two doc comments still named deprecated spellings as warning producers (types.ts ValidationResult, markdoc.ts requireMarkdoc). Accepted. Both are now producer-neutral.

Re-ran after the fix: npm run build, lint:workspaces, check:spec-coverage, openspec validate --strict and test:run. All green except one docx-compare 5s timeout under full-suite load (pipeline-text-box-stories.test.ts), which passes in isolation (28/28).

[stevenobiajulu]

Post-merge smoke: PASS. Ran on merge commit d972566, whose docx-markdoc tree is identical to the tested worktree, against the real Bonterms mutual NDA (templates/bonterms-cc0-1.0/bonterms-mutual-nda/template.docx).

• Import: two runs produced identical .mdoc output, with 0 operation= occurrences.
• edit= / edits= edit: validate exit 0, and compile exit 0. It wrote clean.docx, redline.docx and verification.json. The certificate reports passed: true and deliveryReady: true, and change-set smoke is complete.
• The same edit spelled operation= / operations=: validate and compile both exit 1, with no output written. Errors:
  • REMOVED_EDIT_ATTRIBUTE: operation= was renamed to edit=; rename the attribute. (line 3)
  • REMOVED_EDIT_ATTRIBUTE: operations= was renamed to edits=; rename the attribute. (line 231)