Part 10: Advanced Process Data API

Throughout this tutorial, you have used process:overview, process:sources, process:tags, process:rules, process:stubs, and commands like dep-tree, list, and arch context. This section covers advanced queries you have not seen yet.

10.1 Commands you already know

Command	First Used	Purpose
`process:overview`	Part 2	Project health summary
`process:sources`	Part 3	Source file inventory
`process:tags`	Part 4	Tag usage distribution
`process:list`	Part 5	Pattern listing with filters
`dep-tree`	Part 5	Recursive dependency chains
`arch context`	Part 5	Bounded context listing
`process:rules`	Part 7	Business rules from Gherkin
`process:stubs`	Part 8	Design stub resolution status

10.2 Architecture neighborhood

See everything a pattern touches — uses, used-by, same-context peers:

npm run process:query -- arch neighborhood UserService

{
  "success": true,
  "data": {
    "pattern": "UserService",
    "context": "identity",
    "role": "service",
    "layer": "application",
    "uses": [
      {
        "name": "EventStore",
        "status": "deferred",
        "archRole": "infrastructure",
        "archContext": "persistence",
        "file": "src/sample-sources/event-store.ts"
      }
    ],
    "usedBy": [
      {
        "name": "AuthHandler",
        "status": "roadmap",
        "archRole": "service",
        "archContext": "identity",
        "file": "src/sample-sources/auth-handler.ts"
      }
    ],
    "dependsOn": [
      {
        "name": "EventStore",
        "status": "deferred",
        "archRole": "infrastructure",
        "archContext": "persistence",
        "file": "src/sample-sources/event-store.ts"
      }
    ],
    "enables": [
      {
        "name": "AuthHandler",
        "status": "roadmap",
        "archRole": "service",
        "archContext": "identity",
        "file": "src/sample-sources/auth-handler.ts"
      }
    ],
    "sameContext": [
      {
        "name": "NotificationService",
        "status": "roadmap",
        "archRole": "service",
        "archContext": "identity",
        "file": "src/stubs/notification-service.stub.ts"
      },
      {
        "name": "AuthHandler",
        "status": "roadmap",
        "archRole": "service",
        "archContext": "identity",
        "file": "src/sample-sources/auth-handler.ts"
      }
    ],
    "implements": [],
    "implementedBy": ["UserRegistration"]
  }
}

The neighborhood view shows the full connectivity for UserService: it uses EventStore (in the persistence context), is used by AuthHandler (same identity context), shares the identity context with NotificationService and AuthHandler, and is implemented by the UserRegistration Gherkin spec.

10.3 Blocking analysis

Find patterns stuck on incomplete dependencies:

npm run process:query -- arch blocking

{
  "success": true,
  "data": [
    { "pattern": "UserService", "status": "active", "blockedBy": ["EventStore"] },
    { "pattern": "AuthHandler", "status": "roadmap", "blockedBy": ["UserService"] },
    { "pattern": "Authentication", "status": "roadmap", "blockedBy": ["UserRegistration"] }
  ]
}

Three blocking chains are visible:

UserService is active but blocked by EventStore (which is deferred)
AuthHandler is planned but blocked by UserService
Authentication spec is blocked by UserRegistration spec

10.4 Dangling references

Find broken references to nonexistent pattern names:

npm run process:query -- arch dangling

{
  "success": true,
  "data": []
}

Empty array — all pattern references resolve correctly. If you had a typo like @libar-docs-uses UserServce, it would appear here.

10.5 Full pattern detail

Get complete metadata for a single pattern:

npm run process:query -- pattern UserService

