knosky 0.6.3 → 0.7.0

package/ssot/decision-codes.json

@@ -0,0 +1,133 @@
+{
+  "$schema_comment": "KnoSky DEC-108 / R3-D closed decision-code freeze. Identical list on protocol page, README, wiki, fixtures.",
+  "id": "knosky-decision-codes",
+  "version": "1.0.0",
+  "status": "draft-freeze",
+  "dec": ["DEC-108", "DEC-106"],
+  "last_updated": "2026-07-19",
+  "lattice_note": "policy-lattice.mjs uses DENY > ALLOW > NOT_APPLICABLE for rule combine. Protocol decision_code on the wire extends that with reason-specific DENY_* and Mode A label.",
+  "codes": [
+    {
+      "code": "ALLOW",
+      "http_analogy": 200,
+      "mode": "B",
+      "authorizing": true,
+      "metadata_disclosed": true,
+      "meaning": "Route/list/bundle returned under policy; audit receipt present.",
+      "client_hint": "Proceed using pointers; still open live files for truth."
+    },
+    {
+      "code": "DENY",
+      "http_analogy": 403,
+      "mode": "B",
+      "authorizing": false,
+      "metadata_disclosed": false,
+      "meaning": "No route; generic policy or authorization denial without subclass.",
+      "client_hint": "No authorized path; do not probe for hidden structure."
+    },
+    {
+      "code": "DENY_IDENTITY",
+      "http_analogy": 401,
+      "mode": "B",
+      "authorizing": false,
+      "metadata_disclosed": false,
+      "meaning": "Missing, unknown, expired/revoked lease, or spoofed agent identity.",
+      "client_hint": "Register/bind agent + valid lease before governed calls."
+    },
+    {
+      "code": "DENY_POLICY",
+      "http_analogy": 403,
+      "mode": "B",
+      "authorizing": false,
+      "metadata_disclosed": false,
+      "meaning": "Policy missing, invalid, unsigned when required, or explicit policy DENY.",
+      "client_hint": "Fix domain policy/governance; re-run kc_policy_check."
+    },
+    {
+      "code": "DENY_AUDIT",
+      "http_analogy": 503,
+      "mode": "B",
+      "authorizing": false,
+      "metadata_disclosed": false,
+      "meaning": "Ledger write or verify failed; fail closed — no ALLOW payload.",
+      "client_hint": "Check disk/permissions for audit ledger; retry later."
+    },
+    {
+      "code": "DENY_FRESHNESS",
+      "http_analogy": 409,
+      "mode": "B",
+      "authorizing": false,
+      "metadata_disclosed": false,
+      "meaning": "Map or evidence stale when freshness required.",
+      "client_hint": "Re-index / refresh map rev; retry."
+    },
+    {
+      "code": "DENY_EVIDENCE",
+      "http_analogy": 403,
+      "mode": "B",
+      "authorizing": false,
+      "metadata_disclosed": false,
+      "meaning": "Required security evidence failed (e.g. lockdown/evidence profile requirement).",
+      "client_hint": "Run knosky doctor; satisfy profile evidence or choose a lower claim profile."
+    },
+    {
+      "code": "ERROR_INVALID_INPUT",
+      "http_analogy": 400,
+      "mode": ["A", "B"],
+      "authorizing": false,
+      "metadata_disclosed": false,
+      "meaning": "Bad arguments / schema validation failure.",
+      "client_hint": "Fix tool arguments; see validation details (non-oracle)."
+    },
+    {
+      "code": "ERROR_INDEX",
+      "http_analogy": 500,
+      "mode": ["A", "B"],
+      "authorizing": false,
+      "metadata_disclosed": false,
+      "meaning": "City/index load missing or corrupt.",
+      "client_hint": "Build or repair local map index."
+    },
+    {
+      "code": "ADVISORY_UNAUTH",
+      "http_analogy": 200,
+      "mode": "A",
+      "authorizing": false,
+      "metadata_disclosed": true,
+      "meaning": "Explicit Mode A non-governed advisory navigation. Not authorized, not policy-certified, not swarm-safe.",
+      "client_hint": "Treat as structural tips only; verify before acting; do not claim governance.",
+      "aliases_rejected": ["ALLOW", "authorized", "swarm-safe"]
+    }
+  ],
+  "closed_set": [
+    "ALLOW",
+    "DENY",
+    "DENY_IDENTITY",
+    "DENY_POLICY",
+    "DENY_AUDIT",
+    "DENY_FRESHNESS",
+    "DENY_EVIDENCE",
+    "ERROR_INVALID_INPUT",
+    "ERROR_INDEX",
+    "ADVISORY_UNAUTH"
+  ],
+  "rules": [
+    "No open-string decision codes on the wire.",
+    "Mode B terminal ALLOW requires receipt_id.",
+    "All DENY_* and DENY must set metadata_disclosed=false for restricted data.",
+    "ADVISORY_UNAUTH must appear on Mode A route responses.",
+    "Pack smoke fixtures snapshot this closed_set.",
+    "CI gate: unknown code in responses fails release."
+  ],
+  "safe_deny_package": {
+    "required_fields": ["decision_code", "mode", "metadata_disclosed"],
+    "optional_fields": ["receipt_id", "next_action", "request_id"],
+    "forbidden_on_deny": [
+      "restricted path lists",
+      "blocked district node dumps",
+      "other agents lease inventories",
+      "file bodies",
+      "secrets"
+    ]
+  }
+}

