@moreih29/nexus-core 0.12.0 → 0.13.0

package/scripts/validate.ts

@@ -1,90 +0,0 @@
-#!/usr/bin/env bun
-
-import path from 'node:path';
-import {
-  loadSchemas,
-  runAll as runSchemaAndIntegrity,
-  type ValidationResult,
-} from './lib/validate.ts';
-import {
-  checkHarnessSpecific,
-  checkConcreteModel,
-  checkPromptOnly,
-  checkTagTriggerConsistency,
-} from './lib/lint.ts';
-import {
-  checkDirectoryStrict,
-  checkIdMatch,
-} from './lib/structure.ts';
-
-const IS_GITHUB_ACTIONS = process.env.GITHUB_ACTIONS === 'true';
-
-async function main(): Promise<void> {
-  const root = process.cwd();
-  const allResults: ValidationResult[] = [];
-
-  // Gate 1-5: schema + referential integrity + manifest generation
-  // (runAll internally does per-file fail-forward and generates manifest on success)
-  await loadSchemas(root);
-  const schemaResults = await runSchemaAndIntegrity(root);
-  allResults.push(...schemaResults);
-
-  // Gate 6: harness-specific tool names
-  const harnessResults = await checkHarnessSpecific(root);
-  allResults.push(...harnessResults);
-
-  // Gate 7: concrete model names
-  const modelResults = await checkConcreteModel(root);
-  allResults.push(...modelResults);
-
-  // Gate 8: prompt-only enforcement
-  const promptOnlyResults = await checkPromptOnly(root);
-  allResults.push(...promptOnlyResults);
-
-  // Gate 9: directory strict
-  const dirResults = await checkDirectoryStrict(root);
-  allResults.push(...dirResults);
-
-  // Gate 10: id ↔ directory name + kebab pattern
-  const idResults = await checkIdMatch(root);
-  allResults.push(...idResults);
-
-  // Gate 11: tag trigger consistency
-  const tagTriggerResults = await checkTagTriggerConsistency(root);
-  allResults.push(...tagTriggerResults);
-
-  // Report
-  const errors = allResults.filter((r) => r.severity === 'error');
-  const warnings = allResults.filter((r) => r.severity === 'warning');
-
-  if (allResults.length === 0) {
-    console.log('All 11 validation gates passed.');
-    return;
-  }
-
-  if (IS_GITHUB_ACTIONS) {
-    // GitHub annotations format
-    for (const r of allResults) {
-      const level = r.severity === 'error' ? 'error' : 'warning';
-      const lineAttr = r.line ? `,line=${r.line}` : '';
-      console.log(`::${level} file=${r.file}${lineAttr}::[${r.gate}] ${r.message}`);
-    }
-  } else {
-    // Human-readable format
-    for (const r of allResults) {
-      const loc = r.line ? `${r.file}:${r.line}` : r.file;
-      console.log(`${loc}  [${r.gate}] ${r.severity.toUpperCase()}: ${r.message}`);
-    }
-    console.log('');
-    console.log(`Summary: ${errors.length} error(s), ${warnings.length} warning(s)`);
-  }
-
-  if (errors.length > 0) {
-    process.exit(1);
-  }
-}
-
-main().catch((err) => {
-  console.error('Fatal error in validate.ts:', err);
-  process.exit(2);
-});

package/skills/nx-init/meta.yml

@@ -1,8 +0,0 @@
-name: nx-init
-description: Project onboarding — scan, mission, essentials, context generation
-summary: "Project onboarding — scan, mission, essentials, context generation"
-manual_only: true
-harness_docs_refs:
-  - instruction_file
-  - slash_command_display
-id: nx-init

package/skills/nx-plan/meta.yml

@@ -1,10 +0,0 @@
-name: nx-plan
-description: Structured multi-perspective analysis to decompose issues, align on
-  decisions, and produce an enriched plan before execution. Plan only — does not
-  execute.
-summary: "Structured planning — subagent-based analysis, deliberate decisions, produce execution plan"
-triggers:
-  - plan
-harness_docs_refs:
-  - resume_invocation
-id: nx-plan

