ontoref/reflection/modes/coder-workflow.ncl

let d = import "../defaults.ncl" in
let ncl_export = import "../templates/step-nickel-export.ncl" in

d.make_mode String {
  id      = "coder-workflow",
  trigger = "Manage .coder/ process memory — initialize authors, record structured entries, triage markdown, publish and graduate knowledge",

  preconditions = [
    "ONTOREF_PROJECT_ROOT is set",
    "reflection/modules/coder.nu is accessible via ONTOREF_ROOT",
    "Nushell >= 0.110.0 is available",
  ],

  guards = [
    {
      id       = "coder-dir-exists",
      cmd      = "test -d .coder",
      reason   = "No .coder/ directory — run coder init first.",
      severity = 'Block,
    },
  ],

  steps = [
    {
      id     = "init-author",
      action = "Initialize an author workspace with inbox/ and author.ncl. Each human, agent, or CI actor gets their own workspace.",
      cmd    = "./ontoref coder init <author> --actor Human|AgentClaude|AgentCustom|CI",
      actor  = 'Both,
      on_error = { strategy = 'Stop },
    },
    {
      id     = "record-json",
      action = "Write a structured JSON entry to entries.jsonl. Use for insights, summaries, completed features, decisions. Entries are immediately queryable via coder log.",
      cmd    = "./ontoref coder record <author> '<content>' --title '<title>' --kind info --category insights --tags '[tag1,tag2]' --relates_to '[nodo-id]' --trigger '<why>' --domain Architecture",
      actor  = 'Both,
      depends_on = [{ step = "init-author" }],
      on_error = { strategy = 'Continue },
    },
    {
      id     = "dump-markdown",
      action = "Copy or paste markdown files into .coder/<author>/inbox/. Zero ceremony — just dump. Files are named YYYY-MM-DD-description.{kind}.md where kind is done|plan|info|review|audit|commit.",
      actor  = 'Human,
      depends_on = [{ step = "init-author" }],
      on_error = { strategy = 'Continue },
    },
    {
      id     = "triage",
      action = "Classify inbox/ files into categories (insights, features, bugfixes, investigations, decisions, reviews, resources). Generates companion NCL with validated metadata. Use --interactive for manual review.",
      cmd    = "./ontoref coder triage <author> --interactive",
      actor  = 'Both,
      depends_on = [{ step = "dump-markdown" }],
      on_error = { strategy = 'Continue },
    },
    {
      id     = "query",
      action = "Query JSONL entries across authors and categories. Filter by tag, kind, domain, or author. Export as JSON, JSONL, or CSV for external tools.",
      cmd    = "./ontoref coder log --author <author> --tag <tag> --domain <domain>",
      actor  = 'Both,
      depends_on = [{ step = "record-json" }],
      on_error = { strategy = 'Continue },
    },
    {
      id     = "novelty-check",
      action = "Compare pending entries against published entries and QA store. Flags entries with >60% Jaccard overlap as REDUNDANT (potential slop). SIMILAR entries (42-60%) get warnings. NOVEL entries pass. Prevents promoting content that duplicates existing knowledge.",
      cmd    = "./ontoref coder novelty-check <author>",
      actor  = 'Both,
      depends_on = [{ step = "triage" }],
      on_error = { strategy = 'Continue },
      note   = "Anti-slop guard: entries flagged REDUNDANT should be reviewed before publish. High overlap means the knowledge already exists in the project.",
    },
    {
      id     = "publish",
      action = "Promote entries from an author workspace to .coder/general/<category>/. Files are prefixed with author name for attribution.",
      cmd    = "./ontoref coder publish <author> <category>",
      actor  = 'Human,
      depends_on = [{ step = "novelty-check" }],
      on_error = { strategy = 'Continue },
    },
    {
      id     = "graduate",
      action = "Copy graduated entries from .coder/ to a committed path (reflection/knowledge/). Only categories marked graduable=true in context.ncl are eligible.",
      cmd    = "./ontoref coder graduate general/insights --target reflection/knowledge",
      actor  = 'Human,
      depends_on = [{ step = "publish" }],
      on_error = { strategy = 'Stop },
    },
    ncl_export {
      id     = "validate-ontology-core",
      action = "After creating new systems or schemas, register them in .ontology/core.ncl with artifact_paths. Validate core.ncl exports without contract errors.",
      file   = ".ontology/core.ncl",
    },
    ncl_export {
      id        = "validate-ontology-state",
      action    = "Update state.ncl if maturity changed. Validate state.ncl exports without contract errors.",
      file      = ".ontology/state.ncl",
      depends_on = [{ step = "validate-ontology-core" }],
    },
  ],

  postconditions = [
    "coder authors lists all active author workspaces",
    "coder log returns queryable structured entries",
    "New systems have nodes in .ontology/core.ncl with artifact_paths",
  ],
}