package/ssot/ladder-l0-l3.md

@@ -0,0 +1,232 @@
+# KnoSky Guarantee Ladder L0–L3 (SSOT)
+
+```yaml
+---
+id: knosky-ladder-l0-l3
+version: 1.0.0
+status: draft-freeze
+dec: DEC-110
+last_updated: 2026-07-19
+consumers:
+  - README.md / SECURITY.md / PRIVACY.md
+  - knosky.com /trust and /product
+  - knosky.wiki govern/ladder
+  - knosky doctor claim_ceiling
+  - pack onboarding blurbs
+---
+```
+
+## Purpose
+
+Public, checkable promises for installers and agents. **Never claim a higher level than `knosky doctor` reports for that install.**
+
+Related freezes:
+
+- Tool menu → `tool-menu.json` (DEC-108)
+- Decision codes → `decision-codes.json` (DEC-108 / DEC-106)
+- Architecture → DOC-02; threat model → DOC-05
+
+---
+
+## Ladder at a glance
+
+| Level | Name | One-line promise | Mode |
+| :---: | :--- | :--- | :--- |
+| **L0** | Local map | Index and navigate locally; **no KnoSky upload by default** | Map / Mode A |
+| **L1** | Share-safe artifact | Artifact suitable to share only after **fail-closed secret controls** | Share tooling |
+| **L2** | Governed evaluator | **Mode B**: identity + policy + audit receipt (or safe DENY) before authorized routes | Mode B |
+| **L3** | Swarm domain | **Full coordinator** on Mode B: leases, quotas, backpressure, claims, fairness, multi-agent audit, anti-probe, ops heatmap, benchmarks | Mode B + L3 |
+
+---
+
+## L0 — Local map
+
+### Promise
+
+- Runs on the operator machine / domain.
+- Builds a **map of pointers and short projections**, not a body store (DEC-107).
+- Core path does **not** require a KnoSky account or always-on telemetry (DEC-114).
+
+### You may say
+
+- “Local map”, “citations”, “where to look first”, “MCP map tools”
+
+### You must not say
+
+- “Authorized”, “policy-enforced”, “swarm-safe”, “zero data risk”
+
+### Checks (doctor / tests)
+
+- Index builds without required egress
+- CONTRACT allowlist: no bodies in index
+- Tier 0 tools available
+
+---
+
+## L1 — Share-safe artifact
+
+### Promise
+
+- Share/export path runs **secret-like detection** and **fails closed** on hits (explicit operator override only).
+- Absolute roots stripped to basename by default.
+- Operator still reviews before publishing (honest residual risk).
+
+### You may say
+
+- “Share-safe city/bundle”, “failed closed on secrets”, “review before share”
+
+### You must not say
+
+- “Guaranteed free of all secrets forever”, “safe for any public unauth multi-tenant host without review”
+
+### Checks
+
+- Seeded secret fixture fails share-safe build
+- Safety report emitted
+- Demo corpus uses share-safe artifacts only
+
+---
+
+## L2 — Governed evaluator (Mode B)
+
+### Promise
+
+Any claim of **authorized / governed / policy-checked** routing requires:
+
+1. Bound **identity** (authoritative agent; lease store pattern — no payload spoof)
+2. **Policy lattice** decision + district classification → authorized subgraph
+3. **Audit receipt** written (metadata-only) before ALLOW payload
+4. Otherwise **DENY_*** with **no restricted metadata**
+
+Decision codes: see `decision-codes.json` (`ALLOW`, `DENY_*`, errors). Mode A may still exist **only** if labeled `ADVISORY_UNAUTH`.
+
+### You may say
+
+- “Governed route”, “authorized subgraph”, “policy-checked”, “audit-backed decision”
+
+### You must not say
+
+- That plain advisory MCP (today’s unlabeled path) is L2
+- “Kernel no-egress proven on Windows” when doctor reports unsupported (F0.5 honesty)
+
+### Checks
+
+- Anonymous governed call → `DENY_IDENTITY`
+- Audit failure → `DENY_AUDIT` and no route body
+- Policy deny does not leak restricted paths
+- Doctor `mode_b_ready` green
+- Menu SSOT matches binary
+
+### Platform honesty
+
+| Platform | Lockdown |
+| :--- | :--- |
+| Linux | Real enforcement path when tools present |
+| macOS | Partial / network-oriented |
+| Windows | Doctor must report **unsupported/inactive** until packaging proves otherwise |
+
+---
+
+## L3 — Swarm domain (full coordinator)
+
+### Promise (DEC-113 — Wave 1 floor is **full**, not label-only)
+
+On top of green L2:
+
+| Capability | Required |
+| :--- | :---: |
+| Distinct agent identities | YES |
+| Route leases (issue/renew/expire/bind) | YES |
+| Quotas | YES |
+| Backpressure | YES |
+| File/district claims (traffic, not VCS locks) | YES |
+| Fairness / conflict rules | YES |
+| Multi-agent audit stream | YES |
+| Operator swarm dashboard / heatmap | YES |
+| Anti-probe defenses | YES |
+| Swarm benchmarks | YES |
+
+### You may say
+
+- “Swarm-coordinated”, “lease-governed multi-agent routing”, “domain swarm-safe under policy”
+
+### You must not say
+
+- “Swarm-safe” when only the lease helper exists
+- Multi-tenant **cloud** swarm isolation (DEC-109 non-goal)
+- Preview-only labeling as the Wave 1 floor (would need **new DEC** to thin)
+
+### Checks
+
+- Doctor `l3_ready` green
+- Lease reuse / spoof denials
+- Coordinator down + `require_route_lease` → fail closed
+- Swarm benchmarks in release gate set
+- Claims lint blocks L3 marketing if doctor ceiling < L3
+
+### Prerequisite law
+
+```text
+L3 ⊆ requires L2 Mode B identity + policy + audit
+```
+
+---
+
+## Claim ceiling algorithm (normative)
+
+```text
+ceiling = L0
+if share_safe_controls_green: ceiling = max(ceiling, L1)
+if mode_b_composition_green and doctor.mode_b_ready: ceiling = max(ceiling, L2)
+if full_l3_modules_green and doctor.l3_ready: ceiling = max(ceiling, L3)
+if windows and claim needs kernel_lockdown_evidence: do not raise L2 badge on lockdown_is_proven
+public_copy.claim_level must be <= ceiling
+```
+
+---
+
+## Adoption profiles (language only; detailed FR in DOC-01)
+
+| Profile | Typical ceiling intent |
+| :--- | :--- |
+| Solo | L0–L1 fast path; explicit Mode A OK |
+| Team | L2 Mode B default for governed tools |
+| Regulated | L2+ with evidence requirements; security profile; Windows honesty loud |
+
+---
+
+## Metrics relationship (DEC-114)
+
+Ladder honesty is independent of adoption metrics:
+
+- **No always-on telemetry** at any L
+- Opt-in counters default **OFF**
+- Public benchmarks may support proof without elevating ladder by slogans alone
+
+---
+
+## Banned overclaim phrases (claims lint seeds)
+
+Do not use without matching doctor ceiling + evidence:
+
+- zero-risk / zero data risk  
+- fully understands your codebase  
+- SOC2 certified (unless true externally)  
+- multi-tenant SaaS isolation (W1)  
+- swarm-safe (unless L3 green)  
+- authorized / policy-enforced (unless L2 green)  
+- Windows kernel no-egress guaranteed (unless doctor proves)
+
+---
+
+## Change control
+
+| Version | Date | Notes |
+| :--- | :--- | :--- |
+| 1.0.0 | 2026-07-19 | Initial SSOT freeze draft for Wave 1 surfaces |
+
+Edits require DEC-110 revisit or superseding DEC; bump version; regenerate README/wiki/com renders.
+
+---
+
+*SSOT ladder — bind all public L0–L3 language to this file.*