package/skills/nx-run/meta.yml

@@ -1,8 +0,0 @@
-name: nx-run
-description: Execution — user-directed agent composition.
-summary: "Execution — user-directed agent composition"
-triggers:
-  - run
-harness_docs_refs:
-  - resume_invocation
-id: nx-run

package/skills/nx-sync/meta.yml

@@ -1,7 +0,0 @@
-name: nx-sync
-description: Context knowledge synchronization — scans project state and updates
-  .nexus/context/ design documents
-summary: "Context knowledge synchronization"
-triggers:
-  - sync
-id: nx-sync

package/vocabulary/capabilities.yml

@@ -1,65 +0,0 @@
-# Harness-neutral capability definitions.
-# Each entry describes WHAT is denied in semantic terms.
-# Consumers (claude-nexus, opencode-nexus) maintain their own
-# local map from these ids/classes to concrete tool names in their own repo.
-# nexus-core does not and must not know those tool names.
-
-capabilities:
-  - id: no_file_edit
-    description: "Agent cannot create, modify, or delete files in the user's workspace."
-    intent: workspace_write_denial
-    blocks_semantic_classes:
-      - file_creation
-      - file_modification
-      - file_deletion
-      - partial_file_edit
-      - structured_document_edit
-    prose_guidance: |
-      Block any tool whose primary effect is to alter content at a workspace
-      file path. This includes: creating new files at arbitrary paths, rewriting
-      whole file contents, applying partial edits (diffs, patches, find-replace,
-      multi-edit batches), deleting or truncating files, and cell-level edits in
-      structured documents such as notebooks.
-      Read-only operations are NOT blocked: reading file contents, querying
-      metadata, listing directories, and running code-intelligence queries that
-      do not mutate files.
-
-  - id: no_task_create
-    description: "Agent cannot create new tasks in the Nexus task pipeline."
-    intent: task_pipeline_append_denial
-    blocks_semantic_classes:
-      - nexus_task_creation
-    prose_guidance: |
-      Block any tool that appends a new task to the Nexus task pipeline (the
-      mechanism by which Lead-owned work is enqueued for execution). Tools that
-      read, list, or query existing tasks are NOT blocked. Tools that modify
-      existing task state belong to a separate capability (no_task_update) and
-      are not governed here.
-
-  - id: no_task_update
-    description: "Agent cannot update the state of existing Nexus tasks."
-    intent: task_pipeline_mutate_denial
-    blocks_semantic_classes:
-      - nexus_task_state_transition
-      - nexus_task_metadata_modification
-    prose_guidance: |
-      Block any tool that mutates an existing Nexus task: changing its status,
-      editing its description, reassigning ownership, closing it, or modifying
-      any field on its record. Tools that read, list, or query tasks are NOT
-      blocked. Creation of new tasks is governed by no_task_create, not here.
-
-  - id: no_shell_exec
-    description: "Agent cannot execute arbitrary shell commands or spawn subprocesses."
-    intent: shell_execution_denial
-    blocks_semantic_classes:
-      - shell_command_exec
-      - subprocess_spawn
-      - interactive_shell_session
-    prose_guidance: |
-      Block any tool whose primary effect is to run a command-line invocation,
-      shell script, or spawn a subprocess on the user's machine. This includes
-      general-purpose shell runners, background process managers, shell output
-      readers, and shell-session kill operations. Tools that read files, query
-      metadata, or call specialized non-shell APIs (HTTP, language-server
-      queries, sandboxed code evaluators that do not spawn user-machine
-      processes) are NOT blocked.

package/vocabulary/categories.yml

@@ -1,11 +0,0 @@
-# Agent role categories. Determined by reasoning surface vs artifact surface.
-
-categories:
-  - id: how
-    description: "분석·자문. 깊은 맥락 유지가 핵심 자산. architect, designer, postdoc, strategist."
-
-  - id: do
-    description: "실행. 산출물(artifact) 단위로 작업하고 종료. engineer, writer, researcher."
-
-  - id: check
-    description: "검증. 항상 fresh한 관점에서 독립적으로 검사. tester, reviewer."

package/vocabulary/invocations.yml

@@ -1,147 +0,0 @@
-# Harness-neutral invocation semantic definitions.
-# Each entry describes WHAT is invoked and what params are semantically required.
-# Consumers (claude-nexus, opencode-nexus) maintain their own
-# local map from these semantic primitives to concrete tool call syntax in their own repo.
-# nexus-core does not and must not know those tool names.
-#
-# body.md uses macro syntax: {{primitive_id key1=val1 key2=val2}}
-# See Spec γ (plan session #4, Issue #2) for macro grammar.
-
-invocations:
-  - id: skill_activation
-    description: "Activate another skill within the current conversation."
-    intent: skill_entry_dispatch
-    semantic_params:
-      - name: skill
-        description: "Canonical skill id from manifest.json skills list."
-        required: true
-      - name: mode
-        description: "Activation mode (e.g., 'auto' for non-interactive)."
-        required: false
-    prose_guidance: |
-      Invoke a skill whose logic should be inlined into the current session.
-      The target skill must exist in the current harness's skill registry.
-      The invocation transfers execution context to the named skill; the
-      calling skill yields until the activated skill completes or signals
-      a return. Optional mode parameters modify activation behavior (e.g.,
-      bypassing interactive prompts for fully autonomous execution).
-      Only skill ids that appear in manifest.json are valid targets.
-    fallback_behavior: |
-      If the harness lacks a live skill activation primitive, re-emit the
-      skill's trigger tag (e.g., '[plan:auto]') as a self-dispatch signal,
-      relying on tag detection to re-enter the skill. The skill id must be
-      mapped to its canonical trigger tag by the harness's own docs.
-
-  - id: subagent_spawn
-    description: "Spawn a new subagent session with a specific role and prompt."
-    intent: subagent_session_create
-    semantic_params:
-      - name: target_role
-        description: "Canonical agent id from manifest.json agents list (e.g., 'writer', 'engineer')."
-        required: true
-      - name: prompt
-        description: "Structured task prompt. May be multiline (heredoc in body.md)."
-        required: true
-      - name: name
-        description: "Optional instance label for this subagent session."
-        required: false
-      - name: resume_tier_hint
-        description: "Optional hint from vocabulary/resume-tiers.yml (e.g., 'bounded', 'ephemeral')."
-        required: false
-    prose_guidance: |
-      Delegates a bounded unit of work to an agent with the given role.
-      The target_role must match an id in manifest.json agents list; the
-      harness resolves this to a concrete session or thread configuration.
-      The prompt provides the complete task specification for the subagent,
-      including all context the agent needs — do not rely on ambient session
-      state unless the resume_tier_hint indicates persistent context.
-      resume_tier_hint is advisory: harnesses may override based on their
-      own session management constraints.
-    fallback_behavior: |
-      If the harness lacks an explicit subagent spawn primitive (e.g.,
-      hooks-based implicit routing), inject the target_role as a routing
-      hint and structure the prompt so the harness's own delegation rules
-      catch it. A harness that cannot spawn agents must document this
-      limitation and treat the invocation as a no-op with a warning.
-
-  - id: task_register
-    description: "Register a task for user-visible progress tracking."
-    intent: execution_visibility_register
-    semantic_params:
-      - name: label
-        description: "Short human-readable task label."
-        required: true
-      - name: state
-        description: "Current state (pending / in_progress / completed)."
-        required: true
-    prose_guidance: |
-      Primarily for TUI progress rendering — allows the user to see which
-      work items are active, pending, or done during multi-step execution.
-      The label should be concise enough to display in a progress panel.
-      The state values are constrained to a three-state lifecycle: pending
-      (enqueued but not started), in_progress (currently executing), and
-      completed (done). Harnesses without TUI progress support may silently
-      no-op this primitive; failure must not block execution flow.
-    fallback_behavior: |
-      If the harness has no TUI task tracker, omit the call entirely. This
-      primitive is best-effort — failure or absence must not block
-      execution. Logging the label and state to the conversation transcript
-      is acceptable as a degraded fallback for auditability.
-
-  - id: user_question
-    description: "Ask the user a structured question with selectable options."
-    intent: structured_user_prompt
-    semantic_params:
-      - name: question
-        description: "The question text shown to the user."
-        required: true
-      - name: options
-        description: "Array of option objects, each with 'label' and 'description'. If empty, free-form response is expected."
-        required: true
-    prose_guidance: |
-      Presents the user with a structured decision point. When options is
-      non-empty, the user is expected to select one of the provided choices;
-      when empty, the user provides a free-form text response. The harness
-      is responsible for rendering options in a way appropriate to its UI
-      (e.g., numbered list, interactive picker, inline buttons). The LLM
-      should not proceed with execution until a response is received.
-      Use this primitive for branch points that require explicit user input,
-      not for informational messages or confirmations that could be inferred
-      from context.
-    fallback_behavior: |
-      If the harness lacks a structured question tool (e.g., opencode-nexus),
-      present the question as prose followed by the options enumerated as a
-      numbered list, then await the user's free-form reply. The LLM is
-      expected to map the reply to the most appropriate option or treat it
-      as a free-form answer if no options were given.
-
-  - id: memory_read_observation
-    description: >
-      Harness-local observation of an agent reading a file under .nexus/memory/.
-      This invocation captures the moment a memory file's content is loaded into
-      an agent's context. It is not the read action itself — the read is performed
-      by the harness's file-read primitive — but the observation event emitted by
-      the harness after the read completes.
-    intent: memory_read_observation
-    semantic_params:
-      - name: file_path
-        description: Absolute or project-relative path to the memory file that was read.
-        required: true
-      - name: reader_identity
-        description: Opaque identifier of the agent or subject that performed the read.
-        required: true
-      - name: observed_at
-        description: ISO 8601 timestamp of the observation event.
-        required: true
-    prose_guidance: >
-      Harnesses that wish to track memory access to support informed gc decisions
-      should implement this observation by hooking into their filesystem read
-      primitive and emitting the event after a read under .nexus/memory/ completes.
-      Writes and directory scans are excluded. The accumulated records are persisted
-      per conformance/state-schemas/memory-access.schema.json at
-      .nexus/state/{harness_id}/memory-access.jsonl.
-    fallback_behavior: >
-      If the harness cannot observe file-read events (no equivalent hook), memory
-      access tracking is unavailable and forgetting decisions must rely on manual
-      inspection via the [m:gc] tag. Automatic deletion policies requiring access
-      metadata are consequently not enabled in such harnesses.