{
  "success": true,
  "data": {
    "id": "pattern-9e96b484",
    "name": "UserService",
    "category": "core",
    "directive": {
      "tags": [
        "@libar-docs-pattern", "@libar-docs-status", "@libar-docs-core",
        "@libar-docs-arch-role", "@libar-docs-arch-context", "@libar-docs-arch-layer",
        "@libar-docs-used-by", "@libar-docs-uses", "@libar-docs-extract-shapes",
        "@libar-docs-phase", "@libar-docs-release", "@libar-docs-brief",
        "@libar-docs-usecase", "@libar-docs-usecase", "@libar-docs-usecase",
        "@libar-docs-quarter", "@libar-docs-depends-on", "@libar-docs-see-also"
      ],
      "patternName": "UserService",
      "status": "active",
      "isCore": true,
      "useCases": [
        "Register a new user account via the signup form",
        "Look up a user by ID for profile display",
        "Deactivate a compromised user account"
      ],
      "uses": ["EventStore"],
      "usedBy": ["AuthHandler"],
      "phase": 1,
      "brief": "Core user lifecycle management service",
      "dependsOn": ["EventStore"],
      "seeAlso": ["AuthHandler", "EventStore"],
      "archRole": "service",
      "archContext": "identity",
      "archLayer": "application",
      "extractShapes": ["UserRecord"]
    },
    "source": { "file": "src/sample-sources/user-service.ts", "lines": [3, 32] },
    "extractedShapes": [
      {
        "name": "UserRecord",
        "kind": "interface",
        "sourceText": "interface UserRecord {\n  id: string;\n  email: string;\n  active: boolean;\n}",
        "lineNumber": 35,
        "exported": true,
        "group": "reference-sample"
      }
    ],
    "relationships": {
      "dependsOn": ["EventStore"],
      "enables": ["AuthHandler"],
      "uses": ["EventStore"],
      "usedBy": ["AuthHandler"],
      "implementedBy": [
        { "name": "UserRegistration", "file": "src/specs/user-registration.feature" }
      ],
      "seeAlso": ["AuthHandler", "EventStore"]
    }
  }
}

(Trimmed for brevity — the full output includes additional fields like code, exports, deliverables, and whenToUse.)

10.6 Output modifiers

Any JSON-outputting command supports these composable modifiers:

Flag	Effect	Example
`--names-only`	Return array of pattern name strings	`list --names-only`
`--count`	Return integer count	`list --status roadmap --count`
`--fields name,status,phase`	Selected fields only	`list --fields patternName,status`
`--full`	Bypass summarization, return raw data	`list --full`

# How many roadmap patterns?
npm run process:query -- list --status roadmap --count

{
  "success": true,
  "data": 4
}

# Just the names of all patterns
npm run process:query -- list --names-only

{
  "success": true,
  "data": [
    "NotificationService",
    "NotificationConfig",
    "NotificationResult",
    "UserService",
    "UserRecord",
    "EventStore",
    "DomainEvent",
    "AuthHandler",
    "AuthResult",
    "UserRegistration",
    "Authentication"
  ]
}

10.7 Final overview

npm run process:overview

=== PROGRESS ===
11 patterns (0 completed, 1 active, 10 planned) = 0%

=== ACTIVE PHASES ===
Phase 1: Inception (1 active)

=== BLOCKING ===
UserService blocked by: EventStore
AuthHandler blocked by: UserService
Authentication blocked by: UserRegistration

Recap: Part 10

arch neighborhood shows a pattern’s full connectivity (uses, usedBy, dependsOn, enables, sameContext, implementedBy)
arch blocking surfaces dependency bottlenecks
arch dangling catches broken references
pattern <name> returns complete JSON detail for a single pattern
Output modifiers (--names-only, --count, --fields, --full) shape any query’s response

Results Summary

Final counts

Metric	Count
Total patterns	11
Source files	6 (3 TypeScript + 2 Gherkin + 1 stub)
Generated files	26
Business rules	5
Blocking chains	3
Bounded contexts	2 (identity, persistence)
Categories	5 (API, Core, DDD, Infra, Shape)
Phases in use	3 (Inception, Elaboration, Session)

All 11 patterns

Pattern	Source	Category	Status
UserService	TypeScript	Core	active
UserRecord	TypeScript (shape)	Shape	planned
AuthHandler	TypeScript	API	roadmap
AuthResult	TypeScript (shape)	Shape	planned
EventStore	TypeScript	Infra	deferred
DomainEvent	TypeScript (shape)	Shape	planned
UserRegistration	Gherkin	DDD	roadmap
Authentication	Gherkin	API	roadmap
NotificationService	Stub	Infra	roadmap
NotificationConfig	Stub (shape)	Shape	planned
NotificationResult	Stub (shape)	Shape	planned

