feat: add .ctxrc provenance_required config

Projects can now relax provenance flags (session_id, branch,
commit) individually via .ctxrc instead of requiring all three
on every ctx add. Default remains all-required. CLI stays
strict — only human config relaxes, agents cannot bypass.

Also backfills tool, steering, hooks into ctxrc JSON schema
and test mirror struct.

Spec: specs/init-plugin-local-enable.md
Signed-off-by: Jose Alekhinne <jose@ctx.ist>

Author: josealekhine

.context/TASKS.md

@@ -59,14 +59,12 @@ TASK STATUS LABELS:
   hooks. #priority:high #session:a92cadca #branch:main #commit:68fbc00a
   #added:2026-04-06-151044
 
-- [ ] Wire provenance flags into add skills: update ctx-task-add,
+- [x] Wire provenance flags into add skills: update ctx-task-add,
   ctx-decision-add, and ctx-learning-add skills to pass --session-id, --branch,
   --commit from the hook-relayed provenance line when invoking ctx add. Spec:
   specs/task-session-provenance.md #priority:medium #session:a92cadca
   #branch:main #commit:68fbc00a #added:2026-04-06-151036
 
-
-
 - [x] JSONL schema validation: derive schema from empirical JSONL data, embed in
   binary, validate on import (warn, never block), add `ctx journal schema check`
   command with nightly drift reports to `.context/reports/schema-drift.md`.
@@ -641,7 +639,7 @@ Taxonomy (from prefix analysis):
   #priority:low #added:2026-03-07-220825
 
 
-- [ ] Add .ctxrc provenance validation config: allow projects to relax required
+- [x] Add .ctxrc provenance validation config: allow projects to relax required
   provenance flags (session, branch, commit) individually via ctxrc fields. CLI
   stays strict — no --skip-validation flag. Agent cannot bypass; only human
   config relaxes. Default: all three required. #priority:medium

docs/home/configuration.md

@@ -109,6 +109,11 @@ A commented `.ctxrc` showing all options and their defaults:
 #   timeout: 10
 #   enabled: true
 #
+# provenance_required:  # Relax provenance flags for ctx add
+#   session_id: true    # Require --session-id (default: true)
+#   branch: true        # Require --branch (default: true)
+#   commit: true        # Require --commit (default: true)
+#
 # priority_order:
 #   - CONSTITUTION.md
 #   - TASKS.md
@@ -150,6 +155,9 @@ A commented `.ctxrc` showing all options and their defaults:
 | `hooks.dir`             | `string`   | `.context/hooks` | Hook scripts directory                                                                                                                |
 | `hooks.timeout`         | `int`      | `10`          | Per-hook execution timeout in seconds                                                                                                     |
 | `hooks.enabled`         | `bool`     | `true`        | Whether hook execution is enabled                                                                                                         |
+| `provenance_required.session_id` | `bool` | `true` | Require `--session-id` on `ctx add` for tasks, decisions, learnings                                                            |
+| `provenance_required.branch` | `bool` | `true`     | Require `--branch` on `ctx add` for tasks, decisions, learnings                                                                |
+| `provenance_required.commit` | `bool` | `true`     | Require `--commit` on `ctx add` for tasks, decisions, learnings                                                                |
 
 **Default priority order** (*used when `priority_order` is not set*):
 

docs/recipes/knowledge-capture.md

@@ -397,6 +397,18 @@ Both approaches produce the same structured entries in the same context files.
 * **Trust the agent's proactive instincts**. Agents trained on the `ctx` playbook will
   offer to persist context at milestones. A brief "*want me to save this?*" is
   cheaper than re-discovering the same lesson three sessions later.
+* **Relax provenance per-project** if `--session-id`, `--branch`, or `--commit`
+  are impractical (e.g., manual notes outside an AI session). Add to `.ctxrc`:
+
+    ```yaml
+    provenance_required:
+      session_id: false   # allow entries without --session-id
+      branch: true        # still require --branch
+      commit: true        # still require --commit
+    ```
+
+    Default is all three required. Only human config relaxes:
+    Agents cannot bypass, and that's by design.
 
 ## Next Up
 

internal/assets/embed_test.go