package/vocabulary/memory_policy.yml

@@ -1,88 +0,0 @@
-# Canonical memory policy vocabulary for .nexus/memory/.
-# Defines categories, naming conventions, access tracking semantics,
-# forgetting policy, and merge preference.
-# Consumers (claude-nexus, opencode-nexus) read this file; specific thresholds
-# and enforcement mechanics are consumer-local.
-
-categories:
-  - id: empirical
-    prefix: empirical-
-    description: >
-      Empirically verified findings — observations and measurements that the
-      project has confirmed through its own experimentation. Examples include
-      runtime behavior observations, testing-derived structural facts, and
-      operational measurements that cannot be inferred from documentation alone.
-  - id: external
-    prefix: external-
-    description: >
-      External constraints and references — requirements imposed by upstream
-      dependencies, third-party API limits, vendor documentation quotations, and
-      any knowledge that originates outside the project. May become stale if
-      the upstream source changes.
-  - id: pattern
-    prefix: pattern-
-    description: >
-      Tactical operational patterns — recurring cycle-level recipes, routing
-      heuristics, and procedural knowledge developed through work on the project.
-      Architectural or design-level patterns belong in .nexus/context/, not here.
-
-naming:
-  pattern: "^[a-z0-9][a-z0-9-]*\\.md$"
-  description: >
-    Memory filenames are lowercase kebab-case .md files. The name should be a
-    descriptive topic of 2–4 words. An optional category prefix from the
-    categories section above may precede the topic. Version numbers and dates
-    must not appear in filenames — temporal information belongs inside the file.
-  optional_prefix: true
-
-access_tracking:
-  observation_primitive: file_read
-  scope: .nexus/memory/
-  description: >
-    Harnesses observe the moment an agent reads a memory file. Save events,
-    directory scans (glob, grep), and mentions of the path in prose are not
-    observation events. The set of events observed determines the accumulated
-    access record.
-  information_accumulated:
-    - name: last_access_timestamp
-      meaning: >
-        Wall-clock time of the most recent read event. Field name is harness-local;
-        the canonical schema for storage is conformance/state-schemas/memory-access.schema.json.
-    - name: access_count
-      meaning: >
-        Cumulative count of read events observed for this file since tracking began.
-    - name: last_reader_identity
-      meaning: >
-        Identifier of the most recent reader (agent id or equivalent). Harness-local
-        value domain.
-  storage_contract_reference: conformance/state-schemas/memory-access.schema.json
-
-forgetting:
-  manual_gate_default: true
-  description: >
-    Manual gc (triggered by the [m:gc] tag) is the default forgetting path.
-    Automatic deletion is opt-in per consumer and never runs without explicit
-    enablement.
-  automatic_deletion_structure:
-    principle: minimum_three_signal_intersection
-    description: >
-      If a consumer enables automatic deletion, the policy must require the
-      simultaneous satisfaction of at least three independent signals — for
-      example, elapsed time since last access, cycles since last read, and
-      cumulative access count. Single-signal automatic deletion is prohibited.
-      The specific signal thresholds are consumer-local and must be set to
-      match the project's cycle cadence.
-  recoverable_deletion_requirement: git_commit
-  recoverable_deletion_description: >
-    Every memory file deletion must be recorded as a git commit. The commit
-    message should include a recovery path that allows the file to be
-    reconstructed via git history. Specific commit message format is
-    consumer-local.
-
-merge:
-  principle: merge_before_create
-  description: >
-    When a new memory save candidate substantively overlaps an existing file
-    in topic and category, merging the new content into the existing file is
-    preferred over creating a new file. Specific overlap-detection criteria
-    (for example, keyword match thresholds) are consumer-local.

