refactor: enforce package boundaries and eliminate recorded dependency debt

.github/workflows/arch-audit.yml

@@ -62,19 +62,6 @@ jobs:
           go list -m -u all 2>/dev/null | grep '\[' >> report.md || echo "All dependencies up to date" >> report.md
           echo '```' >> report.md
 
-      - name: Circular dependency check
-        run: |
-          echo "## Circular Dependencies" >> report.md
-          go list -f '{{.ImportPath}} {{join .Imports " "}}' ./... | \
-            go run golang.org/x/tools/cmd/digraph@v0.31.0 scc 2>&1 | tee cycles.txt
-          if [ -s cycles.txt ]; then
-            echo '```' >> report.md
-            cat cycles.txt >> report.md
-            echo '```' >> report.md
-          else
-            echo "No circular dependencies detected." >> report.md
-          fi
-
       - name: E2E coverage gaps
         run: |
           echo "## E2E Coverage Gaps" >> report.md

.github/workflows/ci.yml

@@ -119,6 +119,8 @@ jobs:
         env:
           QUALITY_GATE_CHANGED_FROM: ${{ github.event.pull_request.base.sha || github.event.before || 'origin/main' }}
         run: echo "QUALITY_GATE_CHANGED_FROM=$(bash scripts/resolve-changed-from.sh)" >> "$GITHUB_ENV"
+      - name: Enforce layering ratchet
+        run: bash scripts/check-layering-ratchet.sh "$QUALITY_GATE_CHANGED_FROM"
       - name: Run golangci-lint
         run: go run github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.1.6 run --new-from-rev="$QUALITY_GATE_CHANGED_FROM"
       - name: Run source-contract lint guards (lintcheck)

AGENTS.md

@@ -62,10 +62,21 @@ Both notices recommend the same fix command: `lark-cli update`. The skills notic
 | `internal/credential/` | Credential provider chain (extension → default) |
 | `extension/credential/` | Plugin-facing credential interfaces and env provider |
 | `internal/client/client.go` | APIClient: DoSDKRequest, DoStream |
-| `internal/core/config.go` | Multi-profile config loading/saving |
+| `brand/` | Brand (feishu/lark) and its endpoint hosts — repo root, so `extension/` may import it |
+| `internal/workspace/` | Workspace detection plus the config and runtime directory paths |
+| `internal/identity/` | The `--as` identity (user/bot) and the strict-mode policy |
+| `internal/config/config.go` | Multi-profile config loading/saving |
 | `internal/vfs/` | Filesystem abstraction (use `vfs.*` instead of `os.*`) |
 | `internal/validate/path.go` | Path safety validation |
 
+`internal/core` is gone. Besides the four packages above it also became
+`internal/secret` (app secret storage and resolution) and `internal/risk` (the
+read / write / high-risk-write vocabulary). Import the narrowest one you need:
+`brand`, `internal/workspace`, `internal/identity`, `internal/secret` and
+`internal/risk` do not import each other — only `internal/config` sits on top of
+them — so asking for a config directory no longer drags in keychain, i18n and
+validate.
+
 ## Who Uses This CLI
 
 This CLI's primary consumers include AI agents (Claude Code, Cursor, Gemini CLI). Your code is read by machines — error messages, output format, and flag design all directly affect agent success rates.

Makefile

@@ -49,6 +49,7 @@ fmt-check:
 
 script-test:
 	bash scripts/resolve-changed-from.test.sh
+	bash scripts/check-layering-ratchet.test.sh
 	bash scripts/ci-workflow.test.sh
 	bash scripts/semantic-review-workflow.test.sh
 	$(NODE) --test scripts/e2e_domains.test.js scripts/fetch_e2e_tat.test.js scripts/install.test.js scripts/release-preflight.test.js scripts/semantic-review-verify-artifact.test.js scripts/pr-quality-summary.test.js scripts/semantic-review-publish.test.js scripts/ci-quality-summary-publish.test.js

internal/core/types.go → brand/brand.go

@@ -1,27 +1,27 @@
 // Copyright (c) 2026 Lark Technologies Pte. Ltd.
 // SPDX-License-Identifier: MIT
 
-package core
+package brand
 
 import "strings"
 
