Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions .github/workflows/validate.yml
Original file line number Diff line number Diff line change
Expand Up @@ -21,3 +21,7 @@ jobs:

- name: Run test suite
run: python3 -m unittest discover -s tests -v

- name: Internal register gate (bilingual)
working-directory: scripts
run: python3 test_internal_register_scan.py
15 changes: 10 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -95,8 +95,12 @@ bằng chứng, `TERM` thuật ngữ, `STANCE` lập trường khoa học, `LOGI

Quyết định `pass` yêu cầu mọi chiều đạt ít nhất 4/5 và không có lỗi chặn. Điểm
trung bình cao không bù được lỗi đảo nghĩa, mất phủ định, nâng tương quan thành
nhân quả, sai số liệu, hỏng trích dẫn, đổi phạm vi hoặc bịa bằng chứng. Hai
quyết định còn lại là `revise` và `human_review`. Thang điểm và điều kiện chặn:
nhân quả, sai số liệu, hỏng trích dẫn, đổi phạm vi, bịa bằng chứng, hay văn
phong nội bộ/tự thuật. Văn phong đó bị cấm ở cả tiếng Việt và tiếng Anh: câu nói
về bản thảo, dự án, log kiểm tra, đường dẫn máy, placeholder hoặc cuộc hội thoại
soạn thảo không được xuất hiện trong văn bản công bố. Cơ chế kiểm định:
[`references/internal-register-gate.md`](references/internal-register-gate.md).
Hai quyết định còn lại là `revise` và `human_review`. Thang điểm và điều kiện chặn:
[`references/quality-rubric.md`](references/quality-rubric.md).

## Kiến trúc kho mã
Expand All @@ -105,10 +109,10 @@ quyết định còn lại là `revise` và `human_review`. Thang điểm và đ
academic-prose/
├── SKILL.md # Hợp đồng và bộ định tuyến chính
├── agents/openai.yaml # Bộ điều hợp giao diện tùy chọn
├── references/ # 15 tài liệu chuẩn ngôn ngữ, quy trình và phân loại lỗi
├── references/ # Tài liệu chuẩn ngôn ngữ, quy trình, thuật ngữ và phân loại lỗi
├── schemas/ # Lược đồ JSON cho hiện vật trung gian
├── evals/ # Tình huống tổng hợp cho viết, dịch, humanize và usage
├── scripts/ # Trình kiểm định và hai trình mô phỏng
├── scripts/ # Validator, scanner register nội bộ và mô phỏng
└── tests/ # Kiểm thử kho mã và lược đồ
```

Expand All @@ -117,11 +121,12 @@ academic-prose/
```bash
python3 scripts/validate_skill.py # cổng kiểm định đầy đủ
python3 -m unittest discover -s tests -v # kiểm thử kho mã
python3 scripts/test_internal_register_scan.py # cổng văn phong nội bộ, song ngữ
python3 scripts/run_usage_simulations.py # riêng mô phỏng usage
python3 scripts/run_capability_examples.py # riêng ví dụ năng lực
```

Trình kiểm định gọi lại cả hai trình mô phỏng, nên một ví dụ hỏng sẽ làm cổng đỏ.
Trình kiểm định gọi lại cả hai trình mô phỏng và bộ test scanner register nội bộ, nên một ví dụ hỏng hoặc một lớp tiếng Anh/tiếng Việt bị sót sẽ làm cổng đỏ.
Mỗi phép kiểm tra được đột biến có chủ đích để chứng minh nó biết thất bại; một
phép kiểm tra không bao giờ đỏ thì không phải là bằng chứng.

Expand Down
298 changes: 290 additions & 8 deletions SKILL.md

Large diffs are not rendered by default.

6 changes: 6 additions & 0 deletions references/academic-english-standard.md
Original file line number Diff line number Diff line change
Expand Up @@ -101,4 +101,10 @@ The upstream watched-word lists are English and apply directly. Three additions

## Cross-Language Symmetry

Vietnamese institutional, legal, administrative, and academic-title terms are
system-specific and rarely have an exact English equivalent. Preserve instrument
numbering, and gloss the institutional difference rather than substituting a
near-equivalent; see the reverse-direction section of
[Terminology localization policy](terminology-localization.md).