All 26 generated files

Generator	Files
patterns	`PATTERNS.md`, `patterns/notification-service.md`, `patterns/notification-config.md`, `patterns/notification-result.md`, `patterns/user-service.md`, `patterns/user-record.md`, `patterns/event-store.md`, `patterns/domain-event.md`, `patterns/auth-handler.md`, `patterns/auth-result.md`, `patterns/user-registration.md`, `patterns/authentication.md`
roadmap	`ROADMAP.md`, `phases/phase-01-inception.md`, `phases/phase-02-elaboration.md`, `phases/phase-03-session.md`
reference-docs	`docs/IDENTITY-PERSISTENCE-REFERENCE.md`, `_claude-md/reference/identity-persistence-reference.md`
overview-rdm	`OVERVIEW.md`
architecture	`ARCHITECTURE.md`
business-rules	`BUSINESS-RULES.md`, `business-rules/platform.md`
taxonomy	`TAXONOMY.md`, `taxonomy/categories.md`, `taxonomy/metadata-tags.md`, `taxonomy/format-types.md`

All 10 parts executed successfully with zero failures.

Issues & Improvements for Next Revision

The following discrepancies were found between the original tutorial (TUTORIAL.md) and the actual CLI output from the test run. Each is marked with a severity level:

[MINOR] — Formatting or display differences that do not affect correctness
[CONTENT] — Wrong counts, data values, or misleading information
[STRUCTURE] — Organizational issues affecting tutorial flow

Issue 1: `=== DATA API ===` section in overview output `[MINOR]`

Location: TUTORIAL.md Parts 2, 3, 4, 5, 7 — all process:overview expected outputs

Expected (tutorial): Overview output shows only === PROGRESS ===, === ACTIVE PHASES ===, and === BLOCKING === sections.

Actual: Every process:overview call also appends a === DATA API -- Use Instead of Explore Agents === help reference section listing available subcommands (overview, context, scope-validate, dep-tree, list, stubs, files, rules, arch blocking).

Impact: The tutorial outputs appear truncated. Readers running the commands will see extra output not shown in the tutorial.

Suggested fix: Either include the DATA API section in the first overview output (Part 2) with a note that it appears on every call, or add a one-line note after the first overview output explaining the omitted section. Subsequent outputs can omit it with “(DATA API help reference omitted)”.

Issue 2: `arch context` identity count and pattern list `[CONTENT]`

Location: TUTORIAL.md Part 5, section 5.4 — arch context expected output

Expected (tutorial):

{ "context": "identity", "count": 3, "patterns": ["UserService", "AuthHandler", "..."] }

Actual:

{ "context": "identity", "count": 2, "patterns": ["UserService", "AuthHandler"] }

Impact: The tutorial claims count 3 with a trailing "..." suggesting more patterns. The actual count is 2 because shape patterns (UserRecord, AuthResult, DomainEvent) do not have @libar-docs-arch-context tags and are not included in bounded context groupings. The "..." is misleading — it implies additional patterns exist.

Suggested fix: Change the expected output to show count 2 with patterns ["UserService", "AuthHandler"]. Add a note explaining that only patterns with explicit @libar-docs-arch-context tags appear in context groupings.

Issue 3: Part 7 pattern count is wrong `[CONTENT]`

Location: TUTORIAL.md Part 7, section 7.7 — overview expected output and checkpoint

Expected (tutorial):

11 patterns (0 completed, 1 active, 10 planned) = 0%

The checkpoint also says “npm run process:overview shows 11 patterns”.

Actual:

8 patterns (0 completed, 1 active, 7 planned) = 0%

Impact: The tutorial claims 11 patterns after adding Gherkin specs, but the actual count is 8. The 11 count is only reached in Part 8 after adding the stub file (which contributes NotificationService + NotificationConfig + NotificationResult = 3 more patterns: 8 + 3 = 11). This is a factual error in the tutorial.

Suggested fix: Change the Part 7.7 expected output to show 8 patterns. Update the checkpoint to match. Move the “11 patterns” milestone to Part 8 or Part 9 where it actually occurs.

Issue 4: Stubs output shows 3 entries, not 1 `[CONTENT]`

Location: TUTORIAL.md Part 8, section 8.3 — process:stubs expected output

Expected (tutorial): Shows only 1 stub entry for NotificationService with targetPath, since, and targetExists fields.

Actual: Shows 3 entries — NotificationConfig, NotificationResult, and NotificationService. The shape patterns from the stub file are also tracked as separate stub entries. NotificationConfig and NotificationResult have empty targetPath strings and no since field.

Impact: Readers will see unexpected additional entries. The tutorial explanation only discusses the NotificationService entry.

Suggested fix: Show all 3 entries in the expected output. Add a note explaining that shape patterns defined in stub files also appear as separate stub entries, and that only the main pattern (NotificationService) has targetPath and since metadata.

Issue 5: `list --status roadmap` output not shown `[MINOR]`

Location: TUTORIAL.md Part 5, section 5.4 — list --status roadmap command

Expected (tutorial): The tutorial shows the command but provides no expected output, just “Shows your planned work backlog — all patterns with status roadmap.”

Actual: Returns only AuthHandler. EventStore has status deferred, not roadmap, so it is correctly excluded.

Impact: Minor — the tutorial does not make an incorrect claim, but the missing expected output leaves the reader guessing. The implicit suggestion that multiple patterns would appear is slightly misleading since only AuthHandler is roadmap at that point.

Suggested fix: Add the actual JSON output showing the single AuthHandler entry. Add a note that EventStore is deferred (not roadmap) and therefore excluded.

Issue 6: `docs:all` output format differs from tutorial `[MINOR]`

Location: TUTORIAL.md Part 9, section 9.4 — docs:all expected output

Expected (tutorial):

Running generator: patterns        → PATTERNS.md + 11 detail pages
Running generator: roadmap         → ROADMAP.md + 3 phase pages
...
✅ 26 files written

(Simplified summary with arrow notation)

Actual: The output is more verbose, showing scan/extract progress lines at the top (Using sources from delivery-process.config.ts..., Scanning source files..., Found 11 patterns, Extracting patterns..., Extracted 11 patterns) followed by individual file checkmarks per generator (each file gets its own ✓ line), ending with ✅ Documentation generation complete! 26 files written.

Impact: The tutorial shows a simplified/stylized output format that does not match reality. Readers may be confused when they see different formatting.

Suggested fix: Replace the expected output with the actual verbatim output showing the scan preamble and individual file checkmarks. This is more informative and avoids reader confusion.

Issue 7: `docs:list` generator list is incomplete `[MINOR]`

Location: TUTORIAL.md Part 9, section 9.5 — generator listing

Expected (tutorial): Mentions reference-docs and product-area-docs generators. Lists some additional generators in a paragraph at the end.

Actual: docs:list returns 20 generators. Several generators not mentioned in the tutorial are present: doc-from-decision, session, session-plan, session-findings, planning-checklist, traceability. The tutorial mentions product-area-docs which does not appear in the actual list.

Impact: Minor inaccuracy. The product-area-docs reference may confuse readers who try to use it. The unlisted generators are available but undocumented in the tutorial.

Suggested fix: Remove the product-area-docs reference (it does not exist). Add the full docs:list output or at minimum list all 20 generator names. Group them into “used in this tutorial” and “available for advanced workflows”.

Issue 8: `PATTERNS.md` categories include “DDD” `[CONTENT]`

Location: TUTORIAL.md Part 6, section 6.1 — description of PATTERNS.md

Expected (tutorial): Patterns are organized by “API, Core, Infra, Shape” (4 categories).

Actual: PATTERNS.md shows 5 categories: “API, Core, DDD, Infra, Shape”. The DDD category is assigned to UserRegistration. Despite the Gherkin file using @libar-docs-core, the system classifies UserRegistration under DDD.

Impact: The tutorial does not mention DDD as a category for the libar-generic preset and states only 3 categories exist (core, api, infra). The appearance of a DDD category may confuse readers who expect only the documented categories.

Suggested fix: Investigate why UserRegistration is classified as DDD despite using @libar-docs-core. If this is expected behavior (perhaps Gherkin features with @libar-docs-implements get auto-classified), document it. Update the category listing in the tutorial to include DDD or explain when it appears.

