@deftai/directive-content 0.66.2 → 0.68.0

package/templates/embed_test.go

@@ -2,6 +2,7 @@ package templates
 
 import (
 	"os"
+	"strings"
 	"testing"
 )
 
@@ -34,3 +35,29 @@ func TestAgentsEntryNonEmpty(t *testing.T) {
 		t.Fatal("AgentsEntry is empty -- templates/agents-entry.md embed is broken")
 	}
 }
+
+// TestAgentsConsumerHeaderMatchesFile asserts the embedded consumer header equals
+// templates/agents-consumer-header.md on disk (#2065).
+func TestAgentsConsumerHeaderMatchesFile(t *testing.T) {
+	onDisk, err := os.ReadFile("agents-consumer-header.md")
+	if err != nil {
+		t.Fatalf("could not read templates/agents-consumer-header.md: %v", err)
+	}
+	if AgentsConsumerHeader != string(onDisk) {
+		t.Errorf("embedded AgentsConsumerHeader drift from templates/agents-consumer-header.md:\n"+
+			"embedded len=%d, on-disk len=%d",
+			len(AgentsConsumerHeader), len(onDisk))
+	}
+}
+
+func TestAgentsConsumerHeaderOmitsRetiredSections(t *testing.T) {
+	if strings.Contains(AgentsConsumerHeader, "## Status") {
+		t.Error("consumer header must not scaffold ## Status (#2065)")
+	}
+	if strings.Contains(AgentsConsumerHeader, "## Known Issues") {
+		t.Error("consumer header must not scaffold ## Known Issues (#2065)")
+	}
+	if !strings.Contains(AgentsConsumerHeader, "## Session orientation") {
+		t.Fatal("consumer header must include Session orientation pointer")
+	}
+}

package/tools/package-manager-network.md

@@ -0,0 +1,29 @@
+# Package-Manager Network Access (#2182)
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ⊗=MUST NOT, ?=MAY.
+
+**⚠️ See also**: [main.md](../../main.md) | [tools/taskfile.md](./taskfile.md) | [scm/github.md](../scm/github.md)
+
+**Scope:** How Directive's own tooling (session ritual, doctor, read-only flows) treats npm/pnpm registry access as an explicit, security-sensitive, opt-in operation. Applies to Directive's own code, not to a consumer project's own build/install scripts.
+
+## Why this exists
+
+Directive runs against arbitrary repositories, including private monorepos with private package scopes, workspace dependencies, proxy configuration, and authenticated registries. If Directive silently invokes `npm`/`pnpm` during session startup or health checks, it may contact public or private registries, disclose package names/scopes/dependency-graph shape over the network, pick up unintended project/user registry configuration, or trip sandboxed network-approval prompts for work that never needed dependency resolution. Registry traffic itself is sensitive even when no secrets are printed.
+
+## Rules
+
+- ! Read-only, session-start, and session-ritual flows (`deft session:start`, `deft verify:session-ritual`, `deft verify:tools`) MUST perform no npm/pnpm registry access. Tool-presence probes MUST use PATH lookups (`which`/`accessSync`) or `--version` checks, never a subcommand that can resolve dependencies or query a registry.
+- ! `deft doctor` MUST default to an OFFLINE tier: no check in the default run may contact an npm/pnpm registry. The one check that can (`payload-staleness`, which resolves the latest framework version via `git ls-remote` and falls back to `npm view <package> version`) is gated behind the explicit `--network` flag and is skipped by default with a pointer to that flag.
+- ! Before a network-gated check runs, `deft doctor --network` MUST print a disclosure line naming the tool and registry class it may contact (e.g. "may contact your git remote and, as a fallback, the npm registry") BEFORE any network call is attempted.
+- ! Any future doctor check, session step, or read-only command that needs to invoke `npm`/`pnpm` in a way that can reach a registry MUST follow the same pattern: explicit flag or subcommand, disclosed registry class before the call, and offline by default.
+- ~ Where a package-manager operation is unavoidable in an explicitly-invoked flow (e.g. a release or install workflow that legitimately needs to fetch packages), prefer offline/frozen modes (`--offline`, `--prefer-offline`, `--frozen-lockfile`) when the operation only needs to validate local state rather than resolve fresh metadata.
+- ⊗ MUST NOT invoke `npm`/`pnpm` subcommands that can contact a registry from any code path reachable by `session:start`, `verify:session-ritual`, `verify:tools`, or the default `deft doctor` invocation.
+- ⊗ MUST NOT ship a new registry-reaching check without adding it to this doc and gating it the same way.
+
+## Non-goals
+
+This does not ban dependency installation or registry verification from explicit build/check/release workflows (e.g. `task build`, CI install steps) -- those are intentionally invoked and their network use is expected. It does not require supporting every private registry provider, and it does not replace npm/pnpm lockfile or provenance checks where they are intentionally invoked.
+
+## Reference implementation
+
+`packages/core/src/doctor/payload-staleness.ts` is the only code path in the TS engine that shells out to `npm` (`npm view`) or performs a git-remote network call for framework-currency checks; `packages/core/src/doctor/main.ts` gates it behind `--network` and prints the disclosure line first. `packages/core/src/session/session-start.ts` and `packages/core/src/verify-env/verify-tools.ts` perform no package-manager network access at all -- tool presence is resolved via PATH probing only.