@descent-vtt/spec-graph 0.10.0 → 0.11.0

package/CHANGELOG.md

@@ -11,6 +11,24 @@ the family's
 [versioning policy](https://github.com/DescentVTT/spec-core/blob/main/docs/adr/0009-versions-before-1-0.md)
 records.
 
+## 0.11.0
+
+spec-graph reads English only again, by the maintainer's decision; the
+two-column status table stays with English keys. spec-core's copy is
+unchanged.
+
+### Removed
+
+- Statuses, relations, obligation and bookkeeping headings and markers
+  written in Chinese are no longer read: a Chinese status word, `狀態` or
+  `状态` as a status key, heading, label or table key, and a full-width
+  colon after a status label or heading give an unknown phase, and a
+  Chinese phrase, heading or marker draws nothing. The two-column status
+  table stays, with `Status` and `State`, and so do the stop at `。？！；`
+  and a full-width comma or semicolon between successors (ADR-0002,
+  ADR-0003, ADR-0006). Upgrading: write the status in English, e.g.
+  `status: superseded`.
+
 ## 0.10.0
 
 Statuses, status tables, relations, obligations and markers written in

package/README.md

@@ -133,8 +133,9 @@ onto four phases, chosen so one question can be answered from the phase alone:
 | `frozen` | `final`, `ratified`, `locked`, `published`, … | **no** |
 | `retired` | `superseded`, `deprecated`, `rejected`, `withdrawn`, … | **no** |
 
-The status is found wherever your team writes it, in English or in Chinese
-(`## 狀態` / `已接受`), and however it is dressed (`**Accepted** (2026-03-01) ✅`):
+The status is found wherever your team writes it, and however it is dressed
+(`**Accepted** (2026-03-01) ✅`). A document may be written in any language; its
+status is read in English (`status: superseded`):
 
 - front matter: `status:`, `state:`, `stage:`
 - a `## Status` section
@@ -167,44 +168,14 @@ that `provisionally accepted` is a draft.
 | `active` | `accepted`, `active`, `approved`, `adopted`, `agreed`, `implementable`, `implemented`, `implementing`, `current`, `effective`, `in-effect`, `enforced`, `stable`, `merged`, `released`, `shipped`, `live`, `done`, `complete`, `completed`, `signed-off`, `committed` |
 | `draft` | `draft`, `drafting`, `proposed`, `proposal`, `provisional`, `provisionally-accepted`, `prospective`, `wip`, `work-in-progress`, `in-progress`, `in_progress`, `review`, `in-review`, `under-review`, `reviewing`, `discussion`, `discussing`, `pending`, `idea`, `exploratory`, `candidate`, `open`, `new`, `unreviewed`, `rfc`, `experimental`, `alpha`, `beta`, `incubating` |
 
-Chinese is read in Traditional and Simplified characters, each word as the
-English word it translates, so it lands in that word's row: `延後` is
-`deferred` and retired, `封存` is `archived` and a record, and `暫定` is
-`provisionally accepted`, so `暫定接受` is a draft.
-
-- **A Chinese word counts wherever it stands in the status**, because Chinese
-  puts no space between words: `已接受，後被ADR-0003取代` holds `已接受` and a
-  supersession.
-- **Except directly after a negation:** `不`, `未`, `非`, `沒`, `没`, `無`,
-  `无`, `勿`, `尚未` or `不再`. `未接受`, `尚未核准` and `不再生效` say nothing;
-  a word that starts with one, `不採納`, is itself.
-- **Superseded is also `被` followed by `取代`, `替代` or `取而代之`**, within 30
-  characters and in the same sentence: `已被 ADR-0003 取代` is retired, and
-  names ADR-0003 as what replaced it.
-- **`已取代` alone is retired.** Followed by a name, after spaces or a colon -
-  `已取代 ADR-0002` - it says what this document replaced, and is not read.
-- **`取代` with no `被`**, as in `已接受（取代 ADR-0002）`, retires nothing.
-
-| Phase | Chinese status words |
-| --- | --- |
-| `retired` | `已被取代`, `被取代`, `已取代`, `已棄用`, `棄用`, `已弃用`, `弃用`, `已廢棄`, `廢棄`, `已废弃`, `废弃`, `已停用`, `已過時`, `已过时`, `已否決`, `否決`, `已否决`, `否决`, `已拒絕`, `已拒绝`, `不採納`, `不采纳`, `已撤回`, `撤回`, `已作廢`, `作廢`, `已作废`, `作废`, `延後`, `延后`, `暫緩`, `暂缓`, `擱置`, `搁置` |
-| `record` | `封存`, `已封存`, `歸檔`, `已歸檔`, `归档`, `已归档` |
-| `frozen` | `已定案`, `定案`, `已凍結`, `已冻结` |
-| `active` | `已接受`, `接受`, `已採納`, `採納`, `已采纳`, `采纳`, `已核准`, `核准`, `已批准`, `批准`, `已生效`, `生效`, `已實施`, `已实施`, `已完成` |
-| `draft` | `暫定`, `暂定`, `草稿`, `草案`, `提議`, `提议`, `提案`, `審查中`, `审查中`, `審核中`, `审核中`, `討論中`, `讨论中`, `待審`, `待审`, `待審核`, `待审核` |
-
 | Where | Read from |
 | --- | --- |
-| Front matter, the first key present | `status`, `狀態`, `状态`, `state`, `stage`, `lifecycle`, `phase`, `adr-status` |
-| A section, under the heading, with or without a colon, `:` or `：` | `Status`, `State`, `Stage`, `Lifecycle`, `Current status`, `狀態`, `状态` |
-| A two-column table above the first `##`, in the cell right of the first key in the left column, the header row included | `Status`, `State`, `狀態`, `状态` |
+| Front matter, the first key present | `status`, `state`, `stage`, `lifecycle`, `phase`, `adr-status` |
+| A section, under the heading, with or without a colon | `Status`, `State`, `Stage`, `Lifecycle`, `Current status` |
+| A two-column table above the first `##`, in the cell right of the first key in the left column, the header row included | `Status`, `State` |
 | A directory, for a document that declares no status | `archive`, `archived`, `attic`, `deprecated`, `graveyard`, `historical`, `obsolete`, `rejected`, `retired`, `superseded`, `superceded`, `withdrawn` |
 
-In front matter only an ASCII colon ends a key, as YAML has it: `狀態：已接受`
-there is a line left unread, where a heading or a label takes either colon.
-
-The table is where many teams put a document's fields, `| 狀態 | 已接受 |` or
-`| Status | Accepted |`:
+The table is where many teams put a document's fields, `| Status | Accepted |`:
 
 - It is read where a `## Status` section is, after one: a document with both is
   read from the section, and front matter still wins over either.
@@ -275,26 +246,23 @@ code. *"We resolved to keep the queue"* does not close anything.
 | Disposition | Checkboxes | Markers | `state=` |
 | --- | --- | --- | --- |
 | `unresolved` | `[ ]` `[?]` `[!]` `[*]` | `unresolved`, `still open`, `open question`, `tbd`, `undecided`, `reopened` | `open`, `unresolved`, `todo` |
-| `narrowed` | `[~]` `[/]` | `partially resolved`, `partially answered`, `partially done`, `partly resolved`, `narrowed`, `narrowed to`, `scoped down`, `reduced scope`, `reduced to`, `partial`, `in progress`, `in_progress`, `remaining`, `split`, `部分解決`, `部分解决` | `narrowed`, `partial` |
-| `delegated` | | `delegated`, `delegated to`, `moved to`, `tracked in`, `tracked by`, `handed off`, `handed off to`, `handed to`, `deferred to`, `follow up in`, `follow-up in`, `followup in`, `continued in`, `owned by`, `已移交` | `delegated` |
-| `satisfied` | `[x]` `[X]` `[+]` | `resolved`, `answered`, `decided`, `settled`, `done`, `complete`, `completed`, `closed`, `fixed`, `shipped`, `addressed`, `implemented`, `solved`, `confirmed`, `已解決`, `已解决`, `已決定`, `已决定`, `已定案` | `satisfied`, `resolved`, `done`, `closed` |
-| `accepted-debt` | | `accepted debt`, `accepted as debt`, `accepted risk`, `known limitation`, `known issue`, `known gap`, `technical debt`, `tech debt`, `wontfix`, `won't fix`, `won’t fix`, `will not fix`, `by design`, `tolerated`, `living with it`, `技術債`, `技术债`, `已知限制` | `accepted-debt`, `debt`, `wontfix` |
+| `narrowed` | `[~]` `[/]` | `partially resolved`, `partially answered`, `partially done`, `partly resolved`, `narrowed`, `narrowed to`, `scoped down`, `reduced scope`, `reduced to`, `partial`, `in progress`, `in_progress`, `remaining`, `split` | `narrowed`, `partial` |
+| `delegated` | | `delegated`, `delegated to`, `moved to`, `tracked in`, `tracked by`, `handed off`, `handed off to`, `handed to`, `deferred to`, `follow up in`, `follow-up in`, `followup in`, `continued in`, `owned by` | `delegated` |
+| `satisfied` | `[x]` `[X]` `[+]` | `resolved`, `answered`, `decided`, `settled`, `done`, `complete`, `completed`, `closed`, `fixed`, `shipped`, `addressed`, `implemented`, `solved`, `confirmed` | `satisfied`, `resolved`, `done`, `closed` |
+| `accepted-debt` | | `accepted debt`, `accepted as debt`, `accepted risk`, `known limitation`, `known issue`, `known gap`, `technical debt`, `tech debt`, `wontfix`, `won't fix`, `won’t fix`, `will not fix`, `by design`, `tolerated`, `living with it` | `accepted-debt`, `debt`, `wontfix` |
 | `rejected` | `[-]` | `rejected`, `declined`, `dropped`, `not doing`, `will not do`, `abandoned`, `cancelled`, `canceled`, `withdrawn` | `rejected`, `declined` |
 | `obviated` | | `no longer applicable`, `no longer relevant`, `no longer needed`, `overtaken by events`, `premise invalid`, `obviated`, `obsolete`, `not applicable`, `moot`, `void`, `n/a`, `obe` | `obviated`, `moot` |
 
 Where a marker counts, and how it may be written:
 
 - A marker counts where a statement starts: at the start of the item or of a
-  line, after the end of a sentence - a Chinese one, `。`, `？`, `！` or `；`,
-  with a space after it or none - or after `(` or `[`.
+  line, after the end of a sentence, or after `(` or `[`.
 - Punctuated means followed by `:`, `：`, `-`, `–`, `—` or `.`, so `Done.`
   closes an item; emphasised means the emphasis closes on the marker, so
   `**Closed beta**` does not.
 - A marker of more than one word may be spaced, hyphenated or joined by an
   underscore, whichever the table has: `**Tech-debt:**` and `TECH_DEBT:` are
   `tech debt`. An apostrophe may be straight or curly.
-- A Chinese marker is the English one it translates, and has no case to shout
-  in: `已決定：` and `**已決定**` close an item, and `我們已決定採用` does not.
 
 </details>
 
@@ -309,8 +277,7 @@ heading of its level. Every other bullet is the document's own prose.
 `Follow Ups`, `Follow-Ups`, `Followups`, `Follow Up`, `Follow-Up`,
 `Unresolved`, `Outstanding`, `Outstanding Questions`, `Tasks`, `Task List`,
 `Work Items`, `Remaining Work`, `Decisions Needed`, `Blockers`, `Parking Lot`,
-`Future Work`, `Deferred`, `待決事項`, `待决事项`, `未決問題`, `未决问题`,
-`待辦事項`, `待办事项`, `後續工作`, `后续工作`.
+`Future Work`, `Deferred`.
 
 ### References, resolved forgivingly and validated strictly
 
@@ -473,6 +440,9 @@ A phrase governs a reference when it stands no more than 40 characters before
 it, in the same statement: a sentence, a paragraph, a list item or a table cell.
 
 - A negation between the two - `owned by nobody` - cancels it.
+- A sentence written in Chinese ends at `。`, `？`, `！` or `；`, with a space
+  after it or none, so `Deferred to later。另見 ADR-0002` hands nothing to
+  ADR-0002. A stop only ends a statement sooner: it reads less, never more.
 - Prose reads both directions too: `supersedes` and `superseded by`, `amends`
   and `amended by`, `blocked by` and `blocks` or `blocking`, `depends on` and
   `depended on by` - the second of each pair points back at the document that
@@ -482,30 +452,12 @@ it, in the same statement: a sentence, a paragraph, a list item or a table cell.
   phrase: `[ADR-0002](0002.md) requires a migration` says nothing about this
   document.
 
-In Chinese a phrase before the reference hands the work on, as `deferred to`
-does. **Chinese hand-off phrases:** `延後至`, `延后至`, `延至`, `移交至`,
-`移交給`, `移交给`, `留待`, `交由`, `併入`, `并入`.
-
-- Chinese puts no space between words, so one counts wherever it stands,
-  `此問題延後至ADR-0002`, except directly after a negation - `不`, `未`, `非`,
-  `沒`, `没`, `無`, `无`, `勿`, `尚未` or `不再` - so `未移交給 ADR-0002` hands
-  nothing on.
-- An English phrase counts beside Chinese as well, `此問題deferred to ADR-0002`:
-  a Han character is not part of an English word.
-- A statement also ends at `。`, `？`, `！` and `；`, with a space after it or
-  none, so `上次延後至別處。另見 ADR-0002` hands nothing to ADR-0002.
-- A phrase written around the reference, `由 ADR-0002 決定` or
-  `在 ADR-0002 中追蹤`, is not read, and neither are `根據`, `依據` and `基於`:
-  Chinese uses them for any citation, and an `assumes` read from one would make
-  a stale premise of it.
-
 A link under a heading that files it as bookkeeping is `relates-to` unless a
 phrase beside it says more. **Bookkeeping headings:** `See also`, `References`,
 `Reference`, `Related`, `Related work`, `Related decisions`,
 `Related documents`, `Links`, `Further reading`, `Prior art`, `History`,
 `Changelog`, `Change log`, `Revision history`, `Bibliography`, `Sources`,
-`Appendix`, `More information`, `Resources`, `Index`, `參考資料`, `参考资料`,
-`相關文件`, `相关文件`, `延伸閱讀`, `延伸阅读`, `附錄`, `附录`, `修訂紀錄`, `修订记录`.
+`Appendix`, `More information`, `Resources`, `Index`.
 
 Two properties do the work:
 
@@ -531,8 +483,8 @@ decisions. **A specification is a region of a file, not a file**, so both work:
 Shard by tenant id.
 ```
 
-Each section with an identifier *and* a status - a `**Status:**` line,
-`**狀態：**` in Chinese, or a `### Status` section under its heading - becomes a
+Each section with an identifier *and* a status - a `**Status:**` line or a
+`### Status` section under its heading - becomes a
 specification in its own right, with its own lifecycle, its own obligations and
 its own relations — resolvable from anywhere in the corpus as `ADR-0007`,
 whether it lives in a register or in its own file. Moving it out later breaks
@@ -1325,9 +1277,9 @@ tools share, whose code is copied into `src/vendor/` and checked by hash rather
 than installed. So the whole package is auditable in an afternoon — and nothing
 in the pipeline can take longer than its input.
 
-**Verified, not just covered.** 1,996 tests; 99.4% statement and 99.8% line
+**Verified, not just covered.** 1,880 tests; 99.4% statement and 99.8% line
 coverage. Coverage says a line ran, so the suite is also held to a mutation
-score - 96.34% over 8,575 mutants, measured by CI's full sweep, and a build
+score - 96.32% over 8,393 mutants, measured by CI's full sweep, and a build
 fails under 93 - because a vocabulary entry or a boundary
 condition can be weakened by an ordinary-looking refactor without a single test
 going red. [ADR-0007](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0007-mutation-testing.md) is straight about what

package/dist/extract.d.ts

@@ -128,19 +128,6 @@ export declare function foldRelationKey(key: string): string;
  * be shadowed, which is {@link UNINHERITED}.
  */
 export declare function inheritableFrontMatter(entries: readonly YamlEntry[]): Readonly<Record<string, string | readonly string[]>>;
-/**
- * Phrases that give a link its meaning, longest-matching-nearest wins.
- *
- * Only phrases that genuinely commit the citing document are here. Vague ones
- * ("see", "covered by") stay out: a `references` edge is harmless, whereas a
- * wrongly inferred `assumes` edge produces a confident stale-premise finding
- * about a document that never depended on anything.
- */
-declare const VERB_RULES: readonly {
-    kind: EdgeKind;
-    inverted: boolean;
-    phrases: readonly string[];
-}[];
 /** Headings under which a link is bookkeeping rather than a commitment. */
 declare const WEAK_SECTIONS: ReadonlySet<string>;
 /** Headings whose bullets are obligations even without a checkbox. */
@@ -183,4 +170,4 @@ export interface Classification {
  */
 export declare function classifyReference(text: string, start: number, end: number, section: readonly string[]): Classification;
 /** Exposed for tests and for callers that classify their own sections. */
-export { OBLIGATION_SECTIONS, sectionPathAt, VERB_RULES, WEAK_SECTIONS };
+export { OBLIGATION_SECTIONS, sectionPathAt, WEAK_SECTIONS };

package/dist/extract.js

@@ -16,7 +16,7 @@
  */
 import { attr, attrList, bindItemDirectives, parseDirectives } from './directives.js';
 import { identify, isDocumentTarget, isExternal, looksLikePath, normaliseRef, parsePrefixedRef, withinOneEdit, ID_KEYS, } from './identity.js';
-import { isStatusHeading, negatedAt, phaseFromPath, phaseOf, STATUS_KEYS, supersessionTargetsIn, } from './lifecycle.js';
+import { isStatusHeading, phaseFromPath, phaseOf, STATUS_KEYS, supersessionTargetsIn } from './lifecycle.js';
 import { anchorsOf, isMarkdownLine, isOnlyComment, referenceLinks, scanMarkdown, slugify, } from './markdown.js';
 import { findSpecificationRegions, isRegisterTable, opensHeading, regionAt, } from './sections.js';
 import { resolveItemState } from './state.js';
@@ -253,22 +253,6 @@ const VERB_RULES = [
             'to be resolved in',
             'to be handled in',
             'to be answered in',
-            // Chinese, Traditional and Simplified, each standing before the
-            // reference as its English counterpart does: deferred to, handed to,
-            // left to. `併入`, merged into, hands a question on whole; read as
-            // `rolled into`, a supersession, a constraint merged into another
-            // decision's design would retire the document that states it. Nothing
-            // that wraps the reference, `由 X 決定`: a phrase here only precedes one.
-            '延後至',
-            '延后至',
-            '延至',
-            '移交至',
-            '移交給',
-            '移交给',
-            '留待',
-            '交由',
-            '併入',
-            '并入',
         ],
     },
     {
@@ -354,22 +338,12 @@ const VERB_WINDOW = 40;
  * Neither the sort nor the escaping decides anything today, and no test can
  * pin them: no phrase in the table is another one followed by more words, and
  * none holds a character a pattern would read. Both are for the next phrase.
- *
- * An English phrase stands between word boundaries, and a Han character is
- * not part of an English word: `此問題deferred to ADR-0002` holds the whole
- * phrase, which the boundary read as a letter used to refuse. A Chinese phrase
- * has no boundary at all, since Chinese puts no space between words.
  */
 const VERB_LOOKUP = new Map(VERB_RULES.flatMap((rule) => rule.phrases.map((phrase) => [phrase, { kind: rule.kind, inverted: rule.inverted }])));
-const HAN = /\p{Script=Han}/u;
-/** A letter or digit an English phrase may not touch: any but a Han character. */
-const WORD_CHARACTER = String.raw `(?!\p{Script=Han})[\p{L}\p{N}]`;
-const alternation = (phrases) => [...phrases]
+const VERB_PATTERN = new RegExp(`(?<![\\p{L}\\p{N}])(?:${[...VERB_LOOKUP.keys()]
     .sort((a, b) => b.length - a.length)
     .map((phrase) => phrase.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
-    .join('|');
-const VERB_PATTERN = new RegExp(`(?<!${WORD_CHARACTER})(?:${alternation([...VERB_LOOKUP.keys()].filter((phrase) => !HAN.test(phrase)))})(?!${WORD_CHARACTER})` +
-    `|(?:${alternation([...VERB_LOOKUP.keys()].filter((phrase) => HAN.test(phrase)))})`, 'gu');
+    .join('|')})(?![\\p{L}\\p{N}])`, 'gu');
 /** Headings under which a link is bookkeeping rather than a commitment. */
 const WEAK_SECTIONS = new Set([
     'see also',
@@ -392,16 +366,6 @@ const WEAK_SECTIONS = new Set([
     'more information',
     'resources',
     'index',
-    '參考資料',
-    '参考资料',
-    '相關文件',
-    '相关文件',
-    '延伸閱讀',
-    '延伸阅读',
-    '附錄',
-    '附录',
-    '修訂紀錄',
-    '修订记录',
 ]);
 /** Headings whose bullets are obligations even without a checkbox. */
 const OBLIGATION_SECTIONS = new Set([
@@ -435,14 +399,6 @@ const OBLIGATION_SECTIONS = new Set([
     'parking lot',
     'future work',
     'deferred',
-    '待決事項',
-    '待决事项',
-    '未決問題',
-    '未决问题',
-    '待辦事項',
-    '待办事项',
-    '後續工作',
-    '后续工作',
 ]);
 /**
  * Prefixes that look like specification identifiers but never are.
@@ -840,11 +796,11 @@ function readStatus(scanned, byKey, nodeDirective, index, file, regions) {
     return { raw: null, at: null, phase: 'unknown' };
 }
 /** The left cells that make a two-column table's row the document's status. */
-const STATUS_TABLE_KEYS = new Set(['status', 'state', '狀態', '状态']);
+const STATUS_TABLE_KEYS = new Set(['status', 'state']);
 /**
  * The status a key-value table at the top of a document gives:
- * `| 狀態 | 已接受 |`, or `| Status | Accepted |`, as the right cell of the first
- * row whose left cell is a status key, the header row included.
+ * `| Status | Accepted |`, as the right cell of the first row whose left cell
+ * is a status key, the header row included.
  *
  * Read only where a document describes itself. A table under a heading below
  * the title is a legend or a register, and one with more than two columns is
@@ -1265,9 +1221,6 @@ export function classifyReference(text, start, end, section) {
         // negation in there reverses the claim the phrase would otherwise make.
         if (NEGATION.test(before.slice(end)))
             continue;
-        // Chinese negates the phrase itself, directly before it: `未移交給`.
-        if (negatedAt(before, m.index))
-            continue;
         // Always found: the pattern was compiled from this table's own keys, and a
         // lower-cased search matches them only as written. The check is for types.
         const rule = VERB_LOOKUP.get(phrase);
@@ -1309,9 +1262,11 @@ export function classifyReference(text, start, end, section) {
  * following row's link into an `assumes` edge, and so turned every archived
  * document it listed into a stale premise.
  *
- * A Chinese sentence ends at `。？！；`, with a space after it or none, since
- * Chinese writes none. Without it `上次延後至別處。另見 ADR-0002` handed the
- * question to ADR-0002 from the sentence before.
+ * A sentence written in Chinese ends at `。？！；`, with a space after it or
+ * none, since Chinese writes none. A stop only ends a statement sooner, so it
+ * reads fewer relations and never more: without it,
+ * `Deferred to later。另見 ADR-0002` handed the question to ADR-0002 from the
+ * sentence before.
  */
 const STATEMENT_BREAK = /[.?!;]\s|[。？！；]|\n\s*\n|\n\s*[-*+>#]|\|/g;
 /**
@@ -1335,7 +1290,8 @@ function sentenceBefore(text, start) {
         .replace(/\s+/g, ' ');
 }
 /**
- * The statement after a reference, to the first stop, Chinese ones included.
+ * The statement after a reference, to the first stop, the stops of a sentence
+ * written in Chinese included.
  *
  * Only its start is read. A line break matters as a stop, since the trim
  * below would otherwise bring the next line's phrase to the start. A Chinese
@@ -1452,5 +1408,5 @@ function renderLink(link) {
     }
 }
 /** Exposed for tests and for callers that classify their own sections. */
-export { OBLIGATION_SECTIONS, sectionPathAt, VERB_RULES, WEAK_SECTIONS };
+export { OBLIGATION_SECTIONS, sectionPathAt, WEAK_SECTIONS };
 //# sourceMappingURL=extract.js.map