Appendix A: Full npm Scripts Reference

Script	Description
Process Data API
`npm run process:query -- <cmd>`	Run any process-api subcommand
`npm run process:overview`	Project health summary
`npm run process:status`	Pattern counts and completion %
`npm run process:list`	List all patterns
`npm run process:tags`	Tag usage report
`npm run process:sources`	Source file inventory
`npm run process:rules`	Business rules from Gherkin
`npm run process:stubs`	Design stubs with resolution status
Doc Generators
`npm run docs:all`	Generate all doc types (7 generators)
`npm run docs:patterns`	Pattern registry + detail pages
`npm run docs:roadmap`	Roadmap by phase
`npm run docs:reference`	Bespoke reference docs
`npm run docs:overview`	Project overview
`npm run docs:architecture`	Architecture diagrams
`npm run docs:business-rules`	Business rules + invariants
`npm run docs:taxonomy`	Tag taxonomy reference
`npm run docs:list`	List all available generators
Linting
`npm run lint:patterns`	Check annotation quality
`npm run lint:validate`	Cross-source validation (TS + Gherkin)

Appendix B: Tag Quick Reference

Required Tags

Tag	Format	Example
`@libar-docs`	file opt-in (standalone JSDoc or Gherkin tag)	`/** @libar-docs */`
`@libar-docs-pattern`	`Name`	`@libar-docs-pattern UserService`

Status FSM

roadmap → active → completed
  ↓         ↓
deferred  roadmap (blocked)

Relationship Arrows in Diagrams

Tag	Arrow Style	Meaning
`uses` / `used-by`	`-->` solid	Direct dependency
`depends-on` / `enables`	`-.->` dashed	Roadmap sequencing
`implements`	`..->` dotted	Spec realizes code
`extends`	`-->>` open	Generalization

Tag Syntax by Context

Context	Syntax	Example
TypeScript JSDoc	Space-separated	`@libar-docs-pattern UserService`
Gherkin tags	Colon-separated	`@libar-docs-pattern:UserService`

All Tag Groups

Identity & Status: pattern, status, core/api/infra

Architecture: arch-role, arch-context, arch-layer

Enrichment: brief, usecase, quarter, phase, release

Shapes: extract-shapes, shape

Relationships: uses, used-by, depends-on, enables, see-also, implements

Stubs: target, since

Part 10: Advanced Process Data API

10.1 Commands you already know

10.2 Architecture neighborhood

10.3 Blocking analysis

10.4 Dangling references

10.5 Full pattern detail

10.6 Output modifiers

10.7 Final overview

Recap: Part 10

Results Summary

Final counts

All 11 patterns

All 26 generated files

Issues & Improvements for Next Revision

Issue 1: === DATA API === section in overview output [MINOR]

Issue 2: arch context identity count and pattern list [CONTENT]

Issue 3: Part 7 pattern count is wrong [CONTENT]

Issue 4: Stubs output shows 3 entries, not 1 [CONTENT]

Issue 5: list --status roadmap output not shown [MINOR]

Issue 6: docs:all output format differs from tutorial [MINOR]

Issue 7: docs:list generator list is incomplete [MINOR]

Issue 8: PATTERNS.md categories include “DDD” [CONTENT]

Appendix A: Full npm Scripts Reference

Appendix B: Tag Quick Reference

Required Tags

Status FSM

Relationship Arrows in Diagrams

Tag Syntax by Context

All Tag Groups

Issue 1: `=== DATA API ===` section in overview output `[MINOR]`

Issue 2: `arch context` identity count and pattern list `[CONTENT]`

Issue 3: Part 7 pattern count is wrong `[CONTENT]`

Issue 4: Stubs output shows 3 entries, not 1 `[CONTENT]`

Issue 5: `list --status roadmap` output not shown `[MINOR]`

Issue 6: `docs:all` output format differs from tutorial `[MINOR]`

Issue 7: `docs:list` generator list is incomplete `[MINOR]`

Issue 8: `PATTERNS.md` categories include “DDD” `[CONTENT]`