Layer 1: Properties

What Artifacts ARE¶

Layer 1 defines the intrinsic properties of knowledge artifacts—metadata that describes what an artifact fundamentally is, independent of any specific project, workflow, or context. These properties are stored directly in document frontmatter and travel with the artifact wherever it goes.

Knowledge artifacts need structured metadata to track their quality, purpose, maturity, and completeness—metadata that travels with the artifact and remains stable across different contexts and tools.

The Five Core Properties¶

1. Refinement (Quality Score)¶

Type: Float (0.00 - 1.00)
Purpose: Measures how well the artifact’s content fulfills its stated purpose

Think of refinement as your quality gate metric:

• 0.00-0.30: Initial capture, rough notes

• 0.30-0.50: Developing, needs significant work

• 0.50-0.70: Usable for collaboration

• 0.70-0.90: High quality, ready for sharing

• 0.90-1.00: Publication-ready, evergreen

refinement: 0.75

In research workflows: Track literature notes from initial reading (0.40) to synthesized insights (0.85)

2. Origin (Creation Context)¶

Type: Enum
Purpose: Why was this artifact created?

Values:

• requirement - Created to fulfill a specific need

• question - Emerged from inquiry or exploration

• insight - Captured unexpected discovery

• task - Generated for specific action item

• reference - External source being tracked

origin: question

In research workflows: Distinguish between literature reviews (reference), research questions (question), and experimental findings (insight)

3. Form (Permanence Intent)¶

Type: Enum
Purpose: What is the intended lifecycle of this artifact?

Values:

• transient - Temporary, will be archived/deleted

• developing - Active work in progress

• stable - Settled content, minor updates expected

• evergreen - Maintained indefinitely, living document

• archived - Preserved but no longer active

form: developing

In research workflows: Lab notebooks might be transient, methodology docs evergreen, draft papers developing

4. Audience (Intended Visibility)¶

Type: Enum
Purpose: Who is this artifact intended for?

Values:

• personal - Private notes, not for sharing

• internal - Team/lab members only

• public - Can be shared externally

• published - Formally published/released

audience: internal

In research workflows: Separate private musings from sharable research notes from publication-ready content

5. Stubs (Typed Vectors)¶

Type: Array of strings OR structured objects
Purpose: Editorial demand signals with measurable properties

Stubs are more than simple TODOs or content gaps, they’re vectors for refinement. Stubs encode what kind of work is needed, how urgent it is, and who identified it.

Simple form (lightweight):

stubs:
  - expand: "Add statistical analysis section"
  - review: "Need peer review feedback"

Structured form (comprehensive):

stubs:
  - gap_id: "vec-001"
    description: "Add deployment examples"
    vector_family: "Creation"
    vector_type: "Expand"
    urgency: 0.6
    impact: 0.7
    complexity: 0.5
    stub_origin: "author-declared"
    stub_form: "transient"

Vector families classify the type of work needed:

• Retrieval - Information exists but is missing (find and link)

• Computation - Analysis needed to derive answer

• Synthesis - Multiple perspectives need reconciliation

• Creation - Original content must be written

• Structural - Fundamental architecture change required

In research workflows: Track missing citations (Retrieval), needed analysis (Computation), literature synthesis (Synthesis), new sections (Creation), or methodology refactoring (Structural)

Properties in Action¶

Layer 1 properties transform knowledge artifacts from unstructured files into a queryable, actionable knowledge base.

Querying and Discovery¶

• Find gaps by type: Query for vector_family: "Retrieval" to surface all missing citations

• Track progress: Monitor refinement evolution over time

• Manage lifecycle: Surface form: developing notes that haven’t been updated

• Quality audit: Calculate average refinement across collections

• Workload estimation: Sum potential energy ($E_p$) across stubs to forecast effort

Agentic Surfaces¶

Layer 1 properties serve as surfaces for agentic interaction—structured interfaces that AI agents can read, reason about, and act upon:

• Typed vectors drive development: A Creation stub signals “generate content here”; a Retrieval stub signals “find and link existing information.” Agents can be routed to appropriate tasks based on vector family.

• Refinement as a target: Agents can work toward a target refinement score, with stubs providing specific action items to resolve.

• Audience-aware generation: An agent knows audience: public requires higher quality (0.90+) than audience: personal (0.50+).

• Form-appropriate updates: Agents treat evergreen documents differently than transient captures—the former warrant careful enhancement, the latter quick resolution.

From Passive Metadata to Active Development¶

Traditional metadata describes artifacts after the fact. L1 properties drive document development forward:

This structured metadata is the foundation for Layer 2 interpretation and Layer 3 automation—but it’s also the contract between human authors and AI agents for collaborative knowledge work.

Next Steps¶

• Layer 2: Learn how these properties are interpreted to calculate health, usefulness, and priority

• Layer 3: See how rules automate workflows based on these properties

• Framework Overview: Return to J-Editorial

• Practice: See Layer 1 in action in the Case Study