Skip to content

Publish LinxCore architecture contracts and policy-driven SPEC lane docs#34

Draft
zhoubot wants to merge 1 commit into
mainfrom
codex/model-polish-20260530
Draft

Publish LinxCore architecture contracts and policy-driven SPEC lane docs#34
zhoubot wants to merge 1 commit into
mainfrom
codex/model-polish-20260530

Conversation

@zhoubot

@zhoubot zhoubot commented May 30, 2026

Copy link
Copy Markdown
Contributor

Summary

  • package the current model-generated LinxCore docs and helper updates from the existing checkout
  • add the architecture contract pages for overview, interfaces, microarchitecture, stage catalog, module catalog, and verification matrix
  • align SPEC helper scripts with named governance phases and manifest-driven bringup subsets

Testing

  • git diff --check

Not tested

  • MkDocs contract lint
  • SPEC Stage-A helper execution

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request introduces comprehensive architectural documentation for LinxCore v0.56, including external interface contracts, microarchitecture specifications, a module catalog, a pipeline stage catalog, and a verification matrix mapping architectural intent to validation gates. Additionally, it updates the SPEC benchmark test scripts to dynamically resolve the bring-up subset from the policy manifest instead of using hardcoded lists. Feedback on the documentation highlights a hardcoded user-specific absolute path in the overview document that should be replaced with a generic placeholder for portability.

Comment on lines +141 to +142
- Standalone trees such as `/Users/zhoubot/LinxCore` are development mirrors,
not contract authority.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The document contains a hardcoded absolute path specific to a user (/Users/zhoubot/LinxCore). Hardcoded user-specific paths should be avoided in shared documentation to ensure portability and maintain privacy. Consider using a generic placeholder or referring to local development clones abstractly.

Suggested change
- Standalone trees such as `/Users/zhoubot/LinxCore` are development mirrors,
not contract authority.
- Standalone trees (e.g., local development clones) are development mirrors,
not contract authority.

The old PR branch was pinned before the Janus documentation wave landed, so it
could no longer merge cleanly and still referenced stale v0.4 contract wording
and obsolete SPEC manifest keys. Rebuilding it on top of current main keeps the
surviving contract clarifications while dropping the now-superseded history.

Constraint: The branch must be rebuilt on top of current main rather than replayed conflict-by-conflict from a stale base
Rejected: Preserve the original stale branch history | it obscures the surviving diff and keeps the PR conflict-heavy
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Keep architecture contract version bumps and SPEC policy-key changes synchronized across overview, interface, stage-catalog, and wrapper scripts
Tested: git diff --check; bash -n tests/test_specint_stage_a_xcheck.sh tests/test_specint_full_xcheck_nightly.sh
Not-tested: full architecture lint, mkdocs publish, SPEC xcheck execution
@zhoubot zhoubot force-pushed the codex/model-polish-20260530 branch from 1b9213a to c839551 Compare June 9, 2026 09:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant