docs(krl): ground KRL identity + 5-role stack per canonical spec

[hyperpolymath]

What

Grounds README.adoc to the canonical KRL spec:

• "What it is" now leads with the agreed one-liner — KRL is QuandleDB's canonical resolution DSL: a database-facing language whose domain is knot/tangle identity, equivalence, transformation, and disambiguation — and names the fuller object list (presentations, invariants, fingerprints, equivalence classes, witnesses, disambiguation results).
• Calls out the two anti-framings explicitly: "a database language" alone wrongly suggests SQL-for-knots; "a surface DSL over Tangle" alone makes QuandleDB incidental and KRL too compiler-ish. KRL is database-facing but not merely a query language.
• "Architecture position" now enumerates the 5 stack roles, each with the question it answers: KRL (resolution DSL) → TangleIR (lowered IR) → Tangle (compute substrate) → QuandleDB (persistence + invariant/equivalence DB) + Skein.jl (backend library).

Why

First commit in a doc-grounding pass that aligns the whole estate to one canonical statement of the KRL stack, agreed directly with the maintainer. Downstream repos (Skein.jl, quandledb, tangle) will be aligned to this same framing in their own PRs.

Scope

Docs only — README.adoc. No spec/code/proof changes.

🤖 Generated with Claude Code

---

Generated by Claude Code

[github-actions]

🔍 Hypatia Security Scan

Findings: 38 issues detected

Severity	Count
🔴 Critical	4
🟠 High	10
🟡 Medium	24

⚠️ Action Required: Critical security issues found!

View findings

[
  {
    "reason": "Issue in scorecard-enforcer.yml",
    "type": "scorecard_publish_with_run_step",
    "file": "scorecard-enforcer.yml",
    "action": "split_scorecard_publish_job",
    "rule_module": "workflow_audit",
    "severity": "high"
  },
  {
    "reason": "Issue in instant-sync.yml",
    "type": "secret_action_without_presence_gate",
    "file": "instant-sync.yml",
    "action": "peter-evans/repository-dispatch",
    "rule_module": "workflow_audit",
    "severity": "high"
  },
  {
    "reason": "Issue in scorecard.yml",
    "type": "scorecard_wrapper_missing_job_permissions",
    "file": "scorecard.yml",
    "action": "flag",
    "rule_module": "workflow_audit",
    "severity": "high"
  },
  {
    "reason": "Download-and-execute pattern (curl|wget pipe to shell) -- verify integrity before execution (3 occurrences, CWE-494)",
    "type": "shell_download_then_run",
    "file": "/home/runner/work/krl/krl/setup.sh",
    "action": "flag",
    "rule_module": "code_safety",
    "severity": "high"
  },
  {
    "line": 24,
    "reason": "Secret found: Generic API key",
    "type": "secret_detected",
    "file": "/home/runner/work/krl/krl/.envrc",
    "action": "revoke_rotate_and_purge",
    "rule_module": "security_errors",
    "severity": "critical"
  },
  {
    "reason": "Nominal-only SAST in krl: codeql.yml language matrix contains no language present in the repo and lacks `actions`, so CodeQL records zero results on every commit. Remediation: set the CodeQL matrix to `language: actions`.",
    "type": "StaticAnalysis",
    "file": "/home/runner/work/krl/krl",
    "action": "auto_fix",
    "rule_module": "scorecard",
    "severity": "medium",
    "remediation": "Add CodeQL or equivalent SAST workflow.",
    "scorecard_check": "SAST"
  },
  {
    "reason": "1 workflow(s) with tag-pinned (not SHA-pinned) actions in krl",
    "type": "DependencyPinning",
    "file": "/home/runner/work/krl/krl",
    "action": "auto_fix",
    "rule_module": "scorecard",
    "severity": "medium",
    "remediation": "Pin GitHub Actions and Docker base images by SHA hash.",
    "scorecard_check": "Pinned-Dependencies"
  },
  {
    "reason": "Repository has 3 non-main remote branch(es). Policy: single main branch only.",
    "type": "GS007",
    "file": ".",
    "action": "delete_remote_branches",
    "rule_module": "git_state",
    "severity": "medium"
  },
  {
    "reason": "Code scanning (Hypatia): hypatia/structural_drift/SD022 -- Hypatia structural_drift: SD022 -- 6 day(s) old",
    "type": "CSA001",
    "file": "spec/grammar-overview.md",
    "action": "review",
    "rule_module": "code_scanning_alerts",
    "severity": "medium"
  },
  {
    "reason": "Code scanning (Hypatia): hypatia/structural_drift/SD022 -- Hypatia structural_drift: SD022 -- 6 day(s) old",
    "type": "CSA001",
    "file": "docs/practice/AI-CONVENTIONS.adoc",
    "action": "review",
    "rule_module": "code_scanning_alerts",
    "severity": "medium"
  }
]

Powered by Hypatia Neurosymbolic CI/CD Intelligence