package/ssot/tool-menu.json

@@ -0,0 +1,130 @@
+{
+  "$schema_comment": "KnoSky DEC-108 tool menu SSOT — Wave 1 freeze. README = wiki = site = binary must match.",
+  "id": "knosky-tool-menu",
+  "version": "1.0.0",
+  "status": "draft-freeze",
+  "dec": "DEC-108",
+  "last_updated": "2026-07-19",
+  "profiles": {
+    "coding": {
+      "description": "Default agent packs (Hermes, Claude Code, Cursor, Codex CLI, VS Code MCP). No audit ledger tools.",
+      "includes_tiers": ["tier0_map", "tier1_governed"]
+    },
+    "security": {
+      "description": "Operator / security / CI verify profile. Includes coding tools plus audit tools.",
+      "includes_tiers": ["tier0_map", "tier1_governed", "security_audit"]
+    },
+    "advisory": {
+      "description": "Explicit non-authorizing exploration. Mode A labels required. Must not be marketed as governed.",
+      "includes_tiers": ["tier0_map"],
+      "allows_mode_a_route": true
+    }
+  },
+  "tiers": {
+    "tier0_map": {
+      "name": "Tier 0 map",
+      "authorizing": false,
+      "label_when_no_policy": "non-authorizing map",
+      "tools": [
+        {
+          "name": "kc_search",
+          "summary": "Search map nodes by text/metadata over the city index.",
+          "mode_default": "A",
+          "profiles": ["coding", "security", "advisory"]
+        },
+        {
+          "name": "kc_get_node",
+          "summary": "Fetch a single node projection by id.",
+          "mode_default": "A",
+          "profiles": ["coding", "security", "advisory"]
+        },
+        {
+          "name": "kc_list_categories",
+          "summary": "List category/district manifest entries.",
+          "mode_default": "A",
+          "profiles": ["coding", "security", "advisory"]
+        },
+        {
+          "name": "kc_get_provenance",
+          "summary": "Return provenance pointers for a node (live SoT refs).",
+          "mode_default": "A",
+          "profiles": ["coding", "security", "advisory"]
+        },
+        {
+          "name": "kc_related",
+          "summary": "Related nodes via map edges (tests/docs/neighbors).",
+          "mode_default": "A",
+          "profiles": ["coding", "security", "advisory"]
+        }
+      ]
+    },
+    "tier1_governed": {
+      "name": "Tier 1 governed",
+      "authorizing": true,
+      "requires_mode_b_for_allow": true,
+      "tools": [
+        {
+          "name": "kc_route",
+          "summary": "Route GPS toward a destination. Dual-mode: Mode B ALLOW/DENY_* with receipt, or labeled Mode A ADVISORY_UNAUTH.",
+          "mode_default": "B",
+          "dual_mode": true,
+          "profiles": ["coding", "security"],
+          "advisory_profile": "advisory",
+          "decision_codes_used": true
+        },
+        {
+          "name": "kc_bundle",
+          "summary": "Build share-oriented intent-manifest/bundle under same gates + fail-closed secret scan.",
+          "mode_default": "B",
+          "profiles": ["coding", "security"],
+          "decision_codes_used": true
+        },
+        {
+          "name": "kc_policy_check",
+          "summary": "Dry-run policy decision + reasons without full route body.",
+          "mode_default": "B",
+          "profiles": ["coding", "security"],
+          "decision_codes_used": true
+        }
+      ]
+    },
+    "security_audit": {
+      "name": "Security profile only",
+      "authorizing": false,
+      "profiles_only": ["security"],
+      "tools": [
+        {
+          "name": "kc_audit_query",
+          "summary": "Query local route/swarm decision audit events (metadata-only).",
+          "mode_default": "B",
+          "profiles": ["security"],
+          "forbidden_profiles": ["coding", "advisory"]
+        },
+        {
+          "name": "kc_audit_verify",
+          "summary": "Verify audit chain / receipt integrity.",
+          "mode_default": "B",
+          "profiles": ["security"],
+          "forbidden_profiles": ["coding", "advisory"]
+        }
+      ]
+    }
+  },
+  "pack_matrix": {
+    "P0": ["hermes", "claude-code", "cursor", "codex-cli"],
+    "P1": ["vscode-mcp", "greptile-recipe", "gha-pr-gps"],
+    "default_profile_for_packs": "coding",
+    "must_not_include_on_coding_packs": ["kc_audit_query", "kc_audit_verify"]
+  },
+  "release_gates": [
+    "AR-03: README tool list == wiki tool list == knosky.com protocol summary == this file == mcp registerTool names",
+    "Mode A tools/responses must carry ADVISORY_UNAUTH when non-governed",
+    "Mode B ALLOW requires identity + policy + audit receipt",
+    "Decision codes closed set from decision-codes.json"
+  ],
+  "non_goals": [
+    "Multi-tenant SaaS tool surface",
+    "Audit tools on default coding packs",
+    "Wave 2 native app exclusive tools as W1 dependencies"
+  ]
+}