@@ -366,6 +366,10 @@ func TestSchemaCoversCtxRC(t *testing.T) {
 		SpecNudgeMinLen     int    `yaml:"spec_nudge_min_len"`
 		Notify              *int   `yaml:"notify"`
 		FreshnessFiles      []int  `yaml:"freshness_files"`
+		Tool                string `yaml:"tool"`
+		Steering            *int   `yaml:"steering"`
+		Hooks               *int   `yaml:"hooks"`
+		ProvenanceRequired  *int   `yaml:"provenance_required"`
 	}
 	yamlBytes, marshalErr := yaml.Marshal(ctxRC{})
 	if marshalErr != nil {

internal/assets/schema/ctxrc.schema.json

@@ -165,6 +165,25 @@
       "description": "Task content length above which a spec nudge fires regardless of signal words. Default: 150.",
       "minimum": 0
     },
+    "provenance_required": {
+      "type": "object",
+      "description": "Controls which provenance flags are required for ctx add. Default: all true. Set to false to relax per-project.",
+      "additionalProperties": false,
+      "properties": {
+        "session_id": {
+          "type": "boolean",
+          "description": "Require --session-id. Default: true."
+        },
+        "branch": {
+          "type": "boolean",
+          "description": "Require --branch. Default: true."
+        },
+        "commit": {
+          "type": "boolean",
+          "description": "Require --commit. Default: true."
+        }
+      }
+    },
     "notify": {
       "type": "object",
       "description": "Webhook notification settings.",
@@ -184,6 +203,50 @@
           "minimum": 0
         }
       }
+    },
+    "tool": {
+      "type": "string",
+      "description": "Active AI tool identifier (e.g., claude, cursor, cline, kiro, codex)."
+    },
+    "steering": {
+      "type": "object",
+      "description": "Steering layer configuration overrides.",
+      "additionalProperties": false,
+      "properties": {
+        "dir": {
+          "type": "string",
+          "description": "Path override for the steering directory."
+        },
+        "default_inclusion": {
+          "type": "string",
+          "description": "Default inclusion mode for new steering files."
+        },
+        "default_tools": {
+          "type": "array",
+          "description": "Default tool identifier list for new steering files.",
+          "items": { "type": "string" }
+        }
+      }
+    },
+    "hooks": {
+      "type": "object",
+      "description": "Hook system configuration overrides.",
+      "additionalProperties": false,
+      "properties": {
+        "dir": {
+          "type": "string",
+          "description": "Path override for the hooks directory."
+        },
+        "timeout": {
+          "type": "integer",
+          "description": "Per-hook execution timeout in seconds. Default: 10.",
+          "minimum": 0
+        },
+        "enabled": {
+          "type": "boolean",
+          "description": "Whether hook execution is enabled. Default: true."
+        }
+      }
     }
   }
 }

internal/entry/validate.go

@@ -11,6 +11,7 @@ import (
 	"github.com/ActiveMemory/ctx/internal/config/flag"
 	"github.com/ActiveMemory/ctx/internal/entity"
 	errAdd "github.com/ActiveMemory/ctx/internal/err/add"
+	"github.com/ActiveMemory/ctx/internal/rc"
 )
 
 // Validate checks that required fields are present for the given entry type.
@@ -31,11 +32,20 @@ func Validate(params entity.EntryParams, examplesFn func(string) string) error {
 		return errAdd.NoContentProvided(params.Type, examples)
 	}
 