package/vocabulary/resume-tiers.yml

@@ -1,11 +0,0 @@
-# Agent session resumability tiers. Reflects what kind of surface the agent produces.
-
-resume_tiers:
-  - id: persistent
-    description: "세션 전체를 지속한다. HOW 카테고리 에이전트와 researcher. 맥락 누적이 핵심 자산."
-
-  - id: bounded
-    description: "artifact 단위로 지속한다. engineer, writer. 특정 산출물 완성 후 종료."
-
-  - id: ephemeral
-    description: "항상 새로 시작한다. tester, reviewer. 이전 맥락 없이 독립 검증해야 하기 때문."

package/vocabulary/tags.yml

@@ -1,60 +0,0 @@
-# Canonical definition of all Nexus tag triggers.
-# Slash command triggers are NOT stored here — each harness resolves them
-# in its own command namespace.
-# variants field is valid for both skill and inline_action types.
-
-tags:
-  # skill tags (3 entries, 4 triggers)
-  - id: plan
-    trigger: "[plan]"
-    type: skill
-    skill: nx-plan
-    description: "Activates nx-plan skill for structured multi-perspective analysis and decision recording"
-    variants: ["auto"]   # [plan:auto] for autonomous mode
-
-  - id: run
-    trigger: "[run]"
-    type: skill
-    skill: nx-run
-    description: "Activates nx-run skill for task execution with subagent composition"
-
-  - id: sync
-    trigger: "[sync]"
-    type: skill
-    skill: nx-sync
-    description: "Activates nx-sync skill for .nexus/context/ knowledge synchronization"
-
-  # inline action tags (4 entries, 5 triggers)
-  - id: d
-    trigger: "[d]"
-    type: inline_action
-    handler: nx_plan_decide
-    description: "Records a decision during an active plan session"
-
-  - id: m
-    trigger: "[m]"
-    type: inline_action
-    handler: memory_store
-    description: "Stores a lesson or reference to .nexus/memory/"
-    prose_guidance: >
-      저장 admission 기준 — 코드/웹에서 다시 얻을 수 없는 정보만 저장한다.
-      memory 파일의 naming, category, lifecycle 운영 정책은
-      vocabulary/memory_policy.yml과 docs/memory-lifecycle-contract.md를
-      canonical source로 참조한다.
-
-  - id: m-gc
-    trigger: "[m:gc]"
-    type: inline_action
-    handler: memory_gc
-    description: "Garbage-collects .nexus/memory/ by merging or removing stale entries"
-    prose_guidance: >
-      gc 트리거 조건 평가, merge 판단, forgetting policy 집행은
-      vocabulary/memory_policy.yml에 정의된 원칙을 따르고
-      구체 임계값은 consumer-local 설정으로 결정한다.
-
-  - id: rule
-    trigger: "[rule]"
-    type: inline_action
-    handler: rule_store
-    description: "Stores a project rule to .nexus/rules/. [rule:*] supports tag parameter."
-    variants: ["*"]   # [rule:any-tag] for parameterized variants

