Documentation
Trace a public explanation to accepted contracts, gate evidence, commands, and tests. Correct stale status claims instead of adding marketing copy.
Contributor workflow
Change behavior with evidence
A Nexus contribution is complete when reviewers can identify the authority for the change, the invariant it preserves, the tests that exercise it, and the claims it does not make.
Start with the authority chain
- Approved specificationsNormative contracts under
specs/. - Accepted architecture decisionsDurable choices, conflicts, and non-goals under
docs/adr/. - Golden fixturesReproducible compatibility evidence under
fixtures/. - Pinned PHP behaviorObservable reference behavior, not framework structure or syntax.
- Current C# behaviorImplementation evidence, never a silent override of higher authority.
Conflict rule: if those sources disagree, record the conflict and stop the affected behavior. Do not select the convenient interpretation in code.
Choose one coherent behavior
Use the current protected-main status and feature sequence before opening a change. One task should implement, verify, and document one bounded behavior. New product dependencies, compatibility decisions, privacy boundaries, and scientific authority rules require written rationale or an ADR.
Focused tests
Exercise an accepted edge case, invalid-input path, immutable boundary, deterministic serializer, or architecture constraint.
New behavior
Define dependencies, authority, provenance, invalidation, fixtures, failure modes, and exit criteria before implementation.
Preserve the product laws
| Boundary | Contributor test |
|---|---|
| Suggestion is not a decision | Does a human-authorized mutation remain explicit, attributable, and reviewable? |
| Draft is not an approved protocol | Can draft content alter conduct before the accepted approval transition? |
| Current state is not history | Can a later correction or invalidation erase the record that preceded it? |
| Paths are not scientific identities | Is identity bound to stable identifiers and content digests instead of a machine-local location? |
| Plugins are not a security sandbox | Does an extension receive only explicit capabilities, staged output, and no database credentials? |
| AI output remains a proposal | Are provenance, schema validation, evidence references, and human action preserved? |
Repository boundaries
- Domain projects do not reference EF Core, ASP.NET Core, UI frameworks, provider SDKs, storage SDKs, or concrete model clients.
- Infrastructure and product surfaces depend inward; domain code never reaches outward to a host or adapter.
NexusScholar.UiContractsstays renderer-neutral, while desktop and sample renderers remain outside Core authority.- Plugin manifests declare capabilities; runtime hosts validate grants, stage output, and preserve the human acceptance boundary.
- PHP compatibility requires a generated fixture or focused comparator. Shared names or similar output are not enough.
Verify before review
dotnet build NexusScholar.Core.slnx -c Release
dotnet test NexusScholar.Core.slnx -c Release --no-build
dotnet format NexusScholar.Core.slnx --verify-no-changes --no-restoreAlso run the affected architecture, conformance, package-smoke, fixture, or gate-specific checks. CI must remain deterministic and must not call a live scholarly provider or live model.
Write the completion report
Tell reviewers the behavior implemented, files changed, invariants enforced, tests added, commands run, unresolved risks, ADR impact, and PHP compatibility impact. A useful report distinguishes implementation success from production readiness and future intent.