-	// Provenance is required for task, decision, and learning.
-	provenance := [][2]string{
-		{flag.PrefixLong + flag.SessionID, params.SessionID},
-		{flag.PrefixLong + flag.Branch, params.Branch},
-		{flag.PrefixLong + flag.Commit, params.Commit},
+	// Provenance is required for task, decision, and learning
+	// unless relaxed per-project via .ctxrc provenance_required.
+	var provenance [][2]string
+	if rc.ProvenanceSessionRequired() {
+		provenance = append(provenance,
+			[2]string{flag.PrefixLong + flag.SessionID, params.SessionID})
+	}
+	if rc.ProvenanceBranchRequired() {
+		provenance = append(provenance,
+			[2]string{flag.PrefixLong + flag.Branch, params.Branch})
+	}
+	if rc.ProvenanceCommitRequired() {
+		provenance = append(provenance,
+			[2]string{flag.PrefixLong + flag.Commit, params.Commit})
 	}
 
 	var extra [][2]string

internal/rc/rc.go

@@ -358,6 +358,51 @@ func Tool() string {
 	return RC().Tool
 }
 
+// ProvenanceSessionRequired reports whether --session-id is
+// required when adding tasks, decisions, and learnings.
+// Returns true (default) unless explicitly disabled in .ctxrc.
+//
+// Returns:
+//   - bool: True if --session-id is required
+func ProvenanceSessionRequired() bool {
+	cfg := RC()
+	if cfg.ProvenanceRequired == nil ||
+		cfg.ProvenanceRequired.SessionID == nil {
+		return true
+	}
+	return *cfg.ProvenanceRequired.SessionID
+}
+
+// ProvenanceBranchRequired reports whether --branch is
+// required when adding tasks, decisions, and learnings.
+// Returns true (default) unless explicitly disabled in .ctxrc.
+//
+// Returns:
+//   - bool: True if --branch is required
+func ProvenanceBranchRequired() bool {
+	cfg := RC()
+	if cfg.ProvenanceRequired == nil ||
+		cfg.ProvenanceRequired.Branch == nil {
+		return true
+	}
+	return *cfg.ProvenanceRequired.Branch
+}
+
+// ProvenanceCommitRequired reports whether --commit is
+// required when adding tasks, decisions, and learnings.
+// Returns true (default) unless explicitly disabled in .ctxrc.
+//
+// Returns:
+//   - bool: True if --commit is required
+func ProvenanceCommitRequired() bool {
+	cfg := RC()
+	if cfg.ProvenanceRequired == nil ||
+		cfg.ProvenanceRequired.Commit == nil {
+		return true
+	}
+	return *cfg.ProvenanceRequired.Commit
+}
+
 // SteeringDir returns the configured steering directory path.
 //
 // Returns the value from .ctxrc steering.dir, or the default

internal/rc/types.go

@@ -58,6 +58,8 @@ import cfgMemory "github.com/ActiveMemory/ctx/internal/config/memory"
 //     cursor, cline, kiro, codex)
 //   - Steering: Steering layer configuration overrides
 //   - Hooks: Hook system configuration overrides
+//   - ProvenanceRequired: Per-project relaxation of
+//     provenance flags for ctx add (default: all required)
 type CtxRC struct {
 	Profile             string                   `yaml:"profile"`
 	Tool                string                   `yaml:"tool"`
@@ -88,6 +90,22 @@ type CtxRC struct {
 	Notify              *NotifyConfig            `yaml:"notify"`
 	Steering            *SteeringRC              `yaml:"steering"`
 	Hooks               *HooksRC                 `yaml:"hooks"`
+	ProvenanceRequired  *ProvenanceConfig        `yaml:"provenance_required"`
+}
+
+// ProvenanceConfig controls which provenance flags are
+// required when adding tasks, decisions, and learnings.
+// Default: all three required. Set individual fields to
+// false to relax per-project.
+//
+// Fields:
+//   - SessionID: Require --session-id (default true)
+//   - Branch: Require --branch (default true)
+//   - Commit: Require --commit (default true)
+type ProvenanceConfig struct {
+	SessionID *bool `yaml:"session_id"`
+	Branch    *bool `yaml:"branch"`
+	Commit    *bool `yaml:"commit"`
 }
 
 // FreshnessFile describes a source file containing technology-dependent

site/home/configuration/index.html

@@ -4205,15 +4205,20 @@ <h3 id="full-reference">Full Reference<a class="headerlink" href="#full-referenc
 </span><span id="__span-1-40"><a id="__codelineno-1-40" name="__codelineno-1-40" href="#__codelineno-1-40"></a><span class="c1">#   timeout: 10</span>
 </span><span id="__span-1-41"><a id="__codelineno-1-41" name="__codelineno-1-41" href="#__codelineno-1-41"></a><span class="c1">#   enabled: true</span>
 </span><span id="__span-1-42"><a id="__codelineno-1-42" name="__codelineno-1-42" href="#__codelineno-1-42"></a><span class="c1">#</span>
-</span><span id="__span-1-43"><a id="__codelineno-1-43" name="__codelineno-1-43" href="#__codelineno-1-43"></a><span class="c1"># priority_order:</span>
-</span><span id="__span-1-44"><a id="__codelineno-1-44" name="__codelineno-1-44" href="#__codelineno-1-44"></a><span class="c1">#   - CONSTITUTION.md</span>
-</span><span id="__span-1-45"><a id="__codelineno-1-45" name="__codelineno-1-45" href="#__codelineno-1-45"></a><span class="c1">#   - TASKS.md</span>
-</span><span id="__span-1-46"><a id="__codelineno-1-46" name="__codelineno-1-46" href="#__codelineno-1-46"></a><span class="c1">#   - CONVENTIONS.md</span>
-</span><span id="__span-1-47"><a id="__codelineno-1-47" name="__codelineno-1-47" href="#__codelineno-1-47"></a><span class="c1">#   - ARCHITECTURE.md</span>
-</span><span id="__span-1-48"><a id="__codelineno-1-48" name="__codelineno-1-48" href="#__codelineno-1-48"></a><span class="c1">#   - DECISIONS.md</span>
-</span><span id="__span-1-49"><a id="__codelineno-1-49" name="__codelineno-1-49" href="#__codelineno-1-49"></a><span class="c1">#   - LEARNINGS.md</span>
-</span><span id="__span-1-50"><a id="__codelineno-1-50" name="__codelineno-1-50" href="#__codelineno-1-50"></a><span class="c1">#   - GLOSSARY.md</span>
-</span><span id="__span-1-51"><a id="__codelineno-1-51" name="__codelineno-1-51" href="#__codelineno-1-51"></a><span class="c1">#   - AGENT_PLAYBOOK.md</span>
+</span><span id="__span-1-43"><a id="__codelineno-1-43" name="__codelineno-1-43" href="#__codelineno-1-43"></a><span class="c1"># provenance_required:  # Relax provenance flags for ctx add</span>
+</span><span id="__span-1-44"><a id="__codelineno-1-44" name="__codelineno-1-44" href="#__codelineno-1-44"></a><span class="c1">#   session_id: true    # Require --session-id (default: true)</span>
+</span><span id="__span-1-45"><a id="__codelineno-1-45" name="__codelineno-1-45" href="#__codelineno-1-45"></a><span class="c1">#   branch: true        # Require --branch (default: true)</span>
+</span><span id="__span-1-46"><a id="__codelineno-1-46" name="__codelineno-1-46" href="#__codelineno-1-46"></a><span class="c1">#   commit: true        # Require --commit (default: true)</span>
+</span><span id="__span-1-47"><a id="__codelineno-1-47" name="__codelineno-1-47" href="#__codelineno-1-47"></a><span class="c1">#</span>
+</span><span id="__span-1-48"><a id="__codelineno-1-48" name="__codelineno-1-48" href="#__codelineno-1-48"></a><span class="c1"># priority_order:</span>
+</span><span id="__span-1-49"><a id="__codelineno-1-49" name="__codelineno-1-49" href="#__codelineno-1-49"></a><span class="c1">#   - CONSTITUTION.md</span>
+</span><span id="__span-1-50"><a id="__codelineno-1-50" name="__codelineno-1-50" href="#__codelineno-1-50"></a><span class="c1">#   - TASKS.md</span>
+</span><span id="__span-1-51"><a id="__codelineno-1-51" name="__codelineno-1-51" href="#__codelineno-1-51"></a><span class="c1">#   - CONVENTIONS.md</span>
+</span><span id="__span-1-52"><a id="__codelineno-1-52" name="__codelineno-1-52" href="#__codelineno-1-52"></a><span class="c1">#   - ARCHITECTURE.md</span>
+</span><span id="__span-1-53"><a id="__codelineno-1-53" name="__codelineno-1-53" href="#__codelineno-1-53"></a><span class="c1">#   - DECISIONS.md</span>
+</span><span id="__span-1-54"><a id="__codelineno-1-54" name="__codelineno-1-54" href="#__codelineno-1-54"></a><span class="c1">#   - LEARNINGS.md</span>
+</span><span id="__span-1-55"><a id="__codelineno-1-55" name="__codelineno-1-55" href="#__codelineno-1-55"></a><span class="c1">#   - GLOSSARY.md</span>
+</span><span id="__span-1-56"><a id="__codelineno-1-56" name="__codelineno-1-56" href="#__codelineno-1-56"></a><span class="c1">#   - AGENT_PLAYBOOK.md</span>
 </span></code></pre></div>
 <!-- drift-check: diff <(grep 'yaml:' internal/rc/types.go | grep -oP '"[a-z_]+"' | tr -d '"' | sort -u | grep -v 'desc\|events\|path\|review_url\|profile\|key_path') <(sed -n '/Option Reference/,/^\*\*Default/p' docs/home/configuration.md | grep -oP '`([a-z_.]+)`' | tr -d '`' | sed 's/notify\.events/notify/' | sort -u | grep -v 'string\|int\|bool\|\[\]') -->
 <h3 id="option-reference">Option Reference<a class="headerlink" href="#option-reference" title="Permanent link">&para;</a></h3>
@@ -4377,6 +4382,24 @@ <h3 id="option-reference">Option Reference<a class="headerlink" href="#option-re
 <td><code>true</code></td>
 <td>Whether hook execution is enabled</td>
 </tr>
+<tr>
+<td><code>provenance_required.session_id</code></td>
+<td><code>bool</code></td>
+<td><code>true</code></td>
+<td>Require <code>--session-id</code> on <code>ctx add</code> for tasks, decisions, learnings</td>
+</tr>
+<tr>
+<td><code>provenance_required.branch</code></td>
+<td><code>bool</code></td>
+<td><code>true</code></td>
+<td>Require <code>--branch</code> on <code>ctx add</code> for tasks, decisions, learnings</td>
+</tr>
+<tr>
+<td><code>provenance_required.commit</code></td>
+<td><code>bool</code></td>
+<td><code>true</code></td>
+<td>Require <code>--commit</code> on <code>ctx add</code> for tasks, decisions, learnings</td>
+</tr>
 </tbody>
 </table>
 <p><strong>Default priority order</strong> (<em>used when <code>priority_order</code> is not set</em>):</p>

site/recipes/knowledge-capture/index.html

@@ -4464,6 +4464,17 @@ <h2 id="tips">Tips<a class="headerlink" href="#tips" title="Permanent link">&par
 <li><strong>Trust the agent's proactive instincts</strong>. Agents trained on the <code>ctx</code> playbook will
   offer to persist context at milestones. A brief "<em>want me to save this?</em>" is
   cheaper than re-discovering the same lesson three sessions later.</li>
+<li>
+<p><strong>Relax provenance per-project</strong> if <code>--session-id</code>, <code>--branch</code>, or <code>--commit</code>
+  are impractical (e.g., manual notes outside an AI session). Add to <code>.ctxrc</code>:</p>
+<div class="language-yaml highlight"><pre><span></span><code><span id="__span-13-1"><a id="__codelineno-13-1" name="__codelineno-13-1" href="#__codelineno-13-1"></a><span class="nt">provenance_required</span><span class="p">:</span>
+</span><span id="__span-13-2"><a id="__codelineno-13-2" name="__codelineno-13-2" href="#__codelineno-13-2"></a><span class="w">  </span><span class="nt">session_id</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">false</span><span class="w">   </span><span class="c1"># allow entries without --session-id</span>
+</span><span id="__span-13-3"><a id="__codelineno-13-3" name="__codelineno-13-3" href="#__codelineno-13-3"></a><span class="w">  </span><span class="nt">branch</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">true</span><span class="w">        </span><span class="c1"># still require --branch</span>
+</span><span id="__span-13-4"><a id="__codelineno-13-4" name="__codelineno-13-4" href="#__codelineno-13-4"></a><span class="w">  </span><span class="nt">commit</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">true</span><span class="w">        </span><span class="c1"># still require --commit</span>
+</span></code></pre></div>
+<p>Default is all three required. Only human config relaxes:
+Agents cannot bypass, and that's by design.</p>
+</li>
 </ul>
 <h2 id="next-up">Next Up<a class="headerlink" href="#next-up" title="Permanent link">&para;</a></h2>
 <p><strong><a href="../task-management/">Tracking Work Across Sessions →</a></strong>: