doc: state the design philosophy and the doc-sync rule for contributors

[bitflicker64]

Purpose of the PR

Draft for discussion.

AGENTS.md describes the module layout, the build and the test profiles, but it says
nothing about how code is expected to be written in this repo. Without that, agents fall
back on generic best practice: they add an interface where the existing class would do,
widen a fix into a refactor, or explain a tricky case in a long block comment that then
drifts out of date.

The same gap exists on the documentation side, in a different form. The PR template already
has a Documentation Status section, so the intent is there, but the first option is:

- [ ] `Doc - TODO`  <!-- Your PR changes impact docs and you will update later -->

"You will update later" is a promise with nothing attached to it. No link, no issue, no
follow-up, so once the code PR merges the box is the only record that documentation was
owed, and it stops being visible to anyone. The result is documentation that describes an
older version of the code, which readers and search tools then pick up as current.
CONTRIBUTING.md does not mention documentation at all in the section on opening a PR,
which is the point where a contributor decides whether to write any.

Main Changes

AGENTS.md, kept short on purpose so the file stays usable as a prompt:

• new Design philosophy section: extend existing code before introducing a new
  abstraction, keep the change minimal, one concern per PR, link the issue when something
  needs real context instead of writing a long inline comment
• two entries under Cross-module notes, in the same "change X, also update Y" shape as
  the existing ones: the paired hugegraph-doc PR, and the README staying thin at 120
  columns

For contributors, who do not read AGENTS.md:

• .github/PULL_REQUEST_TEMPLATE.md: one visible field under the existing options,
  Related hugegraph-doc PR or issue:. The three options keep their current wording, so
  this block stays identical to the one in hugegraph-toolchain and hugegraph-computer and
  the change is purely additive. The field sits in the rendered body rather than in an
  HTML comment, which GitHub strips, and it applies to whichever option is ticked instead
  of repeating the prompt on each one. This follows the shape kubernetes uses for its
  documentation and release-note fields: visible heading, guidance in the comment, an
  obviously empty field below.
• docs/CONTRIBUTING.md: one paragraph in section 4, saying that a change to a feature, a
  configuration item or a Dockerfile opens the matching hugegraph-doc PR at the same
  time, and that the two merge together.

24 lines added, nothing removed or reworded.

Two open points for review:

1. Should Doc - TODO stay at all, or should the choice be Done or No Need? A field
   that asks for the link is the softer option and is what this PR does. Nothing yet
   checks that the field is filled in; a small workflow on the paths that touch features,
   configs and Dockerfiles could do that, if that is wanted.
2. .github/PULL_REQUEST_TEMPLATE.md is byte identical in hugegraph-toolchain and
   hugegraph-computer. If this lands, both want the same line.
3. CONTRIBUTING.md says the website copy at
   https://hugegraph.apache.org/docs/contribution-guidelines/ is authoritative. If this
   lands, the same paragraph needs a matching hugegraph-doc PR, which is the rule applying
   to itself.

Verifying these changes

• Trivial rework / code cleanup without any test coverage. (No Need)
• Already covered by existing tests, such as (please modify tests here).
• Need tests and can be verified as follows:
  • xxx

Does this PR potentially affect the following parts?

• Dependencies (add/update license info & regenerate_known_dependencies.sh)
• Modify configurations
• The public API
• Other affects (typed here)
  • Changes the PR template every contributor sees, and the contribution guide.
• Nope

Documentation Status

• Doc - TODO
• Doc - Done
• Doc - No Need

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 37.77%. Comparing base (e85b36a) to head (96a48ad).
⚠️ Report is 1 commits behind head on master.

Additional details and impacted files

@@             Coverage Diff              @@
##             master    #3197      +/-   ##
============================================
- Coverage     37.79%   37.77%   -0.02%     
+ Complexity     6563     6560       -3     
============================================
  Files           800      800              
  Lines         68960    68960              
  Branches       9166     9166              
============================================
- Hits          26061    26052       -9     
- Misses        39834    39841       +7     
- Partials       3065     3067       +2     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[bitflicker64]

Blocking: no. Summary: The design-philosophy section and the doc-sync paragraph are additive and read well, but the three edited files disagree about what the rule actually is, and the README guidance does not match the README it describes. Separately, open point 2 in the description says the PR template is byte identical in hugegraph-toolchain and hugegraph-computer; it is not (the Documentation Status block is identical, the rest of the file differs in several places), so that follow-up is a hand merge rather than a copy. Evidence: git show 96a48ad:.github/PULL_REQUEST_TEMPLATE.md, AGENTS.md, docs/CONTRIBUTING.md and README.md at head; awk 'length>120' README.md returns 47 lines, including prose; diff of .github/PULL_REQUEST_TEMPLATE.md fetched via gh api from apache/hugegraph, apache/hugegraph-toolchain and apache/hugegraph-computer default branches.

[bitflicker64]

⚠️ Two things work against this field being filled in.

1. Line 63, directly above, still says DO NOT REMOVE THIS SECTION. CHECK THE PROPER BOX ONLY. A contributor following that ticks a box and leaves this line empty.
2. Doc - Done is defined as "Related docs have been already added or updated", which also covers in-repo docs (README.md, module READMEs, docs/, AGENTS.md). This PR is itself an example. For those, a hugegraph-doc link does not exist, yet the hint marks it required.

The hint is also an HTML comment, so it disappears once the PR is rendered, and reviewers never see that the field was meant to be required.

Suggested change: reword line 63 to cover the field too, for example CHECK THE PROPER BOX AND FILL IN THE LINK BELOW, and scope the hint to required for Doc - TODO; for Doc - Done, when the docs live in hugegraph-doc.

[bitflicker64]

🧹 The rule here and the rule in docs/CONTRIBUTING.md are not the same as the one in the template. This line and the CONTRIBUTING paragraph both say the paired hugegraph-doc PR lands together with the code. .github/PULL_REQUEST_TEMPLATE.md then accepts hugegraph-doc PR or issue and keeps Doc - TODO ("you will update later"), so an issue link plus deferred docs passes the template. An agent reading this file will hold contributors to a stricter rule than the one they are shown.

Suggested change: choose one rule and write it the same way in all three files. Either allow a tracking issue here and in CONTRIBUTING, or drop or issue from the template field.

[bitflicker64]

🧹 wrap at 120 does not describe the current README.md. At this head, 47 of its 390 lines are longer than 120 columns. That count covers the badge rows, the module table (L114-116) and the ASCII architecture diagram, none of which can wrap, and also plain prose (L25-27, L34, L175, L204-208). Given as an agent instruction, this invites reflowing the whole README in unrelated PRs, which cuts against the Keep the change minimal rule added above. It is also a formatting rule rather than a cross-module dependency, so it fits Style & Pre-commit better than this list.

Suggested change: limit it to new or edited prose (wrap new prose at 120; tables, links and diagrams are exempt) and move it under Style & Pre-commit.