When a document exists in both languages, keep one glossary with paired renderings, one claim ledger, and one stance calibration. A hedge present in one language must be present in the other. A claim that is `needs_source` in Vietnamese is `needs_source` in English. Divergence between versions is a `CONS` failure, not a stylistic choice.
6 changes: 6 additions & 0 deletions references/academic-vietnamese-standard.md
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,12 @@ that store those values are normally unnecessary.

## Protected Elements

Whether a required foreign term is translated, kept, or glossed is decided by
[Terminology localization policy](terminology-localization.md), recorded once per
concept in the glossary, and enforced across the document. The abstraction rule
above removes implementation tokens with no publication-facing function; it does not
license translating a name that carries the identity of an external object.

When a protected element is substantively required, copy formulas, symbols,
values, units, citations, DOI, URLs, code, dataset names, model names, quoted
text, and structured placeholders exactly unless the task explicitly changes
Expand Down
6 changes: 3 additions & 3 deletions references/ai-pattern-vietnamese.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,8 +18,8 @@ Vietnamese equivalent of §1 and §4. These are the strongest single-word signal
**Repair.** Replace the evaluation with the measurement, or delete it.

- Before: `Phương pháp đề xuất mang tính đột phá và cho kết quả vượt trội đáng kể so với các phương pháp hiện có.`
- After: `Phương pháp đề xuất đạt F1 0,847, cao hơn 2,3 điểm so với baseline BiLSTM-CRF.`
- When no number exists: `Phương pháp đề xuất cho kết quả cao hơn baseline BiLSTM-CRF.` and mark the magnitude `needs_source`.
- After: `Phương pháp đề xuất đạt F1 0,847, cao hơn 2,3 điểm so với mô hình cơ sở BiLSTM-CRF.`
- When no number exists: `Phương pháp đề xuất cho kết quả cao hơn mô hình cơ sở BiLSTM-CRF.` and mark the magnitude `needs_source`.

`đáng kể` deserves separate attention. In statistics it renders *significant* and is licensed only when a test supports it. Used as a vague intensifier it is padding; used for an unsupported statistical claim it is a stance upgrade. Distinguish `khác biệt có ý nghĩa thống kê (p < 0,05)` from `cải thiện đáng kể`.

