P1: Reframe OwnLang as analysis IR/debug format, not required user-authored code

[PhysShell]

Type

Documentation / product direction / UX guardrail.

Priority

P1 / High.

Tags

ownlang, ownir, docs, ux, product-positioning, no-manual-ownlang, adoption

Problem

OwnLang is useful as an analysis vocabulary, minimized repro format, test fixture language, and debug dump. But it should not become something ordinary users must learn and write to benefit from Own.NET.

The desired product posture:

Users write C# / XAML / attributes / small markers.
Own.NET lowers semantic facts into OwnIR / OwnLang internally.
OwnLang is what Own.NET understands, not what users must author.

If the public story becomes "write another language", adoption will die immediately. People already have C#, XAML, MSBuild, DevExpress, and legacy pain. Handing them a new language is how tools become shrineware.

Proposed direction

Add a spine/design doc that fixes the contract:

OwnLang is not what users write.
OwnLang is what Own.NET understands.

Recommended user-facing inputs, in descending order of preference:

1. Automatic inference / suggestions from real C# patterns.
2. C# attributes for stable facts/barriers.
3. Marker calls or comments for local legacy anchors.
4. Approved generated .ownrules files for rare explicit project policy.
5. Hand-written .own only for tests/minimized repro/debug, not normal usage.

Scope

Create/update docs to clarify:

• OwnIR JSON is the machine transport format.
• .own is a human-readable debug/test/repro format.
• .ownrules or similar policy files are optional and should be generated/approved, not hand-authored from scratch.
• Roslyn extraction is the primary path for mainstream C#.
• OwnAudit consumes findings; it does not own analysis semantics.
• 007 runs gates; it does not understand analysis semantics.

Acceptance criteria

• README or a dedicated docs/verification-spine.md states the no-manual-OwnLang posture explicitly.
• The doc defines repo roles:
  • Own.NET = facts/checking/OwnIR/protocol semantics;
  • OwnAudit = evidence/reporting/baselines/mining;
  • 007 = execution/gates/records.
• The doc includes the first killer demo target: DocumentLoading obligation over IsLoaded and OnPropertyChanged.
• The doc lists non-goals:
  • no generic theorem prover;
  • no mandatory OwnLang authoring;
  • no LLM as source of truth;
  • no second checker in OwnAudit.

Why this matters

This protects the project from accidentally becoming a homebrew language instead of a mainstream C# analysis tool. OwnLang can remain powerful internally while the user-facing experience stays boring, scriptable, and adoptable. Boring wins. Tragically, so does gravity.