How-To: Inspect, Link, and Validate Knowledge Kernel Objects

This practical guide provides step-by-step recipes for inspecting objects, establishing semantic graph relationships, advancing lifecycle states, authoring validation policy rules, and verifying Definition of Done (DoD) compliance.

---

Recipe 1: Link and Unlink Relationships (object ref add / object ref remove)

Connecting objects across the ontology graph is a first-class operation. Always use schema-aware reference commands rather than low-level scalar --field modifications.

Preferred Modern Pattern:

# 1. Link a requirement to a backlog item (automatically maps to requirement_refs):
zqk object ref add BLI-001 REQ-001

# 2. Link multiple criteria to a requirement atomically:
zqk object ref add REQ-001 CRIT-001 CRIT-002

# 3. Explicitly target a specific reference field when needed:
zqk object ref add BLI-001 PRI-001 --field priority_plan_ref

# 4. Remove a reference relationship cleanly:
zqk object ref remove BLI-001 REQ-001

---

Recipe 2: Advance Object Lifecycle States (object promote / demote / park)

Every kernel object kind is governed by an authoritative finite state machine (e.g. originated ➔ planned ➔ in_progress ➔ validated ➔ complete). Never use object update --field status=<status> for lifecycle progression.

Preferred Modern Pattern:

# 1. Promote an object to its next valid lifecycle state:
zqk object promote BLI-001

# 2. Promote multiple objects concurrently:
zqk object promote BLI-001,BLI-002,BLI-003

# 3. Demote an object if QA verification uncovers rework:
zqk object demote BLI-001

# 4. Park an object along an intentional lifecycle exit:
zqk object park BLI-001

---

Recipe 3: Inspect an Object as an Autonomous Agent

When an AI agent needs to inspect a task, backlog item, or requirement without consuming unnecessary LLM context window tokens:

# Request agent-optimized semantic JSON projection
zqk object inspect backlog_item BLI-001 -f json

Expected Result:

{
  "kind": "backlog_item",
  "id": "BLI-001",
  "status": "in_progress",
  "priority": "P0",
  "title": "Implement pure-Go CAS storage backend",
  "storage_profile": {
    "storage_plane": "cas",
    "cas_hash": "e3b0c442...",
    "byte_size": 1420
  },
  "lineage": {
    "requirement": "REQ-001",
    "priority_plan": "PRI-001",
    "is_intact": true
  },
  "criteria_summary": {
    "total": 3,
    "satisfied": 2,
    "pending": 1
  }
}

---

Recipe 4: Launch the Full Interactive Object Inspector

For human developers exploring the graph interactively:

zqk object inspect

1. Cycle Kinds: Press [Tab] to cycle across backlog_item, requirement, criteria, test_case, milestone, priority_plan, and policy.
2. Filter: Press [f] to filter to [ACTIVE], [MINE], or [BLOCKED].
3. Search: Press [/], type a query (e.g. auth), and press [Enter]. Use [n] / [N] to navigate matches.
4. Drill Down: Press [Enter] on any row to open the deep inspection modal.
5. Adjust Display Density: Press [z] to switch between newb (full headers & hints), pro (compact single-line), and jedi (zen mode with maximum rows).

---

Recipe 5: Write and Test a Policy Rule Live

To test new validation rules against the current repository before committing:

1. Launch directly into the Policy Studio: bash zqk object inspect backlog_item --policy-studio

2. Navigate to an existing rule with [j]/[k], or create a custom rule.

3. Press [c] to enter DSL Edit Mode.
4. Type your condition: status != "" && len(requirement_refs) > 0

• Press [Tab] to trigger dynamic autocompletion for schema field tokens. 5. Press [Enter] to apply. 6. Press [t] to run a live dry-run evaluation across all active objects. The status line will report pass/violation counts immediately.

---

Recipe 6: Verify Definition of Done in Mission Control & Test Dashboard

To verify downward traceability and test coverage across the entire project:

# 1. Launch Mission Control on QA Tab
zqk ui --tab qa

# 2. Or run the terminal Test & DoD Verification Dashboard
zqk test dashboard --check-dod

• Review the DoD Vitals Card:
• Traceability DoD: Must show 100% Intact [PASS].
• Intact Chains: Confirms test case lineage to root objects.
• Unbound Criteria: Must be 0 [OK].
• Press [t] at any time to re-scan the test matrix and refresh test case execution states.
• Press [Enter] on any test suite row to inspect its exact bound criteria, test target file, and lineage chain.

---

Modern vs. Legacy Mutation Cheatsheet

---

Related References

• Mission Control UI & Diagnostics Visual Guide — Comprehensive visual walkthrough of all 8 TUI tabs and Web Studio.
• Object Inspector & Policy Studio Manual — Complete keybinding reference and modal architecture.
• First-Run Object Tutorial — Step-by-step object lifecycle walkthrough.