Expand Down Expand Up @@ -85,7 +85,7 @@ Also watch: `sự` and `việc` stacked across a clause (`việc thực hiện s
Vietnamese equivalent of §11, and a genuine hazard because Vietnamese offers a Sino-Vietnamese and a native word for most concepts. A model alternates them to avoid repetition; a reader infers two constructs.

- Before: `Mô hình học sâu đạt độ chính xác cao. Mạng nơ-ron sâu này cho kết quả tốt. Kiến trúc đề xuất vượt các baseline.`
- After: `Mô hình học sâu đề xuất đạt độ chính xác 94%, cao hơn cả ba baseline.`
- After: `Mô hình học sâu đề xuất đạt độ chính xác 94%, cao hơn cả ba mô hình cơ sở.`

Repetition of a locked term is correct. Never introduce a synonym to satisfy a repetition rule; that is `terminology_drift`, a major failure.

Expand Down
76 changes: 76 additions & 0 deletions references/artifact-register-to-scientific-register.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,76 @@
# From Project Artifacts to Scientific Register

Measured case: a Vietnamese dataset/benchmark paper (HOEIT-LegalQA → HUJOS-TT) drafted from a
working repository. Every number was correct and every citation resolved; the user still
rejected a whole section with: *"toàn nội dung kiểu này sao lại đưa vào em? bản thảo chủ yếu
trình bày mình đã làm gì thôi chứ? Còn hạn chế và hướng tương lai thì phải về mặt khoa học."*

The draft had inherited the register of its sources — `quality_gates.json`, an audit summary,
two empty annotator CSVs, a claim ledger. Those answer *what state is the project in*. A paper
answers *what is now known, and under what conditions*.

## The eight sites found in one sweep

Not one section. A register leak shows up wherever the draft touched an artifact:

| # | Section | Artifact-register text | Scientific-register replacement |
| --- | --- | --- | --- |
| 1 | Limitations | "Hai tệp annotator có 240 dòng nhưng các cột đánh giá đều trống" | labels have no human reference annotation, so reliability is unquantified and generator error cannot be separated from source-context error |
| 2 | Limitations | "nhãn lĩnh vực hiện là giá trị placeholder giống nhau cho toàn bộ 14.210 bản ghi" | the dataset is not stratified by domain, so per-domain performance cannot be analysed — a material gap in a domain where difficulty varies sharply |
| 3 | Limitations | "các điểm tự động đạt mức tối đa trong một số báo cáo" | the automatic scorer saturates near the ceiling and loses discriminative power, so it functions as a coarse error filter only |
| 4 | Limitations | "Audit trước đó cho thấy 84 ảnh và 78 ứng viên bảng chỉ là kho ứng viên, chưa có tài sản nào được người xác nhận" | the multimodal subset holds 29 items after adjudication, too few for a statistically meaningful visual evaluation; the paper therefore makes no multimodal-benchmark claim |
| 5 | Methods (context stage) | four per-bucket candidate tallies (1.528 / 469 / 891 / 263) plus "75 chuyển duyệt thủ công và 165 bị loại trong báo cáo đủ điều kiện" | the OCR-noise rate (31,15%) and the three anchor-precision levels of the recovery mechanism, plus the constraint that recovered context is content-equivalent, not verbatim |
| 6 | Methods (release stage) | "Mẫu số này thuộc tệp dữ liệu xử lý 16.158 bản ghi, không phải toàn bộ 14.210" and a 155/154-record reconciliation note | one sentence on the mechanism: both branches derive from the same filtered pool but place the language filter at different points, so the evaluation set is not a subset of the release and the two totals share no denominator |
| 7 | Results ("Kiểm tra tính toàn vẹn") | a QA checklist — 48 Markdown files match 48 PDFs, zero `qa_id` collisions | opens by stating *why* traceability and non-duplication are preconditions for measuring model performance, reports the checks as premises, then states explicitly what they do **not** establish (legal correctness) |
| 8 | Conclusion | "Các bước tiếp theo cần ưu tiên là …" (a task list) | a `Hướng nghiên cứu` section: four open problems, each with the question, why current evidence cannot settle it, and a feasible design |

## The test that catches all eight

> If the team did more work next week and this sentence changed, but the scientific finding did
> not, the sentence is bookkeeping.

Rows 1–4 all fail it: fill the columns, add the tags, calibrate the scorer, qualify the assets
— every sentence evaporates while the paper's contribution is untouched. Rows 5–7 fail a
variant: the numbers are stable but their *unit of analysis* is the team's spreadsheet
(candidates, files, rows) rather than the phenomenon.

## What NOT to do with the leak

**Do not delete the numbers.** The target is a change of register, not a loss of
verifiability. Rows 5 and 6 keep their load-bearing quantities (31,15% noise rate; the fact
that two totals have different denominators) and drop only the reconstruction of the audit
trail. A reviewer must still be able to audit the work.

**Do not let a limitation stand without its consequence.** Each rewritten limitation names the
inference it weakens: which claim is unavailable, over what scope. A limitation with no
consequence is `ceremonial_limitation`, a different failure with the same smell.

**Separate ethics from limitations.** The original section was titled `Hạn chế và vấn đề đạo
đức` and mixed distribution rights into a list of measurement limits. Rights and intended-use
scope are a normative statement, not a validity bound; they earned their own section.

**Reorder the tail.** Correct order after the sweep: Hạn chế → Đạo đức và phạm vi sử dụng →
Hướng nghiên cứu → Kết luận. The conclusion closes the paper; it cannot sit before the open
problems it does not resolve.

## A side effect worth expecting

Rewriting the Methods paragraph (row 5) forced a read of the actual pipeline code, which
revealed that a VLM stage present in the implementation and in Figure 1 was **missing from the
prose entirely** — the earlier draft had "resolved" the figure/text mismatch by planning to
edit the figure. Register cleanup and evidence verification are the same pass: an artifact-
register sentence is usually a sentence nobody traced back to the system.

## Future-work rewrite pattern

Each item needs three parts, in this order:

1. the open question, phrased as a question about the world rather than about the project;
2. why the present evidence cannot settle it;
3. a design that could, concrete enough to argue with.

Worked example from the same paper: *"Obtain expert review"* (task) →
*"Establish a human reference set annotated by legal and educational-measurement experts,
measure inter-rater reliability, and estimate convergence between automatic and expert
cognitive labels; this is a precondition before any claim about the dataset's cognitive
stratification counts as verified."*
4 changes: 4 additions & 0 deletions references/capability-matrix.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,10 @@ primary capability.
Declare the target language; it selects the target-language standard and the
`LANG` scoring reference. Pair translation with a PDF tool only when
extraction or reconstruction is also required.
- Terminology localization is not confined to `translate`. Authored text carries
source-language terms for the same reason translated text does, so `draft`,
`develop`, `revise`, and `audit` all run the localization decision and gate;
see [Terminology localization policy](terminology-localization.md).
- The translation adapter explicitly covers both English-to-Vietnamese and
Vietnamese-to-English academic transfer. Keep one claim ledger and glossary
across the pair; direction changes the target-language realization, not the
Expand Down
12 changes: 10 additions & 2 deletions references/composition-workflow.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ Writing is not sentence expansion. It is the controlled conversion of a research

## 1. Rhetorical brief

Record: discipline and subfield; genre; section; readers; communicative purpose; research question; central claim; supplied evidence; required length; terminology policy; citation convention; and unresolved inputs. If the requested text depends on missing evidence, mark the gap instead of filling it plausibly.
Record: discipline and subfield; genre; section; readers; communicative purpose; research question; central claim; supplied evidence; required length; terminology policy; citation convention; and unresolved inputs. The terminology policy includes the localization stance — which source-language terms are kept, translated, or glossed — decided per concept rather than per sentence; see [Terminology localization policy](terminology-localization.md). If the requested text depends on missing evidence, mark the gap instead of filling it plausibly.

## 2. Claim-evidence ledger

Expand All @@ -27,7 +27,14 @@ Reject an outline if sections merely name subjects, evidence has no claim, or a

## 4. Paragraph design

Assign one dominant function to each paragraph. Select only moves needed for that function:
Assign one dominant function to each paragraph, plus an **admissible subject**:
the object of study, the data, the method, a result, a cited work's claim, or an
inference available to the reader. A paragraph whose planned subject is the
manuscript, its sections, the project, a file, or the drafting conversation is
rejected here rather than repaired later; see
[Internal register gate](internal-register-gate.md).

Select only moves needed for that function:

- establish context or a precise problem;
- state a claim;
Expand All @@ -53,6 +60,7 @@ Review the draft independently:
3. Does every paragraph perform its assigned role and advance the section purpose?
4. Are causal, contrastive, and consequential connectives warranted?
5. Could a reader identify the central claim and its limits without reconstructing the author's intention?
6. Does every source-language term in the prose have a recorded reason to be there, and does every rendering hold one concept throughout?

## 7. Revision order

Expand Down
9 changes: 9 additions & 0 deletions references/cross-language-transfer-taxonomy.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,15 @@ even in a text written by a human translator; a ceremonial adjective is an
AI tell even in a text that was never translated. When both apply to the same
span, repair the transfer error first, because it changes meaning.

They are also distinct from a terminology decision. Whether a term should be
translated at all, kept as a designator, or glossed is not an error in transfer;
it is a policy fixed once per concept in the glossary. `terminology_error` and
`terminology_drift` below presuppose that decision has been made. When a source
term appears untranslated in target-language prose, or a designator appears
translated, classify it under
[Terminology localization policy](terminology-localization.md) rather than as a
calque.

## Direction-neutral errors

These occur in both directions.
Expand Down
8 changes: 8 additions & 0 deletions references/domain-profiles.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,14 @@ Profiles tune terminology and discourse; they never override the fidelity contra

Record discipline, subfield, genre, section, intended readers, locale/institutional convention, and whether English terms should appear at first mention.

The profile selects the terminology rendering, not only the register. The same
source word takes different Vietnamese renderings across the profiles below —
`baseline` is `mốc cơ sở` in an evaluation, `kỳ gốc` in econometrics, and `giá trị
ban đầu` in a clinical trial — so a rendering copied from a neighbouring discipline
is a terminology error even when the Vietnamese is idiomatic. Each glossary entry
carries its domain; see
[Terminology localization policy](terminology-localization.md).

## Natural Sciences and Engineering

- Prefer operational verbs and explicit variables, conditions, mechanisms, and uncertainty.
Expand Down
Loading
Loading