Maintenance log

What changed

Tax content goes stale silently. This page is the antidote: every substantive edit and every correction is recorded here, including the ones that make the site look like it got something wrong — because it did.

2026-11 — Initial publication

  • Five-gate model published, with the identity matrix as the reference page.
  • Nine modules written: M0 through M8.
  • Three tools released: identity comparison, day counter with the six-year lookback, income type comparison.
  • Glossary of sixteen terms, each with the specific way it is misread.
Known limitations at launch
  • All numeric parameters are stated as structure rather than as current values where they are subject to change. Rate tables in the tools reflect the statutory scales as understood when this was written — they have not been re-checked against current official guidance since.
  • The day counter assigns a whole absence to a single calendar year, so an absence spanning 31 December is split across two years rather than measured as one absence. It also cannot detect domicile as a separate route into residency.
  • No city-level variation is modelled — social insurance bases, housing fund contributions and some deductions differ by locality.
  • Foreign tax credit mechanics are described, not computed. No tool models the cap.

2026-11 — Substantive corrections, after checking against the source documents

The first round of this content was written from the structure of the rules without going back to the announcements. Checking them turned up two things that were wrong, and one that was badly framed.

  • Day counting was wrong. The site said entry and exit days count, and that a Friday-to-Sunday trip is three days. The rule is that a day counts only if you were in China for 24 hours of it, so arrival and departure days usually do not count — that trip is one day, and a Monday-to-Friday trip is three. This changed the day counter's arithmetic, not just its wording.
  • The six-year rule was framed as a countdown. It is a lookback: you lose the offshore exemption only if all six previous years had 183+ days and none contained a single absence longer than 30 days. One failing year preserves the exemption. The tool now tests each prior year separately, and the window starts in 2019 — so the earliest anyone can lose it is 2025.
  • The allowance exemption was missing its precondition. It is available to foreign nationals who qualify as resident individuals, it is mutually exclusive with the special deductions, the election is locked for the tax year, and the current policy runs to 31 December 2027.
  • Concrete figures added where they were previously described only as structure: the seven deduction standards, the ¥60,000 basic deduction, and the two reliefs that excuse a resident from filing a reconciliation (income of ¥120,000 or less, or a top-up of ¥400 or less).

2026-11 — Corrections after launch

  • The privacy page was wrong. It claimed there were no third-party analytics scripts. Cloudflare injects a cookieless visitor counter into every page served through it, so the claim was false. The page now names that counter, states what it does and does not do, and explains how to block it.
  • The date label overclaimed. Pages said “last verified”, but the content was assembled from research without live re-checking of each parameter. The label is now “Written”, and the date is the accurate month of writing.
  • The same overclaim was removed from the footer, the home page and the About page, which previously implied no measurement took place at all.

2026-11 — Worked scenarios added

The modules explain the gates; they do not show what it looks like to stand at one. Six scenario pages now do that, each with a fixed set of invented facts, a gate-by-gate walk, and the worked numbers rather than the conclusion alone.

  • Added six scenarios: a seconded manager, a locally-hired teacher, a freelancer, someone leaving in June, a property seller, and a US citizen. Together they touch most of the twelve matrix cells.
  • Surfaced by writing them: the allowance-versus-deduction election is not self-evidently worth taking. On the seconded manager's figures the allowance route is ¥145,000 better, but the arithmetic reverses for a lower earner with high rent and no school fees — so the site now presents it as a calculation rather than a rule.
  • Surfaced by writing them: the relief that excuses a reconciliation when tax was over-withheld has a sharp edge. The teacher is not obliged to file, so not filing is not a failure to comply — it is a decision to forgo the refund by default.
  • Navigation changed to accommodate the new section: a Scenarios item in the header, a section on the home page, and cross-links from the model, the course index and the matrix.
  • Stated limitation: the figures in every scenario are rounded and invented for illustration. They are arithmetic on the published tables, not quotations from any real case, and the pages say so.

How to read the date on a page

Each page shows the month it was written. It is a statement about provenance, not a guarantee of currency: the structure and reasoning were assembled then, but rates, thresholds and time-limited policies may have moved since. An older date means the logic is probably still useful and the numbers should not be trusted — start from current official guidance for anything financial.

What gets logged

  • Corrections to a statement that was wrong.
  • Changes following a policy update — rate thresholds, time-limited regimes.
  • New modules, tools or matrix cells.
  • Removals, and why something was removed.

Typographical fixes are not logged.