package/vocabulary/task-exceptions.yml

@@ -1,29 +0,0 @@
-# Canonical exception rules for task decomposition and counting.
-# Each entry defines a condition under which standard task decomposition rules
-# are suspended or modified, along with the alternative treatment to apply.
-# Consumers apply these exceptions during nx-plan task synthesis.
-
-task_exceptions:
-  - id: docs_only.coherent
-    description: "A batch of documentation files that all address the same scheme, decision, or structural change and should be treated as a single coherent unit."
-    applies_when: "all changed files are .md or frontmatter-only, and share one common scheme, decision, or structural change"
-    treatment: "bundle into 1 writer task + 1 reviewer pair; file count / line count thresholds waived; state coherence claim in task approach field"
-    rationale: "e.g., updating agent frontmatter files after a new field is introduced; files share the same change intent"
-
-  - id: docs_only.independent
-    description: "A set of documentation files where each file addresses a distinct topic with no cross-reference dependency."
-    applies_when: "each .md file addresses a distinct topic with no cross-reference dependency"
-    treatment: "N parallel writer tasks (one per file), each paired with 1 reviewer task; file count threshold waived per-task"
-    rationale: "e.g., separate proposal drafts; each file is independently consumed"
-
-  - id: same_file_bundle
-    description: "Two or more decomposed sub-tasks that would each modify the same target file, requiring merger to avoid conflicts."
-    applies_when: "two or more sub-tasks in the decomposition would each modify the same target file"
-    treatment: "merge sub-tasks into a single task under one owner with a structured prompt listing each sub-task's requirements; the merged task counts as 1 task and 1 artifact cluster; does not apply when sub-tasks are sequenced (A's output feeds B) — those remain separate with a deps relationship"
-    rationale: "parallel subagents targeting the same file cause merge conflicts"
-
-  - id: generated_artifacts
-    description: "Files that are build output and do not represent independent authoring decisions."
-    applies_when: "files are build output (e.g., paths declared as build outputs in the harness's build configuration)"
-    treatment: "excluded from task count, artifact cluster file count, and line count calculations; committed as part of the task that triggers their generation"
-    rationale: "generated files do not represent independent authoring decisions"