-// LarkBrand represents the Lark platform brand.
+// Brand represents the Lark platform brand.
 // "feishu" targets China-mainland, "lark" targets international.
-// ParseBrand and ResolveEndpoints map unrecognized values to BrandFeishu.
-type LarkBrand string
+// ParseBrand and ResolveEndpoints map unrecognized values to Feishu.
+type Brand string
 
 const (
-	BrandFeishu LarkBrand = "feishu"
-	BrandLark   LarkBrand = "lark"
+	Feishu Brand = "feishu"
+	Lark   Brand = "lark"
 )
 
 // ParseBrand normalizes a brand string (case-insensitive, whitespace-tolerant);
-// anything other than "lark" normalizes to BrandFeishu.
-func ParseBrand(value string) LarkBrand {
+// anything other than "lark" normalizes to Feishu.
+func ParseBrand(value string) Brand {
 	if strings.ToLower(strings.TrimSpace(value)) == "lark" {
-		return BrandLark
+		return Lark
 	}
-	return BrandFeishu
+	return Feishu
 }
 
 // OAuthTokenV3Path is the unified OAuth 2.0 Token Endpoint path on the accounts
@@ -40,9 +40,9 @@ type Endpoints struct {
 
 // ResolveEndpoints resolves endpoint URLs for the brand, normalizing its
 // input so stored values with unusual casing still resolve correctly.
-func ResolveEndpoints(brand LarkBrand) Endpoints {
+func ResolveEndpoints(brand Brand) Endpoints {
 	switch ParseBrand(string(brand)) {
-	case BrandLark:
+	case Lark:
 		return Endpoints{
 			Open:     "https://open.larksuite.com",
 			Accounts: "https://accounts.larksuite.com",
@@ -60,6 +60,6 @@ func ResolveEndpoints(brand LarkBrand) Endpoints {
 }
 
 // ResolveOpenBaseURL returns the Open API base URL for the given brand.
-func ResolveOpenBaseURL(brand LarkBrand) string {
+func ResolveOpenBaseURL(brand Brand) string {
 	return ResolveEndpoints(brand).Open
 }

internal/core/types_test.go → brand/brand_test.go

@@ -1,12 +1,12 @@
 // Copyright (c) 2026 Lark Technologies Pte. Ltd.
 // SPDX-License-Identifier: MIT
 
-package core
+package brand
 
 import "testing"
 
 func TestResolveEndpoints_Feishu(t *testing.T) {
-	ep := ResolveEndpoints(BrandFeishu)
+	ep := ResolveEndpoints(Feishu)
 	if ep.Open != "https://open.feishu.cn" {
 		t.Errorf("Open = %q, want feishu.cn", ep.Open)
 	}
@@ -22,7 +22,7 @@ func TestResolveEndpoints_Feishu(t *testing.T) {
 }
 
 func TestResolveEndpoints_Lark(t *testing.T) {
-	ep := ResolveEndpoints(BrandLark)
+	ep := ResolveEndpoints(Lark)
 	if ep.Open != "https://open.larksuite.com" {
 		t.Errorf("Open = %q, want larksuite.com", ep.Open)
 	}
@@ -50,26 +50,26 @@ func TestResolveEndpoints_EmptyDefaultsToFeishu(t *testing.T) {
 }
 
 func TestResolveOpenBaseURL(t *testing.T) {
-	if got := ResolveOpenBaseURL(BrandFeishu); got != "https://open.feishu.cn" {
+	if got := ResolveOpenBaseURL(Feishu); got != "https://open.feishu.cn" {
 		t.Errorf("ResolveOpenBaseURL(feishu) = %q", got)
 	}
-	if got := ResolveOpenBaseURL(BrandLark); got != "https://open.larksuite.com" {
+	if got := ResolveOpenBaseURL(Lark); got != "https://open.larksuite.com" {
 		t.Errorf("ResolveOpenBaseURL(lark) = %q", got)
 	}
 }
 
 func TestParseBrand(t *testing.T) {
 	cases := []struct {
 		in   string
-		want LarkBrand
+		want Brand
 	}{
-		{"", BrandFeishu},
-		{"feishu", BrandFeishu},
-		{"lark", BrandLark},
-		{"LARK", BrandLark},
-		{" lark ", BrandLark},
-		{"Lark", BrandLark},
-		{"xyz", BrandFeishu},
+		{"", Feishu},
+		{"feishu", Feishu},
+		{"lark", Lark},
+		{"LARK", Lark},
+		{" lark ", Lark},
+		{"Lark", Lark},
+		{"xyz", Feishu},
 	}
 	for _, c := range cases {
 		if got := ParseBrand(c.in); got != c.want {
@@ -83,11 +83,11 @@ func TestParseBrand(t *testing.T) {
 // unusual casing or whitespace still resolve to their intended endpoints.
 func TestResolveEndpoints_NormalizesBrand(t *testing.T) {
 	for _, raw := range []string{"LARK", " lark ", "Lark"} {
-		if got := ResolveEndpoints(LarkBrand(raw)).Open; got != "https://open.larksuite.com" {
+		if got := ResolveEndpoints(Brand(raw)).Open; got != "https://open.larksuite.com" {
 			t.Errorf("ResolveEndpoints(%q).Open = %q, want the lark endpoint", raw, got)
 		}
 	}
-	if got := ResolveEndpoints(LarkBrand("unexpected")).Open; got != "https://open.feishu.cn" {
+	if got := ResolveEndpoints(Brand("unexpected")).Open; got != "https://open.feishu.cn" {
 		t.Errorf("ResolveEndpoints(unexpected).Open = %q, want the feishu default", got)
 	}
 }

cmd/api/api.go

@@ -13,7 +13,8 @@ import (
 	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/client"
 	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/core"
+	configpkg "github.com/larksuite/cli/internal/config"
+	"github.com/larksuite/cli/internal/identity"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/validate"
 	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
@@ -33,7 +34,7 @@ type APIOptions struct {
 	// Flags
 	Params    string
 	Data      string
-	As        core.Identity
+	As        identity.Identity
 	Output    string
 	PageAll   bool
 	PageSize  int
@@ -87,7 +88,7 @@ Examples:
 			opts.Path = args[1]
 			opts.Cmd = cmd
 			opts.Ctx = cmd.Context()
-			opts.As = core.Identity(asStr)
+			opts.As = identity.Identity(asStr)
 			if runF != nil {
 				return runF(opts)
 			}
@@ -304,7 +305,7 @@ func apiRun(opts *APIOptions) error {
 	return nil
 }
 
-func apiDryRun(f *cmdutil.Factory, request client.RawApiRequest, config *core.CliConfig, opts *APIOptions) error {
+func apiDryRun(f *cmdutil.Factory, request client.RawApiRequest, config *configpkg.CliConfig, opts *APIOptions) error {
 	return cmdutil.PrintDryRun(request, config, dryRunOutputOptions(f, opts))
 }
 

cmd/api/api_paginate_test.go

@@ -13,11 +13,13 @@ import (
 	"net/http"
 	"testing"
 
+	"github.com/larksuite/cli/brand"
 	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/client"
 	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/core"
+	configpkg "github.com/larksuite/cli/internal/config"
 	"github.com/larksuite/cli/internal/httpmock"
+	"github.com/larksuite/cli/internal/identity"
 	"github.com/larksuite/cli/internal/output"
 )
 
@@ -44,10 +46,10 @@ func newAPIPaginateTestHarness(t *testing.T) (*client.APIClient, *bytes.Buffer,
 	output.PendingNotice = nil
 	t.Cleanup(func() { output.PendingNotice = previousNotice })
 
-	config := &core.CliConfig{
+	config := &configpkg.CliConfig{
 		AppID:     "test-app",
 		AppSecret: "test-secret",
-		Brand:     core.BrandFeishu,
+		Brand:     brand.Feishu,
 	}
 	f, out, errOut, reg := cmdutil.TestFactory(t, config)
 	ac, err := f.NewAPIClientWithConfig(config)
@@ -62,7 +64,7 @@ func apiPaginateRequest() client.RawApiRequest {
 	return client.RawApiRequest{
 		Method: "GET",
 		URL:    "/open-apis/test/v1/items",
-		As:     core.AsBot,
+		As:     identity.AsBot,
 	}
 }